1. Rozszerzanie języka pytonowskiego za pomocą C lub C++

Jest całkiem łatwo dodać nowe wbudowane moduły do języka pytonowskiego, jeśli znasz się na programowaniu w C. Takie moduły rozszerzające - z ang. - extension modules mogą zrobić dwie rzeczy których nie da się zrobić bezpośrednio w języku pytonowskim: mogą wypełnić nowe wbudowane typy przedmiotów i mogą odwołać się do zadań bibliotecznych C i odwołań systemowych.

Aby wspierać rozszerzenia, sprzęg programowania języka pytonowskiego API - z ang. (Application Programmers Interface) określa zbiór zadań, makropoleceń i zmiennych które dostarczają dostęp do większości aspektów systemu czasu-wykonania języka pytonowskiego. Sprzęg programowania języka pytonowskiego jest załączany w źródłowym pliku C przez załączenie pliku nagłówkowego "Python.h".

Kompilacja rozszerzających modułów zależy od jego zamierzonego użycia zarówno jak też od ustawień twojego systemu; szczegóły są dane w późniejszych rozdziałach.

Informacja

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. Prosty przykład

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")

Zaczynając od stworzenia pliku spammodule.c (Historycznie, jeśli moduł był nazwany spam, plik C zawierający jego wypełnienie jest nazywany spammodule.c; jeśli nazwa modułu jest bardzo długa, jak np spammify, nazwa modułu może być po prostu spammify.c.)

The first two lines of our file can be:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

Które pociąga sprzęg programowania języka pytonowskiego (możesz dodać komentarz opisujący powód modułu i uwagi praw autorskich jeśli wolisz).

Informacja

Odkąd język pytonowski może definiować pewne definicje preprocesora, które wpływają na pliki nagłówkowe na niektórych systemach, musisz załączyć plik Python.h zanim jakiekolwiek standardowe nagłówki zostaną załączone.

It is recommended to always define PY_SSIZE_T_CLEAN before including Python.h. See Wydobywanie parametrów w zadaniach rozszerzających 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. For convenience, and since they are used extensively by the Python interpreter, "Python.h" includes a few standard header files: <stdio.h>, <string.h>, <errno.h>, and <stdlib.h>. If the latter header file does not exist on your system, it declares the functions malloc(), free() and realloc() directly.

Następną rzeczą którą dodajemy do naszego pliku modułu jest zadanie C które będzie wzywane gdy wyrażenie języka pytonowskiego spam.system(string) zostanie obliczone (zobaczymy niedługo, jak to się kończy wywołaniem):

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);
}

Istnieje prosta zamiana nazw z listy parametrów w języku pytonowskim (dla przykładu, pojedyncze wyrażenie "ls -l") do parametrów przekazanych do zadania C. Zadanie C zawsze ma dwa parametry, dla wygody nazywane sam - z ang. - self i args.

Parametr sam - z ang. - self - wskazuje na przedmiot modułu dla zadań na poziomie-modułu; dla sposobu postępowania wskazywałby na przykład przedmiotu.

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: Błędy i Wyjątki

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 a NULL pointer). Exceptions are stored in a static global variable inside the interpreter; if this variable is NULL no exception has occurred. A second global variable stores the „associated value” of the exception (the second argument to raise). A third variable contains the stack traceback in case the error originated in Python code. These three variables are the C equivalents of the result in Python of sys.exc_info() (see the section on module sys in the Python Library Reference). It is important to know about them to understand how errors are passed around.

Sprzęg języka pytonowskiego określa pewien zestaw zadań do ustawiania różnych rodzajów wyjątków.

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_IOError). 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.

Możesz też określić nowy wyjątek który jest niepowtarzalny dla twojego modułu. Dla tego, zwykle deklarujesz przedmiot statycznej zmiennej na początku pliku:

static PyObject *SpamError;

and initialize it in your module’s initialization function (PyInit_spam()) with an exception object:

PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    Py_XINCREF(SpamError);
    if (PyModule_AddObject(m, "error", SpamError) < 0) {
        Py_XDECREF(SpamError);
        Py_CLEAR(SpamError);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

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.

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. Z powrotem do Przykładu

Wracając do naszej przykładowego zadania, powinieneś już być w stanie zrozumieć to wyrażenie:

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);

W tym przypadku, zwróci przedmiot liczby całkowitej (Tak, nawet liczby całkowite są przedmiotami na stercie w języku pytonowskim!)

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. Zadanie zainicjowania i tabela sposobów postępowania modułu.

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 SpamMethods[] = {
    ...
    {"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.

Tabela sposobów postępowania musi być określona w strukturze definicji modułu:

static struct PyModuleDef spammodule = {
    PyModuleDef_HEAD_INIT,
    "spam",   /* name of module */
    spam_doc, /* module documentation, may be NULL */
    -1,       /* size of per-interpreter state of the module,
                 or -1 if the module keeps state in global variables. */
    SpamMethods
};

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 PyModule_Create(&spammodule);
}

Zauważ że PyMODINIT_FUNC deklaruje zadanie jako zwrotny typ PyObject *, deklaruje wszelkie specjalne deklaracje połączeń wymagane przez maszynę/środowisko, i dla C++ deklaruje zadanie jako extern "C".

When the Python program imports module spam for the first time, PyInit_spam() is called. (See below for comments about embedding Python.) It calls PyModule_Create(), which returns a module object, and inserts built-in function objects into the newly created module based upon the table (an array of PyMethodDef structures) found in the module definition. PyModule_Create() returns a pointer to the module object that it creates. It may abort with a fatal error for certain errors, or return NULL if the module could not be initialized satisfactorily. The init function must return the module object to its caller, so that it then gets inserted into 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:

int
main(int argc, char *argv[])
{
    wchar_t *program = Py_DecodeLocale(argv[0], NULL);
    if (program == NULL) {
        fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
        exit(1);
    }

    /* 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 */
    Py_SetProgramName(program);

    /* Initialize the Python interpreter.  Required.
       If this step fails, it will be a fatal error. */
    Py_Initialize();

    /* 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");
    }

    ...

    PyMem_RawFree(program);
    return 0;
}

Informacja

Removing entries from sys.modules or importing compiled modules into multiple interpreters within a process (or following a fork() without an intervening exec()) can create problems for some extension modules. Extension module authors should exercise caution when initializing internal data structures.

Bardziej konkretny przykład modułu jest załączony w dystrybucji źródeł języka pytonowskiego jako plik Modules/xxmodule.c. Ten plik może być użyty jako wzór lub po prostu czytany jako przykład.

Informacja

Unlike our spam example, xxmodule uses multi-phase initialization (new in Python 3.5), where a PyModuleDef structure is returned from PyInit_spam, and creation of the module is left to the import machinery. For details on multi-phase initialization, see PEP 489.

1.5. Kompilacja i łączenie

Są jeszcze dwie rzeczy które trzeba zrobić zanim będzie można użyć nowego rozszerzenia: skompilowanie go i podłączenie z systemem Pythona. Jeśli używasz dynamicznego ładowania, szczegóły mogą zależeć od stylu dynamicznego ładowania którego twój system używa; zobacz rozdział o budowaniu rozszerzających modułów (rozdział Building C and C++ Extensions) i dodatkowe informacje które odnoszą się tylko do budowania w Windows (rozdział Tworzenie rozszerzeń C i C++ w Windowsie) po więcej informacji na ten temat.

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

i przebuduj program interpretujący przez uruchomienie programu make w katalogu głównym instalacji. Możesz także uruchomić program make w podkatalogu Modules/, ale wtedy musisz najpierw przebudować plik Makefile tam przez uruchomienie programu make Makefile». To jest konieczne za każdym razem gdy zmieniasz plik Setup.)

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. Wywoływanie zadań języka pytonowskiego z C

Jak do tej pory koncentrowaliśmy się na uczynieniu zadań C możliwymi do wywołania z poziomu języka pytonowskiego. Odwrotna sytuacja jest także użyteczna: wywoływanie zadań języka pytonowskiego z poziomu języka C. To w szczególności odnosi się do bibliotek które wspierają tak zwane zadania „callback” wstecznie wywołujące. Jeśli sprzęg C używa zadań wstecznie wywołujących, odpowiednik języka pytonowskiego często potrzebuje dostarczyć mechanizm wstecznego wywołania dla programisty języka pytonowskiego; wypełnienie będzie potrzebowało wzywać zadania wywołania wstecznego z poziomu wstecznego C. Inne przypadki są także możliwe do wyobrażenia.

Szczęśliwie, program interpretujący polecenia języka pytonowskiego jest łatwo wywoływany rekursywnie i istnieje standardowy sprzęg aby wywołać zadanie języka pytonowskiego. (Nie będę rozpisywał się o tym jak wywołać czytnik języka pytonowskiego z konkretnym ciągiem znaków na wejściu — jeśli jesteś zainteresowany, spójrz na wypełnienie opcji -c wiersza polecenia w Modules/main.c z kodu źródłowego języka pytonowskiego.)

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 Zadanie zainicjowania i tabela sposobów postępowania modułu.. The PyArg_ParseTuple() function and its arguments are documented in section Wydobywanie parametrów w zadaniach rozszerzających.

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 Liczby odniesień.

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. Wydobywanie parametrów w zadaniach rozszerzających

The PyArg_ParseTuple() function is declared as follows:

int PyArg_ParseTuple(PyObject *arg, const char *format, ...);

Parametr arg musi być przedmiotem - krotką zawierającym listę parametrów z języka pytonowskiego dla zadania C. Parametr format musi być ciągiem formatu, którego składnia jest wyjaśniona w Pobieranie kolejnych rzeczy podanych na wejściu i konstruowanie wartości. w podręczniku użytkownika API Python/C. Pozostałe parametry muszą być adresami zmiennych których rodzaj jest określony przez ciąg formatujący.

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!

Zwróć uwagę, że każde odniesienie do obiektu Pythona które jest dostarczone do wywołującego funkcję jest odniesieniem pożyczonym; nie zmniejsza ich liczby odniesień!

Pewne przykładowe wywołania:

#define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
#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. Parametry kluczowe dla zadań rozszerzających

The PyArg_ParseTupleAndKeywords() function is declared as follows:

int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                const char *format, char *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.

Informacja

Zagnieżdźone krotki nie mogą być wczytane gdy używane są parametry słów kluczowych! Parametry słów kluczowych przekazane do zadania które nie są obecne na liście kwlist spowodują że wyjątek TypeError zostanie zgłoszony.

Tu jest przykładowy moduł który używa słów kluczowych, oparty na przykładzie Geoffa Philbricka (philbrick@hks.com):

#define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
#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 keywdargmodule = {
    PyModuleDef_HEAD_INIT,
    "keywdarg",
    NULL,
    -1,
    keywdarg_methods
};

PyMODINIT_FUNC
PyInit_keywdarg(void)
{
    return PyModule_Create(&keywdargmodule);
}

1.9. Budowanie Dowolnych Wartości

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. Liczby odniesień

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 re-use 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.

Typowymi przyczynami wycieków pamięci są nietypowe ścieżki przejścia przez kod. Dla przykładu, zadanie może zaalokować blok pamięci, wykonać pewne obliczenia, a potem uwolnić ten blok jeszcze raz. Teraz zmiana w wymaganiach dla zadania może dodać test do obliczenia który wykrywa warunek błędu i może wrócić wcześniej z zadania. Łatwo jest zapomnieć aby uwolnić zaalokowany blok pamięci podczas wybierania tej drogi wcześniejszego zakończenia, szczególnie gdy jest dodawane później do kodu. Takie przecieki, gdy raz wprowadzone, często uchodzą niewykryte przez długi czas: błędne wyjście jest wybierane tylko w małym wycinku wszystkich wywołań, i większość nowoczesnych maszyn ma mnóstwo wirtualnej pamięci, tak że wyciek staje się widoczny tylko w długo działającym procesie który używa cieknącego zadania często. Dlatego też, jest to ważne aby zapobiegać wyciekom przed ich nastąpieniem, przez powzięcie konwencji kodowania lub strategii która minimalizuje ten rodzaj błędu.

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.

Podczas gdy język pytonowski używa tradycyjnego wypełnienia zliczania odniesień, on także oferuje wykrywanie cykli, które pracuje aby wykrywać cykliczne odniesienia. To pozwala aplikacjom nie martwić się o tworzenie bezpośrednich lub pośrednich cyklicznych odniesień; to są słabości wypełnienia zbiórki śmieci opartego jedynie na zliczaniu odniesień. Cykle odniesień składają się z przedmiotów które zawierają (możliwie pośrednio) odniesienia do samych siebie, tak że każdy przedmiot w cyklu ma liczbę odniesień która jest nie-zerowa. Typowe wypełnienia zliczające odniesienia nie są w stanie przejąć z powrotem pamięci należącej do któregokolwiek z przedmiotów w cyklu odniesień, ani do której odnosi się któryś z przedmiotów w cyklu, nawet jeśli nie ma więcej odniesień do cyklu samego w sobie.

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. The cycle detector is considered an optional component; though it is included by default, it can be disabled at build time using the --without-cycle-gc option to the configure script on Unix platforms (including Mac OS X). If the cycle detector is disabled in this way, the gc module will not be available.

1.10.1. Zliczanie odniesień w języku pytonowskim

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.

Zaletą pożyczania ponad posiadaniem odniesienia jest to że nie potrzebujesz zaprzątać swojej uwagi pozbyciem się odniesienia na wszystkich możliwych ścieżkach przejścia przez kod — innymi słowy, z pożyczonym odniesieniem nie musisz ryzykować wycieku gdy nastąpi przedwczesne wyjście z programu. Wadą pożyczania ponad posiadaniem jest to że istnieją pewne szczególne sytuacje gdzie w wydawałoby się poprawnym kodzie pożyczone odniesienie może być użyte po tym jak właściciel od którego zostało ono pożyczone faktycznie pozbył się go.

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. Zasady właścicielskie

Zawsze gdy odniesienie do przedmiotu jest przekazywane do lub z zadania, jest częścią specyfiki sprzęgu zadania to czy własność jest przekazywana z odniesieniem czy też nie.

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().

Odniesienie do przedmiotu zwrócone z zadania C które jest wywołane z poziomu języka pytonowskiego musi być posiadanym odniesieniem — prawo własności jest przekazywane z zadania do wywołującego to ostatnie.

1.10.3. Cienki lód

Istnieje kilka sytuacji gdzie wydawałoby się nieszkodliwe użycie pożyczonych odniesień może prowadzić do kłopotów. Wszystkie one mają do czynienia z niejawnymi wezwaniami programu interpretującego polecenia języka pytonowskiego, które mogą powodować że właściciel odniesienia pozbędzie się go.

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! */
}

To zadanie najpierw pożycza odniesienie do list[0], potem zamienia list[1] na wartość ``0, i ostatecznie wypisuje pożyczone odniesienie. Wydaje się nieszkodliwe, czyż nie? A jednak jest!

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.

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.

Rozwiązanie, gdy znasz już źródło problemu, jest łatwe: tymczasowo zwiększyć ilość odniesień. Poprawna wersja zadania równa jest:

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);
}

To jest prawdziwa historia. Starsza wersja języka pytonowskiego zawierała warianty tego błędu i ktoś spędził zdrowy kawałek czasu w debugerze C aby dowiedzieć się czemu jegosposoby postępowania __del__() zawodziły…

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. Puste wskaźniki (NULL)

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. Pisanie rozszerzeń w C++

Jest możliwe pisanie modułów rozszerzających w C++. Niektóre ograniczenia obowiązują. Jeśli główny program (program interpretujący polecenia języka pytonowskiego) jest kompilowany i łączony przez kompilator języka C, nadrzędne lub statyczne przedmioty z konstruktorami nie mogą być używane. To nie jest problemem jeśli główny program jest łączony przez kompilator C++. Zadania które będą wezwane przez program interpretujący polecenia języka pytonowskiego (w szczególności, zadania inicjujące moduł) muszą być deklarowane używając extern "C". Nie jest to konieczne aby zawierać plik nagłówkowy języka pytonowskiego w extern "C" {...} — one używają już tej formy jeśli symbol __cplusplus jest zdefiniowany (wszystkie niedawne kompilatory C++ definiują ten symbol).

1.12. Dostarczanie sprzęgu programowania aplikacji (API) języka C dla modułu rozszerzającego

Wiele modułów rozszerzających po prostu dostarcza nowych zadań i typów aby były używane z języka pytonowskiego, ale czasami kod w module rozszerzającym może być użyteczny dla innych rozszerzających modułów. Na przykład, moduł rozszerzający mógłby wypełniać typ „kolekcji” który działałby jak lista bez wprowadzonego porządku. Tak jak standardowy typ listy języka pytonowskiego posiada sprzęg programowania aplikacji języka C, który pozwala modułom rozszerzającym tworzenie i zmianę list, ten nowy typ kolekcji powinien mieć zbiór zadań C dla bezpośrednich zmian z innych modułów rozszerzających.

Na pierwszy rzut oka to wydaje się proste: napisać zadania (bez deklarowania ich jako statycznych, oczywiście), dostarczyć odpowiedni plik nagłówkowy, i udokumentować sprzęg programowania aplikacji (API) C. I faktycznie to mogłoby zadziałać jeśli wszystkie rozszerzające moduły byłyby zawsze złączone statycznie z programem interpretującym polecenia języka pytonowskiego. Gdy moduły są używane jako współdzielone biblioteki, jednakże, symbole zdefiniowane w jednym module mogą nie być widoczne dla innych modułów. Szczegóły widoczności zależą od systemu operacyjnego; niektóre systemy używają jednej nadrzędnej przestrzeni nazw dla programu interpretującego polecenia języka pytonowskiego i wszystkich modułów rozszerzających (dla Windows, na przykład), podczas gdy inne wymagają jawnej listy importowanych symboli w czasie łączenia modułów (AIX jest jednym z przykładów), lub oferują wybór różnych strategii (większość Unix-ów). I nawet jeśli symbole są widoczne nadrzędnie, moduł którego zadania ktoś chciałby uruchomić mogły nie zostać jeszcze załadowane!

Przenośność zatem wymaga aby nie czynić żadnych założeń o widoczności symboli. To oznacza, że wszystkie symbole w rozszerzających modułach powinny być deklarowane jako statyczne, z wyjątkiem zadania zainicjowania modułu, w celu ominięcia wojen nazw z innymi modułami rozszerzającymi (jak określono w rozdziale Zadanie zainicjowania i tabela sposobów postępowania modułu.). I to oznacza, że symbole, które powinny być dostępne z innych rozszerzających modułów muszą być eksportowane w różny sposób.

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.

Istnieje wiele sposobów w jakie kapsuły mogą być używane aby wystawiać na zewnątrz sprzęgi programowania aplikacji (API) języka C dla danego modułu rozszerzającego. Każde zadanie mogłoby dostać swoją własną kapsułę, lub wszystkie wskaźniki sprzęgu programowania aplikacji (API) języka C mogłyby być zachowane w tabeli której adres byłby opublikowany w kapsule. A różne zadania zachowania i odbioru wskaźników mogłyby być rozprowadzone na różne sposoby pomiędzy moduły dostarczające kod i moduły odbierające.

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.

W szczególności, kapsułom używanym do wystawiania sprzęgów programowania aplikacji języka C ( - z ang. - API) powinna być nadana nazwa stosująca się do następującej konwencji:

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 Prosty przykład. 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);
}

Na początku modułu, zaraz za linią

#include <Python.h>

muszą być dodane dwie linie:

#define SPAM_MODULE
#include "spammodule.h"

#define jest używane aby przekazać plikowi nagłówkowemu że jest załączany w module wystawianym na zewnątrz, nie w module któremu wszystko służy. Ostatecznie zadanie inicjowania musi zadbać o zainicjowanie tabeli wskaźników sprzęgu programowania aplikacji języka C.

PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;
    static void *PySpam_API[PySpam_API_pointers];
    PyObject *c_api_object;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    /* 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_AddObject(m, "_C_API", c_api_object) < 0) {
        Py_XDECREF(c_api_object);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Zauważ, że PySpam_API jest zadeklarowane statycznie; w innym przypadku tabela wskaźników zniknęłaby gdy PyInit_spam() się zakończy!

Większa część pracy jest wykonywana w pliku nagłówkowym spammodule.h, który wygląda następująco:

#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 initialization function:

PyMODINIT_FUNC
PyInit_client(void)
{
    PyObject *m;

    m = PyModule_Create(&clientmodule);
    if (m == NULL)
        return NULL;
    if (import_spam() < 0)
        return NULL;
    /* additional initialization can happen here */
    return m;
}

Główną wadą tego podejścia jest to, że plik spammodule.h jest raczej skomplikowany. Jednakże podstawowa struktura jest taka sama dla każdego zadania które jest wystawiane na zewnątrz więc trzeba się tego uczyć tylko raz.

Ostatecznie warto wspomnieć, że kapsuły dają dodatkowe możliwości działania, które są szczególnie użyteczne dla umieszczania i zabierania miejsca w pamięci wskaźników zachowywanych w kapsule. Szczegóły są opisane w podręczniku użytkownika API Python/C w rozdziale Capsules i w wypełnieniu programowym kapsuł (plików Include/pycapsule.h i Objects/pycapsule.c w dystrybucji źródłowej kodu Pythona).

Przypisy

1

sprzęg dla tego zadania już istnieje w standardowym module os — został on wybrany jako prosty i przejrzysty przykład.

2

Metafora „pożyczania” odniesienia nie jest do końca poprawna: właściciel wciąż ma kopię odniesienia.

3

Sprawdzanie że liczba odniesień jest przynajmniej 1 nie działa — liczba odniesień sama w sobie może być w uwolnionej pamięci i dlatego może być ponownie użyta dla innego przedmiotu!

4

Te gwarancje nie są w mocy gdy używasz „starego” sposobu wywoływania — to jest wciąż znajdowane w dużej części istniejącego kodu.