Toute fonction utilisable dans Python est de la forme PyObject* ma_fonction(PyObject* self, PyObject* args). Le premier argument est facultatif et représente l'instance de la classe sur laquelle une méthode est appelée. Dans le cas d'une fonction, seul le second argument est utile. Celui-ci contient un tuple contenant les arguments passés à la fonction.

La récupération des arguments se réalise traditionnellement par la fonction PyArg_ParseTuple(). Le premier argument est le tuple contenant les arguments, puis une chaine de format et des pointeurs vers les données à remplir. Le retour de cette fonction est différent de 0 si tout s'est bien passé.

static PyObject* exemple(PyObject* self, PyObject* args)
{
  const char* chaine;
  
  if(!PyArg_ParseTuple(args, "s", &chaine))
    return NULL;

  return Py_BuildValue("i", 0);
}

Dans cet exemple, la fonction exemple() prend en argument une seule valeur qui est une chaine de caractères. Cette chaine de caractères est remplie par PyArg_ParseTuple() à qui il est précisé qu'il n'y a qu'un seul argument de type 's' ou chaine de caractères. L'opération inverse est effectuée par Py_BuildValue() qui crée un objet Python à partir d'une chaine de format et plusieurs arguments, ici un entier est créé.

La valeur de retour de PyArg_ParseTuple() est testée et si elle est nulle, un pointeur nul sera retourné à la fonction appelante. En fait, cette fonction a levé une exception Python qui sera propagée par ce pointeur nul. De même, si Py_BuildValue() échoue, une exception Python est levée et est propagée à la fonction appelante. Si une exception est levée dans une fonction fille, il ne faut surtout pas lever une nouvelle exception, mais simplement la propager en retournant un pointeur nul. Arrivé dans le code Python appelant, l'utilisateur pourra décider de l'action à mener.

Lever une exception se fait par la fonction PyErr_SetString(), prenant en paramètre un type d'erreur et une chaine de commentaire. Heureusement, plusieurs fonctions d'aide existent pour simplifier les appels, comme PyExc_ZeroDivisionError() qui lève une exception indiquant une division par zéro, PyErr_NoMemory() levée en cas d'erreur d'allocation ou encore PyErr_BadArgument() qui indique une erreur de type (c'est l'exception levée par PyArg_ParseTuple() en cas d'erreur de conversion). Si une fonction C est capable de gérer une erreur (détectée en vérifiant le retour d'une fonction appelée), elle peut effacer l'exception en appelant PyErr_Clear().

Une fois les fonctions créées, elles ne sont pas visibles pour le moment par Python. En effet, dans l'exemple donné, le mot-clé static indique expressément que la fonction ne sera pas visible de l'extérieur et donc a fortiori par Python. Une seule fonction doit être visible de l'extérieur, il s'agit de init_module() où _module est le nom du module qui devra être chargé. Cette fonction a pour mission de créer un PyObject* et de le retourner, cet objet contenant la liste des fonctions disponibles dans le module. En fait, ceci sera effectué par un appel à Py_InitModule() qui prend en argument le nom du module ainsi qu'un tableau de PyMethodDef. Cette structure PyMethodDef contient quant à elle le nom de la fonction, le pointeur vers cette fonction, quel est le mode de passage des arguments (METH_VARARGS pour passer les arguments dans un tuple) et une chaine de commentaire sur la fonction.

static PyMethodDef fonctions[]={
  {"exemple", exemple, METH_VARARGS, "Un commentaire"},
  {NULL, NULL, 0, NULL}
};

PyMODINIT_FUNC init_mon_module(void)
{
  PyObject* m;
  m = Py_InitModule("_mon_module", fonctions);
}

L'objet module m est automatiquement enregistré dans l'interpréteur, mais peut être utilisé pour ajouter manuellement d'autres objets. Par exemple une nouvelle exception ExempleErreur (déclarée comme variable statique dans le fichier source) pourra être déclarée avec PyErr_NewException(), le premier argument étant le nom de l'exception (avec le nom du module donc _mon_module.Exception), le deuxième donne le type dont l'exception héritera et le troisième est un dictionnaire donnant une liste de méthodes (en général, ces deux arguments sont placés à NULL et l'exception héritera de la classe de base Exception). Elle doit ensuite être enregistrée dans le module à l'aide de la fonction PyModule_AddObject() prenant en paramètres le module où inclure l'objet, le nom de cet objet dans le module et l'objet lui-même. Une fois l'exception créée et enregistrée, elle pourra être utilisée avec PyErr_SetString(ExempleErreur, « Une explication »).

Voici le code complet de cet exemple :

#include <Python.h>

/**
  Une fois importe, le module definit deux fonctions :
    - exemple qui prend une chaine en argument et retourne 0
    - exemple2 qui leve une exception creee pour l'occasion
**/

static PyObject* ExempleErreur;

static PyObject* exemple(PyObject* self, PyObject* args)
{
  const char* chaine;

  if(!PyArg_ParseTuple(args, "s", &chaine))
    return NULL;

  return Py_BuildValue("i", 0);
}

static PyObject* exemple2(PyObject* self, PyObject* args)
{
  const char* chaine;

  PyErr_SetString(ExempleErreur, "Exemple de levée d'erreur");
  return NULL;
}

static PyMethodDef fonctions[]={
  {"exemple", exemple, METH_VARARGS, "Un commentaire"},
  {"exemple2", exemple2, METH_VARARGS, "Une methode levant une exception"},
  {NULL, NULL, 0, NULL}
};

PyMODINIT_FUNC init_mon_module(void)
{
  PyObject* m;
  m = Py_InitModule("_mon_module", fonctions);
  
  ExempleErreur = PyErr_NewException("_mon_module.Exception", NULL, NULL);
  Py_INCREF(ExempleErreur);
  PyModule_AddObject(m, "Exception", ExempleErreur);
}

#!/usr/bin/python
# -*- coding: cp1252 -*-

from distutils.core import setup
from distutils.core import Extension

setup(name = 'exemples',
      version = '1.0',
      ext_modules = [Extension('_mon_module', ['api_c.c']), ],
      cmdclass = cmdclass,
      url='http://matthieu-brucher.developpez.com/livre/python/scientifiques',
      author='Matthieu Brucher',
      author_email='@',
      )

pythons etup.py build_ext --inplace

import _mon_module

print _mon_module.exemple()
print _mon_module.exemple2()

Une fois ces éléments de base maîtrisés, d'autres concepts peuvent être présentés.

Le premier consiste à comprendre le mécanisme de références utilisé par Python pour gérer l'utilisation de la mémoire. À chaque fois qu'un objet Python est créé, un compteur de référence y est attaché, comptant le nombre de variables référençant l'objet. Une fois ce compte nul, l'objet est détruit. Il est donc nécessaire d'indiquer explicitement si on veut garder l'objet ou non. On parle alors d'acquisition de l'objet.

Pour compliquer les choses, lorsqu'une fonction Python est appelée, elle emprunte les objets Python passés en paramètre (par exemple pour la fonction exemple(), aucune incrémentation du compteur de référence n'a été faite, en effet, l'objet est acquis par l'une des fonctions parentes et donc ne sera pas détruit), elle ne les acquiert pas. Pour les acquérir explicitement, les fonctions Py_INCREF() et Py_XINCREF() doivent être appelées (la seconde permet de passer un pointeur nul, ce n'est pas le cas de la première) et pour les relâcher, les fonctions réciproques Py_DECREF() et Py_XDECREF() sont à utiliser. Lorsqu'une fonction retourne un objet, l'acquisition de l'objet passe à la fonction appelante. C'est pourquoi la fonction Py_BuildValue() n'est pas suivie d'un appel à Py_INCREF() puisque c'est la fonction qui s'en charge elle-même lors de l'appel. En revanche, si un objet est lu depuis une liste ou toute autre classe (par exemple un attribut d'une classe), il est prudent d'acquérir l'objet lu et de le relâcher explicitement. En effet, lors d'opérations annexes, le compteur de référence de l'objet lu peut descendre à 0 et l'objet sera détruit alors qu'on veut travailler dessus.

Pour résumer : une fonction appelée emprunte chaque objet passé en paramètre et une fonction retournant un objet créé passe son acquisition à la fonction appelante.

Les fonctions définies peuvent aussi passer les arguments par dictionnaire. Dans ce cas, un troisième argument est fourni qui est le dictionnaire des arguments utilisés. Pour remplir les arguments C à partir de ces deux objets Python, une autre fonction doit être utilisée, PyArg_ParseTupleAndKeywords(), prenant ces deux objets en paramètres, une chaine de format (toujours pour indiquer le ou les type(s) attendu(s)), une liste des arguments nommés attendus puis les pointeurs vers les variables.

static PyObject* ma_fonction(PyObject* self, PyObject *args, PyObject *kwargs)
{
  int argument1, argument2;
  float argument3;
  static char* liste[] = {"argument1", "argument2", "argument3"};
  if(!PyArg_ParseTupleAndKeywords(args, kwargs, "iif", liste, &argument1, &argument2, &argument3);
  
  Py_INCREF(Py_None);
  return Py_None;
}

La fonction n'est plus du même type que les fonctions traditionnelles ne prenant qu'un seul argument. De plus, elle prend en argument un dictionnaire. Cela s'écrit sous la forme suivante dans le tableau des méthodes :

static PyMethodDef fonctions ={
...,
{"ma_fonction", (PyCFunction)ma_fonction, METH_VARARGS|METH_KEYWORDS, "Un commentaire"}
};

Dans l'exemple précédent, un objet Py_None a été utilisé. Il s'agit de l'objet Python None, et il est unique. Puisqu'on le retourne de la fonction, on transfère son acquisition. Pour cela, il faut donc l'acquérir au préalable, d'où l'incrémentation de son compteur.

Chaque fonction Python est préfixée par Py ou PY. Dans le cas de méthodes sur des types Python, comme les entiers, les listes ou les tuples, ce préfixe est suivi du nom de ce type (par exemple PyList_SetItem() et PyList_GetItem()). Ensuite se situe le nom de la méthode qui sera appelée. L'exposé des différentes méthodes n'est pas l'objet de cette partie, mais ce sont ces fonctions qui permettront de convertir un objet Python en une variable C associée ou inversement, transformer un objet Python en un autre, ajouter un objet Python à un autre, etc.

Afin de proposer des extensions concrètes à Python, une série de fonctions a vu le jour. L'objectif est de permettre à une extension d'être accessible par une autre extension (c'est typiquement le cas de l'extension Numpy qui est accédée par une extension créée pour optimiser certains calculs). Plutôt que de forcer tous les modules à exporter leurs fonctions et à ce que chaque module soit lié directement à l'interpréteur, une solution a été trouvée pour que les types et fonctions d'une extension dynamique puissent être passés à une autre extension dynamique, et c'est le rôle des objets PyCObject. Cet objet contient un pointeur quelconque sur des données qui pourra ensuite être réutilisé.

Les fonctions intéressantes sont :

• PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) qui crée un objet PyCObject à partir du pointeur donné et qui utilisera la fonction passée en paramètre (si le pointeur n'est pas nul) lors de la destruction de l'objet ;
• PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) qui crée un objet à partir d'un pointeur et d'une description et qui appellera la fonction destr lors de la destruction de l'objet avec les deux pointeurs passés en paramètre. L'utilisation classique de cette fonction avec numpy est de passer en second argument l'objet Python duquel une vue a été faite et pour permettre de relâcher cet objet lors de la destruction de la vue ;
• void* PyCObject_AsVoidPtr(PyObject* self) qui récupère le pointeur stocké dans l'objet ;
• void* PyCObject_GetDesc(PyObject* self) qui récupère la description de l'objet si elle existe.

Pour utiliser des objets et les communiquer à un autre module, ils doivent tout d'abord être enregistrés. Pour cela, la fonction d'initialisation du module d'extension va enregistrer la totalité des fonctions accessibles dans un tableau de fonction appelé par exemple PyMonModule_API de type void**. À partir de ce tableau, un objet de type PyCObject sera créé et enfin cet objet sera ajouté au module chargé avec un nom explicite.

void* PyMonModule_API[]={/*Ma liste de pointeurs vers une liste de fonctions*/};

PyMODINIT_FUNC init_mon_module(void)
{
  PyObject* m;
  PyObject* c_api;

  m = Py_InitModule("_mon_module", MesFonctions);

  c_api = PyCObject_FromVoidPtr((void *)PyMonModule_API, NULL);

  if (c_api != NULL)
    PyModule_AddObject(m, "c_api", c_api);
}

Ainsi, le module exporte un seul attribut qui sera un tableau de fonctions. Un nom plus explicite que c_api pour cet attribut est souhaitable. En effet, comme il sera vu lors de l'utilisation de cet attribut, si tous les modules utilisent le même nom, il sera impossible de savoir si le module correct a été chargé, le test se faisant justement sur l'attribut chargé.

Voici le fichier d'entête simplifié qui doit être créé pour permettre de charger dans tout autre module d'extension les fonctions C mises à disposition par _mon_module :

static void **PyMonModule_API;

static int import_mon_module(void)
{
  PyObject* m = PyImport_ImportModule("_mon_module");

  if (m!=NULL)
  {
    PyObject* c_api = PyObject_GetAttrString(m, "c_api");
    id(c_api == NULL)
      return -1;
    if (PyCObject_Check(c_api))
      PyMonModule_API = (void **)PyObject_AsVoidPtr(c_api);
    PyDECREF(c_api);
    PyDECREF(m);
  }
  else
    return -1;
  return 0;
}

Cette fonction est a priori complexe, mais une fois assimilée, toutes les autres fonctions d'importation de fonctions d'un autre module d'extension sont connues. La première étape est d'importer le module que l'on souhaite charger. Une fois chargé, l'objet contenant la liste des fonctions de ce module est récupéré et acquis par PyObject_GetAttrString(). Un test supplémentaire est effectué pour vérifier que l'objet est bien un PyCObject et si c'est le cas, son contenu est récupéré et si la création du module a suivi le protocole précédent, le contenu est un pointeur vers un tableau de fonctions. Enfin, il faut relâcher l'objet récupéré dans le module ainsi que le module lui-même.

Par défaut, il n'est pas possible d'exécuter plusieurs fonctions dans Python en même temps sur plusieurs processeurs. Dans le cas où des accès longs d'entrée/sortie, Python propose des macros pour relâcher le GIL et permettre à un autre thread d'accéder à l'interpréteur, et lorsque les accès seront terminés, le GIL sera réacquis.

Voici les deux macros :

Py_BEGIN_ALLOW_THREADS
/* Effectuer des opérations extérieures à Python */
Py_END_ALLOW_THREADS

Ces deux macros créent un bloc donc toute variable déclarée entre ces deux macros est détruite en sortant du bloc. Numpy utilise ce système lors de ses appels aux fonctions C sous-jacentes pour permettre à un autre thread Python de travailler.

La réacquisition du GIL pendant le bloc (par exemple lors d'un appel à une fonction Python) se produit avec les instructions :

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

Puis son relâchement par :

PyGILState_Release(gstate);