Python Initialization Configuration

Python Initialization Configuration¶
PyInitConfig C API¶
Added in version 3.14.
Python can be initialized with Py_InitializeFromInitConfig()
.
The Py_RunMain()
function can be used to write a customized Python
program.
See also Initialization, Finalization, and Threads.
See also
PEP 741 “Python Configuration C API”.
Example¶
Example of customized Python always running with the Python Development
Mode enabled; return -1
on error:
int init_python(void)
{
PyInitConfig *config = PyInitConfig_Create();
if (config == NULL) {
printf("PYTHON INIT ERROR: memory allocation failed\n");
return -1;
}
// Enable the Python Development Mode
if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
goto error;
}
// Initialize Python with the configuration
if (Py_InitializeFromInitConfig(config) < 0) {
goto error;
}
PyInitConfig_Free(config);
return 0;
error:
{
// Display the error message.
//
// This uncommon braces style is used, because you cannot make
// goto targets point to variable declarations.
const char *err_msg;
(void)PyInitConfig_GetError(config, &err_msg);
printf("PYTHON INIT ERROR: %s\n", err_msg);
PyInitConfig_Free(config);
return -1;
}
}
Create Config¶
-
struct PyInitConfig¶
Opaque structure to configure the Python initialization.
-
PyInitConfig *PyInitConfig_Create(void)¶
Create a new initialization configuration using Isolated Configuration default values.
It must be freed by
PyInitConfig_Free()
.Return
NULL
on memory allocation failure.
-
void PyInitConfig_Free(PyInitConfig *config)¶
Free memory of the initialization configuration config.
If config is
NULL
, no operation is performed.
Error Handling¶
-
int PyInitConfig_GetError(PyInitConfig *config, const char **err_msg)¶
Get the config error message.
Set *err_msg and return
1
if an error is set.Set *err_msg to
NULL
and return0
otherwise.
An error message is a UTF-8 encoded string.
If config has an exit code, format the exit code as an error message.
The error message remains valid until another
PyInitConfig
function is called with config. The caller doesn’t have to free the error message.
-
int PyInitConfig_GetExitCode(PyInitConfig *config, int *exitcode)¶
Get the config exit code.
Set *exitcode and return
1
if config has an exit code set.Return
0
if config has no exit code set.
Only the
Py_InitializeFromInitConfig()
function can set an exit code if theparse_argv
option is non-zero.An exit code can be set when parsing the command line failed (exit code
2
) or when a command line option asks to display the command line help (exit code0
).
Get Options¶
The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See Configuration Options.
-
int PyInitConfig_HasOption(PyInitConfig *config, const char *name)¶
Test if the configuration has an option called name.
Return
1
if the option exists, or return0
otherwise.
-
int PyInitConfig_GetInt(PyInitConfig *config, const char *name, int64_t *value)¶
Get an integer configuration option.
Set *value, and return
0
on success.Set an error in config and return
-1
on error.
-
int PyInitConfig_GetStr(PyInitConfig *config, const char *name, char **value)¶
Get a string configuration option as a null-terminated UTF-8 encoded string.
Set *value, and return
0
on success.Set an error in config and return
-1
on error.
*value can be set to
NULL
if the option is an optional string and the option is unset.On success, the string must be released with
free(value)
if it’s notNULL
.
-
int PyInitConfig_GetStrList(PyInitConfig *config, const char *name, size_t *length, char ***items)¶
Get a string list configuration option as an array of null-terminated UTF-8 encoded strings.
Set *length and *value, and return
0
on success.Set an error in config and return
-1
on error.
On success, the string list must be released with
PyInitConfig_FreeStrList(length, items)
.
-
void PyInitConfig_FreeStrList(size_t length, char **items)¶
Free memory of a string list created by
PyInitConfig_GetStrList()
.
Set Options¶
The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See Configuration Options.
Some configuration options have side effects on other options. This logic is
only implemented when Py_InitializeFromInitConfig()
is called, not by the
“Set” functions below. For example, setting dev_mode
to 1
does not set
faulthandler
to 1
.
-
int PyInitConfig_SetInt(PyInitConfig *config, const char *name, int64_t value)¶
Set an integer configuration option.
Return
0
on success.Set an error in config and return
-1
on error.
-
int PyInitConfig_SetStr(PyInitConfig *config, const char *name, const char *value)¶
Set a string configuration option from a null-terminated UTF-8 encoded string. The string is copied.
Return
0
on success.Set an error in config and return
-1
on error.
-
int PyInitConfig_SetStrList(PyInitConfig *config, const char *name, size_t length, char *const *items)¶
Set a string list configuration option from an array of null-terminated UTF-8 encoded strings. The string list is copied.
Return
0
on success.Set an error in config and return
-1
on error.
Module¶
-
int PyInitConfig_AddModule(PyInitConfig *config, const char *name, PyObject *(*initfunc)(void))¶
Add a built-in extension module to the table of built-in modules.
The new module can be imported by the name name, and uses the function initfunc as the initialization function called on the first attempted import.
Return
0
on success.Set an error in config and return
-1
on error.
If Python is initialized multiple times,
PyInitConfig_AddModule()
must be called at each Python initialization.Similar to the
PyImport_AppendInittab()
function.
Initialize Python¶
-
int Py_InitializeFromInitConfig(PyInitConfig *config)¶
Initialize Python from the initialization configuration.
Return
0
on success.Set an error in config and return
-1
on error.Set an exit code in config and return
-1
if Python wants to exit.
See
PyInitConfig_GetExitcode()
for the exit code case.
Configuration Options¶
Option |
PyConfig/PyPreConfig member |
Type |
Visibility |
|---|---|---|---|
|
|
Read-only |
|
|
|
Public |
|
|
|
Public |
|
|
|
Public |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Read-only |
|
|
|
Public |
|
|
|
Public |
|
|
|
Public |
|
|
|
Read-only |
Visibility:
Public: Can be retrieved by
PyConfig_Get()
and set byPyConfig_Set()
.Read-only: Can be retrieved by
PyConfig_Get()
, but cannot be set byPyConfig_Set()
.
Runtime Python configuration API¶
At runtime, it’s possible to get and set configuration options using
PyConfig_Get()
and PyConfig_Set()
functions.
The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See Configuration Options.
Some options are read from the sys
attributes. For example, the option
"argv"
is read from sys.argv
.
-
PyObject *PyConfig_Get(const char *name)¶
Get the current runtime value of a configuration option as a Python object.
Return a new reference on success.
Set an exception and return
NULL
on error.
The object type depends on the configuration option. It can be:
bool
int
str
list[str]
dict[str, str]
The caller must have an attached thread state. The function cannot be called before Python initialization nor after Python finalization.
Added in version 3.14.
-
int PyConfig_GetInt(const char *name, int *value)¶
Similar to
PyConfig_Get()
, but get the value as a C int.Return
0
on success.Set an exception and return
-1
on error.
Added in version 3.14.
-
PyObject *PyConfig_Names(void)¶
Get all configuration option names as a
frozenset
.Return a new reference on success.
Set an exception and return
NULL
on error.
The caller must have an attached thread state. The function cannot be called before Python initialization nor after Python finalization.
Added in version 3.14.
-
int PyConfig_Set(const char *name, PyObject *value)¶
Set the current runtime value of a configuration option.
Raise a
ValueError
if there is no option name.Raise a
ValueError
if value is an invalid value.Raise a
ValueError
if the option is read-only (cannot be set).Raise a
TypeError
if value has not the proper type.
The caller must have an attached thread state. The function cannot be called before Python initialization nor after Python finalization.
Raises an auditing event
cpython.PyConfig_Set
with argumentsname
,value
.Added in version 3.14.
PyConfig C API¶
Added in version 3.8.
Python can be initialized with Py_InitializeFromConfig()
and the
PyConfig
structure. It can be preinitialized with
Py_PreInitialize()
and the PyPreConfig
structure.
There are two kinds of configuration:
The Python Configuration can be used to build a customized Python which behaves as the regular Python. For example, environment variables and command line arguments are used to configure Python.
The Isolated Configuration can be used to embed Python into an application. It isolates Python from the system. For example, environment variables are ignored, the LC_CTYPE locale is left unchanged and no signal handler is registered.
The Py_RunMain()
function can be used to write a customized Python
program.
See also Initialization, Finalization, and Threads.
See also
PEP 587 “Python Initialization Configuration”.
Example¶
Example of customized Python always running in isolated mode:
int main(int argc, char **argv)
{
PyStatus status;
PyConfig config;
PyConfig_InitPythonConfig(&config);
config.isolated = 1;
/* Decode command line arguments.
Implicitly preinitialize Python (in isolated mode). */
status = PyConfig_SetBytesArgv(&config, argc, argv);
if (PyStatus_Exception(status)) {
goto exception;
}
status = Py_InitializeFromConfig(&config);
if (PyStatus_Exception(status)) {
goto exception;
}
PyConfig_Clear(&config);
return Py_RunMain();
exception:
PyConfig_Clear(&config);
if (PyStatus_IsExit(status)) {
return status.exitcode;
}
/* Display the error message and exit the process with
non-zero exit code */
Py_ExitStatusException(status);
}
PyWideStringList¶
-
type PyWideStringList¶
List of
wchar_t*
strings.If length is non-zero, items must be non-
NULL
and all strings must be non-NULL
.Methods:
-
PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)¶
Append item to list.
Python must be preinitialized to call this function.
-
PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)¶
Insert item into list at index.
If index is greater than or equal to list length, append item to list.
index must be greater than or equal to
0
.Python must be preinitialized to call this function.
Structure fields:
-
Py_ssize_t length¶
List length.
-
wchar_t **items¶
List items.
-
PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)¶
PyStatus¶
-
type PyStatus¶
Structure to store an initialization function status: success, error or exit.
For an error, it can store the C function name which created the error.
Structure fields:
-
int exitcode¶
Exit code. Argument passed to
exit()
.
-
const char *err_msg¶
Error message.
-
const char *func¶
Name of the function which created an error, can be
NULL
.
Functions to create a status:
-
PyStatus PyStatus_Error(const char *err_msg)¶
Initialization error with a message.
err_msg must not be
NULL
.
Functions to handle a status:
-
int PyStatus_Exception(PyStatus status)¶
Is the status an error or an exit? If true, the exception must be handled; by calling
Py_ExitStatusException()
for example.
-
int exitcode¶
Note
Internally, Python uses macros which set PyStatus.func
,
whereas functions to create a status set func
to NULL
.
Example:
PyStatus alloc(void **ptr, size_t size)
{
*ptr = PyMem_RawMalloc(size);
if (*ptr == NULL) {
return PyStatus_NoMemory();
}
return PyStatus_Ok();
}
int main(int argc, char **argv)
{
void *ptr;
PyStatus status = alloc(&ptr, 16);
if (PyStatus_Exception(status)) {
Py_ExitStatusException(status);
}
PyMem_Free(ptr);
return 0;
}
PyPreConfig¶
-
type PyPreConfig¶
Structure used to preinitialize Python.
Function to initialize a preconfiguration:
-
void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶
Initialize the preconfiguration with Python Configuration.
-
void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶
Initialize the preconfiguration with Isolated Configuration.
Structure fields:
-
int allocator¶
Name of the Python memory allocators:
PYMEM_ALLOCATOR_NOT_SET
(0
): don’t change memory allocators (use defaults).PYMEM_ALLOCATOR_DEFAULT
(1
): default memory allocators.PYMEM_ALLOCATOR_DEBUG
(2
): default memory allocators with debug hooks.PYMEM_ALLOCATOR_MALLOC
(3
): usemalloc()
of the C library.PYMEM_ALLOCATOR_MALLOC_DEBUG
(4
): force usage ofmalloc()
with debug hooks.PYMEM_ALLOCATOR_PYMALLOC
(5
): Python pymalloc memory allocator.PYMEM_ALLOCATOR_PYMALLOC_DEBUG
(6
): Python pymalloc memory allocator with debug hooks.PYMEM_ALLOCATOR_MIMALLOC
(6
): usemimalloc
, a fast malloc replacement.PYMEM_ALLOCATOR_MIMALLOC_DEBUG
(7
): usemimalloc
, a fast malloc replacement with debug hooks.
PYMEM_ALLOCATOR_PYMALLOC
andPYMEM_ALLOCATOR_PYMALLOC_DEBUG
are not supported if Python isconfigured using --without-pymalloc
.PYMEM_ALLOCATOR_MIMALLOC
andPYMEM_ALLOCATOR_MIMALLOC_DEBUG
are not supported if Python isconfigured using --without-mimalloc
or if the underlying atomic support isn’t available.See Memory Management.
Default:
PYMEM_ALLOCATOR_NOT_SET
.
-
int configure_locale¶
Set the LC_CTYPE locale to the user preferred locale.
If equals to
0
, setcoerce_c_locale
andcoerce_c_locale_warn
members to0
.See the locale encoding.
Default:
1
in Python config,0
in isolated config.
-
int coerce_c_locale¶
If equals to
2
, coerce the C locale.If equals to
1
, read the LC_CTYPE locale to decide if it should be coerced.See the locale encoding.
Default:
-1
in Python config,0
in isolated config.
-
int coerce_c_locale_warn¶
If non-zero, emit a warning if the C locale is coerced.
Default:
-1
in Python config,0
in isolated config.
-
int dev_mode¶
Python Development Mode: see
PyConfig.dev_mode
.Default:
-1
in Python mode,0
in isolated mode.
-
int isolated¶
Isolated mode: see
PyConfig.isolated
.Default:
0
in Python mode,1
in isolated mode.
-
int legacy_windows_fs_encoding¶
If non-zero:
Set
PyPreConfig.utf8_mode
to0
,Set
PyConfig.filesystem_encoding
to"mbcs"
,Set
PyConfig.filesystem_errors
to"replace"
.
Initialized from the
PYTHONLEGACYWINDOWSFSENCODING
environment variable value.Only available on Windows.
#ifdef MS_WINDOWS
macro can be used for Windows specific code.Default:
0
.
-
int parse_argv¶
If non-zero,
Py_PreInitializeFromArgs()
andPy_PreInitializeFromBytesArgs()
parse theirargv
argument the same way the regular Python parses command line arguments: see Command Line Arguments.Default:
1
in Python config,0
in isolated config.
-
int use_environment¶
Use environment variables? See
PyConfig.use_environment
.Default:
1
in Python config and0
in isolated config.
-
int utf8_mode¶
If non-zero, enable the Python UTF-8 Mode.
Set to
0
or1
by the-X utf8
command line option and thePYTHONUTF8
environment variable.Also set to
1
if theLC_CTYPE
locale isC
orPOSIX
.Default:
-1
in Python config and0
in isolated config.
-
void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶
Preinitialize Python with PyPreConfig¶
The preinitialization of Python:
Set the Python memory allocators (
PyPreConfig.allocator
)Configure the LC_CTYPE locale (locale encoding)
Set the Python UTF-8 Mode (
PyPreConfig.utf8_mode
)
The current preconfiguration (PyPreConfig
type) is stored in
_PyRuntime.preconfig
.
Functions to preinitialize Python:
-
PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶
Preinitialize Python from preconfig preconfiguration.
preconfig must not be
NULL
.
-
PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)¶
Preinitialize Python from preconfig preconfiguration.
Parse argv command line arguments (bytes strings) if
parse_argv
of preconfig is non-zero.preconfig must not be
NULL
.
-
PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)¶
Preinitialize Python from preconfig preconfiguration.
Parse argv command line arguments (wide strings) if
parse_argv
of preconfig is non-zero.preconfig must not be
NULL
.
The caller is responsible to handle exceptions (error or exit) using
PyStatus_Exception()
and Py_ExitStatusException()
.
For Python Configuration
(PyPreConfig_InitPythonConfig()
), if Python is initialized with
command line arguments, the command line arguments must also be passed to
preinitialize Python, since they have an effect on the pre-configuration
like encodings. For example, the -X utf8
command line option
enables the Python UTF-8 Mode.
PyMem_SetAllocator()
can be called after Py_PreInitialize()
and
before Py_InitializeFromConfig()
to install a custom memory allocator.
It can be called before Py_PreInitialize()
if
PyPreConfig.allocator
is set to PYMEM_ALLOCATOR_NOT_SET
.
Python memory allocation functions like PyMem_RawMalloc()
must not be
used before the Python preinitialization, whereas calling directly malloc()
and free()
is always safe. Py_DecodeLocale()
must not be called
before the Python preinitialization.
Example using the preinitialization to enable the Python UTF-8 Mode:
PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);
preconfig.utf8_mode = 1;
status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
Py_ExitStatusException(status);
}
/* at this point, Python speaks UTF-8 */
Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();
PyConfig¶
-
type PyConfig¶
Structure containing most parameters to configure Python.
When done, the
PyConfig_Clear()
function must be used to release the configuration memory.Structure methods:
-
void PyConfig_InitPythonConfig(PyConfig *config)¶
Initialize configuration with the Python Configuration.
-
void PyConfig_InitIsolatedConfig(PyConfig *config)¶
Initialize configuration with the Isolated Configuration.
-
PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)¶
Copy the wide character string str into
*config_str
.Preinitialize Python if needed.
-
PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)¶
Decode str using
Py_DecodeLocale()
and set the result into*config_str
.Preinitialize Python if needed.
-
PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)¶
Set command line arguments (
argv
member of config) from the argv list of wide character strings.Preinitialize Python if needed.
-
PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char *const *argv)¶
Set command line arguments (
argv
member of config) from the argv list of bytes strings. Decode bytes usingPy_DecodeLocale()
.Preinitialize Python if needed.
-
PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)¶
Set the list of wide strings list to length and items.
Preinitialize Python if needed.
-
PyStatus PyConfig_Read(PyConfig *config)¶
Read all Python configuration.
Fields which are already initialized are left unchanged.
Fields for path configuration are no longer calculated or modified when calling this function, as of Python 3.11.
The
PyConfig_Read()
function only parsesPyConfig.argv
arguments once:PyConfig.parse_argv
is set to2
after arguments are parsed. Since Python arguments are stripped fromPyConfig.argv
, parsing arguments twice would parse the application options as Python options.Preinitialize Python if needed.
Changed in version 3.10: The
PyConfig.argv
arguments are now only parsed once,PyConfig.parse_argv
is set to2
after arguments are parsed, and arguments are only parsed ifPyConfig.parse_argv
equals1
.Changed in version 3.11:
PyConfig_Read()
no longer calculates all paths, and so fields listed under Python Path Configuration may no longer be updated untilPy_InitializeFromConfig()
is called.
Most
PyConfig
methods preinitialize Python if needed. In that case, the Python preinitialization configuration (PyPreConfig
) is based on thePyConfig
. If configuration fields which are in common withPyPreConfig
are tuned, they must be set before calling aPyConfig
method:Moreover, if
PyConfig_SetArgv()
orPyConfig_SetBytesArgv()
is used, this method must be called before other methods, since the preinitialization configuration depends on command line arguments (ifparse_argv
is non-zero).The caller of these methods is responsible to handle exceptions (error or exit) using
PyStatus_Exception()
andPy_ExitStatusException()
.Structure fields:
-
PyWideStringList argv¶
Set
sys.argv
command line arguments based onargv
. These parameters are similar to those passed to the program’smain()
function with the difference that the first entry should refer to the script file to be executed rather than the executable hosting the Python interpreter. If there isn’t a script that will be run, the first entry inargv
can be an empty string.Set
parse_argv
to1
to parseargv
the same way the regular Python parses Python command line arguments and then to strip Python arguments fromargv
.If
argv
is empty, an empty string is added to ensure thatsys.argv
always exists and is never empty.Default:
NULL
.See also the
orig_argv
member.
-
int safe_path¶
If equals to zero,
Py_RunMain()
prepends a potentially unsafe path tosys.path
at startup:If
argv[0]
is equal toL"-m"
(python -m module
), prepend the current working directory.If running a script (
python script.py
), prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.Otherwise (
python -c code
andpython
), prepend an empty string, which means the current working directory.
Set to
1
by the-P
command line option and thePYTHONSAFEPATH
environment variable.Default:
0
in Python config,1
in isolated config.Added in version 3.11.
-
wchar_t *base_exec_prefix¶
-
Default:
NULL
.Part of the Python Path Configuration output.
See also
PyConfig.exec_prefix
.
-
wchar_t *base_executable¶
Python base executable:
sys._base_executable
.Set by the
__PYVENV_LAUNCHER__
environment variable.Set from
PyConfig.executable
ifNULL
.Default:
NULL
.Part of the Python Path Configuration output.
See also
PyConfig.executable
.
-
wchar_t *base_prefix¶
-
Default:
NULL
.Part of the Python Path Configuration output.
See also
PyConfig.prefix
.
-
int buffered_stdio¶
If equals to
0
andconfigure_c_stdio
is non-zero, disable buffering on the C streams stdout and stderr.Set to
0
by the-u
command line option and thePYTHONUNBUFFERED
environment variable.stdin is always opened in buffered mode.
Default:
1
.
-
int bytes_warning¶
If equals to
1
, issue a warning when comparingbytes
orbytearray
withstr
, or comparingbytes
withint
.If equal or greater to
2
, raise aBytesWarning
exception in these cases.Incremented by the
-b
command line option.Default:
0
.
-
int warn_default_encoding¶
If non-zero, emit a
EncodingWarning
warning whenio.TextIOWrapper
uses its default encoding. See Opt-in EncodingWarning for details.Default:
0
.Added in version 3.10.
-
int code_debug_ranges¶
If equals to
0
, disables the inclusion of the end line and column mappings in code objects. Also disables traceback printing carets to specific error locations.Set to
0
by thePYTHONNODEBUGRANGES
environment variable and by the-X no_debug_ranges
command line option.Default:
1
.Added in version 3.11.
-
wchar_t *check_hash_pycs_mode¶
Control the validation behavior of hash-based
.pyc
files: value of the--check-hash-based-pycs
command line option.Valid values:
L"always"
: Hash the source file for invalidation regardless of value of the ‘check_source’ flag.L"never"
: Assume that hash-based pycs always are valid.L"default"
: The ‘check_source’ flag in hash-based pycs determines invalidation.
Default:
L"default"
.See also PEP 552 “Deterministic pycs”.
-
int configure_c_stdio¶
If non-zero, configure C standard streams:
On Windows, set the binary mode (
O_BINARY
) on stdin, stdout and stderr.If
buffered_stdio
equals zero, disable buffering of stdin, stdout and stderr streams.If
interactive
is non-zero, enable stream buffering on stdin and stdout (only stdout on Windows).
Default:
1
in Python config,0
in isolated config.
-
int dev_mode¶
If non-zero, enable the Python Development Mode.
Set to
1
by the-X dev
option and thePYTHONDEVMODE
environment variable.Default:
-1
in Python mode,0
in isolated mode.
-
int dump_refs¶
Dump Python references?
If non-zero, dump all objects which are still alive at exit.
Set to
1
by thePYTHONDUMPREFS
environment variable.Needs a special build of Python with the
Py_TRACE_REFS
macro defined: see theconfigure --with-trace-refs option
.Default:
0
.
-
wchar_t *dump_refs_file¶
Filename where to dump Python references.
Set by the
PYTHONDUMPREFSFILE
environment variable.Default:
NULL
.Added in version 3.11.
-
wchar_t *exec_prefix¶
The site-specific directory prefix where the platform-dependent Python files are installed:
sys.exec_prefix
.Default:
NULL
.Part of the Python Path Configuration output.
See also
PyConfig.base_exec_prefix
.
-
wchar_t *executable¶
The absolute path of the executable binary for the Python interpreter:
sys.executable
.Default:
NULL
.Part of the Python Path Configuration output.
See also
PyConfig.base_executable
.
-
int faulthandler¶
Enable faulthandler?
If non-zero, call
faulthandler.enable()
at startup.Set to
1
by-X faulthandler
and thePYTHONFAULTHANDLER
environment variable.Default:
-1
in Python mode,0
in isolated mode.
-
wchar_t *filesystem_encoding¶
Filesystem encoding:
sys.getfilesystemencoding()
.On macOS, Android and VxWorks: use
"utf-8"
by default.On Windows: use
"utf-8"
by default, or"mbcs"
iflegacy_windows_fs_encoding
ofPyPreConfig
is non-zero.Default encoding on other platforms:
"utf-8"
ifPyPreConfig.utf8_mode
is non-zero."ascii"
if Python detects thatnl_langinfo(CODESET)
announces the ASCII encoding, whereas thembstowcs()
function decodes from a different encoding (usually Latin1)."utf-8"
ifnl_langinfo(CODESET)
returns an empty string.Otherwise, use the locale encoding:
nl_langinfo(CODESET)
result.
At Python startup, the encoding name is normalized to the Python codec name. For example,
"ANSI_X3.4-1968"
is replaced with"ascii"
.See also the
filesystem_errors
member.
-
wchar_t *filesystem_errors¶
Filesystem error handler:
sys.getfilesystemencodeerrors()
.On Windows: use
"surrogatepass"
by default, or"replace"
iflegacy_windows_fs_encoding
ofPyPreConfig
is non-zero.On other platforms: use
"surrogateescape"
by default.Supported error handlers:
"strict"
"surrogateescape"
"surrogatepass"
(only supported with the UTF-8 encoding)
See also the
filesystem_encoding
member.
-
int use_frozen_modules¶
If non-zero, use frozen modules.
Set by the
PYTHON_FROZEN_MODULES
environment variable.Default:
1
in a release build, or0
in a debug build.
-
unsigned long hash_seed¶
-
int use_hash_seed¶
Randomized hash function seed.
If
use_hash_seed
is zero, a seed is chosen randomly at Python startup, andhash_seed
is ignored.Set by the
PYTHONHASHSEED
environment variable.Default use_hash_seed value:
-1
in Python mode,0
in isolated mode.
-
wchar_t *home¶
Set the default Python “home” directory, that is, the location of the standard Python libraries (see
PYTHONHOME
).Set by the
PYTHONHOME
environment variable.Default:
NULL
.Part of the Python Path Configuration input.
-
int import_time¶
If
1
, profile import time. If2
, include additional output that indicates when an imported module has already been loaded.Set by the
-X importtime
option and thePYTHONPROFILEIMPORTTIME
environment variable.Default:
0
.Changed in version 3.14: Added support for
import_time = 2
-
int inspect¶
Enter interactive mode after executing a script or a command.
If greater than
0
, enable inspect: when a script is passed as first argument or the -c option is used, enter interactive mode after executing the script or the command, even whensys.stdin
does not appear to be a terminal.Incremented by the
-i
command line option. Set to1
if thePYTHONINSPECT
environment variable is non-empty.Default:
0
.
-
int install_signal_handlers¶
Install Python signal handlers?
Default:
1
in Python mode,0
in isolated mode.
-
int interactive¶
If greater than
0
, enable the interactive mode (REPL).Incremented by the
-i
command line option.Default:
0
.
-
int int_max_str_digits¶
Configures the integer string conversion length limitation. An initial value of
-1
means the value will be taken from the command line or environment or otherwise default to 4300 (sys.int_info.default_max_str_digits
). A value of0
disables the limitation. Values greater than zero but less than 640 (sys.int_info.str_digits_check_threshold
) are unsupported and will produce an error.Configured by the
-X int_max_str_digits
command line flag or thePYTHONINTMAXSTRDIGITS
environment variable.Default:
-1
in Python mode. 4300 (sys.int_info.default_max_str_digits
) in isolated mode.Added in version 3.12.
-
int cpu_count¶
If the value of
cpu_count
is not-1
then it will override the return values ofos.cpu_count()
,os.process_cpu_count()
, andmultiprocessing.cpu_count()
.Configured by the
-X cpu_count=n|default
command line flag or thePYTHON_CPU_COUNT
environment variable.Default:
-1
.Added in version 3.13.
-
int isolated¶
If greater than
0
, enable isolated mode:Set
safe_path
to1
: don’t prepend a potentially unsafe path tosys.path
at Python startup, such as the current directory, the script’s directory or an empty string.Set
use_environment
to0
: ignorePYTHON
environment variables.Set
user_site_directory
to0
: don’t add the user site directory tosys.path
.Python REPL doesn’t import
readline
nor enable default readline configuration on interactive prompts.
Set to
1
by the-I
command line option.Default:
0
in Python mode,1
in isolated mode.See also the Isolated Configuration and
PyPreConfig.isolated
.
-
int legacy_windows_stdio¶
If non-zero, use
io.FileIO
instead ofio._WindowsConsoleIO
forsys.stdin
,sys.stdout
andsys.stderr
.Set to
1
if thePYTHONLEGACYWINDOWSSTDIO
environment variable is set to a non-empty string.Only available on Windows.
#ifdef MS_WINDOWS
macro can be used for Windows specific code.Default:
0
.See also the PEP 528 (Change Windows console encoding to UTF-8).
-
int malloc_stats¶
If non-zero, dump statistics on Python pymalloc memory allocator at exit.
Set to
1
by thePYTHONMALLOCSTATS
environment variable.The option is ignored if Python is
configured using the --without-pymalloc option
.Default:
0
.
-
wchar_t *platlibdir¶
Platform library directory name:
sys.platlibdir
.Set by the
PYTHONPLATLIBDIR
environment variable.Default: value of the
PLATLIBDIR
macro which is set by theconfigure --with-platlibdir option
(default:"lib"
, or"DLLs"
on Windows).Part of the Python Path Configuration input.
Added in version 3.9.
Changed in version 3.11: This macro is now used on Windows to locate the standard library extension modules, typically under
DLLs
. However, for compatibility, note that this value is ignored for any non-standard layouts, including in-tree builds and virtual environments.
-
wchar_t *pythonpath_env¶
Module search paths (
sys.path
) as a string separated byDELIM
(os.pathsep
).Set by the
PYTHONPATH
environment variable.Default:
NULL
.Part of the Python Path Configuration input.
-
PyWideStringList module_search_paths¶
-
int module_search_paths_set¶
Module search paths:
sys.path
.If
module_search_paths_set
is equal to0
,Py_InitializeFromConfig()
will replacemodule_search_paths
and setsmodule_search_paths_set
to1
.Default: empty list (
module_search_paths
) and0
(module_search_paths_set
).Part of the Python Path Configuration output.
-
int optimization_level¶
Compilation optimization level:
0
: Peephole optimizer, set__debug__
toTrue
.1
: Level 0, remove assertions, set__debug__
toFalse
.2
: Level 1, strip docstrings.
Incremented by the
-O
command line option. Set to thePYTHONOPTIMIZE
environment variable value.Default:
0
.
-
PyWideStringList orig_argv¶
The list of the original command line arguments passed to the Python executable:
sys.orig_argv
.If
orig_argv
list is empty andargv
is not a list only containing an empty string,PyConfig_Read()
copiesargv
intoorig_argv
before modifyingargv
(ifparse_argv
is non-zero).See also the
argv
member and thePy_GetArgcArgv()
function.Default: empty list.
Added in version 3.10.
-
int parse_argv¶
Parse command line arguments?
If equals to
1
, parseargv
the same way the regular Python parses command line arguments, and strip Python arguments fromargv
.The
PyConfig_Read()
function only parsesPyConfig.argv
arguments once:PyConfig.parse_argv
is set to2
after arguments are parsed. Since Python arguments are stripped fromPyConfig.argv
, parsing arguments twice would parse the application options as Python options.Default:
1
in Python mode,0
in isolated mode.Changed in version 3.10: The
PyConfig.argv
arguments are now only parsed ifPyConfig.parse_argv
equals to1
.
-
int parser_debug¶
Parser debug mode. If greater than
0
, turn on parser debugging output (for expert only, depending on compilation options).Incremented by the
-d
command line option. Set to thePYTHONDEBUG
environment variable value.Needs a debug build of Python (the
Py_DEBUG
macro must be defined).Default:
0
.
-
int pathconfig_warnings¶
If non-zero, calculation of path configuration is allowed to log warnings into
stderr
. If equals to0
, suppress these warnings.Default:
1
in Python mode,0
in isolated mode.Part of the Python Path Configuration input.
Changed in version 3.11: Now also applies on Windows.
-
wchar_t *prefix¶
The site-specific directory prefix where the platform independent Python files are installed:
sys.prefix
.Default:
NULL
.Part of the Python Path Configuration output.
See also
PyConfig.base_prefix
.
-
wchar_t *program_name¶
Program name used to initialize
executable
and in early error messages during Python initialization.On macOS, use
PYTHONEXECUTABLE
environment variable if set.If the
WITH_NEXT_FRAMEWORK
macro is defined, use__PYVENV_LAUNCHER__
environment variable if set.Use
argv[0]
ofargv
if available and non-empty.Otherwise, use
L"python"
on Windows, orL"python3"
on other platforms.
Default:
NULL
.Part of the Python Path Configuration input.
-
wchar_t *pycache_prefix¶
Directory where cached
.pyc
files are written:sys.pycache_prefix
.Set by the
-X pycache_prefix=PATH
command line option and thePYTHONPYCACHEPREFIX
environment variable. The command-line option takes precedence.If
NULL
,sys.pycache_prefix
is set toNone
.Default:
NULL
.
-
int quiet¶
Quiet mode. If greater than
0
, don’t display the copyright and version at Python startup in interactive mode.Incremented by the
-q
command line option.Default:
0
.
-
wchar_t *run_command¶
Value of the
-c
command line option.Used by
Py_RunMain()
.Default:
NULL
.
-
wchar_t *run_filename¶
Filename passed on the command line: trailing command line argument without
-c
or-m
. It is used by thePy_RunMain()
function.For example, it is set to
script.py
by thepython3 script.py arg
command line.See also the
PyConfig.skip_source_first_line
option.Default:
NULL
.
-
wchar_t *run_module¶
Value of the
-m
command line option.Used by
Py_RunMain()
.Default:
NULL
.
-
wchar_t *run_presite¶
package.module
path to module that should be imported beforesite.py
is run.Set by the
-X presite=package.module
command-line option and thePYTHON_PRESITE
environment variable. The command-line option takes precedence.Needs a debug build of Python (the
Py_DEBUG
macro must be defined).Default:
NULL
.
-
int show_ref_count¶
Show total reference count at exit (excluding immortal objects)?
Set to
1
by-X showrefcount
command line option.Needs a debug build of Python (the
Py_REF_DEBUG
macro must be defined).Default:
0
.
-
int site_import¶
Import the
site
module at startup?If equal to zero, disable the import of the module site and the site-dependent manipulations of
sys.path
that it entails.Also disable these manipulations if the
site
module is explicitly imported later (callsite.main()
if you want them to be triggered).Set to
0
by the-S
command line option.sys.flags.no_site
is set to the inverted value ofsite_import
.Default:
1
.
-
int skip_source_first_line¶
If non-zero, skip the first line of the
PyConfig.run_filename
source.It allows the usage of non-Unix forms of
#!cmd
. This is intended for a DOS specific hack only.Set to
1
by the-x
command line option.Default:
0
.
-
wchar_t *stdio_encoding¶
-
wchar_t *stdio_errors¶
Encoding and encoding errors of
sys.stdin
,sys.stdout
andsys.stderr
(butsys.stderr
always uses"backslashreplace"
error handler).Use the
PYTHONIOENCODING
environment variable if it is non-empty.Default encoding:
"UTF-8"
ifPyPreConfig.utf8_mode
is non-zero.Otherwise, use the locale encoding.
Default error handler:
On Windows: use
"surrogateescape"
."surrogateescape"
ifPyPreConfig.utf8_mode
is non-zero, or if the LC_CTYPE locale is “C” or “POSIX”."strict"
otherwise.
See also
PyConfig.legacy_windows_stdio
.
-
int tracemalloc¶
Enable tracemalloc?
If non-zero, call
tracemalloc.start()
at startup.Set by
-X tracemalloc=N
command line option and by thePYTHONTRACEMALLOC
environment variable.Default:
-1
in Python mode,0
in isolated mode.
-
int perf_profiling¶
Enable the Linux
perf
profiler support?If equals to
1
, enable support for the Linuxperf
profiler.If equals to
2
, enable support for the Linuxperf
profiler with DWARF JIT support.Set to
1
by-X perf
command-line option and thePYTHONPERFSUPPORT
environment variable.Set to
2
by the-X perf_jit
command-line option and thePYTHON_PERF_JIT_SUPPORT
environment variable.Default:
-1
.See also
See Python support for the Linux perf profiler for more information.
Added in version 3.12.
-
wchar_t *stdlib_dir¶
Directory of the Python standard library.
Default:
NULL
.Added in version 3.11.
-
int use_environment¶
-
If equals to zero, ignore the environment variables.
Set to
0
by the-E
environment variable.Default:
1
in Python config and0
in isolated config.
-
int use_system_logger¶
If non-zero,
stdout
andstderr
will be redirected to the system log.Only available on macOS 10.12 and later, and on iOS.
Default:
0
(don’t use the system log) on macOS;1
on iOS (use the system log).Added in version 3.14.
-
int user_site_directory¶
If non-zero, add the user site directory to
sys.path
.Set to
0
by the-s
and-I
command line options.Set to
0
by thePYTHONNOUSERSITE
environment variable.Default:
1
in Python mode,0
in isolated mode.
-
int verbose¶
Verbose mode. If greater than
0
, print a message each time a module is imported, showing the place (filename or built-in module) from which it is loaded.If greater than or equal to
2
, print a message for each file that is checked for when searching for a module. Also provides information on module cleanup at exit.Incremented by the
-v
command line option.Set by the
PYTHONVERBOSE
environment variable value.Default:
0
.
-
PyWideStringList warnoptions¶
Options of the
warnings
module to build warnings filters, lowest to highest priority:sys.warnoptions
.The
warnings
module addssys.warnoptions
in the reverse order: the lastPyConfig.warnoptions
item becomes the first item ofwarnings.filters
which is checked first (highest priority).The
-W
command line options adds its value towarnoptions
, it can be used multiple times.The
PYTHONWARNINGS
environment variable can also be used to add warning options. Multiple options can be specified, separated by commas (,
).Default: empty list.
-
int write_bytecode¶
If equal to
0
, Python won’t try to write.pyc
files on the import of source modules.Set to
0
by the-B
command line option and thePYTHONDONTWRITEBYTECODE
environment variable.sys.dont_write_bytecode
is initialized to the inverted value ofwrite_bytecode
.Default:
1
.
-
PyWideStringList xoptions¶
Values of the
-X
command line options:sys._xoptions
.Default: empty list.
-
int _pystats¶
If non-zero, write performance statistics at Python exit.
Need a special build with the
Py_STATS
macro: see--enable-pystats
.Default:
0
.
-
void PyConfig_InitPythonConfig(PyConfig *config)¶
If parse_argv
is non-zero, argv
arguments are parsed the same way the regular Python parses command line
arguments, and Python arguments are stripped from
argv
.
The xoptions
options are parsed to set other options: see
the -X
command line option.
Changed in version 3.9: The show_alloc_count
field has been removed.
Initialization with PyConfig¶
Initializing the interpreter from a populated configuration struct is handled
by calling Py_InitializeFromConfig()
.
The caller is responsible to handle exceptions (error or exit) using
PyStatus_Exception()
and Py_ExitStatusException()
.
If PyImport_FrozenModules()
, PyImport_AppendInittab()
or
PyImport_ExtendInittab()
are used, they must be set or called after
Python preinitialization and before the Python initialization. If Python is
initialized multiple times, PyImport_AppendInittab()
or
PyImport_ExtendInittab()
must be called before each Python
initialization.
The current configuration (PyConfig
type) is stored in
PyInterpreterState.config
.
Example setting the program name:
void init_python(void)
{
PyStatus status;
PyConfig config;
PyConfig_InitPythonConfig(&config);
/* Set the program name. Implicitly preinitialize Python. */
status = PyConfig_SetString(&config, &config.program_name,
L"/path/to/my_program");
if (PyStatus_Exception(status)) {
goto exception;
}
status = Py_InitializeFromConfig(&config);
if (PyStatus_Exception(status)) {
goto exception;
}
PyConfig_Clear(&config);
return;
exception:
PyConfig_Clear(&config);
Py_ExitStatusException(status);
}
More complete example modifying the default configuration, read the configuration, and then override some parameters. Note that since 3.11, many parameters are not calculated until initialization, and so values cannot be read from the configuration structure. Any values set before initialize is called will be left unchanged by initialization:
PyStatus init_python(const char *program_name)
{
PyStatus status;
PyConfig config;
PyConfig_InitPythonConfig(&config);
/* Set the program name before reading the configuration
(decode byte string from the locale encoding).
Implicitly preinitialize Python. */
status = PyConfig_SetBytesString(&config, &config.program_name,
program_name);
if (PyStatus_Exception(status)) {
goto done;
}
/* Read all configuration at once */
status = PyConfig_Read(&config);
if (PyStatus_Exception(status)) {
goto done;
}
/* Specify sys.path explicitly */
/* If you want to modify the default set of paths, finish
initialization first and then use PySys_GetObject("path") */
config.module_search_paths_set = 1;
status = PyWideStringList_Append(&config.module_search_paths,
L"/path/to/stdlib");
if (PyStatus_Exception(status)) {
goto done;
}
status = PyWideStringList_Append(&config.module_search_paths,
L"/path/to/more/modules");
if (PyStatus_Exception(status)) {
goto done;
}
/* Override executable computed by PyConfig_Read() */
status = PyConfig_SetString(&config, &config.executable,
L"/path/to/my_executable");
if (PyStatus_Exception(status)) {
goto done;
}
status = Py_InitializeFromConfig(&config);
done:
PyConfig_Clear(&config);
return status;
}
Isolated Configuration¶
PyPreConfig_InitIsolatedConfig()
and
PyConfig_InitIsolatedConfig()
functions create a configuration to
isolate Python from the system. For example, to embed Python into an
application.
This configuration ignores global configuration variables, environment
variables, command line arguments (PyConfig.argv
is not parsed)
and user site directory. The C standard streams (ex: stdout
) and the
LC_CTYPE locale are left unchanged. Signal handlers are not installed.
Configuration files are still used with this configuration to determine
paths that are unspecified. Ensure PyConfig.home
is specified
to avoid computing the default path configuration.
Python Configuration¶
PyPreConfig_InitPythonConfig()
and PyConfig_InitPythonConfig()
functions create a configuration to build a customized Python which behaves as
the regular Python.
Environments variables and command line arguments are used to configure Python, whereas global configuration variables are ignored.
This function enables C locale coercion (PEP 538)
and Python UTF-8 Mode
(PEP 540) depending on the LC_CTYPE locale, PYTHONUTF8
and
PYTHONCOERCECLOCALE
environment variables.
Python Path Configuration¶
PyConfig
contains multiple fields for the path configuration:
Path configuration inputs:
current working directory: to get absolute paths
PATH
environment variable to get the program full path (fromPyConfig.program_name
)__PYVENV_LAUNCHER__
environment variable(Windows only) Application paths in the registry under “SoftwarePythonPythonCoreX.YPythonPath” of HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE (where X.Y is the Python version).
Path configuration output fields:
If at least one “output field” is not set, Python calculates the path
configuration to fill unset fields. If
module_search_paths_set
is equal to 0
,
module_search_paths
is overridden and
module_search_paths_set
is set to 1
.
It is possible to completely ignore the function calculating the default
path configuration by setting explicitly all path configuration output
fields listed above. A string is considered as set even if it is non-empty.
module_search_paths
is considered as set if
module_search_paths_set
is set to 1
. In this case,
module_search_paths
will be used without modification.
Set pathconfig_warnings
to 0
to suppress warnings when
calculating the path configuration (Unix only, Windows does not log any warning).
If base_prefix
or base_exec_prefix
fields are not set, they inherit their value from prefix
and exec_prefix
respectively.
Py_RunMain()
and Py_Main()
modify sys.path
:
If
run_filename
is set and is a directory which contains a__main__.py
script, prependrun_filename
tosys.path
.If
isolated
is zero:If
run_module
is set, prepend the current directory tosys.path
. Do nothing if the current directory cannot be read.If
run_filename
is set, prepend the directory of the filename tosys.path
.Otherwise, prepend an empty string to
sys.path
.
If site_import
is non-zero, sys.path
can be
modified by the site
module. If
user_site_directory
is non-zero and the user’s
site-package directory exists, the site
module appends the user’s
site-package directory to sys.path
.
The following configuration files are used by the path configuration:
pyvenv.cfg
._pth
file (ex:python._pth
)pybuilddir.txt
(Unix only)
If a ._pth
file is present:
Set
isolated
to1
.Set
use_environment
to0
.Set
site_import
to0
.Set
safe_path
to1
.
If home
is not set and a pyvenv.cfg
file is present in
the same directory as executable
, or its parent,
prefix
and exec_prefix
are set that
location. When this happens, base_prefix
and
base_exec_prefix
still keep their value, pointing to the
base installation. See Virtual Environments for more
information.
The __PYVENV_LAUNCHER__
environment variable is used to set
PyConfig.base_executable
.
Changed in version 3.14: prefix
, and exec_prefix
, are now
set to the pyvenv.cfg
directory. This was previously done by site
,
therefore affected by -S
.
Py_GetArgcArgv()¶
-
void Py_GetArgcArgv(int *argc, wchar_t ***argv)¶
Get the original command line arguments, before Python modified them.
See also
PyConfig.orig_argv
member.
Delaying main module execution¶
In some embedding use cases, it may be desirable to separate interpreter initialization from the execution of the main module.
This separation can be achieved by setting PyConfig.run_command
to the empty
string during initialization (to prevent the interpreter from dropping into the
interactive prompt), and then subsequently executing the desired main module
code using __main__.__dict__
as the global namespace.


DateTime Objects

DateTime Objects¶
Various date and time objects are supplied by the datetime
module.
Before using any of these functions, the header file datetime.h
must be
included in your source (note that this is not included by Python.h
),
and the macro PyDateTime_IMPORT
must be invoked, usually as part of
the module initialisation function. The macro puts a pointer to a C structure
into a static variable, PyDateTimeAPI
, that is used by the following
macros.
-
PyDateTime_IMPORT()¶
Import the datetime C API.
On success, populate the
PyDateTimeAPI
pointer. On failure, setPyDateTimeAPI
toNULL
and set an exception. The caller must check if an error occurred viaPyErr_Occurred()
:PyDateTime_IMPORT; if (PyErr_Occurred()) { /* cleanup */ }
Warning
This is not compatible with subinterpreters.
-
type PyDateTime_CAPI¶
Structure containing the fields for the datetime C API.
The fields of this structure are private and subject to change.
Do not use this directly; prefer
PyDateTime_*
APIs instead.
-
PyDateTime_CAPI *PyDateTimeAPI¶
Dynamically allocated object containing the datetime C API.
This variable is only available once
PyDateTime_IMPORT
succeeds.
-
type PyDateTime_Delta¶
This subtype of
PyObject
represents the difference between two datetime values.
-
PyTypeObject PyDateTime_DateType¶
This instance of
PyTypeObject
represents the Python date type; it is the same object asdatetime.date
in the Python layer.
-
PyTypeObject PyDateTime_DateTimeType¶
This instance of
PyTypeObject
represents the Python datetime type; it is the same object asdatetime.datetime
in the Python layer.
-
PyTypeObject PyDateTime_TimeType¶
This instance of
PyTypeObject
represents the Python time type; it is the same object asdatetime.time
in the Python layer.
-
PyTypeObject PyDateTime_DeltaType¶
This instance of
PyTypeObject
represents the Python type for the difference between two datetime values; it is the same object asdatetime.timedelta
in the Python layer.
-
PyTypeObject PyDateTime_TZInfoType¶
This instance of
PyTypeObject
represents the Python time zone info type; it is the same object asdatetime.tzinfo
in the Python layer.
Macro for access to the UTC singleton:
-
PyObject *PyDateTime_TimeZone_UTC¶
Returns the time zone singleton representing UTC, the same object as
datetime.timezone.utc
.Added in version 3.7.
Type-check macros:
-
int PyDate_Check(PyObject *ob)¶
Return true if ob is of type
PyDateTime_DateType
or a subtype ofPyDateTime_DateType
. ob must not beNULL
. This function always succeeds.
-
int PyDate_CheckExact(PyObject *ob)¶
Return true if ob is of type
PyDateTime_DateType
. ob must not beNULL
. This function always succeeds.
-
int PyDateTime_Check(PyObject *ob)¶
Return true if ob is of type
PyDateTime_DateTimeType
or a subtype ofPyDateTime_DateTimeType
. ob must not beNULL
. This function always succeeds.
-
int PyDateTime_CheckExact(PyObject *ob)¶
Return true if ob is of type
PyDateTime_DateTimeType
. ob must not beNULL
. This function always succeeds.
-
int PyTime_Check(PyObject *ob)¶
Return true if ob is of type
PyDateTime_TimeType
or a subtype ofPyDateTime_TimeType
. ob must not beNULL
. This function always succeeds.
-
int PyTime_CheckExact(PyObject *ob)¶
Return true if ob is of type
PyDateTime_TimeType
. ob must not beNULL
. This function always succeeds.
-
int PyDelta_Check(PyObject *ob)¶
Return true if ob is of type
PyDateTime_DeltaType
or a subtype ofPyDateTime_DeltaType
. ob must not beNULL
. This function always succeeds.
-
int PyDelta_CheckExact(PyObject *ob)¶
Return true if ob is of type
PyDateTime_DeltaType
. ob must not beNULL
. This function always succeeds.
-
int PyTZInfo_Check(PyObject *ob)¶
Return true if ob is of type
PyDateTime_TZInfoType
or a subtype ofPyDateTime_TZInfoType
. ob must not beNULL
. This function always succeeds.
-
int PyTZInfo_CheckExact(PyObject *ob)¶
Return true if ob is of type
PyDateTime_TZInfoType
. ob must not beNULL
. This function always succeeds.
Macros to create objects:
-
PyObject *PyDate_FromDate(int year, int month, int day)¶
- Return value: New reference.
Return a
datetime.date
object with the specified year, month and day.
-
PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)¶
- Return value: New reference.
Return a
datetime.datetime
object with the specified year, month, day, hour, minute, second and microsecond.
-
PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)¶
- Return value: New reference.
Return a
datetime.datetime
object with the specified year, month, day, hour, minute, second, microsecond and fold.Added in version 3.6.
-
PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)¶
- Return value: New reference.
Return a
datetime.time
object with the specified hour, minute, second and microsecond.
-
PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)¶
- Return value: New reference.
Return a
datetime.time
object with the specified hour, minute, second, microsecond and fold.Added in version 3.6.
-
PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)¶
- Return value: New reference.
Return a
datetime.timedelta
object representing the given number of days, seconds and microseconds. Normalization is performed so that the resulting number of microseconds and seconds lie in the ranges documented fordatetime.timedelta
objects.
-
PyObject *PyTimeZone_FromOffset(PyObject *offset)¶
- Return value: New reference.
Return a
datetime.timezone
object with an unnamed fixed offset represented by the offset argument.Added in version 3.7.
-
PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)¶
- Return value: New reference.
Return a
datetime.timezone
object with a fixed offset represented by the offset argument and with tzname name.Added in version 3.7.
Macros to extract fields from date objects. The argument must be an instance of
PyDateTime_Date
, including subclasses (such as
PyDateTime_DateTime
). The argument must not be NULL
, and the type is
not checked:
-
int PyDateTime_GET_YEAR(PyDateTime_Date *o)¶
Return the year, as a positive int.
-
int PyDateTime_GET_MONTH(PyDateTime_Date *o)¶
Return the month, as an int from 1 through 12.
-
int PyDateTime_GET_DAY(PyDateTime_Date *o)¶
Return the day, as an int from 1 through 31.
Macros to extract fields from datetime objects. The argument must be an
instance of PyDateTime_DateTime
, including subclasses. The argument
must not be NULL
, and the type is not checked:
-
int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)¶
Return the hour, as an int from 0 through 23.
-
int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)¶
Return the minute, as an int from 0 through 59.
-
int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)¶
Return the second, as an int from 0 through 59.
-
int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)¶
Return the microsecond, as an int from 0 through 999999.
-
int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)¶
Return the fold, as an int from 0 through 1.
Added in version 3.6.
-
PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)¶
Return the tzinfo (which may be
None
).Added in version 3.10.
Macros to extract fields from time objects. The argument must be an instance of
PyDateTime_Time
, including subclasses. The argument must not be NULL
,
and the type is not checked:
-
int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)¶
Return the hour, as an int from 0 through 23.
-
int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)¶
Return the minute, as an int from 0 through 59.
-
int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)¶
Return the second, as an int from 0 through 59.
-
int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)¶
Return the microsecond, as an int from 0 through 999999.
-
int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)¶
Return the fold, as an int from 0 through 1.
Added in version 3.6.
-
PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)¶
Return the tzinfo (which may be
None
).Added in version 3.10.
Macros to extract fields from time delta objects. The argument must be an
instance of PyDateTime_Delta
, including subclasses. The argument must
not be NULL
, and the type is not checked:
-
int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)¶
Return the number of days, as an int from -999999999 to 999999999.
Added in version 3.3.
-
int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)¶
Return the number of seconds, as an int from 0 through 86399.
Added in version 3.3.
-
int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)¶
Return the number of microseconds, as an int from 0 through 999999.
Added in version 3.3.
Macros for the convenience of modules implementing the DB API:
-
PyObject *PyDateTime_FromTimestamp(PyObject *args)¶
- Return value: New reference.
Create and return a new
datetime.datetime
object given an argument tuple suitable for passing todatetime.datetime.fromtimestamp()
.
-
PyObject *PyDate_FromTimestamp(PyObject *args)¶
- Return value: New reference.
Create and return a new
datetime.date
object given an argument tuple suitable for passing todatetime.date.fromtimestamp()
.
Internal data¶
The following symbols are exposed by the C API but should be considered internal-only.
-
PyDateTime_CAPSULE_NAME¶
Name of the datetime capsule to pass to
PyCapsule_Import()
.Internal usage only. Use
PyDateTime_IMPORT
instead.


— Determine the type of an image

imghdr
— Determine the type of an image¶
Deprecated since version 3.11, removed in version 3.13.
This module is no longer part of the Python standard library. It was removed in Python 3.13 after being deprecated in Python 3.11. The removal was decided in PEP 594.
Possible replacements are third-party libraries from PyPI: filetype, puremagic, or python-magic. These are not supported or maintained by the Python core team.
The last version of Python that provided the imghdr
module was
Python 3.12.


distutils
— Building and installing Python modules¶
Deprecated since version 3.10, removed in version 3.12.
This module is no longer part of the Python standard library. It was removed in Python 3.12 after being deprecated in Python 3.10. The removal was decided in PEP 632, which has migration advice.
The last version of Python that provided the distutils
module was
Python 3.11.


— Function to check Unix passwords

crypt
— Function to check Unix passwords¶
Deprecated since version 3.11, removed in version 3.13.
This module is no longer part of the Python standard library. It was removed in Python 3.13 after being deprecated in Python 3.11. The removal was decided in PEP 594.
Applications can use the hashlib
module from the standard library.
Other possible replacements are third-party libraries from PyPI:
legacycrypt, bcrypt, or argon2-cffi.
These are not supported or maintained by the Python core team.
The last version of Python that provided the crypt
module was
Python 3.12.


— Read IFF chunked data

chunk
— Read IFF chunked data¶
Deprecated since version 3.11, removed in version 3.13.
This module is no longer part of the Python standard library. It was removed in Python 3.13 after being deprecated in Python 3.11. The removal was decided in PEP 594.
The last version of Python that provided the chunk
module was
Python 3.12.


Object Life Cycle

Object Life Cycle¶
This section explains how a type’s slots relate to each other throughout the life of an object. It is not intended to be a complete canonical reference for the slots; instead, refer to the slot-specific documentation in Type Object Structures for details about a particular slot.
Life Events¶
The figure below illustrates the order of events that can occur throughout an object’s life. An arrow from A to B indicates that event B can occur after event A has occurred, with the arrow’s label indicating the condition that must be true for B to occur after A.
Explanation:
When a new object is constructed by calling its type:
tp_new
is called to create a new object.tp_alloc
is directly called bytp_new
to allocate the memory for the new object.tp_init
initializes the newly created object.tp_init
can be called again to re-initialize an object, if desired. Thetp_init
call can also be skipped entirely, for example by Python code calling__new__()
.
After
tp_init
completes, the object is ready to use.Some time after the last reference to an object is removed:
If an object is not marked as finalized, it might be finalized by marking it as finalized and calling its
tp_finalize
function. Python does not finalize an object when the last reference to it is deleted; usePyObject_CallFinalizerFromDealloc()
to ensure thattp_finalize
is always called.If the object is marked as finalized,
tp_clear
might be called by the garbage collector to clear references held by the object. It is not called when the object’s reference count reaches zero.tp_dealloc
is called to destroy the object. To avoid code duplication,tp_dealloc
typically calls intotp_clear
to free up the object’s references.When
tp_dealloc
finishes object destruction, it directly callstp_free
(usually set toPyObject_Free()
orPyObject_GC_Del()
automatically as appropriate for the type) to deallocate the memory.
The
tp_finalize
function is permitted to add a reference to the object if desired. If it does, the object is resurrected, preventing its pending destruction. (Onlytp_finalize
is allowed to resurrect an object;tp_clear
andtp_dealloc
cannot without calling intotp_finalize
.) Resurrecting an object may or may not cause the object’s finalized mark to be removed. Currently, Python does not remove the finalized mark from a resurrected object if it supports garbage collection (i.e., thePy_TPFLAGS_HAVE_GC
flag is set) but does remove the mark if the object does not support garbage collection; either or both of these behaviors may change in the future.tp_dealloc
can optionally calltp_finalize
viaPyObject_CallFinalizerFromDealloc()
if it wishes to reuse that code to help with object destruction. This is recommended because it guarantees thattp_finalize
is always called before destruction. See thetp_dealloc
documentation for example code.If the object is a member of a cyclic isolate and either
tp_clear
fails to break the reference cycle or the cyclic isolate is not detected (perhapsgc.disable()
was called, or thePy_TPFLAGS_HAVE_GC
flag was erroneously omitted in one of the involved types), the objects remain indefinitely uncollectable (they “leak”). Seegc.garbage
.
If the object is marked as supporting garbage collection (the
Py_TPFLAGS_HAVE_GC
flag is set in
tp_flags
), the following events are also possible:
The garbage collector occasionally calls
tp_traverse
to identify cyclic isolates.When the garbage collector discovers a cyclic isolate, it finalizes one of the objects in the group by marking it as finalized and calling its
tp_finalize
function, if it has one. This repeats until the cyclic isolate doesn’t exist or all of the objects have been finalized.tp_finalize
is permitted to resurrect the object by adding a reference from outside the cyclic isolate. The new reference causes the group of objects to no longer form a cyclic isolate (the reference cycle may still exist, but if it does the objects are no longer isolated).When the garbage collector discovers a cyclic isolate and all of the objects in the group have already been marked as finalized, the garbage collector clears one or more of the uncleared objects in the group (possibly concurrently) by calling each’s
tp_clear
function. This repeats as long as the cyclic isolate still exists and not all of the objects have been cleared.
Cyclic Isolate Destruction¶
Listed below are the stages of life of a hypothetical cyclic isolate
that continues to exist after each member object is finalized or cleared. It
is a memory leak if a cyclic isolate progresses through all of these stages; it should
vanish once all objects are cleared, if not sooner. A cyclic isolate can
vanish either because the reference cycle is broken or because the objects are
no longer isolated due to finalizer resurrection (see
tp_finalize
).
Reachable (not yet a cyclic isolate): All objects are in their normal, reachable state. A reference cycle could exist, but an external reference means the objects are not yet isolated.
Unreachable but consistent: The final reference from outside the cyclic group of objects has been removed, causing the objects to become isolated (thus a cyclic isolate is born). None of the group’s objects have been finalized or cleared yet. The cyclic isolate remains at this stage until some future run of the garbage collector (not necessarily the next run because the next run might not scan every object).
Mix of finalized and not finalized: Objects in a cyclic isolate are finalized one at a time, which means that there is a period of time when the cyclic isolate is composed of a mix of finalized and non-finalized objects. Finalization order is unspecified, so it can appear random. A finalized object must behave in a sane manner when non-finalized objects interact with it, and a non-finalized object must be able to tolerate the finalization of an arbitrary subset of its referents.
All finalized: All objects in a cyclic isolate are finalized before any of them are cleared.
Mix of finalized and cleared: The objects can be cleared serially or concurrently (but with the GIL held); either way, some will finish before others. A finalized object must be able to tolerate the clearing of a subset of its referents. PEP 442 calls this stage “cyclic trash”.
Leaked: If a cyclic isolate still exists after all objects in the group have been finalized and cleared, then the objects remain indefinitely uncollectable (see
gc.garbage
). It is a bug if a cyclic isolate reaches this stage—it means thetp_clear
methods of the participating objects have failed to break the reference cycle as required.
If tp_clear
did not exist, then Python would have no
way to safely break a reference cycle. Simply destroying an object in a cyclic
isolate would result in a dangling pointer, triggering undefined behavior when
an object referencing the destroyed object is itself destroyed. The clearing
step makes object destruction a two-phase process: first
tp_clear
is called to partially destroy the objects
enough to detangle them from each other, then
tp_dealloc
is called to complete the destruction.
Unlike clearing, finalization is not a phase of destruction. A finalized
object must still behave properly by continuing to fulfill its design
contracts. An object’s finalizer is allowed to execute arbitrary Python code,
and is even allowed to prevent the impending destruction by adding a reference.
The finalizer is only related to destruction by call order—if it runs, it runs
before destruction, which starts with tp_clear
(if
called) and concludes with tp_dealloc
.
The finalization step is not necessary to safely reclaim the objects in a cyclic isolate, but its existence makes it easier to design types that behave in a sane manner when objects are cleared. Clearing an object might necessarily leave it in a broken, partially destroyed state—it might be unsafe to call any of the cleared object’s methods or access any of its attributes. With finalization, only finalized objects can possibly interact with cleared objects; non-finalized objects are guaranteed to interact with only non-cleared (but potentially finalized) objects.
To summarize the possible interactions:
A non-finalized object might have references to or from non-finalized and finalized objects, but not to or from cleared objects.
A finalized object might have references to or from non-finalized, finalized, and cleared objects.
A cleared object might have references to or from finalized and cleared objects, but not to or from non-finalized objects.
Without any reference cycles, an object can be simply destroyed once its last
reference is deleted; the finalization and clearing steps are not necessary to
safely reclaim unused objects. However, it can be useful to automatically call
tp_finalize
and tp_clear
before destruction anyway because type design is simplified when all objects
always experience the same series of events regardless of whether they
participated in a cyclic isolate. Python currently only calls
tp_finalize
and tp_clear
as
needed to destroy a cyclic isolate; this may change in a future version.
Functions¶
To allocate and free memory, see Allocating Objects on the Heap.
-
void PyObject_CallFinalizer(PyObject *op)¶
Finalizes the object as described in
tp_finalize
. Call this function (orPyObject_CallFinalizerFromDealloc()
) instead of callingtp_finalize
directly because this function may deduplicate multiple calls totp_finalize
. Currently, calls are only deduplicated if the type supports garbage collection (i.e., thePy_TPFLAGS_HAVE_GC
flag is set); this may change in the future.Added in version 3.4.
-
int PyObject_CallFinalizerFromDealloc(PyObject *op)¶
Same as
PyObject_CallFinalizer()
but meant to be called at the beginning of the object’s destructor (tp_dealloc
). There must not be any references to the object. If the object’s finalizer resurrects the object, this function returns -1; no further destruction should happen. Otherwise, this function returns 0 and destruction can continue normally.Added in version 3.4.
See also
tp_dealloc
for example code.


— Traceback manager for CGI scripts

cgitb
— Traceback manager for CGI scripts¶
Deprecated since version 3.11, removed in version 3.13.
This module is no longer part of the Python standard library. It was removed in Python 3.13 after being deprecated in Python 3.11. The removal was decided in PEP 594.
A fork of the module on PyPI can now be used instead: legacy-cgi. This is a copy of the cgi module, no longer maintained or supported by the core Python team.
The last version of Python that provided the cgitb
module was
Python 3.12.


— Common Gateway Interface support

cgi
— Common Gateway Interface support¶
Deprecated since version 3.11, removed in version 3.13.
This module is no longer part of the Python standard library. It was removed in Python 3.13 after being deprecated in Python 3.11. The removal was decided in PEP 594.
A fork of the module on PyPI can be used instead: legacy-cgi. This is a copy of the cgi module, no longer maintained or supported by the core Python team.
The last version of Python that provided the cgi
module was
Python 3.12.


Allocating Objects on the Heap

Allocating Objects on the Heap¶
-
PyObject *_PyObject_New(PyTypeObject *type)¶
- Return value: New reference.
-
PyVarObject *_PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)¶
- Return value: New reference.
-
PyObject *PyObject_Init(PyObject *op, PyTypeObject *type)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Initialize a newly allocated object op with its type and initial reference. Returns the initialized object. Other fields of the object are not initialized. Despite its name, this function is unrelated to the object’s
__init__()
method (tp_init
slot). Specifically, this function does not call the object’s__init__()
method.In general, consider this function to be a low-level routine. Use
tp_alloc
where possible. For implementingtp_alloc
for your type, preferPyType_GenericAlloc()
orPyObject_New()
.Note
This function only initializes the object’s memory corresponding to the initial
PyObject
structure. It does not zero the rest.
-
PyVarObject *PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)¶
- Return value: Borrowed reference. Part of the Stable ABI.
This does everything
PyObject_Init()
does, and also initializes the length information for a variable-size object.Note
This function only initializes some of the object’s memory. It does not zero the rest.
-
PyObject_New(TYPE, typeobj)¶
Allocates a new Python object using the C structure type TYPE and the Python type object typeobj (
PyTypeObject*
) by callingPyObject_Malloc()
to allocate memory and initializing it likePyObject_Init()
. The caller will own the only reference to the object (i.e. its reference count will be one).Avoid calling this directly to allocate memory for an object; call the type’s
tp_alloc
slot instead.When populating a type’s
tp_alloc
slot,PyType_GenericAlloc()
is preferred over a custom function that simply calls this macro.This macro does not call
tp_alloc
,tp_new
(__new__()
), ortp_init
(__init__()
).This cannot be used for objects with
Py_TPFLAGS_HAVE_GC
set intp_flags
; usePyObject_GC_New
instead.Memory allocated by this macro must be freed with
PyObject_Free()
(usually called via the object’stp_free
slot).Note
The returned memory is not guaranteed to have been completely zeroed before it was initialized.
Note
This macro does not construct a fully initialized object of the given type; it merely allocates memory and prepares it for further initialization by
tp_init
. To construct a fully initialized object, call typeobj instead. For example:PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);
-
PyObject_NewVar(TYPE, typeobj, size)¶
Like
PyObject_New
except:It allocates enough memory for the TYPE structure plus size (
Py_ssize_t
) fields of the size given by thetp_itemsize
field of typeobj.The memory is initialized like
PyObject_InitVar()
.
This is useful for implementing objects like tuples, which are able to determine their size at construction time. Embedding the array of fields into the same allocation decreases the number of allocations, improving the memory management efficiency.
Avoid calling this directly to allocate memory for an object; call the type’s
tp_alloc
slot instead.When populating a type’s
tp_alloc
slot,PyType_GenericAlloc()
is preferred over a custom function that simply calls this macro.This cannot be used for objects with
Py_TPFLAGS_HAVE_GC
set intp_flags
; usePyObject_GC_NewVar
instead.Memory allocated by this function must be freed with
PyObject_Free()
(usually called via the object’stp_free
slot).Note
The returned memory is not guaranteed to have been completely zeroed before it was initialized.
Note
This macro does not construct a fully initialized object of the given type; it merely allocates memory and prepares it for further initialization by
tp_init
. To construct a fully initialized object, call typeobj instead. For example:PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);
-
PyObject _Py_NoneStruct¶
Object which is visible in Python as
None
. This should only be accessed using thePy_None
macro, which evaluates to a pointer to this object.
See also
- Module Objects
To allocate and create extension modules.
Deprecated aliases¶
These are soft deprecated aliases to existing functions and macros. They exist solely for backwards compatibility.
Deprecated alias |
Function |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|


Buffer Protocol

Buffer Protocol¶
Certain objects available in Python wrap access to an underlying memory
array or buffer. Such objects include the built-in bytes
and
bytearray
, and some extension types like array.array
.
Third-party libraries may define their own types for special purposes, such
as image processing or numeric analysis.
While each of these types have their own semantics, they share the common characteristic of being backed by a possibly large memory buffer. It is then desirable, in some situations, to access that buffer directly and without intermediate copying.
Python provides such a facility at the C and Python level in the form of the buffer protocol. This protocol has two sides:
on the producer side, a type can export a “buffer interface” which allows objects of that type to expose information about their underlying buffer. This interface is described in the section Buffer Object Structures; for Python see Emulating buffer types.
on the consumer side, several means are available to obtain a pointer to the raw underlying data of an object (for example a method parameter). For Python see
memoryview
.
Simple objects such as bytes
and bytearray
expose their
underlying buffer in byte-oriented form. Other forms are possible; for example,
the elements exposed by an array.array
can be multi-byte values.
An example consumer of the buffer interface is the write()
method of file objects: any object that can export a series of bytes through
the buffer interface can be written to a file. While write()
only
needs read-only access to the internal contents of the object passed to it,
other methods such as readinto()
need write access
to the contents of their argument. The buffer interface allows objects to
selectively allow or reject exporting of read-write and read-only buffers.
There are two ways for a consumer of the buffer interface to acquire a buffer over a target object:
call
PyObject_GetBuffer()
with the right parameters;call
PyArg_ParseTuple()
(or one of its siblings) with one of they*
,w*
ors*
format codes.
In both cases, PyBuffer_Release()
must be called when the buffer
isn’t needed anymore. Failure to do so could lead to various issues such as
resource leaks.
Added in version 3.12: The buffer protocol is now accessible in Python, see
Emulating buffer types and memoryview
.
Buffer structure¶
Buffer structures (or simply “buffers”) are useful as a way to expose the binary data from another object to the Python programmer. They can also be used as a zero-copy slicing mechanism. Using their ability to reference a block of memory, it is possible to expose any data to the Python programmer quite easily. The memory could be a large, constant array in a C extension, it could be a raw block of memory for manipulation before passing to an operating system library, or it could be used to pass around structured data in its native, in-memory format.
Contrary to most data types exposed by the Python interpreter, buffers
are not PyObject
pointers but rather simple C structures. This
allows them to be created and copied very simply. When a generic wrapper
around a buffer is needed, a memoryview object
can be created.
For short instructions how to write an exporting object, see
Buffer Object Structures. For obtaining
a buffer, see PyObject_GetBuffer()
.
-
type Py_buffer¶
- Part of the Stable ABI (including all members) since version 3.11.
-
void *buf¶
A pointer to the start of the logical structure described by the buffer fields. This can be any location within the underlying physical memory block of the exporter. For example, with negative
strides
the value may point to the end of the memory block.For contiguous arrays, the value points to the beginning of the memory block.
-
PyObject *obj¶
A new reference to the exporting object. The reference is owned by the consumer and automatically released (i.e. reference count decremented) and set to
NULL
byPyBuffer_Release()
. The field is the equivalent of the return value of any standard C-API function.As a special case, for temporary buffers that are wrapped by
PyMemoryView_FromBuffer()
orPyBuffer_FillInfo()
this field isNULL
. In general, exporting objects MUST NOT use this scheme.
-
Py_ssize_t len¶
product(shape) * itemsize
. For contiguous arrays, this is the length of the underlying memory block. For non-contiguous arrays, it is the length that the logical structure would have if it were copied to a contiguous representation.Accessing
((char *)buf)[0] up to ((char *)buf)[len-1]
is only valid if the buffer has been obtained by a request that guarantees contiguity. In most cases such a request will bePyBUF_SIMPLE
orPyBUF_WRITABLE
.
-
int readonly¶
An indicator of whether the buffer is read-only. This field is controlled by the
PyBUF_WRITABLE
flag.
-
Py_ssize_t itemsize¶
Item size in bytes of a single element. Same as the value of
struct.calcsize()
called on non-NULL
format
values.Important exception: If a consumer requests a buffer without the
PyBUF_FORMAT
flag,format
will be set toNULL
, butitemsize
still has the value for the original format.If
shape
is present, the equalityproduct(shape) * itemsize == len
still holds and the consumer can useitemsize
to navigate the buffer.If
shape
isNULL
as a result of aPyBUF_SIMPLE
or aPyBUF_WRITABLE
request, the consumer must disregarditemsize
and assumeitemsize == 1
.
-
char *format¶
A NULL terminated string in
struct
module style syntax describing the contents of a single item. If this isNULL
,"B"
(unsigned bytes) is assumed.This field is controlled by the
PyBUF_FORMAT
flag.
-
int ndim¶
The number of dimensions the memory represents as an n-dimensional array. If it is
0
,buf
points to a single item representing a scalar. In this case,shape
,strides
andsuboffsets
MUST beNULL
. The maximum number of dimensions is given byPyBUF_MAX_NDIM
.
-
Py_ssize_t *shape¶
An array of
Py_ssize_t
of lengthndim
indicating the shape of the memory as an n-dimensional array. Note thatshape[0] * ... * shape[ndim-1] * itemsize
MUST be equal tolen
.Shape values are restricted to
shape[n] >= 0
. The caseshape[n] == 0
requires special attention. See complex arrays for further information.The shape array is read-only for the consumer.
-
Py_ssize_t *strides¶
An array of
Py_ssize_t
of lengthndim
giving the number of bytes to skip to get to a new element in each dimension.Stride values can be any integer. For regular arrays, strides are usually positive, but a consumer MUST be able to handle the case
strides[n] <= 0
. See complex arrays for further information.The strides array is read-only for the consumer.
-
Py_ssize_t *suboffsets¶
An array of
Py_ssize_t
of lengthndim
. Ifsuboffsets[n] >= 0
, the values stored along the nth dimension are pointers and the suboffset value dictates how many bytes to add to each pointer after de-referencing. A suboffset value that is negative indicates that no de-referencing should occur (striding in a contiguous memory block).If all suboffsets are negative (i.e. no de-referencing is needed), then this field must be
NULL
(the default value).This type of array representation is used by the Python Imaging Library (PIL). See complex arrays for further information how to access elements of such an array.
The suboffsets array is read-only for the consumer.
-
void *internal¶
This is for use internally by the exporting object. For example, this might be re-cast as an integer by the exporter and used to store flags about whether or not the shape, strides, and suboffsets arrays must be freed when the buffer is released. The consumer MUST NOT alter this value.
-
void *buf¶
Constants:
-
PyBUF_MAX_NDIM¶
- Part of the Stable ABI since version 3.11.
The maximum number of dimensions the memory represents. Exporters MUST respect this limit, consumers of multi-dimensional buffers SHOULD be able to handle up to
PyBUF_MAX_NDIM
dimensions. Currently set to 64.
Buffer request types¶
Buffers are usually obtained by sending a buffer request to an exporting
object via PyObject_GetBuffer()
. Since the complexity of the logical
structure of the memory can vary drastically, the consumer uses the flags
argument to specify the exact buffer type it can handle.
All Py_buffer
fields are unambiguously defined by the request
type.
request-independent fields¶
The following fields are not influenced by flags and must always be filled in
with the correct values: obj
, buf
,
len
, itemsize
, ndim
.
readonly, format¶
- PyBUF_WRITABLE¶
- Part of the Stable ABI since version 3.11.
Controls the
readonly
field. If set, the exporter MUST provide a writable buffer or else report failure. Otherwise, the exporter MAY provide either a read-only or writable buffer, but the choice MUST be consistent for all consumers. For example, PyBUF_SIMPLE | PyBUF_WRITABLE can be used to request a simple writable buffer.
- PyBUF_WRITEABLE¶
This is a soft deprecated alias to
PyBUF_WRITABLE
.
- PyBUF_FORMAT¶
- Part of the Stable ABI since version 3.11.
Controls the
format
field. If set, this field MUST be filled in correctly. Otherwise, this field MUST beNULL
.
PyBUF_WRITABLE
can be |’d to any of the flags in the next section.
Since PyBUF_SIMPLE
is defined as 0, PyBUF_WRITABLE
can be used as a stand-alone flag to request a simple writable buffer.
PyBUF_FORMAT
must be |’d to any of the flags except PyBUF_SIMPLE
, because
the latter already implies format B
(unsigned bytes). PyBUF_FORMAT
cannot be
used on its own.
shape, strides, suboffsets¶
The flags that control the logical structure of the memory are listed in decreasing order of complexity. Note that each flag contains all bits of the flags below it.
Request |
shape |
strides |
suboffsets |
|---|---|---|---|
|
yes |
yes |
if needed |
|
yes |
yes |
NULL |
|
yes |
NULL |
NULL |
|
NULL |
NULL |
NULL |
contiguity requests¶
C or Fortran contiguity can be explicitly requested, with and without stride information. Without stride information, the buffer must be C-contiguous.
Request |
shape |
strides |
suboffsets |
contig |
|---|---|---|---|---|
|
yes |
yes |
NULL |
C |
|
yes |
yes |
NULL |
F |
|
yes |
yes |
NULL |
C or F |
yes |
NULL |
NULL |
C |
compound requests¶
All possible requests are fully defined by some combination of the flags in the previous section. For convenience, the buffer protocol provides frequently used combinations as single flags.
In the following table U stands for undefined contiguity. The consumer would
have to call PyBuffer_IsContiguous()
to determine contiguity.
Request |
shape |
strides |
suboffsets |
contig |
readonly |
format |
|---|---|---|---|---|---|---|
|
yes |
yes |
if needed |
U |
0 |
yes |
|
yes |
yes |
if needed |
U |
1 or 0 |
yes |
|
yes |
yes |
NULL |
U |
0 |
yes |
|
yes |
yes |
NULL |
U |
1 or 0 |
yes |
|
yes |
yes |
NULL |
U |
0 |
NULL |
|
yes |
yes |
NULL |
U |
1 or 0 |
NULL |
|
yes |
NULL |
NULL |
C |
0 |
NULL |
|
yes |
NULL |
NULL |
C |
1 or 0 |
NULL |
Complex arrays¶
NumPy-style: shape and strides¶
The logical structure of NumPy-style arrays is defined by itemsize
,
ndim
, shape
and strides
.
If ndim == 0
, the memory location pointed to by buf
is
interpreted as a scalar of size itemsize
. In that case,
both shape
and strides
are NULL
.
If strides
is NULL
, the array is interpreted as
a standard n-dimensional C-array. Otherwise, the consumer must access an
n-dimensional array as follows:
ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);
As noted above, buf
can point to any location within
the actual memory block. An exporter can check the validity of a buffer with
this function:
def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
"""Verify that the parameters represent a valid array within
the bounds of the allocated memory:
char *mem: start of the physical memory block
memlen: length of the physical memory block
offset: (char *)buf - mem
"""
if offset % itemsize:
return False
if offset < 0 or offset+itemsize > memlen:
return False
if any(v % itemsize for v in strides):
return False
if ndim <= 0:
return ndim == 0 and not shape and not strides
if 0 in shape:
return True
imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
if strides[j] <= 0)
imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
if strides[j] > 0)
return 0 <= offset+imin and offset+imax+itemsize <= memlen
PIL-style: shape, strides and suboffsets¶
In addition to the regular items, PIL-style arrays can contain pointers
that must be followed in order to get to the next element in a dimension.
For example, the regular three-dimensional C-array char v[2][2][3]
can
also be viewed as an array of 2 pointers to 2 two-dimensional arrays:
char (*v[2])[2][3]
. In suboffsets representation, those two pointers
can be embedded at the start of buf
, pointing
to two char x[2][3]
arrays that can be located anywhere in memory.
Here is a function that returns a pointer to the element in an N-D array
pointed to by an N-dimensional index when there are both non-NULL
strides
and suboffsets:
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
Py_ssize_t *suboffsets, Py_ssize_t *indices) {
char *pointer = (char*)buf;
int i;
for (i = 0; i < ndim; i++) {
pointer += strides[i] * indices[i];
if (suboffsets[i] >=0 ) {
pointer = *((char**)pointer) + suboffsets[i];
}
}
return (void*)pointer;
}


— Manipulate raw audio data

audioop
— Manipulate raw audio data¶
Deprecated since version 3.11, removed in version 3.13.
This module is no longer part of the Python standard library. It was removed in Python 3.13 after being deprecated in Python 3.11. The removal was decided in PEP 594.
The last version of Python that provided the audioop
module was
Python 3.12.


Object Implementation Support

Object Implementation Support¶
This chapter describes the functions, types, and macros used when defining new object types.
- Allocating Objects on the Heap
- Object Life Cycle
- Common Object Structures
- Type Object Structures
- Supporting Cyclic Garbage Collection