forked from AFPy/python-docs-fr
3745 lines
160 KiB
Plaintext
3745 lines
160 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
|
# Copyright (C) 2001-2016, Python Software Foundation
|
|
# This file is distributed under the same license as the Python package.
|
|
# FIRST AUTHOR <EMAIL@ADDRESS>, 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 <EMAIL@ADDRESS>\n"
|
|
"Language-Team: LANGUAGE <LL@li.org>\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_<modulename>``, with ``<modulename>`` 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_<modulename>``, with ``<modulename>`` 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_<modulename>``, dont ``<modulename>`` 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_<modulename>``, 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 <compiling>` 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 <compiling>` 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 <reporting-"
|
|
"bugs>`) 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 <reporting-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:`<modules d'extension> 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 <https://cffi.readthedocs.org>`_ library rather than "
|
|
"writing custom C code. These modules let you write Python code to interface "
|
|
"with C code and are more portable between implementations of Python than "
|
|
"writing and compiling a C extension module."
|
|
msgstr ""
|
|
"L'interface d'extension C est spécifique à CPython, et les modules "
|
|
"d'extension ne fonctionne pas sur les autres implémentations de Python. Dans "
|
|
"de nombreux cas, il est possible d'éviter la rédaction des extensions en C "
|
|
"et ainsi préserver la portabilité vers d'autres implémentations. Par "
|
|
"exemple, si vous devez appeler une fonction de la bibliothèque C ou faire un "
|
|
"appel système, vous devriez envisager d'utiliser le module :mod:`ctypes` ou "
|
|
"d'utiliser la bibliothèque `cffi <https://cffi.readthedocs.org>`_ 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: ``<stdio.h>``, ``<string.h>``, "
|
|
"``<errno.h>``, and ``<stdlib.h>``. If the latter header file does not exist "
|
|
"on your system, it declares the functions :c:func:`malloc`, :c:func:`free` "
|
|
"and :c:func:`realloc` directly."
|
|
msgstr ""
|
|
"Tous les symboles exposés par :file:`Python.h` sont préfixés de ``Py`` ou "
|
|
"``PY``, sauf ceux qui sont définis dans les en-têtes standard. Pour le "
|
|
"confort, et comme ils sont largement utilisés par l'interpréteur Python, ``"
|
|
"\"Python.h\"`` inclu lui même quelques d'en-têtes standard : ``<stdio.h>``, "
|
|
"``<string.h>``, ``<errno.h>`` et ``<stdlib.h>``. Si ce dernier n'existe pas "
|
|
"sur votre système, il déclare les fonctions :c:func:`malloc`, :c:func:`free` "
|
|
"et :c:func:`realloc` directement."
|
|
|
|
#: ../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 <https://packaging.python."
|
|
"org/en/latest/extensions/>`_"
|
|
msgstr ""
|
|
"`Python Packaging User Guide: Binary Extensions <https://packaging.python."
|
|
"org/en/latest/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 <richcmpfuncs>`, 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 <PCbuild/winsound.vcxproj>` 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 ""
|