python-docs-fr/extending/extending.po

# Copyright (C) 2001-2018, Python Software Foundation
# For licence information, see README file.
#
msgid ""
msgstr ""
"Project-Id-Version: Python 3\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2021-11-27 10:27+0100\n"
"PO-Revision-Date: 2021-12-11 12:50+0100\n"
"Last-Translator: Julien Palard <julien@palard.fr>\n"
"Language-Team: FRENCH <traductions@lists.afpy.org>\n"
"Language: fr\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: Poedit 2.3\n"

#: extending/extending.rst:8
msgid "Extending Python with C or C++"
msgstr "Étendre Python en C ou C++"

#: extending/extending.rst:10
msgid ""
"It is quite easy to add new built-in modules to Python, if you know how to "
"program in C.  Such :dfn:`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."
msgstr ""
"Il est relativement facile d'ajouter de nouveaux modules à Python, si vous "
"savez programmer en C. Ces :dfn:`<modules d'extension> extension modules` "
"permettent deux choses qui ne sont pas possibles directement en Python : "
"Elles peuvent définir de nouveaux types natifs, et peuvent appeler des "
"fonctions de bibliothèques C ou faire des appels systèmes."

#: extending/extending.rst:15
msgid ""
"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\"``."
msgstr ""
"Pour gérer les extensions, l'API Python (*Application Programmer Interface*) "
"définit un ensemble de fonctions, macros et variables qui donnent accès à la "
"plupart des aspects du système d'exécution de Python. L'API Python est "
"incorporée dans un fichier source C en incluant l'en-tête ``\"Python.h\"``."

#: extending/extending.rst:20
msgid ""
"The compilation of an extension module depends on its intended use as well "
"as on your system setup; details are given in later chapters."
msgstr ""
"La compilation d'un module d'extension dépend de l'usage prévu et de la "
"configuration du système, plus de détails peuvent être trouvés dans les "
"chapitres suivants."

#: extending/extending.rst:25
msgid ""
"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 :mod:`ctypes` "
"module or the `cffi <https://cffi.readthedocs.io/>`_ 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."
msgstr ""
"L'interface d'extension C est spécifique à *CPython*, et les modules "
"d'extension ne fonctionne pas sur les autres implémentations de Python. Dans "
"de nombreux cas, il est possible d'éviter la rédaction des extensions en C "
"et ainsi préserver la portabilité vers d'autres implémentations. Par "
"exemple, si vous devez appeler une fonction de la bibliothèque C ou faire un "
"appel système, vous devriez envisager d'utiliser le module :mod:`ctypes` ou "
"d'utiliser la bibliothèque `*cffi* <https://cffi.readthedocs.io/>`_ plutôt "
"que d'écrire du code C sur mesure. Ces modules vous permettent d'écrire du "
"code Python s'interfaçant avec le code C et sont plus portables entre les "
"implémentations de Python que l'écriture et la compilation d'une d'extension "
"C."

#: extending/extending.rst:40
msgid "A Simple Example"
msgstr "Un exemple simple"

#: extending/extending.rst:42
msgid ""
"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 :c:func:`system` [#]_. 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:"
msgstr ""
"Créons un module d'extension appelé ``spam`` (la nourriture préférée de fans "
"des *Monty Python* …) et disons que nous voulons créer une interface Python "
"à la fonction de la bibliothèque C :c:func:`system` [#]_. Cette fonction "
"prend une chaîne de caractères à terminaison nulle comme argument et renvoie "
"un entier. Nous voulons que cette fonction soit appelable à partir de Python "
"comme suit :"

#: extending/extending.rst:53
msgid ""
"Begin by creating a file :file:`spammodule.c`.  (Historically, if a module "
"is called ``spam``, the C file containing its implementation is called :file:"
"`spammodule.c`; if the module name is very long, like ``spammify``, the "
"module name can be just :file:`spammify.c`.)"
msgstr ""
"Commencez par créer un fichier :file:`spammodule.c`. (Historiquement, si un "
"module se nomme ``spam``, le fichier C contenant son implémentation est "
"appelé :file:`spammodule.c`. Si le nom du module est très long, comme "
"``spammify``, le nom du module peut être juste :file:`spammify.c`.)"

#: extending/extending.rst:58
msgid "The first two lines of our file can be::"
msgstr "Les deux premières lignes de notre fichier peuvent être ::"

#: extending/extending.rst:63
msgid ""
"which pulls in the Python API (you can add a comment describing the purpose "
"of the module and a copyright notice if you like)."
msgstr ""
"qui récupère l'API Python (vous pouvez ajouter un commentaire décrivant le "
"but du module et un avis de droit d'auteur si vous le souhaitez)."

#: extending/extending.rst:68
msgid ""
"Since Python may define some pre-processor definitions which affect the "
"standard headers on some systems, you *must* include :file:`Python.h` before "
"any standard headers are included."
msgstr ""
"Python pouvant définir certaines définitions pré-processeur qui affectent "
"les têtes standard sur certains systèmes, vous *devez* inclure :file:`Python."
"h` avant les en-têtes standards."

#: extending/extending.rst:72
msgid ""
"It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including "
"``Python.h``.  See :ref:`parsetuple` for a description of this macro."
msgstr ""
"Il est recommandé de toujours définir ``PY_SSIZE_T_CLEAN`` avant d'inclure "
"``Python.h``. Lisez :ref:`parsetuple` pour avoir une description de cette "
"macro."

#: extending/extending.rst:75
msgid ""
"All user-visible symbols defined by :file:`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 :c:func:`malloc`, :c:func:`free` "
"and :c:func:`realloc` directly."
msgstr ""
"Tous les symboles exposés par :file:`Python.h` sont préfixés de ``Py`` ou "
"``PY``, sauf ceux qui sont définis dans les en-têtes standard. Pour le "
"confort, et comme ils sont largement utilisés par l'interpréteur Python, ``"
"\"Python.h\"`` inclut lui-même quelques d'en-têtes standard : ``<stdio.h>``, "
"``<string.h>``, ``<errno.h>`` et ``<stdlib.h>``. Si ce dernier n'existe pas "
"sur votre système, il déclare les fonctions :c:func:`malloc`, :c:func:`free` "
"et :c:func:`realloc` directement."

#: extending/extending.rst:83
msgid ""
"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)::"
msgstr ""
"La prochaine chose que nous ajoutons à notre fichier de module est la "
"fonction C qui sera appelée lorsque l'expression Python ``spam."
"system(chaîne)`` sera évaluée (nous verrons bientôt comment elle finit par "
"être appelée) ::"

#: extending/extending.rst:99
msgid ""
"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*."
msgstr ""
"Il y a une correspondance directe de la liste des arguments en Python (par "
"exemple, l'expression ``\"ls -l\"``) aux arguments passés à la fonction C. "
"La fonction C a toujours deux arguments, appelés par convention *self* et "
"*args*."

#: extending/extending.rst:104
msgid ""
"The *self* argument points to the module object for module-level functions; "
"for a method it would point to the object instance."
msgstr ""
"Pour les fonctions au niveau du module, l'argument *self* pointe sur l'objet "
"module, pour une méthode, il pointe sur l'instance de l'objet."

#: extending/extending.rst:107
msgid ""
"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 :c:func:`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."
msgstr ""
"L'argument *args* sera un pointeur vers un *n*-uplet Python contenant les "
"arguments. Chaque élément du *n*-uplet correspond à un argument dans la "
"liste des arguments de l'appel. Les arguments sont des objets Python, afin "
"d'en faire quelque chose dans notre fonction C, nous devons les convertir en "
"valeurs C. La fonction :c:func:`PyArg_ParseTuple` de l'API Python vérifie "
"les types des arguments et les convertit en valeurs C. Elle utilise un "
"modèle sous forme de chaîne pour déterminer les types requis des arguments "
"ainsi que les types de variables C dans lequel stocker les valeurs "
"converties. Nous en verront plus, plus tard."

#: extending/extending.rst:116
msgid ""
":c:func:`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)."
msgstr ""
":c:func:`PyArg_ParseTuple` renvoie vrai (pas zéro) si tous les arguments ont "
"le bon type et que ses composants ont été stockés dans les variables dont "
"les adresses ont été données en entrée. Il renvoie faux (zéro) si une liste "
"d'arguments invalide a été passée. Dans ce dernier cas, elle lève également "
"une exception appropriée de sorte que la fonction d'appel puisse renvoyer "
"``NULL`` immédiatement (comme nous l'avons vu dans l'exemple)."

#: extending/extending.rst:126
msgid "Intermezzo: Errors and Exceptions"
msgstr "Intermezzo : Les erreurs et les exceptions"

#: extending/extending.rst:128
#, fuzzy
msgid ""
"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 :meth:`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."
msgstr ""
"Une convention primordiale imprégnant tout l'interpréteur Python est : quand "
"une fonction échoue, elle devrait laisser une exception et renvoyer une "
"valeur d'erreur (typiquement un pointeur ``NULL``). Dans l'interpréteur, les "
"exceptions sont stockées dans une variable globale statique, si cette "
"variable est ``NULL``, aucune exception n'a eu lieu. Une seconde variable "
"globale stocke la \"valeur associée\" à l'exception (le deuxième argument "
"de :keyword:`raise`). Une troisième variable contient la trace de la pile "
"dans le cas où l'erreur soit survenue dans du code Python. Ces trois "
"variables sont les équivalents C du résultat de :meth:`sys.exc_info` en "
"Python (voir la section sur le module :mod:`sys` dans *The Python Library "
"Reference*). Il est important de les connaître pour comprendre comment les "
"erreurs sont propagées."

#: extending/extending.rst:137
msgid ""
"The Python API defines a number of functions to set various types of "
"exceptions."
msgstr ""
"L'API Python définit un certain nombre de fonctions pour créer différents "
"types d'exceptions."

#: extending/extending.rst:139
msgid ""
"The most common one is :c:func:`PyErr_SetString`.  Its arguments are an "
"exception object and a C string.  The exception object is usually a "
"predefined object like :c:data:`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."
msgstr ""
"La plus courante est :c:func:`PyErr_SetString`. Ses arguments sont un objet "
"exception et une chaîne C. L'objet exception est généralement un objet "
"prédéfini comme :c:data:`PyExc_ZeroDivisionError`. La chaîne C indique la "
"cause de l'erreur et est convertie en une chaîne Python puis stockée en tant "
"que \"valeur associée\" à l'exception."

#: extending/extending.rst:145
msgid ""
"Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an "
"exception argument and constructs the associated value by inspection of the "
"global variable :c:data:`errno`.  The most general function is :c:func:"
"`PyErr_SetObject`, which takes two object arguments, the exception and its "
"associated value.  You don't need to :c:func:`Py_INCREF` the objects passed "
"to any of these functions."
msgstr ""
"Une autre fonction utile est :c:func:`PyErr_SetFromErrno`, qui construit une "
"exception à partir de la valeur de la variable globale :c:data:`errno`. La "
"fonction la plus générale est :c:func:`PyErr_SetObject`, qui prend deux "
"arguments : l'exception et sa valeur associée. Vous ne devez pas appliquer :"
"c:func:`Py_INCREF` aux objets transmis à ces fonctions."

#: extending/extending.rst:152
msgid ""
"You can test non-destructively whether an exception has been set with :c:"
"func:`PyErr_Occurred`.  This returns the current exception object, or "
"``NULL`` if no exception has occurred.  You normally don't need to call :c:"
"func:`PyErr_Occurred` to see whether an error occurred in a function call, "
"since you should be able to tell from the return value."
msgstr ""
"Vous pouvez tester de manière non destructive si une exception a été levée "
"avec :c:func:`PyErr_Occurred`. Cela renvoie l'objet exception actuel, ou "
"``NULL`` si aucune exception n'a eu lieu. Cependant, vous ne devriez pas "
"avoir besoin d'appeler :c:func:`PyErr_Occurred` pour voir si une erreur est "
"survenue durant l'appel d'une fonction, puisque vous devriez être en mesure "
"de le déterminer à partir de la valeur renvoyée."

#: extending/extending.rst:158
#, fuzzy
msgid ""
"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 :c:func:`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 :c:func:"
"`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."
msgstr ""
"Lorsqu'une fonction *f* ayant appelé une autre fonction *g* détecte que "
"cette dernière a échoué, *f* devrait donner une valeur d'erreur à son tour "
"(habituellement ``NULL`` ou ``-1``). La fonction *f* ne devrait *pas* "
"appeler l'une des fonctions :c:func:`PyErr_\\*`, l'une d'entre elles ayant "
"déjà été appelée par *g*. La fonction appelant *f* est alors censée renvoyer "
"aussi un code d'erreur à celle qui l'a appelée, toujours sans utiliser :c:"
"func:`PyErr_\\*`, et ainsi de suite. La cause la plus détaillée de l'erreur "
"a déjà été signalée par la fonction l'ayant détecté en premier. Une fois "
"l'erreur remontée à la boucle principale de l'interpréteur Python, il "
"interrompt le code en cours d'exécution et essaie de trouver un gestionnaire "
"d'exception spécifié par le développeur Python."

#: extending/extending.rst:168
msgid ""
"(There are situations where a module can actually give a more detailed error "
"message by calling another :c:func:`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.)"
msgstr ""
"(Il y a des situations où un module peut effectivement donner un message "
"d'erreur plus détaillé en appelant une autre fonction :c:func:`PyErr_\\*`, "
"dans de tels cas, il est tout à fait possible de le faire. Cependant, ce "
"n'est généralement pas nécessaire, et peut amener à perdre des informations "
"sur la cause de l'erreur : la plupart des opérations peuvent échouer pour "
"tout un tas de raisons.)"

#: extending/extending.rst:174
msgid ""
"To ignore an exception set by a function call that failed, the exception "
"condition must be cleared explicitly by calling :c:func:`PyErr_Clear`.  The "
"only time C code should call :c:func:`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)."
msgstr ""
"Pour ignorer une exception qui aurait été émise lors d'un appel de fonction "
"qui aurait échoué, l'exception doit être retirée explicitement en appelant :"
"c:func:`PyErr_Clear`. Le seul cas pour lequel du code C devrait appeler :c:"
"func:`PyErr_Clear` est lorsqu'il ne veut pas passer l'erreur à "
"l'interpréteur, mais souhaite la gérer lui-même (peut-être en essayant "
"quelque chose d'autre, ou en prétendant que rien n'a mal tourné)."

#: extending/extending.rst:180
msgid ""
"Every failing :c:func:`malloc` call must be turned into an exception --- the "
"direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call :c:func:"
"`PyErr_NoMemory` and return a failure indicator itself.  All the object-"
"creating functions (for example, :c:func:`PyLong_FromLong`) already do this, "
"so this note is only relevant to those who call :c:func:`malloc` directly."
msgstr ""
"Chaque échec de :c:func:`malloc` doit être transformé en une exception, "
"l'appelant direct de :c:func:`malloc` (ou :c:func:`realloc`) doit appeler :c:"
"func:`PyErr_NoMemory` et prendre l'initiative de renvoyer une valeur "
"d'erreur. Toutes les fonctions construisant des objets (tels que :c:func:"
"`PyLong_FromLong`) le font déjà, donc cette note ne concerne que ceux qui "
"appellent :c:func:`malloc` directement."

#: extending/extending.rst:186
msgid ""
"Also note that, with the important exception of :c:func:`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."
msgstr ""
"Notez également que, à l'exception notable de :c:func:`PyArg_ParseTuple` et "
"compagnie, les fonctions qui renvoient leur statut sous forme d'entier "
"donnent généralement une valeur positive ou zéro en cas de succès et ``-1`` "
"en cas d'échec, comme les appels du système Unix."

#: extending/extending.rst:190
msgid ""
"Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or :"
"c:func:`Py_DECREF` calls for objects you have already created) when you "
"return an error indicator!"
msgstr ""
"Enfin, lorsque vous renvoyez un code d'erreur, n'oubliez pas faire un brin "
"de nettoyage (en appelant :c:func:`Py_XDECREF` ou :c:func:`Py_DECREF` avec "
"les objets que vous auriez déjà créés) !"

#: extending/extending.rst:194
msgid ""
"The choice of which exception to raise is entirely yours.  There are "
"predeclared C objects corresponding to all built-in Python exceptions, such "
"as :c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, "
"you should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` "
"to mean that a file couldn't be opened (that should probably be :c:data:"
"`PyExc_IOError`). If something's wrong with the argument list, the :c:func:"
"`PyArg_ParseTuple` function usually raises :c:data:`PyExc_TypeError`.  If "
"you have an argument whose value must be in a particular range or must "
"satisfy other conditions, :c:data:`PyExc_ValueError` is appropriate."
msgstr ""
"Le choix de l'exception à lever vous incombe. Il existe des objets C "
"correspondant à chaque exception Python, tel que :c:data:"
"`PyExc_ZeroDivisionError`, que vous pouvez utiliser directement. Choisissez "
"judicieusement vos exceptions, typiquement n'utilisez pas :c:data:"
"`PyExc_TypeError` pour indiquer qu'un fichier n'a pas pu être ouvert (qui "
"devrait probablement être :c:data:`PyExc_IOError`). Si quelque chose ne va "
"pas avec la liste des arguments, la fonction :c:func:`PyArg_ParseTuple` lève "
"habituellement une exception :c:data:`PyExc_TypeError`. Mais si vous avez un "
"argument dont la valeur doit être dans un intervalle particulier ou qui doit "
"satisfaire d'autres conditions, :c:data:`PyExc_ValueError` sera plus "
"appropriée."

#: extending/extending.rst:204
msgid ""
"You can also define a new exception that is unique to your module. For this, "
"you usually declare a static object variable at the beginning of your file::"
msgstr ""
"Vous pouvez également créer une exception spécifique à votre module. Pour "
"cela, déclarez simplement une variable statique au début de votre fichier ::"

#: extending/extending.rst:209
msgid ""
"and initialize it in your module's initialization function (:c:func:"
"`PyInit_spam`) with an exception object::"
msgstr ""
"et initialisez-la dans la fonction d'initialisation de votre module (:c:func:"
"`PyInit_spam`) avec un objet exception ::"

#: extending/extending.rst:233
msgid ""
"Note that the Python name for the exception object is :exc:`spam.error`.  "
"The :c:func:`PyErr_NewException` function may create a class with the base "
"class being :exc:`Exception` (unless another class is passed in instead of "
"``NULL``), described in :ref:`bltin-exceptions`."
msgstr ""
"Notez que le nom de l'exception en Python est :exc:`spam.error`. La "
"fonction :c:func:`PyErr_NewException` peut créer une classe héritant de :exc:"
"`Exception` (à moins qu'une autre classe ne lui soit fournie à la place de "
"``NULL``), voir :ref:`bltin-exceptions`."

#: extending/extending.rst:238
msgid ""
"Note also that the :c:data:`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 :c:data:"
"`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."
msgstr ""
"Notez également que la variable :c:data:`SpamError` contient une référence à "
"la nouvelle classe créée ; ceci est intentionnel ! Comme l'exception peut "
"être retirée du module par un code externe, une référence à la classe est "
"nécessaire pour assurer qu'il ne sera pas rejeté, causant :c:data:"
"`SpamError` et devenir un pointeur défaillant. Si cela se produirait, le C "
"code qui lève cette exception peut engendrer un *core dump* ou des effets "
"secondaires inattendus."

#: extending/extending.rst:245
msgid ""
"We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in "
"this sample."
msgstr ""
"Nous traiterons de l'utilisation de ``PyMODINIT_FUNC`` comme un type de "
"renvoi de fonction plus tard dans cette section."

#: extending/extending.rst:248
msgid ""
"The :exc:`spam.error` exception can be raised in your extension module using "
"a call to :c:func:`PyErr_SetString` as shown below::"
msgstr ""
"L'exception :exc:`spam.error` peut être levée dans votre module d'extension "
"en appelant :c:func:`PyErr_SetString` comme montré ci-dessous ::"

#: extending/extending.rst:271
msgid "Back to the Example"
msgstr "Retour vers l'exemple"

#: extending/extending.rst:273
msgid ""
"Going back to our example function, you should now be able to understand "
"this statement::"
msgstr ""
"En revenant vers notre fonction exemple, vous devriez maintenant être "
"capable de comprendre cette affirmation ::"

#: extending/extending.rst:279
msgid ""
"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 :c:func:`PyArg_ParseTuple`.  Otherwise the string value of "
"the argument has been copied to the local variable :c:data:`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 :c:data:`command` should "
"properly be declared as ``const char *command``)."
msgstr ""
"Elle renvoie ``NULL`` (l'indicateur d'erreur pour les fonctions renvoyant "
"des pointeurs d'objet) si une erreur est détectée dans la liste des "
"arguments, se fiant à l'exception définie par :c:func:`PyArg_ParseTuple`. "
"Autrement, la valeur chaîne de l'argument a été copiée dans la variable "
"locale :c:data:`command`. Il s'agit d'une attribution de pointeur et vous "
"n'êtes pas supposés modifier la chaîne vers laquelle il pointe (donc en C "
"Standard, la variable :c:data:`command` doit être clairement déclarée comme "
"``const char *command``)."

#: extending/extending.rst:287
msgid ""
"The next statement is a call to the Unix function :c:func:`system`, passing "
"it the string we just got from :c:func:`PyArg_ParseTuple`::"
msgstr ""
"La prochaine instruction est un appel à la fonction Unix :c:func:`system`, "
"en lui passant la chaîne que nous venons d'obtenir à partir de :c:func:"
"`PyArg_ParseTuple` ::"

#: extending/extending.rst:292
msgid ""
"Our :func:`spam.system` function must return the value of :c:data:`sts` as a "
"Python object.  This is done using the function :c:func:`PyLong_FromLong`. ::"
msgstr ""
"Notre fonction :func:`spam.system` doit renvoyer la valeur de :c:data:`sts` "
"comme un objet Python. Cela est effectué par l'utilisation de la fonction :c:"
"func:`PyLong_FromLong`. ::"

#: extending/extending.rst:297
msgid ""
"In this case, it will return an integer object.  (Yes, even integers are "
"objects on the heap in Python!)"
msgstr ""
"Dans ce cas, elle renverra un objet entier. (Oui, même les entiers sont des "
"objets dans le tas en Python !)"

#: extending/extending.rst:300
msgid ""
"If you have a C function that returns no useful argument (a function "
"returning :c:type:`void`), the corresponding Python function must return "
"``None``.   You need this idiom to do so (which is implemented by the :c:"
"macro:`Py_RETURN_NONE` macro)::"
msgstr ""
"Si vous avez une fonction C qui ne renvoie aucun argument utile (une "
"fonction renvoyant :c:type:`void`), la fonction Python correspondante doit "
"renvoyer ``None``. Vous aurez besoin de cette locution pour cela (qui est "
"implémentée par la macro :c:macro:`Py_RETURN_NONE`) ::"

#: extending/extending.rst:308
msgid ""
":c:data:`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."
msgstr ""
":c:data:`Py_None` est la dénomination en C pour l'objet spécial Python "
"``None``. C'est un authentique objet Python plutôt qu'un pointeur ``NULL``, "
"qui signifie qu'une erreur est survenue, dans la plupart des situations, "
"comme nous l'avons vu."

#: extending/extending.rst:316
msgid "The Module's Method Table and Initialization Function"
msgstr "La fonction d'initialisation et le tableau des méthodes du module"

#: extending/extending.rst:318
msgid ""
"I promised to show how :c:func:`spam_system` is called from Python programs. "
"First, we need to list its name and address in a \"method table\"::"
msgstr ""
"Nous avons promis de montrer comment :c:func:`spam_system` est appelée "
"depuis les programmes Python. D'abord, nous avons besoin d'avoir son nom et "
"son adresse dans un « tableau des méthodes » ::"

#: extending/extending.rst:329
msgid ""
"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 :c:func:`PyArg_ParseTuple` "
"is used."
msgstr ""
"Notez la troisième entrée (``METH_VARARGS``). C'est un indicateur du type de "
"convention à utiliser pour la fonction C, à destination de l'interpréteur. "
"Il doit valoir normalement ``METH_VARARGS`` ou ``METH_VARARGS | "
"METH_KEYWORDS`` ; la valeur ``0`` indique qu'une variante obsolète de :c:"
"func:`PyArg_ParseTuple` est utilisée."

#: extending/extending.rst:334
msgid ""
"When using only ``METH_VARARGS``, the function should expect the Python-"
"level parameters to be passed in as a tuple acceptable for parsing via :c:"
"func:`PyArg_ParseTuple`; more information on this function is provided below."
msgstr ""
"Si seulement ``METH_VARARGS`` est utilisé, la fonction s'attend à ce que les "
"paramètres Python soient passés comme un *n*-uplet que l'on peut analyser "
"*via* :c:func:`PyArg_ParseTuple` ; des informations supplémentaires sont "
"fournies plus bas."

#: extending/extending.rst:338
msgid ""
"The :const:`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 :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments "
"to such a function."
msgstr ""
"Le bit :const:`METH_KEYWORDS` peut être mis à un dans le troisième champ si "
"des arguments par mots-clés doivent être passés à la fonction. Dans ce cas, "
"la fonction C doit accepter un troisième paramètre ``PyObject *`` qui est un "
"dictionnaire des mots-clés. Utilisez :c:func:`PyArg_ParseTupleAndKeywords` "
"pour analyser les arguments d'une telle fonction."

#: extending/extending.rst:344
msgid ""
"The method table must be referenced in the module definition structure::"
msgstr ""
"Le tableau des méthodes doit être référencé dans la structure de définition "
"du module ::"

#: extending/extending.rst:355
msgid ""
"This structure, in turn, must be passed to the interpreter in the module's "
"initialization function.  The initialization function must be named :c:func:"
"`PyInit_name`, where *name* is the name of the module, and should be the "
"only non-\\ ``static`` item defined in the module file::"
msgstr ""
"Cette structure, à son tour, doit être transmise à l'interpréteur dans la "
"fonction d'initialisation du module.  La fonction d'initialisation doit être "
"nommée :c:func:`PyInit_name`, où *nom* est le nom du module, et doit être le "
"seul élément non ``static`` défini dans le fichier du module ::"

#: extending/extending.rst:366
msgid ""
"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\"``."
msgstr ""
"Notez que *PyMODINIT_FUNC* déclare la fonction comme renvoyant un objet de "
"type ``PyObject *``, et déclare également toute déclaration de liaison "
"spéciale requise par la plate-forme, et pour le C++ déclare la fonction "
"comme un C ``extern``."

#: extending/extending.rst:370
msgid ""
"When the Python program imports module :mod:`spam` for the first time, :c:"
"func:`PyInit_spam` is called. (See below for comments about embedding "
"Python.) It calls :c:func:`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 :c:type:`PyMethodDef` structures) found in the "
"module definition. :c:func:`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``."
msgstr ""
"Lorsque le programme Python importe le module :mod:`spam` pour la première "
"fois, :c:func:`PyInit_spam` est appelé. (Voir ci-dessous pour les "
"commentaires sur l'intégration en Python.) Il appelle :c:func:"
"`PyModule_Create`, qui renvoie un objet module, et insère des objets "
"fonction intégrés dans le module nouvellement créé en se basant sur la table "
"(un tableau de structures :c:type:`PyMethodDef`) trouvée dans la définition "
"du module. :c:func:`PyModule_Create` renvoie un pointeur vers l'objet module "
"qu'il crée. Il peut s'interrompre avec une erreur fatale pour certaines "
"erreurs, ou renvoyer ``NULL`` si le module n'a pas pu être initialisé de "
"manière satisfaisante. La fonction `*init* doit renvoyer l'objet module à "
"son appelant, afin qu'il soit ensuite inséré dans ``sys.modules``."

#: extending/extending.rst:381
msgid ""
"When embedding Python, the :c:func:`PyInit_spam` function is not called "
"automatically unless there's an entry in the :c:data:`PyImport_Inittab` "
"table. To add the module to the initialization table, use :c:func:"
"`PyImport_AppendInittab`, optionally followed by an import of the module::"
msgstr ""
"Lors de l'intégration de Python, la fonction :c:func:`PyInit_spam` n'est pas "
"appelée automatiquement, sauf s'il y a une entrée dans la table :c:data:"
"`PyImport_Inittab`. Pour ajouter le module à la table d'initialisation, "
"utilisez :c:func:`PyImport_AppendInittab`, suivi éventuellement d'une "
"importation du module ::"

#: extending/extending.rst:425
msgid ""
"Removing entries from ``sys.modules`` or importing compiled modules into "
"multiple interpreters within a process (or following a :c:func:`fork` "
"without an intervening :c:func:`exec`) can create problems for some "
"extension modules. Extension module authors should exercise caution when "
"initializing internal data structures."
msgstr ""
"Supprimer des entrées de ``sys.modules`` ou importer des modules compilés "
"dans plusieurs interpréteurs au sein d'un processus (ou suivre un :c:func:"
"`fork` sans l'intervention d'un :c:func:`exec`) peut créer des problèmes "
"pour certains modules d'extension. Les auteurs de modules d'extension "
"doivent faire preuve de prudence lorsqu'ils initialisent des structures de "
"données internes."

#: extending/extending.rst:431
msgid ""
"A more substantial example module is included in the Python source "
"distribution as :file:`Modules/xxmodule.c`.  This file may be used as a  "
"template or simply read as an example."
msgstr ""
"Un exemple de module plus substantiel est inclus dans la distribution des "
"sources Python sous le nom :file:`Modules/xxmodule.c`. Ce fichier peut être "
"utilisé comme modèle ou simplement lu comme exemple."

#: extending/extending.rst:437
msgid ""
"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`."
msgstr ""
"Contrairement à notre exemple de ``spam``, ``xxmodule`` utilise une "
"*initialisation multi-phase* (nouveau en Python 3.5), où une structure "
"*PyModuleDef* est renvoyée à partir de ``PyInit_spam``, et la création du "
"module est laissée au mécanisme d'importation. Pour plus de détails sur "
"l'initialisation multi-phase, voir :PEP:`489`."

#: extending/extending.rst:446
msgid "Compilation and Linkage"
msgstr "Compilation et liaison"

#: extending/extending.rst:448
msgid ""
"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 :ref:"
"`building`) and additional information that pertains only to building on "
"Windows (chapter :ref:`building-on-windows`) for more information about this."
msgstr ""

#: extending/extending.rst:455
msgid ""
"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 (:file:`spammodule.c` for example) in "
"the :file:`Modules/` directory of an unpacked source distribution, add a "
"line to the file :file:`Modules/Setup.local` describing your file:"
msgstr ""

#: extending/extending.rst:466
msgid ""
"and rebuild the interpreter by running :program:`make` in the toplevel "
"directory.  You can also run :program:`make` in the :file:`Modules/` "
"subdirectory, but then you must first rebuild :file:`Makefile` there by "
"running ':program:`make` Makefile'.  (This is necessary each time you change "
"the :file:`Setup` file.)"
msgstr ""

#: extending/extending.rst:472
msgid ""
"If your module requires additional libraries to link with, these can be "
"listed on the line in the configuration file as well, for instance:"
msgstr ""

#: extending/extending.rst:483
msgid "Calling Python Functions from C"
msgstr "Appeler des fonctions Python en C"

#: extending/extending.rst:485
msgid ""
"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."
msgstr ""

#: extending/extending.rst:493
msgid ""
"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 :option:`-c` command "
"line option in :file:`Modules/main.c` from the Python source code.)"
msgstr ""

#: extending/extending.rst:499
msgid ""
"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 :c:func:`Py_INCREF` it!) in a "
"global variable --- or wherever you see fit. For example, the following "
"function might be part of a module definition::"
msgstr ""

#: extending/extending.rst:529
msgid ""
"This function must be registered with the interpreter using the :const:"
"`METH_VARARGS` flag; this is described in section :ref:`methodtable`.  The :"
"c:func:`PyArg_ParseTuple` function and its arguments are documented in "
"section :ref:`parsetuple`."
msgstr ""
"Cette fonction doit être déclarée en utilisant le drapeau :const:"
"`METH_VARARGS` ; ceci est décrit dans la section :ref:`methodtable`.  La "
"fonction :c:func:`PyArg_ParseTuple` et ses arguments sont documentés dans la "
"section :ref:`parsetuple`."

#: extending/extending.rst:534
msgid ""
"The macros :c:func:`Py_XINCREF` and :c:func:`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 :ref:`refcounts`."
msgstr ""
"Les macros :c:func:`Py_XINCREF` et :c:func:`Py_XDECREF` incrémentent/"
"décrémentent le compteur des références d'un objet et sont sûres quant à la "
"présence de pointeurs ``NULL`` (mais notez que *temp* ne sera pas ``NULL`` "
"dans ce contexte).  Plus d'informations à ce sujet dans la section :ref:"
"`refcounts`."

#: extending/extending.rst:541
msgid ""
"Later, when it is time to call the function, you call the C function :c:func:"
"`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. :c:"
"func:`Py_BuildValue` returns a tuple when its format string consists of zero "
"or more format codes between parentheses.  For example::"
msgstr ""

#: extending/extending.rst:561
msgid ""
":c:func:`PyObject_CallObject` returns a Python object pointer: this is the "
"return value of the Python function.  :c:func:`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 :c:func:"
"`Py_DECREF`\\ -ed immediately after the :c:func:`PyObject_CallObject` call."
msgstr ""

#: extending/extending.rst:568
msgid ""
"The return value of :c:func:`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 :c:func:`Py_DECREF` the result, even (especially!) if you are "
"not interested in its value."
msgstr ""

#: extending/extending.rst:574
msgid ""
"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 :c:func:`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 :c:func:`PyErr_Clear`.  For example::"
msgstr ""
"Mais avant de le faire, il est important de vérifier que la valeur renvoyée "
"n'est pas ``NULL``.  Si c'est le cas, la fonction Python s'est terminée par "
"la levée d'une exception. Si le code C qui a appelé :c:func:"
"`PyObject_CallObject` est appelé depuis Python, il devrait maintenant "
"renvoyer une indication d'erreur à son appelant Python, afin que "
"l'interpréteur puisse afficher la pile d'appels, ou que le code Python "
"appelant puisse gérer l'exception. Si cela n'est pas possible ou "
"souhaitable, l'exception doit être effacée en appelant :c:func:"
"`PyErr_Clear`. Par exemple ::"

#: extending/extending.rst:587
msgid ""
"Depending on the desired interface to the Python callback function, you may "
"also have to provide an argument list to :c:func:`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 :c:func:`Py_BuildValue`.  For example, if "
"you want to pass an integral event code, you might use the following code::"
msgstr ""
"Selon l'interface souhaitée pour la fonction de rappel Python, vous devrez "
"peut-être aussi fournir une liste d'arguments à :c:func:"
"`PyObject_CallObject`. Dans certains cas, la liste d'arguments est également "
"fournie par le programme Python, par l'intermédiaire de la même interface "
"qui a spécifié la fonction de rappel. Elle peut alors être sauvegardée et "
"utilisée de la même manière que l'objet fonction. Dans d'autres cas, vous "
"pouvez avoir à construire un nouveau n-uplet à passer comme liste "
"d'arguments. La façon la plus simple de faire cela est d'appeler :c:func:"
"`Py_BuildValue`. Par exemple, si vous voulez passer un code d'événement "
"intégral, vous pouvez utiliser le code suivant ::"

#: extending/extending.rst:606
msgid ""
"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: :c:func:`Py_BuildValue` may run out of memory, and this should be "
"checked."
msgstr ""

#: extending/extending.rst:610
msgid ""
"You may also call a function with keyword arguments by using :c:func:"
"`PyObject_Call`, which supports arguments and keyword arguments.  As in the "
"above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::"
msgstr ""
"Vous pouvez également appeler une fonction avec des arguments nommés en "
"utilisant :c:func:`PyObject_Call`, qui accepte les arguments et les "
"arguments nommés. Comme dans l'exemple ci-dessus, nous utilisons :c:func:"
"`Py_BuildValue` pour construire le dictionnaire. ::"

#: extending/extending.rst:628
msgid "Extracting Parameters in Extension Functions"
msgstr "Extraire des paramètres dans des fonctions d'extension"

#: extending/extending.rst:632
msgid "The :c:func:`PyArg_ParseTuple` function is declared as follows::"
msgstr "La fonction :c:func:`PyArg_ParseTuple` est déclarée ainsi ::"

#: extending/extending.rst:636
msgid ""
"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 :ref:`arg-parsing` in the Python/C API "
"Reference Manual.  The remaining arguments must be addresses of variables "
"whose type is determined by the format string."
msgstr ""

#: extending/extending.rst:642
msgid ""
"Note that while :c:func:`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!"
msgstr ""

#: extending/extending.rst:647
msgid ""
"Note that any Python object references which are provided to the caller are "
"*borrowed* references; do not decrement their reference count!"
msgstr ""
"Notez que n'importe quelles références sur un objet Python qui sont données "
"à l'appelant sont des références *empruntées* ; ne décrémentez pas leur "
"compteur de références !"

#: extending/extending.rst:650
msgid "Some example calls::"
msgstr "Quelques exemples d'appels ::"

#: extending/extending.rst:720
msgid "Keyword Parameters for Extension Functions"
msgstr "Paramètres nommés pour des fonctions d'extension"

#: extending/extending.rst:724
msgid ""
"The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::"
msgstr ""
"La fonction :c:func:`PyArg_ParseTupleAndKeywords` est déclarée ainsi ::"

#: extending/extending.rst:729
msgid ""
"The *arg* and *format* parameters are identical to those of the :c:func:"
"`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, :c:func:"
"`PyArg_ParseTupleAndKeywords` returns true, otherwise it returns false and "
"raises an appropriate exception."
msgstr ""
"Les paramètres *arg* et *format* sont identiques à ceux de la fonction :c:"
"func:`PyArg_ParseTuple`. Le paramètre *kwdict* est le dictionnaire de mots-"
"clés reçu comme troisième paramètre du *runtime* Python. Le paramètre "
"*kwlist* est une liste de chaînes de caractères terminée par ``NULL`` qui "
"identifie les paramètres ; les noms sont mis en correspondance, de gauche à "
"droite, avec les informations de type de *format*. En cas de succès du "
"processus, :c:func:`PyArg_ParseTupleAndKeywords` renvoie vrai, sinon il "
"renvoie faux et lève une exception appropriée."

#: extending/extending.rst:739
msgid ""
"Nested tuples cannot be parsed when using keyword arguments!  Keyword "
"parameters passed in which are not present in the *kwlist* will cause :exc:"
"`TypeError` to be raised."
msgstr ""
"Les n-uplets imbriqués ne peuvent pas être traités lorsqu'on utilise des "
"arguments de type mot-clé ! Ceux-ci doivent apparaître dans dans *kwlist*, "
"dans le cas contraire une exception :exc:`TypeError` est levée."

#: extending/extending.rst:745
msgid ""
"Here is an example module which uses keywords, based on an example by Geoff "
"Philbrick (philbrick@hks.com)::"
msgstr ""
"Voici un exemple de module qui utilise des mots-clés, basé sur un exemple de "
"*Geoff Philbrick* (philbrick@hks.com) ::"

#: extending/extending.rst:800
msgid "Building Arbitrary Values"
msgstr "Créer des valeurs arbitraires"

#: extending/extending.rst:802
msgid ""
"This function is the counterpart to :c:func:`PyArg_ParseTuple`.  It is "
"declared as follows::"
msgstr ""
"Cette fonction est le complément de :c:func:`PyArg_ParseTuple`.  Elle est "
"déclarée comme suit ::"

#: extending/extending.rst:807
msgid ""
"It recognizes a set of format units similar to the ones recognized by :c:"
"func:`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."
msgstr ""
"Il reconnaît un ensemble d'unités de format similaires à celles reconnues "
"par :c:func:`PyArg_ParseTuple`, mais les arguments (qui sont les données en "
"entrée de fonction, et non de la sortie) ne doivent pas être des pointeurs, "
"mais juste des valeurs. Il renvoie un nouvel objet Python, adapté pour être "
"renvoyé par une fonction C appelée depuis Python."

#: extending/extending.rst:812
#, fuzzy
msgid ""
"One difference with :c:func:`PyArg_ParseTuple`: while the latter requires "
"its first argument to be a tuple (since Python argument lists are always "
"represented as tuples internally), :c:func:`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."
msgstr ""
"Une différence par rapport à :c:func:`PyArg_ParseTuple` : alors que ce "
"dernier nécessite que son premier argument soit un *n*-uplet (puisque les "
"listes d'arguments Python sont toujours représentées par des *n*-uplets en "

#: extending/extending.rst:820
msgid ""
"Examples (to the left the call, to the right the resulting Python value):"
msgstr ""
"Exemples (à gauche l'appel, à droite la valeur résultante, en Python) :"

#: extending/extending.rst:846
msgid "Reference Counts"
msgstr "Compteurs de références"

#: extending/extending.rst:848
msgid ""
"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 :c:func:`malloc` and :c:func:`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."
msgstr ""
"Dans les langages comme le C ou le C++, le développeur est responsable de "
"l'allocation dynamique et de la dés-allocation de la mémoire sur le tas. En "
"C, cela se fait à l'aide des fonctions :c:func:`malloc` et :c:func:`free`. "
"En C++, les opérateurs  ``new`` et ``delete``  sont utilisés avec "
"essentiellement la même signification et nous limiterons la discussion "
"suivante au cas du C."

#: extending/extending.rst:854
msgid ""
"Every block of memory allocated with :c:func:`malloc` should eventually be "
"returned to the pool of available memory by exactly one call to :c:func:"
"`free`. It is important to call :c:func:`free` at the right time.  If a "
"block's address is forgotten but :c:func:`free` is not called for it, the "
"memory it occupies cannot be reused until the program terminates.  This is "
"called a :dfn:`memory leak`.  On the other hand, if a program calls :c:func:"
"`free` for a block and then continues to use the block, it creates a "
"conflict with re-use of the block through another :c:func:`malloc` call.  "
"This is called :dfn:`using freed memory`. It has the same bad consequences "
"as referencing uninitialized data --- core dumps, wrong results, mysterious "
"crashes."
msgstr ""

#: extending/extending.rst:865
msgid ""
"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."
msgstr ""

#: extending/extending.rst:878
msgid ""
"Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it "
"needs a strategy to avoid memory leaks as well as the use of freed memory.  "
"The chosen method is called :dfn:`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."
msgstr ""
"Comme Python fait un usage intensif de :c:func:`malloc` et de :c:func:"
"`free`, il a besoin d'une stratégie pour éviter les fuites de mémoire ainsi "
"que l'utilisation de la mémoire libérée. La méthode choisie est appelée :dfn:"
"`reference counting`. Le principe est simple : chaque objet contient un "
"compteur, qui est incrémenté lorsqu'une référence à l'objet est stockée "
"quelque part, et qui est décrémenté lorsqu'une référence à celui-ci est "
"supprimée. Lorsque le compteur atteint zéro, la dernière référence à l'objet "
"a été supprimée et l'objet est libéré."

#: extending/extending.rst:886
msgid ""
"An alternative strategy is called :dfn:`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 :c:func:`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 :c:func:`malloc` and :c:func:`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."
msgstr ""
"Une stratégie alternative est appelée :dfn:`automatic garbage collection` "
"(ramasse-miettes). Parfois, le comptage des références est également appelé "
"stratégie de ramasse-miettes, d'où l'utilisation du terme \"automatique\" "
"pour distinguer les deux. Le grand avantage du ramasse-miettes est que "
"l'utilisateur n'a pas besoin d'appeler :c:func:`free` explicitement. (Un "
"autre avantage important est l'amélioration de la vitesse ou de "
"l'utilisation de la mémoire, ce n'est cependant pas un fait avéré). "
"L'inconvénient est que pour C, il n'y a pas de ramasse-miettes portable "
"proprement-dit, alors que le comptage des références peut être implémenté de "
"façon portable (tant que les fonctions :c:func:`malloc` et :c:func:`free` "
"soient disponibles, ce que la norme C garantit). Peut-être qu'un jour un "
"ramasse-miettes suffisamment portable sera disponible pour C. D'ici là, nous "
"devrons utiliser les compteurs des références."

#: extending/extending.rst:898
msgid ""
"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."
msgstr ""
"Bien que Python utilise l'implémentation traditionnelle de comptage de "
"référence, il contient également un détecteur de cycles qui fonctionne pour "
"détecter les cycles de référence. Cela permet aux applications d'empêcher la "
"création de références circulaires directes ou indirectes ; ceci sont les "
"faiblesses du ramasse-miettes mis en œuvre en utilisant uniquement le "
"comptage de référence. Les cycles de référence sont constitués d'objets qui "
"contiennent des références (éventuellement indirectes) à eux-mêmes, de sorte "
"que chaque objet du cycle a un comptage de référence qui n'est pas nul. Les "
"implémentations typiques de comptage de référence ne sont pas capables de "
"récupérer la mémoire appartenant à des objets dans un cycle de référence, ou "
"référencés à partir des objets dans le cycle, même s'il n'y a pas d'autres "
"références au cycle lui-même."

#: extending/extending.rst:909
msgid ""
"The cycle detector is able to detect garbage cycles and can reclaim them. "
"The :mod:`gc` module exposes a way to run the detector (the :func:`~gc."
"collect` function), as well as configuration interfaces and the ability to "
"disable the detector at runtime."
msgstr ""

#: extending/extending.rst:918
msgid "Reference Counting in Python"
msgstr "Comptage de références en Python"

#: extending/extending.rst:920
msgid ""
"There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle "
"the incrementing and decrementing of the reference count. :c:func:"
"`Py_DECREF` also frees the object when the count reaches zero. For "
"flexibility, it doesn't call :c:func:`free` directly --- rather, it makes a "
"call through a function pointer in the object's :dfn:`type object`.  For "
"this purpose (and others), every object also contains a pointer to its type "
"object."
msgstr ""
"Il existe deux macros, ``Py_INCREF(x)`` et ``Py_DECREF(x)``, qui gèrent "
"l'incrémentation et la décrémentation du comptage de référence. :c:func:"
"`Py_DECREF` libère également l'objet lorsque le comptage atteint zéro. Pour "
"plus de flexibilité, il n'appelle pas :c:func:`free` directement — plutôt, "
"il fait un appel à travers un pointeur de fonction dans l'objet :dfn:`type "
"objet` de l'objet.  À cette fin (et pour d'autres), chaque objet contient "
"également un pointeur vers son objet type."

#: extending/extending.rst:927
msgid ""
"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 :dfn:`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 :c:func:`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 :c:func:`Py_DECREF`. Forgetting to dispose of an owned "
"reference creates a memory leak."
msgstr ""
"La grande question demeure maintenant : quand utiliser ``Py_INCREF(x)`` et "
"``Py_DECREF(x)`` ? Commençons par définir quelques termes. Personne ne "
"possède un objet, mais vous pouvez en :dfn:`avoir une référence`. Le "
"comptage de références d'un objet est maintenant défini comme étant le "
"nombre de références à cet objet. Le propriétaire d'une référence est "
"responsable d'appeler :c:func:`Py_DECREF` lorsque la référence n'est plus "
"nécessaire. La propriété d'une référence peut être transférée. Il y a trois "
"façons de disposer d'une référence : la transmettre, la stocker, ou appeler :"
"c:func:`Py_DECREF`. Oublier de se débarrasser d'une référence crée une fuite "
"de mémoire."

#: extending/extending.rst:936
msgid ""
"It is also possible to :dfn:`borrow` [#]_ a reference to an object.  The "
"borrower of a reference should not call :c:func:`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 [#]_."
msgstr ""

#: extending/extending.rst:942
msgid ""
"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."
msgstr ""
"L'avantage d'emprunter, plutôt qu'être propriétaire d'une référence est que "
"vous n'avez pas à vous soucier de disposer de la référence sur tous les "
"chemins possibles dans le code — en d'autres termes, avec une référence "
"empruntée, vous ne courez pas le risque de fuites lors d'une sortie "
"prématurée. L'inconvénient de l'emprunt par rapport à la possession est "
"qu'il existe certaines situations subtiles où, dans un code apparemment "
"correct, une référence empruntée peut être utilisée après que le "
"propriétaire auquel elle a été empruntée l'a en fait éliminée."

#: extending/extending.rst:950
msgid ""
"A borrowed reference can be changed into an owned reference by calling :c:"
"func:`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)."
msgstr ""

#: extending/extending.rst:960
msgid "Ownership Rules"
msgstr "Règles concernant la propriété de références"

#: extending/extending.rst:962
msgid ""
"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."
msgstr ""
"Chaque fois qu'une référence d'objet est passée à l'intérieur ou à "
"l'extérieur d'une fonction, elle fait partie de la spécification de "
"l'interface de la fonction, peu importe que la propriété soit transférée "
"avec la référence ou non."

#: extending/extending.rst:966
msgid ""
"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 :c:func:`PyLong_FromLong` and :c:func:`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, :c:"
"func:`PyLong_FromLong` maintains a cache of popular values and can return a "
"reference to a cached item."
msgstr ""

#: extending/extending.rst:974
msgid ""
"Many functions that extract objects from other objects also transfer "
"ownership with the reference, for instance :c:func:"
"`PyObject_GetAttrString`.  The picture is less clear, here, however, since a "
"few common routines are exceptions: :c:func:`PyTuple_GetItem`, :c:func:"
"`PyList_GetItem`, :c:func:`PyDict_GetItem`, and :c:func:"
"`PyDict_GetItemString` all return references that you borrow from the tuple, "
"list or dictionary."
msgstr ""

#: extending/extending.rst:981
msgid ""
"The function :c:func:`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``."
msgstr ""

#: extending/extending.rst:985
msgid ""
"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 :c:func:`Py_INCREF` to become an independent owner.  There are exactly "
"two important exceptions to this rule: :c:func:`PyTuple_SetItem` and :c:func:"
"`PyList_SetItem`.  These functions take over ownership of the item passed to "
"them --- even if they fail!  (Note that :c:func:`PyDict_SetItem` and friends "
"don't take over ownership --- they are \"normal.\")"
msgstr ""

#: extending/extending.rst:993
msgid ""
"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 :c:func:`Py_INCREF`."
msgstr ""

#: extending/extending.rst:999
msgid ""
"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."
msgstr ""

#: extending/extending.rst:1007
msgid "Thin Ice"
msgstr "Terrain dangereux"

#: extending/extending.rst:1009
msgid ""
"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."
msgstr ""
"Il existe quelques situations où l'utilisation apparemment inoffensive d'une "
"référence empruntée peut entraîner des problèmes. Tous ces problèmes sont en "
"lien avec des invocations implicites de l’interpréteur, et peuvent amener le "
"propriétaire d'une référence à s'en défaire."

#: extending/extending.rst:1013
msgid ""
"The first and most important case to know about is using :c:func:`Py_DECREF` "
"on an unrelated object while borrowing a reference to a list item.  For "
"instance::"
msgstr ""
"Le premier cas, et le plus important à connaître, est celui de l'application "
"de :c:func:`Py_DECREF` à un objet non relié, tout en empruntant une "
"référence à un élément de liste. Par exemple ::"

#: extending/extending.rst:1025
msgid ""
"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!"
msgstr ""
"Cette fonction emprunte d'abord une référence à  ``list[0]``, puis remplace  "
"``list[1]`` par la valeur  ``0``, et enfin affiche la référence empruntée. "
"Ça a l'air inoffensif, n'est-ce pas ? Mais ce n'est pas le cas !"

#: extending/extending.rst:1029
msgid ""
"Let's follow the control flow into :c:func:`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 :meth:`__del__` method.  If this class instance has a reference "
"count of 1, disposing of it will call its :meth:`__del__` method."
msgstr ""
"Suivons le flux de contrôle dans :c:func:`PyList_SetItem`. La liste possède "
"des références à tous ses éléments, donc quand l'élément 1 est remplacé, "
"elle doit se débarrasser de l'élément 1 original.  Supposons maintenant que "
"l'élément 1 original était une instance d'une classe définie par "
"l'utilisateur, et supposons en outre que la classe définisse une méthode :"
"meth:`__del__`.  Si l'instance de cette classe a un nombre des références de "
"1, sa destruction appellera sa méthode :meth:`__del__`."

#: extending/extending.rst:1036
msgid ""
"Since it is written in Python, the :meth:`__del__` method can execute "
"arbitrary Python code.  Could it perhaps do something to invalidate the "
"reference to ``item`` in :c:func:`bug`?  You bet!  Assuming that the list "
"passed into :c:func:`bug` is accessible to the :meth:`__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``."
msgstr ""
"Comme elle est écrite en Python, la méthode :meth:`__del__` peut exécuter du "
"code Python arbitraire. Pourrait-elle faire quelque chose pour invalider la "
"référence à ``item`` dans :c:func:`bug` ? Bien sûr ! En supposant que la "
"liste passée dans :c:func:`bug` est accessible à la méthode :meth:`__del__`, "
"elle pourrait exécuter une instruction à l'effet de ``del list[0]``, et en "
"supposant que ce soit la dernière référence à cet objet, elle libérerait la "
"mémoire qui lui est associée, invalidant ainsi ``item``."

#: extending/extending.rst:1044
msgid ""
"The solution, once you know the source of the problem, is easy: temporarily "
"increment the reference count.  The correct version of the function reads::"
msgstr ""

#: extending/extending.rst:1058
msgid ""
"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 :meth:`__del__` methods would fail..."
msgstr ""

#: extending/extending.rst:1062
msgid ""
"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 :c:macro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it "
"using :c:macro:`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::"
msgstr ""
"Le deuxième cas de problèmes liés à une référence empruntée est une variante "
"impliquant des fils de discussion. Normalement, plusieurs threads dans "
"l'interpréteur Python ne peuvent pas se gêner mutuellement, car il existe un "
"verrou global protégeant tout l'espace objet de Python. Cependant, il est "
"possible de libérer temporairement ce verrou en utilisant la macro :c:macro:"
"`Py_BEGIN_ALLOW_THREADS`, et de le ré-acquérir en utilisant :c:macro:"
"`Py_END_ALLOW_THREADS`. Ceci est un procédé courant pour bloquer les appels "
"d'entrées/sorties, afin de permettre aux autres threads d'utiliser le "
"processeur en attendant que les E/S soient terminées. Évidemment, la "
"fonction suivante a le même problème que la précédente ::"

#: extending/extending.rst:1085
msgid "NULL Pointers"
msgstr "Pointeurs ``NULL``"

#: extending/extending.rst:1087
msgid ""
"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."
msgstr ""
"En général, les fonctions qui prennent des références d'objets comme "
"arguments ne sont pas conçues pour recevoir des pointeurs ``NULL``, et si "
"vous en donnez comme arguments, elles causeront une erreur de segmentation "
"(ou provoqueront des *core dump* ultérieurs). Les fonctions qui renvoient "
"des références d'objets renvoient généralement ``NULL`` uniquement pour "
"indiquer qu'une exception s'est produite.  La raison pour laquelle les "
"arguments ``NULL`` ne sont pas testés est que les fonctions passent souvent "
"les objets qu'elles reçoivent à d'autres fonctions, si chaque fonction "
"devait tester pour ``NULL``, il y aurait beaucoup de tests redondants et le "
"code s'exécuterait plus lentement."

#: extending/extending.rst:1095
msgid ""
"It is better to test for ``NULL`` only at the \"source:\" when a pointer "
"that may be ``NULL`` is received, for example, from :c:func:`malloc` or from "
"a function that may raise an exception."
msgstr ""
"Il est préférable de tester la présence de ``NULL`` uniquement au début : "
"lorsqu'un pointeur qui peut être ``NULL`` est reçu, par exemple, de :c:func:"
"`malloc` ou d'une fonction qui peut lever une exception."

#: extending/extending.rst:1099
msgid ""
"The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for "
"``NULL`` pointers --- however, their variants :c:func:`Py_XINCREF` and :c:"
"func:`Py_XDECREF` do."
msgstr ""
"Les macros :c:func:`Py_INCREF` et :c:func:`Py_DECREF` ne vérifient pas les "
"pointeurs ``NULL``. Cependant, leurs variantes :c:func:`Py_XINCREF` et :c:"
"func:`Py_XDECREF` le font."

#: extending/extending.rst:1103
msgid ""
"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."
msgstr ""

#: extending/extending.rst:1109
msgid ""
"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 [#]_."
msgstr ""
"Le mécanisme d'appel de fonctions C garantit que la liste d'arguments passée "
"aux fonctions C (``args`` dans les exemples) n'est jamais ``NULL``. En fait, "
"il garantit qu'il s'agit toujours d'un n-uplet [#]_."

#: extending/extending.rst:1113
msgid ""
"It is a severe error to ever let a ``NULL`` pointer \"escape\" to the Python "
"user."
msgstr ""
"C'est une grave erreur de laisser un pointeur ``NULL`` \"échapper\" à "
"l'utilisateur Python."

#: extending/extending.rst:1124
msgid "Writing Extensions in C++"
msgstr "Écrire des extensions en C++"

#: extending/extending.rst:1126
msgid ""
"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)."
msgstr ""
"C'est possible d'écrire des modules d'extension en C++, mais sous certaines "
"conditions. Si le programme principal (l'interpréteur Python) est compilé et "
"lié par le compilateur C, les objets globaux ou statiques avec les "
"constructeurs ne peuvent pas être utilisés. Ceci n'est pas un problème si le "
"programme principal est relié par le compilateur C++. Les fonctions qui "
"seront appelées par l'interpréteur Python (en particulier, les fonctions "
"d'initialisation des modules) doivent être déclarées en utilisant ``extern "
"\"C\"``. Il n'est pas nécessaire d'inclure les fichiers d'en-tête Python "
"dans le ``extern \"C\" {…}``, car ils utilisent déjà ce format si le symbole "
"``__cplusplus`` est défini (tous les compilateurs C++ récents définissent ce "
"symbole)."

#: extending/extending.rst:1140
msgid "Providing a C API for an Extension Module"
msgstr "Fournir une API en langage C pour un module d'extension"

#: extending/extending.rst:1145
msgid ""
"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."
msgstr ""
"De nombreux modules d'extension fournissent simplement de nouvelles "
"fonctions et de nouveaux types à utiliser à partir de Python, mais parfois "
"le code d'un module d'extension peut être utile pour d'autres modules "
"d'extension. Par exemple, un module d'extension peut mettre en œuvre un type "
"\"collection\" qui fonctionne comme des listes sans ordre. Tout comme le "
"type de liste Python standard possède une API C qui permet aux modules "
"d'extension de créer et de manipuler des listes, ce nouveau type de "
"collection devrait posséder un ensemble de fonctions C pour une manipulation "
"directe à partir d'autres modules d'extension."

#: extending/extending.rst:1153
msgid ""
"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!"
msgstr ""
"À première vue, cela semble facile : il suffit d'écrire les fonctions (sans "
"les déclarer \"statiques\", bien sûr), de fournir un fichier d'en-tête "
"approprié et de documenter l'API C. Et en fait, cela fonctionnerait si tous "
"les modules d'extension étaient toujours liés statiquement avec "
"l'interpréteur Python. Cependant, lorsque les modules sont utilisés comme "
"des bibliothèques partagées, les symboles définis dans un module peuvent ne "
"pas être visibles par un autre module. Les détails de la visibilité "
"dépendent du système d'exploitation ; certains systèmes utilisent un espace "
"de noms global pour l'interpréteur Python et tous les modules d'extension "
"(Windows, par exemple), tandis que d'autres exigent une liste explicite des "
"symboles importés au moment de la liaison des modules (AIX en est un "
"exemple), ou offrent un choix de stratégies différentes (la plupart des "
"*Unix*). Et même si les symboles sont globalement visibles, le module dont "
"on souhaite appeler les fonctions n'est peut-être pas encore chargé !"

#: extending/extending.rst:1165
msgid ""
"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 :ref:`methodtable`). And it means that symbols that *should* be "
"accessible from other extension modules must be exported in a different way."
msgstr ""
"La portabilité exige donc de ne faire aucune supposition sur la visibilité "
"des symboles. Cela signifie que tous les symboles des modules d'extension "
"doivent être déclarés ``static``, à l'exception de la fonction "
"d'initialisation du module, afin d'éviter les conflits de noms avec les "
"autres modules d'extension (comme discuté dans la section :ref:"
"`methodtable`). Et cela signifie que les symboles qui *devraient* être "
"accessibles à partir d'autres modules d'extension doivent être exportés "
"d'une manière différente."

#: extending/extending.rst:1172
msgid ""
"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 (:c:type:`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."
msgstr ""

#: extending/extending.rst:1180
msgid ""
"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."
msgstr ""
"Il existe de nombreuses façons d'utiliser les Capsules pour exporter l'API C "
"d'un module d'extension. Chaque fonction peut obtenir sa propre Capsule, ou "
"tous les pointeurs de l'API C peuvent être stockés dans un tableau dont "
"l'adresse est inscrite dans une Capsule. Et les différentes tâches de "
"stockage et de récupération des pointeurs peuvent être réparties de "
"différentes manières entre le module fournissant le code et les modules "
"clients."

#: extending/extending.rst:1186
#, fuzzy
msgid ""
"Whichever method you choose, it's important to name your Capsules properly. "
"The function :c:func:`PyCapsule_New` takes a name parameter (:c:type:`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."
msgstr ""
"Quelle que soit la méthode que vous choisissez, il est important de bien "
"nommer vos Capsules. La fonction :c:func:`PyCapsule_New` prend un paramètre "
"nommé (:c:type:`const char \\*`). Vous êtes autorisé à passer un nom "
"``NULL``, mais nous vous encourageons vivement à spécifier un nom. Des "
"Capsules correctement nommées offrent un certain degré de sécurité "
"concernant un éventuel conflit de types, car il n'y a pas de moyen de "
"distinguer deux ou plusieurs Capsules non nommée entre elles."

#: extending/extending.rst:1193
msgid ""
"In particular, Capsules used to expose C APIs should be given a name "
"following this convention::"
msgstr ""

#: extending/extending.rst:1198
#, fuzzy
msgid ""
"The convenience function :c:func:`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."
msgstr ""
"La fonction communément utilisée :c:func:`PyCapsule_Import` permet de "
"charger facilement une API C fournie via une Capsule, mais seulement si le "
"nom de la Capsule correspond à cette convention. Ce comportement donne aux "
"utilisateurs d'API C un degré élevé de certitude que la Capsule qu'ils "
"chargent contient l'API C correcte."

#: extending/extending.rst:1203
msgid ""
"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 :c:type:`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."
msgstr ""
"L'exemple suivant montre une approche qui fait peser la plus grande partie "
"de la charge sur le rédacteur du module d'exportation, ce qui est approprié "
"pour les modules de bibliothèque couramment utilisés. Il stocke tous les "
"pointeurs de l'API C (un seul dans l'exemple !) dans un tableau de "
"pointeurs :c:type:`void` qui devient la valeur d'une Capsule. Le fichier "
"d'en-tête correspondant au module fournit une macro qui se charge d'importer "
"le module et de récupérer ses pointeurs d'API C. Les modules clients n'ont "
"qu'à appeler cette macro avant d'accéder à l'API C."

#: extending/extending.rst:1211
msgid ""
"The exporting module is a modification of the :mod:`spam` module from "
"section :ref:`extending-simpleexample`. The function :func:`spam.system` "
"does not call the C library function :c:func:`system` directly, but a "
"function :c:func:`PySpam_System`, which would of course do something more "
"complicated in reality (such as adding \"spam\" to every command). This "
"function :c:func:`PySpam_System` is also exported to other extension modules."
msgstr ""
"Le module d'exportation est une modification du module :mod:`spam` de la "
"section :ref:`extending-simpleexample`. La fonction :func:`spam.system` "
"n'appelle pas directement la fonction de la bibliothèque C :c:func:`system`, "
"mais une fonction :c:func:`PySpam_System`, qui ferait bien sûr quelque chose "
"de plus compliqué en réalité (comme ajouter du *spam* à chaque commande). "
"Cette fonction :c:func:`PySpam_System` est également exportée vers d'autres "
"modules d'extension."

#: extending/extending.rst:1218
msgid ""
"The function :c:func:`PySpam_System` is a plain C function, declared "
"``static`` like everything else::"
msgstr ""

#: extending/extending.rst:1227
msgid "The function :c:func:`spam_system` is modified in a trivial way::"
msgstr "La fonction :c:func:`spam_system` est modifiée de manière simple ::"

#: extending/extending.rst:1241
msgid "In the beginning of the module, right after the line ::"
msgstr "Au début du module, immédiatement après la ligne ::"

#: extending/extending.rst:1245
msgid "two more lines must be added::"
msgstr "on doit ajouter deux lignes supplémentaires ::"

#: extending/extending.rst:1250
msgid ""
"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 "
"initialization function must take care of initializing the C API pointer "
"array::"
msgstr ""
"L'indicateur ``#define`` est utilisé pour indiquer au fichier d'en-tête "
"qu'il est inclus dans le module d'exportation, et non dans un module client. "
"Enfin, la fonction d'initialisation du module doit prendre en charge "
"l'initialisation du tableau de pointeurs de l'API C ::"

#: extending/extending.rst:1280
msgid ""
"Note that ``PySpam_API`` is declared ``static``; otherwise the pointer array "
"would disappear when :func:`PyInit_spam` terminates!"
msgstr ""
"Notez que ``PySpam_API`` est déclaré ``static`` ; sinon le tableau de "
"pointeurs disparaîtrait lorsque :func:`PyInit_spam`` se finit !"

#: extending/extending.rst:1283
msgid ""
"The bulk of the work is in the header file :file:`spammodule.h`, which looks "
"like this::"
msgstr ""
"L'essentiel du travail se trouve dans le fichier d'en-tête :file:`spammodule."
"h`, qui ressemble à ceci ::"

#: extending/extending.rst:1334
msgid ""
"All that a client module must do in order to have access to the function :c:"
"func:`PySpam_System` is to call the function (or rather macro) :c:func:"
"`import_spam` in its initialization function::"
msgstr ""
"Tout ce qu'un module client doit faire pour avoir accès à la fonction :c:"
"func:`PySpam_System` est d'appeler la fonction (ou plutôt la macro) :c:func:"
"`import_spam` dans sa fonction d'initialisation ::"

#: extending/extending.rst:1352
msgid ""
"The main disadvantage of this approach is that the file :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."
msgstr ""
"Le principal inconvénient de cette approche est que le fichier :file:"
"`spammodule.h` est assez compliqué. Cependant, la structure de base est la "
"même pour chaque fonction exportée, ce qui fait qu'elle ne doit être apprise "
"qu'une seule fois."

#: extending/extending.rst:1356
msgid ""
"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 :ref:`capsules` and in the implementation of "
"Capsules (files :file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` "
"in the Python source code distribution)."
msgstr ""
"Enfin, il convient de mentionner que Capsules offrent des fonctionnalités "
"supplémentaires, qui sont particulièrement utiles pour l'allocation de la "
"mémoire et la dés-allocation du pointeur stocké dans un objet Capsule. Les "
"détails sont décrits dans le manuel de référence de l'API Python/C dans la "
"section :ref:`capsules` et dans l'implémentation des Capsules (fichiers :"
"file:`Include/pycapsule.h` et :file:`Objects/pycapsule.c` dans la "
"distribution du code source Python)."

#: extending/extending.rst:1364
msgid "Footnotes"
msgstr "Notes"

#: extending/extending.rst:1365
msgid ""
"An interface for this function already exists in the standard module :mod:"
"`os` --- it was chosen as a simple and straightforward example."
msgstr ""
"Une interface pour cette fonction existe déjà dans le module standard :mod:"
"`os`, elle a été choisie comme un exemple simple et direct."

#: extending/extending.rst:1368
msgid ""
"The metaphor of \"borrowing\" a reference is not completely correct: the "
"owner still has a copy of the reference."
msgstr ""
"L'expression « emprunter une référence » n'est pas tout à fait correcte, car "
"le propriétaire a toujours une copie de la référence."

#: extending/extending.rst:1371
msgid ""
"Checking that the reference count is at least 1 **does not work** --- the "
"reference count itself could be in freed memory and may thus be reused for "
"another object!"
msgstr ""
"Vérifier que le comptage de référence est d'au moins 1 **ne fonctionne "
"pas**, le compte de référence lui-même pourrait être en mémoire libérée et "
"peut donc être réutilisé pour un autre objet !"

#: extending/extending.rst:1375
msgid ""
"These guarantees don't hold when you use the \"old\" style calling "
"convention --- this is still found in much existing code."
msgstr ""
"Ces garanties ne sont pas valables lorsqu'on emploie les conventions de "
"nommage anciennes, qu'on retrouve encore assez souvent dans beaucoup de code "
"existant."