The Very High Level Layer

The Very High Level Layer¶
The functions in this chapter will let you execute Python source code given in a file or a buffer, but they will not let you interact in a more detailed way with the interpreter.
Several of these functions accept a start symbol from the grammar as a
parameter. The available start symbols are Py_eval_input
,
Py_file_input
, Py_single_input
, and
Py_func_type_input
. These are described following the functions
which accept them as parameters.
Note also that several of these functions take FILE* parameters. One
particular issue which needs to be handled carefully is that the FILE
structure for different C libraries can be different and incompatible. Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that FILE* parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.
-
int PyRun_AnyFile(FILE *fp, const char *filename)¶
This is a simplified interface to
PyRun_AnyFileExFlags()
below, leaving closeit set to0
and flags set toNULL
.
-
int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
This is a simplified interface to
PyRun_AnyFileExFlags()
below, leaving the closeit argument set to0
.
-
int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)¶
This is a simplified interface to
PyRun_AnyFileExFlags()
below, leaving the flags argument set toNULL
.
-
int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)¶
If fp refers to a file associated with an interactive device (console or terminal input or Unix pseudo-terminal), return the value of
PyRun_InteractiveLoop()
, otherwise return the result ofPyRun_SimpleFile()
. filename is decoded from the filesystem encoding (sys.getfilesystemencoding()
). If filename isNULL
, this function uses"???"
as the filename. If closeit is true, the file is closed beforePyRun_SimpleFileExFlags()
returns.
-
int PyRun_SimpleString(const char *command)¶
This is a simplified interface to
PyRun_SimpleStringFlags()
below, leaving thePyCompilerFlags
* argument set toNULL
.
-
int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)¶
Executes the Python source code from command in the
__main__
module according to the flags argument. If__main__
does not already exist, it is created. Returns0
on success or-1
if an exception was raised. If there was an error, there is no way to get the exception information. For the meaning of flags, see below.Note that if an otherwise unhandled
SystemExit
is raised, this function will not return-1
, but exit the process, as long asPyConfig.inspect
is zero.
-
int PyRun_SimpleFile(FILE *fp, const char *filename)¶
This is a simplified interface to
PyRun_SimpleFileExFlags()
below, leaving closeit set to0
and flags set toNULL
.
-
int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)¶
This is a simplified interface to
PyRun_SimpleFileExFlags()
below, leaving flags set toNULL
.
-
int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)¶
Similar to
PyRun_SimpleStringFlags()
, but the Python source code is read from fp instead of an in-memory string. filename should be the name of the file, it is decoded from filesystem encoding and error handler. If closeit is true, the file is closed beforePyRun_SimpleFileExFlags()
returns.Note
On Windows, fp should be opened as binary mode (e.g.
fopen(filename, "rb")
). Otherwise, Python may not handle script file with LF line ending correctly.
-
int PyRun_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)¶
Read and execute a single statement from a file associated with an interactive device according to the flags argument. The user will be prompted using
sys.ps1
andsys.ps2
. filename must be a Pythonstr
object.Returns
0
when the input was executed successfully,-1
if there was an exception, or an error code from theerrcode.h
include file distributed as part of Python if there was a parse error. (Note thaterrcode.h
is not included byPython.h
, so must be included specifically if needed.)
-
int PyRun_InteractiveOne(FILE *fp, const char *filename)¶
This is a simplified interface to
PyRun_InteractiveOneFlags()
below, leaving flags set toNULL
.
-
int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
Similar to
PyRun_InteractiveOneObject()
, but filename is a const char*, which is decoded from the filesystem encoding and error handler.
-
int PyRun_InteractiveLoop(FILE *fp, const char *filename)¶
This is a simplified interface to
PyRun_InteractiveLoopFlags()
below, leaving flags set toNULL
.
-
int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
Read and execute statements from a file associated with an interactive device until EOF is reached. The user will be prompted using
sys.ps1
andsys.ps2
. filename is decoded from the filesystem encoding and error handler. Returns0
at EOF or a negative number upon failure.
-
int (*PyOS_InputHook)(void)¶
- Part of the Stable ABI.
Can be set to point to a function with the prototype
int func(void)
. The function will be called when Python’s interpreter prompt is about to become idle and wait for user input from the terminal. The return value is ignored. Overriding this hook can be used to integrate the interpreter’s prompt with other event loops, as done inModules/_tkinter.c
in the Python source code.Changed in version 3.12: This function is only called from the main interpreter.
-
char *(*PyOS_ReadlineFunctionPointer)(FILE*, FILE*, const char*)¶
Can be set to point to a function with the prototype
char *func(FILE *stdin, FILE *stdout, char *prompt)
, overriding the default function used to read a single line of input at the interpreter’s prompt. The function is expected to output the string prompt if it’s notNULL
, and then read a line of input from the provided standard input file, returning the resulting string. For example, Thereadline
module sets this hook to provide line-editing and tab-completion features.The result must be a string allocated by
PyMem_RawMalloc()
orPyMem_RawRealloc()
, orNULL
if an error occurred.Changed in version 3.4: The result must be allocated by
PyMem_RawMalloc()
orPyMem_RawRealloc()
, instead of being allocated byPyMem_Malloc()
orPyMem_Realloc()
.Changed in version 3.12: This function is only called from the main interpreter.
-
PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)¶
- Return value: New reference.
This is a simplified interface to
PyRun_StringFlags()
below, leaving flags set toNULL
.
-
PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)¶
- Return value: New reference.
Execute Python source code from str in the context specified by the objects globals and locals with the compiler flags specified by flags. globals must be a dictionary; locals can be any object that implements the mapping protocol. The parameter start specifies the start symbol and must be one of the available start symbols.
Returns the result of executing the code as a Python object, or
NULL
if an exception was raised.
-
PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)¶
- Return value: New reference.
This is a simplified interface to
PyRun_FileExFlags()
below, leaving closeit set to0
and flags set toNULL
.
-
PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)¶
- Return value: New reference.
This is a simplified interface to
PyRun_FileExFlags()
below, leaving flags set toNULL
.
-
PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)¶
- Return value: New reference.
This is a simplified interface to
PyRun_FileExFlags()
below, leaving closeit set to0
.
-
PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)¶
- Return value: New reference.
Similar to
PyRun_StringFlags()
, but the Python source code is read from fp instead of an in-memory string. filename should be the name of the file, it is decoded from the filesystem encoding and error handler. If closeit is true, the file is closed beforePyRun_FileExFlags()
returns.
-
PyObject *Py_CompileString(const char *str, const char *filename, int start)¶
- Return value: New reference. Part of the Stable ABI.
This is a simplified interface to
Py_CompileStringFlags()
below, leaving flags set toNULL
.
-
PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)¶
- Return value: New reference.
This is a simplified interface to
Py_CompileStringExFlags()
below, with optimize set to-1
.
-
PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)¶
- Return value: New reference.
Parse and compile the Python source code in str, returning the resulting code object. The start symbol is given by start; this can be used to constrain the code which can be compiled and should be available start symbols. The filename specified by filename is used to construct the code object and may appear in tracebacks or
SyntaxError
exception messages. This returnsNULL
if the code cannot be parsed or compiled.The integer optimize specifies the optimization level of the compiler; a value of
-1
selects the optimization level of the interpreter as given by-O
options. Explicit levels are0
(no optimization;__debug__
is true),1
(asserts are removed,__debug__
is false) or2
(docstrings are removed too).Added in version 3.4.
-
PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)¶
- Return value: New reference.
Like
Py_CompileStringObject()
, but filename is a byte string decoded from the filesystem encoding and error handler.Added in version 3.2.
-
PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)¶
- Return value: New reference. Part of the Stable ABI.
This is a simplified interface to
PyEval_EvalCodeEx()
, with just the code object, and global and local variables. The other arguments are set toNULL
.
-
PyObject *PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)¶
- Return value: New reference. Part of the Stable ABI.
Evaluate a precompiled code object, given a particular environment for its evaluation. This environment consists of a dictionary of global variables, a mapping object of local variables, arrays of arguments, keywords and defaults, a dictionary of default values for keyword-only arguments and a closure tuple of cells.
-
PyObject *PyEval_EvalFrame(PyFrameObject *f)¶
- Return value: New reference. Part of the Stable ABI.
Evaluate an execution frame. This is a simplified interface to
PyEval_EvalFrameEx()
, for backward compatibility.
-
PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)¶
- Return value: New reference. Part of the Stable ABI.
This is the main, unvarnished function of Python interpretation. The code object associated with the execution frame f is executed, interpreting bytecode and executing calls as needed. The additional throwflag parameter can mostly be ignored - if true, then it causes an exception to immediately be thrown; this is used for the
throw()
methods of generator objects.Changed in version 3.4: This function now includes a debug assertion to help ensure that it does not silently discard an active exception.
-
int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)¶
This function changes the flags of the current evaluation frame, and returns true on success, false on failure.
-
struct PyCompilerFlags¶
This is the structure used to hold compiler flags. In cases where code is only being compiled, it is passed as
int flags
, and in cases where code is being executed, it is passed asPyCompilerFlags *flags
. In this case,from __future__ import
can modify flags.Whenever
PyCompilerFlags *flags
isNULL
,cf_flags
is treated as equal to0
, and any modification due tofrom __future__ import
is discarded.-
int cf_flags¶
Compiler flags.
-
int cf_feature_version¶
cf_feature_version is the minor Python version. It should be initialized to
PY_MINOR_VERSION
.The field is ignored by default, it is used if and only if
PyCF_ONLY_AST
flag is set incf_flags
.
Changed in version 3.8: Added cf_feature_version field.
The available compiler flags are accessible as macros:
-
PyCF_ALLOW_TOP_LEVEL_AWAIT¶
-
PyCF_ONLY_AST¶
-
PyCF_OPTIMIZED_AST¶
-
PyCF_TYPE_COMMENTS¶
See compiler flags in documentation of the
ast
Python module, which exports these constants under the same names.
The “
PyCF
” flags above can be combined with “CO_FUTURE
” flags such asCO_FUTURE_ANNOTATIONS
to enable features normally selectable using future statements. See Code Object Flags for a complete list.-
int cf_flags¶
Available start symbols¶
-
int Py_eval_input¶
The start symbol from the Python grammar for isolated expressions; for use with
Py_CompileString()
.
-
int Py_file_input¶
The start symbol from the Python grammar for sequences of statements as read from a file or other source; for use with
Py_CompileString()
. This is the symbol to use when compiling arbitrarily long Python source code.
-
int Py_single_input¶
The start symbol from the Python grammar for a single statement; for use with
Py_CompileString()
. This is the symbol used for the interactive interpreter loop.
-
int Py_func_type_input¶
The start symbol from the Python grammar for a function type; for use with
Py_CompileString()
. This is used to parse “signature type comments” from PEP 484.This requires the
PyCF_ONLY_AST
flag to be set.See also
Added in version 3.8.
Stack Effects¶
See also
-
PY_INVALID_STACK_EFFECT¶
Sentinel value representing an invalid stack effect.
This is currently equivalent to
INT_MAX
.Added in version 3.8.
-
int PyCompile_OpcodeStackEffect(int opcode, int oparg)¶
Compute the stack effect of opcode with argument oparg.
On success, this function returns the stack effect; on failure, this returns
PY_INVALID_STACK_EFFECT
.Added in version 3.4.
-
int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)¶
Similar to
PyCompile_OpcodeStackEffect()
, but don’t include the stack effect of jumping if jump is zero.If jump is
0
, this will not include the stack effect of jumping, but if jump is1
or-1
, this will include it.On success, this function returns the stack effect; on failure, this returns
PY_INVALID_STACK_EFFECT
.Added in version 3.8.


Number Protocol

Number Protocol¶
-
int PyNumber_Check(PyObject *o)¶
- Part of the Stable ABI.
Returns
1
if the object o provides numeric protocols, and false otherwise. This function always succeeds.Changed in version 3.8: Returns
1
if o is an index integer.
-
PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of adding o1 and o2, or
NULL
on failure. This is the equivalent of the Python expressiono1 + o2
.
-
PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of subtracting o2 from o1, or
NULL
on failure. This is the equivalent of the Python expressiono1 - o2
.
-
PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of multiplying o1 and o2, or
NULL
on failure. This is the equivalent of the Python expressiono1 * o2
.
-
PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI since version 3.7.
Returns the result of matrix multiplication on o1 and o2, or
NULL
on failure. This is the equivalent of the Python expressiono1 @ o2
.Added in version 3.5.
-
PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Return the floor of o1 divided by o2, or
NULL
on failure. This is the equivalent of the Python expressiono1 // o2
.
-
PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Return a reasonable approximation for the mathematical value of o1 divided by o2, or
NULL
on failure. The return value is “approximate” because binary floating-point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating-point value when passed two integers. This is the equivalent of the Python expressiono1 / o2
.
-
PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the remainder of dividing o1 by o2, or
NULL
on failure. This is the equivalent of the Python expressiono1 % o2
.
-
PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
See the built-in function
divmod()
. ReturnsNULL
on failure. This is the equivalent of the Python expressiondivmod(o1, o2)
.
-
PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)¶
- Return value: New reference. Part of the Stable ABI.
See the built-in function
pow()
. ReturnsNULL
on failure. This is the equivalent of the Python expressionpow(o1, o2, o3)
, where o3 is optional. If o3 is to be ignored, passPy_None
in its place (passingNULL
for o3 would cause an illegal memory access).
-
PyObject *PyNumber_Negative(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Returns the negation of o on success, or
NULL
on failure. This is the equivalent of the Python expression-o
.
-
PyObject *PyNumber_Positive(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Returns o on success, or
NULL
on failure. This is the equivalent of the Python expression+o
.
-
PyObject *PyNumber_Absolute(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Returns the absolute value of o, or
NULL
on failure. This is the equivalent of the Python expressionabs(o)
.
-
PyObject *PyNumber_Invert(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Returns the bitwise negation of o on success, or
NULL
on failure. This is the equivalent of the Python expression~o
.
-
PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of left shifting o1 by o2 on success, or
NULL
on failure. This is the equivalent of the Python expressiono1 << o2
.
-
PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of right shifting o1 by o2 on success, or
NULL
on failure. This is the equivalent of the Python expressiono1 >> o2
.
-
PyObject *PyNumber_And(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the “bitwise and” of o1 and o2 on success and
NULL
on failure. This is the equivalent of the Python expressiono1 & o2
.
-
PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the “bitwise exclusive or” of o1 by o2 on success, or
NULL
on failure. This is the equivalent of the Python expressiono1 ^ o2
.
-
PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the “bitwise or” of o1 and o2 on success, or
NULL
on failure. This is the equivalent of the Python expressiono1 | o2
.
-
PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of adding o1 and o2, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 += o2
.
-
PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of subtracting o2 from o1, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 -= o2
.
-
PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of multiplying o1 and o2, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 *= o2
.
-
PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI since version 3.7.
Returns the result of matrix multiplication on o1 and o2, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 @= o2
.Added in version 3.5.
-
PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the mathematical floor of dividing o1 by o2, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 //= o2
.
-
PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Return a reasonable approximation for the mathematical value of o1 divided by o2, or
NULL
on failure. The return value is “approximate” because binary floating-point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating-point value when passed two integers. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 /= o2
.
-
PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the remainder of dividing o1 by o2, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 %= o2
.
-
PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)¶
- Return value: New reference. Part of the Stable ABI.
See the built-in function
pow()
. ReturnsNULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 **= o2
when o3 isPy_None
, or an in-place variant ofpow(o1, o2, o3)
otherwise. If o3 is to be ignored, passPy_None
in its place (passingNULL
for o3 would cause an illegal memory access).
-
PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of left shifting o1 by o2 on success, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 <<= o2
.
-
PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the result of right shifting o1 by o2 on success, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 >>= o2
.
-
PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the “bitwise and” of o1 and o2 on success and
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 &= o2
.
-
PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the “bitwise exclusive or” of o1 by o2 on success, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 ^= o2
.
-
PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)¶
- Return value: New reference. Part of the Stable ABI.
Returns the “bitwise or” of o1 and o2 on success, or
NULL
on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statemento1 |= o2
.
-
PyObject *PyNumber_Long(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Returns the o converted to an integer object on success, or
NULL
on failure. This is the equivalent of the Python expressionint(o)
.
-
PyObject *PyNumber_Float(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Returns the o converted to a float object on success, or
NULL
on failure. This is the equivalent of the Python expressionfloat(o)
.
-
PyObject *PyNumber_Index(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Returns the o converted to a Python int on success or
NULL
with aTypeError
exception raised on failure.Changed in version 3.10: The result always has exact type
int
. Previously, the result could have been an instance of a subclass ofint
.
-
PyObject *PyNumber_ToBase(PyObject *n, int base)¶
- Return value: New reference. Part of the Stable ABI.
Returns the integer n converted to base base as a string. The base argument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, the returned string is prefixed with a base marker of
'0b'
,'0o'
, or'0x'
, respectively. If n is not a Python int, it is converted withPyNumber_Index()
first.
-
Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)¶
- Part of the Stable ABI.
Returns o converted to a
Py_ssize_t
value if o can be interpreted as an integer. If the call fails, an exception is raised and-1
is returned.If o can be converted to a Python int but the attempt to convert to a
Py_ssize_t
value would raise anOverflowError
, then the exc argument is the type of exception that will be raised (usuallyIndexError
orOverflowError
). If exc isNULL
, then the exception is cleared and the value is clipped toPY_SSIZE_T_MIN
for a negative integer orPY_SSIZE_T_MAX
for a positive integer.
-
int PyIndex_Check(PyObject *o)¶
- Part of the Stable ABI since version 3.8.
Returns
1
if o is an index integer (has thenb_index
slot of thetp_as_number
structure filled in), and0
otherwise. This function always succeeds.


Synchronization Primitives

Synchronization Primitives¶
Source code: Lib/asyncio/locks.py
asyncio synchronization primitives are designed to be similar to
those of the threading
module with two important caveats:
asyncio primitives are not thread-safe, therefore they should not be used for OS thread synchronization (use
threading
for that);methods of these synchronization primitives do not accept the timeout argument; use the
asyncio.wait_for()
function to perform operations with timeouts.
asyncio has the following basic synchronization primitives:
Lock¶
- class asyncio.Lock¶
Implements a mutex lock for asyncio tasks. Not thread-safe.
An asyncio lock can be used to guarantee exclusive access to a shared resource.
The preferred way to use a Lock is an
async with
statement:lock = asyncio.Lock() # ... later async with lock: # access shared state
which is equivalent to:
lock = asyncio.Lock() # ... later await lock.acquire() try: # access shared state finally: lock.release()
Changed in version 3.10: Removed the loop parameter.
- async acquire()¶
Acquire the lock.
This method waits until the lock is unlocked, sets it to locked and returns
True
.When more than one coroutine is blocked in
acquire()
waiting for the lock to be unlocked, only one coroutine eventually proceeds.Acquiring a lock is fair: the coroutine that proceeds will be the first coroutine that started waiting on the lock.
- release()¶
Release the lock.
When the lock is locked, reset it to unlocked and return.
If the lock is unlocked, a
RuntimeError
is raised.
- locked()¶
Return
True
if the lock is locked.
Event¶
- class asyncio.Event¶
An event object. Not thread-safe.
An asyncio event can be used to notify multiple asyncio tasks that some event has happened.
An Event object manages an internal flag that can be set to true with the
set()
method and reset to false with theclear()
method. Thewait()
method blocks until the flag is set to true. The flag is set to false initially.Changed in version 3.10: Removed the loop parameter.
Example:
async def waiter(event): print('waiting for it ...') await event.wait() print('... got it!') async def main(): # Create an Event object. event = asyncio.Event() # Spawn a Task to wait until 'event' is set. waiter_task = asyncio.create_task(waiter(event)) # Sleep for 1 second and set the event. await asyncio.sleep(1) event.set() # Wait until the waiter task is finished. await waiter_task asyncio.run(main())
- async wait()¶
Wait until the event is set.
If the event is set, return
True
immediately. Otherwise block until another task callsset()
.
- set()¶
Set the event.
All tasks waiting for event to be set will be immediately awakened.
- clear()¶
Clear (unset) the event.
Subsequent tasks awaiting on
wait()
will now block until theset()
method is called again.
- is_set()¶
Return
True
if the event is set.
Condition¶
- class asyncio.Condition(lock=None)¶
A Condition object. Not thread-safe.
An asyncio condition primitive can be used by a task to wait for some event to happen and then get exclusive access to a shared resource.
In essence, a Condition object combines the functionality of an
Event
and aLock
. It is possible to have multiple Condition objects share one Lock, which allows coordinating exclusive access to a shared resource between different tasks interested in particular states of that shared resource.The optional lock argument must be a
Lock
object orNone
. In the latter case a new Lock object is created automatically.Changed in version 3.10: Removed the loop parameter.
The preferred way to use a Condition is an
async with
statement:cond = asyncio.Condition() # ... later async with cond: await cond.wait()
which is equivalent to:
cond = asyncio.Condition() # ... later await cond.acquire() try: await cond.wait() finally: cond.release()
- async acquire()¶
Acquire the underlying lock.
This method waits until the underlying lock is unlocked, sets it to locked and returns
True
.
- notify(n=1)¶
Wake up n tasks (1 by default) waiting on this condition. If fewer than n tasks are waiting they are all awakened.
The lock must be acquired before this method is called and released shortly after. If called with an unlocked lock a
RuntimeError
error is raised.
- locked()¶
Return
True
if the underlying lock is acquired.
- notify_all()¶
Wake up all tasks waiting on this condition.
This method acts like
notify()
, but wakes up all waiting tasks.The lock must be acquired before this method is called and released shortly after. If called with an unlocked lock a
RuntimeError
error is raised.
- release()¶
Release the underlying lock.
When invoked on an unlocked lock, a
RuntimeError
is raised.
- async wait()¶
Wait until notified.
If the calling task has not acquired the lock when this method is called, a
RuntimeError
is raised.This method releases the underlying lock, and then blocks until it is awakened by a
notify()
ornotify_all()
call. Once awakened, the Condition re-acquires its lock and this method returnsTrue
.Note that a task may return from this call spuriously, which is why the caller should always re-check the state and be prepared to
wait()
again. For this reason, you may prefer to usewait_for()
instead.
Semaphore¶
- class asyncio.Semaphore(value=1)¶
A Semaphore object. Not thread-safe.
A semaphore manages an internal counter which is decremented by each
acquire()
call and incremented by eachrelease()
call. The counter can never go below zero; whenacquire()
finds that it is zero, it blocks, waiting until some task callsrelease()
.The optional value argument gives the initial value for the internal counter (
1
by default). If the given value is less than0
aValueError
is raised.Changed in version 3.10: Removed the loop parameter.
The preferred way to use a Semaphore is an
async with
statement:sem = asyncio.Semaphore(10) # ... later async with sem: # work with shared resource
which is equivalent to:
sem = asyncio.Semaphore(10) # ... later await sem.acquire() try: # work with shared resource finally: sem.release()
- async acquire()¶
Acquire a semaphore.
If the internal counter is greater than zero, decrement it by one and return
True
immediately. If it is zero, wait until arelease()
is called and returnTrue
.
- locked()¶
Returns
True
if semaphore can not be acquired immediately.
- release()¶
Release a semaphore, incrementing the internal counter by one. Can wake up a task waiting to acquire the semaphore.
Unlike
BoundedSemaphore
,Semaphore
allows making morerelease()
calls thanacquire()
calls.
BoundedSemaphore¶
- class asyncio.BoundedSemaphore(value=1)¶
A bounded semaphore object. Not thread-safe.
Bounded Semaphore is a version of
Semaphore
that raises aValueError
inrelease()
if it increases the internal counter above the initial value.Changed in version 3.10: Removed the loop parameter.
Barrier¶
- class asyncio.Barrier(parties)¶
A barrier object. Not thread-safe.
A barrier is a simple synchronization primitive that allows to block until parties number of tasks are waiting on it. Tasks can wait on the
wait()
method and would be blocked until the specified number of tasks end up waiting onwait()
. At that point all of the waiting tasks would unblock simultaneously.async with
can be used as an alternative to awaiting onwait()
.The barrier can be reused any number of times.
Example:
async def example_barrier(): # barrier with 3 parties b = asyncio.Barrier(3) # create 2 new waiting tasks asyncio.create_task(b.wait()) asyncio.create_task(b.wait()) await asyncio.sleep(0) print(b) # The third .wait() call passes the barrier await b.wait() print(b) print("barrier passed") await asyncio.sleep(0) print(b) asyncio.run(example_barrier())
Result of this example is:
<asyncio.locks.Barrier object at 0x... [filling, waiters:2/3]> <asyncio.locks.Barrier object at 0x... [draining, waiters:0/3]> barrier passed <asyncio.locks.Barrier object at 0x... [filling, waiters:0/3]>
Added in version 3.11.
- async wait()¶
Pass the barrier. When all the tasks party to the barrier have called this function, they are all unblocked simultaneously.
When a waiting or blocked task in the barrier is cancelled, this task exits the barrier which stays in the same state. If the state of the barrier is “filling”, the number of waiting task decreases by 1.
The return value is an integer in the range of 0 to
parties-1
, different for each task. This can be used to select a task to do some special housekeeping, e.g.:... async with barrier as position: if position == 0: # Only one task prints this print('End of *draining phase*')
This method may raise a
BrokenBarrierError
exception if the barrier is broken or reset while a task is waiting. It could raise aCancelledError
if a task is cancelled.
- async reset()¶
Return the barrier to the default, empty state. Any tasks waiting on it will receive the
BrokenBarrierError
exception.If a barrier is broken it may be better to just leave it and create a new one.
- async abort()¶
Put the barrier into a broken state. This causes any active or future calls to
wait()
to fail with theBrokenBarrierError
. Use this for example if one of the tasks needs to abort, to avoid infinite waiting tasks.
- parties¶
The number of tasks required to pass the barrier.
- n_waiting¶
The number of tasks currently waiting in the barrier while filling.
- broken¶
A boolean that is
True
if the barrier is in the broken state.
- exception asyncio.BrokenBarrierError¶
This exception, a subclass of
RuntimeError
, is raised when theBarrier
object is reset or broken.
Changed in version 3.9: Acquiring a lock using await lock
or yield from lock
and/or
with
statement (with await lock
, with (yield from
lock)
) was removed. Use async with lock
instead.


email.message.Message
: Representing an email message using the compat32
API¶
The Message
class is very similar to the
EmailMessage
class, without the methods added by that
class, and with the default behavior of certain other methods being slightly
different. We also document here some methods that, while supported by the
EmailMessage
class, are not recommended unless you are
dealing with legacy code.
The philosophy and structure of the two classes is otherwise the same.
This document describes the behavior under the default (for Message
)
policy Compat32
. If you are going to use another policy,
you should be using the EmailMessage
class instead.
An email message consists of headers and a payload. Headers must be RFC 5322 style names and values, where the field name and value are separated by a colon. The colon is not part of either the field name or the field value. The payload may be a simple text message, or a binary object, or a structured sequence of sub-messages each with their own set of headers and their own payload. The latter type of payload is indicated by the message having a MIME type such as multipart/* or message/rfc822.
The conceptual model provided by a Message
object is that of an
ordered dictionary of headers with additional methods for accessing both
specialized information from the headers, for accessing the payload, for
generating a serialized version of the message, and for recursively walking
over the object tree. Note that duplicate headers are supported but special
methods must be used to access them.
The Message
pseudo-dictionary is indexed by the header names, which
must be ASCII values. The values of the dictionary are strings that are
supposed to contain only ASCII characters; there is some special handling for
non-ASCII input, but it doesn’t always produce the correct results. Headers
are stored and returned in case-preserving form, but field names are matched
case-insensitively. There may also be a single envelope header, also known as
the Unix-From header or the From_
header. The payload is either a
string or bytes, in the case of simple message objects, or a list of
Message
objects, for MIME container documents (e.g.
multipart/* and message/rfc822).
Here are the methods of the Message
class:
- class email.message.Message(policy=compat32)¶
If policy is specified (it must be an instance of a
policy
class) use the rules it specifies to update and serialize the representation of the message. If policy is not set, use thecompat32
policy, which maintains backward compatibility with the Python 3.2 version of the email package. For more information see thepolicy
documentation.Changed in version 3.3: The policy keyword argument was added.
- as_string(unixfrom=False, maxheaderlen=0, policy=None)¶
Return the entire message flattened as a string. When optional unixfrom is true, the envelope header is included in the returned string. unixfrom defaults to
False
. For backward compatibility reasons, maxheaderlen defaults to0
, so if you want a different value you must override it explicitly (the value specified for max_line_length in the policy will be ignored by this method). The policy argument may be used to override the default policy obtained from the message instance. This can be used to control some of the formatting produced by the method, since the specified policy will be passed to theGenerator
.Flattening the message may trigger changes to the
Message
if defaults need to be filled in to complete the transformation to a string (for example, MIME boundaries may be generated or modified).Note that this method is provided as a convenience and may not always format the message the way you want. For example, by default it does not do the mangling of lines that begin with
From
that is required by the Unix mbox format. For more flexibility, instantiate aGenerator
instance and use itsflatten()
method directly. For example:from io import StringIO from email.generator import Generator fp = StringIO() g = Generator(fp, mangle_from_=True, maxheaderlen=60) g.flatten(msg) text = fp.getvalue()
If the message object contains binary data that is not encoded according to RFC standards, the non-compliant data will be replaced by unicode “unknown character” code points. (See also
as_bytes()
andBytesGenerator
.)Changed in version 3.4: the policy keyword argument was added.
- __str__()¶
Equivalent to
as_string()
. Allowsstr(msg)
to produce a string containing the formatted message.
- as_bytes(unixfrom=False, policy=None)¶
Return the entire message flattened as a bytes object. When optional unixfrom is true, the envelope header is included in the returned string. unixfrom defaults to
False
. The policy argument may be used to override the default policy obtained from the message instance. This can be used to control some of the formatting produced by the method, since the specified policy will be passed to theBytesGenerator
.Flattening the message may trigger changes to the
Message
if defaults need to be filled in to complete the transformation to a string (for example, MIME boundaries may be generated or modified).Note that this method is provided as a convenience and may not always format the message the way you want. For example, by default it does not do the mangling of lines that begin with
From
that is required by the Unix mbox format. For more flexibility, instantiate aBytesGenerator
instance and use itsflatten()
method directly. For example:from io import BytesIO from email.generator import BytesGenerator fp = BytesIO() g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60) g.flatten(msg) text = fp.getvalue()
Added in version 3.4.
- __bytes__()¶
Equivalent to
as_bytes()
. Allowsbytes(msg)
to produce a bytes object containing the formatted message.Added in version 3.4.
- is_multipart()¶
Return
True
if the message’s payload is a list of sub-Message
objects, otherwise returnFalse
. Whenis_multipart()
returnsFalse
, the payload should be a string object (which might be a CTE encoded binary payload). (Note thatis_multipart()
returningTrue
does not necessarily mean that “msg.get_content_maintype() == ‘multipart’” will return theTrue
. For example,is_multipart
will returnTrue
when theMessage
is of typemessage/rfc822
.)
- set_unixfrom(unixfrom)¶
Set the message’s envelope header to unixfrom, which should be a string.
- get_unixfrom()¶
Return the message’s envelope header. Defaults to
None
if the envelope header was never set.
- attach(payload)¶
Add the given payload to the current payload, which must be
None
or a list ofMessage
objects before the call. After the call, the payload will always be a list ofMessage
objects. If you want to set the payload to a scalar object (e.g. a string), useset_payload()
instead.This is a legacy method. On the
EmailMessage
class its functionality is replaced byset_content()
and the relatedmake
andadd
methods.
- get_payload(i=None, decode=False)¶
Return the current payload, which will be a list of
Message
objects whenis_multipart()
isTrue
, or a string whenis_multipart()
isFalse
. If the payload is a list and you mutate the list object, you modify the message’s payload in place.With optional argument i,
get_payload()
will return the i-th element of the payload, counting from zero, ifis_multipart()
isTrue
. AnIndexError
will be raised if i is less than 0 or greater than or equal to the number of items in the payload. If the payload is a string (i.e.is_multipart()
isFalse
) and i is given, aTypeError
is raised.Optional decode is a flag indicating whether the payload should be decoded or not, according to the Content-Transfer-Encoding header. When
True
and the message is not a multipart, the payload will be decoded if this header’s value isquoted-printable
orbase64
. If some other encoding is used, or Content-Transfer-Encoding header is missing, the payload is returned as-is (undecoded). In all cases the returned value is binary data. If the message is a multipart and the decode flag isTrue
, thenNone
is returned. If the payload is base64 and it was not perfectly formed (missing padding, characters outside the base64 alphabet), then an appropriate defect will be added to the message’s defect property (InvalidBase64PaddingDefect
orInvalidBase64CharactersDefect
, respectively).When decode is
False
(the default) the body is returned as a string without decoding the Content-Transfer-Encoding. However, for a Content-Transfer-Encoding of 8bit, an attempt is made to decode the original bytes using thecharset
specified by the Content-Type header, using thereplace
error handler. If nocharset
is specified, or if thecharset
given is not recognized by the email package, the body is decoded using the default ASCII charset.This is a legacy method. On the
EmailMessage
class its functionality is replaced byget_content()
anditer_parts()
.
- set_payload(payload, charset=None)¶
Set the entire message object’s payload to payload. It is the client’s responsibility to ensure the payload invariants. Optional charset sets the message’s default character set; see
set_charset()
for details.This is a legacy method. On the
EmailMessage
class its functionality is replaced byset_content()
.
- set_charset(charset)¶
Set the character set of the payload to charset, which can either be a
Charset
instance (seeemail.charset
), a string naming a character set, orNone
. If it is a string, it will be converted to aCharset
instance. If charset isNone
, thecharset
parameter will be removed from the Content-Type header (the message will not be otherwise modified). Anything else will generate aTypeError
.If there is no existing MIME-Version header one will be added. If there is no existing Content-Type header, one will be added with a value of text/plain. Whether the Content-Type header already exists or not, its
charset
parameter will be set to charset.output_charset. If charset.input_charset and charset.output_charset differ, the payload will be re-encoded to the output_charset. If there is no existing Content-Transfer-Encoding header, then the payload will be transfer-encoded, if needed, using the specifiedCharset
, and a header with the appropriate value will be added. If a Content-Transfer-Encoding header already exists, the payload is assumed to already be correctly encoded using that Content-Transfer-Encoding and is not modified.This is a legacy method. On the
EmailMessage
class its functionality is replaced by the charset parameter of theemail.message.EmailMessage.set_content()
method.
- get_charset()¶
Return the
Charset
instance associated with the message’s payload.This is a legacy method. On the
EmailMessage
class it always returnsNone
.
The following methods implement a mapping-like interface for accessing the message’s RFC 2822 headers. Note that there are some semantic differences between these methods and a normal mapping (i.e. dictionary) interface. For example, in a dictionary there are no duplicate keys, but here there may be duplicate message headers. Also, in dictionaries there is no guaranteed order to the keys returned by
keys()
, but in aMessage
object, headers are always returned in the order they appeared in the original message, or were added to the message later. Any header deleted and then re-added are always appended to the end of the header list.These semantic differences are intentional and are biased toward maximal convenience.
Note that in all cases, any envelope header present in the message is not included in the mapping interface.
In a model generated from bytes, any header values that (in contravention of the RFCs) contain non-ASCII bytes will, when retrieved through this interface, be represented as
Header
objects with a charset ofunknown-8bit
.- __len__()¶
Return the total number of headers, including duplicates.
- __contains__(name)¶
Return
True
if the message object has a field named name. Matching is done case-insensitively and name should not include the trailing colon. Used for thein
operator, e.g.:if 'message-id' in myMessage: print('Message-ID:', myMessage['message-id'])
- __getitem__(name)¶
Return the value of the named header field. name should not include the colon field separator. If the header is missing,
None
is returned; aKeyError
is never raised.Note that if the named field appears more than once in the message’s headers, exactly which of those field values will be returned is undefined. Use the
get_all()
method to get the values of all the extant named headers.
- __setitem__(name, val)¶
Add a header to the message with field name name and value val. The field is appended to the end of the message’s existing fields.
Note that this does not overwrite or delete any existing header with the same name. If you want to ensure that the new header is the only one present in the message with field name name, delete the field first, e.g.:
del msg['subject'] msg['subject'] = 'Python roolz!'
- __delitem__(name)¶
Delete all occurrences of the field with name name from the message’s headers. No exception is raised if the named field isn’t present in the headers.
- keys()¶
Return a list of all the message’s header field names.
- values()¶
Return a list of all the message’s field values.
- items()¶
Return a list of 2-tuples containing all the message’s field headers and values.
- get(name, failobj=None)¶
Return the value of the named header field. This is identical to
__getitem__()
except that optional failobj is returned if the named header is missing (defaults toNone
).
Here are some additional useful methods:
- get_all(name, failobj=None)¶
Return a list of all the values for the field named name. If there are no such named headers in the message, failobj is returned (defaults to
None
).
- add_header(_name, _value, **_params)¶
Extended header setting. This method is similar to
__setitem__()
except that additional header parameters can be provided as keyword arguments. _name is the header field to add and _value is the primary value for the header.For each item in the keyword argument dictionary _params, the key is taken as the parameter name, with underscores converted to dashes (since dashes are illegal in Python identifiers). Normally, the parameter will be added as
key="value"
unless the value isNone
, in which case only the key will be added. If the value contains non-ASCII characters, it can be specified as a three tuple in the format(CHARSET, LANGUAGE, VALUE)
, whereCHARSET
is a string naming the charset to be used to encode the value,LANGUAGE
can usually be set toNone
or the empty string (see RFC 2231 for other possibilities), andVALUE
is the string value containing non-ASCII code points. If a three tuple is not passed and the value contains non-ASCII characters, it is automatically encoded in RFC 2231 format using aCHARSET
ofutf-8
and aLANGUAGE
ofNone
.Here’s an example:
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
This will add a header that looks like
Content-Disposition: attachment; filename="bud.gif"
An example with non-ASCII characters:
msg.add_header('Content-Disposition', 'attachment', filename=('iso-8859-1', '', 'Fußballer.ppt'))
Which produces
Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
- replace_header(_name, _value)¶
Replace a header. Replace the first header found in the message that matches _name, retaining header order and field name case. If no matching header was found, a
KeyError
is raised.
- get_content_type()¶
Return the message’s content type. The returned string is coerced to lower case of the form maintype/subtype. If there was no Content-Type header in the message the default type as given by
get_default_type()
will be returned. Since according to RFC 2045, messages always have a default type,get_content_type()
will always return a value.RFC 2045 defines a message’s default type to be text/plain unless it appears inside a multipart/digest container, in which case it would be message/rfc822. If the Content-Type header has an invalid type specification, RFC 2045 mandates that the default type be text/plain.
- get_content_maintype()¶
Return the message’s main content type. This is the maintype part of the string returned by
get_content_type()
.
- get_content_subtype()¶
Return the message’s sub-content type. This is the subtype part of the string returned by
get_content_type()
.
- get_default_type()¶
Return the default content type. Most messages have a default content type of text/plain, except for messages that are subparts of multipart/digest containers. Such subparts have a default content type of message/rfc822.
- set_default_type(ctype)¶
Set the default content type. ctype should either be text/plain or message/rfc822, although this is not enforced. The default content type is not stored in the Content-Type header.
- get_params(failobj=None, header='content-type', unquote=True)¶
Return the message’s Content-Type parameters, as a list. The elements of the returned list are 2-tuples of key/value pairs, as split on the
'='
sign. The left hand side of the'='
is the key, while the right hand side is the value. If there is no'='
sign in the parameter the value is the empty string, otherwise the value is as described inget_param()
and is unquoted if optional unquote isTrue
(the default).Optional failobj is the object to return if there is no Content-Type header. Optional header is the header to search instead of Content-Type.
This is a legacy method. On the
EmailMessage
class its functionality is replaced by the params property of the individual header objects returned by the header access methods.
- get_param(param, failobj=None, header='content-type', unquote=True)¶
Return the value of the Content-Type header’s parameter param as a string. If the message has no Content-Type header or if there is no such parameter, then failobj is returned (defaults to
None
).Optional header if given, specifies the message header to use instead of Content-Type.
Parameter keys are always compared case insensitively. The return value can either be a string, or a 3-tuple if the parameter was RFC 2231 encoded. When it’s a 3-tuple, the elements of the value are of the form
(CHARSET, LANGUAGE, VALUE)
. Note that bothCHARSET
andLANGUAGE
can beNone
, in which case you should considerVALUE
to be encoded in theus-ascii
charset. You can usually ignoreLANGUAGE
.If your application doesn’t care whether the parameter was encoded as in RFC 2231, you can collapse the parameter value by calling
email.utils.collapse_rfc2231_value()
, passing in the return value fromget_param()
. This will return a suitably decoded Unicode string when the value is a tuple, or the original string unquoted if it isn’t. For example:rawparam = msg.get_param('foo') param = email.utils.collapse_rfc2231_value(rawparam)
In any case, the parameter value (either the returned string, or the
VALUE
item in the 3-tuple) is always unquoted, unless unquote is set toFalse
.This is a legacy method. On the
EmailMessage
class its functionality is replaced by the params property of the individual header objects returned by the header access methods.
- set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)¶
Set a parameter in the Content-Type header. If the parameter already exists in the header, its value will be replaced with value. If the Content-Type header as not yet been defined for this message, it will be set to text/plain and the new parameter value will be appended as per RFC 2045.
Optional header specifies an alternative header to Content-Type, and all parameters will be quoted as necessary unless optional requote is
False
(the default isTrue
).If optional charset is specified, the parameter will be encoded according to RFC 2231. Optional language specifies the RFC 2231 language, defaulting to the empty string. Both charset and language should be strings.
If replace is
False
(the default) the header is moved to the end of the list of headers. If replace isTrue
, the header will be updated in place.Changed in version 3.4:
replace
keyword was added.
- del_param(param, header='content-type', requote=True)¶
Remove the given parameter completely from the Content-Type header. The header will be re-written in place without the parameter or its value. All values will be quoted as necessary unless requote is
False
(the default isTrue
). Optional header specifies an alternative to Content-Type.
- set_type(type, header='Content-Type', requote=True)¶
Set the main type and subtype for the Content-Type header. type must be a string in the form maintype/subtype, otherwise a
ValueError
is raised.This method replaces the Content-Type header, keeping all the parameters in place. If requote is
False
, this leaves the existing header’s quoting as is, otherwise the parameters will be quoted (the default).An alternative header can be specified in the header argument. When the Content-Type header is set a MIME-Version header is also added.
This is a legacy method. On the
EmailMessage
class its functionality is replaced by themake_
andadd_
methods.
- get_filename(failobj=None)¶
Return the value of the
filename
parameter of the Content-Disposition header of the message. If the header does not have afilename
parameter, this method falls back to looking for thename
parameter on the Content-Type header. If neither is found, or the header is missing, then failobj is returned. The returned string will always be unquoted as peremail.utils.unquote()
.
- get_boundary(failobj=None)¶
Return the value of the
boundary
parameter of the Content-Type header of the message, or failobj if either the header is missing, or has noboundary
parameter. The returned string will always be unquoted as peremail.utils.unquote()
.
- set_boundary(boundary)¶
Set the
boundary
parameter of the Content-Type header to boundary.set_boundary()
will always quote boundary if necessary. AHeaderParseError
is raised if the message object has no Content-Type header.Note that using this method is subtly different than deleting the old Content-Type header and adding a new one with the new boundary via
add_header()
, becauseset_boundary()
preserves the order of the Content-Type header in the list of headers. However, it does not preserve any continuation lines which may have been present in the original Content-Type header.
- get_content_charset(failobj=None)¶
Return the
charset
parameter of the Content-Type header, coerced to lower case. If there is no Content-Type header, or if that header has nocharset
parameter, failobj is returned.Note that this method differs from
get_charset()
which returns theCharset
instance for the default encoding of the message body.
- get_charsets(failobj=None)¶
Return a list containing the character set names in the message. If the message is a multipart, then the list will contain one element for each subpart in the payload, otherwise, it will be a list of length 1.
Each item in the list will be a string which is the value of the
charset
parameter in the Content-Type header for the represented subpart. However, if the subpart has no Content-Type header, nocharset
parameter, or is not of the text main MIME type, then that item in the returned list will be failobj.
- get_content_disposition()¶
Return the lowercased value (without parameters) of the message’s Content-Disposition header if it has one, or
None
. The possible values for this method are inline, attachment orNone
if the message follows RFC 2183.Added in version 3.5.
- walk()¶
The
walk()
method is an all-purpose generator which can be used to iterate over all the parts and subparts of a message object tree, in depth-first traversal order. You will typically usewalk()
as the iterator in afor
loop; each iteration returns the next subpart.Here’s an example that prints the MIME type of every part of a multipart message structure:
>>> for part in msg.walk(): ... print(part.get_content_type()) multipart/report text/plain message/delivery-status text/plain text/plain message/rfc822 text/plain
walk
iterates over the subparts of any part whereis_multipart()
returnsTrue
, even thoughmsg.get_content_maintype() == 'multipart'
may returnFalse
. We can see this in our example by making use of the_structure
debug helper function:>>> for part in msg.walk(): ... print(part.get_content_maintype() == 'multipart', ... part.is_multipart()) True True False False False True False False False False False True False False >>> _structure(msg) multipart/report text/plain message/delivery-status text/plain text/plain message/rfc822 text/plain
Here the
message
parts are notmultiparts
, but they do contain subparts.is_multipart()
returnsTrue
andwalk
descends into the subparts.
Message
objects can also optionally contain two instance attributes, which can be used when generating the plain text of a MIME message.- preamble¶
The format of a MIME document allows for some text between the blank line following the headers, and the first multipart boundary string. Normally, this text is never visible in a MIME-aware mail reader because it falls outside the standard MIME armor. However, when viewing the raw text of the message, or when viewing the message in a non-MIME aware reader, this text can become visible.
The preamble attribute contains this leading extra-armor text for MIME documents. When the
Parser
discovers some text after the headers but before the first boundary string, it assigns this text to the message’s preamble attribute. When theGenerator
is writing out the plain text representation of a MIME message, and it finds the message has a preamble attribute, it will write this text in the area between the headers and the first boundary. Seeemail.parser
andemail.generator
for details.Note that if the message object has no preamble, the preamble attribute will be
None
.
- epilogue¶
The epilogue attribute acts the same way as the preamble attribute, except that it contains text that appears between the last boundary and the end of the message.
You do not need to set the epilogue to the empty string in order for the
Generator
to print a newline at the end of the file.
- defects¶
The defects attribute contains a list of all the problems found when parsing this message. See
email.errors
for a detailed description of the possible parsing defects.


: Parsing email messages

email.parser
: Parsing email messages¶
Source code: Lib/email/parser.py
Message object structures can be created in one of two ways: they can be
created from whole cloth by creating an EmailMessage
object, adding headers using the dictionary interface, and adding payload(s)
using set_content()
and related methods, or
they can be created by parsing a serialized representation of the email
message.
The email
package provides a standard parser that understands most email
document structures, including MIME documents. You can pass the parser a
bytes, string or file object, and the parser will return to you the root
EmailMessage
instance of the object structure. For
simple, non-MIME messages the payload of this root object will likely be a
string containing the text of the message. For MIME messages, the root object
will return True
from its is_multipart()
method, and the subparts can be accessed via the payload manipulation methods,
such as get_body()
,
iter_parts()
, and
walk()
.
There are actually two parser interfaces available for use, the Parser
API and the incremental FeedParser
API. The Parser
API is
most useful if you have the entire text of the message in memory, or if the
entire message lives in a file on the file system. FeedParser
is more
appropriate when you are reading the message from a stream which might block
waiting for more input (such as reading an email message from a socket). The
FeedParser
can consume and parse the message incrementally, and only
returns the root object when you close the parser.
Note that the parser can be extended in limited ways, and of course you can
implement your own parser completely from scratch. All of the logic that
connects the email
package’s bundled parser and the
EmailMessage
class is embodied in the Policy
class, so a custom parser can create message object trees any way it finds
necessary by implementing custom versions of the appropriate Policy
methods.
FeedParser API¶
The BytesFeedParser
, imported from the email.feedparser
module,
provides an API that is conducive to incremental parsing of email messages,
such as would be necessary when reading the text of an email message from a
source that can block (such as a socket). The BytesFeedParser
can of
course be used to parse an email message fully contained in a bytes-like
object, string, or file, but the BytesParser
API may be more
convenient for such use cases. The semantics and results of the two parser
APIs are identical.
The BytesFeedParser
’s API is simple; you create an instance, feed it a
bunch of bytes until there’s no more to feed it, then close the parser to
retrieve the root message object. The BytesFeedParser
is extremely
accurate when parsing standards-compliant messages, and it does a very good job
of parsing non-compliant messages, providing information about how a message
was deemed broken. It will populate a message object’s
defects
attribute with a list of any
problems it found in a message. See the email.errors
module for the
list of defects that it can find.
Here is the API for the BytesFeedParser
:
- class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)¶
Create a
BytesFeedParser
instance. Optional _factory is a no-argument callable; if not specified use themessage_factory
from the policy. Call _factory whenever a new message object is needed.If policy is specified use the rules it specifies to update the representation of the message. If policy is not set, use the
compat32
policy, which maintains backward compatibility with the Python 3.2 version of the email package and providesMessage
as the default factory. All other policies provideEmailMessage
as the default _factory. For more information on what else policy controls, see thepolicy
documentation.Note: The policy keyword should always be specified; The default will change to
email.policy.default
in a future version of Python.Added in version 3.2.
Changed in version 3.3: Added the policy keyword.
Changed in version 3.6: _factory defaults to the policy
message_factory
.- feed(data)¶
Feed the parser some more data. data should be a bytes-like object containing one or more lines. The lines can be partial and the parser will stitch such partial lines together properly. The lines can have any of the three common line endings: carriage return, newline, or carriage return and newline (they can even be mixed).
- class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)¶
Works like
BytesFeedParser
except that the input to thefeed()
method must be a string. This is of limited utility, since the only way for such a message to be valid is for it to contain only ASCII text or, ifutf8
isTrue
, no binary attachments.Changed in version 3.3: Added the policy keyword.
Parser API¶
The BytesParser
class, imported from the email.parser
module,
provides an API that can be used to parse a message when the complete contents
of the message are available in a bytes-like object or file. The
email.parser
module also provides Parser
for parsing strings,
and header-only parsers, BytesHeaderParser
and
HeaderParser
, which can be used if you’re only interested in the
headers of the message. BytesHeaderParser
and HeaderParser
can be much faster in these situations, since they do not attempt to parse the
message body, instead setting the payload to the raw body.
- class email.parser.BytesParser(_class=None, *, policy=policy.compat32)¶
Create a
BytesParser
instance. The _class and policy arguments have the same meaning and semantics as the _factory and policy arguments ofBytesFeedParser
.Note: The policy keyword should always be specified; The default will change to
email.policy.default
in a future version of Python.Changed in version 3.3: Removed the strict argument that was deprecated in 2.4. Added the policy keyword.
Changed in version 3.6: _class defaults to the policy
message_factory
.- parse(fp, headersonly=False)¶
Read all the data from the binary file-like object fp, parse the resulting bytes, and return the message object. fp must support both the
readline()
and theread()
methods.The bytes contained in fp must be formatted as a block of RFC 5322 (or, if
utf8
isTrue
, RFC 6532) style headers and header continuation lines, optionally preceded by an envelope header. The header block is terminated either by the end of the data or by a blank line. Following the header block is the body of the message (which may contain MIME-encoded subparts, including subparts with a Content-Transfer-Encoding of8bit
).Optional headersonly is a flag specifying whether to stop parsing after reading the headers or not. The default is
False
, meaning it parses the entire contents of the file.
- parsebytes(bytes, headersonly=False)¶
Similar to the
parse()
method, except it takes a bytes-like object instead of a file-like object. Calling this method on a bytes-like object is equivalent to wrapping bytes in aBytesIO
instance first and callingparse()
.Optional headersonly is as with the
parse()
method.
Added in version 3.2.
- class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)¶
Exactly like
BytesParser
, except that headersonly defaults toTrue
.Added in version 3.3.
- class email.parser.Parser(_class=None, *, policy=policy.compat32)¶
This class is parallel to
BytesParser
, but handles string input.Changed in version 3.3: Removed the strict argument. Added the policy keyword.
Changed in version 3.6: _class defaults to the policy
message_factory
.- parse(fp, headersonly=False)¶
Read all the data from the text-mode file-like object fp, parse the resulting text, and return the root message object. fp must support both the
readline()
and theread()
methods on file-like objects.Other than the text mode requirement, this method operates like
BytesParser.parse()
.
- class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)¶
Exactly like
Parser
, except that headersonly defaults toTrue
.
Since creating a message object structure from a string or a file object is such
a common task, four functions are provided as a convenience. They are available
in the top-level email
package namespace.
- email.message_from_bytes(s, _class=None, *, policy=policy.compat32)¶
Return a message object structure from a bytes-like object. This is equivalent to
BytesParser().parsebytes(s)
. Optional _class and policy are interpreted as with theBytesParser
class constructor.Added in version 3.2.
Changed in version 3.3: Removed the strict argument. Added the policy keyword.
- email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)¶
Return a message object structure tree from an open binary file object. This is equivalent to
BytesParser().parse(fp)
. _class and policy are interpreted as with theBytesParser
class constructor.Added in version 3.2.
Changed in version 3.3: Removed the strict argument. Added the policy keyword.
- email.message_from_string(s, _class=None, *, policy=policy.compat32)¶
Return a message object structure from a string. This is equivalent to
Parser().parsestr(s)
. _class and policy are interpreted as with theParser
class constructor.Changed in version 3.3: Removed the strict argument. Added the policy keyword.
- email.message_from_file(fp, _class=None, *, policy=policy.compat32)¶
Return a message object structure tree from an open file object. This is equivalent to
Parser().parse(fp)
. _class and policy are interpreted as with theParser
class constructor.Changed in version 3.3: Removed the strict argument. Added the policy keyword.
Changed in version 3.6: _class defaults to the policy
message_factory
.
Here’s an example of how you might use message_from_bytes()
at an
interactive Python prompt:
>>> import email
>>> msg = email.message_from_bytes(myBytes)
Additional notes¶
Here are some notes on the parsing semantics:
Most non-multipart type messages are parsed as a single message object with a string payload. These objects will return
False
foris_multipart()
, anditer_parts()
will yield an empty list.All multipart type messages will be parsed as a container message object with a list of sub-message objects for their payload. The outer container message will return
True
foris_multipart()
, anditer_parts()
will yield a list of subparts.Most messages with a content type of message/* (such as message/delivery-status and message/rfc822) will also be parsed as container object containing a list payload of length 1. Their
is_multipart()
method will returnTrue
. The single element yielded byiter_parts()
will be a sub-message object.Some non-standards-compliant messages may not be internally consistent about their multipart-edness. Such messages may have a Content-Type header of type multipart, but their
is_multipart()
method may returnFalse
. If such messages were parsed with theFeedParser
, they will have an instance of theMultipartInvariantViolationDefect
class in their defects attribute list. Seeemail.errors
for details.