Ce document est relatif à une vieille version de Python qui n'est plus soutenue. Mettez à jour votre version et lisez Bienvenue sur la documentation de la version stable actuelle de Python.

# Portage des modules d'extension vers Python 3

auteur

  Benjamin Peterson

Résumé

Changer l'API C n'était pas l'un des objectifs de Python 3, cependant les nombreux changements au niveau Python ont rendu impossible de garder l'API de Python 2 comme elle était. Certains changements tels que l'unification de `int()` et `long()` sont plus apparents au niveau C. Ce document s'efforce de documenter les incompatibilités et la façon dont elles peuvent être contournées.

## Compilation conditionnelle

La façon la plus simple de compiler seulement une section de code pour Python 3 est de vérifier si `PY_MAJOR_VERSION` est supérieur ou égal à 3. :

    #if PY_MAJOR_VERSION >= 3
    #define IS_PY3K
    #endif

Les fonctions manquantes dans l'API peuvent être remplacées par des alias à leurs équivalents dans des blocs conditionnels.

## Modifications apportées aux API des objets

Python 3 a fusionné certains types avec des fonctions identiques tout en séparant de façon propre, d'autres.

### Unification de str et unicode

Le type `str()` de Python 3 est l'équivalent de `unicode()` sous Python 2 ; Les fonctions C sont appelées `PyUnicode_*` pour les deux versions. L'ancien type de chaîne de caractères de 8 bits est devenue `bytes()`, avec des fonctions C nommées `PyBytes_*`. Python 2.6 et toutes les versions supérieures fournissent un en-tête de compatibilité, `bytesobject.h`, faisant correspondre les noms `PyBytes` aux `PyString`. Pour une meilleure compatibilité avec Python 3, `PyUnicode` doit être utilisé seulement pour des données textuelles et `PyBytes` pour des données binaires. Il est important de noter que `PyBytes` et `PyUnicode` en Python 3 ne sont pas remplaçables contrairement à `PyString` et `PyUnicode` dans Python 2. L'exemple suivant montre l'utilisation optimale de `PyUnicode`, `PyString`, et `PyBytes`.

    #include "stdlib.h"
    #include "Python.h"
    #include "bytesobject.h"

    /* text example */
    static PyObject *
    say_hello(PyObject *self, PyObject *args) {
        PyObject *name, *result;

        if (!PyArg_ParseTuple(args, "U:say_hello", &name))
            return NULL;

        result = PyUnicode_FromFormat("Hello, %S!", name);
        return result;
    }

    /* just a forward */
    static char * do_encode(PyObject *);

    /* bytes example */
    static PyObject *
    encode_object(PyObject *self, PyObject *args) {
        char *encoded;
        PyObject *result, *myobj;

        if (!PyArg_ParseTuple(args, "O:encode_object", &myobj))
            return NULL;

        encoded = do_encode(myobj);
        if (encoded == NULL)
            return NULL;
        result = PyBytes_FromString(encoded);
        free(encoded);
        return result;
    }

### Unification de long et int

Python 3 n'a qu'un type d'entier, `int()`. Mais il correspond au type `long()` de Python 2 — le type `int()` utilisé dans Python 2 a été supprimé. Dans l'API C, les fonctions `PyInt_*` sont remplacées par leurs équivalents `PyLong_*`.

## Initialisation et état du module

Python 3 a remanié son système d'initialisation des modules d'extension (Voir PEP 3121.). Au lieu de stocker les états de module dans les variables globales, les états doivent être stockés dans une structure spécifique à l'interpréteur. Créer des modules qui ont un fonctionnement correct en Python 2 et Python 3 est délicat. L'exemple suivant montre comment.

    #include "Python.h"

    struct module_state {
        PyObject *error;
    };

    #if PY_MAJOR_VERSION >= 3
    #define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))
    #else
    #define GETSTATE(m) (&_state)
    static struct module_state _state;
    #endif

    static PyObject *
    error_out(PyObject *m) {
        struct module_state *st = GETSTATE(m);
        PyErr_SetString(st->error, "something bad happened");
        return NULL;
    }

    static PyMethodDef myextension_methods[] = {
        {"error_out", (PyCFunction)error_out, METH_NOARGS, NULL},
        {NULL, NULL}
    };

    #if PY_MAJOR_VERSION >= 3

    static int myextension_traverse(PyObject *m, visitproc visit, void *arg) {
        Py_VISIT(GETSTATE(m)->error);
        return 0;
    }

    static int myextension_clear(PyObject *m) {
        Py_CLEAR(GETSTATE(m)->error);
        return 0;
    }

    static struct PyModuleDef moduledef = {
            PyModuleDef_HEAD_INIT,
            "myextension",
            NULL,
            sizeof(struct module_state),
            myextension_methods,
            NULL,
            myextension_traverse,
            myextension_clear,
            NULL
    };

    #define INITERROR return NULL

    PyMODINIT_FUNC
    PyInit_myextension(void)

    #else
    #define INITERROR return

    void
    initmyextension(void)
    #endif
    {
    #if PY_MAJOR_VERSION >= 3
        PyObject *module = PyModule_Create(&moduledef);
    #else
        PyObject *module = Py_InitModule("myextension", myextension_methods);
    #endif

        if (module == NULL)
            INITERROR;
        struct module_state *st = GETSTATE(module);

        st->error = PyErr_NewException("myextension.Error", NULL, NULL);
        if (st->error == NULL) {
            Py_DECREF(module);
            INITERROR;
        }

    #if PY_MAJOR_VERSION >= 3
        return module;
    #endif
    }

## CObject remplacé par Capsule

L'objet `Capsule` a été introduit dans Python 3.1 et 2.7 pour remplacer `CObject`. Le type `CObject` était utile, mais son API posait des soucis : elle ne permettait pas la distinction entre les objets C valides, ce qui permettait aux objets C assortis incorrectement de planter l'interpréteur, et certaines des API s'appuyaient sur un comportement indéfini en C. (Pour plus de détails sur la logique de Capsules, veuillez consulter bpo-5630).

Si vous utilisez actuellement CObjects et que vous voulez migrer vers la version 3.1 ou plus récente, vous devrez passer à Capsules. `CObject` est déprécié dans 3.1 et 2.7 et est supprimé dans Python 3.2. Si vous ne gérez que les versions 2.7, ou 3.1 et supérieures, vous pouvez simplement passer à `Capsule`. Si vous avez besoin de gérer Python 3.0, ou des versions de Python antérieures à 2.7, vous devez gérer CObjects et Capsules. (Notez que Python 3.0 n'est plus maintenu, et qu'il n'est pas recommandé pour une utilisation en production).

L'exemple suivant d'en-tête de fichier `capsulethunk.h` peut résoudre le problème. Il suffit d'écrire votre code dans l'API `Capsule` et d'inclure ce fichier d'en-tête après `Python.h`. Votre code utilisera automatiquement Capsules dans les versions de Python avec Capsules, et passera à CObjects lorsque les Capsules ne sont pas disponibles.

`capsulethunk.h` reproduit le fonctionnement de Capsules en utilisant CObjects. Cependant, `CObject` ne permet pas de stocker le "nom" de la capsule. Les objets simulés `Capsule` créés par `capsulethunk.h` se comportent légèrement différemment des véritables Capsules. Ainsi :

> - Le paramètre name passé à `PyCapsule_New()` est ignoré.

> - Le paramètre name passé à `PyCapsule_IsValid()` et `PyCapsule_GetPointer()` est ignoré et il n'y a pas de vérification d'erreur du nom.

> - `PyCapsule_GetName()` renvoie toujours un NULL.

> - `PyCapsule_SetName()` lève toujours une exception et renvoie un échec. Note : Puisqu'il n'y a aucun moyen de stocker un nom dans un CObject, l'échec verbeux de `PyCapsule_SetName()` a été jugé préférable à un échec non-verbeux dans ce cas. Si cela ne vous convenait pas, vous pouvez modifier votre copie locale selon vos besoins.

Vous pouvez trouver `capsulethunk.h` dans la distribution source de Python comme Doc/includes/capsulethunk.h. Nous l'incluons ici pour votre confort :

    #ifndef __CAPSULETHUNK_H
    #define __CAPSULETHUNK_H

    #if (    (PY_VERSION_HEX <  0x02070000) \
         || ((PY_VERSION_HEX >= 0x03000000) \
          && (PY_VERSION_HEX <  0x03010000)) )

    #define __PyCapsule_GetField(capsule, field, default_value) \
        ( PyCapsule_CheckExact(capsule) \
            ? (((PyCObject *)capsule)->field) \
            : (default_value) \
        ) \

    #define __PyCapsule_SetField(capsule, field, value) \
        ( PyCapsule_CheckExact(capsule) \
            ? (((PyCObject *)capsule)->field = value), 1 \
            : 0 \
        ) \

    #define PyCapsule_Type PyCObject_Type

    #define PyCapsule_CheckExact(capsule) (PyCObject_Check(capsule))
    #define PyCapsule_IsValid(capsule, name) (PyCObject_Check(capsule))

    #define PyCapsule_New(pointer, name, destructor) \
        (PyCObject_FromVoidPtr(pointer, destructor))

    #define PyCapsule_GetPointer(capsule, name) \
        (PyCObject_AsVoidPtr(capsule))

    /* Don't call PyCObject_SetPointer here, it fails if there's a destructor */
    #define PyCapsule_SetPointer(capsule, pointer) \
        __PyCapsule_SetField(capsule, cobject, pointer)

    #define PyCapsule_GetDestructor(capsule) \
        __PyCapsule_GetField(capsule, destructor)

    #define PyCapsule_SetDestructor(capsule, dtor) \
        __PyCapsule_SetField(capsule, destructor, dtor)

    /*
     * Sorry, there's simply no place
     * to store a Capsule "name" in a CObject.
     */
    #define PyCapsule_GetName(capsule) NULL

    static int
    PyCapsule_SetName(PyObject *capsule, const char *unused)
    {
        unused = unused;
        PyErr_SetString(PyExc_NotImplementedError,
            "can't use PyCapsule_SetName with CObjects");
        return 1;
    }

    #define PyCapsule_GetContext(capsule) \
        __PyCapsule_GetField(capsule, descr)

    #define PyCapsule_SetContext(capsule, context) \
        __PyCapsule_SetField(capsule, descr, context)

    static void *
    PyCapsule_Import(const char *name, int no_block)
    {
        PyObject *object = NULL;
        void *return_value = NULL;
        char *trace;
        size_t name_length = (strlen(name) + 1) * sizeof(char);
        char *name_dup = (char *)PyMem_MALLOC(name_length);

        if (!name_dup) {
            return NULL;
        }

        memcpy(name_dup, name, name_length);

        trace = name_dup;
        while (trace) {
            char *dot = strchr(trace, '.');
            if (dot) {
                *dot++ = '\0';
            }

            if (object == NULL) {
                if (no_block) {
                    object = PyImport_ImportModuleNoBlock(trace);
                } else {
                    object = PyImport_ImportModule(trace);
                    if (!object) {
                        PyErr_Format(PyExc_ImportError,
                            "PyCapsule_Import could not "
                            "import module \"%s\"", trace);
                    }
                }
            } else {
                PyObject *object2 = PyObject_GetAttrString(object, trace);
                Py_DECREF(object);
                object = object2;
            }
            if (!object) {
                goto EXIT;
            }

            trace = dot;
        }

        if (PyCObject_Check(object)) {
            PyCObject *cobject = (PyCObject *)object;
            return_value = cobject->cobject;
        } else {
            PyErr_Format(PyExc_AttributeError,
                "PyCapsule_Import \"%s\" is not valid",
                name);
        }

    EXIT:
        Py_XDECREF(object);
        if (name_dup) {
            PyMem_FREE(name_dup);
        }
        return return_value;
    }

    #endif /* #if PY_VERSION_HEX < 0x02070000 */

    #endif /* __CAPSULETHUNK_H */

## Autres options

Si vous écrivez un nouveau module d'extension, vous pouvez envisager d'utiliser Cython. Il traduit un langage de type Python en C. Les modules d'extension qu'il crée sont compatibles avec Python 3 et Python 2.