Extending Python with C or C++

1. Extending Python with C or C++¶
It is quite easy to add new built-in modules to Python, if you know how to program in C. Such extension modules can do two things that can’t be done directly in Python: they can implement new built-in object types, and they can call C library functions and system calls.
To support extensions, the Python API (Application Programmers Interface)
defines a set of functions, macros and variables that provide access to most
aspects of the Python run-time system. The Python API is incorporated in a C
source file by including the header "Python.h"
.
The compilation of an extension module depends on its intended use as well as on your system setup; details are given in later chapters.
Note
The C extension interface is specific to CPython, and extension modules do
not work on other Python implementations. In many cases, it is possible to
avoid writing C extensions and preserve portability to other implementations.
For example, if your use case is calling C library functions or system calls,
you should consider using the ctypes
module or the cffi library rather than writing
custom C code.
These modules let you write Python code to interface with C code and are more
portable between implementations of Python than writing and compiling a C
extension module.
1.1. A Simple Example¶
Let’s create an extension module called spam
(the favorite food of Monty
Python fans…) and let’s say we want to create a Python interface to the C
library function system()
[1]. This function takes a null-terminated
character string as argument and returns an integer. We want this function to
be callable from Python as follows:
>>> import spam
>>> status = spam.system("ls -l")
Begin by creating a file spammodule.c
. (Historically, if a module is
called spam
, the C file containing its implementation is called
spammodule.c
; if the module name is very long, like spammify
, the
module name can be just spammify.c
.)
The first two lines of our file can be:
#define PY_SSIZE_T_CLEAN
#include <Python.h>
which pulls in the Python API (you can add a comment describing the purpose of the module and a copyright notice if you like).
Note
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you must include Python.h
before any standard
headers are included.
#define PY_SSIZE_T_CLEAN
was used to indicate that Py_ssize_t
should be
used in some APIs instead of int
.
It is not necessary since Python 3.13, but we keep it here for backward compatibility.
See Strings and buffers for a description of this macro.
All user-visible symbols defined by Python.h
have a prefix of Py
or
PY
, except those defined in standard header files.
Tip
For backward compatibility, Python.h
includes several standard header files.
C extensions should include the standard headers that they use,
and should not rely on these implicit includes.
If using the limited C API version 3.13 or newer, the implicit includes are:
<assert.h>
<intrin.h>
(on Windows)<inttypes.h>
<limits.h>
<math.h>
<stdarg.h>
<wchar.h>
<sys/types.h>
(if present)
If Py_LIMITED_API
is not defined, or is set to version 3.12 or older,
the headers below are also included:
<ctype.h>
<unistd.h>
(on POSIX)
If Py_LIMITED_API
is not defined, or is set to version 3.10 or older,
the headers below are also included:
<errno.h>
<stdio.h>
<stdlib.h>
<string.h>
The next thing we add to our module file is the C function that will be called
when the Python expression spam.system(string)
is evaluated (we’ll see
shortly how it ends up being called):
static PyObject *
spam_system(PyObject *self, PyObject *args)
{
const char *command;
int sts;
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
sts = system(command);
return PyLong_FromLong(sts);
}
There is a straightforward translation from the argument list in Python (for
example, the single expression "ls -l"
) to the arguments passed to the C
function. The C function always has two arguments, conventionally named self
and args.
The self argument points to the module object for module-level functions; for a method it would point to the object instance.
The args argument will be a pointer to a Python tuple object containing the
arguments. Each item of the tuple corresponds to an argument in the call’s
argument list. The arguments are Python objects — in order to do anything
with them in our C function we have to convert them to C values. The function
PyArg_ParseTuple()
in the Python API checks the argument types and
converts them to C values. It uses a template string to determine the required
types of the arguments as well as the types of the C variables into which to
store the converted values. More about this later.
PyArg_ParseTuple()
returns true (nonzero) if all arguments have the right
type and its components have been stored in the variables whose addresses are
passed. It returns false (zero) if an invalid argument list was passed. In the
latter case it also raises an appropriate exception so the calling function can
return NULL
immediately (as we saw in the example).
1.2. Intermezzo: Errors and Exceptions¶
An important convention throughout the Python interpreter is the following: when
a function fails, it should set an exception condition and return an error value
(usually -1
or a NULL
pointer). Exception information is stored in
three members of the interpreter’s thread state. These are NULL
if
there is no exception. Otherwise they are the C equivalents of the members
of the Python tuple returned by sys.exc_info()
. These are the
exception type, exception instance, and a traceback object. It is important
to know about them to understand how errors are passed around.
The Python API defines a number of functions to set various types of exceptions.
The most common one is PyErr_SetString()
. Its arguments are an exception
object and a C string. The exception object is usually a predefined object like
PyExc_ZeroDivisionError
. The C string indicates the cause of the error
and is converted to a Python string object and stored as the “associated value”
of the exception.
Another useful function is PyErr_SetFromErrno()
, which only takes an
exception argument and constructs the associated value by inspection of the
global variable errno
. The most general function is
PyErr_SetObject()
, which takes two object arguments, the exception and
its associated value. You don’t need to Py_INCREF()
the objects passed
to any of these functions.
You can test non-destructively whether an exception has been set with
PyErr_Occurred()
. This returns the current exception object, or NULL
if no exception has occurred. You normally don’t need to call
PyErr_Occurred()
to see whether an error occurred in a function call,
since you should be able to tell from the return value.
When a function f that calls another function g detects that the latter
fails, f should itself return an error value (usually NULL
or -1
). It
should not call one of the PyErr_*
functions — one has already
been called by g. f’s caller is then supposed to also return an error
indication to its caller, again without calling PyErr_*
, and so on
— the most detailed cause of the error was already reported by the function
that first detected it. Once the error reaches the Python interpreter’s main
loop, this aborts the currently executing Python code and tries to find an
exception handler specified by the Python programmer.
(There are situations where a module can actually give a more detailed error
message by calling another PyErr_*
function, and in such cases it is
fine to do so. As a general rule, however, this is not necessary, and can cause
information about the cause of the error to be lost: most operations can fail
for a variety of reasons.)
To ignore an exception set by a function call that failed, the exception
condition must be cleared explicitly by calling PyErr_Clear()
. The only
time C code should call PyErr_Clear()
is if it doesn’t want to pass the
error on to the interpreter but wants to handle it completely by itself
(possibly by trying something else, or pretending nothing went wrong).
Every failing malloc()
call must be turned into an exception — the
direct caller of malloc()
(or realloc()
) must call
PyErr_NoMemory()
and return a failure indicator itself. All the
object-creating functions (for example, PyLong_FromLong()
) already do
this, so this note is only relevant to those who call malloc()
directly.
Also note that, with the important exception of PyArg_ParseTuple()
and
friends, functions that return an integer status usually return a positive value
or zero for success and -1
for failure, like Unix system calls.
Finally, be careful to clean up garbage (by making Py_XDECREF()
or
Py_DECREF()
calls for objects you have already created) when you return
an error indicator!
The choice of which exception to raise is entirely yours. There are predeclared
C objects corresponding to all built-in Python exceptions, such as
PyExc_ZeroDivisionError
, which you can use directly. Of course, you
should choose exceptions wisely — don’t use PyExc_TypeError
to mean
that a file couldn’t be opened (that should probably be PyExc_OSError
).
If something’s wrong with the argument list, the PyArg_ParseTuple()
function usually raises PyExc_TypeError
. If you have an argument whose
value must be in a particular range or must satisfy other conditions,
PyExc_ValueError
is appropriate.
You can also define a new exception that is unique to your module. The simplest way to do this is to declare a static global object variable at the beginning of the file:
static PyObject *SpamError = NULL;
and initialize it by calling PyErr_NewException()
in the module’s
Py_mod_exec
function (spam_module_exec()
):
SpamError = PyErr_NewException("spam.error", NULL, NULL);
Since SpamError
is a global variable, it will be overwritten every time
the module is reinitialized, when the Py_mod_exec
function is called.
For now, let’s avoid the issue: we will block repeated initialization by raising an
ImportError
:
static PyObject *SpamError = NULL;
static int
spam_module_exec(PyObject *m)
{
if (SpamError != NULL) {
PyErr_SetString(PyExc_ImportError,
"cannot initialize spam module more than once");
return -1;
}
SpamError = PyErr_NewException("spam.error", NULL, NULL);
if (PyModule_AddObjectRef(m, "SpamError", SpamError) < 0) {
return -1;
}
return 0;
}
static PyModuleDef_Slot spam_module_slots[] = {
{Py_mod_exec, spam_module_exec},
{0, NULL}
};
static struct PyModuleDef spam_module = {
.m_base = PyModuleDef_HEAD_INIT,
.m_name = "spam",
.m_size = 0, // non-negative
.m_slots = spam_module_slots,
};
PyMODINIT_FUNC
PyInit_spam(void)
{
return PyModuleDef_Init(&spam_module);
}
Note that the Python name for the exception object is spam.error
. The
PyErr_NewException()
function may create a class with the base class
being Exception
(unless another class is passed in instead of NULL
),
described in Built-in Exceptions.
Note also that the SpamError
variable retains a reference to the newly
created exception class; this is intentional! Since the exception could be
removed from the module by external code, an owned reference to the class is
needed to ensure that it will not be discarded, causing SpamError
to
become a dangling pointer. Should it become a dangling pointer, C code which
raises the exception could cause a core dump or other unintended side effects.
For now, the Py_DECREF()
call to remove this reference is missing.
Even when the Python interpreter shuts down, the global SpamError
variable will not be garbage-collected. It will “leak”.
We did, however, ensure that this will happen at most once per process.
We discuss the use of PyMODINIT_FUNC
as a function return type later in this
sample.
The spam.error
exception can be raised in your extension module using a
call to PyErr_SetString()
as shown below:
static PyObject *
spam_system(PyObject *self, PyObject *args)
{
const char *command;
int sts;
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
sts = system(command);
if (sts < 0) {
PyErr_SetString(SpamError, "System command failed");
return NULL;
}
return PyLong_FromLong(sts);
}
1.3. Back to the Example¶
Going back to our example function, you should now be able to understand this statement:
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
It returns NULL
(the error indicator for functions returning object pointers)
if an error is detected in the argument list, relying on the exception set by
PyArg_ParseTuple()
. Otherwise the string value of the argument has been
copied to the local variable command
. This is a pointer assignment and
you are not supposed to modify the string to which it points (so in Standard C,
the variable command
should properly be declared as const char
*command
).
The next statement is a call to the Unix function system()
, passing it
the string we just got from PyArg_ParseTuple()
:
sts = system(command);
Our spam.system()
function must return the value of sts
as a
Python object. This is done using the function PyLong_FromLong()
.
return PyLong_FromLong(sts);
In this case, it will return an integer object. (Yes, even integers are objects on the heap in Python!)
If you have a C function that returns no useful argument (a function returning
void), the corresponding Python function must return None
. You
need this idiom to do so (which is implemented by the Py_RETURN_NONE
macro):
Py_INCREF(Py_None);
return Py_None;
Py_None
is the C name for the special Python object None
. It is a
genuine Python object rather than a NULL
pointer, which means “error” in most
contexts, as we have seen.
1.4. The Module’s Method Table and Initialization Function¶
I promised to show how spam_system()
is called from Python programs.
First, we need to list its name and address in a “method table”:
static PyMethodDef spam_methods[] = {
...
{"system", spam_system, METH_VARARGS,
"Execute a shell command."},
...
{NULL, NULL, 0, NULL} /* Sentinel */
};
Note the third entry (METH_VARARGS
). This is a flag telling the interpreter
the calling convention to be used for the C function. It should normally always
be METH_VARARGS
or METH_VARARGS | METH_KEYWORDS
; a value of 0
means
that an obsolete variant of PyArg_ParseTuple()
is used.
When using only METH_VARARGS
, the function should expect the Python-level
parameters to be passed in as a tuple acceptable for parsing via
PyArg_ParseTuple()
; more information on this function is provided below.
The METH_KEYWORDS
bit may be set in the third field if keyword
arguments should be passed to the function. In this case, the C function should
accept a third PyObject *
parameter which will be a dictionary of keywords.
Use PyArg_ParseTupleAndKeywords()
to parse the arguments to such a
function.
The method table must be referenced in the module definition structure:
static struct PyModuleDef spam_module = {
...
.m_methods = spam_methods,
...
};
This structure, in turn, must be passed to the interpreter in the module’s
initialization function. The initialization function must be named
PyInit_name()
, where name is the name of the module, and should be the
only non-static
item defined in the module file:
PyMODINIT_FUNC
PyInit_spam(void)
{
return PyModuleDef_Init(&spam_module);
}
Note that PyMODINIT_FUNC
declares the function as PyObject *
return type,
declares any special linkage declarations required by the platform, and for C++
declares the function as extern "C"
.
PyInit_spam()
is called when each interpreter imports its module
spam
for the first time. (See below for comments about embedding Python.)
A pointer to the module definition must be returned via PyModuleDef_Init()
,
so that the import machinery can create the module and store it in sys.modules
.
When embedding Python, the PyInit_spam()
function is not called
automatically unless there’s an entry in the PyImport_Inittab
table.
To add the module to the initialization table, use PyImport_AppendInittab()
,
optionally followed by an import of the module:
#define PY_SSIZE_T_CLEAN
#include <Python.h>
int
main(int argc, char *argv[])
{
PyStatus status;
PyConfig config;
PyConfig_InitPythonConfig(&config);
/* Add a built-in module, before Py_Initialize */
if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {
fprintf(stderr, "Error: could not extend in-built modules table\n");
exit(1);
}
/* Pass argv[0] to the Python interpreter */
status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);
if (PyStatus_Exception(status)) {
goto exception;
}
/* Initialize the Python interpreter. Required.
If this step fails, it will be a fatal error. */
status = Py_InitializeFromConfig(&config);
if (PyStatus_Exception(status)) {
goto exception;
}
PyConfig_Clear(&config);
/* Optionally import the module; alternatively,
import can be deferred until the embedded script
imports it. */
PyObject *pmodule = PyImport_ImportModule("spam");
if (!pmodule) {
PyErr_Print();
fprintf(stderr, "Error: could not import module 'spam'\n");
}
// ... use Python C API here ...
return 0;
exception:
PyConfig_Clear(&config);
Py_ExitStatusException(status);
}
Note
If you declare a global variable or a local static one, the module may
experience unintended side-effects on re-initialisation, for example when
removing entries from sys.modules
or importing compiled modules into
multiple interpreters within a process
(or following a fork()
without an intervening exec()
).
If module state is not yet fully isolated,
authors should consider marking the module as having no support for subinterpreters
(via Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED
).
A more substantial example module is included in the Python source distribution
as Modules/xxlimited.c
. This file may be used as a template or simply
read as an example.
1.5. Compilation and Linkage¶
There are two more things to do before you can use your new extension: compiling and linking it with the Python system. If you use dynamic loading, the details may depend on the style of dynamic loading your system uses; see the chapters about building extension modules (chapter Building C and C++ Extensions) and additional information that pertains only to building on Windows (chapter Building C and C++ Extensions on Windows) for more information about this.
If you can’t use dynamic loading, or if you want to make your module a permanent
part of the Python interpreter, you will have to change the configuration setup
and rebuild the interpreter. Luckily, this is very simple on Unix: just place
your file (spammodule.c
for example) in the Modules/
directory
of an unpacked source distribution, add a line to the file
Modules/Setup.local
describing your file:
spam spammodule.o
and rebuild the interpreter by running make in the toplevel
directory. You can also run make in the Modules/
subdirectory, but then you must first rebuild Makefile
there by running
‘make Makefile’. (This is necessary each time you change the
Setup
file.)
If your module requires additional libraries to link with, these can be listed on the line in the configuration file as well, for instance:
spam spammodule.o -lX11
1.6. Calling Python Functions from C¶
So far we have concentrated on making C functions callable from Python. The reverse is also useful: calling Python functions from C. This is especially the case for libraries that support so-called “callback” functions. If a C interface makes use of callbacks, the equivalent Python often needs to provide a callback mechanism to the Python programmer; the implementation will require calling the Python callback functions from a C callback. Other uses are also imaginable.
Fortunately, the Python interpreter is easily called recursively, and there is a
standard interface to call a Python function. (I won’t dwell on how to call the
Python parser with a particular string as input — if you’re interested, have a
look at the implementation of the -c
command line option in
Modules/main.c
from the Python source code.)
Calling a Python function is easy. First, the Python program must somehow pass
you the Python function object. You should provide a function (or some other
interface) to do this. When this function is called, save a pointer to the
Python function object (be careful to Py_INCREF()
it!) in a global
variable — or wherever you see fit. For example, the following function might
be part of a module definition:
static PyObject *my_callback = NULL;
static PyObject *
my_set_callback(PyObject *dummy, PyObject *args)
{
PyObject *result = NULL;
PyObject *temp;
if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
if (!PyCallable_Check(temp)) {
PyErr_SetString(PyExc_TypeError, "parameter must be callable");
return NULL;
}
Py_XINCREF(temp); /* Add a reference to new callback */
Py_XDECREF(my_callback); /* Dispose of previous callback */
my_callback = temp; /* Remember new callback */
/* Boilerplate to return "None" */
Py_INCREF(Py_None);
result = Py_None;
}
return result;
}
This function must be registered with the interpreter using the
METH_VARARGS
flag; this is described in section The Module’s Method Table and Initialization Function. The
PyArg_ParseTuple()
function and its arguments are documented in section
Extracting Parameters in Extension Functions.
The macros Py_XINCREF()
and Py_XDECREF()
increment/decrement the
reference count of an object and are safe in the presence of NULL
pointers
(but note that temp will not be NULL
in this context). More info on them
in section Reference Counts.
Later, when it is time to call the function, you call the C function
PyObject_CallObject()
. This function has two arguments, both pointers to
arbitrary Python objects: the Python function, and the argument list. The
argument list must always be a tuple object, whose length is the number of
arguments. To call the Python function with no arguments, pass in NULL
, or
an empty tuple; to call it with one argument, pass a singleton tuple.
Py_BuildValue()
returns a tuple when its format string consists of zero
or more format codes between parentheses. For example:
int arg;
PyObject *arglist;
PyObject *result;
...
arg = 123;
...
/* Time to call the callback */
arglist = Py_BuildValue("(i)", arg);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);
PyObject_CallObject()
returns a Python object pointer: this is the return
value of the Python function. PyObject_CallObject()
is
“reference-count-neutral” with respect to its arguments. In the example a new
tuple was created to serve as the argument list, which is
Py_DECREF()
-ed immediately after the PyObject_CallObject()
call.
The return value of PyObject_CallObject()
is “new”: either it is a brand
new object, or it is an existing object whose reference count has been
incremented. So, unless you want to save it in a global variable, you should
somehow Py_DECREF()
the result, even (especially!) if you are not
interested in its value.
Before you do this, however, it is important to check that the return value
isn’t NULL
. If it is, the Python function terminated by raising an exception.
If the C code that called PyObject_CallObject()
is called from Python, it
should now return an error indication to its Python caller, so the interpreter
can print a stack trace, or the calling Python code can handle the exception.
If this is not possible or desirable, the exception should be cleared by calling
PyErr_Clear()
. For example:
if (result == NULL)
return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
Depending on the desired interface to the Python callback function, you may also
have to provide an argument list to PyObject_CallObject()
. In some cases
the argument list is also provided by the Python program, through the same
interface that specified the callback function. It can then be saved and used
in the same manner as the function object. In other cases, you may have to
construct a new tuple to pass as the argument list. The simplest way to do this
is to call Py_BuildValue()
. For example, if you want to pass an integral
event code, you might use the following code:
PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);
if (result == NULL)
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
Note the placement of Py_DECREF(arglist)
immediately after the call, before
the error check! Also note that strictly speaking this code is not complete:
Py_BuildValue()
may run out of memory, and this should be checked.
You may also call a function with keyword arguments by using
PyObject_Call()
, which supports arguments and keyword arguments. As in
the above example, we use Py_BuildValue()
to construct the dictionary.
PyObject *dict;
...
dict = Py_BuildValue("{s:i}", "name", val);
result = PyObject_Call(my_callback, NULL, dict);
Py_DECREF(dict);
if (result == NULL)
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
1.7. Extracting Parameters in Extension Functions¶
The PyArg_ParseTuple()
function is declared as follows:
int PyArg_ParseTuple(PyObject *arg, const char *format, ...);
The arg argument must be a tuple object containing an argument list passed from Python to a C function. The format argument must be a format string, whose syntax is explained in Parsing arguments and building values in the Python/C API Reference Manual. The remaining arguments must be addresses of variables whose type is determined by the format string.
Note that while PyArg_ParseTuple()
checks that the Python arguments have
the required types, it cannot check the validity of the addresses of C variables
passed to the call: if you make mistakes there, your code will probably crash or
at least overwrite random bits in memory. So be careful!
Note that any Python object references which are provided to the caller are borrowed references; do not decrement their reference count!
Some example calls:
#define PY_SSIZE_T_CLEAN
#include <Python.h>
int ok;
int i, j;
long k, l;
const char *s;
Py_ssize_t size;
ok = PyArg_ParseTuple(args, ""); /* No arguments */
/* Python call: f() */
ok = PyArg_ParseTuple(args, "s", &s); /* A string */
/* Possible Python call: f('whoops!') */
ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
/* Possible Python call: f(1, 2, 'three') */
ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
/* A pair of ints and a string, whose size is also returned */
/* Possible Python call: f((1, 2), 'three') */
{
const char *file;
const char *mode = "r";
int bufsize = 0;
ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
/* A string, and optionally another string and an integer */
/* Possible Python calls:
f('spam')
f('spam', 'w')
f('spam', 'wb', 100000) */
}
{
int left, top, right, bottom, h, v;
ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
&left, &top, &right, &bottom, &h, &v);
/* A rectangle and a point */
/* Possible Python call:
f(((0, 0), (400, 300)), (10, 10)) */
}
{
Py_complex c;
ok = PyArg_ParseTuple(args, "D:myfunction", &c);
/* a complex, also providing a function name for errors */
/* Possible Python call: myfunction(1+2j) */
}
1.8. Keyword Parameters for Extension Functions¶
The PyArg_ParseTupleAndKeywords()
function is declared as follows:
int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
const char *format, char * const *kwlist, ...);
The arg and format parameters are identical to those of the
PyArg_ParseTuple()
function. The kwdict parameter is the dictionary of
keywords received as the third parameter from the Python runtime. The kwlist
parameter is a NULL
-terminated list of strings which identify the parameters;
the names are matched with the type information from format from left to
right. On success, PyArg_ParseTupleAndKeywords()
returns true, otherwise
it returns false and raises an appropriate exception.
Note
Nested tuples cannot be parsed when using keyword arguments! Keyword parameters
passed in which are not present in the kwlist will cause TypeError
to
be raised.
Here is an example module which uses keywords, based on an example by Geoff Philbrick (philbrick@hks.com):
#define PY_SSIZE_T_CLEAN
#include <Python.h>
static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{
int voltage;
const char *state = "a stiff";
const char *action = "voom";
const char *type = "Norwegian Blue";
static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
&voltage, &state, &action, &type))
return NULL;
printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
action, voltage);
printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
Py_RETURN_NONE;
}
static PyMethodDef keywdarg_methods[] = {
/* The cast of the function is necessary since PyCFunction values
* only take two PyObject* parameters, and keywdarg_parrot() takes
* three.
*/
{"parrot", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
"Print a lovely skit to standard output."},
{NULL, NULL, 0, NULL} /* sentinel */
};
static struct PyModuleDef keywdarg_module = {
.m_base = PyModuleDef_HEAD_INIT,
.m_name = "keywdarg",
.m_size = 0,
.m_methods = keywdarg_methods,
};
PyMODINIT_FUNC
PyInit_keywdarg(void)
{
return PyModuleDef_Init(&keywdarg_module);
}
1.9. Building Arbitrary Values¶
This function is the counterpart to PyArg_ParseTuple()
. It is declared
as follows:
PyObject *Py_BuildValue(const char *format, ...);
It recognizes a set of format units similar to the ones recognized by
PyArg_ParseTuple()
, but the arguments (which are input to the function,
not output) must not be pointers, just values. It returns a new Python object,
suitable for returning from a C function called from Python.
One difference with PyArg_ParseTuple()
: while the latter requires its
first argument to be a tuple (since Python argument lists are always represented
as tuples internally), Py_BuildValue()
does not always build a tuple. It
builds a tuple only if its format string contains two or more format units. If
the format string is empty, it returns None
; if it contains exactly one
format unit, it returns whatever object is described by that format unit. To
force it to return a tuple of size 0 or one, parenthesize the format string.
Examples (to the left the call, to the right the resulting Python value):
Py_BuildValue("") None
Py_BuildValue("i", 123) 123
Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
Py_BuildValue("s", "hello") 'hello'
Py_BuildValue("y", "hello") b'hello'
Py_BuildValue("ss", "hello", "world") ('hello', 'world')
Py_BuildValue("s#", "hello", 4) 'hell'
Py_BuildValue("y#", "hello", 4) b'hell'
Py_BuildValue("()") ()
Py_BuildValue("(i)", 123) (123,)
Py_BuildValue("(ii)", 123, 456) (123, 456)
Py_BuildValue("(i,i)", 123, 456) (123, 456)
Py_BuildValue("[i,i]", 123, 456) [123, 456]
Py_BuildValue("{s:i,s:i}",
"abc", 123, "def", 456) {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
1.10. Reference Counts¶
In languages like C or C++, the programmer is responsible for dynamic allocation
and deallocation of memory on the heap. In C, this is done using the functions
malloc()
and free()
. In C++, the operators new
and
delete
are used with essentially the same meaning and we’ll restrict
the following discussion to the C case.
Every block of memory allocated with malloc()
should eventually be
returned to the pool of available memory by exactly one call to free()
.
It is important to call free()
at the right time. If a block’s address
is forgotten but free()
is not called for it, the memory it occupies
cannot be reused until the program terminates. This is called a memory
leak. On the other hand, if a program calls free()
for a block and then
continues to use the block, it creates a conflict with reuse of the block
through another malloc()
call. This is called using freed memory.
It has the same bad consequences as referencing uninitialized data — core
dumps, wrong results, mysterious crashes.
Common causes of memory leaks are unusual paths through the code. For instance, a function may allocate a block of memory, do some calculation, and then free the block again. Now a change in the requirements for the function may add a test to the calculation that detects an error condition and can return prematurely from the function. It’s easy to forget to free the allocated memory block when taking this premature exit, especially when it is added later to the code. Such leaks, once introduced, often go undetected for a long time: the error exit is taken only in a small fraction of all calls, and most modern machines have plenty of virtual memory, so the leak only becomes apparent in a long-running process that uses the leaking function frequently. Therefore, it’s important to prevent leaks from happening by having a coding convention or strategy that minimizes this kind of errors.
Since Python makes heavy use of malloc()
and free()
, it needs a
strategy to avoid memory leaks as well as the use of freed memory. The chosen
method is called reference counting. The principle is simple: every
object contains a counter, which is incremented when a reference to the object
is stored somewhere, and which is decremented when a reference to it is deleted.
When the counter reaches zero, the last reference to the object has been deleted
and the object is freed.
An alternative strategy is called automatic garbage collection.
(Sometimes, reference counting is also referred to as a garbage collection
strategy, hence my use of “automatic” to distinguish the two.) The big
advantage of automatic garbage collection is that the user doesn’t need to call
free()
explicitly. (Another claimed advantage is an improvement in speed
or memory usage — this is no hard fact however.) The disadvantage is that for
C, there is no truly portable automatic garbage collector, while reference
counting can be implemented portably (as long as the functions malloc()
and free()
are available — which the C Standard guarantees). Maybe some
day a sufficiently portable automatic garbage collector will be available for C.
Until then, we’ll have to live with reference counts.
While Python uses the traditional reference counting implementation, it also offers a cycle detector that works to detect reference cycles. This allows applications to not worry about creating direct or indirect circular references; these are the weakness of garbage collection implemented using only reference counting. Reference cycles consist of objects which contain (possibly indirect) references to themselves, so that each object in the cycle has a reference count which is non-zero. Typical reference counting implementations are not able to reclaim the memory belonging to any objects in a reference cycle, or referenced from the objects in the cycle, even though there are no further references to the cycle itself.
The cycle detector is able to detect garbage cycles and can reclaim them.
The gc
module exposes a way to run the detector (the
collect()
function), as well as configuration
interfaces and the ability to disable the detector at runtime.
1.10.1. Reference Counting in Python¶
There are two macros, Py_INCREF(x)
and Py_DECREF(x)
, which handle the
incrementing and decrementing of the reference count. Py_DECREF()
also
frees the object when the count reaches zero. For flexibility, it doesn’t call
free()
directly — rather, it makes a call through a function pointer in
the object’s type object. For this purpose (and others), every object
also contains a pointer to its type object.
The big question now remains: when to use Py_INCREF(x)
and Py_DECREF(x)
?
Let’s first introduce some terms. Nobody “owns” an object; however, you can
own a reference to an object. An object’s reference count is now defined
as the number of owned references to it. The owner of a reference is
responsible for calling Py_DECREF()
when the reference is no longer
needed. Ownership of a reference can be transferred. There are three ways to
dispose of an owned reference: pass it on, store it, or call Py_DECREF()
.
Forgetting to dispose of an owned reference creates a memory leak.
It is also possible to borrow [2] a reference to an object. The
borrower of a reference should not call Py_DECREF()
. The borrower must
not hold on to the object longer than the owner from which it was borrowed.
Using a borrowed reference after the owner has disposed of it risks using freed
memory and should be avoided completely [3].
The advantage of borrowing over owning a reference is that you don’t need to take care of disposing of the reference on all possible paths through the code — in other words, with a borrowed reference you don’t run the risk of leaking when a premature exit is taken. The disadvantage of borrowing over owning is that there are some subtle situations where in seemingly correct code a borrowed reference can be used after the owner from which it was borrowed has in fact disposed of it.
A borrowed reference can be changed into an owned reference by calling
Py_INCREF()
. This does not affect the status of the owner from which the
reference was borrowed — it creates a new owned reference, and gives full
owner responsibilities (the new owner must dispose of the reference properly, as
well as the previous owner).
1.10.2. Ownership Rules¶
Whenever an object reference is passed into or out of a function, it is part of the function’s interface specification whether ownership is transferred with the reference or not.
Most functions that return a reference to an object pass on ownership with the
reference. In particular, all functions whose function it is to create a new
object, such as PyLong_FromLong()
and Py_BuildValue()
, pass
ownership to the receiver. Even if the object is not actually new, you still
receive ownership of a new reference to that object. For instance,
PyLong_FromLong()
maintains a cache of popular values and can return a
reference to a cached item.
Many functions that extract objects from other objects also transfer ownership
with the reference, for instance PyObject_GetAttrString()
. The picture
is less clear, here, however, since a few common routines are exceptions:
PyTuple_GetItem()
, PyList_GetItem()
, PyDict_GetItem()
, and
PyDict_GetItemString()
all return references that you borrow from the
tuple, list or dictionary.
The function PyImport_AddModule()
also returns a borrowed reference, even
though it may actually create the object it returns: this is possible because an
owned reference to the object is stored in sys.modules
.
When you pass an object reference into another function, in general, the
function borrows the reference from you — if it needs to store it, it will use
Py_INCREF()
to become an independent owner. There are exactly two
important exceptions to this rule: PyTuple_SetItem()
and
PyList_SetItem()
. These functions take over ownership of the item passed
to them — even if they fail! (Note that PyDict_SetItem()
and friends
don’t take over ownership — they are “normal.”)
When a C function is called from Python, it borrows references to its arguments
from the caller. The caller owns a reference to the object, so the borrowed
reference’s lifetime is guaranteed until the function returns. Only when such a
borrowed reference must be stored or passed on, it must be turned into an owned
reference by calling Py_INCREF()
.
The object reference returned from a C function that is called from Python must be an owned reference — ownership is transferred from the function to its caller.
1.10.3. Thin Ice¶
There are a few situations where seemingly harmless use of a borrowed reference can lead to problems. These all have to do with implicit invocations of the interpreter, which can cause the owner of a reference to dispose of it.
The first and most important case to know about is using Py_DECREF()
on
an unrelated object while borrowing a reference to a list item. For instance:
void
bug(PyObject *list)
{
PyObject *item = PyList_GetItem(list, 0);
PyList_SetItem(list, 1, PyLong_FromLong(0L));
PyObject_Print(item, stdout, 0); /* BUG! */
}
This function first borrows a reference to list[0]
, then replaces
list[1]
with the value 0
, and finally prints the borrowed reference.
Looks harmless, right? But it’s not!
Let’s follow the control flow into PyList_SetItem()
. The list owns
references to all its items, so when item 1 is replaced, it has to dispose of
the original item 1. Now let’s suppose the original item 1 was an instance of a
user-defined class, and let’s further suppose that the class defined a
__del__()
method. If this class instance has a reference count of 1,
disposing of it will call its __del__()
method. Internally,
PyList_SetItem()
calls Py_DECREF()
on the replaced item,
which invokes replaced item’s corresponding
tp_dealloc
function. During
deallocation, tp_dealloc
calls
tp_finalize
, which is mapped to the
__del__()
method for class instances (see PEP 442). This entire
sequence happens synchronously within the PyList_SetItem()
call.
Since it is written in Python, the __del__()
method can execute arbitrary
Python code. Could it perhaps do something to invalidate the reference to
item
in bug()
? You bet! Assuming that the list passed into
bug()
is accessible to the __del__()
method, it could execute a
statement to the effect of del list[0]
, and assuming this was the last
reference to that object, it would free the memory associated with it, thereby
invalidating item
.
The solution, once you know the source of the problem, is easy: temporarily increment the reference count. The correct version of the function reads:
void
no_bug(PyObject *list)
{
PyObject *item = PyList_GetItem(list, 0);
Py_INCREF(item);
PyList_SetItem(list, 1, PyLong_FromLong(0L));
PyObject_Print(item, stdout, 0);
Py_DECREF(item);
}
This is a true story. An older version of Python contained variants of this bug
and someone spent a considerable amount of time in a C debugger to figure out
why his __del__()
methods would fail…
The second case of problems with a borrowed reference is a variant involving
threads. Normally, multiple threads in the Python interpreter can’t get in each
other’s way, because there is a global lock
protecting Python’s entire object space.
However, it is possible to temporarily release this lock using the macro
Py_BEGIN_ALLOW_THREADS
, and to re-acquire it using
Py_END_ALLOW_THREADS
. This is common around blocking I/O calls, to
let other threads use the processor while waiting for the I/O to complete.
Obviously, the following function has the same problem as the previous one:
void
bug(PyObject *list)
{
PyObject *item = PyList_GetItem(list, 0);
Py_BEGIN_ALLOW_THREADS
...some blocking I/O call...
Py_END_ALLOW_THREADS
PyObject_Print(item, stdout, 0); /* BUG! */
}
1.10.4. NULL Pointers¶
In general, functions that take object references as arguments do not expect you
to pass them NULL
pointers, and will dump core (or cause later core dumps) if
you do so. Functions that return object references generally return NULL
only
to indicate that an exception occurred. The reason for not testing for NULL
arguments is that functions often pass the objects they receive on to other
function — if each function were to test for NULL
, there would be a lot of
redundant tests and the code would run more slowly.
It is better to test for NULL
only at the “source:” when a pointer that may be
NULL
is received, for example, from malloc()
or from a function that
may raise an exception.
The macros Py_INCREF()
and Py_DECREF()
do not check for NULL
pointers — however, their variants Py_XINCREF()
and Py_XDECREF()
do.
The macros for checking for a particular object type (Pytype_Check()
) don’t
check for NULL
pointers — again, there is much code that calls several of
these in a row to test an object against various different expected types, and
this would generate redundant tests. There are no variants with NULL
checking.
The C function calling mechanism guarantees that the argument list passed to C
functions (args
in the examples) is never NULL
— in fact it guarantees
that it is always a tuple [4].
It is a severe error to ever let a NULL
pointer “escape” to the Python user.
1.11. Writing Extensions in C++¶
It is possible to write extension modules in C++. Some restrictions apply. If
the main program (the Python interpreter) is compiled and linked by the C
compiler, global or static objects with constructors cannot be used. This is
not a problem if the main program is linked by the C++ compiler. Functions that
will be called by the Python interpreter (in particular, module initialization
functions) have to be declared using extern "C"
. It is unnecessary to
enclose the Python header files in extern "C" {...}
— they use this form
already if the symbol __cplusplus
is defined (all recent C++ compilers
define this symbol).
1.12. Providing a C API for an Extension Module¶
Many extension modules just provide new functions and types to be used from Python, but sometimes the code in an extension module can be useful for other extension modules. For example, an extension module could implement a type “collection” which works like lists without order. Just like the standard Python list type has a C API which permits extension modules to create and manipulate lists, this new collection type should have a set of C functions for direct manipulation from other extension modules.
At first sight this seems easy: just write the functions (without declaring them
static
, of course), provide an appropriate header file, and document
the C API. And in fact this would work if all extension modules were always
linked statically with the Python interpreter. When modules are used as shared
libraries, however, the symbols defined in one module may not be visible to
another module. The details of visibility depend on the operating system; some
systems use one global namespace for the Python interpreter and all extension
modules (Windows, for example), whereas others require an explicit list of
imported symbols at module link time (AIX is one example), or offer a choice of
different strategies (most Unices). And even if symbols are globally visible,
the module whose functions one wishes to call might not have been loaded yet!
Portability therefore requires not to make any assumptions about symbol
visibility. This means that all symbols in extension modules should be declared
static
, except for the module’s initialization function, in order to
avoid name clashes with other extension modules (as discussed in section
The Module’s Method Table and Initialization Function). And it means that symbols that should be accessible from
other extension modules must be exported in a different way.
Python provides a special mechanism to pass C-level information (pointers) from one extension module to another one: Capsules. A Capsule is a Python data type which stores a pointer (void*). Capsules can only be created and accessed via their C API, but they can be passed around like any other Python object. In particular, they can be assigned to a name in an extension module’s namespace. Other extension modules can then import this module, retrieve the value of this name, and then retrieve the pointer from the Capsule.
There are many ways in which Capsules can be used to export the C API of an extension module. Each function could get its own Capsule, or all C API pointers could be stored in an array whose address is published in a Capsule. And the various tasks of storing and retrieving the pointers can be distributed in different ways between the module providing the code and the client modules.
Whichever method you choose, it’s important to name your Capsules properly.
The function PyCapsule_New()
takes a name parameter
(const char*); you’re permitted to pass in a NULL
name, but
we strongly encourage you to specify a name. Properly named Capsules provide
a degree of runtime type-safety; there is no feasible way to tell one unnamed
Capsule from another.
In particular, Capsules used to expose C APIs should be given a name following this convention:
modulename.attributename
The convenience function PyCapsule_Import()
makes it easy to
load a C API provided via a Capsule, but only if the Capsule’s name
matches this convention. This behavior gives C API users a high degree
of certainty that the Capsule they load contains the correct C API.
The following example demonstrates an approach that puts most of the burden on the writer of the exporting module, which is appropriate for commonly used library modules. It stores all C API pointers (just one in the example!) in an array of void pointers which becomes the value of a Capsule. The header file corresponding to the module provides a macro that takes care of importing the module and retrieving its C API pointers; client modules only have to call this macro before accessing the C API.
The exporting module is a modification of the spam
module from section
A Simple Example. The function spam.system()
does not call
the C library function system()
directly, but a function
PySpam_System()
, which would of course do something more complicated in
reality (such as adding “spam” to every command). This function
PySpam_System()
is also exported to other extension modules.
The function PySpam_System()
is a plain C function, declared
static
like everything else:
static int
PySpam_System(const char *command)
{
return system(command);
}
The function spam_system()
is modified in a trivial way:
static PyObject *
spam_system(PyObject *self, PyObject *args)
{
const char *command;
int sts;
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
sts = PySpam_System(command);
return PyLong_FromLong(sts);
}
In the beginning of the module, right after the line
#include <Python.h>
two more lines must be added:
#define SPAM_MODULE
#include "spammodule.h"
The #define
is used to tell the header file that it is being included in the
exporting module, not a client module. Finally, the module’s mod_exec
function must take care of initializing the C API pointer array:
static int
spam_module_exec(PyObject *m)
{
static void *PySpam_API[PySpam_API_pointers];
PyObject *c_api_object;
/* Initialize the C API pointer array */
PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
/* Create a Capsule containing the API pointer array's address */
c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);
if (PyModule_Add(m, "_C_API", c_api_object) < 0) {
return -1;
}
return 0;
}
Note that PySpam_API
is declared static
; otherwise the pointer
array would disappear when PyInit_spam()
terminates!
The bulk of the work is in the header file spammodule.h
, which looks
like this:
#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern "C" {
#endif
/* Header file for spammodule */
/* C API functions */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (const char *command)
/* Total number of C API pointers */
#define PySpam_API_pointers 1
#ifdef SPAM_MODULE
/* This section is used when compiling spammodule.c */
static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;
#else
/* This section is used in modules that use spammodule's API */
static void **PySpam_API;
#define PySpam_System \
(*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
/* Return -1 on error, 0 on success.
* PyCapsule_Import will set an exception if there's an error.
*/
static int
import_spam(void)
{
PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
return (PySpam_API != NULL) ? 0 : -1;
}
#endif
#ifdef __cplusplus
}
#endif
#endif /* !defined(Py_SPAMMODULE_H) */
All that a client module must do in order to have access to the function
PySpam_System()
is to call the function (or rather macro)
import_spam()
in its mod_exec
function:
static int
client_module_exec(PyObject *m)
{
if (import_spam() < 0) {
return -1;
}
/* additional initialization can happen here */
return 0;
}
The main disadvantage of this approach is that the file spammodule.h
is
rather complicated. However, the basic structure is the same for each function
that is exported, so it has to be learned only once.
Finally it should be mentioned that Capsules offer additional functionality,
which is especially useful for memory allocation and deallocation of the pointer
stored in a Capsule. The details are described in the Python/C API Reference
Manual in the section Capsules and in the implementation of Capsules (files
Include/pycapsule.h
and Objects/pycapsule.c
in the Python source
code distribution).
Footnotes


Using Python on macOS

5. Using Python on macOS¶
This document aims to give an overview of macOS-specific behavior you should know about to get started with Python on Mac computers. Python on a Mac running macOS is very similar to Python on other Unix-derived platforms, but there are some differences in installation and some features.
There are various ways to obtain and install Python for macOS. Pre-built versions of the most recent versions of Python are available from a number of distributors. Much of this document describes use of the Pythons provided by the CPython release team for download from the python.org website. See Alternative Distributions for some other options.
5.1. Using Python for macOS from python.org
¶
5.1.1. Installation steps¶
For current Python versions
(other than those in security
status), the release team produces a
Python for macOS installer package for each new release.
A list of available installers
is available here.
We recommend using the most recent supported Python version where possible.
Current installers provide a
universal2 binary build
of Python which runs natively on all Macs (Apple Silicon and Intel) that are
supported by a wide range of macOS versions,
currently typically from at least macOS 10.15 Catalina on.
The downloaded file is a standard macOS installer package file (.pkg
).
File integrity information (checksum, size, sigstore signature, etc) for each file is included
on the release download page. Installer packages and their contents are signed and notarized
with Python Software Foundation
Apple Developer ID certificates
to meet macOS Gatekeeper requirements.
For a default installation, double-click on the downloaded installer package file. This should launch the standard macOS Installer app and display the first of several installer windows steps.
Clicking on the Continue button brings up the Read Me for this installer.
Besides other important information, the Read Me documents which Python version is
going to be installed and on what versions of macOS it is supported. You may need
to scroll through to read the whole file. By default, this Read Me will also be
installed in /Applications/Python 3.14/
and available to read anytime.
Clicking on Continue proceeds to display the license for Python and for other included software. You will then need to Agree to the license terms before proceeding to the next step. This license file will also be installed and available to be read later.
After the license terms are accepted, the next step is the Installation Type display. For most uses, the standard set of installation operations is appropriate.
By pressing the Customize button, you can choose to omit or select certain package components of the installer. Click on each package name to see a description of what it installs. To also install support for the optional free-threaded feature, see Installing Free-threaded Binaries.
In either case, clicking Install will begin the install process by asking
permission to install new software. A macOS user name with Administrator
privilege
is needed as the installed Python will be available to all users of the Mac.
When the installation is complete, the Summary window will appear.
Double-click on the Install Certificates.command
icon or file in the /Applications/Python 3.14/
window to complete the
installation.
This will open a temporary Terminal shell window that will use the new Python to download and install SSL root certificates for its use.
If Successfully installed certifi
and update complete
appears
in the terminal window, the installation is complete.
Close this terminal window and the installer window.
A default install will include:
A
Python 3.14
folder in yourApplications
folder. In here you find IDLE, the development environment that is a standard part of official Python distributions; and Python Launcher, which handles double-clicking Python scripts from the macOS Finder.A framework
/Library/Frameworks/Python.framework
, which includes the Python executable and libraries. The installer adds this location to your shell path. To uninstall Python, you can remove these three things. Symlinks to the Python executable are placed in/usr/local/bin/
.
Note
Recent versions of macOS include a python3 command in /usr/bin/python3
that links to a usually older and incomplete version of Python provided by and for use by
the Apple development tools, Xcode or the Command Line Tools for Xcode.
You should never modify or attempt to delete this installation, as it is
Apple-controlled and is used by Apple-provided or third-party software. If
you choose to install a newer Python version from python.org
, you will have
two different but functional Python installations on your computer that
can co-exist. The default installer options should ensure that its python3
will be used instead of the system python3.
5.1.2. How to run a Python script¶
There are two ways to invoke the Python interpreter.
If you are familiar with using a Unix shell in a terminal
window, you can invoke python3.14
or python3
optionally
followed by one or more command line options (described in Command line and environment).
The Python tutorial also has a useful section on
using Python interactively from a shell.
You can also invoke the interpreter through an integrated development environment. IDLE — Python editor and shell is a basic editor and interpreter environment which is included with the standard distribution of Python. IDLE includes a Help menu that allows you to access Python documentation. If you are completely new to Python, you can read the tutorial introduction in that document.
There are many other editors and IDEs available, see Editors and IDEs for more information.
To run a Python script file from the terminal window, you can invoke the interpreter with the name of the script file:
python3.14
myscript.py
To run your script from the Finder, you can either:
Drag it to Python Launcher.
Select Python Launcher as the default application to open your script (or any
.py
script) through the Finder Info window and double-click it. Python Launcher has various preferences to control how your script is launched. Option-dragging allows you to change these for one invocation, or use itsPreferences
menu to change things globally.
Be aware that running the script directly from the macOS Finder might produce different results than when running from a terminal window as the script will not be run in the usual shell environment including any setting of environment variables in shell profiles. And, as with any other script or program, be certain of what you are about to run.
5.2. Alternative Distributions¶
Besides the standard python.org
for macOS installer, there are third-party
distributions for macOS that may include additional functionality.
Some popular distributions and their key features:
- ActivePython
Installer with multi-platform compatibility, documentation
- Anaconda
Popular scientific modules (such as numpy, scipy, and pandas) and the
conda
package manager.- Homebrew
Package manager for macOS including multiple versions of Python and many third-party Python-based packages (including numpy, scipy, and pandas).
- MacPorts
Another package manager for macOS including multiple versions of Python and many third-party Python-based packages. May include pre-built versions of Python and many packages for older versions of macOS.
Note that distributions might not include the latest versions of Python or other libraries, and are not maintained or supported by the core Python team.
5.3. Installing Additional Python Packages¶
Refer to the Python Packaging User Guide for more information.
5.4. GUI Programming¶
There are several options for building GUI applications on the Mac with Python.
The standard Python GUI toolkit is tkinter
, based on the cross-platform
Tk toolkit (https://www.tcl.tk). A macOS-native version of Tk is included with
the installer.
PyObjC is a Python binding to Apple’s Objective-C/Cocoa framework. Information on PyObjC is available from pyobjc.
A number of alternative macOS GUI toolkits are available including:
PySide: Official Python bindings to the Qt GUI toolkit.
PyQt: Alternative Python bindings to Qt.
Kivy: A cross-platform GUI toolkit that supports desktop and mobile platforms.
Toga: Part of the BeeWare Project; supports desktop, mobile, web and console apps.
wxPython: A cross-platform toolkit that supports desktop operating systems.
5.5. Advanced Topics¶
5.5.1. Installing Free-threaded Binaries¶
Added in version 3.13.
The python.org
Python for macOS
installer package can optionally install an additional build of
Python 3.14 that supports PEP 703, the free-threading feature
(running with the global interpreter lock disabled).
Check the release page on python.org
for possible updated information.
The free-threaded mode is working and continues to be improved, but there is some additional overhead in single-threaded workloads compared to the regular build. Additionally, third-party packages, in particular ones with an extension module, may not be ready for use in a free-threaded build, and will re-enable the GIL. Therefore, the support for free-threading is not installed by default. It is packaged as a separate install option, available by clicking the Customize button on the Installation Type step of the installer as described above.
If the box next to the Free-threaded Python package name is checked,
a separate PythonT.framework
will also be installed
alongside the normal Python.framework
in /Library/Frameworks
.
This configuration allows a free-threaded Python 3.14 build to co-exist
on your system with a traditional (GIL only) Python 3.14 build with
minimal risk while installing or testing. This installation layout may
change in future releases.
Known cautions and limitations:
The UNIX command-line tools package, which is selected by default, will install links in
/usr/local/bin
forpython3.14t
, the free-threaded interpreter, andpython3.14t-config
, a configuration utility which may be useful for package builders. Since/usr/local/bin
is typically included in your shellPATH
, in most cases no changes to yourPATH
environment variables should be needed to usepython3.14t
.For this release, the Shell profile updater package and the
Update Shell Profile.command
in/Applications/Python 3.14/
do not support the free-threaded package.The free-threaded build and the traditional build have separate search paths and separate
site-packages
directories so, by default, if you need a package available in both builds, it may need to be installed in both. The free-threaded package will install a separate instance of pip for use withpython3.14t
.To install a package using pip without a venv:
python3.14t -m pip install <package_name>
When working with multiple Python environments, it is usually safest and easiest to create and use virtual environments. This can avoid possible command name conflicts and confusion about which Python is in use:
python3.14t -m venv <venv_name>
then activate.
To run a free-threaded version of IDLE:
python3.14t -m idlelib
The interpreters in both builds respond to the same PYTHON environment variables which may have unexpected results, for example, if you have
PYTHONPATH
set in a shell profile. If necessary, there are command line options like-E
to ignore these environment variables.The free-threaded build links to the third-party shared libraries, such as
OpenSSL
andTk
, installed in the traditional framework. This means that both builds also share one set of trust certificates as installed by the Install Certificates.command script, thus it only needs to be run once.If you cannot depend on the link in
/usr/local/bin
pointing to thepython.org
free-threadedpython3.14t
(for example, if you want to install your own version there or some other distribution does), you can explicitly set your shellPATH
environment variable to include thePythonT
frameworkbin
directory:export PATH="/Library/Frameworks/PythonT.framework/Versions/3.14/bin":"$PATH"
The traditional framework installation by default does something similar, except for
Python.framework
. Be aware that having both frameworkbin
directories inPATH
can lead to confusion if there are duplicate names likepython3.14
in both; which one is actually used depends on the order they appear inPATH
. Thewhich python3.x
orwhich python3.xt
commands can show which path is being used. Using virtual environments can help avoid such ambiguities. Another option might be to create a shell alias to the desired interpreter, like:alias py3.14="/Library/Frameworks/Python.framework/Versions/3.14/bin/python3.14" alias py3.14t="/Library/Frameworks/PythonT.framework/Versions/3.14/bin/python3.14t"
5.5.2. Installing using the command line¶
If you want to use automation to install the python.org
installer package
(rather than by using the familiar macOS Installer GUI app),
the macOS command line installer utility lets you select non-default
options, too. If you are not familiar with installer, it can be
somewhat cryptic (see man installer for more information).
As an example, the following shell snippet shows one way to do it,
using the 3.14.0b2
release and selecting the free-threaded interpreter
option:
RELEASE="python-3.140b2-macos11.pkg" # download installer pkg curl -O https://www.python.org/ftp/python/3.14.0/${RELEASE} # create installer choicechanges to customize the install: # enable the PythonTFramework-3.14 package # while accepting the other defaults (install all other packages) cat > ./choicechanges.plist <<EOF <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <array> <dict> <key>attributeSetting</key> <integer>1</integer> <key>choiceAttribute</key> <string>selected</string> <key>choiceIdentifier</key> <string>org.python.Python.PythonTFramework-3.14</string> </dict> </array> </plist> EOF sudo installer -pkg ./${RELEASE} -applyChoiceChangesXML ./choicechanges.plist -target /
You can then test that both installer builds are now available with something like:
$ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled $ /usr/local/bin/python3.14t -VV Python 3.14.0b2 free-threading build (v3.14.0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)] $ # and the traditional interpreter $ /usr/local/bin/python3.14 -VV Python 3.14.0b2 (v3.14.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)] $ # test that they are also available without the prefix if /usr/local/bin is on $PATH $ python3.14t -VV Python 3.14.0b2 free-threading build (v3.14.0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)] $ python3.14 -VV Python 3.14.0b2 (v3.14.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
Note
Current python.org
installers only install to fixed locations like
/Library/Frameworks/
, /Applications
, and /usr/local/bin
.
You cannot use the installer -domain
option to install to
other locations.
5.5.3. Distributing Python Applications¶
A range of tools exist for converting your Python code into a standalone distributable application:
py2app: Supports creating macOS
.app
bundles from a Python project.Briefcase: Part of the BeeWare Project; a cross-platform packaging tool that supports creation of
.app
bundles on macOS, as well as managing signing and notarization.PyInstaller: A cross-platform packaging tool that creates a single file or folder as a distributable artifact.
5.5.4. App Store Compliance¶
Apps submitted for distribution through the macOS App Store must pass Apple’s app review process. This process includes a set of automated validation rules that inspect the submitted application bundle for problematic code.
The Python standard library contains some code that is known to violate these automated rules. While these violations appear to be false positives, Apple’s review rules cannot be challenged. Therefore, it is necessary to modify the Python standard library for an app to pass App Store review.
The Python source tree contains
a patch file that will remove
all code that is known to cause issues with the App Store review process. This
patch is applied automatically when CPython is configured with the
--with-app-store-compliance
option.
This patch is not normally required to use CPython on a Mac; nor is it required if you are distributing an app outside the macOS App Store. It is only required if you are using the macOS App Store as a distribution channel.
5.6. Other Resources¶
The python.org Help page has links to many useful resources. The Pythonmac-SIG mailing list is another support resource specifically for Python users and developers on the Mac.


Using Python on iOS

7. Using Python on iOS¶
- Authors:
Russell Keith-Magee (2024-03)
Python on iOS is unlike Python on desktop platforms. On a desktop platform, Python is generally installed as a system resource that can be used by any user of that computer. Users then interact with Python by running a python executable and entering commands at an interactive prompt, or by running a Python script.
On iOS, there is no concept of installing as a system resource. The only unit of software distribution is an “app”. There is also no console where you could run a python executable, or interact with a Python REPL.
As a result, the only way you can use Python on iOS is in embedded mode - that
is, by writing a native iOS application, and embedding a Python interpreter
using libPython
, and invoking Python code using the Python embedding
API. The full Python interpreter, the standard library, and all
your Python code is then packaged as a standalone bundle that can be
distributed via the iOS App Store.
If you’re looking to experiment for the first time with writing an iOS app in Python, projects such as BeeWare and Kivy will provide a much more approachable user experience. These projects manage the complexities associated with getting an iOS project running, so you only need to deal with the Python code itself.
7.1. Python at runtime on iOS¶
7.1.1. iOS version compatibility¶
The minimum supported iOS version is specified at compile time, using the
--host
option to configure
. By default, when compiled for iOS,
Python will be compiled with a minimum supported iOS version of 13.0. To use a
different minimum iOS version, provide the version number as part of the
--host
argument - for example,
--host=arm64-apple-ios15.4-simulator
would compile an ARM64 simulator build
with a deployment target of 15.4.
7.1.2. Platform identification¶
When executing on iOS, sys.platform
will report as ios
. This value will
be returned on an iPhone or iPad, regardless of whether the app is running on
the simulator or a physical device.
Information about the specific runtime environment, including the iOS version,
device model, and whether the device is a simulator, can be obtained using
platform.ios_ver()
. platform.system()
will report iOS
or
iPadOS
, depending on the device.
os.uname()
reports kernel-level details; it will report a name of
Darwin
.
7.1.3. Standard library availability¶
The Python standard library has some notable omissions and restrictions on iOS. See the API availability guide for iOS for details.
7.1.4. Binary extension modules¶
One notable difference about iOS as a platform is that App Store distribution imposes hard requirements on the packaging of an application. One of these requirements governs how binary extension modules are distributed.
The iOS App Store requires that all binary modules in an iOS app must be
dynamic libraries, contained in a framework with appropriate metadata, stored
in the Frameworks
folder of the packaged app. There can be only a single
binary per framework, and there can be no executable binary material outside
the Frameworks
folder.
This conflicts with the usual Python approach for distributing binaries, which
allows a binary extension module to be loaded from any location on
sys.path
. To ensure compliance with App Store policies, an iOS project must
post-process any Python packages, converting .so
binary modules into
individual standalone frameworks with appropriate metadata and signing. For
details on how to perform this post-processing, see the guide for adding
Python to your project.
To help Python discover binaries in their new location, the original .so
file on sys.path
is replaced with a .fwork
file. This file is a text
file containing the location of the framework binary, relative to the app
bundle. To allow the framework to resolve back to the original location, the
framework must contain a .origin
file that contains the location of the
.fwork
file, relative to the app bundle.
For example, consider the case of an import from foo.bar import _whiz
,
where _whiz
is implemented with the binary module
sources/foo/bar/_whiz.abi3.so
, with sources
being the location
registered on sys.path
, relative to the application bundle. This module
must be distributed as Frameworks/foo.bar._whiz.framework/foo.bar._whiz
(creating the framework name from the full import path of the module), with an
Info.plist
file in the .framework
directory identifying the binary as a
framework. The foo.bar._whiz
module would be represented in the original
location with a sources/foo/bar/_whiz.abi3.fwork
marker file, containing
the path Frameworks/foo.bar._whiz/foo.bar._whiz
. The framework would also
contain Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin
, containing
the path to the .fwork
file.
When running on iOS, the Python interpreter will install an
AppleFrameworkLoader
that is able to read and
import .fwork
files. Once imported, the __file__
attribute of the
binary module will report as the location of the .fwork
file. However, the
ModuleSpec
for the loaded module will report the
origin
as the location of the binary in the framework folder.
7.1.5. Compiler stub binaries¶
Xcode doesn’t expose explicit compilers for iOS; instead, it uses an xcrun
script that resolves to a full compiler path (e.g., xcrun --sdk iphoneos
clang
to get the clang
for an iPhone device). However, using this script
poses two problems:
The output of
xcrun
includes paths that are machine specific, resulting in a sysconfig module that cannot be shared between users; andIt results in
CC
/CPP
/LD
/AR
definitions that include spaces. There is a lot of C ecosystem tooling that assumes that you can split a command line at the first space to get the path to the compiler executable; this isn’t the case when usingxcrun
.
To avoid these problems, Python provided stubs for these tools. These stubs are
shell script wrappers around the underingly xcrun
tools, distributed in a
bin
folder distributed alongside the compiled iOS framework. These scripts
are relocatable, and will always resolve to the appropriate local system paths.
By including these scripts in the bin folder that accompanies a framework, the
contents of the sysconfig
module becomes useful for end-users to compile
their own modules. When compiling third-party Python modules for iOS, you
should ensure these stub binaries are on your path.
7.2. Installing Python on iOS¶
7.2.1. Tools for building iOS apps¶
Building for iOS requires the use of Apple’s Xcode tooling. It is strongly recommended that you use the most recent stable release of Xcode. This will require the use of the most (or second-most) recently released macOS version, as Apple does not maintain Xcode for older macOS versions. The Xcode Command Line Tools are not sufficient for iOS development; you need a full Xcode install.
If you want to run your code on the iOS simulator, you’ll also need to install an iOS Simulator Platform. You should be prompted to select an iOS Simulator Platform when you first run Xcode. Alternatively, you can add an iOS Simulator Platform by selecting from the Platforms tab of the Xcode Settings panel.
7.2.2. Adding Python to an iOS project¶
Python can be added to any iOS project, using either Swift or Objective C. The following examples will use Objective C; if you are using Swift, you may find a library like PythonKit to be helpful.
To add Python to an iOS Xcode project:
Build or obtain a Python
XCFramework
. See the instructions in Apple/iOS/README.md (in the CPython source distribution) for details on how to build a PythonXCFramework
. At a minimum, you will need a build that supportsarm64-apple-ios
, plus one of eitherarm64-apple-ios-simulator
orx86_64-apple-ios-simulator
.Drag the
XCframework
into your iOS project. In the following instructions, we’ll assume you’ve dropped theXCframework
into the root of your project; however, you can use any other location that you want by adjusting paths as needed.Add your application code as a folder in your Xcode project. In the following instructions, we’ll assume that your user code is in a folder named
app
in the root of your project; you can use any other location by adjusting paths as needed. Ensure that this folder is associated with your app target.Select the app target by selecting the root node of your Xcode project, then the target name in the sidebar that appears.
In the “General” settings, under “Frameworks, Libraries and Embedded Content”, add
Python.xcframework
, with “Embed & Sign” selected.In the “Build Settings” tab, modify the following:
Build Options
User Script Sandboxing: No
Enable Testability: Yes
Search Paths
Framework Search Paths:
$(PROJECT_DIR)
Header Search Paths:
"$(BUILT_PRODUCTS_DIR)/Python.framework/Headers"
Apple Clang - Warnings - All languages
Quoted Include In Framework Header: No
Add a build step that processes the Python standard library, and your own Python binary dependencies. In the “Build Phases” tab, add a new “Run Script” build step before the “Embed Frameworks” step, but after the “Copy Bundle Resources” step. Name the step “Process Python libraries”, disable the “Based on dependency analysis” checkbox, and set the script content to:
set -e source $PROJECT_DIR/Python.xcframework/build/build_utils.sh install_python Python.xcframework app
If you have placed your XCframework somewhere other than the root of your project, modify the path to the first argument.
Add Objective C code to initialize and use a Python interpreter in embedded mode. You should ensure that:
UTF-8 mode (
PyPreConfig.utf8_mode
) is enabled;Buffered stdio (
PyConfig.buffered_stdio
) is disabled;Writing bytecode (
PyConfig.write_bytecode
) is disabled;Signal handlers (
PyConfig.install_signal_handlers
) are enabled;System logging (
PyConfig.use_system_logger
) is enabled (optional, but strongly recommended; this is enabled by default);PYTHONHOME
for the interpreter is configured to point at thepython
subfolder of your app’s bundle; andThe
PYTHONPATH
for the interpreter includes:the
python/lib/python3.X
subfolder of your app’s bundle,the
python/lib/python3.X/lib-dynload
subfolder of your app’s bundle, andthe
app
subfolder of your app’s bundle
Your app’s bundle location can be determined using
[[NSBundle mainBundle] resourcePath]
.
Steps 7 and 8 of these instructions assume that you have a single folder of
pure Python application code, named app
. If you have third-party binary
modules in your app, some additional steps will be required:
You need to ensure that any folders containing third-party binaries are either associated with the app target, or are explicitly copied as part of step 7. Step 7 should also purge any binaries that are not appropriate for the platform a specific build is targeting (i.e., delete any device binaries if you’re building an app targeting the simulator).
If you’re using a separate folder for third-party packages, ensure that folder is added to the end of the call to
install_python
in step 7, and as part of thePYTHONPATH
configuration in step 8.If any of the folders that contain third-party packages will contain
.pth
files, you should add that folder as a site directory (usingsite.addsitedir()
), rather than adding toPYTHONPATH
orsys.path
directly.
7.2.3. Testing a Python package¶
The CPython source tree contains a testbed project that is used to run the CPython test suite on the iOS simulator. This testbed can also be used as a testbed project for running your Python library’s test suite on iOS.
After building or obtaining an iOS XCFramework (see Apple/iOS/README.md
for details), create a clone of the Python iOS testbed project. If you used the
Apple
build script to build the XCframework, you can run:
$ python cross-build/iOS/testbed clone --app <path/to/module1> --app <path/to/module2> app-testbed
Or, if you’ve sourced your own XCframework, by running:
$ python Apple/testbed clone --platform iOS --framework <path/to/Python.xcframework> --app <path/to/module1> --app <path/to/module2> app-testbed
Any folders specified with the --app
flag will be copied into the cloned
testbed project. The resulting testbed will be created in the app-testbed
folder. In this example, the module1
and module2
would be importable
modules at runtime. If your project has additional dependencies, they can be
installed into the app-testbed/Testbed/app_packages
folder (using pip
install --target app-testbed/Testbed/app_packages
or similar).
You can then use the app-testbed
folder to run the test suite for your app,
For example, if module1.tests
was the entry point to your test suite, you
could run:
$ python app-testbed run -- module1.tests
This is the equivalent of running python -m module1.tests
on a desktop
Python build. Any arguments after the --
will be passed to the testbed as
if they were arguments to python -m
on a desktop machine.
You can also open the testbed project in Xcode by running:
$ open app-testbed/iOSTestbed.xcodeproj
This will allow you to use the full Xcode suite of tools for debugging.
The arguments used to run the test suite are defined as part of the test plan. To modify the test plan, select the test plan node of the project tree (it should be the first child of the root node), and select the “Configurations” tab. Modify the “Arguments Passed On Launch” value to change the testing arguments.
The test plan also disables parallel testing, and specifies the use of the
Testbed.lldbinit
file for providing configuration of the debugger. The
default debugger configuration disables automatic breakpoints on the
SIGINT
, SIGUSR1
, SIGUSR2
, and SIGXFSZ
signals.
7.3. App Store Compliance¶
The only mechanism for distributing apps to third-party iOS devices is to submit the app to the iOS App Store; apps submitted for distribution must pass Apple’s app review process. This process includes a set of automated validation rules that inspect the submitted application bundle for problematic code. There are some steps that must be taken to ensure that your app will be able to pass these validation steps.
7.3.1. Incompatible code in the standard library¶
The Python standard library contains some code that is known to violate these automated rules. While these violations appear to be false positives, Apple’s review rules cannot be challenged; so, it is necessary to modify the Python standard library for an app to pass App Store review.
The Python source tree contains a patch file that will remove all code that is known to cause issues with the App Store review process. This patch is applied automatically when building for iOS.
7.3.2. Privacy manifests¶
In April 2025, Apple introduced a requirement for certain third-party
libraries to provide a Privacy Manifest.
As a result, if you have a binary module that uses one of the affected
libraries, you must provide an .xcprivacy
file for that library.
OpenSSL is one library affected by this requirement, but there are others.
If you produce a binary module named mymodule.so
, and use you the Xcode
build script described in step 7 above, you can place a mymodule.xcprivacy
file next to mymodule.so
, and the privacy manifest will be installed into
the required location when the binary module is converted into a framework.


: Managing MIME Content

email.contentmanager
: Managing MIME Content¶
Source code: Lib/email/contentmanager.py
Added in version 3.6: [1]
- class email.contentmanager.ContentManager¶
Base class for content managers. Provides the standard registry mechanisms to register converters between MIME content and other representations, as well as the
get_content
andset_content
dispatch methods.- get_content(msg, *args, **kw)¶
Look up a handler function based on the
mimetype
of msg (see next paragraph), call it, passing through all arguments, and return the result of the call. The expectation is that the handler will extract the payload from msg and return an object that encodes information about the extracted data.To find the handler, look for the following keys in the registry, stopping with the first one found:
the string representing the full MIME type (
maintype/subtype
)the string representing the
maintype
the empty string
If none of these keys produce a handler, raise a
KeyError
for the full MIME type.
- set_content(msg, obj, *args, **kw)¶
If the
maintype
ismultipart
, raise aTypeError
; otherwise look up a handler function based on the type of obj (see next paragraph), callclear_content()
on the msg, and call the handler function, passing through all arguments. The expectation is that the handler will transform and store obj into msg, possibly making other changes to msg as well, such as adding various MIME headers to encode information needed to interpret the stored data.To find the handler, obtain the type of obj (
typ = type(obj)
), and look for the following keys in the registry, stopping with the first one found:the type itself (
typ
)the type’s fully qualified name (
typ.__module__ + '.' + typ.__qualname__
).the type’s
qualname
(typ.__qualname__
)the type’s
name
(typ.__name__
).
If none of the above match, repeat all of the checks above for each of the types in the MRO (
typ.__mro__
). Finally, if no other key yields a handler, check for a handler for the keyNone
. If there is no handler forNone
, raise aKeyError
for the fully qualified name of the type.Also add a MIME-Version header if one is not present (see also
MIMEPart
).
- add_get_handler(key, handler)¶
Record the function handler as the handler for key. For the possible values of key, see
get_content()
.
- add_set_handler(typekey, handler)¶
Record handler as the function to call when an object of a type matching typekey is passed to
set_content()
. For the possible values of typekey, seeset_content()
.
Content Manager Instances¶
Currently the email package provides only one concrete content manager,
raw_data_manager
, although more may be added in the future.
raw_data_manager
is the
content_manager
provided by
EmailPolicy
and its derivatives.
- email.contentmanager.raw_data_manager¶
This content manager provides only a minimum interface beyond that provided by
Message
itself: it deals only with text, raw byte strings, andMessage
objects. Nevertheless, it provides significant advantages compared to the base API:get_content
on a text part will return a unicode string without the application needing to manually decode it,set_content
provides a rich set of options for controlling the headers added to a part and controlling the content transfer encoding, and it enables the use of the variousadd_
methods, thereby simplifying the creation of multipart messages.- email.contentmanager.get_content(msg, errors='replace')¶
Return the payload of the part as either a string (for
text
parts), anEmailMessage
object (formessage/rfc822
parts), or abytes
object (for all other non-multipart types). Raise aKeyError
if called on amultipart
. If the part is atext
part and errors is specified, use it as the error handler when decoding the payload to unicode. The default error handler isreplace
.
- email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)¶
- email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
- email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
Add headers and payload to msg:
Add a Content-Type header with a
maintype/subtype
value.For
str
, set the MIMEmaintype
totext
, and set the subtype to subtype if it is specified, orplain
if it is not.For
bytes
, use the specified maintype and subtype, or raise aTypeError
if they are not specified.For
EmailMessage
objects, set the maintype tomessage
, and set the subtype to subtype if it is specified orrfc822
if it is not. If subtype ispartial
, raise an error (bytes
objects must be used to constructmessage/partial
parts).
If charset is provided (which is valid only for
str
), encode the string to bytes using the specified character set. The default isutf-8
. If the specified charset is a known alias for a standard MIME charset name, use the standard charset instead.If cte is set, encode the payload using the specified content transfer encoding, and set the Content-Transfer-Encoding header to that value. Possible values for cte are
quoted-printable
,base64
,7bit
,8bit
, andbinary
. If the input cannot be encoded in the specified encoding (for example, specifying a cte of7bit
for an input that contains non-ASCII values), raise aValueError
.For
str
objects, if cte is not set use heuristics to determine the most compact encoding. Prior to encoding,str.splitlines()
is used to normalize all line boundaries, ensuring that each line of the payload is terminated by the current policy’slinesep
property (even if the original string did not end with one).For
bytes
objects, cte is taken to be base64 if not set, and the aforementioned newline translation is not performed.For
EmailMessage
, per RFC 2046, raise an error if a cte ofquoted-printable
orbase64
is requested for subtyperfc822
, and for any cte other than7bit
for subtypeexternal-body
. Formessage/rfc822
, use8bit
if cte is not specified. For all other values of subtype, use7bit
.
Note
A cte of
binary
does not actually work correctly yet. TheEmailMessage
object as modified byset_content
is correct, butBytesGenerator
does not serialize it correctly.If disposition is set, use it as the value of the Content-Disposition header. If not specified, and filename is specified, add the header with the value
attachment
. If disposition is not specified and filename is also not specified, do not add the header. The only valid values for disposition areattachment
andinline
.If filename is specified, use it as the value of the
filename
parameter of the Content-Disposition header.If cid is specified, add a Content-ID header with cid as its value.
If params is specified, iterate its
items
method and use the resulting(key, value)
pairs to set additional parameters on the Content-Type header.If headers is specified and is a list of strings of the form
headername: headervalue
or a list ofheader
objects (distinguished from strings by having aname
attribute), add the headers to msg.
Footnotes


5. Building C and C++ Extensions on Windows¶
This chapter briefly explains how to create a Windows extension module for Python using Microsoft Visual C++, and follows with more detailed background information on how it works. The explanatory material is useful for both the Windows programmer learning to build Python extensions and the Unix programmer interested in producing software which can be successfully built on both Unix and Windows.
Module authors are encouraged to use the distutils approach for building extension modules, instead of the one described in this section. You will still need the C compiler that was used to build Python; typically Microsoft Visual C++.
Note
This chapter mentions a number of filenames that include an encoded Python
version number. These filenames are represented with the version number shown
as XY
; in practice, 'X'
will be the major version number and 'Y'
will be the minor version number of the Python release you’re working with. For
example, if you are using Python 2.2.1, XY
will actually be 22
.
5.1. A Cookbook Approach¶
There are two approaches to building extension modules on Windows, just as there
are on Unix: use the setuptools
package to control the build process, or
do things manually. The setuptools approach works well for most extensions;
documentation on using setuptools
to build and package extension modules
is available in Building C and C++ Extensions with setuptools. If you find you really need to do
things manually, it may be instructive to study the project file for the
winsound standard library module.
5.2. Differences Between Unix and Windows¶
Unix and Windows use completely different paradigms for run-time loading of code. Before you try to build a module that can be dynamically loaded, be aware of how your system works.
In Unix, a shared object (.so
) file contains code to be used by the
program, and also the names of functions and data that it expects to find in the
program. When the file is joined to the program, all references to those
functions and data in the file’s code are changed to point to the actual
locations in the program where the functions and data are placed in memory.
This is basically a link operation.
In Windows, a dynamic-link library (.dll
) file has no dangling
references. Instead, an access to functions or data goes through a lookup
table. So the DLL code does not have to be fixed up at runtime to refer to the
program’s memory; instead, the code already uses the DLL’s lookup table, and the
lookup table is modified at runtime to point to the functions and data.
In Unix, there is only one type of library file (.a
) which contains code
from several object files (.o
). During the link step to create a shared
object file (.so
), the linker may find that it doesn’t know where an
identifier is defined. The linker will look for it in the object files in the
libraries; if it finds it, it will include all the code from that object file.
In Windows, there are two types of library, a static library and an import
library (both called .lib
). A static library is like a Unix .a
file; it contains code to be included as necessary. An import library is
basically used only to reassure the linker that a certain identifier is legal,
and will be present in the program when the DLL is loaded. So the linker uses
the information from the import library to build the lookup table for using
identifiers that are not included in the DLL. When an application or a DLL is
linked, an import library may be generated, which will need to be used for all
future DLLs that depend on the symbols in the application or DLL.
Suppose you are building two dynamic-load modules, B and C, which should share
another block of code A. On Unix, you would not pass A.a
to the
linker for B.so
and C.so
; that would cause it to be included
twice, so that B and C would each have their own copy. In Windows, building
A.dll
will also build A.lib
. You do pass A.lib
to the
linker for B and C. A.lib
does not contain code; it just contains
information which will be used at runtime to access A’s code.
In Windows, using an import library is sort of like using import spam
; it
gives you access to spam’s names, but does not create a separate copy. On Unix,
linking with a library is more like from spam import *
; it does create a
separate copy.
-
Py_NO_LINK_LIB¶
Turn off the implicit,
#pragma
-based linkage with the Python library, performed inside CPython header files.Added in version 3.14.
5.3. Using DLLs in Practice¶
Windows Python is built in Microsoft Visual C++; using other compilers may or may not work. The rest of this section is MSVC++ specific.
When creating DLLs in Windows, you can use the CPython library in two ways:
By default, inclusion of
PC/pyconfig.h
directly or viaPython.h
triggers an implicit, configure-aware link with the library. The header file choosespythonXY_d.lib
for Debug,pythonXY.lib
for Release, andpythonX.lib
for Release with the Limited API enabled.To build two DLLs, spam and ni (which uses C functions found in spam), you could use these commands:
cl /LD /I/python/include spam.c cl /LD /I/python/include ni.c spam.lib
The first command created three files:
spam.obj
,spam.dll
andspam.lib
.Spam.dll
does not contain any Python functions (such asPyArg_ParseTuple()
), but it does know how to find the Python code thanks to the implicitly linkedpythonXY.lib
.The second command created
ni.dll
(and.obj
and.lib
), which knows how to find the necessary functions from spam, and also from the Python executable.Manually by defining
Py_NO_LINK_LIB
macro before includingPython.h
. You must passpythonXY.lib
to the linker.To build two DLLs, spam and ni (which uses C functions found in spam), you could use these commands:
cl /LD /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib cl /LD /DPy_NO_LINK_LIB /I/python/include ni.c spam.lib ../libs/pythonXY.lib
The first command created three files:
spam.obj
,spam.dll
andspam.lib
.Spam.dll
does not contain any Python functions (such asPyArg_ParseTuple()
), but it does know how to find the Python code thanks topythonXY.lib
.The second command created
ni.dll
(and.obj
and.lib
), which knows how to find the necessary functions from spam, and also from the Python executable.
Not every identifier is exported to the lookup table. If you want any other
modules (including Python) to be able to see your identifiers, you have to say
_declspec(dllexport)
, as in void _declspec(dllexport) initspam(void)
or
PyObject _declspec(dllexport) *NiGetSpamData(void)
.
Developer Studio will throw in a lot of import libraries that you do not really
need, adding about 100K to your executable. To get rid of them, use the Project
Settings dialog, Link tab, to specify ignore default libraries. Add the
correct msvcrtxx.lib
to the list of libraries.


— 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.