# SOME DESCRIPTIVE TITLE. # Copyright (C) 2001-2016, Python Software Foundation # This file is distributed under the same license as the Python package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Python 3.6\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2016-10-17 21:44+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../Doc/extending/building.rst:7 msgid "Building C and C++ Extensions" msgstr "Construire des extensions C et C++" #: ../Doc/extending/building.rst:9 msgid "" "A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux, " "``.pyd`` on Windows), which exports an *initialization function*." msgstr "" "Une extension C pour CPython est une bibliothèque partagée (Un ``.so`` sur " "Linux, un ``.pyd`` sur windows), qui expose une *fonction d'initialisation*." #: ../Doc/extending/building.rst:12 msgid "" "To be importable, the shared library must be available on :envvar:" "`PYTHONPATH`, and must be named after the module name, with an appropriate " "extension. When using distutils, the correct filename is generated " "automatically." msgstr "" "Pour pouvoir être importée, la bibliothèque partagée doit pourvoir être " "trouvée dans :envvar:`PYTHONPATH`, et doit porter le nom du module, avec " "l'extension appropriée. En utilisant distutils, le nom est généré " "automatiquement." #: ../Doc/extending/building.rst:16 msgid "The initialization function has the signature:" msgstr "La fonction d'initialisation doit avoir le prototype :" #: ../Doc/extending/building.rst:20 msgid "" "It returns either a fully-initialized module, or a :c:type:`PyModuleDef` " "instance. See :ref:`initializing-modules` for details." msgstr "" "Elle doit donner soit un module entièrement initialisé, soit une instance " "de :c:type:`PyModuleDef`. Voir :ref:`initializing-modules` pour plus de " "détails." #: ../Doc/extending/building.rst:25 msgid "" "For modules with ASCII-only names, the function must be named " "``PyInit_``, with ```` replaced by the name of the " "module. When using :ref:`multi-phase-initialization`, non-ASCII module names " "are allowed. In this case, the initialization function name is " "``PyInitU_``, with ```` encoded using Python's " "*punycode* encoding with hyphens replaced by underscores. In Python::" msgstr "" "Pour les modules dont les noms sont entièrement en ASCII, la fonction doit " "être nommée ``PyInit_``, dont ```` est remplacé par " "le nom du module. En utilisant :ref:`multi-phase-initialization`, il est " "possible d'utiliser des noms de modules comptant des caractères non-ASCII. " "Dans ce cas, le nom de la fonction d'initialisation est " "``PyInitU_``, où ``modulename`` est encodé avec l'encodage " "*punyencode* de Python, dont les tirets sont remplacés par des tirets-bas. " "En Python ça donne : ::" #: ../Doc/extending/building.rst:39 msgid "" "It is possible to export multiple modules from a single shared library by " "defining multiple initialization functions. However, importing them requires " "using symbolic links or a custom importer, because by default only the " "function corresponding to the filename is found. See the *\"Multiple modules " "in one library\"* section in :pep:`489` for details." msgstr "" #: ../Doc/extending/building.rst:49 msgid "Building C and C++ Extensions with distutils" msgstr "Construire les extensions C et C++ avec distutils" #: ../Doc/extending/building.rst:53 msgid "" "Extension modules can be built using distutils, which is included in " "Python. Since distutils also supports creation of binary packages, users " "don't necessarily need a compiler and distutils to install the extension." msgstr "" "Des modules d'extension peuvent être construits avec distutils, qui est " "inclus dans Python. Puisque distutils gère aussi la création de paquets " "binaires, les utilisateurs n'auront pas nécessairement besoin ni d'un " "compilateur ni de distutils pour installer l'extension." #: ../Doc/extending/building.rst:57 msgid "" "A distutils package contains a driver script, :file:`setup.py`. This is a " "plain Python file, which, in the most simple case, could look like this:" msgstr "" #: ../Doc/extending/building.rst:73 msgid "With this :file:`setup.py`, and a file :file:`demo.c`, running ::" msgstr "Avec ce :file:`setup.py` et un fichier :file:`demo.c`, lancer : ::" #: ../Doc/extending/building.rst:77 msgid "" "will compile :file:`demo.c`, and produce an extension module named ``demo`` " "in the :file:`build` directory. Depending on the system, the module file " "will end up in a subdirectory :file:`build/lib.system`, and may have a name " "like :file:`demo.so` or :file:`demo.pyd`." msgstr "" "compilera :file:`demo.c`, et produira un module d'extension nommé ``demo`` " "dans le dossier :file:`build`. En fonction du système, le fichier du module " "peut se retrouver dans :file:`build/lib.system`, et son nom peut être :file:" "`demo.py` ou :file:`demo.pyd`." #: ../Doc/extending/building.rst:82 msgid "" "In the :file:`setup.py`, all execution is performed by calling the ``setup`` " "function. This takes a variable number of keyword arguments, of which the " "example above uses only a subset. Specifically, the example specifies meta-" "information to build packages, and it specifies the contents of the " "package. Normally, a package will contain additional modules, like Python " "source modules, documentation, subpackages, etc. Please refer to the " "distutils documentation in :ref:`distutils-index` to learn more about the " "features of distutils; this section explains building extension modules only." msgstr "" "Dans le fichier :file:`setup.py`, tout est exécuté en appelant la fonction " "``setup``. Elle prend un nombre variable d'arguments nommés, dont l'exemple " "précédent n'utilise qu'une partie. L'exemple précise des méta-informations " "pour construire les paquets, et définir le contenu du paquet. Normalement un " "paquet contient des modules additionnels, comme des modules sources, " "documentation, sous paquets, etc. Referez-vous à la documentation de " "distutils dans :ref:`distutils-index` pour en apprendre plus sur les " "fonctionnalités de distutils. Cette section n'explique que la construction " "de modules d'extension." #: ../Doc/extending/building.rst:91 msgid "" "It is common to pre-compute arguments to :func:`setup`, to better structure " "the driver script. In the example above, the ``ext_modules`` argument to :" "func:`~distutils.core.setup` is a list of extension modules, each of which " "is an instance of the :class:`~distutils.extension.Extension`. In the " "example, the instance defines an extension named ``demo`` which is build by " "compiling a single source file, :file:`demo.c`." msgstr "" #: ../Doc/extending/building.rst:99 msgid "" "In many cases, building an extension is more complex, since additional " "preprocessor defines and libraries may be needed. This is demonstrated in " "the example below." msgstr "" #: ../Doc/extending/building.rst:127 msgid "" "In this example, :func:`~distutils.core.setup` is called with additional " "meta-information, which is recommended when distribution packages have to be " "built. For the extension itself, it specifies preprocessor defines, include " "directories, library directories, and libraries. Depending on the compiler, " "distutils passes this information in different ways to the compiler. For " "example, on Unix, this may result in the compilation commands ::" msgstr "" #: ../Doc/extending/building.rst:139 msgid "" "These lines are for demonstration purposes only; distutils users should " "trust that distutils gets the invocations right." msgstr "" "Ces lignes ne sont qu'à titre d'exemple, les utilisateurs de distutils " "doivent avoir confiance en distutils qui fera les appels correctement." #: ../Doc/extending/building.rst:146 msgid "Distributing your extension modules" msgstr "Distribuer vos modules d'extension" #: ../Doc/extending/building.rst:148 msgid "" "When an extension has been successfully build, there are three ways to use " "it." msgstr "" "Lorsqu'une extension a été construite avec succès, il existe trois moyens de " "l'utiliser." #: ../Doc/extending/building.rst:150 msgid "" "End-users will typically want to install the module, they do so by running ::" msgstr "" "Typiquement, les utilisateurs vont vouloir installer le module, ils le font " "en exécutant : ::" #: ../Doc/extending/building.rst:154 msgid "" "Module maintainers should produce source packages; to do so, they run ::" msgstr "" "Les mainteneurs de modules voudront produire des paquets source, pour ce " "faire ils exécuteront : ::" #: ../Doc/extending/building.rst:158 msgid "" "In some cases, additional files need to be included in a source " "distribution; this is done through a :file:`MANIFEST.in` file; see :ref:" "`manifest` for details." msgstr "" #: ../Doc/extending/building.rst:161 msgid "" "If the source distribution has been build successfully, maintainers can also " "create binary distributions. Depending on the platform, one of the following " "commands can be used to do so. ::" msgstr "" "Si la distribution source a été construite avec succès, les mainteneurs " "peuvent créer une distribution binaire. En fonction de la plateforme, une " "des commandes suivantes peut être utilisée. ::" #: ../Doc/extending/embedding.rst:8 msgid "Embedding Python in Another Application" msgstr "Intégrer Python dans une autre Application" #: ../Doc/extending/embedding.rst:10 msgid "" "The previous chapters discussed how to extend Python, that is, how to extend " "the functionality of Python by attaching a library of C functions to it. It " "is also possible to do it the other way around: enrich your C/C++ " "application by embedding Python in it. Embedding provides your application " "with the ability to implement some of the functionality of your application " "in Python rather than C or C++. This can be used for many purposes; one " "example would be to allow users to tailor the application to their needs by " "writing some scripts in Python. You can also use it yourself if some of the " "functionality can be written in Python more easily." msgstr "" "Les chapitres précédents couvraient l'extension de Python, c'est à dire, " "comment enrichir une fonctionnalité de Python en y attachant une " "bibliothèque de fonctions C. C'est aussi possible dans l'autre sens: " "enrichir vos applications C/C++ en y intégrant Python. Intégrer Python vous " "permet d'implémenter certaines fonctionnalités de vos applications en Python " "plutôt qu'en C ou C++. C'est utile dans de nombreux cas, un exemple serait " "de permettre aux utilisateurs d'adapter une application à leur besoins en y " "écrivant des scripts Python. Vous pouvez aussi l'utiliser vous même si " "certaines fonctionnalités peuvent être rédigées plus facilement en Python." #: ../Doc/extending/embedding.rst:20 msgid "" "Embedding Python is similar to extending it, but not quite. The difference " "is that when you extend Python, the main program of the application is still " "the Python interpreter, while if you embed Python, the main program may have " "nothing to do with Python --- instead, some parts of the application " "occasionally call the Python interpreter to run some Python code." msgstr "" "Intégrer et étendre Python sont des tâches presque identiques. La différence " "est qu'en étendant Python, le programme principal reste l'interpréteur " "Python, alors qu'en intégrant Python le programme principal peut ne rien à " "voir avec Python. C'est simplement quelques parties du programme qui " "appellent l'interprète Python pour exécuter un peu de code Python." #: ../Doc/extending/embedding.rst:26 msgid "" "So if you are embedding Python, you are providing your own main program. " "One of the things this main program has to do is initialize the Python " "interpreter. At the very least, you have to call the function :c:func:" "`Py_Initialize`. There are optional calls to pass command line arguments to " "Python. Then later you can call the interpreter from any part of the " "application." msgstr "" "En intégrant Python, vous fournissez le programme principal. L'une de ses " "tâches sera d'initialiser l'interpréteur. Au minimum vous devrez appeler :c:" "func:`Py_Initialize`. Il est possible, avec quelques appels supplémentaires, " "de passer des options à Python. Ensuite vous pourrez appeler l'interpréteur " "depuis n'importe quelle partie de votre programme." #: ../Doc/extending/embedding.rst:32 msgid "" "There are several different ways to call the interpreter: you can pass a " "string containing Python statements to :c:func:`PyRun_SimpleString`, or you " "can pass a stdio file pointer and a file name (for identification in error " "messages only) to :c:func:`PyRun_SimpleFile`. You can also call the lower-" "level operations described in the previous chapters to construct and use " "Python objects." msgstr "" "Il existe différents moyens d'appeler l'interpréteur: vous pouvez donner une " "chaîne contenant des instructions Python à :c:func:`PyRun_SimpleString`, ou " "vous pouvez donner un pointeur de fichier *stdio* et un nom de fichier " "(juste pour nommer les messages d'erreur) à :c:func:`PyRunSimpleFile`. Vous " "pouvez aussi appeler les API de bas niveau décrites dans les chapitres " "précédents pour construire et utiliser des objets Python." #: ../Doc/extending/embedding.rst:42 msgid ":ref:`c-api-index`" msgstr ":ref:`c-api-index`" #: ../Doc/extending/embedding.rst:42 msgid "" "The details of Python's C interface are given in this manual. A great deal " "of necessary information can be found here." msgstr "" "Les détails sur l'interface entre Python et le C sont donnés dans ce manuel. " "Pléthore informations s'y trouvent." #: ../Doc/extending/embedding.rst:49 msgid "Very High Level Embedding" msgstr "Intégration de Très Haut Niveau" #: ../Doc/extending/embedding.rst:51 msgid "" "The simplest form of embedding Python is the use of the very high level " "interface. This interface is intended to execute a Python script without " "needing to interact with the application directly. This can for example be " "used to perform some operation on a file. ::" msgstr "" "La manière la plus simple d'intégrer Python est d'utiliser une interface de " "très haut niveau. Cette interface a pour but d'exécuter un script Python " "sans avoir à interagir avec directement. C'est utile, par exemple, pour " "effectuer une opération sur un fichier. ::" #: ../Doc/extending/embedding.rst:77 msgid "" "The :c:func:`Py_SetProgramName` function should be called before :c:func:" "`Py_Initialize` to inform the interpreter about paths to Python run-time " "libraries. Next, the Python interpreter is initialized with :c:func:" "`Py_Initialize`, followed by the execution of a hard-coded Python script " "that prints the date and time. Afterwards, the :c:func:`Py_FinalizeEx` call " "shuts the interpreter down, followed by the end of the program. In a real " "program, you may want to get the Python script from another source, perhaps " "a text-editor routine, a file, or a database. Getting the Python code from " "a file can better be done by using the :c:func:`PyRun_SimpleFile` function, " "which saves you the trouble of allocating memory space and loading the file " "contents." msgstr "" #: ../Doc/extending/embedding.rst:92 msgid "Beyond Very High Level Embedding: An overview" msgstr "Au delà de l'Intégration de Haut Niveau: Survol" #: ../Doc/extending/embedding.rst:94 msgid "" "The high level interface gives you the ability to execute arbitrary pieces " "of Python code from your application, but exchanging data values is quite " "cumbersome to say the least. If you want that, you should use lower level " "calls. At the cost of having to write more C code, you can achieve almost " "anything." msgstr "" "L'interface de haut niveau vous permet d'exécuter n'importe quel morceau de " "code Python depuis votre application, mais échanger des données est quelque " "peu alambiqué. Si c'est ce dont vous avez besoin, vous devez utiliser des " "appels de niveau plus bas. Il vous en coûtera plus de lignes de C à écrire, " "mais vous pourrez presque tout faire." #: ../Doc/extending/embedding.rst:99 msgid "" "It should be noted that extending Python and embedding Python is quite the " "same activity, despite the different intent. Most topics discussed in the " "previous chapters are still valid. To show this, consider what the extension " "code from Python to C really does:" msgstr "" "Il est à souligner qu'étendre ou intégrer Python revient à la louche au " "même, en dépit de la différence d'intention. La plupart des sujets parcourus " "dans les chapitres précédents sont toujours valides. Pour le prouver, " "regardez ce qu'un code d'extension de Python vers C fait réellement :" #: ../Doc/extending/embedding.rst:104 msgid "Convert data values from Python to C," msgstr "Convertir des valeurs de Python vers le C," #: ../Doc/extending/embedding.rst:106 msgid "Perform a function call to a C routine using the converted values, and" msgstr "Appeler une fonction C en utilisant les valeurs converties, et" #: ../Doc/extending/embedding.rst:108 msgid "Convert the data values from the call from C to Python." msgstr "Convertir les résultats de l'appel à la fonction C pour Python." #: ../Doc/extending/embedding.rst:110 msgid "When embedding Python, the interface code does:" msgstr "Lors de l'intégration de Python, le code de l'interface fait :" #: ../Doc/extending/embedding.rst:112 msgid "Convert data values from C to Python," msgstr "Convertir les valeurs depuis le C vers Python," #: ../Doc/extending/embedding.rst:114 msgid "" "Perform a function call to a Python interface routine using the converted " "values, and" msgstr "" "Effectuer un appel de fonction de l'interface Python en utilisant les " "valeurs converties, et" #: ../Doc/extending/embedding.rst:117 msgid "Convert the data values from the call from Python to C." msgstr "Convertir les valeurs de l'appel Python pour le C." #: ../Doc/extending/embedding.rst:119 msgid "" "As you can see, the data conversion steps are simply swapped to accommodate " "the different direction of the cross-language transfer. The only difference " "is the routine that you call between both data conversions. When extending, " "you call a C routine, when embedding, you call a Python routine." msgstr "" "Tel que vous le voyez, les conversions sont simplement inversées pour " "s'adapter au différentes directions de transfert inter-langage. La seule " "différence est la fonction que vous appelez entre les deux conversions de " "données. Lors de l'extension, vous appelez une fonction C, lors de " "l'intégration vous appelez une fonction Python." #: ../Doc/extending/embedding.rst:124 msgid "" "This chapter will not discuss how to convert data from Python to C and vice " "versa. Also, proper use of references and dealing with errors is assumed to " "be understood. Since these aspects do not differ from extending the " "interpreter, you can refer to earlier chapters for the required information." msgstr "" "Ce chapitre ne couvrira pas la conversion des données de Python vers le C ni " "l'inverse. Aussi, un usage correct des références, ainsi que savoir gérer " "les erreurs sont considérés acquis. Ces aspects étant identiques à " "l'extension de l'interpréteur, vous pouvez vous référer aux chapitres " "précédents." #: ../Doc/extending/embedding.rst:133 msgid "Pure Embedding" msgstr "Intégration Pure" #: ../Doc/extending/embedding.rst:135 msgid "" "The first program aims to execute a function in a Python script. Like in the " "section about the very high level interface, the Python interpreter does not " "directly interact with the application (but that will change in the next " "section)." msgstr "" "L'objectif du premier programme est d'exécuter une fonction dans un script " "Python. Comme dans la section à propos des interfaces de haut niveau, " "l'interpréteur n'interagit pas directement avec l'application (mais le fera " "dans la section suivante)." #: ../Doc/extending/embedding.rst:140 msgid "The code to run a function defined in a Python script is:" msgstr "Le code pour appeler une fonction définie dans un script Python est :" #: ../Doc/extending/embedding.rst:145 msgid "" "This code loads a Python script using ``argv[1]``, and calls the function " "named in ``argv[2]``. Its integer arguments are the other values of the " "``argv`` array. If you :ref:`compile and link ` this program " "(let's call the finished executable :program:`call`), and use it to execute " "a Python script, such as:" msgstr "" "Ce code charge un script Python en utilisant ``argv[1]``, et appelle une " "fonction dont le nom est dans ``argv[2]``. Ses arguments entiers sont les " "autres valeurs de ``argv``. Si vous :ref:`compilez et liez ` ce " "programme (appelons l'exécutable :program:`call`), et l'appellez pour " "exécuter un script Python, tel que :" #: ../Doc/extending/embedding.rst:160 msgid "then the result should be:" msgstr "" #: ../Doc/extending/embedding.rst:168 msgid "" "Although the program is quite large for its functionality, most of the code " "is for data conversion between Python and C, and for error reporting. The " "interesting part with respect to embedding Python starts with ::" msgstr "" "Bien que le programme soit plutôt gros pour ses fonctionnalités, la plupart " "du code n'est que conversion de données entre Python et C, aussi que pour " "rapporter les erreurs. La partie intéressante, qui concerne l'intégration de " "Python débute par : ::" #: ../Doc/extending/embedding.rst:177 msgid "" "After initializing the interpreter, the script is loaded using :c:func:" "`PyImport_Import`. This routine needs a Python string as its argument, " "which is constructed using the :c:func:`PyUnicode_FromString` data " "conversion routine. ::" msgstr "" "Après avoir initialisé l'interpréteur, le script est chargé en utilisant :c:" "func:`PyImport_Import`. Cette fonction prend une chaîne Python pour " "argument, elle même construite en utilisant la fonction de conversion :c:" "func:`PyUnicode_FromString`." #: ../Doc/extending/embedding.rst:190 msgid "" "Once the script is loaded, the name we're looking for is retrieved using :c:" "func:`PyObject_GetAttrString`. If the name exists, and the object returned " "is callable, you can safely assume that it is a function. The program then " "proceeds by constructing a tuple of arguments as normal. The call to the " "Python function is then made with::" msgstr "" "Une fois le script chargé, le nom recherché est obtenu en utilisant :c:func:" "`PyObject_GetAttrString`. Si le nom existe, et que l'objet récupéré peut " "être appelé, vous pouvez présumer sans risque que c'est une fonction. Le " "programme continue, classiquement, par la construction de l'uplet " "d'arguments. L'appel à la fonction Python est alors effectué avec : ::" #: ../Doc/extending/embedding.rst:198 msgid "" "Upon return of the function, ``pValue`` is either *NULL* or it contains a " "reference to the return value of the function. Be sure to release the " "reference after examining the value." msgstr "" "Après l'exécution de la fonction, ``pValue`` est soit *NULL*, soit une " "référence sur la valeur donnée par la fonction. Assurez-vous de libérer la " "référence après avoir utilisé la valeur." #: ../Doc/extending/embedding.rst:206 msgid "Extending Embedded Python" msgstr "Étendre un Python Intégré" #: ../Doc/extending/embedding.rst:208 msgid "" "Until now, the embedded Python interpreter had no access to functionality " "from the application itself. The Python API allows this by extending the " "embedded interpreter. That is, the embedded interpreter gets extended with " "routines provided by the application. While it sounds complex, it is not so " "bad. Simply forget for a while that the application starts the Python " "interpreter. Instead, consider the application to be a set of subroutines, " "and write some glue code that gives Python access to those routines, just " "like you would write a normal Python extension. For example::" msgstr "" "Jusqu'à présent, l'interpréteur Python intégré n'avait pas accès aux " "fonctionnalités de l'application elle-même. L'API Python le permet en " "étendant l'interpréteur intégré. Autrement dit, l'interpréteur intégré est " "étendu avec des fonctions fournies par l'application. Bien que cela puisse " "sembler complexe, ce n'est pas si dur. Il suffit d'oublier que l'application " "démarre l'interpréteur Python, au lieu de cela, voyez l'application comme un " "ensemble de fonctions, et rédigez un peu de code pour exposer ces fonctions " "à Python, tout comme vous écririez une extension Python normale. Par " "exemple : ::" #: ../Doc/extending/embedding.rst:245 msgid "" "Insert the above code just above the :c:func:`main` function. Also, insert " "the following two statements before the call to :c:func:`Py_Initialize`::" msgstr "" "Insérez le code ci-dessus juste avant la fonction :c:func:`main`. Ajoutez " "aussi les deux instructions suivantes avant l'appel à :c:func:" "`Py_Initialize` ::" #: ../Doc/extending/embedding.rst:251 msgid "" "These two lines initialize the ``numargs`` variable, and make the :func:`emb." "numargs` function accessible to the embedded Python interpreter. With these " "extensions, the Python script can do things like" msgstr "" "Ces deux lignes initialisent la variable ``numarg``, et rend la fonction :" "func:`emb.numargs` accessible à l'interprète intégré. Avec ces ajouts, le " "script Python petit maintenant faire des choses comme" #: ../Doc/extending/embedding.rst:260 msgid "" "In a real application, the methods will expose an API of the application to " "Python." msgstr "" "Dans un cas réel, les méthodes exposeraient une API de l'application a " "Python." #: ../Doc/extending/embedding.rst:270 msgid "Embedding Python in C++" msgstr "Intégrer Python dans du C++" #: ../Doc/extending/embedding.rst:272 msgid "" "It is also possible to embed Python in a C++ program; precisely how this is " "done will depend on the details of the C++ system used; in general you will " "need to write the main program in C++, and use the C++ compiler to compile " "and link your program. There is no need to recompile Python itself using C+" "+." msgstr "" "Il est aussi possible d'intégrer Python dans un programme en C++, la manière " "exacte dont cela se fait dépend de détails du système C++ utilisé. En " "général vous écrirez le programme principal en C++, utiliserez un " "compilateur C++ pour compiler et lier votre programme. Il n'y a pas besoin " "de recompiler Python en utilisant C++." #: ../Doc/extending/embedding.rst:281 msgid "Compiling and Linking under Unix-like systems" msgstr "Compiler et Lier en environnement Unix ou similaire" #: ../Doc/extending/embedding.rst:283 msgid "" "It is not necessarily trivial to find the right flags to pass to your " "compiler (and linker) in order to embed the Python interpreter into your " "application, particularly because Python needs to load library modules " "implemented as C dynamic extensions (:file:`.so` files) linked against it." msgstr "" "Ce n'est pas évident de trouver les bonnes options à passer au compilateur " "(et *linker*) pour intégrer l'interpréteur Python dans une application, " "Python ayant besoin de charger des extensions sous forme de bibliothèques " "dynamiques en C (des :file:`.so`) pour se lier avec." #: ../Doc/extending/embedding.rst:289 msgid "" "To find out the required compiler and linker flags, you can execute the :" "file:`python{X.Y}-config` script which is generated as part of the " "installation process (a :file:`python3-config` script may also be " "available). This script has several options, of which the following will be " "directly useful to you:" msgstr "" "Pour trouver les bonnes option de compilateur et *linker*, vous pouvez " "exécuter le script :file:`python(X.Y)-config` généré durant l'installation " "(un script :file:`python3-config` peut aussi être disponible). Ce script a " "quelques options, celles-ci vous seront utiles :" #: ../Doc/extending/embedding.rst:295 msgid "" "``pythonX.Y-config --cflags`` will give you the recommended flags when " "compiling:" msgstr "" #: ../Doc/extending/embedding.rst:303 msgid "" "``pythonX.Y-config --ldflags`` will give you the recommended flags when " "linking:" msgstr "" #: ../Doc/extending/embedding.rst:312 msgid "" "To avoid confusion between several Python installations (and especially " "between the system Python and your own compiled Python), it is recommended " "that you use the absolute path to :file:`python{X.Y}-config`, as in the " "above example." msgstr "" "Pour éviter la confusion entre différentes installations de Python, (et plus " "spécialement entre celle de votre système et votre version compilée), il est " "recommandé d'utiliser un chemin absolu vers :file:`python{X.Y}-config`, " "comme dans l'exemple précédent." #: ../Doc/extending/embedding.rst:317 msgid "" "If this procedure doesn't work for you (it is not guaranteed to work for all " "Unix-like platforms; however, we welcome :ref:`bug reports `) you will have to read your system's documentation about dynamic " "linking and/or examine Python's :file:`Makefile` (use :func:`sysconfig." "get_makefile_filename` to find its location) and compilation options. In " "this case, the :mod:`sysconfig` module is a useful tool to programmatically " "extract the configuration values that you will want to combine together. " "For example:" msgstr "" "Si cette procédure ne fonctionne pas pour vous (il n'est pas garanti qu'elle " "fonctionne pour toutes les plateformes Unix, mais nous traiteront volontiers " "les :ref:`rapports de bugs `), vous devrez lire " "ladocumentation de votre système sur la liaison dynamique (*dynamic " "linking*) et / ouexaminer le :file:`Makefile` de Python (utilisez :func:" "`sysconfig.get_makefile_filename` pour trouver son emplacement) et les " "options de compilation. Dans ce cas, le module :mod:`sysconfig` est un outil " "utile pour extraire automatiquement les valeurs de configuration que vous " "voudrez combiner ensemble. Par example :" #: ../Doc/extending/extending.rst:8 msgid "Extending Python with C or C++" msgstr "Étendre Python en C ou C++" #: ../Doc/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 possible directement en Python: Elles " "peuvent définir de nouveaux types natifs, et peuvent appeler des fonctions " "de bibliothèques C ou appels systèmes." #: ../Doc/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\"``." #: ../Doc/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." #: ../Doc/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." #: ../Doc/extending/extending.rst:39 msgid "A Simple Example" msgstr "Un exemple simple" #: ../Doc/extending/extending.rst:41 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 terminée par NULL comme argument et renvoie " "un entier. Nous voulons que cette fonction soit appelable à partir de Python " "comme suit : ::" #: ../Doc/extending/extending.rst:50 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`.)" #: ../Doc/extending/extending.rst:55 msgid "The first line of our file can be::" msgstr "La première ligne de notre fichier peut être : ::" #: ../Doc/extending/extending.rst:59 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)." #: ../Doc/extending/extending.rst:64 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." #: ../Doc/extending/extending.rst:68 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\"`` inclu 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." #: ../Doc/extending/extending.rst:76 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) ::" #: ../Doc/extending/extending.rst:92 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 ya 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*." #: ../Doc/extending/extending.rst:97 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." #: ../Doc/extending/extending.rst:100 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 *tuple* Python contenant les " "arguments. Chaque élément du *tuple* 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." #: ../Doc/extending/extending.rst:109 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 données. Il retourne faux (zéro) si une liste d'arguments " "invalide a été passée. Dans ce dernier cas, elle soulève également une " "exception appropriée de sorte que la fonction d'appel puisse retourner " "*NULL* immédiatement (comme nous l'avons vu dans l'exemple)." #: ../Doc/extending/extending.rst:119 msgid "Intermezzo: Errors and Exceptions" msgstr "Intermezzo: Les Erreurs et Exceptions" #: ../Doc/extending/extending.rst:121 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 a *NULL* pointer). Exceptions are stored in a static " "global variable inside the interpreter; if this variable is *NULL* no " "exception has occurred. A second global variable stores the \"associated " "value\" of the exception (the second argument to :keyword:`raise`). A third " "variable contains the stack traceback in case the error originated in Python " "code. These three variables are the C equivalents of the result in Python " "of :meth:`sys.exc_info` (see the section on module :mod:`sys` in the Python " "Library Reference). 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és 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." #: ../Doc/extending/extending.rst:132 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." #: ../Doc/extending/extending.rst:134 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." #: ../Doc/extending/extending.rst:140 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." #: ../Doc/extending/extending.rst:147 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 de retour." #: ../Doc/extending/extending.rst:153 msgid "" "When a function *f* that calls another function *g* detects that the latter " "fails, *f* should itself return an error value (usually *NULL* or ``-1``). " "It should *not* call one of the :c:func:`PyErr_\\*` functions --- one has " "already been called by *g*. *f*'s caller is then supposed to also return an " "error indication to *its* caller, again *without* calling :c:func:`PyErr_" "\\*`, and so on --- the most detailed cause of the error was already " "reported by the function that first detected it. Once the error reaches the " "Python interpreter's main loop, this aborts the currently executing Python " "code and tries to find an exception handler specified by the Python " "programmer." msgstr "" "Lorsqu'une fonction *f* ayant appelé une autre fonction *g* détecte que " "cette dernière a échoué, *f* devrait donner une valeur d'erreur à son tour " "(habituellement *NULL* ou ``-1``). *f* ne devrait *pas* appeler l'une des " "fonctions :c:func:`PyErr_\\*`, l'une d'elles ayant déjà été appelée par *g*. " "La fonction appelant *f* est alors censée retourner 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ée 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." #: ../Doc/extending/extending.rst:163 msgid "" "(There are situations where a module can actually give a more detailed error " "message by calling another :c:func:`PyErr_\\*` function, and in such cases " "it is fine to do so. As a general rule, however, this is not necessary, and " "can cause information about the cause of the error to be lost: most " "operations can fail for a variety of reasons.)" msgstr "" "(Il ya 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)." #: ../Doc/extending/extending.rst:169 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é)." #: ../Doc/extending/extending.rst:175 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." #: ../Doc/extending/extending.rst:181 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." #: ../Doc/extending/extending.rst:185 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) !" #: ../Doc/extending/extending.rst:189 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` " "soulè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." #: ../Doc/extending/extending.rst:199 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 : ::" #: ../Doc/extending/extending.rst:204 msgid "" "and initialize it in your module's initialization function (:c:func:" "`PyInit_spam`) with an exception object (leaving out the error checking for " "now)::" msgstr "" "et initialisez-la dans la fonction d'initialisation de votre module (:c:func:" "`PyInit_spam`) avec un objet exception (Passons, pour le moment, la " "vérification des codes d'erreur) ::" #: ../Doc/extending/extending.rst:222 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 exception, côté 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`." #: ../Doc/extending/extending.rst:227 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 " "êtreretirée du module par un code externe, une référence à la classe est " "nécessairepour assurer qu'il ne sera pas rejeté, causant :c:data:`SpamError` " "à devenirun pointeur défaillant. S'il devenait un pointeur défaillant, le C " "code qui soulèvel'exception peut engendrer un rejet central ou des effets " "secondaires innatendus." #: ../Doc/extending/extending.rst:234 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 " "retour de fonction plus tard dans cette section." #: ../Doc/extending/extending.rst:237 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::" #: ../Doc/extending/extending.rst:260 msgid "Back to the Example" msgstr "Retour vers l'Exemple" #: ../Doc/extending/extending.rst:262 msgid "" "Going back to our example function, you should now be able to understand " "this statement::" msgstr "" "En retournant vers notre fonction exemple, vous devriez maintenant " "êtrecapable de comprendre cette affirmation::" #: ../Doc/extending/extending.rst:268 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 retourne *NULL* (l'indicateur d'erreur pour les fonctions retournant " "des pointeurs d'objet) si une erreur est detecté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 qui vers laquelle il pointe (donc en " "C Standard, la variable :c:data:`command` doit être clairement déclarée " "comme ``const char *command``)." #: ../Doc/extending/extending.rst:276 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`::" #: ../Doc/extending/extending.rst:281 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 retourner la valeur de :c:data:`sts` " "comme un objet Python. Cela est effectué par l'utilisation de la fonction :c:" "func:`PyLong_FromLong`. ::" #: ../Doc/extending/extending.rst:286 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 retournera un objet entier. (Oui, même les entiers sont " "des objets dans le tas en Python!)" #: ../Doc/extending/extending.rst:289 msgid "" "If you have a C function that returns no useful argument (a function " "returning :c:type:`void`), the corresponding Python function must return " "``None``. You need this idiom to do so (which is implemented by the :c:" "macro:`Py_RETURN_NONE` macro)::" msgstr "" "Si vous avez une fonction C qui ne retourne aucun argument utile (une " "fonction retournant :c:type:`void`), la fonction Python correspondante doit " "retourner ``None``. Vous aurez besoin de cette locution pour cela (qui est " "implémentée par la macro :c:macro:`Py_RETURN_NONE`)::" #: ../Doc/extending/extending.rst:297 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 le nom C pour l'objet spécial Python ``None``. C'est " "un authentique objet Python plutôt qu'un pointeur *NULL*, qui signifie " "\"error\" dans la plupart des situations, comme nous l'avons vu." #: ../Doc/extending/extending.rst:305 msgid "The Module's Method Table and Initialization Function" msgstr "" #: ../Doc/extending/extending.rst:307 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 "" #: ../Doc/extending/extending.rst:318 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 "" #: ../Doc/extending/extending.rst:323 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 "" #: ../Doc/extending/extending.rst:327 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 "" #: ../Doc/extending/extending.rst:333 msgid "" "The method table must be referenced in the module definition structure::" msgstr "" #: ../Doc/extending/extending.rst:344 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 "" #: ../Doc/extending/extending.rst:355 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 "" #: ../Doc/extending/extending.rst:359 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 "" #: ../Doc/extending/extending.rst:370 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 "" #: ../Doc/extending/extending.rst:406 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 "" #: ../Doc/extending/extending.rst:412 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 "" #: ../Doc/extending/extending.rst:418 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 "" #: ../Doc/extending/extending.rst:427 msgid "Compilation and Linkage" msgstr "" #: ../Doc/extending/extending.rst:429 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 "" #: ../Doc/extending/extending.rst:436 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 "" #: ../Doc/extending/extending.rst:445 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 "" #: ../Doc/extending/extending.rst:451 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 "" #: ../Doc/extending/extending.rst:460 msgid "Calling Python Functions from C" msgstr "" #: ../Doc/extending/extending.rst:462 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 "" #: ../Doc/extending/extending.rst:470 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 "" #: ../Doc/extending/extending.rst:476 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 "" #: ../Doc/extending/extending.rst:506 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 "" #: ../Doc/extending/extending.rst:511 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 "" #: ../Doc/extending/extending.rst:518 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 "" #: ../Doc/extending/extending.rst:538 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 "" #: ../Doc/extending/extending.rst:544 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 "" #: ../Doc/extending/extending.rst:550 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 "" #: ../Doc/extending/extending.rst:563 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 "" #: ../Doc/extending/extending.rst:582 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 "" #: ../Doc/extending/extending.rst:586 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 "" #: ../Doc/extending/extending.rst:604 msgid "Extracting Parameters in Extension Functions" msgstr "" #: ../Doc/extending/extending.rst:608 msgid "The :c:func:`PyArg_ParseTuple` function is declared as follows::" msgstr "" #: ../Doc/extending/extending.rst:612 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 "" #: ../Doc/extending/extending.rst:618 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 "" #: ../Doc/extending/extending.rst:623 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 ! " #: ../Doc/extending/extending.rst:626 msgid "Some example calls::" msgstr "" #: ../Doc/extending/extending.rst:696 msgid "Keyword Parameters for Extension Functions" msgstr "" #: ../Doc/extending/extending.rst:700 msgid "" "The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::" msgstr "" #: ../Doc/extending/extending.rst:705 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 "" #: ../Doc/extending/extending.rst:715 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 "" #: ../Doc/extending/extending.rst:721 msgid "" "Here is an example module which uses keywords, based on an example by Geoff " "Philbrick (philbrick@hks.com)::" msgstr "" #: ../Doc/extending/extending.rst:775 msgid "Building Arbitrary Values" msgstr "" #: ../Doc/extending/extending.rst:777 msgid "" "This function is the counterpart to :c:func:`PyArg_ParseTuple`. It is " "declared as follows::" msgstr "" #: ../Doc/extending/extending.rst:782 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 "" #: ../Doc/extending/extending.rst:787 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 "" #: ../Doc/extending/extending.rst:795 msgid "" "Examples (to the left the call, to the right the resulting Python value):" msgstr "" #: ../Doc/extending/extending.rst:821 msgid "Reference Counts" msgstr "" #: ../Doc/extending/extending.rst:823 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 "" #: ../Doc/extending/extending.rst:829 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 "" #: ../Doc/extending/extending.rst:840 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 "" #: ../Doc/extending/extending.rst:853 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 "" #: ../Doc/extending/extending.rst:861 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 "" #: ../Doc/extending/extending.rst:873 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 "" #: ../Doc/extending/extending.rst:884 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. The cycle detector is considered an " "optional component; though it is included by default, it can be disabled at " "build time using the :option:`--without-cycle-gc` option to the :program:" "`configure` script on Unix platforms (including Mac OS X). If the cycle " "detector is disabled in this way, the :mod:`gc` module will not be available." msgstr "" #: ../Doc/extending/extending.rst:898 msgid "Reference Counting in Python" msgstr "" #: ../Doc/extending/extending.rst:900 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 "" #: ../Doc/extending/extending.rst:907 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 "" #: ../Doc/extending/extending.rst:916 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 "" #: ../Doc/extending/extending.rst:922 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 "" #: ../Doc/extending/extending.rst:930 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 "" #: ../Doc/extending/extending.rst:940 msgid "Ownership Rules" msgstr "" #: ../Doc/extending/extending.rst:942 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 "" #: ../Doc/extending/extending.rst:946 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 "" #: ../Doc/extending/extending.rst:954 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 "" #: ../Doc/extending/extending.rst:961 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 "" #: ../Doc/extending/extending.rst:965 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 "" #: ../Doc/extending/extending.rst:973 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 "" #: ../Doc/extending/extending.rst:979 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 "" #: ../Doc/extending/extending.rst:987 msgid "Thin Ice" msgstr "" #: ../Doc/extending/extending.rst:989 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 "" #: ../Doc/extending/extending.rst:993 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 "" #: ../Doc/extending/extending.rst:1005 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 "" #: ../Doc/extending/extending.rst:1009 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 "" #: ../Doc/extending/extending.rst:1016 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 "" #: ../Doc/extending/extending.rst:1024 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 "" #: ../Doc/extending/extending.rst:1038 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 "" #: ../Doc/extending/extending.rst:1042 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 "" #: ../Doc/extending/extending.rst:1065 msgid "NULL Pointers" msgstr "" #: ../Doc/extending/extending.rst:1067 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 "" #: ../Doc/extending/extending.rst:1075 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 "" #: ../Doc/extending/extending.rst:1079 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 "" #: ../Doc/extending/extending.rst:1083 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 "" #: ../Doc/extending/extending.rst:1089 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 "" #: ../Doc/extending/extending.rst:1093 msgid "" "It is a severe error to ever let a *NULL* pointer \"escape\" to the Python " "user." msgstr "" #: ../Doc/extending/extending.rst:1104 msgid "Writing Extensions in C++" msgstr "" #: ../Doc/extending/extending.rst:1106 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 "" #: ../Doc/extending/extending.rst:1120 msgid "Providing a C API for an Extension Module" msgstr "" #: ../Doc/extending/extending.rst:1125 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 "" #: ../Doc/extending/extending.rst:1133 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 "" #: ../Doc/extending/extending.rst:1145 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 "" #: ../Doc/extending/extending.rst:1152 msgid "" "Python provides a special mechanism to pass C-level information (pointers) " "from one extension module to another one: Capsules. A Capsule is a Python " "data type which stores a pointer (:c:type:`void \\*`). Capsules can only be " "created and accessed via their C API, but they can be passed around like any " "other Python object. In particular, they can be assigned to a name in an " "extension module's namespace. Other extension modules can then import this " "module, retrieve the value of this name, and then retrieve the pointer from " "the Capsule." msgstr "" #: ../Doc/extending/extending.rst:1160 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 "" #: ../Doc/extending/extending.rst:1166 msgid "" "Whichever method you choose, it's important to name your Capsules properly. " "The function :c:func:`PyCapsule_New` takes a name parameter (:c:type:`const " "char \\*`); you're permitted to pass in a *NULL* name, but we strongly " "encourage you to specify a name. Properly named Capsules provide a degree " "of runtime type-safety; there is no feasible way to tell one unnamed Capsule " "from another." msgstr "" #: ../Doc/extending/extending.rst:1173 msgid "" "In particular, Capsules used to expose C APIs should be given a name " "following this convention::" msgstr "" #: ../Doc/extending/extending.rst:1178 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 "" #: ../Doc/extending/extending.rst:1183 msgid "" "The following example demonstrates an approach that puts most of the burden " "on the writer of the exporting module, which is appropriate for commonly " "used library modules. It stores all C API pointers (just one in the " "example!) in an array of :c:type:`void` pointers which becomes the value of " "a Capsule. The header file corresponding to the module provides a macro that " "takes care of importing the module and retrieving its C API pointers; client " "modules only have to call this macro before accessing the C API." msgstr "" #: ../Doc/extending/extending.rst:1191 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 "" #: ../Doc/extending/extending.rst:1198 msgid "" "The function :c:func:`PySpam_System` is a plain C function, declared " "``static`` like everything else::" msgstr "" #: ../Doc/extending/extending.rst:1207 msgid "The function :c:func:`spam_system` is modified in a trivial way::" msgstr "" #: ../Doc/extending/extending.rst:1221 msgid "In the beginning of the module, right after the line ::" msgstr "" #: ../Doc/extending/extending.rst:1225 msgid "two more lines must be added::" msgstr "" #: ../Doc/extending/extending.rst:1230 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 "" #: ../Doc/extending/extending.rst:1256 msgid "" "Note that ``PySpam_API`` is declared ``static``; otherwise the pointer array " "would disappear when :func:`PyInit_spam` terminates!" msgstr "" #: ../Doc/extending/extending.rst:1259 msgid "" "The bulk of the work is in the header file :file:`spammodule.h`, which looks " "like this::" msgstr "" #: ../Doc/extending/extending.rst:1310 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 "" #: ../Doc/extending/extending.rst:1328 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 "" #: ../Doc/extending/extending.rst:1332 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 "" #: ../Doc/extending/extending.rst:1340 ../Doc/extending/newtypes.rst:1506 msgid "Footnotes" msgstr "Notes" #: ../Doc/extending/extending.rst:1341 msgid "" "An interface for this function already exists in the standard module :mod:" "`os` --- it was chosen as a simple and straightforward example." msgstr "" #: ../Doc/extending/extending.rst:1344 msgid "" "The metaphor of \"borrowing\" a reference is not completely correct: the " "owner still has a copy of the reference." msgstr "" #: ../Doc/extending/extending.rst:1347 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 "" #: ../Doc/extending/extending.rst:1351 msgid "" "These guarantees don't hold when you use the \"old\" style calling " "convention --- this is still found in much existing code." msgstr "" #: ../Doc/extending/index.rst:5 msgid "Extending and Embedding the Python Interpreter" msgstr "" #: ../Doc/extending/index.rst:7 msgid "" "This document describes how to write modules in C or C++ to extend the " "Python interpreter with new modules. Those modules can not only define new " "functions but also new object types and their methods. The document also " "describes how to embed the Python interpreter in another application, for " "use as an extension language. Finally, it shows how to compile and link " "extension modules so that they can be loaded dynamically (at run time) into " "the interpreter, if the underlying operating system supports this feature." msgstr "" #: ../Doc/extending/index.rst:15 msgid "" "This document assumes basic knowledge about Python. For an informal " "introduction to the language, see :ref:`tutorial-index`. :ref:`reference-" "index` gives a more formal definition of the language. :ref:`library-index` " "documents the existing object types, functions and modules (both built-in " "and written in Python) that give the language its wide application range." msgstr "" #: ../Doc/extending/index.rst:21 msgid "" "For a detailed description of the whole Python/C API, see the separate :ref:" "`c-api-index`." msgstr "" #: ../Doc/extending/index.rst:26 msgid "Recommended third party tools" msgstr "" #: ../Doc/extending/index.rst:28 msgid "" "This guide only covers the basic tools for creating extensions provided as " "part of this version of CPython. Third party tools like Cython, ``cffi``, " "SWIG and Numba offer both simpler and more sophisticated approaches to " "creating C and C++ extensions for Python." msgstr "" #: ../Doc/extending/index.rst:38 msgid "" "`Python Packaging User Guide: Binary Extensions `_" msgstr "" "`Python Packaging User Guide: Binary Extensions `_" #: ../Doc/extending/index.rst:36 msgid "" "The Python Packaging User Guide not only covers several available tools that " "simplify the creation of binary extensions, but also discusses the various " "reasons why creating an extension module may be desirable in the first place." msgstr "" #: ../Doc/extending/index.rst:43 msgid "Creating extensions without third party tools" msgstr "" #: ../Doc/extending/index.rst:45 msgid "" "This section of the guide covers creating C and C++ extensions without " "assistance from third party tools. It is intended primarily for creators of " "those tools, rather than being a recommended way to create your own C " "extensions." msgstr "" #: ../Doc/extending/index.rst:60 msgid "Embedding the CPython runtime in a larger application" msgstr "" #: ../Doc/extending/index.rst:62 msgid "" "Sometimes, rather than creating an extension that runs inside the Python " "interpreter as the main application, it is desirable to instead embed the " "CPython runtime inside a larger application. This section covers some of the " "details involved in doing that successfully." msgstr "" #: ../Doc/extending/newtypes.rst:8 msgid "Defining New Types" msgstr "" #: ../Doc/extending/newtypes.rst:15 msgid "" "As mentioned in the last chapter, Python allows the writer of an extension " "module to define new types that can be manipulated from Python code, much " "like strings and lists in core Python." msgstr "" #: ../Doc/extending/newtypes.rst:19 msgid "" "This is not hard; the code for all extension types follows a pattern, but " "there are some details that you need to understand before you can get " "started." msgstr "" #: ../Doc/extending/newtypes.rst:26 msgid "The Basics" msgstr "" #: ../Doc/extending/newtypes.rst:28 msgid "" "The Python runtime sees all Python objects as variables of type :c:type:" "`PyObject\\*`, which serves as a \"base type\" for all Python objects. :c:" "type:`PyObject` itself only contains the refcount and a pointer to the " "object's \"type object\". This is where the action is; the type object " "determines which (C) functions get called when, for instance, an attribute " "gets looked up on an object or it is multiplied by another object. These C " "functions are called \"type methods\"." msgstr "" #: ../Doc/extending/newtypes.rst:36 msgid "" "So, if you want to define a new object type, you need to create a new type " "object." msgstr "" #: ../Doc/extending/newtypes.rst:39 msgid "" "This sort of thing can only be explained by example, so here's a minimal, " "but complete, module that defines a new type:" msgstr "" #: ../Doc/extending/newtypes.rst:45 msgid "" "Now that's quite a bit to take in at once, but hopefully bits will seem " "familiar from the last chapter." msgstr "" #: ../Doc/extending/newtypes.rst:48 msgid "The first bit that will be new is::" msgstr "" #: ../Doc/extending/newtypes.rst:54 msgid "" "This is what a Noddy object will contain---in this case, nothing more than " "what every Python object contains---a field called ``ob_base`` of type :c:" "type:`PyObject`. :c:type:`PyObject` in turn, contains an ``ob_refcnt`` " "field and a pointer to a type object. These can be accessed using the " "macros :c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE` respectively. These are " "the fields the :c:macro:`PyObject_HEAD` macro brings in. The reason for the " "macro is to standardize the layout and to enable special debugging fields in " "debug builds." msgstr "" #: ../Doc/extending/newtypes.rst:62 msgid "" "Note that there is no semicolon after the :c:macro:`PyObject_HEAD` macro; " "one is included in the macro definition. Be wary of adding one by accident; " "it's easy to do from habit, and your compiler might not complain, but " "someone else's probably will! (On Windows, MSVC is known to call this an " "error and refuse to compile the code.)" msgstr "" #: ../Doc/extending/newtypes.rst:68 msgid "" "For contrast, let's take a look at the corresponding definition for standard " "Python floats::" msgstr "" #: ../Doc/extending/newtypes.rst:76 msgid "Moving on, we come to the crunch --- the type object. ::" msgstr "" #: ../Doc/extending/newtypes.rst:102 msgid "" "Now if you go and look up the definition of :c:type:`PyTypeObject` in :file:" "`object.h` you'll see that it has many more fields that the definition " "above. The remaining fields will be filled with zeros by the C compiler, " "and it's common practice to not specify them explicitly unless you need them." msgstr "" #: ../Doc/extending/newtypes.rst:107 msgid "" "This is so important that we're going to pick the top of it apart still " "further::" msgstr "" #: ../Doc/extending/newtypes.rst:112 msgid "This line is a bit of a wart; what we'd like to write is::" msgstr "" #: ../Doc/extending/newtypes.rst:116 msgid "" "as the type of a type object is \"type\", but this isn't strictly conforming " "C and some compilers complain. Fortunately, this member will be filled in " "for us by :c:func:`PyType_Ready`. ::" msgstr "" #: ../Doc/extending/newtypes.rst:122 msgid "" "The name of our type. This will appear in the default textual " "representation of our objects and in some error messages, for example::" msgstr "" #: ../Doc/extending/newtypes.rst:130 msgid "" "Note that the name is a dotted name that includes both the module name and " "the name of the type within the module. The module in this case is :mod:" "`noddy` and the type is :class:`Noddy`, so we set the type name to :class:" "`noddy.Noddy`. One side effect of using an undotted name is that the pydoc " "documentation tool will not list the new type in the module documentation. ::" msgstr "" #: ../Doc/extending/newtypes.rst:138 msgid "" "This is so that Python knows how much memory to allocate when you call :c:" "func:`PyObject_New`." msgstr "" #: ../Doc/extending/newtypes.rst:143 msgid "" "If you want your type to be subclassable from Python, and your type has the " "same :c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have " "problems with multiple inheritance. A Python subclass of your type will " "have to list your type first in its :attr:`~class.__bases__`, or else it " "will not be able to call your type's :meth:`__new__` method without getting " "an error. You can avoid this problem by ensuring that your type has a " "larger value for :c:member:`~PyTypeObject.tp_basicsize` than its base type " "does. Most of the time, this will be true anyway, because either your base " "type will be :class:`object`, or else you will be adding data members to " "your base type, and therefore increasing its size." msgstr "" #: ../Doc/extending/newtypes.rst:157 msgid "" "This has to do with variable length objects like lists and strings. Ignore " "this for now." msgstr "" #: ../Doc/extending/newtypes.rst:160 msgid "" "Skipping a number of type methods that we don't provide, we set the class " "flags to :const:`Py_TPFLAGS_DEFAULT`. ::" msgstr "" #: ../Doc/extending/newtypes.rst:165 msgid "" "All types should include this constant in their flags. It enables all of " "the members defined until at least Python 3.3. If you need further members, " "you will need to OR the corresponding flags." msgstr "" #: ../Doc/extending/newtypes.rst:169 msgid "" "We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::" msgstr "" #: ../Doc/extending/newtypes.rst:173 msgid "" "Now we get into the type methods, the things that make your objects " "different from the others. We aren't going to implement any of these in " "this version of the module. We'll expand this example later to have more " "interesting behavior." msgstr "" #: ../Doc/extending/newtypes.rst:177 msgid "" "For now, all we want to be able to do is to create new :class:`Noddy` " "objects. To enable object creation, we have to provide a :c:member:" "`~PyTypeObject.tp_new` implementation. In this case, we can just use the " "default implementation provided by the API function :c:func:" "`PyType_GenericNew`. We'd like to just assign this to the :c:member:" "`~PyTypeObject.tp_new` slot, but we can't, for portability sake, On some " "platforms or compilers, we can't statically initialize a structure member " "with a function defined in another C module, so, instead, we'll assign the :" "c:member:`~PyTypeObject.tp_new` slot in the module initialization function " "just before calling :c:func:`PyType_Ready`::" msgstr "" #: ../Doc/extending/newtypes.rst:191 msgid "" "All the other type methods are *NULL*, so we'll go over them later --- " "that's for a later section!" msgstr "" #: ../Doc/extending/newtypes.rst:194 msgid "" "Everything else in the file should be familiar, except for some code in :c:" "func:`PyInit_noddy`::" msgstr "" #: ../Doc/extending/newtypes.rst:200 msgid "" "This initializes the :class:`Noddy` type, filing in a number of members, " "including :attr:`ob_type` that we initially set to *NULL*. ::" msgstr "" #: ../Doc/extending/newtypes.rst:205 msgid "" "This adds the type to the module dictionary. This allows us to create :" "class:`Noddy` instances by calling the :class:`Noddy` class::" msgstr "" #: ../Doc/extending/newtypes.rst:211 msgid "" "That's it! All that remains is to build it; put the above code in a file " "called :file:`noddy.c` and ::" msgstr "" #: ../Doc/extending/newtypes.rst:218 msgid "in a file called :file:`setup.py`; then typing" msgstr "" #: ../Doc/extending/newtypes.rst:224 msgid "" "at a shell should produce a file :file:`noddy.so` in a subdirectory; move to " "that directory and fire up Python --- you should be able to ``import noddy`` " "and play around with Noddy objects." msgstr "" #: ../Doc/extending/newtypes.rst:228 msgid "That wasn't so hard, was it?" msgstr "" #: ../Doc/extending/newtypes.rst:230 msgid "" "Of course, the current Noddy type is pretty uninteresting. It has no data " "and doesn't do anything. It can't even be subclassed." msgstr "" #: ../Doc/extending/newtypes.rst:235 msgid "Adding data and methods to the Basic example" msgstr "" #: ../Doc/extending/newtypes.rst:237 msgid "" "Let's extend the basic example to add some data and methods. Let's also " "make the type usable as a base class. We'll create a new module, :mod:" "`noddy2` that adds these capabilities:" msgstr "" #: ../Doc/extending/newtypes.rst:244 msgid "This version of the module has a number of changes." msgstr "" #: ../Doc/extending/newtypes.rst:246 msgid "We've added an extra include::" msgstr "" #: ../Doc/extending/newtypes.rst:250 msgid "" "This include provides declarations that we use to handle attributes, as " "described a bit later." msgstr "" #: ../Doc/extending/newtypes.rst:253 msgid "" "The name of the :class:`Noddy` object structure has been shortened to :class:" "`Noddy`. The type object name has been shortened to :class:`NoddyType`." msgstr "" #: ../Doc/extending/newtypes.rst:256 msgid "" "The :class:`Noddy` type now has three data attributes, *first*, *last*, and " "*number*. The *first* and *last* variables are Python strings containing " "first and last names. The *number* attribute is an integer." msgstr "" #: ../Doc/extending/newtypes.rst:260 msgid "The object structure is updated accordingly::" msgstr "" #: ../Doc/extending/newtypes.rst:269 msgid "" "Because we now have data to manage, we have to be more careful about object " "allocation and deallocation. At a minimum, we need a deallocation method::" msgstr "" #: ../Doc/extending/newtypes.rst:280 msgid "which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::" msgstr "" #: ../Doc/extending/newtypes.rst:284 msgid "" "This method decrements the reference counts of the two Python attributes. We " "use :c:func:`Py_XDECREF` here because the :attr:`first` and :attr:`last` " "members could be *NULL*. It then calls the :c:member:`~PyTypeObject." "tp_free` member of the object's type to free the object's memory. Note that " "the object's type might not be :class:`NoddyType`, because the object may be " "an instance of a subclass." msgstr "" #: ../Doc/extending/newtypes.rst:290 msgid "" "We want to make sure that the first and last names are initialized to empty " "strings, so we provide a new method::" msgstr "" #: ../Doc/extending/newtypes.rst:318 msgid "and install it in the :c:member:`~PyTypeObject.tp_new` member::" msgstr "" #: ../Doc/extending/newtypes.rst:322 msgid "" "The new member is responsible for creating (as opposed to initializing) " "objects of the type. It is exposed in Python as the :meth:`__new__` " "method. See the paper titled \"Unifying types and classes in Python\" for a " "detailed discussion of the :meth:`__new__` method. One reason to implement " "a new method is to assure the initial values of instance variables. In this " "case, we use the new method to make sure that the initial values of the " "members :attr:`first` and :attr:`last` are not *NULL*. If we didn't care " "whether the initial values were *NULL*, we could have used :c:func:" "`PyType_GenericNew` as our new method, as we did before. :c:func:" "`PyType_GenericNew` initializes all of the instance variable members to " "*NULL*." msgstr "" #: ../Doc/extending/newtypes.rst:333 msgid "" "The new method is a static method that is passed the type being instantiated " "and any arguments passed when the type was called, and that returns the new " "object created. New methods always accept positional and keyword arguments, " "but they often ignore the arguments, leaving the argument handling to " "initializer methods. Note that if the type supports subclassing, the type " "passed may not be the type being defined. The new method calls the :c:" "member:`~PyTypeObject.tp_alloc` slot to allocate memory. We don't fill the :" "c:member:`~PyTypeObject.tp_alloc` slot ourselves. Rather :c:func:" "`PyType_Ready` fills it for us by inheriting it from our base class, which " "is :class:`object` by default. Most types use the default allocation." msgstr "" #: ../Doc/extending/newtypes.rst:345 msgid "" "If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one " "that calls a base type's :c:member:`~PyTypeObject.tp_new` or :meth:" "`__new__`), you must *not* try to determine what method to call using method " "resolution order at runtime. Always statically determine what type you are " "going to call, and call its :c:member:`~PyTypeObject.tp_new` directly, or " "via ``type->tp_base->tp_new``. If you do not do this, Python subclasses of " "your type that also inherit from other Python-defined classes may not work " "correctly. (Specifically, you may not be able to create instances of such " "subclasses without getting a :exc:`TypeError`.)" msgstr "" #: ../Doc/extending/newtypes.rst:354 msgid "We provide an initialization function::" msgstr "" #: ../Doc/extending/newtypes.rst:385 msgid "by filling the :c:member:`~PyTypeObject.tp_init` slot. ::" msgstr "" #: ../Doc/extending/newtypes.rst:389 msgid "" "The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as the :meth:" "`__init__` method. It is used to initialize an object after it's created. " "Unlike the new method, we can't guarantee that the initializer is called. " "The initializer isn't called when unpickling objects and it can be " "overridden. Our initializer accepts arguments to provide initial values for " "our instance. Initializers always accept positional and keyword arguments. " "Initializers should return either 0 on success or -1 on error." msgstr "" #: ../Doc/extending/newtypes.rst:397 msgid "" "Initializers can be called multiple times. Anyone can call the :meth:" "`__init__` method on our objects. For this reason, we have to be extra " "careful when assigning the new values. We might be tempted, for example to " "assign the :attr:`first` member like this::" msgstr "" #: ../Doc/extending/newtypes.rst:408 msgid "" "But this would be risky. Our type doesn't restrict the type of the :attr:" "`first` member, so it could be any kind of object. It could have a " "destructor that causes code to be executed that tries to access the :attr:" "`first` member. To be paranoid and protect ourselves against this " "possibility, we almost always reassign members before decrementing their " "reference counts. When don't we have to do this?" msgstr "" #: ../Doc/extending/newtypes.rst:415 msgid "when we absolutely know that the reference count is greater than 1" msgstr "" #: ../Doc/extending/newtypes.rst:417 msgid "" "when we know that deallocation of the object [#]_ will not cause any calls " "back into our type's code" msgstr "" #: ../Doc/extending/newtypes.rst:420 msgid "" "when decrementing a reference count in a :c:member:`~PyTypeObject." "tp_dealloc` handler when garbage-collections is not supported [#]_" msgstr "" #: ../Doc/extending/newtypes.rst:423 msgid "" "We want to expose our instance variables as attributes. There are a number " "of ways to do that. The simplest way is to define member definitions::" msgstr "" #: ../Doc/extending/newtypes.rst:436 msgid "" "and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::" msgstr "" #: ../Doc/extending/newtypes.rst:440 msgid "" "Each member definition has a member name, type, offset, access flags and " "documentation string. See the :ref:`Generic-Attribute-Management` section " "below for details." msgstr "" #: ../Doc/extending/newtypes.rst:444 msgid "" "A disadvantage of this approach is that it doesn't provide a way to restrict " "the types of objects that can be assigned to the Python attributes. We " "expect the first and last names to be strings, but any Python objects can be " "assigned. Further, the attributes can be deleted, setting the C pointers to " "*NULL*. Even though we can make sure the members are initialized to non-" "*NULL* values, the members can be set to *NULL* if the attributes are " "deleted." msgstr "" #: ../Doc/extending/newtypes.rst:451 msgid "" "We define a single method, :meth:`name`, that outputs the objects name as " "the concatenation of the first and last names. ::" msgstr "" #: ../Doc/extending/newtypes.rst:470 msgid "" "The method is implemented as a C function that takes a :class:`Noddy` (or :" "class:`Noddy` subclass) instance as the first argument. Methods always take " "an instance as the first argument. Methods often take positional and keyword " "arguments as well, but in this case we don't take any and don't need to " "accept a positional argument tuple or keyword argument dictionary. This " "method is equivalent to the Python method::" msgstr "" #: ../Doc/extending/newtypes.rst:480 msgid "" "Note that we have to check for the possibility that our :attr:`first` and :" "attr:`last` members are *NULL*. This is because they can be deleted, in " "which case they are set to *NULL*. It would be better to prevent deletion " "of these attributes and to restrict the attribute values to be strings. " "We'll see how to do that in the next section." msgstr "" #: ../Doc/extending/newtypes.rst:486 msgid "" "Now that we've defined the method, we need to create an array of method " "definitions::" msgstr "" #: ../Doc/extending/newtypes.rst:496 msgid "and assign them to the :c:member:`~PyTypeObject.tp_methods` slot::" msgstr "" #: ../Doc/extending/newtypes.rst:500 msgid "" "Note that we used the :const:`METH_NOARGS` flag to indicate that the method " "is passed no arguments." msgstr "" #: ../Doc/extending/newtypes.rst:503 msgid "" "Finally, we'll make our type usable as a base class. We've written our " "methods carefully so far so that they don't make any assumptions about the " "type of the object being created or used, so all we need to do is to add " "the :const:`Py_TPFLAGS_BASETYPE` to our class flag definition::" msgstr "" #: ../Doc/extending/newtypes.rst:510 msgid "" "We rename :c:func:`PyInit_noddy` to :c:func:`PyInit_noddy2` and update the " "module name in the :c:type:`PyModuleDef` struct." msgstr "" #: ../Doc/extending/newtypes.rst:513 msgid "Finally, we update our :file:`setup.py` file to build the new module::" msgstr "" #: ../Doc/extending/newtypes.rst:524 msgid "Providing finer control over data attributes" msgstr "" #: ../Doc/extending/newtypes.rst:526 msgid "" "In this section, we'll provide finer control over how the :attr:`first` and :" "attr:`last` attributes are set in the :class:`Noddy` example. In the " "previous version of our module, the instance variables :attr:`first` and :" "attr:`last` could be set to non-string values or even deleted. We want to " "make sure that these attributes always contain strings." msgstr "" #: ../Doc/extending/newtypes.rst:535 msgid "" "To provide greater control, over the :attr:`first` and :attr:`last` " "attributes, we'll use custom getter and setter functions. Here are the " "functions for getting and setting the :attr:`first` attribute::" msgstr "" #: ../Doc/extending/newtypes.rst:566 msgid "" "The getter function is passed a :class:`Noddy` object and a \"closure\", " "which is void pointer. In this case, the closure is ignored. (The closure " "supports an advanced usage in which definition data is passed to the getter " "and setter. This could, for example, be used to allow a single set of getter " "and setter functions that decide the attribute to get or set based on data " "in the closure.)" msgstr "" #: ../Doc/extending/newtypes.rst:572 msgid "" "The setter function is passed the :class:`Noddy` object, the new value, and " "the closure. The new value may be *NULL*, in which case the attribute is " "being deleted. In our setter, we raise an error if the attribute is deleted " "or if the attribute value is not a string." msgstr "" #: ../Doc/extending/newtypes.rst:577 msgid "We create an array of :c:type:`PyGetSetDef` structures::" msgstr "" #: ../Doc/extending/newtypes.rst:591 msgid "and register it in the :c:member:`~PyTypeObject.tp_getset` slot::" msgstr "" #: ../Doc/extending/newtypes.rst:595 msgid "to register our attribute getters and setters." msgstr "" #: ../Doc/extending/newtypes.rst:597 msgid "" "The last item in a :c:type:`PyGetSetDef` structure is the closure mentioned " "above. In this case, we aren't using the closure, so we just pass *NULL*." msgstr "" #: ../Doc/extending/newtypes.rst:600 msgid "We also remove the member definitions for these attributes::" msgstr "" #: ../Doc/extending/newtypes.rst:608 msgid "" "We also need to update the :c:member:`~PyTypeObject.tp_init` handler to only " "allow strings [#]_ to be passed::" msgstr "" #: ../Doc/extending/newtypes.rst:640 msgid "" "With these changes, we can assure that the :attr:`first` and :attr:`last` " "members are never *NULL* so we can remove checks for *NULL* values in almost " "all cases. This means that most of the :c:func:`Py_XDECREF` calls can be " "converted to :c:func:`Py_DECREF` calls. The only place we can't change these " "calls is in the deallocator, where there is the possibility that the " "initialization of these members failed in the constructor." msgstr "" #: ../Doc/extending/newtypes.rst:647 msgid "" "We also rename the module initialization function and module name in the " "initialization function, as we did before, and we add an extra definition to " "the :file:`setup.py` file." msgstr "" #: ../Doc/extending/newtypes.rst:653 msgid "Supporting cyclic garbage collection" msgstr "" #: ../Doc/extending/newtypes.rst:655 msgid "" "Python has a cyclic-garbage collector that can identify unneeded objects " "even when their reference counts are not zero. This can happen when objects " "are involved in cycles. For example, consider::" msgstr "" #: ../Doc/extending/newtypes.rst:663 msgid "" "In this example, we create a list that contains itself. When we delete it, " "it still has a reference from itself. Its reference count doesn't drop to " "zero. Fortunately, Python's cyclic-garbage collector will eventually figure " "out that the list is garbage and free it." msgstr "" #: ../Doc/extending/newtypes.rst:668 msgid "" "In the second version of the :class:`Noddy` example, we allowed any kind of " "object to be stored in the :attr:`first` or :attr:`last` attributes. [#]_ " "This means that :class:`Noddy` objects can participate in cycles::" msgstr "" #: ../Doc/extending/newtypes.rst:677 msgid "" "This is pretty silly, but it gives us an excuse to add support for the " "cyclic-garbage collector to the :class:`Noddy` example. To support cyclic " "garbage collection, types need to fill two slots and set a class flag that " "enables these slots:" msgstr "" #: ../Doc/extending/newtypes.rst:685 msgid "" "The traversal method provides access to subobjects that could participate in " "cycles::" msgstr "" #: ../Doc/extending/newtypes.rst:707 msgid "" "For each subobject that can participate in cycles, we need to call the :c:" "func:`visit` function, which is passed to the traversal method. The :c:func:" "`visit` function takes as arguments the subobject and the extra argument " "*arg* passed to the traversal method. It returns an integer value that must " "be returned if it is non-zero." msgstr "" #: ../Doc/extending/newtypes.rst:713 msgid "" "Python provides a :c:func:`Py_VISIT` macro that automates calling visit " "functions. With :c:func:`Py_VISIT`, :c:func:`Noddy_traverse` can be " "simplified::" msgstr "" #: ../Doc/extending/newtypes.rst:726 msgid "" "Note that the :c:member:`~PyTypeObject.tp_traverse` implementation must name " "its arguments exactly *visit* and *arg* in order to use :c:func:`Py_VISIT`. " "This is to encourage uniformity across these boring implementations." msgstr "" #: ../Doc/extending/newtypes.rst:730 msgid "" "We also need to provide a method for clearing any subobjects that can " "participate in cycles. We implement the method and reimplement the " "deallocator to use it::" msgstr "" #: ../Doc/extending/newtypes.rst:757 msgid "" "Notice the use of a temporary variable in :c:func:`Noddy_clear`. We use the " "temporary variable so that we can set each member to *NULL* before " "decrementing its reference count. We do this because, as was discussed " "earlier, if the reference count drops to zero, we might cause code to run " "that calls back into the object. In addition, because we now support " "garbage collection, we also have to worry about code being run that triggers " "garbage collection. If garbage collection is run, our :c:member:" "`~PyTypeObject.tp_traverse` handler could get called. We can't take a chance " "of having :c:func:`Noddy_traverse` called when a member's reference count " "has dropped to zero and its value hasn't been set to *NULL*." msgstr "" #: ../Doc/extending/newtypes.rst:767 msgid "" "Python provides a :c:func:`Py_CLEAR` that automates the careful decrementing " "of reference counts. With :c:func:`Py_CLEAR`, the :c:func:`Noddy_clear` " "function can be simplified::" msgstr "" #: ../Doc/extending/newtypes.rst:779 msgid "" "Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::" msgstr "" #: ../Doc/extending/newtypes.rst:783 msgid "" "That's pretty much it. If we had written custom :c:member:`~PyTypeObject." "tp_alloc` or :c:member:`~PyTypeObject.tp_free` slots, we'd need to modify " "them for cyclic-garbage collection. Most extensions will use the versions " "automatically provided." msgstr "" #: ../Doc/extending/newtypes.rst:789 msgid "Subclassing other types" msgstr "" #: ../Doc/extending/newtypes.rst:791 msgid "" "It is possible to create new extension types that are derived from existing " "types. It is easiest to inherit from the built in types, since an extension " "can easily use the :class:`PyTypeObject` it needs. It can be difficult to " "share these :class:`PyTypeObject` structures between extension modules." msgstr "" #: ../Doc/extending/newtypes.rst:796 msgid "" "In this example we will create a :class:`Shoddy` type that inherits from the " "built-in :class:`list` type. The new type will be completely compatible with " "regular lists, but will have an additional :meth:`increment` method that " "increases an internal counter. ::" msgstr "" #: ../Doc/extending/newtypes.rst:814 msgid "" "As you can see, the source code closely resembles the :class:`Noddy` " "examples in previous sections. We will break down the main differences " "between them. ::" msgstr "" #: ../Doc/extending/newtypes.rst:822 msgid "" "The primary difference for derived type objects is that the base type's " "object structure must be the first value. The base type will already include " "the :c:func:`PyObject_HEAD` at the beginning of its structure." msgstr "" #: ../Doc/extending/newtypes.rst:826 msgid "" "When a Python object is a :class:`Shoddy` instance, its *PyObject\\** " "pointer can be safely cast to both *PyListObject\\** and *Shoddy\\**. ::" msgstr "" #: ../Doc/extending/newtypes.rst:838 msgid "" "In the :attr:`__init__` method for our type, we can see how to call through " "to the :attr:`__init__` method of the base type." msgstr "" #: ../Doc/extending/newtypes.rst:841 msgid "" "This pattern is important when writing a type with custom :attr:`new` and :" "attr:`dealloc` methods. The :attr:`new` method should not actually create " "the memory for the object with :c:member:`~PyTypeObject.tp_alloc`, that will " "be handled by the base class when calling its :c:member:`~PyTypeObject." "tp_new`." msgstr "" #: ../Doc/extending/newtypes.rst:846 msgid "" "When filling out the :c:func:`PyTypeObject` for the :class:`Shoddy` type, " "you see a slot for :c:func:`tp_base`. Due to cross platform compiler issues, " "you can't fill that field directly with the :c:func:`PyList_Type`; it can be " "done later in the module's :c:func:`init` function. ::" msgstr "" #: ../Doc/extending/newtypes.rst:869 msgid "" "Before calling :c:func:`PyType_Ready`, the type structure must have the :c:" "member:`~PyTypeObject.tp_base` slot filled in. When we are deriving a new " "type, it is not necessary to fill out the :c:member:`~PyTypeObject.tp_alloc` " "slot with :c:func:`PyType_GenericNew` -- the allocate function from the base " "type will be inherited." msgstr "" #: ../Doc/extending/newtypes.rst:874 msgid "" "After that, calling :c:func:`PyType_Ready` and adding the type object to the " "module is the same as with the basic :class:`Noddy` examples." msgstr "" #: ../Doc/extending/newtypes.rst:881 msgid "Type Methods" msgstr "" #: ../Doc/extending/newtypes.rst:883 msgid "" "This section aims to give a quick fly-by on the various type methods you can " "implement and what they do." msgstr "" #: ../Doc/extending/newtypes.rst:886 msgid "" "Here is the definition of :c:type:`PyTypeObject`, with some fields only used " "in debug builds omitted:" msgstr "" #: ../Doc/extending/newtypes.rst:892 msgid "" "Now that's a *lot* of methods. Don't worry too much though - if you have a " "type you want to define, the chances are very good that you will only " "implement a handful of these." msgstr "" #: ../Doc/extending/newtypes.rst:896 msgid "" "As you probably expect by now, we're going to go over this and give more " "information about the various handlers. We won't go in the order they are " "defined in the structure, because there is a lot of historical baggage that " "impacts the ordering of the fields; be sure your type initialization keeps " "the fields in the right order! It's often easiest to find an example that " "includes all the fields you need (even if they're initialized to ``0``) and " "then change the values to suit your new type. ::" msgstr "" #: ../Doc/extending/newtypes.rst:906 msgid "" "The name of the type - as mentioned in the last section, this will appear in " "various places, almost entirely for diagnostic purposes. Try to choose " "something that will be helpful in such a situation! ::" msgstr "" #: ../Doc/extending/newtypes.rst:912 msgid "" "These fields tell the runtime how much memory to allocate when new objects " "of this type are created. Python has some built-in support for variable " "length structures (think: strings, lists) which is where the :c:member:" "`~PyTypeObject.tp_itemsize` field comes in. This will be dealt with " "later. ::" msgstr "" #: ../Doc/extending/newtypes.rst:919 msgid "" "Here you can put a string (or its address) that you want returned when the " "Python script references ``obj.__doc__`` to retrieve the doc string." msgstr "" #: ../Doc/extending/newtypes.rst:922 msgid "" "Now we come to the basic type methods---the ones most extension types will " "implement." msgstr "" #: ../Doc/extending/newtypes.rst:927 msgid "Finalization and De-allocation" msgstr "" #: ../Doc/extending/newtypes.rst:939 msgid "" "This function is called when the reference count of the instance of your " "type is reduced to zero and the Python interpreter wants to reclaim it. If " "your type has memory to free or other clean-up to perform, you can put it " "here. The object itself needs to be freed here as well. Here is an example " "of this function::" msgstr "" #: ../Doc/extending/newtypes.rst:956 msgid "" "One important requirement of the deallocator function is that it leaves any " "pending exceptions alone. This is important since deallocators are " "frequently called as the interpreter unwinds the Python stack; when the " "stack is unwound due to an exception (rather than normal returns), nothing " "is done to protect the deallocators from seeing that an exception has " "already been set. Any actions which a deallocator performs which may cause " "additional Python code to be executed may detect that an exception has been " "set. This can lead to misleading errors from the interpreter. The proper " "way to protect against this is to save a pending exception before performing " "the unsafe action, and restoring it when done. This can be done using the :" "c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::" msgstr "" #: ../Doc/extending/newtypes.rst:995 msgid "" "There are limitations to what you can safely do in a deallocator function. " "First, if your type supports garbage collection (using :c:member:" "`~PyTypeObject.tp_traverse` and/or :c:member:`~PyTypeObject.tp_clear`), some " "of the object's members can have been cleared or finalized by the time :c:" "member:`~PyTypeObject.tp_dealloc` is called. Second, in :c:member:" "`~PyTypeObject.tp_dealloc`, your object is in an unstable state: its " "reference count is equal to zero. Any call to a non-trivial object or API " "(as in the example above) might end up calling :c:member:`~PyTypeObject." "tp_dealloc` again, causing a double free and a crash." msgstr "" #: ../Doc/extending/newtypes.rst:1004 msgid "" "Starting with Python 3.4, it is recommended not to put any complex " "finalization code in :c:member:`~PyTypeObject.tp_dealloc`, and instead use " "the new :c:member:`~PyTypeObject.tp_finalize` type method." msgstr "" #: ../Doc/extending/newtypes.rst:1009 msgid ":pep:`442` explains the new finalization scheme." msgstr "" #: ../Doc/extending/newtypes.rst:1016 msgid "Object Presentation" msgstr "" #: ../Doc/extending/newtypes.rst:1018 msgid "" "In Python, there are two ways to generate a textual representation of an " "object: the :func:`repr` function, and the :func:`str` function. (The :func:" "`print` function just calls :func:`str`.) These handlers are both optional." msgstr "" #: ../Doc/extending/newtypes.rst:1027 msgid "" "The :c:member:`~PyTypeObject.tp_repr` handler should return a string object " "containing a representation of the instance for which it is called. Here is " "a simple example::" msgstr "" #: ../Doc/extending/newtypes.rst:1038 msgid "" "If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the " "interpreter will supply a representation that uses the type's :c:member:" "`~PyTypeObject.tp_name` and a uniquely-identifying value for the object." msgstr "" #: ../Doc/extending/newtypes.rst:1042 msgid "" "The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what the :c:" "member:`~PyTypeObject.tp_repr` handler described above is to :func:`repr`; " "that is, it is called when Python code calls :func:`str` on an instance of " "your object. Its implementation is very similar to the :c:member:" "`~PyTypeObject.tp_repr` function, but the resulting string is intended for " "human consumption. If :c:member:`~PyTypeObject.tp_str` is not specified, " "the :c:member:`~PyTypeObject.tp_repr` handler is used instead." msgstr "" #: ../Doc/extending/newtypes.rst:1049 msgid "Here is a simple example::" msgstr "" #: ../Doc/extending/newtypes.rst:1061 msgid "Attribute Management" msgstr "" #: ../Doc/extending/newtypes.rst:1063 msgid "" "For every object which can support attributes, the corresponding type must " "provide the functions that control how the attributes are resolved. There " "needs to be a function which can retrieve attributes (if any are defined), " "and another to set attributes (if setting attributes is allowed). Removing " "an attribute is a special case, for which the new value passed to the " "handler is *NULL*." msgstr "" #: ../Doc/extending/newtypes.rst:1069 msgid "" "Python supports two pairs of attribute handlers; a type that supports " "attributes only needs to implement the functions for one pair. The " "difference is that one pair takes the name of the attribute as a :c:type:" "`char\\*`, while the other accepts a :c:type:`PyObject\\*`. Each type can " "use whichever pair makes more sense for the implementation's convenience. ::" msgstr "" #: ../Doc/extending/newtypes.rst:1081 msgid "" "If accessing attributes of an object is always a simple operation (this will " "be explained shortly), there are generic implementations which can be used " "to provide the :c:type:`PyObject\\*` version of the attribute management " "functions. The actual need for type-specific attribute handlers almost " "completely disappeared starting with Python 2.2, though there are many " "examples which have not been updated to use some of the new generic " "mechanism that is available." msgstr "" #: ../Doc/extending/newtypes.rst:1092 msgid "Generic Attribute Management" msgstr "" #: ../Doc/extending/newtypes.rst:1094 msgid "" "Most extension types only use *simple* attributes. So, what makes the " "attributes simple? There are only a couple of conditions that must be met:" msgstr "" #: ../Doc/extending/newtypes.rst:1097 msgid "" "The name of the attributes must be known when :c:func:`PyType_Ready` is " "called." msgstr "" #: ../Doc/extending/newtypes.rst:1100 msgid "" "No special processing is needed to record that an attribute was looked up or " "set, nor do actions need to be taken based on the value." msgstr "" #: ../Doc/extending/newtypes.rst:1103 msgid "" "Note that this list does not place any restrictions on the values of the " "attributes, when the values are computed, or how relevant data is stored." msgstr "" #: ../Doc/extending/newtypes.rst:1106 msgid "" "When :c:func:`PyType_Ready` is called, it uses three tables referenced by " "the type object to create :term:`descriptor`\\s which are placed in the " "dictionary of the type object. Each descriptor controls access to one " "attribute of the instance object. Each of the tables is optional; if all " "three are *NULL*, instances of the type will only have attributes that are " "inherited from their base type, and should leave the :c:member:" "`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields " "*NULL* as well, allowing the base type to handle attributes." msgstr "" #: ../Doc/extending/newtypes.rst:1114 msgid "The tables are declared as three fields of the type object::" msgstr "" #: ../Doc/extending/newtypes.rst:1120 msgid "" "If :c:member:`~PyTypeObject.tp_methods` is not *NULL*, it must refer to an " "array of :c:type:`PyMethodDef` structures. Each entry in the table is an " "instance of this structure::" msgstr "" #: ../Doc/extending/newtypes.rst:1131 msgid "" "One entry should be defined for each method provided by the type; no entries " "are needed for methods inherited from a base type. One additional entry is " "needed at the end; it is a sentinel that marks the end of the array. The :" "attr:`ml_name` field of the sentinel must be *NULL*." msgstr "" #: ../Doc/extending/newtypes.rst:1136 msgid "" "The second table is used to define attributes which map directly to data " "stored in the instance. A variety of primitive C types are supported, and " "access may be read-only or read-write. The structures in the table are " "defined as::" msgstr "" #: ../Doc/extending/newtypes.rst:1148 msgid "" "For each entry in the table, a :term:`descriptor` will be constructed and " "added to the type which will be able to extract a value from the instance " "structure. The :attr:`type` field should contain one of the type codes " "defined in the :file:`structmember.h` header; the value will be used to " "determine how to convert Python values to and from C values. The :attr:" "`flags` field is used to store flags which control how the attribute can be " "accessed." msgstr "" #: ../Doc/extending/newtypes.rst:1155 msgid "" "The following flag constants are defined in :file:`structmember.h`; they may " "be combined using bitwise-OR." msgstr "" #: ../Doc/extending/newtypes.rst:1159 msgid "Constant" msgstr "" #: ../Doc/extending/newtypes.rst:1159 msgid "Meaning" msgstr "Signification" #: ../Doc/extending/newtypes.rst:1161 msgid ":const:`READONLY`" msgstr "" #: ../Doc/extending/newtypes.rst:1161 msgid "Never writable." msgstr "" #: ../Doc/extending/newtypes.rst:1163 msgid ":const:`READ_RESTRICTED`" msgstr "" #: ../Doc/extending/newtypes.rst:1163 msgid "Not readable in restricted mode." msgstr "" #: ../Doc/extending/newtypes.rst:1165 msgid ":const:`WRITE_RESTRICTED`" msgstr "" #: ../Doc/extending/newtypes.rst:1165 msgid "Not writable in restricted mode." msgstr "" #: ../Doc/extending/newtypes.rst:1167 msgid ":const:`RESTRICTED`" msgstr "" #: ../Doc/extending/newtypes.rst:1167 msgid "Not readable or writable in restricted mode." msgstr "" #: ../Doc/extending/newtypes.rst:1176 msgid "" "An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` " "table to build descriptors that are used at runtime is that any attribute " "defined this way can have an associated doc string simply by providing the " "text in the table. An application can use the introspection API to retrieve " "the descriptor from the class object, and get the doc string using its :attr:" "`__doc__` attribute." msgstr "" #: ../Doc/extending/newtypes.rst:1182 msgid "" "As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry " "with a :attr:`name` value of *NULL* is required." msgstr "" #: ../Doc/extending/newtypes.rst:1196 msgid "Type-specific Attribute Management" msgstr "" #: ../Doc/extending/newtypes.rst:1198 msgid "" "For simplicity, only the :c:type:`char\\*` version will be demonstrated " "here; the type of the name parameter is the only difference between the :c:" "type:`char\\*` and :c:type:`PyObject\\*` flavors of the interface. This " "example effectively does the same thing as the generic example above, but " "does not use the generic support added in Python 2.2. It explains how the " "handler functions are called, so that if you do need to extend their " "functionality, you'll understand what needs to be done." msgstr "" #: ../Doc/extending/newtypes.rst:1206 msgid "" "The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object " "requires an attribute look-up. It is called in the same situations where " "the :meth:`__getattr__` method of a class would be called." msgstr "" #: ../Doc/extending/newtypes.rst:1210 msgid "Here is an example::" msgstr "" #: ../Doc/extending/newtypes.rst:1226 msgid "" "The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:" "`__setattr__` or :meth:`__delattr__` method of a class instance would be " "called. When an attribute should be deleted, the third parameter will be " "*NULL*. Here is an example that simply raises an exception; if this were " "really all you wanted, the :c:member:`~PyTypeObject.tp_setattr` handler " "should be set to *NULL*. ::" msgstr "" #: ../Doc/extending/newtypes.rst:1240 msgid "Object Comparison" msgstr "" #: ../Doc/extending/newtypes.rst:1246 msgid "" "The :c:member:`~PyTypeObject.tp_richcompare` handler is called when " "comparisons are needed. It is analogous to the :ref:`rich comparison " "methods `, like :meth:`__lt__`, and also called by :c:func:" "`PyObject_RichCompare` and :c:func:`PyObject_RichCompareBool`." msgstr "" #: ../Doc/extending/newtypes.rst:1251 msgid "" "This function is called with two Python objects and the operator as " "arguments, where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, " "``Py_GT``, ``Py_LT`` or ``Py_GT``. It should compare the two objects with " "respect to the specified operator and return ``Py_True`` or ``Py_False`` if " "the comparison is successful, ``Py_NotImplemented`` to indicate that " "comparison is not implemented and the other object's comparison method " "should be tried, or *NULL* if an exception was set." msgstr "" #: ../Doc/extending/newtypes.rst:1259 msgid "" "Here is a sample implementation, for a datatype that is considered equal if " "the size of an internal pointer is equal::" msgstr "" #: ../Doc/extending/newtypes.rst:1289 msgid "Abstract Protocol Support" msgstr "" #: ../Doc/extending/newtypes.rst:1291 msgid "" "Python supports a variety of *abstract* 'protocols;' the specific interfaces " "provided to use these interfaces are documented in :ref:`abstract`." msgstr "" #: ../Doc/extending/newtypes.rst:1295 msgid "" "A number of these abstract interfaces were defined early in the development " "of the Python implementation. In particular, the number, mapping, and " "sequence protocols have been part of Python since the beginning. Other " "protocols have been added over time. For protocols which depend on several " "handler routines from the type implementation, the older protocols have been " "defined as optional blocks of handlers referenced by the type object. For " "newer protocols there are additional slots in the main type object, with a " "flag bit being set to indicate that the slots are present and should be " "checked by the interpreter. (The flag bit does not indicate that the slot " "values are non-*NULL*. The flag may be set to indicate the presence of a " "slot, but a slot may still be unfilled.) ::" msgstr "" #: ../Doc/extending/newtypes.rst:1310 msgid "" "If you wish your object to be able to act like a number, a sequence, or a " "mapping object, then you place the address of a structure that implements " "the C type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, or :c:" "type:`PyMappingMethods`, respectively. It is up to you to fill in this " "structure with appropriate values. You can find examples of the use of each " "of these in the :file:`Objects` directory of the Python source " "distribution. ::" msgstr "" #: ../Doc/extending/newtypes.rst:1319 msgid "" "This function, if you choose to provide it, should return a hash number for " "an instance of your data type. Here is a moderately pointless example::" msgstr "" #: ../Doc/extending/newtypes.rst:1335 msgid "" "This function is called when an instance of your data type is \"called\", " "for example, if ``obj1`` is an instance of your data type and the Python " "script contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` " "handler is invoked." msgstr "" #: ../Doc/extending/newtypes.rst:1339 msgid "This function takes three arguments:" msgstr "" #: ../Doc/extending/newtypes.rst:1341 msgid "" "*arg1* is the instance of the data type which is the subject of the call. If " "the call is ``obj1('hello')``, then *arg1* is ``obj1``." msgstr "" #: ../Doc/extending/newtypes.rst:1344 msgid "" "*arg2* is a tuple containing the arguments to the call. You can use :c:func:" "`PyArg_ParseTuple` to extract the arguments." msgstr "" #: ../Doc/extending/newtypes.rst:1347 msgid "" "*arg3* is a dictionary of keyword arguments that were passed. If this is non-" "*NULL* and you support keyword arguments, use :c:func:" "`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do not want " "to support keyword arguments and this is non-*NULL*, raise a :exc:" "`TypeError` with a message saying that keyword arguments are not supported." msgstr "" #: ../Doc/extending/newtypes.rst:1353 msgid "" "Here is a desultory example of the implementation of the call function. ::" msgstr "" #: ../Doc/extending/newtypes.rst:1384 msgid "" "These functions provide support for the iterator protocol. Any object which " "wishes to support iteration over its contents (which may be generated during " "iteration) must implement the ``tp_iter`` handler. Objects which are " "returned by a ``tp_iter`` handler must implement both the ``tp_iter`` and " "``tp_iternext`` handlers. Both handlers take exactly one parameter, the " "instance for which they are being called, and return a new reference. In " "the case of an error, they should set an exception and return *NULL*." msgstr "" #: ../Doc/extending/newtypes.rst:1392 msgid "" "For an object which represents an iterable collection, the ``tp_iter`` " "handler must return an iterator object. The iterator object is responsible " "for maintaining the state of the iteration. For collections which can " "support multiple iterators which do not interfere with each other (as lists " "and tuples do), a new iterator should be created and returned. Objects " "which can only be iterated over once (usually due to side effects of " "iteration) should implement this handler by returning a new reference to " "themselves, and should also implement the ``tp_iternext`` handler. File " "objects are an example of such an iterator." msgstr "" #: ../Doc/extending/newtypes.rst:1402 msgid "" "Iterator objects should implement both handlers. The ``tp_iter`` handler " "should return a new reference to the iterator (this is the same as the " "``tp_iter`` handler for objects which can only be iterated over " "destructively). The ``tp_iternext`` handler should return a new reference " "to the next object in the iteration if there is one. If the iteration has " "reached the end, it may return *NULL* without setting an exception or it may " "set :exc:`StopIteration`; avoiding the exception can yield slightly better " "performance. If an actual error occurs, it should set an exception and " "return *NULL*." msgstr "" #: ../Doc/extending/newtypes.rst:1415 msgid "Weak Reference Support" msgstr "" #: ../Doc/extending/newtypes.rst:1417 msgid "" "One of the goals of Python's weak-reference implementation is to allow any " "type to participate in the weak reference mechanism without incurring the " "overhead on those objects which do not benefit by weak referencing (such as " "numbers)." msgstr "" #: ../Doc/extending/newtypes.rst:1421 msgid "" "For an object to be weakly referencable, the extension must include a :c:" "type:`PyObject\\*` field in the instance structure for the use of the weak " "reference mechanism; it must be initialized to *NULL* by the object's " "constructor. It must also set the :c:member:`~PyTypeObject." "tp_weaklistoffset` field of the corresponding type object to the offset of " "the field. For example, the instance type is defined with the following " "structure::" msgstr "" #: ../Doc/extending/newtypes.rst:1435 msgid "The statically-declared type object for instances is defined this way::" msgstr "" #: ../Doc/extending/newtypes.rst:1452 msgid "" "The type constructor is responsible for initializing the weak reference list " "to *NULL*::" msgstr "" #: ../Doc/extending/newtypes.rst:1464 msgid "" "The only further addition is that the destructor needs to call the weak " "reference manager to clear any weak references. This is only required if " "the weak reference list is non-*NULL*::" msgstr "" #: ../Doc/extending/newtypes.rst:1483 msgid "More Suggestions" msgstr "" #: ../Doc/extending/newtypes.rst:1485 msgid "" "Remember that you can omit most of these functions, in which case you " "provide ``0`` as a value. There are type definitions for each of the " "functions you must provide. They are in :file:`object.h` in the Python " "include directory that comes with the source distribution of Python." msgstr "" #: ../Doc/extending/newtypes.rst:1490 msgid "" "In order to learn how to implement any specific method for your new data " "type, do the following: Download and unpack the Python source distribution. " "Go to the :file:`Objects` directory, then search the C source files for " "``tp_`` plus the function you want (for example, ``tp_richcompare``). You " "will find examples of the function you want to implement." msgstr "" #: ../Doc/extending/newtypes.rst:1496 msgid "" "When you need to verify that an object is an instance of the type you are " "implementing, use the :c:func:`PyObject_TypeCheck` function. A sample of its " "use might be something like the following::" msgstr "" #: ../Doc/extending/newtypes.rst:1507 msgid "" "This is true when we know that the object is a basic type, like a string or " "a float." msgstr "" #: ../Doc/extending/newtypes.rst:1510 msgid "" "We relied on this in the :c:member:`~PyTypeObject.tp_dealloc` handler in " "this example, because our type doesn't support garbage collection. Even if a " "type supports garbage collection, there are calls that can be made to " "\"untrack\" the object from garbage collection, however, these calls are " "advanced and not covered here." msgstr "" #: ../Doc/extending/newtypes.rst:1515 msgid "" "We now know that the first and last members are strings, so perhaps we could " "be less careful about decrementing their reference counts, however, we " "accept instances of string subclasses. Even though deallocating normal " "strings won't call back into our objects, we can't guarantee that " "deallocating an instance of a string subclass won't call back into our " "objects." msgstr "" #: ../Doc/extending/newtypes.rst:1521 msgid "" "Even in the third version, we aren't guaranteed to avoid cycles. Instances " "of string subclasses are allowed and string subclasses could allow cycles " "even if normal strings don't." msgstr "" #: ../Doc/extending/windows.rst:8 msgid "Building C and C++ Extensions on Windows" msgstr "" #: ../Doc/extending/windows.rst:10 msgid "" "This chapter briefly explains how to create a Windows extension module for " "Python using Microsoft Visual C++, and follows with more detailed background " "information on how it works. The explanatory material is useful for both " "the Windows programmer learning to build Python extensions and the Unix " "programmer interested in producing software which can be successfully built " "on both Unix and Windows." msgstr "" #: ../Doc/extending/windows.rst:17 msgid "" "Module authors are encouraged to use the distutils approach for building " "extension modules, instead of the one described in this section. You will " "still need the C compiler that was used to build Python; typically Microsoft " "Visual C++." msgstr "" #: ../Doc/extending/windows.rst:24 msgid "" "This chapter mentions a number of filenames that include an encoded Python " "version number. These filenames are represented with the version number " "shown as ``XY``; in practice, ``'X'`` will be the major version number and " "``'Y'`` will be the minor version number of the Python release you're " "working with. For example, if you are using Python 2.2.1, ``XY`` will " "actually be ``22``." msgstr "" #: ../Doc/extending/windows.rst:34 msgid "A Cookbook Approach" msgstr "" #: ../Doc/extending/windows.rst:36 msgid "" "There are two approaches to building extension modules on Windows, just as " "there are on Unix: use the :mod:`distutils` package to control the build " "process, or do things manually. The distutils approach works well for most " "extensions; documentation on using :mod:`distutils` to build and package " "extension modules is available in :ref:`distutils-index`. If you find you " "really need to do things manually, it may be instructive to study the " "project file for the :source:`winsound ` standard " "library module." msgstr "" #: ../Doc/extending/windows.rst:48 msgid "Differences Between Unix and Windows" msgstr "" #: ../Doc/extending/windows.rst:53 msgid "" "Unix and Windows use completely different paradigms for run-time loading of " "code. Before you try to build a module that can be dynamically loaded, be " "aware of how your system works." msgstr "" #: ../Doc/extending/windows.rst:57 msgid "" "In Unix, a shared object (:file:`.so`) file contains code to be used by the " "program, and also the names of functions and data that it expects to find in " "the program. When the file is joined to the program, all references to " "those functions and data in the file's code are changed to point to the " "actual locations in the program where the functions and data are placed in " "memory. This is basically a link operation." msgstr "" #: ../Doc/extending/windows.rst:64 msgid "" "In Windows, a dynamic-link library (:file:`.dll`) file has no dangling " "references. Instead, an access to functions or data goes through a lookup " "table. So the DLL code does not have to be fixed up at runtime to refer to " "the program's memory; instead, the code already uses the DLL's lookup table, " "and the lookup table is modified at runtime to point to the functions and " "data." msgstr "" #: ../Doc/extending/windows.rst:70 msgid "" "In Unix, there is only one type of library file (:file:`.a`) which contains " "code from several object files (:file:`.o`). During the link step to create " "a shared object file (:file:`.so`), the linker may find that it doesn't know " "where an identifier is defined. The linker will look for it in the object " "files in the libraries; if it finds it, it will include all the code from " "that object file." msgstr "" #: ../Doc/extending/windows.rst:76 msgid "" "In Windows, there are two types of library, a static library and an import " "library (both called :file:`.lib`). A static library is like a Unix :file:`." "a` file; it contains code to be included as necessary. An import library is " "basically used only to reassure the linker that a certain identifier is " "legal, and will be present in the program when the DLL is loaded. So the " "linker uses the information from the import library to build the lookup " "table for using identifiers that are not included in the DLL. When an " "application or a DLL is linked, an import library may be generated, which " "will need to be used for all future DLLs that depend on the symbols in the " "application or DLL." msgstr "" #: ../Doc/extending/windows.rst:86 msgid "" "Suppose you are building two dynamic-load modules, B and C, which should " "share another block of code A. On Unix, you would *not* pass :file:`A.a` to " "the linker for :file:`B.so` and :file:`C.so`; that would cause it to be " "included twice, so that B and C would each have their own copy. In Windows, " "building :file:`A.dll` will also build :file:`A.lib`. You *do* pass :file:" "`A.lib` to the linker for B and C. :file:`A.lib` does not contain code; it " "just contains information which will be used at runtime to access A's code." msgstr "" #: ../Doc/extending/windows.rst:94 msgid "" "In Windows, using an import library is sort of like using ``import spam``; " "it gives you access to spam's names, but does not create a separate copy. " "On Unix, linking with a library is more like ``from spam import *``; it does " "create a separate copy." msgstr "" #: ../Doc/extending/windows.rst:103 msgid "Using DLLs in Practice" msgstr "" #: ../Doc/extending/windows.rst:108 msgid "" "Windows Python is built in Microsoft Visual C++; using other compilers may " "or may not work (though Borland seems to). The rest of this section is MSVC+" "+ specific." msgstr "" #: ../Doc/extending/windows.rst:112 msgid "" "When creating DLLs in Windows, you must pass :file:`pythonXY.lib` to the " "linker. To build two DLLs, spam and ni (which uses C functions found in " "spam), you could use these commands::" msgstr "" #: ../Doc/extending/windows.rst:119 msgid "" "The first command created three files: :file:`spam.obj`, :file:`spam.dll` " "and :file:`spam.lib`. :file:`Spam.dll` does not contain any Python " "functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find " "the Python code thanks to :file:`pythonXY.lib`." msgstr "" #: ../Doc/extending/windows.rst:124 msgid "" "The second command created :file:`ni.dll` (and :file:`.obj` and :file:`." "lib`), which knows how to find the necessary functions from spam, and also " "from the Python executable." msgstr "" #: ../Doc/extending/windows.rst:128 msgid "" "Not every identifier is exported to the lookup table. If you want any other " "modules (including Python) to be able to see your identifiers, you have to " "say ``_declspec(dllexport)``, as in ``void _declspec(dllexport) " "initspam(void)`` or ``PyObject _declspec(dllexport) *NiGetSpamData(void)``." msgstr "" #: ../Doc/extending/windows.rst:133 msgid "" "Developer Studio will throw in a lot of import libraries that you do not " "really need, adding about 100K to your executable. To get rid of them, use " "the Project Settings dialog, Link tab, to specify *ignore default " "libraries*. Add the correct :file:`msvcrtxx.lib` to the list of libraries." msgstr ""