# 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: 2023-01-15 22:33+0100\n" "PO-Revision-Date: 2021-12-11 12:50+0100\n" "Last-Translator: Julien Palard \n" "Language-Team: FRENCH \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:` 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 `_ 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* `_ 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: ````, ````, " "````, and ````. 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 : ````, ````, ```` et ````. 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 ``PyErr_*`` functions --- one has " "already been called by *g*. *f*'s caller is then supposed to also return an " "error indication to *its* caller, again *without* calling ``PyErr_*``, and " "so on --- the most detailed cause of the error was already reported by the " "function that first detected it. Once the error reaches the Python " "interpreter's main loop, this aborts the currently executing Python code and " "tries to find an exception handler specified by the Python programmer." 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 #, fuzzy msgid "" "(There are situations where a module can actually give a more detailed error " "message by calling another ``PyErr_*`` function, and in such cases it is " "fine to do so. As a general rule, however, this is not necessary, and can " "cause information about the cause of the error to be lost: most operations " "can fail for a variety of reasons.)" 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 #, fuzzy msgid "" "If you have a C function that returns no useful argument (a function " "returning :c:expr:`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:expr:`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:expr:`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 #, fuzzy 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:expr:`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."