Commen\u00e7ons par le code source.
Il existe deux m\u00e9thodes : la m\u00e9thode en une seule phase et la m\u00e9thode en plusieurs phases.<\/p>\n\n\n\n
La m\u00e9thode en une seule phase n'est plus recommand\u00e9e (est-elle obsol\u00e8te ? Je n'en suis pas encore s\u00fbr) ==> Pourquoi ne pas cr\u00e9er un programme permettant de migrer le code source de la m\u00e9thode en une seule phase vers la m\u00e9thode en plusieurs phases ? C'est peut-\u00eatre possible ? Mais c'est un autre sujet.
Concentrons-nous sur le code source : voici un mod\u00e8le g\u00e9n\u00e9rique. Commen\u00e7ons par nous exercer sur le code pour comprendre comment proc\u00e9der.
Et au c\u0153ur de Python :<\/p>\n\n\n\n
Include\/pyport.h<\/code> contient le commentaire : \u00ab D\u00e9sormais, PY_SSIZE_T_CLEAN est obligatoire. Ceci est uniquement pour des raisons de compatibilit\u00e9 ascendante. \u00bb<\/li>\n\n\n\n- et il d\u00e9finit \u00e9galement :
typedef Py_ssize_t Py_ssize_clean_t;<\/code><\/li>\n<\/ul>\n\n\n\nLa r\u00e8gle pratique est donc la suivante :<\/p>\n\n\n\n
\n- avant Python 3.13 : le d\u00e9finir avant
#include <Python.h><\/code> pour utiliser les API avec #<\/code><\/li>\n\n\n\n- \u00e0 partir de Python 3.13 : ce n\u2019est plus strictement n\u00e9cessaire, mais on le conserve pour des raisons de compatibilit\u00e9<\/li>\n<\/ul>\n\n\n\n
En bref, PY_SSIZE_T_CLEAN<\/code> cela sert \u00e0 garantir le bon type Py_ssize_t<\/code> dans les liaisons C\/extensions, et le d\u00e9p\u00f4t le met surtout en avant dans la documentation et les exemples, pas dans le corps de l\u2019en-t\u00eate principal.
#ifdef PY_SSIZE_T_CLEAN<\/code> est une condition de compilation utilis\u00e9e par l\u2019API C de CPython pour basculer certaines fonctions vers les Py_ssize_t<\/code>variantes bas\u00e9es sur .<\/p>\n\n\n\nEn pratique, le mod\u00e8le courant est le suivant :<\/p>\n\n\n\n
C<\/p>\n\n\n\n
#define PY_SSIZE_T_CLEAN\n#include <Python.h>\n<\/code><\/pre>\n\n\n\nAinsi, les API qui prennent en param\u00e8tre une longueur\/un nombre ou une taille de tampon utilisent Py_ssize_t<\/code> au lieu de int<\/code> pour certaines unit\u00e9s de format telles que :<\/p>\n\n\n\n\ns#<\/code><\/li>\n\n\n\ny#<\/code><\/li>\n\n\n\nz#<\/code><\/li>\n\n\n\n- et d\u2019autres
#<\/code>formats d\u2019analyse d\u2019arguments bas\u00e9s sur<\/li>\n<\/ul>\n\n\n\nExemple :<\/p>\n\n\n\n
C<\/p>\n\n\n\n
char *buf;\nPy_ssize_t len;\n\nPyArg_ParseTuple(args, \"s#\", &buf, &len);\n<\/code><\/pre>\n\n\n\nSans PY_SSIZE_T_CLEAN<\/code>, certaines anciennes versions de Python pouvaient consid\u00e9rer la longueur comme int<\/code> au lieu de Py_ssize_t<\/code>, ce qui n\u2019est pas id\u00e9al pour les grandes tailles et constitue une source de probl\u00e8mes d\u2019incompatibilit\u00e9 ABI\/API.<\/p>\n\n\n\nRemarques importantes concernant CPython :<\/p>\n\n\n\n
\n- Sous Python 3.12 et versions ant\u00e9rieures, cette macro est n\u00e9cessaire pour utiliser les
#<\/code> variantes en toute s\u00e9curit\u00e9.<\/li>\n\n\n\n- Sous Python 3.13 et versions ult\u00e9rieures, elle n\u2019est plus n\u00e9cessaire dans la plupart des cas.<\/li>\n\n\n\n
- Dans le code CPython plus r\u00e9cent, elle est consid\u00e9r\u00e9e comme une macro de compatibilit\u00e9 : le moteur la prend toujours en charge, mais le code moderne utilise principalement les
Py_ssize_t<\/code>sans avoir besoin d\u2019elle.<\/li>\n<\/ul>\n\n\n\nVous pouvez \u00e9galement le constater dans la documentation de CPython :<\/p>\n\n\n\n
\nDoc\/c-api\/arg.rst<\/code> il est indiqu\u00e9 qu\u2019elle doit \u00eatre d\u00e9finie sous Python 3.12 et versions ant\u00e9rieures pour toutes les #<\/code> variantes de format.<\/li>\n\n\n\nInclude\/pyport.h<\/code> indique que cela n\u2019est d\u00e9sormais conserv\u00e9 que pour des raisons de compatibilit\u00e9 ascendante.<\/li>\n<\/ul>\n\n\n\nEn r\u00e9sum\u00e9 :<\/p>\n\n\n\n
\nPY_SSIZE_T_CLEAN<\/code> = \u00ab utiliser Py_ssize_t<\/code> pour les arguments de type taille\/nombre de l\u2019API C \u00bb<\/li>\n\n\n\n- Cela concerne principalement l\u2019analyse des arguments et les API de tampon<\/li>\n\n\n\n
- Il ne s\u2019agit pas d\u2019un indicateur d\u2019ex\u00e9cution, mais simplement d\u2019une macro qui modifie le contrat de l\u2019API C lors de la compilation<\/li>\n<\/ul>\n\n\n\n
Si vous le souhaitez, je peux \u00e9galement vous indiquer pr\u00e9cis\u00e9ment quelles fonctions de l\u2019API C de CPython sont concern\u00e9es et comment les utiliser Py_ssize_t<\/code> correctement dans un module d\u2019extension.
Py_ssize_t<\/code> n\u2019est pas d\u00e9fini en fonction de PY_SSIZE_T_CLEAN<\/code><\/strong>. Il est d\u00e9fini dans Include\/pyport.h<\/code>. La macro PY_SSIZE_T_CLEAN<\/code> modifie plut\u00f4t la fonction d\u2019analyse syntaxique<\/strong> utilis\u00e9e, et donc le type attendu pour les longueurs des formats #<\/code> comme s#<\/code> ou y#<\/code>.huggingface<\/a><\/p>\n\n\n\nD\u00e9finition de Py_ssize_t<\/h2>\n\n\n\n
Dans Include\/pyport.h<\/code> :<\/p>\n\n\n\nctypedef ssize_t Py_ssize_t;<\/code><\/pre>\n\n\n\nlorsque la plateforme fournit ssize_t<\/code>. Sinon, CPython choisit un type entier sign\u00e9 de m\u00eame taille que size_t<\/code> :<\/p>\n\n\n\ncsizeof(Py_ssize_t) == sizeof(size_t)<\/code><\/pre>\n\n\n\nDonc :<\/p>\n\n\n\n
textPy_ssize_t : toujours d\u00e9fini dans Include\/pyport.h\nPY_SSIZE_T_CLEAN : contr\u00f4le le comportement des formats \"#\"<\/code><\/pre>\n\n\n\nO\u00f9 intervient PY_SSIZE_T_CLEAN<\/h2>\n\n\n\n
La macro est utilis\u00e9e dans Include\/modsupport.h<\/code>. Elle redirige les fonctions d\u2019analyse vers leurs variantes _SizeT<\/code> :<\/p>\n\n\n\nc#ifdef PY_SSIZE_T_CLEAN\n#define PyArg_Parse _PyArg_Parse_SizeT\n#define PyArg_ParseTuple _PyArg_ParseTuple_SizeT\n#define PyArg_ParseTupleAndKeywords _PyArg_ParseTupleAndKeywords_SizeT\n#define Py_VaBuildValue _Py_VaBuildValue_SizeT\n#endif<\/code><\/pre>\n\n\n\nAinsi, avec :<\/p>\n\n\n\n
c#define PY_SSIZE_T_CLEAN\n#include <Python.h><\/code><\/pre>\n\n\n\nce code :<\/p>\n\n\n\n
cPyArg_ParseTuple(args, \"y#\", &data, &length);<\/code><\/pre>\n\n\n\nappelle en r\u00e9alit\u00e9 :<\/p>\n\n\n\n
c_PyArg_ParseTuple_SizeT(args, \"y#\", &data, &length);<\/code><\/pre>\n\n\n\nEffet sur les formats #<\/h2>\n\n\n\nMacro d\u00e9finie ?<\/th> Fonction appel\u00e9e<\/th> Type attendu pour s#<\/code>, y#<\/code>, etc.<\/th><\/tr><\/thead>Non<\/td> PyArg_ParseTuple<\/code><\/td>int<\/code><\/td><\/tr>Oui<\/td> _PyArg_ParseTuple_SizeT<\/code><\/td>Py_ssize_t<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nhuggingface+1<\/p>\n\n\n\n
Exemple :<\/p>\n\n\n\n
c#define PY_SSIZE_T_CLEAN\n#include <Python.h>\n\nconst char *data;\nPy_ssize_t length;\n\nPyArg_ParseTuple(args, \"y#\", &data, &length);<\/code><\/pre>\n\n\n\nIci, length<\/code> il doit s'agir d'un Py_ssize_t<\/code>.cmi.ac+1<\/p>\n\n\n\nO\u00f9 est impl\u00e9ment\u00e9 le comportement<\/h2>\n\n\n\n
L\u2019impl\u00e9mentation se trouve dans :<\/p>\n\n\n\n
textPython\/getargs.c<\/code><\/pre>\n\n\n\nnotamment dans les fonctions de conversion telles que convertsimple()<\/code>. C\u2019est l\u00e0 que CPython v\u00e9rifie, pour les anciennes versions, que la macro a bien \u00e9t\u00e9 d\u00e9finie avant d\u2019accepter un format #<\/code> :<\/p>\n\n\n\nc#define REQUIRE_PY_SSIZE_T_CLEAN \nif (!(flags & FLAG_SIZE_T)) { \n PyErr_SetString(PyExc_SystemError, \n \"PY_SSIZE_T_CLEAN macro must be defined for '#' formats\"); \n return NULL; \n}<\/code><\/pre>\n\n\n\nR\u00e9sum\u00e9 des fichiers<\/h2>\n\n\n\nFichier CPython<\/th> R\u00f4le<\/th><\/tr><\/thead> Include\/pyport.h<\/code><\/td>D\u00e9finit Py_ssize_t<\/code>, PY_SSIZE_T_MAX<\/code>, PY_SSIZE_T_MIN<\/code><\/td><\/tr>Include\/Python.h<\/code><\/td>Inclut pyport.h<\/code>, modsupport.h<\/code>, etc.<\/td><\/tr>Include\/modsupport.h<\/code><\/td>Utilise PY_SSIZE_T_CLEAN<\/code> pour rediriger vers les variantes _SizeT<\/code><\/td><\/tr>Python\/getargs.c<\/code><\/td>Impl\u00e9mente l'analyse et le traitement des formats #<\/code><\/td><\/tr>Python\/modsupport.c<\/code><\/td>Impl\u00e9mente notamment Py_BuildValue()<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nhuggingface+1<\/p>\n\n\n\n
Depuis Python 3.13<\/h2>\n\n\n\n
Depuis Python 3.13, PY_SSIZE_T_CLEAN<\/code> n\u2019est plus n\u00e9cessaire pour les formats #<\/code> : Py_ssize_t<\/code> est d\u00e9sormais le comportement par d\u00e9faut. La macro reste recommand\u00e9e dans le code source pour des raisons de compatibilit\u00e9 avec les versions ant\u00e9rieures.github<\/a><\/p>\n\n\n\nEn un mot<\/h2>\n\n\n\n
Py_ssize_t<\/code> est d\u00e9fini dans Include\/pyport.h<\/code> ind\u00e9pendamment de PY_SSIZE_T_CLEAN<\/code> ; cette macro, trait\u00e9e dans Include\/modsupport.h<\/code> et Python\/getargs.c<\/code>, s\u00e9lectionne les variantes _SizeT<\/code> de PyArg_Parse*()<\/code> afin que les formats #<\/code> attendent un Py_ssize_t<\/code> plut\u00f4t qu\u2019un int<\/code>.<\/p>\n\n\n\nCode C<\/span><\/span>