forked from AFPy/python-docs-fr
16001 lines
551 KiB
Plaintext
16001 lines
551 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/c-api/abstract.rst:7
|
|
msgid "Abstract Objects Layer"
|
|
msgstr "Couche d'Abstraction des Objets"
|
|
|
|
#: ../Doc/c-api/abstract.rst:9
|
|
msgid ""
|
|
"The functions in this chapter interact with Python objects regardless of "
|
|
"their type, or with wide classes of object types (e.g. all numerical types, "
|
|
"or all sequence types). When used on object types for which they do not "
|
|
"apply, they will raise a Python exception."
|
|
msgstr ""
|
|
"Dans ce chapitre, les fonctions s'appliquent à des objets Python sans tenir "
|
|
"compte de leur type, ou des classes d'objets au sens large (par exemple, "
|
|
"tous les types numériques, ou tous les types de séquence). Quand ils sont "
|
|
"utilisés sur des types d'objets qui ne correspondent pas, ils lèveront une "
|
|
"exception Python."
|
|
|
|
#: ../Doc/c-api/abstract.rst:14
|
|
msgid ""
|
|
"It is not possible to use these functions on objects that are not properly "
|
|
"initialized, such as a list object that has been created by :c:func:"
|
|
"`PyList_New`, but whose items have not been set to some non-\\ ``NULL`` "
|
|
"value yet."
|
|
msgstr ""
|
|
"Il n'est pas possible d'utiliser ces fonctions sur des objets qui n'ont pas "
|
|
"été correctement initialisés, comme un objet liste qui a été créé avec :c:"
|
|
"func:`PyList_New` mais dont les éléments n'ont pas encore été mis à une "
|
|
"valeur non-\\ ``NULL``."
|
|
|
|
#: ../Doc/c-api/allocation.rst:6
|
|
msgid "Allocating Objects on the Heap"
|
|
msgstr "Allouer des objets dans le tas"
|
|
|
|
#: ../Doc/c-api/allocation.rst:17
|
|
msgid ""
|
|
"Initialize a newly-allocated object *op* with its type and initial "
|
|
"reference. Returns the initialized object. If *type* indicates that the "
|
|
"object participates in the cyclic garbage detector, it is added to the "
|
|
"detector's set of observed objects. Other fields of the object are not "
|
|
"affected."
|
|
msgstr ""
|
|
"Permet d'initialiser un objet *op* nouvellement alloué ainsi que son type et "
|
|
"sa référence initiale. Retourne l'objet initialisé. La présence de *type* "
|
|
"indique que l'objet doit être traité par le détecteur d'ordures cycliques, "
|
|
"il est de ce fait ajouté à l'ensemble du détecteur d'objets observés. Les "
|
|
"autres champs de l'objet ne sont pas affectés."
|
|
|
|
#: ../Doc/c-api/allocation.rst:26
|
|
msgid ""
|
|
"This does everything :c:func:`PyObject_Init` does, and also initializes the "
|
|
"length information for a variable-size object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/allocation.rst:32
|
|
msgid ""
|
|
"Allocate a new Python object using the C structure type *TYPE* and the "
|
|
"Python type object *type*. Fields not defined by the Python object header "
|
|
"are not initialized; the object's reference count will be one. The size of "
|
|
"the memory allocation is determined from the :c:member:`~PyTypeObject."
|
|
"tp_basicsize` field of the type object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/allocation.rst:41
|
|
msgid ""
|
|
"Allocate a new Python object using the C structure type *TYPE* and the "
|
|
"Python type object *type*. Fields not defined by the Python object header "
|
|
"are not initialized. The allocated memory allows for the *TYPE* structure "
|
|
"plus *size* fields of the size given by the :c:member:`~PyTypeObject."
|
|
"tp_itemsize` field of *type*. This is useful for implementing objects like "
|
|
"tuples, which are able to determine their size at construction time. "
|
|
"Embedding the array of fields into the same allocation decreases the number "
|
|
"of allocations, improving the memory management efficiency."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/allocation.rst:53
|
|
msgid ""
|
|
"Releases memory allocated to an object using :c:func:`PyObject_New` or :c:"
|
|
"func:`PyObject_NewVar`. This is normally called from the :c:member:"
|
|
"`~PyTypeObject.tp_dealloc` handler specified in the object's type. The "
|
|
"fields of the object should not be accessed after this call as the memory is "
|
|
"no longer a valid Python object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/allocation.rst:62
|
|
msgid ""
|
|
"Object which is visible in Python as ``None``. This should only be accessed "
|
|
"using the :c:macro:`Py_None` macro, which evaluates to a pointer to this "
|
|
"object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/allocation.rst:69
|
|
msgid ":c:func:`PyModule_Create`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/allocation.rst:70
|
|
msgid "To allocate and create extension modules."
|
|
msgstr "Allouer et créer des modules d'extension."
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:7
|
|
msgid "API and ABI Versioning"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:9
|
|
msgid ""
|
|
"``PY_VERSION_HEX`` is the Python version number encoded in a single integer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:11
|
|
msgid ""
|
|
"For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the "
|
|
"underlying version information can be found by treating it as a 32 bit "
|
|
"number in the following manner:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:16
|
|
msgid "Bytes"
|
|
msgstr "Bytes"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:16
|
|
msgid "Bits (big endian order)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:16 ../Doc/c-api/memory.rst:277
|
|
#: ../Doc/c-api/memory.rst:414 ../Doc/c-api/structures.rst:129
|
|
#: ../Doc/c-api/structures.rst:241 ../Doc/c-api/tuple.rst:145
|
|
#: ../Doc/c-api/tuple.rst:168
|
|
msgid "Meaning"
|
|
msgstr "Signification"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:18
|
|
msgid "``1``"
|
|
msgstr "``1``"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:18
|
|
msgid "``1-8``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:18
|
|
msgid "``PY_MAJOR_VERSION`` (the ``3`` in ``3.4.1a2``)"
|
|
msgstr "``PY_MAJOR_VERSION`` (le ``3`` dans ``3.4.1a2``)"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:21
|
|
msgid "``2``"
|
|
msgstr "``2``"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:21
|
|
msgid "``9-16``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:21
|
|
msgid "``PY_MINOR_VERSION`` (the ``4`` in ``3.4.1a2``)"
|
|
msgstr "``PY_MINOR_VERSION`` (le ``4`` dans ``3.4.1a2``)"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:24
|
|
msgid "``3``"
|
|
msgstr "``3``"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:24
|
|
msgid "``17-24``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:24
|
|
msgid "``PY_MICRO_VERSION`` (the ``1`` in ``3.4.1a2``)"
|
|
msgstr "``PY_MICRO_VERSION`` (le ``1`` dans ``3.4.1a2``)"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:27
|
|
msgid "``4``"
|
|
msgstr "``4``"
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:27
|
|
msgid "``25-28``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:27
|
|
msgid ""
|
|
"``PY_RELEASE_LEVEL`` (``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for "
|
|
"release candidate and ``0xF`` for final), in this case it is alpha."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:32
|
|
msgid "``29-32``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:32
|
|
msgid ""
|
|
"``PY_RELEASE_SERIAL`` (the ``2`` in ``3.4.1a2``, zero for final releases)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:36
|
|
msgid "Thus ``3.4.1a2`` is hexversion ``0x030401a2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/apiabiversion.rst:38
|
|
msgid "All the given macros are defined in :source:`Include/patchlevel.h`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:6
|
|
msgid "Parsing arguments and building values"
|
|
msgstr "Analyse des arguments et construction des valeurs"
|
|
|
|
#: ../Doc/c-api/arg.rst:8
|
|
msgid ""
|
|
"These functions are useful when creating your own extensions functions and "
|
|
"methods. Additional information and examples are available in :ref:"
|
|
"`extending-index`."
|
|
msgstr ""
|
|
"Ces fonctions sont utiles pour créer vos propres fonctions et méthodes "
|
|
"d'extensions. Des informations supplémentaires et des exemples sont "
|
|
"disponibles ici: :ref:`extending-index`."
|
|
|
|
#: ../Doc/c-api/arg.rst:12
|
|
msgid ""
|
|
"The first three of these functions described, :c:func:`PyArg_ParseTuple`, :c:"
|
|
"func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use "
|
|
"*format strings* which are used to tell the function about the expected "
|
|
"arguments. The format strings use the same syntax for each of these "
|
|
"functions."
|
|
msgstr ""
|
|
"Dans Les trois premières de ces fonctions décrites, :c:func:"
|
|
"`PyArg_ParseTuple`, :c:func:`PyArg_ParseTupleAndKeywords`, et :c:func:"
|
|
"`PyArg_Parse`, toutes utilisent *des chaînes de format* qui sont utilisées "
|
|
"pour indiquer à la fonction les arguments attendus. Les chaînes de format "
|
|
"utilise la même syntaxe pour chacune de ces fonctions."
|
|
|
|
#: ../Doc/c-api/arg.rst:19
|
|
msgid "Parsing arguments"
|
|
msgstr "Analyse des arguments"
|
|
|
|
#: ../Doc/c-api/arg.rst:21
|
|
msgid ""
|
|
"A format string consists of zero or more \"format units.\" A format unit "
|
|
"describes one Python object; it is usually a single character or a "
|
|
"parenthesized sequence of format units. With a few exceptions, a format "
|
|
"unit that is not a parenthesized sequence normally corresponds to a single "
|
|
"address argument to these functions. In the following description, the "
|
|
"quoted form is the format unit; the entry in (round) parentheses is the "
|
|
"Python object type that matches the format unit; and the entry in [square] "
|
|
"brackets is the type of the C variable(s) whose address should be passed."
|
|
msgstr ""
|
|
"Une chaîne de format se compose de zéro ou plusieurs \"unités de format\". "
|
|
"Une unité de format décrit un objet Python, elle est généralement composée "
|
|
"d'un seul caractère ou d'une séquence d'unités de format entre parenthèses. "
|
|
"À quelques exceptions près, une unité de format qui n'est pas une séquence "
|
|
"entre parenthèses correspond normalement à un argument d'une seule adresse "
|
|
"pour ces fonctions. Dans la description qui suit, la forme entre guillemets "
|
|
"est l'unité de format, l'entrée entre parenthèses est le type d'objet Python "
|
|
"qui correspond à l'unité de format, et l'entrée entre crochets est le type "
|
|
"de la variable C (ou des variables) dont l'adresse doit être donnée."
|
|
|
|
#: ../Doc/c-api/arg.rst:31
|
|
msgid "Strings and buffers"
|
|
msgstr "Chaînes et tampons"
|
|
|
|
#: ../Doc/c-api/arg.rst:33
|
|
msgid ""
|
|
"These formats allow accessing an object as a contiguous chunk of memory. You "
|
|
"don't have to provide raw storage for the returned unicode or bytes area."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:37
|
|
msgid ""
|
|
"In general, when a format sets a pointer to a buffer, the buffer is managed "
|
|
"by the corresponding Python object, and the buffer shares the lifetime of "
|
|
"this object. You won't have to release any memory yourself. The only "
|
|
"exceptions are ``es``, ``es#``, ``et`` and ``et#``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:42
|
|
msgid ""
|
|
"However, when a :c:type:`Py_buffer` structure gets filled, the underlying "
|
|
"buffer is locked so that the caller can subsequently use the buffer even "
|
|
"inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable "
|
|
"data being resized or destroyed. As a result, **you have to call** :c:func:"
|
|
"`PyBuffer_Release` after you have finished processing the data (or in any "
|
|
"early abort case)."
|
|
msgstr ""
|
|
"Néanmoins, quand une structure :c:type:`Py_buffer` est en cours de "
|
|
"remplissage, le buffer sous-jacent est verrouillé pour permettre à "
|
|
"l'appelant d'utiliser le buffer par la suite, même à l'intérieur d'un bloc :"
|
|
"c:type:`Py_BEGIN_ALLOW_THREADS`. Ceci sans le risque pour les données "
|
|
"mutables de voir leur taille changée ou d'être supprimées. En conséquence, "
|
|
"**il vous appartient d'appeler** :c:func:`PyBuffer_Release` après que vous "
|
|
"ayez terminé de traiter les données (ou après une interruption prémataturée "
|
|
"du traitement de ces données)."
|
|
|
|
#: ../Doc/c-api/arg.rst:49
|
|
msgid "Unless otherwise stated, buffers are not NUL-terminated."
|
|
msgstr "Sauf indication contraire, les tampons ne se terminent pas par NUL."
|
|
|
|
#: ../Doc/c-api/arg.rst:51
|
|
msgid ""
|
|
"Some formats require a read-only :term:`bytes-like object`, and set a "
|
|
"pointer instead of a buffer structure. They work by checking that the "
|
|
"object's :c:member:`PyBufferProcs.bf_releasebuffer` field is *NULL*, which "
|
|
"disallows mutable objects such as :class:`bytearray`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:58
|
|
msgid ""
|
|
"For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of the "
|
|
"length argument (int or :c:type:`Py_ssize_t`) is controlled by defining the "
|
|
"macro :c:macro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h`. If the "
|
|
"macro was defined, length is a :c:type:`Py_ssize_t` rather than an :c:type:"
|
|
"`int`. This behavior will change in a future Python version to only support :"
|
|
"c:type:`Py_ssize_t` and drop :c:type:`int` support. It is best to always "
|
|
"define :c:macro:`PY_SSIZE_T_CLEAN`."
|
|
msgstr ""
|
|
"Pour toutes les variantes de formats ``#`` (``s#``, ``y#``, etc), le type de "
|
|
"l'argument *length* (int ou :c:type:`Py_ssize_t`) est contrôlé en "
|
|
"définissant la macro :c:macro:`PY_SSIZE_T_CLEAN` avant d'inclure le fichier :"
|
|
"file:`Python.h`. Si la macro est définie, la longueur est de type :c:type:"
|
|
"`Py_ssize_t` au lieu d'être de type :c:type:`int`. Ce comportement changera "
|
|
"dans une future version de Python, qui supportera seulement :c:type:"
|
|
"`Py_ssize_t` a la place de :c:type:`int`. Il est préférable de toujours "
|
|
"définir :c:macro:`PY_SSIZE_T_CLEAN`."
|
|
|
|
#: ../Doc/c-api/arg.rst:85
|
|
msgid "``s`` (:class:`str`) [const char \\*]"
|
|
msgstr "``s`` (:class:`str`) [const char \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:68
|
|
msgid ""
|
|
"Convert a Unicode object to a C pointer to a character string. A pointer to "
|
|
"an existing string is stored in the character pointer variable whose address "
|
|
"you pass. The C string is NUL-terminated. The Python string must not "
|
|
"contain embedded null code points; if it does, a :exc:`ValueError` exception "
|
|
"is raised. Unicode objects are converted to C strings using ``'utf-8'`` "
|
|
"encoding. If this conversion fails, a :exc:`UnicodeError` is raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:77
|
|
msgid ""
|
|
"This format does not accept :term:`bytes-like objects <bytes-like object>`. "
|
|
"If you want to accept filesystem paths and convert them to C character "
|
|
"strings, it is preferable to use the ``O&`` format with :c:func:"
|
|
"`PyUnicode_FSConverter` as *converter*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:83 ../Doc/c-api/arg.rst:150
|
|
msgid ""
|
|
"Previously, :exc:`TypeError` was raised when embedded null code points were "
|
|
"encountered in the Python string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:91
|
|
msgid "``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:88
|
|
msgid ""
|
|
"This format accepts Unicode objects as well as bytes-like objects. It fills "
|
|
"a :c:type:`Py_buffer` structure provided by the caller. In this case the "
|
|
"resulting C string may contain embedded NUL bytes. Unicode objects are "
|
|
"converted to C strings using ``'utf-8'`` encoding."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:98
|
|
msgid ""
|
|
"``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \\*, "
|
|
"int or :c:type:`Py_ssize_t`]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:94
|
|
msgid ""
|
|
"Like ``s*``, except that it doesn't accept mutable objects. The result is "
|
|
"stored into two C variables, the first one a pointer to a C string, the "
|
|
"second one its length. The string may contain embedded null bytes. Unicode "
|
|
"objects are converted to C strings using ``'utf-8'`` encoding."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:102
|
|
msgid "``z`` (:class:`str` or ``None``) [const char \\*]"
|
|
msgstr "``z`` (:class:`str` ou ``None``) [const char \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:101
|
|
msgid ""
|
|
"Like ``s``, but the Python object may also be ``None``, in which case the C "
|
|
"pointer is set to *NULL*."
|
|
msgstr ""
|
|
"Comme ``s``, mais l'objet Python peut aussi être ``None``, auquel cas le "
|
|
"pointeur C devient *NULL*."
|
|
|
|
#: ../Doc/c-api/arg.rst:106
|
|
msgid ""
|
|
"``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:105
|
|
msgid ""
|
|
"Like ``s*``, but the Python object may also be ``None``, in which case the "
|
|
"``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:110
|
|
msgid ""
|
|
"``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) "
|
|
"[const char \\*, int]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:109
|
|
msgid ""
|
|
"Like ``s#``, but the Python object may also be ``None``, in which case the C "
|
|
"pointer is set to *NULL*."
|
|
msgstr ""
|
|
"Comme ``s#``, mais l'objet Python peut également être ``None``, dans ce cas "
|
|
"le pointeur C est définie à *NULL*."
|
|
|
|
#: ../Doc/c-api/arg.rst:120
|
|
msgid "``y`` (read-only :term:`bytes-like object`) [const char \\*]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:113
|
|
msgid ""
|
|
"This format converts a bytes-like object to a C pointer to a character "
|
|
"string; it does not accept Unicode objects. The bytes buffer must not "
|
|
"contain embedded null bytes; if it does, a :exc:`ValueError` exception is "
|
|
"raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:118
|
|
msgid ""
|
|
"Previously, :exc:`TypeError` was raised when embedded null bytes were "
|
|
"encountered in the bytes buffer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:125
|
|
msgid "``y*`` (:term:`bytes-like object`) [Py_buffer]"
|
|
msgstr "``y*`` (:term:`bytes-like object`) [Py_buffer]"
|
|
|
|
#: ../Doc/c-api/arg.rst:123
|
|
msgid ""
|
|
"This variant on ``s*`` doesn't accept Unicode objects, only bytes-like "
|
|
"objects. **This is the recommended way to accept binary data.**"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:129
|
|
msgid "``y#`` (read-only :term:`bytes-like object`) [const char \\*, int]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:128
|
|
msgid ""
|
|
"This variant on ``s#`` doesn't accept Unicode objects, only bytes-like "
|
|
"objects."
|
|
msgstr ""
|
|
"Cette variante de ``s#`` n'accepte pas les objets Unicode, uniquement des "
|
|
"objets assimilés à des octets."
|
|
|
|
#: ../Doc/c-api/arg.rst:134
|
|
msgid "``S`` (:class:`bytes`) [PyBytesObject \\*]"
|
|
msgstr "``S`` (:class:`bytes`) [PyBytesObject \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:132
|
|
msgid ""
|
|
"Requires that the Python object is a :class:`bytes` object, without "
|
|
"attempting any conversion. Raises :exc:`TypeError` if the object is not a "
|
|
"bytes object. The C variable may also be declared as :c:type:`PyObject\\*`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:139
|
|
msgid "``Y`` (:class:`bytearray`) [PyByteArrayObject \\*]"
|
|
msgstr "``Y`` (:class:`bytearray`) [PyByteArrayObject \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:137
|
|
msgid ""
|
|
"Requires that the Python object is a :class:`bytearray` object, without "
|
|
"attempting any conversion. Raises :exc:`TypeError` if the object is not a :"
|
|
"class:`bytearray` object. The C variable may also be declared as :c:type:"
|
|
"`PyObject\\*`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:152 ../Doc/c-api/arg.rst:557
|
|
msgid "``u`` (:class:`str`) [Py_UNICODE \\*]"
|
|
msgstr "``u`` (:class:`str`) [Py_UNICODE \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:142
|
|
msgid ""
|
|
"Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of "
|
|
"Unicode characters. You must pass the address of a :c:type:`Py_UNICODE` "
|
|
"pointer variable, which will be filled with the pointer to an existing "
|
|
"Unicode buffer. Please note that the width of a :c:type:`Py_UNICODE` "
|
|
"character depends on compilation options (it is either 16 or 32 bits). The "
|
|
"Python string must not contain embedded null code points; if it does, a :exc:"
|
|
"`ValueError` exception is raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:157 ../Doc/c-api/arg.rst:562
|
|
msgid "``u#`` (:class:`str`) [Py_UNICODE \\*, int]"
|
|
msgstr "``u#`` (:class:`str`) [Py_UNICODE \\*, int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:155
|
|
msgid ""
|
|
"This variant on ``u`` stores into two C variables, the first one a pointer "
|
|
"to a Unicode data buffer, the second one its length. This variant allows "
|
|
"null code points."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:161
|
|
msgid "``Z`` (:class:`str` or ``None``) [Py_UNICODE \\*]"
|
|
msgstr "``Z`` (:class:`str` ou ``None``) [Py_UNICODE \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:160
|
|
msgid ""
|
|
"Like ``u``, but the Python object may also be ``None``, in which case the :c:"
|
|
"type:`Py_UNICODE` pointer is set to *NULL*."
|
|
msgstr ""
|
|
"Comme ``u``, mais l'objet Python peut aussi être ``None``, auquel cas le "
|
|
"pointeur :c:type:`Py_UNICODE` vaut *NULL*."
|
|
|
|
#: ../Doc/c-api/arg.rst:165
|
|
msgid "``Z#`` (:class:`str` or ``None``) [Py_UNICODE \\*, int]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:164
|
|
msgid ""
|
|
"Like ``u#``, but the Python object may also be ``None``, in which case the :"
|
|
"c:type:`Py_UNICODE` pointer is set to *NULL*."
|
|
msgstr ""
|
|
"Comme ``u#``, mais l'objet Python peut également être ``None``, auquel cas "
|
|
"le pointeur :c:type:`Py_UNICODE` vaut *NULL*."
|
|
|
|
#: ../Doc/c-api/arg.rst:170
|
|
msgid "``U`` (:class:`str`) [PyObject \\*]"
|
|
msgstr "``U`` (:class:`str`) [PyObject \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:168
|
|
msgid ""
|
|
"Requires that the Python object is a Unicode object, without attempting any "
|
|
"conversion. Raises :exc:`TypeError` if the object is not a Unicode object. "
|
|
"The C variable may also be declared as :c:type:`PyObject\\*`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:176
|
|
msgid "``w*`` (read-write :term:`bytes-like object`) [Py_buffer]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:173
|
|
msgid ""
|
|
"This format accepts any object which implements the read-write buffer "
|
|
"interface. It fills a :c:type:`Py_buffer` structure provided by the caller. "
|
|
"The buffer may contain embedded null bytes. The caller have to call :c:func:"
|
|
"`PyBuffer_Release` when it is done with the buffer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:193
|
|
msgid "``es`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:179
|
|
msgid ""
|
|
"This variant on ``s`` is used for encoding Unicode into a character buffer. "
|
|
"It only works for encoded data without embedded NUL bytes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:182
|
|
msgid ""
|
|
"This format requires two arguments. The first is only used as input, and "
|
|
"must be a :c:type:`const char\\*` which points to the name of an encoding as "
|
|
"a NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is "
|
|
"used. An exception is raised if the named encoding is not known to Python. "
|
|
"The second argument must be a :c:type:`char\\*\\*`; the value of the pointer "
|
|
"it references will be set to a buffer with the contents of the argument "
|
|
"text. The text will be encoded in the encoding specified by the first "
|
|
"argument."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:190
|
|
msgid ""
|
|
":c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy "
|
|
"the encoded data into this buffer and adjust *\\*buffer* to reference the "
|
|
"newly allocated storage. The caller is responsible for calling :c:func:"
|
|
"`PyMem_Free` to free the allocated buffer after use."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:198
|
|
msgid ""
|
|
"``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char "
|
|
"\\*encoding, char \\*\\*buffer]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:196
|
|
msgid ""
|
|
"Same as ``es`` except that byte string objects are passed through without "
|
|
"recoding them. Instead, the implementation assumes that the byte string "
|
|
"object uses the encoding passed in as parameter."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:229
|
|
msgid ""
|
|
"``es#`` (:class:`str`) [const char \\*encoding, char \\*\\*buffer, int "
|
|
"\\*buffer_length]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:201
|
|
msgid ""
|
|
"This variant on ``s#`` is used for encoding Unicode into a character buffer. "
|
|
"Unlike the ``es`` format, this variant allows input data which contains NUL "
|
|
"characters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:205
|
|
msgid ""
|
|
"It requires three arguments. The first is only used as input, and must be "
|
|
"a :c:type:`const char\\*` which points to the name of an encoding as a NUL-"
|
|
"terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used. An "
|
|
"exception is raised if the named encoding is not known to Python. The "
|
|
"second argument must be a :c:type:`char\\*\\*`; the value of the pointer it "
|
|
"references will be set to a buffer with the contents of the argument text. "
|
|
"The text will be encoded in the encoding specified by the first argument. "
|
|
"The third argument must be a pointer to an integer; the referenced integer "
|
|
"will be set to the number of bytes in the output buffer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:215
|
|
msgid "There are two modes of operation:"
|
|
msgstr "Il existe deux modes de fonctionnement :"
|
|
|
|
#: ../Doc/c-api/arg.rst:217
|
|
msgid ""
|
|
"If *\\*buffer* points a *NULL* pointer, the function will allocate a buffer "
|
|
"of the needed size, copy the encoded data into this buffer and set *"
|
|
"\\*buffer* to reference the newly allocated storage. The caller is "
|
|
"responsible for calling :c:func:`PyMem_Free` to free the allocated buffer "
|
|
"after usage."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:222
|
|
msgid ""
|
|
"If *\\*buffer* points to a non-*NULL* pointer (an already allocated "
|
|
"buffer), :c:func:`PyArg_ParseTuple` will use this location as the buffer and "
|
|
"interpret the initial value of *\\*buffer_length* as the buffer size. It "
|
|
"will then copy the encoded data into the buffer and NUL-terminate it. If "
|
|
"the buffer is not large enough, a :exc:`ValueError` will be set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:228
|
|
msgid ""
|
|
"In both cases, *\\*buffer_length* is set to the length of the encoded data "
|
|
"without the trailing NUL byte."
|
|
msgstr ""
|
|
"Dans les deux cas, *\\*buffer_length* est la longueur des données encodées, "
|
|
"sans l'octet NUL de fin."
|
|
|
|
#: ../Doc/c-api/arg.rst:234
|
|
msgid ""
|
|
"``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char "
|
|
"\\*encoding, char \\*\\*buffer, int \\*buffer_length]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:232
|
|
msgid ""
|
|
"Same as ``es#`` except that byte string objects are passed through without "
|
|
"recoding them. Instead, the implementation assumes that the byte string "
|
|
"object uses the encoding passed in as parameter."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:237
|
|
msgid "Numbers"
|
|
msgstr "Les nombres"
|
|
|
|
#: ../Doc/c-api/arg.rst:241
|
|
msgid "``b`` (:class:`int`) [unsigned char]"
|
|
msgstr "``b`` (:class:`int`) [unsigned char]"
|
|
|
|
#: ../Doc/c-api/arg.rst:240
|
|
msgid ""
|
|
"Convert a nonnegative Python integer to an unsigned tiny int, stored in a C :"
|
|
"c:type:`unsigned char`."
|
|
msgstr ""
|
|
"Convertit un entier Python positif ou nul en un unsigned tiny int, stocké "
|
|
"dans un :c:type:`unsigned char` C."
|
|
|
|
#: ../Doc/c-api/arg.rst:245 ../Doc/c-api/arg.rst:583
|
|
msgid "``B`` (:class:`int`) [unsigned char]"
|
|
msgstr "``B`` (:class:`int`) [unsigned char]"
|
|
|
|
#: ../Doc/c-api/arg.rst:244
|
|
msgid ""
|
|
"Convert a Python integer to a tiny int without overflow checking, stored in "
|
|
"a C :c:type:`unsigned char`."
|
|
msgstr ""
|
|
"Convertit un entier Python en un tiny int sans vérifier le débordement, "
|
|
"stocké dans un :c:type:`unsigned char` C."
|
|
|
|
#: ../Doc/c-api/arg.rst:248 ../Doc/c-api/arg.rst:577
|
|
msgid "``h`` (:class:`int`) [short int]"
|
|
msgstr "``h`` (:class:`int`) [short int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:248
|
|
msgid "Convert a Python integer to a C :c:type:`short int`."
|
|
msgstr "Convertit un entier Python en un :c:type:`short int` C."
|
|
|
|
#: ../Doc/c-api/arg.rst:252 ../Doc/c-api/arg.rst:586
|
|
msgid "``H`` (:class:`int`) [unsigned short int]"
|
|
msgstr "``H`` (:class:`int`) [unsigned short int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:251
|
|
msgid ""
|
|
"Convert a Python integer to a C :c:type:`unsigned short int`, without "
|
|
"overflow checking."
|
|
msgstr ""
|
|
"Convertit un entier Python en un :c:type:`unsigned short int` C, sans "
|
|
"contrôle de débordement."
|
|
|
|
#: ../Doc/c-api/arg.rst:255 ../Doc/c-api/arg.rst:571
|
|
msgid "``i`` (:class:`int`) [int]"
|
|
msgstr "``i`` (:class:`int`) [int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:255
|
|
msgid "Convert a Python integer to a plain C :c:type:`int`."
|
|
msgstr "Convertit un entier Python en un :c:type:`int` C."
|
|
|
|
#: ../Doc/c-api/arg.rst:259 ../Doc/c-api/arg.rst:589
|
|
msgid "``I`` (:class:`int`) [unsigned int]"
|
|
msgstr "``I`` (:class:`int`) [unsigned int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:258
|
|
msgid ""
|
|
"Convert a Python integer to a C :c:type:`unsigned int`, without overflow "
|
|
"checking."
|
|
msgstr ""
|
|
"Convertit un entier Python en un :c:type:`unsigned int` C, sans contrôle de "
|
|
"le débordement."
|
|
|
|
#: ../Doc/c-api/arg.rst:262 ../Doc/c-api/arg.rst:580
|
|
msgid "``l`` (:class:`int`) [long int]"
|
|
msgstr "``l`` (:class:`int`) [long int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:262
|
|
msgid "Convert a Python integer to a C :c:type:`long int`."
|
|
msgstr "Convertit un entier Python en un :c:type:`long int`."
|
|
|
|
#: ../Doc/c-api/arg.rst:266 ../Doc/c-api/arg.rst:592
|
|
msgid "``k`` (:class:`int`) [unsigned long]"
|
|
msgstr "``k`` (:class:`int`) [unsigned long]"
|
|
|
|
#: ../Doc/c-api/arg.rst:265
|
|
msgid ""
|
|
"Convert a Python integer to a C :c:type:`unsigned long` without overflow "
|
|
"checking."
|
|
msgstr ""
|
|
"Convertit un entier Python en un :c:type:`unsigned long` C sans en vérifier "
|
|
"le débordement."
|
|
|
|
#: ../Doc/c-api/arg.rst:269 ../Doc/c-api/arg.rst:595
|
|
msgid "``L`` (:class:`int`) [long long]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:269
|
|
msgid "Convert a Python integer to a C :c:type:`long long`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:273 ../Doc/c-api/arg.rst:598
|
|
msgid "``K`` (:class:`int`) [unsigned long long]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:272
|
|
msgid ""
|
|
"Convert a Python integer to a C :c:type:`unsigned long long` without "
|
|
"overflow checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:276 ../Doc/c-api/arg.rst:601
|
|
msgid "``n`` (:class:`int`) [Py_ssize_t]"
|
|
msgstr "``n`` (:class:`int`) [Py_ssize_t]"
|
|
|
|
#: ../Doc/c-api/arg.rst:276
|
|
msgid "Convert a Python integer to a C :c:type:`Py_ssize_t`."
|
|
msgstr "Convertit un entier Python en un :c:type:`short int` C."
|
|
|
|
#: ../Doc/c-api/arg.rst:283
|
|
msgid "``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:279
|
|
msgid ""
|
|
"Convert a Python byte, represented as a :class:`bytes` or :class:`bytearray` "
|
|
"object of length 1, to a C :c:type:`char`."
|
|
msgstr ""
|
|
"Convertit un octet Python, représenté comme un objet :class:`bytes` ou :"
|
|
"class:`bytearray` de longueur 1, en un :c:type:`char` C."
|
|
|
|
#: ../Doc/c-api/arg.rst:282
|
|
msgid "Allow :class:`bytearray` objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:287 ../Doc/c-api/arg.rst:609
|
|
msgid "``C`` (:class:`str` of length 1) [int]"
|
|
msgstr "``C`` (:class:`str` of length 1) [int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:286
|
|
msgid ""
|
|
"Convert a Python character, represented as a :class:`str` object of length "
|
|
"1, to a C :c:type:`int`."
|
|
msgstr ""
|
|
"Convertit un caractère Python, représenté comme un objet :class:`str` de "
|
|
"longueur 1, en un :c:type:`int` C."
|
|
|
|
#: ../Doc/c-api/arg.rst:290 ../Doc/c-api/arg.rst:615
|
|
msgid "``f`` (:class:`float`) [float]"
|
|
msgstr "``f`` (:class:`float`) [float]"
|
|
|
|
#: ../Doc/c-api/arg.rst:290
|
|
msgid "Convert a Python floating point number to a C :c:type:`float`."
|
|
msgstr "Convertit un nombre flottant Python vers un :c:type:`float`."
|
|
|
|
#: ../Doc/c-api/arg.rst:293 ../Doc/c-api/arg.rst:612
|
|
msgid "``d`` (:class:`float`) [double]"
|
|
msgstr "``d`` (:class:`float`) [double]"
|
|
|
|
#: ../Doc/c-api/arg.rst:293
|
|
msgid "Convert a Python floating point number to a C :c:type:`double`."
|
|
msgstr "Convertit un nombre flottant Python vers un :c:type:`double` C."
|
|
|
|
#: ../Doc/c-api/arg.rst:296
|
|
msgid "``D`` (:class:`complex`) [Py_complex]"
|
|
msgstr "``D`` (:class:`complex`) [Py_complex]"
|
|
|
|
#: ../Doc/c-api/arg.rst:296
|
|
msgid "Convert a Python complex number to a C :c:type:`Py_complex` structure."
|
|
msgstr ""
|
|
"Convertit un nombre complexe Python vers une structure :c:type:`Py_complex` "
|
|
"C."
|
|
|
|
#: ../Doc/c-api/arg.rst:299
|
|
msgid "Other objects"
|
|
msgstr "Autres Objets"
|
|
|
|
#: ../Doc/c-api/arg.rst:304 ../Doc/c-api/arg.rst:626
|
|
msgid "``O`` (object) [PyObject \\*]"
|
|
msgstr "``O`` (object) [PyObject \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:302
|
|
msgid ""
|
|
"Store a Python object (without any conversion) in a C object pointer. The C "
|
|
"program thus receives the actual object that was passed. The object's "
|
|
"reference count is not increased. The pointer stored is not *NULL*."
|
|
msgstr ""
|
|
"Stocke un objet Python (sans aucune conversion) en un pointeur sur un objet "
|
|
"C. Ainsi, Le programme C reçoit l'objet réel qui a été passé. Le compteur de "
|
|
"référence sur l'objet n'est pas incrémenté. Le pointeur stocké n'est pas "
|
|
"*NULL*."
|
|
|
|
#: ../Doc/c-api/arg.rst:311
|
|
msgid "``O!`` (object) [*typeobject*, PyObject \\*]"
|
|
msgstr "``O!`` (object) [*typeobject*, PyObject \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:307
|
|
msgid ""
|
|
"Store a Python object in a C object pointer. This is similar to ``O``, but "
|
|
"takes two C arguments: the first is the address of a Python type object, the "
|
|
"second is the address of the C variable (of type :c:type:`PyObject\\*`) into "
|
|
"which the object pointer is stored. If the Python object does not have the "
|
|
"required type, :exc:`TypeError` is raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:336 ../Doc/c-api/arg.rst:640
|
|
msgid "``O&`` (object) [*converter*, *anything*]"
|
|
msgstr "``O&`` (object) [*converter*, *anything*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:316
|
|
msgid ""
|
|
"Convert a Python object to a C variable through a *converter* function. "
|
|
"This takes two arguments: the first is a function, the second is the address "
|
|
"of a C variable (of arbitrary type), converted to :c:type:`void \\*`. The "
|
|
"*converter* function in turn is called as follows::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:323
|
|
msgid ""
|
|
"where *object* is the Python object to be converted and *address* is the :c:"
|
|
"type:`void\\*` argument that was passed to the :c:func:`PyArg_Parse\\*` "
|
|
"function. The returned *status* should be ``1`` for a successful conversion "
|
|
"and ``0`` if the conversion has failed. When the conversion fails, the "
|
|
"*converter* function should raise an exception and leave the content of "
|
|
"*address* unmodified."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:329
|
|
msgid ""
|
|
"If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a "
|
|
"second time if the argument parsing eventually fails, giving the converter a "
|
|
"chance to release any memory that it had already allocated. In this second "
|
|
"call, the *object* parameter will be NULL; *address* will have the same "
|
|
"value as in the original call."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:335
|
|
msgid "``Py_CLEANUP_SUPPORTED`` was added."
|
|
msgstr "``Py_CLEANUP_SUPPORTED`` à été ajouté."
|
|
|
|
#: ../Doc/c-api/arg.rst:345
|
|
msgid "``p`` (:class:`bool`) [int]"
|
|
msgstr "``p`` (:class:`bool`) [int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:339
|
|
msgid ""
|
|
"Tests the value passed in for truth (a boolean **p**\\ redicate) and "
|
|
"converts the result to its equivalent C true/false integer value. Sets the "
|
|
"int to 1 if the expression was true and 0 if it was false. This accepts any "
|
|
"valid Python value. See :ref:`truth` for more information about how Python "
|
|
"tests values for truth."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:350 ../Doc/c-api/arg.rst:643
|
|
msgid "``(items)`` (:class:`tuple`) [*matching-items*]"
|
|
msgstr "``(items)`` (:class:`tuple`) [*matching-items*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:348
|
|
msgid ""
|
|
"The object must be a Python sequence whose length is the number of format "
|
|
"units in *items*. The C arguments must correspond to the individual format "
|
|
"units in *items*. Format units for sequences may be nested."
|
|
msgstr ""
|
|
"L'objet doit être une séquence Python dont la longueur est le nombre "
|
|
"d'unités de formats dans *articles*. Les arguments C doivent correspondre à "
|
|
"chaque unité de format particulière dans *articles*. Les unités de formats "
|
|
"pour les séquences peuvent être imbriquées. "
|
|
|
|
#: ../Doc/c-api/arg.rst:352
|
|
msgid ""
|
|
"It is possible to pass \"long\" integers (integers whose value exceeds the "
|
|
"platform's :const:`LONG_MAX`) however no proper range checking is done --- "
|
|
"the most significant bits are silently truncated when the receiving field is "
|
|
"too small to receive the value (actually, the semantics are inherited from "
|
|
"downcasts in C --- your mileage may vary)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:358
|
|
msgid ""
|
|
"A few other characters have a meaning in a format string. These may not "
|
|
"occur inside nested parentheses. They are:"
|
|
msgstr ""
|
|
"Quelques autres caractères ont un sens dans une chaîne de format. On ne doit "
|
|
"pas les trouvées dans des parenthèses imbriquées. Ce sont :"
|
|
|
|
#: ../Doc/c-api/arg.rst:366
|
|
msgid "``|``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:362
|
|
msgid ""
|
|
"Indicates that the remaining arguments in the Python argument list are "
|
|
"optional. The C variables corresponding to optional arguments should be "
|
|
"initialized to their default value --- when an optional argument is not "
|
|
"specified, :c:func:`PyArg_ParseTuple` does not touch the contents of the "
|
|
"corresponding C variable(s)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:375
|
|
msgid "``$``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:369
|
|
msgid ""
|
|
":c:func:`PyArg_ParseTupleAndKeywords` only: Indicates that the remaining "
|
|
"arguments in the Python argument list are keyword-only. Currently, all "
|
|
"keyword-only arguments must also be optional arguments, so ``|`` must always "
|
|
"be specified before ``$`` in the format string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:380
|
|
msgid "``:``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:378
|
|
msgid ""
|
|
"The list of format units ends here; the string after the colon is used as "
|
|
"the function name in error messages (the \"associated value\" of the "
|
|
"exception that :c:func:`PyArg_ParseTuple` raises)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:385
|
|
msgid "``;``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:383
|
|
msgid ""
|
|
"The list of format units ends here; the string after the semicolon is used "
|
|
"as the error message *instead* of the default error message. ``:`` and ``;"
|
|
"`` mutually exclude each other."
|
|
msgstr ""
|
|
"La liste des unités de format s'arrête ici ; la chaîne après le point-"
|
|
"virgule est utilise comme message d'erreur *au lieu* du message d'erreur par "
|
|
"défaut. ``:`` et ``;`` sont mutuellement exclusifs. "
|
|
|
|
#: ../Doc/c-api/arg.rst:387
|
|
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/c-api/arg.rst:390
|
|
msgid ""
|
|
"Additional arguments passed to these functions must be addresses of "
|
|
"variables whose type is determined by the format string; these are used to "
|
|
"store values from the input tuple. There are a few cases, as described in "
|
|
"the list of format units above, where these parameters are used as input "
|
|
"values; they should match what is specified for the corresponding format "
|
|
"unit in that case."
|
|
msgstr ""
|
|
"Les arguments additionnels qui sont donnés à ces fonctions doivent être des "
|
|
"adresses de variables dont le type est déterminé par la chaîine de format. "
|
|
"Elles sont utilisées pour stocker les valeurs du n-uplet d'entrée. Il y a "
|
|
"quelques cas, comme décrit précédemment dans le liste des unités de formats, "
|
|
"où ces paramètres sont utilisés comme valeurs d'entrée. Dans ce cas, ils "
|
|
"devraient correspondre à ce qui est spécifié pour l'unité de format "
|
|
"correspondante."
|
|
|
|
#: ../Doc/c-api/arg.rst:396
|
|
msgid ""
|
|
"For the conversion to succeed, the *arg* object must match the format and "
|
|
"the format must be exhausted. On success, the :c:func:`PyArg_Parse\\*` "
|
|
"functions return true, otherwise they return false and raise an appropriate "
|
|
"exception. When the :c:func:`PyArg_Parse\\*` functions fail due to "
|
|
"conversion failure in one of the format units, the variables at the "
|
|
"addresses corresponding to that and the following format units are left "
|
|
"untouched."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:405
|
|
msgid "API Functions"
|
|
msgstr "Fonction de l'API"
|
|
|
|
#: ../Doc/c-api/arg.rst:409
|
|
msgid ""
|
|
"Parse the parameters of a function that takes only positional parameters "
|
|
"into local variables. Returns true on success; on failure, it returns false "
|
|
"and raises the appropriate exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:416
|
|
msgid ""
|
|
"Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list "
|
|
"rather than a variable number of arguments."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:422
|
|
msgid ""
|
|
"Parse the parameters of a function that takes both positional and keyword "
|
|
"parameters into local variables. The *keywords* argument is a *NULL*-"
|
|
"terminated array of keyword parameter names. Empty names denote :ref:"
|
|
"`positional-only parameters <positional-only_parameter>`. Returns true on "
|
|
"success; on failure, it returns false and raises the appropriate exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:429
|
|
msgid ""
|
|
"Added support for :ref:`positional-only parameters <positional-"
|
|
"only_parameter>`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:436
|
|
msgid ""
|
|
"Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a "
|
|
"va_list rather than a variable number of arguments."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:442
|
|
msgid ""
|
|
"Ensure that the keys in the keywords argument dictionary are strings. This "
|
|
"is only needed if :c:func:`PyArg_ParseTupleAndKeywords` is not used, since "
|
|
"the latter already does this check."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:452
|
|
msgid ""
|
|
"Function used to deconstruct the argument lists of \"old-style\" functions "
|
|
"--- these are functions which use the :const:`METH_OLDARGS` parameter "
|
|
"parsing method, which has been removed in Python 3. This is not recommended "
|
|
"for use in parameter parsing in new code, and most code in the standard "
|
|
"interpreter has been modified to no longer use this for that purpose. It "
|
|
"does remain a convenient way to decompose other tuples, however, and may "
|
|
"continue to be used for that purpose."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:463
|
|
msgid ""
|
|
"A simpler form of parameter retrieval which does not use a format string to "
|
|
"specify the types of the arguments. Functions which use this method to "
|
|
"retrieve their parameters should be declared as :const:`METH_VARARGS` in "
|
|
"function or method tables. The tuple containing the actual parameters "
|
|
"should be passed as *args*; it must actually be a tuple. The length of the "
|
|
"tuple must be at least *min* and no more than *max*; *min* and *max* may be "
|
|
"equal. Additional arguments must be passed to the function, each of which "
|
|
"should be a pointer to a :c:type:`PyObject\\*` variable; these will be "
|
|
"filled in with the values from *args*; they will contain borrowed "
|
|
"references. The variables which correspond to optional parameters not given "
|
|
"by *args* will not be filled in; these should be initialized by the caller. "
|
|
"This function returns true on success and false if *args* is not a tuple or "
|
|
"contains the wrong number of elements; an exception will be set if there was "
|
|
"a failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:477
|
|
msgid ""
|
|
"This is an example of the use of this function, taken from the sources for "
|
|
"the :mod:`_weakref` helper module for weak references::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:493
|
|
msgid ""
|
|
"The call to :c:func:`PyArg_UnpackTuple` in this example is entirely "
|
|
"equivalent to this call to :c:func:`PyArg_ParseTuple`::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:501
|
|
msgid "Building values"
|
|
msgstr "Construction des valeurs"
|
|
|
|
#: ../Doc/c-api/arg.rst:505
|
|
msgid ""
|
|
"Create a new value based on a format string similar to those accepted by "
|
|
"the :c:func:`PyArg_Parse\\*` family of functions and a sequence of values. "
|
|
"Returns the value or *NULL* in the case of an error; an exception will be "
|
|
"raised if *NULL* is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:510
|
|
msgid ""
|
|
":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/c-api/arg.rst:516
|
|
msgid ""
|
|
"When memory buffers are passed as parameters to supply data to build "
|
|
"objects, as for the ``s`` and ``s#`` formats, the required data is copied. "
|
|
"Buffers provided by the caller are never referenced by the objects created "
|
|
"by :c:func:`Py_BuildValue`. In other words, if your code invokes :c:func:"
|
|
"`malloc` and passes the allocated memory to :c:func:`Py_BuildValue`, your "
|
|
"code is responsible for calling :c:func:`free` for that memory once :c:func:"
|
|
"`Py_BuildValue` returns."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:524
|
|
msgid ""
|
|
"In the following description, the quoted form is the format unit; the entry "
|
|
"in (round) parentheses is the Python object type that the format unit will "
|
|
"return; and the entry in [square] brackets is the type of the C value(s) to "
|
|
"be passed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:528
|
|
msgid ""
|
|
"The characters space, tab, colon and comma are ignored in format strings "
|
|
"(but not within format units such as ``s#``). This can be used to make long "
|
|
"format strings a tad more readable."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:534
|
|
msgid "``s`` (:class:`str` or ``None``) [char \\*]"
|
|
msgstr "``s`` (:class:`str` ou ``None``) [char \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:533
|
|
msgid ""
|
|
"Convert a null-terminated C string to a Python :class:`str` object using "
|
|
"``'utf-8'`` encoding. If the C string pointer is *NULL*, ``None`` is used."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:539
|
|
msgid "``s#`` (:class:`str` or ``None``) [char \\*, int]"
|
|
msgstr "``s#`` (:class:`str` ou ``None``) [char \\*, int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:537
|
|
msgid ""
|
|
"Convert a C string and its length to a Python :class:`str` object using "
|
|
"``'utf-8'`` encoding. If the C string pointer is *NULL*, the length is "
|
|
"ignored and ``None`` is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:543
|
|
msgid "``y`` (:class:`bytes`) [char \\*]"
|
|
msgstr "``y`` (:class:`bytes`) [char \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:542
|
|
msgid ""
|
|
"This converts a C string to a Python :class:`bytes` object. If the C string "
|
|
"pointer is *NULL*, ``None`` is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:547
|
|
msgid "``y#`` (:class:`bytes`) [char \\*, int]"
|
|
msgstr "``y#`` (:class:`bytes`) [char \\*, int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:546
|
|
msgid ""
|
|
"This converts a C string and its lengths to a Python object. If the C "
|
|
"string pointer is *NULL*, ``None`` is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:550
|
|
msgid "``z`` (:class:`str` or ``None``) [char \\*]"
|
|
msgstr "``z`` (:class:`str` ou ``None``) [char \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:550 ../Doc/c-api/arg.rst:565
|
|
msgid "Same as ``s``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:553
|
|
msgid "``z#`` (:class:`str` or ``None``) [char \\*, int]"
|
|
msgstr "``z#`` (:class:`str` ou ``None``) [char \\*, int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:553 ../Doc/c-api/arg.rst:568
|
|
msgid "Same as ``s#``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:556
|
|
msgid ""
|
|
"Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a "
|
|
"Python Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is "
|
|
"returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:560
|
|
msgid ""
|
|
"Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python "
|
|
"Unicode object. If the Unicode buffer pointer is *NULL*, the length is "
|
|
"ignored and ``None`` is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:565
|
|
msgid "``U`` (:class:`str` or ``None``) [char \\*]"
|
|
msgstr "``U`` (:class:`str` ou ``None``) [char \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:568
|
|
msgid "``U#`` (:class:`str` or ``None``) [char \\*, int]"
|
|
msgstr "``U#`` (:class:`str` ou ``None``) [char \\*, int]"
|
|
|
|
#: ../Doc/c-api/arg.rst:571
|
|
msgid "Convert a plain C :c:type:`int` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:574
|
|
msgid "``b`` (:class:`int`) [char]"
|
|
msgstr "``b`` (:class:`int`) [char]"
|
|
|
|
#: ../Doc/c-api/arg.rst:574
|
|
msgid "Convert a plain C :c:type:`char` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:577
|
|
msgid "Convert a plain C :c:type:`short int` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:580
|
|
msgid "Convert a C :c:type:`long int` to a Python integer object."
|
|
msgstr "Convertit un :c:type:`long int` en un int Python."
|
|
|
|
#: ../Doc/c-api/arg.rst:583
|
|
msgid "Convert a C :c:type:`unsigned char` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:586
|
|
msgid "Convert a C :c:type:`unsigned short int` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:589
|
|
msgid "Convert a C :c:type:`unsigned int` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:592
|
|
msgid "Convert a C :c:type:`unsigned long` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:595
|
|
msgid "Convert a C :c:type:`long long` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:598
|
|
msgid "Convert a C :c:type:`unsigned long long` to a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:601
|
|
msgid "Convert a C :c:type:`Py_ssize_t` to a Python integer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:605
|
|
msgid "``c`` (:class:`bytes` of length 1) [char]"
|
|
msgstr "``c`` (:class:`bytes` de taille 1) [char]"
|
|
|
|
#: ../Doc/c-api/arg.rst:604
|
|
msgid ""
|
|
"Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` "
|
|
"object of length 1."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:608
|
|
msgid ""
|
|
"Convert a C :c:type:`int` representing a character to Python :class:`str` "
|
|
"object of length 1."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:612
|
|
msgid "Convert a C :c:type:`double` to a Python floating point number."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:615
|
|
msgid "Convert a C :c:type:`float` to a Python floating point number."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:618
|
|
msgid "``D`` (:class:`complex`) [Py_complex \\*]"
|
|
msgstr "``D`` (:class:`complex`) [Py_complex \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:618
|
|
msgid "Convert a C :c:type:`Py_complex` structure to a Python complex number."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:621
|
|
msgid ""
|
|
"Pass a Python object untouched (except for its reference count, which is "
|
|
"incremented by one). If the object passed in is a *NULL* pointer, it is "
|
|
"assumed that this was caused because the call producing the argument found "
|
|
"an error and set an exception. Therefore, :c:func:`Py_BuildValue` will "
|
|
"return *NULL* but won't raise an exception. If no exception has been raised "
|
|
"yet, :exc:`SystemError` is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:629
|
|
msgid "``S`` (object) [PyObject \\*]"
|
|
msgstr "``S`` (object) [PyObject \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:629
|
|
msgid "Same as ``O``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:634
|
|
msgid "``N`` (object) [PyObject \\*]"
|
|
msgstr "``N`` (object) [PyObject \\*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:632
|
|
msgid ""
|
|
"Same as ``O``, except it doesn't increment the reference count on the "
|
|
"object. Useful when the object is created by a call to an object constructor "
|
|
"in the argument list."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:637
|
|
msgid ""
|
|
"Convert *anything* to a Python object through a *converter* function. The "
|
|
"function is called with *anything* (which should be compatible with :c:type:"
|
|
"`void \\*`) as its argument and should return a \"new\" Python object, or "
|
|
"*NULL* if an error occurred."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:643
|
|
msgid ""
|
|
"Convert a sequence of C values to a Python tuple with the same number of "
|
|
"items."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:646
|
|
msgid "``[items]`` (:class:`list`) [*matching-items*]"
|
|
msgstr "``[items]`` (:class:`list`) [*matching-items*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:646
|
|
msgid ""
|
|
"Convert a sequence of C values to a Python list with the same number of "
|
|
"items."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:651
|
|
msgid "``{items}`` (:class:`dict`) [*matching-items*]"
|
|
msgstr "``{items}`` (:class:`dict`) [*matching-items*]"
|
|
|
|
#: ../Doc/c-api/arg.rst:649
|
|
msgid ""
|
|
"Convert a sequence of C values to a Python dictionary. Each pair of "
|
|
"consecutive C values adds one item to the dictionary, serving as key and "
|
|
"value, respectively."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:653
|
|
msgid ""
|
|
"If there is an error in the format string, the :exc:`SystemError` exception "
|
|
"is set and *NULL* returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/arg.rst:658
|
|
msgid ""
|
|
"Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list "
|
|
"rather than a variable number of arguments."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bool.rst:6
|
|
msgid "Boolean Objects"
|
|
msgstr "Les objets booléens"
|
|
|
|
#: ../Doc/c-api/bool.rst:8
|
|
msgid ""
|
|
"Booleans in Python are implemented as a subclass of integers. There are "
|
|
"only two booleans, :const:`Py_False` and :const:`Py_True`. As such, the "
|
|
"normal creation and deletion functions don't apply to booleans. The "
|
|
"following macros are available, however."
|
|
msgstr ""
|
|
"Les booléens en Python sont implémentés comme une classe dérivée des "
|
|
"entiers. Il y a seulement deux booléens, :const:`Py_False` et :const:"
|
|
"`Py_True`. Comme tel, les fonctions de création de suppression ne "
|
|
"s'appliquent pas aux booléens. Toutefois, les macros suivantes sont "
|
|
"disponibles."
|
|
|
|
#: ../Doc/c-api/bool.rst:16
|
|
msgid "Return true if *o* is of type :c:data:`PyBool_Type`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bool.rst:21
|
|
msgid ""
|
|
"The Python ``False`` object. This object has no methods. It needs to be "
|
|
"treated just like any other object with respect to reference counts."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bool.rst:27
|
|
msgid ""
|
|
"The Python ``True`` object. This object has no methods. It needs to be "
|
|
"treated just like any other object with respect to reference counts."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bool.rst:33
|
|
msgid ""
|
|
"Return :const:`Py_False` from a function, properly incrementing its "
|
|
"reference count."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bool.rst:39
|
|
msgid ""
|
|
"Return :const:`Py_True` from a function, properly incrementing its reference "
|
|
"count."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bool.rst:45
|
|
msgid ""
|
|
"Return a new reference to :const:`Py_True` or :const:`Py_False` depending on "
|
|
"the truth value of *v*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:11
|
|
msgid "Buffer Protocol"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:18
|
|
msgid ""
|
|
"Certain objects available in Python wrap access to an underlying memory "
|
|
"array or *buffer*. Such objects include the built-in :class:`bytes` and :"
|
|
"class:`bytearray`, and some extension types like :class:`array.array`. Third-"
|
|
"party libraries may define their own types for special purposes, such as "
|
|
"image processing or numeric analysis."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:24
|
|
msgid ""
|
|
"While each of these types have their own semantics, they share the common "
|
|
"characteristic of being backed by a possibly large memory buffer. It is "
|
|
"then desirable, in some situations, to access that buffer directly and "
|
|
"without intermediate copying."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:29
|
|
msgid ""
|
|
"Python provides such a facility at the C level in the form of the :ref:"
|
|
"`buffer protocol <bufferobjects>`. This protocol has two sides:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:34
|
|
msgid ""
|
|
"on the producer side, a type can export a \"buffer interface\" which allows "
|
|
"objects of that type to expose information about their underlying buffer. "
|
|
"This interface is described in the section :ref:`buffer-structs`;"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:38
|
|
msgid ""
|
|
"on the consumer side, several means are available to obtain a pointer to the "
|
|
"raw underlying data of an object (for example a method parameter)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:41
|
|
msgid ""
|
|
"Simple objects such as :class:`bytes` and :class:`bytearray` expose their "
|
|
"underlying buffer in byte-oriented form. Other forms are possible; for "
|
|
"example, the elements exposed by an :class:`array.array` can be multi-byte "
|
|
"values."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:45
|
|
msgid ""
|
|
"An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase."
|
|
"write` method of file objects: any object that can export a series of bytes "
|
|
"through the buffer interface can be written to a file. While :meth:`write` "
|
|
"only needs read-only access to the internal contents of the object passed to "
|
|
"it, other methods such as :meth:`~io.BufferedIOBase.readinto` need write "
|
|
"access to the contents of their argument. The buffer interface allows "
|
|
"objects to selectively allow or reject exporting of read-write and read-only "
|
|
"buffers."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:53
|
|
msgid ""
|
|
"There are two ways for a consumer of the buffer interface to acquire a "
|
|
"buffer over a target object:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:56
|
|
msgid "call :c:func:`PyObject_GetBuffer` with the right parameters;"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:58
|
|
msgid ""
|
|
"call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the "
|
|
"``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:61
|
|
msgid ""
|
|
"In both cases, :c:func:`PyBuffer_Release` must be called when the buffer "
|
|
"isn't needed anymore. Failure to do so could lead to various issues such as "
|
|
"resource leaks."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:69
|
|
msgid "Buffer structure"
|
|
msgstr "La structure *buffer*"
|
|
|
|
#: ../Doc/c-api/buffer.rst:71
|
|
msgid ""
|
|
"Buffer structures (or simply \"buffers\") are useful as a way to expose the "
|
|
"binary data from another object to the Python programmer. They can also be "
|
|
"used as a zero-copy slicing mechanism. Using their ability to reference a "
|
|
"block of memory, it is possible to expose any data to the Python programmer "
|
|
"quite easily. The memory could be a large, constant array in a C extension, "
|
|
"it could be a raw block of memory for manipulation before passing to an "
|
|
"operating system library, or it could be used to pass around structured data "
|
|
"in its native, in-memory format."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:80
|
|
msgid ""
|
|
"Contrary to most data types exposed by the Python interpreter, buffers are "
|
|
"not :c:type:`PyObject` pointers but rather simple C structures. This allows "
|
|
"them to be created and copied very simply. When a generic wrapper around a "
|
|
"buffer is needed, a :ref:`memoryview <memoryview-objects>` object can be "
|
|
"created."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:86
|
|
msgid ""
|
|
"For short instructions how to write an exporting object, see :ref:`Buffer "
|
|
"Object Structures <buffer-structs>`. For obtaining a buffer, see :c:func:"
|
|
"`PyObject_GetBuffer`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:94
|
|
msgid ""
|
|
"A pointer to the start of the logical structure described by the buffer "
|
|
"fields. This can be any location within the underlying physical memory block "
|
|
"of the exporter. For example, with negative :c:member:`~Py_buffer.strides` "
|
|
"the value may point to the end of the memory block."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:99
|
|
msgid ""
|
|
"For :term:`contiguous` arrays, the value points to the beginning of the "
|
|
"memory block."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:104
|
|
msgid ""
|
|
"A new reference to the exporting object. The reference is owned by the "
|
|
"consumer and automatically decremented and set to *NULL* by :c:func:"
|
|
"`PyBuffer_Release`. The field is the equivalent of the return value of any "
|
|
"standard C-API function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:109
|
|
msgid ""
|
|
"As a special case, for *temporary* buffers that are wrapped by :c:func:"
|
|
"`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo` this field is "
|
|
"*NULL*. In general, exporting objects MUST NOT use this scheme."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:116
|
|
msgid ""
|
|
"``product(shape) * itemsize``. For contiguous arrays, this is the length of "
|
|
"the underlying memory block. For non-contiguous arrays, it is the length "
|
|
"that the logical structure would have if it were copied to a contiguous "
|
|
"representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:121
|
|
msgid ""
|
|
"Accessing ``((char *)buf)[0] up to ((char *)buf)[len-1]`` is only valid if "
|
|
"the buffer has been obtained by a request that guarantees contiguity. In "
|
|
"most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:"
|
|
"`PyBUF_WRITABLE`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:127
|
|
msgid ""
|
|
"An indicator of whether the buffer is read-only. This field is controlled by "
|
|
"the :c:macro:`PyBUF_WRITABLE` flag."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:132
|
|
msgid ""
|
|
"Item size in bytes of a single element. Same as the value of :func:`struct."
|
|
"calcsize` called on non-NULL :c:member:`~Py_buffer.format` values."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:135
|
|
msgid ""
|
|
"Important exception: If a consumer requests a buffer without the :c:macro:"
|
|
"`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will be set to *NULL*, "
|
|
"but :c:member:`~Py_buffer.itemsize` still has the value for the original "
|
|
"format."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:140
|
|
msgid ""
|
|
"If :c:member:`~Py_buffer.shape` is present, the equality ``product(shape) * "
|
|
"itemsize == len`` still holds and the consumer can use :c:member:`~Py_buffer."
|
|
"itemsize` to navigate the buffer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:144
|
|
msgid ""
|
|
"If :c:member:`~Py_buffer.shape` is *NULL* as a result of a :c:macro:"
|
|
"`PyBUF_SIMPLE` or a :c:macro:`PyBUF_WRITABLE` request, the consumer must "
|
|
"disregard :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:150
|
|
msgid ""
|
|
"A *NUL* terminated string in :mod:`struct` module style syntax describing "
|
|
"the contents of a single item. If this is *NULL*, ``\"B\"`` (unsigned bytes) "
|
|
"is assumed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:154
|
|
msgid "This field is controlled by the :c:macro:`PyBUF_FORMAT` flag."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:158
|
|
msgid ""
|
|
"The number of dimensions the memory represents as an n-dimensional array. If "
|
|
"it is 0, :c:member:`~Py_buffer.buf` points to a single item representing a "
|
|
"scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer."
|
|
"strides` and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:163
|
|
msgid ""
|
|
"The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions "
|
|
"to 64. Exporters MUST respect this limit, consumers of multi-dimensional "
|
|
"buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:169
|
|
msgid ""
|
|
"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim` "
|
|
"indicating the shape of the memory as an n-dimensional array. Note that "
|
|
"``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to :c:member:"
|
|
"`~Py_buffer.len`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:174
|
|
msgid ""
|
|
"Shape values are restricted to ``shape[n] >= 0``. The case ``shape[n] == 0`` "
|
|
"requires special attention. See `complex arrays`_ for further information."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:178
|
|
msgid "The shape array is read-only for the consumer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:182
|
|
msgid ""
|
|
"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim` "
|
|
"giving the number of bytes to skip to get to a new element in each dimension."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:186
|
|
msgid ""
|
|
"Stride values can be any integer. For regular arrays, strides are usually "
|
|
"positive, but a consumer MUST be able to handle the case ``strides[n] <= "
|
|
"0``. See `complex arrays`_ for further information."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:190
|
|
msgid "The strides array is read-only for the consumer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:194
|
|
msgid ""
|
|
"An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`. If "
|
|
"``suboffsets[n] >= 0``, the values stored along the nth dimension are "
|
|
"pointers and the suboffset value dictates how many bytes to add to each "
|
|
"pointer after de-referencing. A suboffset value that is negative indicates "
|
|
"that no de-referencing should occur (striding in a contiguous memory block)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:201
|
|
msgid ""
|
|
"If all suboffsets are negative (i.e. no de-referencing is needed, then this "
|
|
"field must be NULL (the default value)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:204
|
|
msgid ""
|
|
"This type of array representation is used by the Python Imaging Library "
|
|
"(PIL). See `complex arrays`_ for further information how to access elements "
|
|
"of such an array."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:208
|
|
msgid "The suboffsets array is read-only for the consumer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:212
|
|
msgid ""
|
|
"This is for use internally by the exporting object. For example, this might "
|
|
"be re-cast as an integer by the exporter and used to store flags about "
|
|
"whether or not the shape, strides, and suboffsets arrays must be freed when "
|
|
"the buffer is released. The consumer MUST NOT alter this value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:221
|
|
msgid "Buffer request types"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:223
|
|
msgid ""
|
|
"Buffers are usually obtained by sending a buffer request to an exporting "
|
|
"object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical "
|
|
"structure of the memory can vary drastically, the consumer uses the *flags* "
|
|
"argument to specify the exact buffer type it can handle."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:228
|
|
msgid ""
|
|
"All :c:data:`Py_buffer` fields are unambiguously defined by the request type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:232
|
|
msgid "request-independent fields"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:233
|
|
msgid ""
|
|
"The following fields are not influenced by *flags* and must always be filled "
|
|
"in with the correct values: :c:member:`~Py_buffer.obj`, :c:member:"
|
|
"`~Py_buffer.buf`, :c:member:`~Py_buffer.len`, :c:member:`~Py_buffer."
|
|
"itemsize`, :c:member:`~Py_buffer.ndim`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:239
|
|
msgid "readonly, format"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:243
|
|
msgid ""
|
|
"Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter "
|
|
"MUST provide a writable buffer or else report failure. Otherwise, the "
|
|
"exporter MAY provide either a read-only or writable buffer, but the choice "
|
|
"MUST be consistent for all consumers."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:250
|
|
msgid ""
|
|
"Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST be "
|
|
"filled in correctly. Otherwise, this field MUST be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:254
|
|
msgid ""
|
|
":c:macro:`PyBUF_WRITABLE` can be \\|'d to any of the flags in the next "
|
|
"section. Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:"
|
|
"`PyBUF_WRITABLE` can be used as a stand-alone flag to request a simple "
|
|
"writable buffer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:258
|
|
msgid ""
|
|
":c:macro:`PyBUF_FORMAT` can be \\|'d to any of the flags except :c:macro:"
|
|
"`PyBUF_SIMPLE`. The latter already implies format ``B`` (unsigned bytes)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:263
|
|
msgid "shape, strides, suboffsets"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:265
|
|
msgid ""
|
|
"The flags that control the logical structure of the memory are listed in "
|
|
"decreasing order of complexity. Note that each flag contains all bits of the "
|
|
"flags below it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:272 ../Doc/c-api/buffer.rst:296
|
|
#: ../Doc/c-api/buffer.rst:321
|
|
msgid "Request"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:272 ../Doc/c-api/buffer.rst:296
|
|
#: ../Doc/c-api/buffer.rst:321
|
|
msgid "shape"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:272 ../Doc/c-api/buffer.rst:296
|
|
#: ../Doc/c-api/buffer.rst:321
|
|
msgid "strides"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:272 ../Doc/c-api/buffer.rst:296
|
|
#: ../Doc/c-api/buffer.rst:321
|
|
msgid "suboffsets"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:274 ../Doc/c-api/buffer.rst:276
|
|
#: ../Doc/c-api/buffer.rst:278 ../Doc/c-api/buffer.rst:298
|
|
#: ../Doc/c-api/buffer.rst:300 ../Doc/c-api/buffer.rst:302
|
|
#: ../Doc/c-api/buffer.rst:304 ../Doc/c-api/buffer.rst:323
|
|
#: ../Doc/c-api/buffer.rst:325 ../Doc/c-api/buffer.rst:327
|
|
#: ../Doc/c-api/buffer.rst:329 ../Doc/c-api/buffer.rst:331
|
|
#: ../Doc/c-api/buffer.rst:333 ../Doc/c-api/buffer.rst:335
|
|
#: ../Doc/c-api/buffer.rst:337
|
|
msgid "yes"
|
|
msgstr "oui"
|
|
|
|
#: ../Doc/c-api/buffer.rst:274 ../Doc/c-api/buffer.rst:323
|
|
#: ../Doc/c-api/buffer.rst:325
|
|
msgid "if needed"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:276 ../Doc/c-api/buffer.rst:278
|
|
#: ../Doc/c-api/buffer.rst:280 ../Doc/c-api/buffer.rst:298
|
|
#: ../Doc/c-api/buffer.rst:300 ../Doc/c-api/buffer.rst:302
|
|
#: ../Doc/c-api/buffer.rst:304 ../Doc/c-api/buffer.rst:327
|
|
#: ../Doc/c-api/buffer.rst:329 ../Doc/c-api/buffer.rst:331
|
|
#: ../Doc/c-api/buffer.rst:333 ../Doc/c-api/buffer.rst:335
|
|
#: ../Doc/c-api/buffer.rst:337
|
|
msgid "NULL"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:287
|
|
msgid "contiguity requests"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:289
|
|
msgid ""
|
|
"C or Fortran :term:`contiguity <contiguous>` can be explicitly requested, "
|
|
"with and without stride information. Without stride information, the buffer "
|
|
"must be C-contiguous."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:296 ../Doc/c-api/buffer.rst:321
|
|
msgid "contig"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:298 ../Doc/c-api/buffer.rst:304
|
|
#: ../Doc/c-api/buffer.rst:335 ../Doc/c-api/buffer.rst:337
|
|
msgid "C"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:300
|
|
msgid "F"
|
|
msgstr "F"
|
|
|
|
#: ../Doc/c-api/buffer.rst:302
|
|
msgid "C or F"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:309
|
|
msgid "compound requests"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:311
|
|
msgid ""
|
|
"All possible requests are fully defined by some combination of the flags in "
|
|
"the previous section. For convenience, the buffer protocol provides "
|
|
"frequently used combinations as single flags."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:315
|
|
msgid ""
|
|
"In the following table *U* stands for undefined contiguity. The consumer "
|
|
"would have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:321
|
|
msgid "readonly"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:321
|
|
msgid "format"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:323 ../Doc/c-api/buffer.rst:325
|
|
#: ../Doc/c-api/buffer.rst:327 ../Doc/c-api/buffer.rst:329
|
|
#: ../Doc/c-api/buffer.rst:331 ../Doc/c-api/buffer.rst:333
|
|
msgid "U"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:323 ../Doc/c-api/buffer.rst:327
|
|
#: ../Doc/c-api/buffer.rst:331 ../Doc/c-api/buffer.rst:335
|
|
#: ../Doc/c-api/init.rst:1158
|
|
msgid "0"
|
|
msgstr "0"
|
|
|
|
#: ../Doc/c-api/buffer.rst:325 ../Doc/c-api/buffer.rst:329
|
|
#: ../Doc/c-api/buffer.rst:333 ../Doc/c-api/buffer.rst:337
|
|
msgid "1 or 0"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:342
|
|
msgid "Complex arrays"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:345
|
|
msgid "NumPy-style: shape and strides"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:347
|
|
msgid ""
|
|
"The logical structure of NumPy-style arrays is defined by :c:member:"
|
|
"`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer."
|
|
"shape` and :c:member:`~Py_buffer.strides`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:350
|
|
msgid ""
|
|
"If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer."
|
|
"buf` is interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In "
|
|
"that case, both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer."
|
|
"strides` are *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:354
|
|
msgid ""
|
|
"If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as a "
|
|
"standard n-dimensional C-array. Otherwise, the consumer must access an n-"
|
|
"dimensional array as follows:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:358
|
|
msgid ""
|
|
"``ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * "
|
|
"strides[n-1]`` ``item = *((typeof(item) *)ptr);``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:362
|
|
msgid ""
|
|
"As noted above, :c:member:`~Py_buffer.buf` can point to any location within "
|
|
"the actual memory block. An exporter can check the validity of a buffer with "
|
|
"this function:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:396
|
|
msgid "PIL-style: shape, strides and suboffsets"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:398
|
|
msgid ""
|
|
"In addition to the regular items, PIL-style arrays can contain pointers that "
|
|
"must be followed in order to get to the next element in a dimension. For "
|
|
"example, the regular three-dimensional C-array ``char v[2][2][3]`` can also "
|
|
"be viewed as an array of 2 pointers to 2 two-dimensional arrays: ``char "
|
|
"(*v[2])[2][3]``. In suboffsets representation, those two pointers can be "
|
|
"embedded at the start of :c:member:`~Py_buffer.buf`, pointing to two ``char "
|
|
"x[2][3]`` arrays that can be located anywhere in memory."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:407
|
|
msgid ""
|
|
"Here is a function that returns a pointer to the element in an N-D array "
|
|
"pointed to by an N-dimensional index when there are both non-NULL strides "
|
|
"and suboffsets::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:426
|
|
msgid "Buffer-related functions"
|
|
msgstr "Fonctions relatives aux buffers"
|
|
|
|
#: ../Doc/c-api/buffer.rst:430
|
|
msgid ""
|
|
"Return 1 if *obj* supports the buffer interface otherwise 0. When 1 is "
|
|
"returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will "
|
|
"succeed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:437
|
|
msgid ""
|
|
"Send a request to *exporter* to fill in *view* as specified by *flags*. If "
|
|
"the exporter cannot provide a buffer of the exact type, it MUST raise :c:"
|
|
"data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and return -1."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:442
|
|
msgid ""
|
|
"On success, fill in *view*, set :c:member:`view->obj` to a new reference to "
|
|
"*exporter* and return 0. In the case of chained buffer providers that "
|
|
"redirect requests to a single object, :c:member:`view->obj` MAY refer to "
|
|
"this object instead of *exporter* (See :ref:`Buffer Object Structures "
|
|
"<buffer-structs>`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:447
|
|
msgid ""
|
|
"Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls "
|
|
"to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:"
|
|
"`free`. Thus, after the consumer is done with the buffer, :c:func:"
|
|
"`PyBuffer_Release` must be called exactly once."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:455
|
|
msgid ""
|
|
"Release the buffer *view* and decrement the reference count for :c:member:"
|
|
"`view->obj`. This function MUST be called when the buffer is no longer being "
|
|
"used, otherwise reference leaks may occur."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:459
|
|
msgid ""
|
|
"It is an error to call this function on a buffer that was not obtained via :"
|
|
"c:func:`PyObject_GetBuffer`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:465
|
|
msgid ""
|
|
"Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer."
|
|
"format`. This function is not yet implemented."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:471
|
|
msgid ""
|
|
"Return 1 if the memory defined by the *view* is C-style (*order* is ``'C'``) "
|
|
"or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one "
|
|
"(*order* is ``'A'``). Return 0 otherwise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:478
|
|
msgid ""
|
|
"Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style "
|
|
"if *order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the "
|
|
"given shape with the given number of bytes per element."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:485
|
|
msgid ""
|
|
"Handle buffer requests for an exporter that wants to expose *buf* of size "
|
|
"*len* with writability set according to *readonly*. *buf* is interpreted as "
|
|
"a sequence of unsigned bytes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:489
|
|
msgid ""
|
|
"The *flags* argument indicates the request type. This function always fills "
|
|
"in *view* as specified by flags, unless *buf* has been designated as read-"
|
|
"only and :c:macro:`PyBUF_WRITABLE` is set in *flags*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:493
|
|
msgid ""
|
|
"On success, set :c:member:`view->obj` to a new reference to *exporter* and "
|
|
"return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set :c:member:`view-"
|
|
">obj` to *NULL* and return -1;"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/buffer.rst:497
|
|
msgid ""
|
|
"If this function is used as part of a :ref:`getbufferproc <buffer-structs>`, "
|
|
"*exporter* MUST be set to the exporting object and *flags* must be passed "
|
|
"unmodified. Otherwise, *exporter* MUST be NULL."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:6
|
|
msgid "Byte Array Objects"
|
|
msgstr "Objets Tableau d'Octets"
|
|
|
|
#: ../Doc/c-api/bytearray.rst:13
|
|
msgid ""
|
|
"This subtype of :c:type:`PyObject` represents a Python bytearray object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:18
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python bytearray "
|
|
"type; it is the same object as :class:`bytearray` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:23
|
|
msgid "Type check macros"
|
|
msgstr "Macros de vérification de type"
|
|
|
|
#: ../Doc/c-api/bytearray.rst:27
|
|
msgid ""
|
|
"Return true if the object *o* is a bytearray object or an instance of a "
|
|
"subtype of the bytearray type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:33
|
|
msgid ""
|
|
"Return true if the object *o* is a bytearray object, but not an instance of "
|
|
"a subtype of the bytearray type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:38
|
|
msgid "Direct API functions"
|
|
msgstr "Fonctions directes sur l'API"
|
|
|
|
#: ../Doc/c-api/bytearray.rst:42
|
|
msgid ""
|
|
"Return a new bytearray object from any object, *o*, that implements the :ref:"
|
|
"`buffer protocol <bufferobjects>`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:50
|
|
msgid ""
|
|
"Create a new bytearray object from *string* and its length, *len*. On "
|
|
"failure, *NULL* is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:56
|
|
msgid ""
|
|
"Concat bytearrays *a* and *b* and return a new bytearray with the result."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:61
|
|
msgid "Return the size of *bytearray* after checking for a *NULL* pointer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:66
|
|
msgid ""
|
|
"Return the contents of *bytearray* as a char array after checking for a "
|
|
"*NULL* pointer. The returned array always has an extra null byte appended."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:73
|
|
msgid "Resize the internal buffer of *bytearray* to *len*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:76
|
|
msgid "Macros"
|
|
msgstr "Macros"
|
|
|
|
#: ../Doc/c-api/bytearray.rst:78
|
|
msgid "These macros trade safety for speed and they don't check pointers."
|
|
msgstr ""
|
|
"Ces macros sont taillées pour la vitesse d'exécution et ne vérifient pas les "
|
|
"pointeurs."
|
|
|
|
#: ../Doc/c-api/bytearray.rst:82
|
|
msgid "Macro version of :c:func:`PyByteArray_AsString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytearray.rst:87
|
|
msgid "Macro version of :c:func:`PyByteArray_Size`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:6
|
|
msgid "Bytes Objects"
|
|
msgstr "Objets bytes"
|
|
|
|
#: ../Doc/c-api/bytes.rst:8
|
|
msgid ""
|
|
"These functions raise :exc:`TypeError` when expecting a bytes parameter and "
|
|
"are called with a non-bytes parameter."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:16
|
|
msgid "This subtype of :c:type:`PyObject` represents a Python bytes object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:21
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python bytes type; it "
|
|
"is the same object as :class:`bytes` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:27
|
|
msgid ""
|
|
"Return true if the object *o* is a bytes object or an instance of a subtype "
|
|
"of the bytes type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:33
|
|
msgid ""
|
|
"Return true if the object *o* is a bytes object, but not an instance of a "
|
|
"subtype of the bytes type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:39
|
|
msgid ""
|
|
"Return a new bytes object with a copy of the string *v* as value on success, "
|
|
"and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be "
|
|
"checked."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:46
|
|
msgid ""
|
|
"Return a new bytes object with a copy of the string *v* as value and length "
|
|
"*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of "
|
|
"the bytes object are uninitialized."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:53
|
|
msgid ""
|
|
"Take a C :c:func:`printf`\\ -style *format* string and a variable number of "
|
|
"arguments, calculate the size of the resulting Python bytes object and "
|
|
"return a bytes object with the values formatted into it. The variable "
|
|
"arguments must be C types and must correspond exactly to the format "
|
|
"characters in the *format* string. The following format characters are "
|
|
"allowed:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:68 ../Doc/c-api/unicode.rst:447
|
|
msgid "Format Characters"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:68 ../Doc/c-api/unicode.rst:447
|
|
msgid "Type"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:68 ../Doc/c-api/unicode.rst:447
|
|
msgid "Comment"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:70 ../Doc/c-api/unicode.rst:449
|
|
msgid ":attr:`%%`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:70 ../Doc/c-api/unicode.rst:449
|
|
msgid "*n/a*"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:70 ../Doc/c-api/unicode.rst:449
|
|
msgid "The literal % character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:72 ../Doc/c-api/unicode.rst:451
|
|
msgid ":attr:`%c`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:72 ../Doc/c-api/bytes.rst:75
|
|
#: ../Doc/c-api/bytes.rst:93 ../Doc/c-api/bytes.rst:96
|
|
#: ../Doc/c-api/structures.rst:136 ../Doc/c-api/structures.rst:245
|
|
#: ../Doc/c-api/structures.rst:252 ../Doc/c-api/structures.rst:268
|
|
#: ../Doc/c-api/unicode.rst:451 ../Doc/c-api/unicode.rst:454
|
|
#: ../Doc/c-api/unicode.rst:487 ../Doc/c-api/unicode.rst:490
|
|
msgid "int"
|
|
msgstr "int"
|
|
|
|
#: ../Doc/c-api/bytes.rst:72
|
|
msgid "A single byte, represented as a C int."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:75 ../Doc/c-api/unicode.rst:454
|
|
msgid ":attr:`%d`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:75 ../Doc/c-api/unicode.rst:454
|
|
msgid "Exactly equivalent to ``printf(\"%d\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:78 ../Doc/c-api/unicode.rst:457
|
|
msgid ":attr:`%u`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:78 ../Doc/c-api/structures.rst:278
|
|
#: ../Doc/c-api/unicode.rst:457
|
|
msgid "unsigned int"
|
|
msgstr "unsigned int"
|
|
|
|
#: ../Doc/c-api/bytes.rst:78 ../Doc/c-api/unicode.rst:457
|
|
msgid "Exactly equivalent to ``printf(\"%u\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:81 ../Doc/c-api/unicode.rst:460
|
|
msgid ":attr:`%ld`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:81 ../Doc/c-api/structures.rst:269
|
|
#: ../Doc/c-api/unicode.rst:460 ../Doc/c-api/unicode.rst:463
|
|
msgid "long"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:81 ../Doc/c-api/unicode.rst:460
|
|
msgid "Exactly equivalent to ``printf(\"%ld\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:84 ../Doc/c-api/unicode.rst:466
|
|
msgid ":attr:`%lu`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:84 ../Doc/c-api/structures.rst:280
|
|
#: ../Doc/c-api/unicode.rst:466
|
|
msgid "unsigned long"
|
|
msgstr "unsigned long"
|
|
|
|
#: ../Doc/c-api/bytes.rst:84 ../Doc/c-api/unicode.rst:466
|
|
msgid "Exactly equivalent to ``printf(\"%lu\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:87 ../Doc/c-api/unicode.rst:478
|
|
msgid ":attr:`%zd`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:87 ../Doc/c-api/structures.rst:248
|
|
#: ../Doc/c-api/structures.rst:284 ../Doc/c-api/unicode.rst:478
|
|
#: ../Doc/c-api/unicode.rst:481
|
|
msgid "Py_ssize_t"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:87 ../Doc/c-api/unicode.rst:478
|
|
msgid "Exactly equivalent to ``printf(\"%zd\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:90 ../Doc/c-api/unicode.rst:484
|
|
msgid ":attr:`%zu`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:90 ../Doc/c-api/unicode.rst:484
|
|
msgid "size_t"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:90 ../Doc/c-api/unicode.rst:484
|
|
msgid "Exactly equivalent to ``printf(\"%zu\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:93 ../Doc/c-api/unicode.rst:487
|
|
msgid ":attr:`%i`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:93 ../Doc/c-api/unicode.rst:487
|
|
msgid "Exactly equivalent to ``printf(\"%i\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:96 ../Doc/c-api/unicode.rst:490
|
|
msgid ":attr:`%x`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:96 ../Doc/c-api/unicode.rst:490
|
|
msgid "Exactly equivalent to ``printf(\"%x\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:99 ../Doc/c-api/unicode.rst:493
|
|
msgid ":attr:`%s`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:99 ../Doc/c-api/unicode.rst:493
|
|
msgid "char\\*"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:99 ../Doc/c-api/unicode.rst:493
|
|
msgid "A null-terminated C character array."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:102 ../Doc/c-api/unicode.rst:496
|
|
msgid ":attr:`%p`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:102 ../Doc/c-api/unicode.rst:496
|
|
msgid "void\\*"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:102 ../Doc/c-api/unicode.rst:496
|
|
msgid ""
|
|
"The hex representation of a C pointer. Mostly equivalent to ``printf(\"%p"
|
|
"\")`` except that it is guaranteed to start with the literal ``0x`` "
|
|
"regardless of what the platform's ``printf`` yields."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:111
|
|
msgid ""
|
|
"An unrecognized format character causes all the rest of the format string to "
|
|
"be copied as-is to the result object, and any extra arguments discarded."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:117
|
|
msgid ""
|
|
"Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two "
|
|
"arguments."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:123
|
|
msgid ""
|
|
"Return the bytes representation of object *o* that implements the buffer "
|
|
"protocol."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:129
|
|
msgid "Return the length of the bytes in bytes object *o*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:134
|
|
msgid "Macro form of :c:func:`PyBytes_Size` but without error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:139
|
|
msgid ""
|
|
"Return a pointer to the contents of *o*. The pointer refers to the internal "
|
|
"buffer of *o*, which consists of ``len(o) + 1`` bytes. The last byte in the "
|
|
"buffer is always null, regardless of whether there are any other null "
|
|
"bytes. The data must not be modified in any way, unless the object was just "
|
|
"created using ``PyBytes_FromStringAndSize(NULL, size)``. It must not be "
|
|
"deallocated. If *o* is not a bytes object at all, :c:func:"
|
|
"`PyBytes_AsString` returns *NULL* and raises :exc:`TypeError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:151
|
|
msgid "Macro form of :c:func:`PyBytes_AsString` but without error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:156
|
|
msgid ""
|
|
"Return the null-terminated contents of the object *obj* through the output "
|
|
"variables *buffer* and *length*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:159
|
|
msgid ""
|
|
"If *length* is *NULL*, the bytes object may not contain embedded null bytes; "
|
|
"if it does, the function returns ``-1`` and a :exc:`ValueError` is raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:163
|
|
msgid ""
|
|
"The buffer refers to an internal buffer of *obj*, which includes an "
|
|
"additional null byte at the end (not counted in *length*). The data must "
|
|
"not be modified in any way, unless the object was just created using "
|
|
"``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If "
|
|
"*obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize` "
|
|
"returns ``-1`` and raises :exc:`TypeError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:170
|
|
msgid ""
|
|
"Previously, :exc:`TypeError` was raised when embedded null bytes were "
|
|
"encountered in the bytes object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:177
|
|
msgid ""
|
|
"Create a new bytes object in *\\*bytes* containing the contents of *newpart* "
|
|
"appended to *bytes*; the caller will own the new reference. The reference "
|
|
"to the old value of *bytes* will be stolen. If the new object cannot be "
|
|
"created, the old reference to *bytes* will still be discarded and the value "
|
|
"of *\\*bytes* will be set to *NULL*; the appropriate exception will be set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:186
|
|
msgid ""
|
|
"Create a new bytes object in *\\*bytes* containing the contents of *newpart* "
|
|
"appended to *bytes*. This version decrements the reference count of "
|
|
"*newpart*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/bytes.rst:193
|
|
msgid ""
|
|
"A way to resize a bytes object even though it is \"immutable\". Only use "
|
|
"this to build up a brand new bytes object; don't use this if the bytes may "
|
|
"already be known in other parts of the code. It is an error to call this "
|
|
"function if the refcount on the input bytes object is not one. Pass the "
|
|
"address of an existing bytes object as an lvalue (it may be written into), "
|
|
"and the new size desired. On success, *\\*bytes* holds the resized bytes "
|
|
"object and ``0`` is returned; the address in *\\*bytes* may differ from its "
|
|
"input value. If the reallocation fails, the original bytes object at *"
|
|
"\\*bytes* is deallocated, *\\*bytes* is set to *NULL*, :exc:`MemoryError` is "
|
|
"set, and ``-1`` is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:6
|
|
msgid "Capsules"
|
|
msgstr "Capsules"
|
|
|
|
#: ../Doc/c-api/capsule.rst:10
|
|
msgid ""
|
|
"Refer to :ref:`using-capsules` for more information on using these objects."
|
|
msgstr ""
|
|
"Reportez-vous à :ref:`using-capsules` pour plus d'informations sur "
|
|
"l'utilisation de ces objets."
|
|
|
|
#: ../Doc/c-api/capsule.rst:15
|
|
msgid ""
|
|
"This subtype of :c:type:`PyObject` represents an opaque value, useful for C "
|
|
"extension modules who need to pass an opaque value (as a :c:type:`void\\*` "
|
|
"pointer) through Python code to other C code. It is often used to make a C "
|
|
"function pointer defined in one module available to other modules, so the "
|
|
"regular import mechanism can be used to access C APIs defined in dynamically "
|
|
"loaded modules."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:24
|
|
msgid "The type of a destructor callback for a capsule. Defined as::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:28
|
|
msgid ""
|
|
"See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor "
|
|
"callbacks."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:34
|
|
msgid "Return true if its argument is a :c:type:`PyCapsule`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:39
|
|
msgid ""
|
|
"Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer* "
|
|
"argument may not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:42
|
|
msgid "On failure, set an exception and return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:44
|
|
msgid ""
|
|
"The *name* string may either be *NULL* or a pointer to a valid C string. If "
|
|
"non-*NULL*, this string must outlive the capsule. (Though it is permitted "
|
|
"to free it inside the *destructor*.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:48
|
|
msgid ""
|
|
"If the *destructor* argument is not *NULL*, it will be called with the "
|
|
"capsule as its argument when it is destroyed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:51
|
|
msgid ""
|
|
"If this capsule will be stored as an attribute of a module, the *name* "
|
|
"should be specified as ``modulename.attributename``. This will enable other "
|
|
"modules to import the capsule using :c:func:`PyCapsule_Import`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:58
|
|
msgid ""
|
|
"Retrieve the *pointer* stored in the capsule. On failure, set an exception "
|
|
"and return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:61
|
|
msgid ""
|
|
"The *name* parameter must compare exactly to the name stored in the capsule. "
|
|
"If the name stored in the capsule is *NULL*, the *name* passed in must also "
|
|
"be *NULL*. Python uses the C function :c:func:`strcmp` to compare capsule "
|
|
"names."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:69
|
|
msgid ""
|
|
"Return the current destructor stored in the capsule. On failure, set an "
|
|
"exception and return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:72
|
|
msgid ""
|
|
"It is legal for a capsule to have a *NULL* destructor. This makes a *NULL* "
|
|
"return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :c:func:"
|
|
"`PyErr_Occurred` to disambiguate."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:79
|
|
msgid ""
|
|
"Return the current context stored in the capsule. On failure, set an "
|
|
"exception and return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:82
|
|
msgid ""
|
|
"It is legal for a capsule to have a *NULL* context. This makes a *NULL* "
|
|
"return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :c:func:"
|
|
"`PyErr_Occurred` to disambiguate."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:89
|
|
msgid ""
|
|
"Return the current name stored in the capsule. On failure, set an exception "
|
|
"and return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:92
|
|
msgid ""
|
|
"It is legal for a capsule to have a *NULL* name. This makes a *NULL* return "
|
|
"code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or :c:func:"
|
|
"`PyErr_Occurred` to disambiguate."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:99
|
|
msgid ""
|
|
"Import a pointer to a C object from a capsule attribute in a module. The "
|
|
"*name* parameter should specify the full name to the attribute, as in "
|
|
"``module.attribute``. The *name* stored in the capsule must match this "
|
|
"string exactly. If *no_block* is true, import the module without blocking "
|
|
"(using :c:func:`PyImport_ImportModuleNoBlock`). If *no_block* is false, "
|
|
"import the module conventionally (using :c:func:`PyImport_ImportModule`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:106
|
|
msgid ""
|
|
"Return the capsule's internal *pointer* on success. On failure, set an "
|
|
"exception and return *NULL*. However, if :c:func:`PyCapsule_Import` failed "
|
|
"to import the module, and *no_block* was true, no exception is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:112
|
|
msgid ""
|
|
"Determines whether or not *capsule* is a valid capsule. A valid capsule is "
|
|
"non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer "
|
|
"stored in it, and its internal name matches the *name* parameter. (See :c:"
|
|
"func:`PyCapsule_GetPointer` for information on how capsule names are "
|
|
"compared.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:118
|
|
msgid ""
|
|
"In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls "
|
|
"to any of the accessors (any function starting with :c:func:`PyCapsule_Get`) "
|
|
"are guaranteed to succeed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:122
|
|
msgid ""
|
|
"Return a nonzero value if the object is valid and matches the name passed "
|
|
"in. Return 0 otherwise. This function will not fail."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:127
|
|
msgid "Set the context pointer inside *capsule* to *context*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:129 ../Doc/c-api/capsule.rst:135
|
|
#: ../Doc/c-api/capsule.rst:143 ../Doc/c-api/capsule.rst:150
|
|
msgid "Return 0 on success. Return nonzero and set an exception on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:133
|
|
msgid "Set the destructor inside *capsule* to *destructor*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:139
|
|
msgid ""
|
|
"Set the name inside *capsule* to *name*. If non-*NULL*, the name must "
|
|
"outlive the capsule. If the previous *name* stored in the capsule was not "
|
|
"*NULL*, no attempt is made to free it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/capsule.rst:147
|
|
msgid ""
|
|
"Set the void pointer inside *capsule* to *pointer*. The pointer may not be "
|
|
"*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/cell.rst:6
|
|
msgid "Cell Objects"
|
|
msgstr "Objets Cellules"
|
|
|
|
#: ../Doc/c-api/cell.rst:8
|
|
msgid ""
|
|
"\"Cell\" objects are used to implement variables referenced by multiple "
|
|
"scopes. For each such variable, a cell object is created to store the value; "
|
|
"the local variables of each stack frame that references the value contains a "
|
|
"reference to the cells from outer scopes which also use that variable. When "
|
|
"the value is accessed, the value contained in the cell is used instead of "
|
|
"the cell object itself. This de-referencing of the cell object requires "
|
|
"support from the generated byte-code; these are not automatically de-"
|
|
"referenced when accessed. Cell objects are not likely to be useful elsewhere."
|
|
msgstr ""
|
|
"Les objets \"Cellules\" sont utilisés pour implémenter des variables "
|
|
"référencées dans de multiples enviromments. Pour chacune de ces variables, "
|
|
"un objet cellule est créé pour stocker sa valeur ; les variables locales de "
|
|
"chaque pile d'exécution qui référence cette valeur contiennent une référence "
|
|
"sur les cellules des autres environnements qui utilisent aussi cette "
|
|
"variable. Quand la valeur est accédée, la valeur de la cellule est utilisée, "
|
|
"au lei de celle de l'objet cellule proprement dit. Ce dé-référencement de "
|
|
"l'objet cellule requiert l'intervention du bytecode généré ; il n'est pas "
|
|
"automatiquement dé-référencé quand il est accédé. Il est plausible que les "
|
|
"objets cellules ne soit utilisés ailleurs."
|
|
|
|
#: ../Doc/c-api/cell.rst:20
|
|
msgid "The C structure used for cell objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/cell.rst:25
|
|
msgid "The type object corresponding to cell objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/cell.rst:30
|
|
msgid "Return true if *ob* is a cell object; *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/cell.rst:35
|
|
msgid ""
|
|
"Create and return a new cell object containing the value *ob*. The parameter "
|
|
"may be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/cell.rst:41
|
|
msgid "Return the contents of the cell *cell*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/cell.rst:46
|
|
msgid ""
|
|
"Return the contents of the cell *cell*, but without checking that *cell* is "
|
|
"non-*NULL* and a cell object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/cell.rst:52
|
|
msgid ""
|
|
"Set the contents of the cell object *cell* to *value*. This releases the "
|
|
"reference to any current content of the cell. *value* may be *NULL*. *cell* "
|
|
"must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On "
|
|
"success, ``0`` will be returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/cell.rst:60
|
|
msgid ""
|
|
"Sets the value of the cell object *cell* to *value*. No reference counts "
|
|
"are adjusted, and no checks are made for safety; *cell* must be non-*NULL* "
|
|
"and must be a cell object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/code.rst:8
|
|
msgid "Code Objects"
|
|
msgstr "Objets Code"
|
|
|
|
#: ../Doc/c-api/code.rst:12
|
|
msgid ""
|
|
"Code objects are a low-level detail of the CPython implementation. Each one "
|
|
"represents a chunk of executable code that hasn't yet been bound into a "
|
|
"function."
|
|
msgstr ""
|
|
"Les objets Code sont un détail bas-niveau de l'implémentation CPython. "
|
|
"Chacun d'eux représente une partie de code exécutable, qui n'a pas encore "
|
|
"été lié dans une fonction."
|
|
|
|
#: ../Doc/c-api/code.rst:18
|
|
msgid ""
|
|
"The C structure of the objects used to describe code objects. The fields of "
|
|
"this type are subject to change at any time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/code.rst:24
|
|
msgid ""
|
|
"This is an instance of :c:type:`PyTypeObject` representing the Python :class:"
|
|
"`code` type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/code.rst:30
|
|
msgid "Return true if *co* is a :class:`code` object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/code.rst:34
|
|
msgid "Return the number of free variables in *co*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/code.rst:38
|
|
msgid ""
|
|
"Return a new code object. If you need a dummy code object to create a "
|
|
"frame, use :c:func:`PyCode_NewEmpty` instead. Calling :c:func:`PyCode_New` "
|
|
"directly can bind you to a precise Python version since the definition of "
|
|
"the bytecode changes often."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/code.rst:46
|
|
msgid ""
|
|
"Return a new empty code object with the specified filename, function name, "
|
|
"and first line number. It is illegal to :func:`exec` or :func:`eval` the "
|
|
"resulting code object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:4
|
|
msgid "Codec registry and support functions"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:8
|
|
msgid "Register a new codec search function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:10
|
|
msgid ""
|
|
"As side effect, this tries to load the :mod:`encodings` package, if not yet "
|
|
"done, to make sure that it is always first in the list of search functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:15
|
|
msgid ""
|
|
"Return ``1`` or ``0`` depending on whether there is a registered codec for "
|
|
"the given *encoding*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:20
|
|
msgid "Generic codec based encoding API."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:22
|
|
msgid ""
|
|
"*object* is passed through the encoder function found for the given "
|
|
"*encoding* using the error handling method defined by *errors*. *errors* "
|
|
"may be *NULL* to use the default method defined for the codec. Raises a :"
|
|
"exc:`LookupError` if no encoder can be found."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:29
|
|
msgid "Generic codec based decoding API."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:31
|
|
msgid ""
|
|
"*object* is passed through the decoder function found for the given "
|
|
"*encoding* using the error handling method defined by *errors*. *errors* "
|
|
"may be *NULL* to use the default method defined for the codec. Raises a :"
|
|
"exc:`LookupError` if no encoder can be found."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:38
|
|
msgid "Codec lookup API"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:40
|
|
msgid ""
|
|
"In the following functions, the *encoding* string is looked up converted to "
|
|
"all lower-case characters, which makes encodings looked up through this "
|
|
"mechanism effectively case-insensitive. If no codec is found, a :exc:"
|
|
"`KeyError` is set and *NULL* returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:47
|
|
msgid "Get an encoder function for the given *encoding*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:51
|
|
msgid "Get a decoder function for the given *encoding*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:55
|
|
msgid ""
|
|
"Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:59
|
|
msgid ""
|
|
"Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:63
|
|
msgid ""
|
|
"Get a :class:`~codecs.StreamReader` factory function for the given "
|
|
"*encoding*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:67
|
|
msgid ""
|
|
"Get a :class:`~codecs.StreamWriter` factory function for the given "
|
|
"*encoding*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:71
|
|
msgid "Registry API for Unicode encoding error handlers"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:75
|
|
msgid ""
|
|
"Register the error handling callback function *error* under the given "
|
|
"*name*. This callback function will be called by a codec when it encounters "
|
|
"unencodable characters/undecodable bytes and *name* is specified as the "
|
|
"error parameter in the call to the encode/decode function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:80
|
|
msgid ""
|
|
"The callback gets a single argument, an instance of :exc:"
|
|
"`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or :exc:"
|
|
"`UnicodeTranslateError` that holds information about the problematic "
|
|
"sequence of characters or bytes and their offset in the original string "
|
|
"(see :ref:`unicodeexceptions` for functions to extract this information). "
|
|
"The callback must either raise the given exception, or return a two-item "
|
|
"tuple containing the replacement for the problematic sequence, and an "
|
|
"integer giving the offset in the original string at which encoding/decoding "
|
|
"should be resumed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:90
|
|
msgid "Return ``0`` on success, ``-1`` on error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:94
|
|
msgid ""
|
|
"Lookup the error handling callback function registered under *name*. As a "
|
|
"special case *NULL* can be passed, in which case the error handling callback "
|
|
"for \"strict\" will be returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:100
|
|
msgid "Raise *exc* as an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:104
|
|
msgid "Ignore the unicode error, skipping the faulty input."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:108
|
|
msgid "Replace the unicode encode error with ``?`` or ``U+FFFD``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:112
|
|
msgid "Replace the unicode encode error with XML character references."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:116
|
|
msgid ""
|
|
"Replace the unicode encode error with backslash escapes (``\\x``, ``\\u`` "
|
|
"and ``\\U``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/codec.rst:121
|
|
msgid "Replace the unicode encode error with ``\\N{...}`` escapes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:6
|
|
msgid "Complex Number Objects"
|
|
msgstr "Objets Nombres Complexes"
|
|
|
|
#: ../Doc/c-api/complex.rst:10
|
|
msgid ""
|
|
"Python's complex number objects are implemented as two distinct types when "
|
|
"viewed from the C API: one is the Python object exposed to Python programs, "
|
|
"and the other is a C structure which represents the actual complex number "
|
|
"value. The API provides functions for working with both."
|
|
msgstr ""
|
|
"Les objets Python nombres complexes sont implémentés comme deux types "
|
|
"distincts, lorsqu'ils sont vus de l'API C : l'un est l'objet Python tel "
|
|
"qu'il est vu par les programmes Python, et l'autre est une structure C qui "
|
|
"représente la valeur complexe courante. L'API fournit des fonctions pour "
|
|
"travailler avec ces deux représentations."
|
|
|
|
#: ../Doc/c-api/complex.rst:17
|
|
msgid "Complex Numbers as C Structures"
|
|
msgstr "Nombres complexes en tant que structures C"
|
|
|
|
#: ../Doc/c-api/complex.rst:19
|
|
msgid ""
|
|
"Note that the functions which accept these structures as parameters and "
|
|
"return them as results do so *by value* rather than dereferencing them "
|
|
"through pointers. This is consistent throughout the API."
|
|
msgstr ""
|
|
"Remarquez que les fonctions qui acceptent ces structures comme paramètres et "
|
|
"les retournent comme résultats le font *par valeur* au lieur de les dé-"
|
|
"référencer en utilisant des pointeurs. Cela est constant dans toute l'API."
|
|
|
|
#: ../Doc/c-api/complex.rst:26
|
|
msgid ""
|
|
"The C structure which corresponds to the value portion of a Python complex "
|
|
"number object. Most of the functions for dealing with complex number "
|
|
"objects use structures of this type as input or output values, as "
|
|
"appropriate. It is defined as::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:39
|
|
msgid ""
|
|
"Return the sum of two complex numbers, using the C :c:type:`Py_complex` "
|
|
"representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:45
|
|
msgid ""
|
|
"Return the difference between two complex numbers, using the C :c:type:"
|
|
"`Py_complex` representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:51
|
|
msgid ""
|
|
"Return the negation of the complex number *complex*, using the C :c:type:"
|
|
"`Py_complex` representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:57
|
|
msgid ""
|
|
"Return the product of two complex numbers, using the C :c:type:`Py_complex` "
|
|
"representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:63
|
|
msgid ""
|
|
"Return the quotient of two complex numbers, using the C :c:type:`Py_complex` "
|
|
"representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:66
|
|
msgid ""
|
|
"If *divisor* is null, this method returns zero and sets :c:data:`errno` to :"
|
|
"c:data:`EDOM`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:72
|
|
msgid ""
|
|
"Return the exponentiation of *num* by *exp*, using the C :c:type:"
|
|
"`Py_complex` representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:75
|
|
msgid ""
|
|
"If *num* is null and *exp* is not a positive real number, this method "
|
|
"returns zero and sets :c:data:`errno` to :c:data:`EDOM`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:80
|
|
msgid "Complex Numbers as Python Objects"
|
|
msgstr "Nombres complexes en tant qu'objets Python"
|
|
|
|
#: ../Doc/c-api/complex.rst:85
|
|
msgid ""
|
|
"This subtype of :c:type:`PyObject` represents a Python complex number object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:90
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python complex number "
|
|
"type. It is the same object as :class:`complex` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:96
|
|
msgid ""
|
|
"Return true if its argument is a :c:type:`PyComplexObject` or a subtype of :"
|
|
"c:type:`PyComplexObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:102
|
|
msgid ""
|
|
"Return true if its argument is a :c:type:`PyComplexObject`, but not a "
|
|
"subtype of :c:type:`PyComplexObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:108
|
|
msgid ""
|
|
"Create a new Python complex number object from a C :c:type:`Py_complex` "
|
|
"value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:113
|
|
msgid "Return a new :c:type:`PyComplexObject` object from *real* and *imag*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:118
|
|
msgid "Return the real part of *op* as a C :c:type:`double`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:123
|
|
msgid "Return the imaginary part of *op* as a C :c:type:`double`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:128
|
|
msgid "Return the :c:type:`Py_complex` value of the complex number *op*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/complex.rst:130
|
|
msgid ""
|
|
"If *op* is not a Python complex number object but has a :meth:`__complex__` "
|
|
"method, this method will first be called to convert *op* to a Python complex "
|
|
"number object. Upon failure, this method returns ``-1.0`` as a real value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/concrete.rst:8
|
|
msgid "Concrete Objects Layer"
|
|
msgstr "Couche des Objets Concrets"
|
|
|
|
#: ../Doc/c-api/concrete.rst:10
|
|
msgid ""
|
|
"The functions in this chapter are specific to certain Python object types. "
|
|
"Passing them an object of the wrong type is not a good idea; if you receive "
|
|
"an object from a Python program and you are not sure that it has the right "
|
|
"type, you must perform a type check first; for example, to check that an "
|
|
"object is a dictionary, use :c:func:`PyDict_Check`. The chapter is "
|
|
"structured like the \"family tree\" of Python object types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/concrete.rst:19
|
|
msgid ""
|
|
"While the functions described in this chapter carefully check the type of "
|
|
"the objects which are passed in, many of them do not check for *NULL* being "
|
|
"passed instead of a valid object. Allowing *NULL* to be passed in can cause "
|
|
"memory access violations and immediate termination of the interpreter."
|
|
msgstr ""
|
|
"Tandis que les fonctions décrites dans ce chapitre vérifient avec soin le "
|
|
"type des objets qui leur sont passés, beaucoup d'entre elles ne vérifient "
|
|
"pas que *NULL* est passé au lieu d'un objet valide. Autoriser *NULL* à être "
|
|
"passé peut provoquer des violations d'accès à la mémoire et ainsi terminer "
|
|
"immédiatement l'interpréteur."
|
|
|
|
#: ../Doc/c-api/concrete.rst:28
|
|
msgid "Fundamental Objects"
|
|
msgstr "Objets fondamentaux"
|
|
|
|
#: ../Doc/c-api/concrete.rst:30
|
|
msgid ""
|
|
"This section describes Python type objects and the singleton object ``None``."
|
|
msgstr ""
|
|
"Cette section décrit les objets de type Python et l'objet singleton ``None``."
|
|
|
|
#: ../Doc/c-api/concrete.rst:41
|
|
msgid "Numeric Objects"
|
|
msgstr "Objets numériques"
|
|
|
|
#: ../Doc/c-api/concrete.rst:56
|
|
msgid "Sequence Objects"
|
|
msgstr "Objets séquences"
|
|
|
|
#: ../Doc/c-api/concrete.rst:60
|
|
msgid ""
|
|
"Generic operations on sequence objects were discussed in the previous "
|
|
"chapter; this section deals with the specific kinds of sequence objects that "
|
|
"are intrinsic to the Python language."
|
|
msgstr ""
|
|
"Les opérations génériques sur les objets séquences ont été discutées dans le "
|
|
"chapitre précédent. Cette section traite des genres spécifiques d'objets "
|
|
"séquences qui sont intrinsèques au langage Python."
|
|
|
|
#: ../Doc/c-api/concrete.rst:78
|
|
msgid "Container Objects"
|
|
msgstr "Objets Conteneurs"
|
|
|
|
#: ../Doc/c-api/concrete.rst:91 ../Doc/c-api/function.rst:6
|
|
msgid "Function Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/concrete.rst:102
|
|
msgid "Other Objects"
|
|
msgstr "Autres Objets"
|
|
|
|
#: ../Doc/c-api/conversion.rst:6
|
|
msgid "String conversion and formatting"
|
|
msgstr "Conversion et formatage de chaînes"
|
|
|
|
#: ../Doc/c-api/conversion.rst:8
|
|
msgid "Functions for number conversion and formatted string output."
|
|
msgstr ""
|
|
"Fonctions de conversion pour les nombres et pour la sortie des chaînes "
|
|
"formattées."
|
|
|
|
#: ../Doc/c-api/conversion.rst:13
|
|
msgid ""
|
|
"Output not more than *size* bytes to *str* according to the format string "
|
|
"*format* and the extra arguments. See the Unix man page :manpage:"
|
|
"`snprintf(2)`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:19
|
|
msgid ""
|
|
"Output not more than *size* bytes to *str* according to the format string "
|
|
"*format* and the variable argument list *va*. Unix man page :manpage:"
|
|
"`vsnprintf(2)`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:23
|
|
msgid ""
|
|
":c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C "
|
|
"library functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose "
|
|
"is to guarantee consistent behavior in corner cases, which the Standard C "
|
|
"functions do not."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:28
|
|
msgid ""
|
|
"The wrappers ensure that *str*[*size*-1] is always ``'\\0'`` upon return. "
|
|
"They never write more than *size* bytes (including the trailing ``'\\0'``) "
|
|
"into str. Both functions require that ``str != NULL``, ``size > 0`` and "
|
|
"``format != NULL``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:33
|
|
msgid ""
|
|
"If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed "
|
|
"to avoid truncation exceeds *size* by more than 512 bytes, Python aborts "
|
|
"with a *Py_FatalError*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:37
|
|
msgid ""
|
|
"The return value (*rv*) for these functions should be interpreted as follows:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:39
|
|
msgid ""
|
|
"When ``0 <= rv < size``, the output conversion was successful and *rv* "
|
|
"characters were written to *str* (excluding the trailing ``'\\0'`` byte at "
|
|
"*str*[*rv*])."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:43
|
|
msgid ""
|
|
"When ``rv >= size``, the output conversion was truncated and a buffer with "
|
|
"``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is "
|
|
"``'\\0'`` in this case."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:47
|
|
msgid ""
|
|
"When ``rv < 0``, \"something bad happened.\" *str*[*size*-1] is ``'\\0'`` in "
|
|
"this case too, but the rest of *str* is undefined. The exact cause of the "
|
|
"error depends on the underlying platform."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:51
|
|
msgid ""
|
|
"The following functions provide locale-independent string to number "
|
|
"conversions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:56
|
|
msgid ""
|
|
"Convert a string ``s`` to a :c:type:`double`, raising a Python exception on "
|
|
"failure. The set of accepted strings corresponds to the set of strings "
|
|
"accepted by Python's :func:`float` constructor, except that ``s`` must not "
|
|
"have leading or trailing whitespace. The conversion is independent of the "
|
|
"current locale."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:62
|
|
msgid ""
|
|
"If ``endptr`` is ``NULL``, convert the whole string. Raise ValueError and "
|
|
"return ``-1.0`` if the string is not a valid representation of a floating-"
|
|
"point number."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:66
|
|
msgid ""
|
|
"If endptr is not ``NULL``, convert as much of the string as possible and set "
|
|
"``*endptr`` to point to the first unconverted character. If no initial "
|
|
"segment of the string is the valid representation of a floating-point "
|
|
"number, set ``*endptr`` to point to the beginning of the string, raise "
|
|
"ValueError, and return ``-1.0``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:73
|
|
msgid ""
|
|
"If ``s`` represents a value that is too large to store in a float (for "
|
|
"example, ``\"1e500\"`` is such a string on many platforms) then if "
|
|
"``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with an "
|
|
"appropriate sign) and don't set any exception. Otherwise, "
|
|
"``overflow_exception`` must point to a Python exception object; raise that "
|
|
"exception and return ``-1.0``. In both cases, set ``*endptr`` to point to "
|
|
"the first character after the converted value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:81
|
|
msgid ""
|
|
"If any other error occurs during the conversion (for example an out-of-"
|
|
"memory error), set the appropriate Python exception and return ``-1.0``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:90
|
|
msgid ""
|
|
"Convert a :c:type:`double` *val* to a string using supplied *format_code*, "
|
|
"*precision*, and *flags*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:93
|
|
msgid ""
|
|
"*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``, ``'g'``, "
|
|
"``'G'`` or ``'r'``. For ``'r'``, the supplied *precision* must be 0 and is "
|
|
"ignored. The ``'r'`` format code specifies the standard :func:`repr` format."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:98
|
|
msgid ""
|
|
"*flags* can be zero or more of the values *Py_DTSF_SIGN*, "
|
|
"*Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:101
|
|
msgid ""
|
|
"*Py_DTSF_SIGN* means to always precede the returned string with a sign "
|
|
"character, even if *val* is non-negative."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:104
|
|
msgid ""
|
|
"*Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look "
|
|
"like an integer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:107
|
|
msgid ""
|
|
"*Py_DTSF_ALT* means to apply \"alternate\" formatting rules. See the "
|
|
"documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for details."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:111
|
|
msgid ""
|
|
"If *ptype* is non-NULL, then the value it points to will be set to one of "
|
|
"*Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that "
|
|
"*val* is a finite number, an infinite number, or not a number, respectively."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:115
|
|
msgid ""
|
|
"The return value is a pointer to *buffer* with the converted string or "
|
|
"*NULL* if the conversion failed. The caller is responsible for freeing the "
|
|
"returned string by calling :c:func:`PyMem_Free`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:124
|
|
msgid ""
|
|
"Case insensitive comparison of strings. The function works almost "
|
|
"identically to :c:func:`strcmp` except that it ignores the case."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/conversion.rst:130
|
|
msgid ""
|
|
"Case insensitive comparison of strings. The function works almost "
|
|
"identically to :c:func:`strncmp` except that it ignores the case."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/coro.rst:6
|
|
msgid "Coroutine Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/coro.rst:10
|
|
msgid ""
|
|
"Coroutine objects are what functions declared with an ``async`` keyword "
|
|
"return."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/coro.rst:16
|
|
msgid "The C structure used for coroutine objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/coro.rst:21
|
|
msgid "The type object corresponding to coroutine objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/coro.rst:26
|
|
msgid "Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/coro.rst:31
|
|
msgid ""
|
|
"Create and return a new coroutine object based on the *frame* object, with "
|
|
"``__name__`` and ``__qualname__`` set to *name* and *qualname*. A reference "
|
|
"to *frame* is stolen by this function. The *frame* argument must not be "
|
|
"*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:6
|
|
msgid "DateTime Objects"
|
|
msgstr "Objets DateTime"
|
|
|
|
#: ../Doc/c-api/datetime.rst:8
|
|
msgid ""
|
|
"Various date and time objects are supplied by the :mod:`datetime` module. "
|
|
"Before using any of these functions, the header file :file:`datetime.h` must "
|
|
"be included in your source (note that this is not included by :file:`Python."
|
|
"h`), and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as "
|
|
"part of the module initialisation function. The macro puts a pointer to a C "
|
|
"structure into a static variable, :c:data:`PyDateTimeAPI`, that is used by "
|
|
"the following macros."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:16
|
|
msgid "Type-check macros:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:20
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype "
|
|
"of :c:data:`PyDateTime_DateType`. *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:26
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not "
|
|
"be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:32
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a "
|
|
"subtype of :c:data:`PyDateTime_DateTimeType`. *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:38
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must "
|
|
"not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:44
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype "
|
|
"of :c:data:`PyDateTime_TimeType`. *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:50
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not "
|
|
"be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:56
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype "
|
|
"of :c:data:`PyDateTime_DeltaType`. *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:62
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not "
|
|
"be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:68
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype "
|
|
"of :c:data:`PyDateTime_TZInfoType`. *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:74
|
|
msgid ""
|
|
"Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must "
|
|
"not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:78
|
|
msgid "Macros to create objects:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:82
|
|
msgid ""
|
|
"Return a ``datetime.date`` object with the specified year, month and day."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:87
|
|
msgid ""
|
|
"Return a ``datetime.datetime`` object with the specified year, month, day, "
|
|
"hour, minute, second and microsecond."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:93
|
|
msgid ""
|
|
"Return a ``datetime.time`` object with the specified hour, minute, second "
|
|
"and microsecond."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:99
|
|
msgid ""
|
|
"Return a ``datetime.timedelta`` object representing the given number of "
|
|
"days, seconds and microseconds. Normalization is performed so that the "
|
|
"resulting number of microseconds and seconds lie in the ranges documented "
|
|
"for ``datetime.timedelta`` objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:105
|
|
msgid ""
|
|
"Macros to extract fields from date objects. The argument must be an "
|
|
"instance of :c:data:`PyDateTime_Date`, including subclasses (such as :c:data:"
|
|
"`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is "
|
|
"not checked:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:112
|
|
msgid "Return the year, as a positive int."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:117
|
|
msgid "Return the month, as an int from 1 through 12."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:122
|
|
msgid "Return the day, as an int from 1 through 31."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:125
|
|
msgid ""
|
|
"Macros to extract fields from datetime objects. The argument must be an "
|
|
"instance of :c:data:`PyDateTime_DateTime`, including subclasses. The "
|
|
"argument must not be *NULL*, and the type is not checked:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:131 ../Doc/c-api/datetime.rst:155
|
|
msgid "Return the hour, as an int from 0 through 23."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:136 ../Doc/c-api/datetime.rst:160
|
|
msgid "Return the minute, as an int from 0 through 59."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:141 ../Doc/c-api/datetime.rst:165
|
|
msgid "Return the second, as an int from 0 through 59."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:146 ../Doc/c-api/datetime.rst:170
|
|
msgid "Return the microsecond, as an int from 0 through 999999."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:149
|
|
msgid ""
|
|
"Macros to extract fields from time objects. The argument must be an "
|
|
"instance of :c:data:`PyDateTime_Time`, including subclasses. The argument "
|
|
"must not be *NULL*, and the type is not checked:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:173
|
|
msgid ""
|
|
"Macros to extract fields from time delta objects. The argument must be an "
|
|
"instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument "
|
|
"must not be *NULL*, and the type is not checked:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:179
|
|
msgid "Return the number of days, as an int from -999999999 to 999999999."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:186
|
|
msgid "Return the number of seconds, as an int from 0 through 86399."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:193
|
|
msgid "Return the number of microseconds, as an int from 0 through 999999."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:198
|
|
msgid "Macros for the convenience of modules implementing the DB API:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:202
|
|
msgid ""
|
|
"Create and return a new ``datetime.datetime`` object given an argument tuple "
|
|
"suitable for passing to ``datetime.datetime.fromtimestamp()``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/datetime.rst:208
|
|
msgid ""
|
|
"Create and return a new ``datetime.date`` object given an argument tuple "
|
|
"suitable for passing to ``datetime.date.fromtimestamp()``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/descriptor.rst:6
|
|
msgid "Descriptor Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/descriptor.rst:8
|
|
msgid ""
|
|
"\"Descriptors\" are objects that describe some attribute of an object. They "
|
|
"are found in the dictionary of type objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/descriptor.rst:15
|
|
msgid "The type object for the built-in descriptor types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/descriptor.rst:35
|
|
msgid ""
|
|
"Return true if the descriptor objects *descr* describes a data attribute, or "
|
|
"false if it describes a method. *descr* must be a descriptor object; there "
|
|
"is no error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:6
|
|
msgid "Dictionary Objects"
|
|
msgstr "Objets dictionnaires"
|
|
|
|
#: ../Doc/c-api/dict.rst:13
|
|
msgid ""
|
|
"This subtype of :c:type:`PyObject` represents a Python dictionary object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:18
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python dictionary "
|
|
"type. This is the same object as :class:`dict` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:24
|
|
msgid ""
|
|
"Return true if *p* is a dict object or an instance of a subtype of the dict "
|
|
"type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:30
|
|
msgid ""
|
|
"Return true if *p* is a dict object, but not an instance of a subtype of the "
|
|
"dict type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:36
|
|
msgid "Return a new empty dictionary, or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:41
|
|
msgid ""
|
|
"Return a :class:`types.MappingProxyType` object for a mapping which enforces "
|
|
"read-only behavior. This is normally used to create a view to prevent "
|
|
"modification of the dictionary for non-dynamic class types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:48
|
|
msgid "Empty an existing dictionary of all key-value pairs."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:53
|
|
msgid ""
|
|
"Determine if dictionary *p* contains *key*. If an item in *p* is matches "
|
|
"*key*, return ``1``, otherwise return ``0``. On error, return ``-1``. This "
|
|
"is equivalent to the Python expression ``key in p``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:60
|
|
msgid "Return a new dictionary that contains the same key-value pairs as *p*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:65
|
|
msgid ""
|
|
"Insert *value* into the dictionary *p* with a key of *key*. *key* must be :"
|
|
"term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0`` "
|
|
"on success or ``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:74
|
|
msgid ""
|
|
"Insert *value* into the dictionary *p* using *key* as a key. *key* should be "
|
|
"a :c:type:`char\\*`. The key object is created using "
|
|
"``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:82
|
|
msgid ""
|
|
"Remove the entry in dictionary *p* with key *key*. *key* must be hashable; "
|
|
"if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1`` "
|
|
"on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:89
|
|
msgid ""
|
|
"Remove the entry in dictionary *p* which has a key specified by the string "
|
|
"*key*. Return ``0`` on success or ``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:95
|
|
msgid ""
|
|
"Return the object from dictionary *p* which has a key *key*. Return *NULL* "
|
|
"if the key *key* is not present, but *without* setting an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:101
|
|
msgid ""
|
|
"Variant of :c:func:`PyDict_GetItem` that does not suppress exceptions. "
|
|
"Return *NULL* **with** an exception set if an exception occurred. Return "
|
|
"*NULL* **without** an exception set if the key wasn't present."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:109
|
|
msgid ""
|
|
"This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a :c:"
|
|
"type:`char\\*`, rather than a :c:type:`PyObject\\*`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:115
|
|
msgid ""
|
|
"This is the same as the Python-level :meth:`dict.setdefault`. If present, "
|
|
"it returns the value corresponding to *key* from the dictionary *p*. If the "
|
|
"key is not in the dict, it is inserted with value *defaultobj* and "
|
|
"*defaultobj* is returned. This function evaluates the hash function of "
|
|
"*key* only once, instead of evaluating it independently for the lookup and "
|
|
"the insertion."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:125
|
|
msgid ""
|
|
"Return a :c:type:`PyListObject` containing all the items from the dictionary."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:130
|
|
msgid ""
|
|
"Return a :c:type:`PyListObject` containing all the keys from the dictionary."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:135
|
|
msgid ""
|
|
"Return a :c:type:`PyListObject` containing all the values from the "
|
|
"dictionary *p*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:143
|
|
msgid ""
|
|
"Return the number of items in the dictionary. This is equivalent to "
|
|
"``len(p)`` on a dictionary."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:149
|
|
msgid ""
|
|
"Iterate over all key-value pairs in the dictionary *p*. The :c:type:"
|
|
"`Py_ssize_t` referred to by *ppos* must be initialized to ``0`` prior to the "
|
|
"first call to this function to start the iteration; the function returns "
|
|
"true for each pair in the dictionary, and false once all pairs have been "
|
|
"reported. The parameters *pkey* and *pvalue* should either point to :c:type:"
|
|
"`PyObject\\*` variables that will be filled in with each key and value, "
|
|
"respectively, or may be *NULL*. Any references returned through them are "
|
|
"borrowed. *ppos* should not be altered during iteration. Its value "
|
|
"represents offsets within the internal dictionary structure, and since the "
|
|
"structure is sparse, the offsets are not consecutive."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:160
|
|
msgid "For example::"
|
|
msgstr "Par exemple : ::"
|
|
|
|
#: ../Doc/c-api/dict.rst:170
|
|
msgid ""
|
|
"The dictionary *p* should not be mutated during iteration. It is safe to "
|
|
"modify the values of the keys as you iterate over the dictionary, but only "
|
|
"so long as the set of keys does not change. For example::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:195
|
|
msgid ""
|
|
"Iterate over mapping object *b* adding key-value pairs to dictionary *a*. "
|
|
"*b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys` "
|
|
"and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* "
|
|
"will be replaced if a matching key is found in *b*, otherwise pairs will "
|
|
"only be added if there is not a matching key in *a*. Return ``0`` on success "
|
|
"or ``-1`` if an exception was raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:205
|
|
msgid ""
|
|
"This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to ``a."
|
|
"update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall back "
|
|
"to the iterating over a sequence of key value pairs if the second argument "
|
|
"has no \"keys\" attribute. Return ``0`` on success or ``-1`` if an "
|
|
"exception was raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:214
|
|
msgid ""
|
|
"Update or merge into dictionary *a*, from the key-value pairs in *seq2*. "
|
|
"*seq2* must be an iterable object producing iterable objects of length 2, "
|
|
"viewed as key-value pairs. In case of duplicate keys, the last wins if "
|
|
"*override* is true, else the first wins. Return ``0`` on success or ``-1`` "
|
|
"if an exception was raised. Equivalent Python (except for the return value)::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/dict.rst:229 ../Doc/c-api/list.rst:149
|
|
#: ../Doc/c-api/method.rst:99 ../Doc/c-api/set.rst:164
|
|
#: ../Doc/c-api/tuple.rst:110 ../Doc/c-api/unicode.rst:202
|
|
msgid "Clear the free list. Return the total number of freed items."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:8
|
|
msgid "Exception Handling"
|
|
msgstr "Gestion des exceptions"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:10
|
|
msgid ""
|
|
"The functions described in this chapter will let you handle and raise Python "
|
|
"exceptions. It is important to understand some of the basics of Python "
|
|
"exception handling. It works somewhat like the POSIX :c:data:`errno` "
|
|
"variable: there is a global indicator (per thread) of the last error that "
|
|
"occurred. Most C API functions don't clear this on success, but will set it "
|
|
"to indicate the cause of the error on failure. Most C API functions also "
|
|
"return an error indicator, usually *NULL* if they are supposed to return a "
|
|
"pointer, or ``-1`` if they return an integer (exception: the :c:func:`PyArg_"
|
|
"\\*` functions return ``1`` for success and ``0`` for failure)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:20
|
|
msgid ""
|
|
"Concretely, the error indicator consists of three object pointers: the "
|
|
"exception's type, the exception's value, and the traceback object. Any of "
|
|
"those pointers can be NULL if non-set (although some combinations are "
|
|
"forbidden, for example you can't have a non-NULL traceback if the exception "
|
|
"type is NULL)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:26
|
|
msgid ""
|
|
"When a function must fail because some function it called failed, it "
|
|
"generally doesn't set the error indicator; the function it called already "
|
|
"set it. It is responsible for either handling the error and clearing the "
|
|
"exception or returning after cleaning up any resources it holds (such as "
|
|
"object references or memory allocations); it should *not* continue normally "
|
|
"if it is not prepared to handle the error. If returning due to an error, it "
|
|
"is important to indicate to the caller that an error has been set. If the "
|
|
"error is not handled or carefully propagated, additional calls into the "
|
|
"Python/C API may not behave as intended and may fail in mysterious ways."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:37
|
|
msgid ""
|
|
"The error indicator is **not** the result of :func:`sys.exc_info()`. The "
|
|
"former corresponds to an exception that is not yet caught (and is therefore "
|
|
"still propagating), while the latter returns an exception after it is caught "
|
|
"(and has therefore stopped propagating)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:44
|
|
msgid "Printing and clearing"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:49
|
|
msgid ""
|
|
"Clear the error indicator. If the error indicator is not set, there is no "
|
|
"effect."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:55
|
|
msgid ""
|
|
"Print a standard traceback to ``sys.stderr`` and clear the error indicator. "
|
|
"Call this function only when the error indicator is set. (Otherwise it will "
|
|
"cause a fatal error!)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:59
|
|
msgid ""
|
|
"If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`, :"
|
|
"data:`sys.last_value` and :data:`sys.last_traceback` will be set to the "
|
|
"type, value and traceback of the printed exception, respectively."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:66
|
|
msgid "Alias for ``PyErr_PrintEx(1)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:71
|
|
msgid ""
|
|
"This utility function prints a warning message to ``sys.stderr`` when an "
|
|
"exception has been set but it is impossible for the interpreter to actually "
|
|
"raise the exception. It is used, for example, when an exception occurs in "
|
|
"an :meth:`__del__` method."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:76
|
|
msgid ""
|
|
"The function is called with a single argument *obj* that identifies the "
|
|
"context in which the unraisable exception occurred. If possible, the repr of "
|
|
"*obj* will be printed in the warning message."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:82
|
|
msgid "Raising exceptions"
|
|
msgstr "Lever des exceptions"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:84
|
|
msgid ""
|
|
"These functions help you set the current thread's error indicator. For "
|
|
"convenience, some of these functions will always return a NULL pointer for "
|
|
"use in a ``return`` statement."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:91
|
|
msgid ""
|
|
"This is the most common way to set the error indicator. The first argument "
|
|
"specifies the exception type; it is normally one of the standard exceptions, "
|
|
"e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference "
|
|
"count. The second argument is an error message; it is decoded from "
|
|
"``'utf-8``'."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:99
|
|
msgid ""
|
|
"This function is similar to :c:func:`PyErr_SetString` but lets you specify "
|
|
"an arbitrary Python object for the \"value\" of the exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:105
|
|
msgid ""
|
|
"This function sets the error indicator and returns *NULL*. *exception* "
|
|
"should be a Python exception class. The *format* and subsequent parameters "
|
|
"help format the error message; they have the same meaning and values as in :"
|
|
"c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:114
|
|
msgid ""
|
|
"Same as :c:func:`PyErr_Format`, but taking a :c:type:`va_list` argument "
|
|
"rather than a variable number of arguments."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:122
|
|
msgid "This is a shorthand for ``PyErr_SetObject(type, Py_None)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:127
|
|
msgid ""
|
|
"This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where "
|
|
"*message* indicates that a built-in operation was invoked with an illegal "
|
|
"argument. It is mostly for internal use."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:134
|
|
msgid ""
|
|
"This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns "
|
|
"*NULL* so an object allocation function can write ``return PyErr_NoMemory();"
|
|
"`` when it runs out of memory."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:143
|
|
msgid ""
|
|
"This is a convenience function to raise an exception when a C library "
|
|
"function has returned an error and set the C variable :c:data:`errno`. It "
|
|
"constructs a tuple object whose first item is the integer :c:data:`errno` "
|
|
"value and whose second item is the corresponding error message (gotten from :"
|
|
"c:func:`strerror`), and then calls ``PyErr_SetObject(type, object)``. On "
|
|
"Unix, when the :c:data:`errno` value is :const:`EINTR`, indicating an "
|
|
"interrupted system call, this calls :c:func:`PyErr_CheckSignals`, and if "
|
|
"that set the error indicator, leaves it set to that. The function always "
|
|
"returns *NULL*, so a wrapper function around a system call can write "
|
|
"``return PyErr_SetFromErrno(type);`` when the system call returns an error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:157
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that "
|
|
"if *filenameObject* is not *NULL*, it is passed to the constructor of *type* "
|
|
"as a third parameter. In the case of :exc:`OSError` exception, this is used "
|
|
"to define the :attr:`filename` attribute of the exception instance."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:166
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a "
|
|
"second filename object, for raising errors when a function that takes two "
|
|
"filenames fails."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:175
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename "
|
|
"is given as a C string. *filename* is decoded from the filesystem encoding "
|
|
"(:func:`os.fsdecode`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:182
|
|
msgid ""
|
|
"This is a convenience function to raise :exc:`WindowsError`. If called with "
|
|
"*ierr* of :c:data:`0`, the error code returned by a call to :c:func:"
|
|
"`GetLastError` is used instead. It calls the Win32 function :c:func:"
|
|
"`FormatMessage` to retrieve the Windows description of error code given by "
|
|
"*ierr* or :c:func:`GetLastError`, then it constructs a tuple object whose "
|
|
"first item is the *ierr* value and whose second item is the corresponding "
|
|
"error message (gotten from :c:func:`FormatMessage`), and then calls "
|
|
"``PyErr_SetObject(PyExc_WindowsError, object)``. This function always "
|
|
"returns *NULL*. Availability: Windows."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:194
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter "
|
|
"specifying the exception type to be raised. Availability: Windows."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:200
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the "
|
|
"filename is given as a C string. *filename* is decoded from the filesystem "
|
|
"encoding (:func:`os.fsdecode`). Availability: Windows."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:207
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an "
|
|
"additional parameter specifying the exception type to be raised. "
|
|
"Availability: Windows."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:214
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`, but "
|
|
"accepts a second filename object. Availability: Windows."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:223
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional "
|
|
"parameter specifying the exception type to be raised. Availability: Windows."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:229
|
|
msgid ""
|
|
"This is a convenience function to raise :exc:`ImportError`. *msg* will be "
|
|
"set as the exception's message string. *name* and *path*, both of which can "
|
|
"be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name`` and "
|
|
"``path`` attributes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:239
|
|
msgid ""
|
|
"Set file, line, and offset information for the current exception. If the "
|
|
"current exception is not a :exc:`SyntaxError`, then it sets additional "
|
|
"attributes, which make the exception printing subsystem think the exception "
|
|
"is a :exc:`SyntaxError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:249
|
|
msgid ""
|
|
"Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string "
|
|
"decoded from the filesystem encoding (:func:`os.fsdecode`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:257
|
|
msgid ""
|
|
"Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is "
|
|
"omitted."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:263
|
|
msgid ""
|
|
"This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, "
|
|
"where *message* indicates that an internal operation (e.g. a Python/C API "
|
|
"function) was invoked with an illegal argument. It is mostly for internal "
|
|
"use."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:270
|
|
msgid "Issuing warnings"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:272
|
|
msgid ""
|
|
"Use these functions to issue warnings from C code. They mirror similar "
|
|
"functions exported by the Python :mod:`warnings` module. They normally "
|
|
"print a warning message to *sys.stderr*; however, it is also possible that "
|
|
"the user has specified that warnings are to be turned into errors, and in "
|
|
"that case they will raise an exception. It is also possible that the "
|
|
"functions raise an exception because of a problem with the warning "
|
|
"machinery. The return value is ``0`` if no exception is raised, or ``-1`` if "
|
|
"an exception is raised. (It is not possible to determine whether a warning "
|
|
"message is actually printed, nor what the reason is for the exception; this "
|
|
"is intentional.) If an exception is raised, the caller should do its normal "
|
|
"exception handling (for example, :c:func:`Py_DECREF` owned references and "
|
|
"return an error value)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:287
|
|
msgid ""
|
|
"Issue a warning message. The *category* argument is a warning category (see "
|
|
"below) or *NULL*; the *message* argument is a UTF-8 encoded string. "
|
|
"*stack_level* is a positive number giving a number of stack frames; the "
|
|
"warning will be issued from the currently executing line of code in that "
|
|
"stack frame. A *stack_level* of 1 is the function calling :c:func:"
|
|
"`PyErr_WarnEx`, 2 is the function above that, and so forth."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:294
|
|
msgid ""
|
|
"Warning categories must be subclasses of :c:data:`Warning`; the default "
|
|
"warning category is :c:data:`RuntimeWarning`. The standard Python warning "
|
|
"categories are available as global variables whose names are ``PyExc_`` "
|
|
"followed by the Python exception name. These have the type :c:type:`PyObject"
|
|
"\\*`; they are all class objects. Their names are :c:data:`PyExc_Warning`, :"
|
|
"c:data:`PyExc_UserWarning`, :c:data:`PyExc_UnicodeWarning`, :c:data:"
|
|
"`PyExc_DeprecationWarning`, :c:data:`PyExc_SyntaxWarning`, :c:data:"
|
|
"`PyExc_RuntimeWarning`, and :c:data:`PyExc_FutureWarning`. :c:data:"
|
|
"`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`; the other "
|
|
"warning categories are subclasses of :c:data:`PyExc_Warning`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:305
|
|
msgid ""
|
|
"For information about warning control, see the documentation for the :mod:"
|
|
"`warnings` module and the :option:`-W` option in the command line "
|
|
"documentation. There is no C API for warning control."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:311
|
|
msgid ""
|
|
"Much like :c:func:`PyErr_SetImportError` but this function allows for "
|
|
"specifying a subclass of :exc:`ImportError` to raise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:319
|
|
msgid ""
|
|
"Issue a warning message with explicit control over all warning attributes. "
|
|
"This is a straightforward wrapper around the Python function :func:`warnings."
|
|
"warn_explicit`, see there for more information. The *module* and *registry* "
|
|
"arguments may be set to *NULL* to get the default effect described there."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:330
|
|
msgid ""
|
|
"Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and "
|
|
"*module* are UTF-8 encoded strings, and *filename* is decoded from the "
|
|
"filesystem encoding (:func:`os.fsdecode`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:337
|
|
msgid ""
|
|
"Function similar to :c:func:`PyErr_WarnEx`, but use :c:func:"
|
|
"`PyUnicode_FromFormat` to format the warning message. *format* is an ASCII-"
|
|
"encoded string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:346
|
|
msgid ""
|
|
"Function similar to :c:func:`PyErr_WarnFormat`, but *category* is :exc:"
|
|
"`ResourceWarning` and pass *source* to :func:`warnings.WarningMessage`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:353
|
|
msgid "Querying the error indicator"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:357
|
|
msgid ""
|
|
"Test whether the error indicator is set. If set, return the exception "
|
|
"*type* (the first argument to the last call to one of the :c:func:`PyErr_Set"
|
|
"\\*` functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. "
|
|
"You do not own a reference to the return value, so you do not need to :c:"
|
|
"func:`Py_DECREF` it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:365
|
|
msgid ""
|
|
"Do not compare the return value to a specific exception; use :c:func:"
|
|
"`PyErr_ExceptionMatches` instead, shown below. (The comparison could easily "
|
|
"fail since the exception may be an instance instead of a class, in the case "
|
|
"of a class exception, or it may be a subclass of the expected exception.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:373
|
|
msgid ""
|
|
"Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This "
|
|
"should only be called when an exception is actually set; a memory access "
|
|
"violation will occur if no exception has been raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:380
|
|
msgid ""
|
|
"Return true if the *given* exception matches the exception type in *exc*. "
|
|
"If *exc* is a class object, this also returns true when *given* is an "
|
|
"instance of a subclass. If *exc* is a tuple, all exception types in the "
|
|
"tuple (and recursively in subtuples) are searched for a match."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:388
|
|
msgid ""
|
|
"Retrieve the error indicator into three variables whose addresses are "
|
|
"passed. If the error indicator is not set, set all three variables to "
|
|
"*NULL*. If it is set, it will be cleared and you own a reference to each "
|
|
"object retrieved. The value and traceback object may be *NULL* even when "
|
|
"the type object is not."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:395
|
|
msgid ""
|
|
"This function is normally only used by code that needs to catch exceptions "
|
|
"or by code that needs to save and restore the error indicator temporarily, e."
|
|
"g.::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:410
|
|
msgid ""
|
|
"Set the error indicator from the three objects. If the error indicator is "
|
|
"already set, it is cleared first. If the objects are *NULL*, the error "
|
|
"indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or "
|
|
"traceback. The exception type should be a class. Do not pass an invalid "
|
|
"exception type or value. (Violating these rules will cause subtle problems "
|
|
"later.) This call takes away a reference to each object: you must own a "
|
|
"reference to each object before the call and after the call you no longer "
|
|
"own these references. (If you don't understand this, don't use this "
|
|
"function. I warned you.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:422
|
|
msgid ""
|
|
"This function is normally only used by code that needs to save and restore "
|
|
"the error indicator temporarily. Use :c:func:`PyErr_Fetch` to save the "
|
|
"current error indicator."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:429
|
|
msgid ""
|
|
"Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` "
|
|
"below can be \"unnormalized\", meaning that ``*exc`` is a class object but "
|
|
"``*val`` is not an instance of the same class. This function can be used "
|
|
"to instantiate the class in that case. If the values are already "
|
|
"normalized, nothing happens. The delayed normalization is implemented to "
|
|
"improve performance."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:437
|
|
msgid ""
|
|
"This function *does not* implicitly set the ``__traceback__`` attribute on "
|
|
"the exception value. If setting the traceback appropriately is desired, the "
|
|
"following additional snippet is needed::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:448
|
|
msgid ""
|
|
"Retrieve the exception info, as known from ``sys.exc_info()``. This refers "
|
|
"to an exception that was *already caught*, not to an exception that was "
|
|
"freshly raised. Returns new references for the three objects, any of which "
|
|
"may be *NULL*. Does not modify the exception info state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:455
|
|
msgid ""
|
|
"This function is not normally used by code that wants to handle exceptions. "
|
|
"Rather, it can be used when code needs to save and restore the exception "
|
|
"state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the "
|
|
"exception state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:465
|
|
msgid ""
|
|
"Set the exception info, as known from ``sys.exc_info()``. This refers to an "
|
|
"exception that was *already caught*, not to an exception that was freshly "
|
|
"raised. This function steals the references of the arguments. To clear the "
|
|
"exception state, pass *NULL* for all three arguments. For general rules "
|
|
"about the three arguments, see :c:func:`PyErr_Restore`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:473
|
|
msgid ""
|
|
"This function is not normally used by code that wants to handle exceptions. "
|
|
"Rather, it can be used when code needs to save and restore the exception "
|
|
"state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception "
|
|
"state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:482
|
|
msgid "Signal Handling"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:492
|
|
msgid ""
|
|
"This function interacts with Python's signal handling. It checks whether a "
|
|
"signal has been sent to the processes and if so, invokes the corresponding "
|
|
"signal handler. If the :mod:`signal` module is supported, this can invoke a "
|
|
"signal handler written in Python. In all cases, the default effect for :"
|
|
"const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an "
|
|
"exception is raised the error indicator is set and the function returns "
|
|
"``-1``; otherwise the function returns ``0``. The error indicator may or "
|
|
"may not be cleared if it was previously set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:508
|
|
msgid ""
|
|
"This function simulates the effect of a :const:`SIGINT` signal arriving --- "
|
|
"the next time :c:func:`PyErr_CheckSignals` is called, :exc:"
|
|
"`KeyboardInterrupt` will be raised. It may be called without holding the "
|
|
"interpreter lock."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:518
|
|
msgid ""
|
|
"This utility function specifies a file descriptor to which the signal number "
|
|
"is written as a single byte whenever a signal is received. *fd* must be non-"
|
|
"blocking. It returns the previous such file descriptor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:522
|
|
msgid ""
|
|
"The value ``-1`` disables the feature; this is the initial state. This is "
|
|
"equivalent to :func:`signal.set_wakeup_fd` in Python, but without any error "
|
|
"checking. *fd* should be a valid file descriptor. The function should only "
|
|
"be called from the main thread."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:527
|
|
msgid "On Windows, the function now also supports socket handles."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:532
|
|
msgid "Exception Classes"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:536
|
|
msgid ""
|
|
"This utility function creates and returns a new exception class. The *name* "
|
|
"argument must be the name of the new exception, a C string of the form "
|
|
"``module.classname``. The *base* and *dict* arguments are normally *NULL*. "
|
|
"This creates a class object derived from :exc:`Exception` (accessible in C "
|
|
"as :c:data:`PyExc_Exception`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:542
|
|
msgid ""
|
|
"The :attr:`__module__` attribute of the new class is set to the first part "
|
|
"(up to the last dot) of the *name* argument, and the class name is set to "
|
|
"the last part (after the last dot). The *base* argument can be used to "
|
|
"specify alternate base classes; it can either be only one class or a tuple "
|
|
"of classes. The *dict* argument can be used to specify a dictionary of class "
|
|
"variables and methods."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:551
|
|
msgid ""
|
|
"Same as :c:func:`PyErr_NewException`, except that the new exception class "
|
|
"can easily be given a docstring: If *doc* is non-*NULL*, it will be used as "
|
|
"the docstring for the exception class."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:559
|
|
msgid "Exception Objects"
|
|
msgstr "Objets Exception"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:563
|
|
msgid ""
|
|
"Return the traceback associated with the exception as a new reference, as "
|
|
"accessible from Python through :attr:`__traceback__`. If there is no "
|
|
"traceback associated, this returns *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:570
|
|
msgid ""
|
|
"Set the traceback associated with the exception to *tb*. Use ``Py_None`` to "
|
|
"clear it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:576
|
|
msgid ""
|
|
"Return the context (another exception instance during whose handling *ex* "
|
|
"was raised) associated with the exception as a new reference, as accessible "
|
|
"from Python through :attr:`__context__`. If there is no context associated, "
|
|
"this returns *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:584
|
|
msgid ""
|
|
"Set the context associated with the exception to *ctx*. Use *NULL* to clear "
|
|
"it. There is no type check to make sure that *ctx* is an exception "
|
|
"instance. This steals a reference to *ctx*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:591
|
|
msgid ""
|
|
"Return the cause (either an exception instance, or :const:`None`, set by "
|
|
"``raise ... from ...``) associated with the exception as a new reference, as "
|
|
"accessible from Python through :attr:`__cause__`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:598
|
|
msgid ""
|
|
"Set the cause associated with the exception to *cause*. Use *NULL* to clear "
|
|
"it. There is no type check to make sure that *cause* is either an exception "
|
|
"instance or :const:`None`. This steals a reference to *cause*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:602
|
|
msgid ""
|
|
":attr:`__suppress_context__` is implicitly set to ``True`` by this function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:608
|
|
msgid "Unicode Exception Objects"
|
|
msgstr "Objets Exception Unicode"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:610
|
|
msgid ""
|
|
"The following functions are used to create and modify Unicode exceptions "
|
|
"from C."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:614
|
|
msgid ""
|
|
"Create a :class:`UnicodeDecodeError` object with the attributes *encoding*, "
|
|
"*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are "
|
|
"UTF-8 encoded strings."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:620
|
|
msgid ""
|
|
"Create a :class:`UnicodeEncodeError` object with the attributes *encoding*, "
|
|
"*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are "
|
|
"UTF-8 encoded strings."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:626
|
|
msgid ""
|
|
"Create a :class:`UnicodeTranslateError` object with the attributes *object*, "
|
|
"*length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:632
|
|
msgid "Return the *encoding* attribute of the given exception object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:638
|
|
msgid "Return the *object* attribute of the given exception object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:644
|
|
msgid ""
|
|
"Get the *start* attribute of the given exception object and place it into *"
|
|
"\\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on "
|
|
"failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:652
|
|
msgid ""
|
|
"Set the *start* attribute of the given exception object to *start*. Return "
|
|
"``0`` on success, ``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:659
|
|
msgid ""
|
|
"Get the *end* attribute of the given exception object and place it into *"
|
|
"\\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on "
|
|
"failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:667
|
|
msgid ""
|
|
"Set the *end* attribute of the given exception object to *end*. Return "
|
|
"``0`` on success, ``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:674
|
|
msgid "Return the *reason* attribute of the given exception object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:680
|
|
msgid ""
|
|
"Set the *reason* attribute of the given exception object to *reason*. "
|
|
"Return ``0`` on success, ``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:685
|
|
msgid "Recursion Control"
|
|
msgstr "Contrôle de la récursion"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:687
|
|
msgid ""
|
|
"These two functions provide a way to perform safe recursive calls at the C "
|
|
"level, both in the core and in extension modules. They are needed if the "
|
|
"recursive code does not necessarily invoke Python code (which tracks its "
|
|
"recursion depth automatically)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:694
|
|
msgid "Marks a point where a recursive C-level call is about to be performed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:696
|
|
msgid ""
|
|
"If :const:`USE_STACKCHECK` is defined, this function checks if the OS stack "
|
|
"overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it sets a :"
|
|
"exc:`MemoryError` and returns a nonzero value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:700
|
|
msgid ""
|
|
"The function then checks if the recursion limit is reached. If this is the "
|
|
"case, a :exc:`RecursionError` is set and a nonzero value is returned. "
|
|
"Otherwise, zero is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:704
|
|
msgid ""
|
|
"*where* should be a string such as ``\" in instance check\"`` to be "
|
|
"concatenated to the :exc:`RecursionError` message caused by the recursion "
|
|
"depth limit."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:710
|
|
msgid ""
|
|
"Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each "
|
|
"*successful* invocation of :c:func:`Py_EnterRecursiveCall`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:713
|
|
msgid ""
|
|
"Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types "
|
|
"requires special recursion handling. In addition to protecting the stack, :"
|
|
"c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent "
|
|
"cycles. The following two functions facilitate this functionality. "
|
|
"Effectively, these are the C equivalent to :func:`reprlib.recursive_repr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:721
|
|
msgid ""
|
|
"Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` "
|
|
"implementation to detect cycles."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:724
|
|
msgid ""
|
|
"If the object has already been processed, the function returns a positive "
|
|
"integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation "
|
|
"should return a string object indicating a cycle. As examples, :class:"
|
|
"`dict` objects return ``{...}`` and :class:`list` objects return ``[...]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:730
|
|
msgid ""
|
|
"The function will return a negative integer if the recursion limit is "
|
|
"reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation "
|
|
"should typically return ``NULL``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:734
|
|
msgid ""
|
|
"Otherwise, the function returns zero and the :c:member:`~PyTypeObject."
|
|
"tp_repr` implementation can continue normally."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:739
|
|
msgid ""
|
|
"Ends a :c:func:`Py_ReprEnter`. Must be called once for each invocation of :"
|
|
"c:func:`Py_ReprEnter` that returns zero."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:746
|
|
msgid "Standard Exceptions"
|
|
msgstr "Exceptions standards"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:748
|
|
msgid ""
|
|
"All standard Python exceptions are available as global variables whose names "
|
|
"are ``PyExc_`` followed by the Python exception name. These have the type :"
|
|
"c:type:`PyObject\\*`; they are all class objects. For completeness, here "
|
|
"are all the variables:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:754 ../Doc/c-api/exceptions.rst:858
|
|
msgid "C Name"
|
|
msgstr "Nom C"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:754
|
|
msgid "Python Name"
|
|
msgstr "Nom Python"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:754 ../Doc/c-api/exceptions.rst:858
|
|
msgid "Notes"
|
|
msgstr "Notes"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:756
|
|
msgid ":c:data:`PyExc_BaseException`"
|
|
msgstr ":c:data:`PyExc_BaseException`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:756
|
|
msgid ":exc:`BaseException`"
|
|
msgstr ":exc:`BaseException`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:756 ../Doc/c-api/exceptions.rst:758
|
|
#: ../Doc/c-api/exceptions.rst:760 ../Doc/c-api/exceptions.rst:762
|
|
#: ../Doc/c-api/exceptions.rst:812
|
|
msgid "\\(1)"
|
|
msgstr "\\(1)"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:758
|
|
msgid ":c:data:`PyExc_Exception`"
|
|
msgstr ":c:data:`PyExc_Exception`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:758
|
|
msgid ":exc:`Exception`"
|
|
msgstr ":exc:`Exception`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:760
|
|
msgid ":c:data:`PyExc_ArithmeticError`"
|
|
msgstr ":c:data:`PyExc_ArithmeticError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:760
|
|
msgid ":exc:`ArithmeticError`"
|
|
msgstr ":exc:`ArithmeticError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:762
|
|
msgid ":c:data:`PyExc_LookupError`"
|
|
msgstr ":c:data:`PyExc_LookupError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:762
|
|
msgid ":exc:`LookupError`"
|
|
msgstr ":exc:`LookupError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:764
|
|
msgid ":c:data:`PyExc_AssertionError`"
|
|
msgstr ":c:data:`PyExc_AssertionError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:764
|
|
msgid ":exc:`AssertionError`"
|
|
msgstr ":exc:`AssertionError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:766
|
|
msgid ":c:data:`PyExc_AttributeError`"
|
|
msgstr ":c:data:`PyExc_AttributeError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:766
|
|
msgid ":exc:`AttributeError`"
|
|
msgstr ":exc:`AttributeError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:768
|
|
msgid ":c:data:`PyExc_BlockingIOError`"
|
|
msgstr ":c:data:`PyExc_BlockingIOError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:768
|
|
msgid ":exc:`BlockingIOError`"
|
|
msgstr ":exc:`BlockingIOError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:770
|
|
msgid ":c:data:`PyExc_BrokenPipeError`"
|
|
msgstr ":c:data:`PyExc_BrokenPipeError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:770
|
|
msgid ":exc:`BrokenPipeError`"
|
|
msgstr ":exc:`BrokenPipeError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:772
|
|
msgid ":c:data:`PyExc_ChildProcessError`"
|
|
msgstr ":c:data:`PyExc_ChildProcessError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:772
|
|
msgid ":exc:`ChildProcessError`"
|
|
msgstr ":exc:`ChildProcessError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:774
|
|
msgid ":c:data:`PyExc_ConnectionError`"
|
|
msgstr ":c:data:`PyExc_ConnectionError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:774
|
|
msgid ":exc:`ConnectionError`"
|
|
msgstr ":exc:`ConnectionError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:776
|
|
msgid ":c:data:`PyExc_ConnectionAbortedError`"
|
|
msgstr ":c:data:`PyExc_ConnectionAbortedError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:776
|
|
msgid ":exc:`ConnectionAbortedError`"
|
|
msgstr ":exc:`ConnectionAbortedError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:778
|
|
msgid ":c:data:`PyExc_ConnectionRefusedError`"
|
|
msgstr ":c:data:`PyExc_ConnectionRefusedError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:778
|
|
msgid ":exc:`ConnectionRefusedError`"
|
|
msgstr ":exc:`ConnectionRefusedError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:780
|
|
msgid ":c:data:`PyExc_ConnectionResetError`"
|
|
msgstr ":c:data:`PyExc_ConnectionResetError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:780
|
|
msgid ":exc:`ConnectionResetError`"
|
|
msgstr ":exc:`ConnectionResetError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:782
|
|
msgid ":c:data:`PyExc_FileExistsError`"
|
|
msgstr ":c:data:`PyExc_FileExistsError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:782
|
|
msgid ":exc:`FileExistsError`"
|
|
msgstr ":exc:`FileExistsError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:784
|
|
msgid ":c:data:`PyExc_FileNotFoundError`"
|
|
msgstr ":c:data:`PyExc_FloatingPointError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:784
|
|
msgid ":exc:`FileNotFoundError`"
|
|
msgstr ":exc:`FileNotFoundError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:786
|
|
msgid ":c:data:`PyExc_EOFError`"
|
|
msgstr ":c:data:`PyExc_EOFError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:786
|
|
msgid ":exc:`EOFError`"
|
|
msgstr ":exc:`EOFError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:788
|
|
msgid ":c:data:`PyExc_FloatingPointError`"
|
|
msgstr ":c:data:`PyExc_FloatingPointError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:788
|
|
msgid ":exc:`FloatingPointError`"
|
|
msgstr ":exc:`FloatingPointError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:790
|
|
msgid ":c:data:`PyExc_ImportError`"
|
|
msgstr ":c:data:`PyExc_ImportError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:790
|
|
msgid ":exc:`ImportError`"
|
|
msgstr ":exc:`ImportError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:792
|
|
msgid ":c:data:`PyExc_ModuleNotFoundError`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:792
|
|
msgid ":exc:`ModuleNotFoundError`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:794
|
|
msgid ":c:data:`PyExc_IndexError`"
|
|
msgstr ":c:data:`PyExc_IndexError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:794
|
|
msgid ":exc:`IndexError`"
|
|
msgstr ":exc:`IndexError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:796
|
|
msgid ":c:data:`PyExc_InterruptedError`"
|
|
msgstr ":c:data:`PyExc_InterruptedError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:796
|
|
msgid ":exc:`InterruptedError`"
|
|
msgstr ":exc:`InterruptedError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:798
|
|
msgid ":c:data:`PyExc_IsADirectoryError`"
|
|
msgstr ":c:data:`PyExc_IsADirectoryError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:798
|
|
msgid ":exc:`IsADirectoryError`"
|
|
msgstr ":exc:`IsADirectoryError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:800
|
|
msgid ":c:data:`PyExc_KeyError`"
|
|
msgstr ":c:data:`PyExc_KeyError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:800
|
|
msgid ":exc:`KeyError`"
|
|
msgstr ":exc:`KeyError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:802
|
|
msgid ":c:data:`PyExc_KeyboardInterrupt`"
|
|
msgstr ":c:data:`PyExc_KeyboardInterrupt`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:802
|
|
msgid ":exc:`KeyboardInterrupt`"
|
|
msgstr ":exc:`KeyboardInterrupt`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:804
|
|
msgid ":c:data:`PyExc_MemoryError`"
|
|
msgstr ":c:data:`PyExc_MemoryError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:804
|
|
msgid ":exc:`MemoryError`"
|
|
msgstr ":exc:`MemoryError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:806
|
|
msgid ":c:data:`PyExc_NameError`"
|
|
msgstr ":c:data:`PyExc_NameError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:806
|
|
msgid ":exc:`NameError`"
|
|
msgstr ":exc:`NameError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:808
|
|
msgid ":c:data:`PyExc_NotADirectoryError`"
|
|
msgstr ":c:data:`PyExc_NotADirectoryError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:808
|
|
msgid ":exc:`NotADirectoryError`"
|
|
msgstr ":exc:`NotADirectoryError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:810
|
|
msgid ":c:data:`PyExc_NotImplementedError`"
|
|
msgstr ":c:data:`PyExc_NotImplementedError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:810
|
|
msgid ":exc:`NotImplementedError`"
|
|
msgstr ":exc:`NotImplementedError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:812
|
|
msgid ":c:data:`PyExc_OSError`"
|
|
msgstr ":c:data:`PyExc_OSError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:812
|
|
msgid ":exc:`OSError`"
|
|
msgstr ":exc:`OSError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:814
|
|
msgid ":c:data:`PyExc_OverflowError`"
|
|
msgstr ":c:data:`PyExc_OverflowError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:814
|
|
msgid ":exc:`OverflowError`"
|
|
msgstr ":exc:`OverflowError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:816
|
|
msgid ":c:data:`PyExc_PermissionError`"
|
|
msgstr ":c:data:`PyExc_PermissionError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:816
|
|
msgid ":exc:`PermissionError`"
|
|
msgstr ":exc:`PermissionError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:818
|
|
msgid ":c:data:`PyExc_ProcessLookupError`"
|
|
msgstr ":c:data:`PyExc_ProcessLookupError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:818
|
|
msgid ":exc:`ProcessLookupError`"
|
|
msgstr ":exc:`ProcessLookupError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:820
|
|
msgid ":c:data:`PyExc_RecursionError`"
|
|
msgstr ":c:data:`PyExc_ReferenceError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:820
|
|
msgid ":exc:`RecursionError`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:822
|
|
msgid ":c:data:`PyExc_ReferenceError`"
|
|
msgstr ":c:data:`PyExc_ReferenceError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:822
|
|
msgid ":exc:`ReferenceError`"
|
|
msgstr ":exc:`ReferenceError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:822
|
|
msgid "\\(2)"
|
|
msgstr "\\(2)"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:824
|
|
msgid ":c:data:`PyExc_RuntimeError`"
|
|
msgstr ":c:data:`PyExc_RuntimeError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:824
|
|
msgid ":exc:`RuntimeError`"
|
|
msgstr ":exc:`RuntimeError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:826
|
|
msgid ":c:data:`PyExc_SyntaxError`"
|
|
msgstr ":c:data:`PyExc_SyntaxError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:826
|
|
msgid ":exc:`SyntaxError`"
|
|
msgstr ":exc:`SyntaxError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:828
|
|
msgid ":c:data:`PyExc_SystemError`"
|
|
msgstr ":c:data:`PyExc_SystemError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:828
|
|
msgid ":exc:`SystemError`"
|
|
msgstr ":exc:`SystemError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:830
|
|
msgid ":c:data:`PyExc_TimeoutError`"
|
|
msgstr ":c:data:`PyExc_ImportError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:830
|
|
msgid ":exc:`TimeoutError`"
|
|
msgstr ":exc:`TimeoutError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:832
|
|
msgid ":c:data:`PyExc_SystemExit`"
|
|
msgstr ":c:data:`PyExc_SystemExit`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:832
|
|
msgid ":exc:`SystemExit`"
|
|
msgstr ":exc:`SystemExit`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:834
|
|
msgid ":c:data:`PyExc_TypeError`"
|
|
msgstr ":c:data:`PyExc_TypeError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:834
|
|
msgid ":exc:`TypeError`"
|
|
msgstr ":exc:`TypeError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:836
|
|
msgid ":c:data:`PyExc_ValueError`"
|
|
msgstr ":c:data:`PyExc_ValueError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:836
|
|
msgid ":exc:`ValueError`"
|
|
msgstr ":exc:`ValueError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:838
|
|
msgid ":c:data:`PyExc_ZeroDivisionError`"
|
|
msgstr ":c:data:`PyExc_ZeroDivisionError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:838
|
|
msgid ":exc:`ZeroDivisionError`"
|
|
msgstr ":exc:`ZeroDivisionError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:841
|
|
msgid ""
|
|
":c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`, :c:data:"
|
|
"`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`, :c:data:"
|
|
"`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`, :c:"
|
|
"data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`, :c:data:"
|
|
"`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`, :c:data:"
|
|
"`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`, :c:data:"
|
|
"`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError` and :c:data:"
|
|
"`PyExc_TimeoutError` were introduced following :pep:`3151`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:851
|
|
msgid ":c:data:`PyExc_RecursionError`."
|
|
msgstr ":c:data:`PyExc_RecursionError`."
|
|
|
|
#: ../Doc/c-api/exceptions.rst:855
|
|
msgid "These are compatibility aliases to :c:data:`PyExc_OSError`:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:860
|
|
msgid ":c:data:`PyExc_EnvironmentError`"
|
|
msgstr ":c:data:`PyExc_EnvironmentError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:862
|
|
msgid ":c:data:`PyExc_IOError`"
|
|
msgstr ":c:data:`PyExc_IOError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:864
|
|
msgid ":c:data:`PyExc_WindowsError`"
|
|
msgstr ":c:data:`PyExc_WindowsError`"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:864
|
|
msgid "\\(3)"
|
|
msgstr "\\(3)"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:867
|
|
msgid "These aliases used to be separate exception types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/exceptions.rst:916
|
|
msgid "Notes:"
|
|
msgstr "Notes : "
|
|
|
|
#: ../Doc/c-api/exceptions.rst:919
|
|
msgid "This is a base class for other standard exceptions."
|
|
msgstr "C'est la classe de base pour les autres exceptions standards"
|
|
|
|
#: ../Doc/c-api/exceptions.rst:922
|
|
msgid "This is the same as :exc:`weakref.ReferenceError`."
|
|
msgstr "Identique à :exc:`weakref.ReferenceError`."
|
|
|
|
#: ../Doc/c-api/exceptions.rst:925
|
|
msgid ""
|
|
"Only defined on Windows; protect code that uses this by testing that the "
|
|
"preprocessor macro ``MS_WINDOWS`` is defined."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/file.rst:6
|
|
msgid "File Objects"
|
|
msgstr "Objets fichiers"
|
|
|
|
#: ../Doc/c-api/file.rst:10
|
|
msgid ""
|
|
"These APIs are a minimal emulation of the Python 2 C API for built-in file "
|
|
"objects, which used to rely on the buffered I/O (:c:type:`FILE\\*`) support "
|
|
"from the C standard library. In Python 3, files and streams use the new :"
|
|
"mod:`io` module, which defines several layers over the low-level unbuffered "
|
|
"I/O of the operating system. The functions described below are convenience "
|
|
"C wrappers over these new APIs, and meant mostly for internal error "
|
|
"reporting in the interpreter; third-party code is advised to access the :mod:"
|
|
"`io` APIs instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/file.rst:22
|
|
msgid ""
|
|
"Create a Python file object from the file descriptor of an already opened "
|
|
"file *fd*. The arguments *name*, *encoding*, *errors* and *newline* can be "
|
|
"*NULL* to use the defaults; *buffering* can be *-1* to use the default. "
|
|
"*name* is ignored and kept for backward compatibility. Return *NULL* on "
|
|
"failure. For a more comprehensive description of the arguments, please refer "
|
|
"to the :func:`io.open` function documentation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/file.rst:31
|
|
msgid ""
|
|
"Since Python streams have their own buffering layer, mixing them with OS-"
|
|
"level file descriptors can produce various issues (such as unexpected "
|
|
"ordering of data)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/file.rst:35
|
|
msgid "Ignore *name* attribute."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/file.rst:41
|
|
msgid ""
|
|
"Return the file descriptor associated with *p* as an :c:type:`int`. If the "
|
|
"object is an integer, its value is returned. If not, the object's :meth:"
|
|
"`~io.IOBase.fileno` method is called if it exists; the method must return an "
|
|
"integer, which is returned as the file descriptor value. Sets an exception "
|
|
"and returns ``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/file.rst:52
|
|
msgid ""
|
|
"Equivalent to ``p.readline([n])``, this function reads one line from the "
|
|
"object *p*. *p* may be a file object or any object with a :meth:`~io.IOBase."
|
|
"readline` method. If *n* is ``0``, exactly one line is read, regardless of "
|
|
"the length of the line. If *n* is greater than ``0``, no more than *n* "
|
|
"bytes will be read from the file; a partial line can be returned. In both "
|
|
"cases, an empty string is returned if the end of the file is reached "
|
|
"immediately. If *n* is less than ``0``, however, one line is read "
|
|
"regardless of length, but :exc:`EOFError` is raised if the end of the file "
|
|
"is reached immediately."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/file.rst:67
|
|
msgid ""
|
|
"Write object *obj* to file object *p*. The only supported flag for *flags* "
|
|
"is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written "
|
|
"instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; "
|
|
"the appropriate exception will be set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/file.rst:75
|
|
msgid ""
|
|
"Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on "
|
|
"failure; the appropriate exception will be set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:6
|
|
msgid "Floating Point Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:13
|
|
msgid ""
|
|
"This subtype of :c:type:`PyObject` represents a Python floating point object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:18
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python floating point "
|
|
"type. This is the same object as :class:`float` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:24
|
|
msgid ""
|
|
"Return true if its argument is a :c:type:`PyFloatObject` or a subtype of :c:"
|
|
"type:`PyFloatObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:30
|
|
msgid ""
|
|
"Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype "
|
|
"of :c:type:`PyFloatObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:36
|
|
msgid ""
|
|
"Create a :c:type:`PyFloatObject` object based on the string value in *str*, "
|
|
"or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:42
|
|
msgid "Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:47
|
|
msgid ""
|
|
"Return a C :c:type:`double` representation of the contents of *pyfloat*. If "
|
|
"*pyfloat* is not a Python floating point object but has a :meth:`__float__` "
|
|
"method, this method will first be called to convert *pyfloat* into a float. "
|
|
"This method returns ``-1.0`` upon failure, so one should call :c:func:"
|
|
"`PyErr_Occurred` to check for errors."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:56
|
|
msgid ""
|
|
"Return a C :c:type:`double` representation of the contents of *pyfloat*, but "
|
|
"without error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:62
|
|
msgid ""
|
|
"Return a structseq instance which contains information about the precision, "
|
|
"minimum and maximum values of a float. It's a thin wrapper around the header "
|
|
"file :file:`float.h`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:69
|
|
msgid ""
|
|
"Return the maximum representable finite float *DBL_MAX* as C :c:type:"
|
|
"`double`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:74
|
|
msgid ""
|
|
"Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/float.rst:78
|
|
msgid ""
|
|
"Clear the float free list. Return the number of items that could not be "
|
|
"freed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:10
|
|
msgid "There are a few functions specific to Python functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:15
|
|
msgid "The C structure used for functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:22
|
|
msgid ""
|
|
"This is an instance of :c:type:`PyTypeObject` and represents the Python "
|
|
"function type. It is exposed to Python programmers as ``types."
|
|
"FunctionType``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:28
|
|
msgid ""
|
|
"Return true if *o* is a function object (has type :c:data:"
|
|
"`PyFunction_Type`). The parameter must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:34
|
|
msgid ""
|
|
"Return a new function object associated with the code object *code*. "
|
|
"*globals* must be a dictionary with the global variables accessible to the "
|
|
"function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:37
|
|
msgid ""
|
|
"The function's docstring and name are retrieved from the code object. "
|
|
"*__module__* is retrieved from *globals*. The argument defaults, annotations "
|
|
"and closure are set to *NULL*. *__qualname__* is set to the same value as "
|
|
"the function's name."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:44
|
|
msgid ""
|
|
"As :c:func:`PyFunction_New`, but also allows setting the function object's "
|
|
"``__qualname__`` attribute. *qualname* should be a unicode object or NULL; "
|
|
"if NULL, the ``__qualname__`` attribute is set to the same value as its "
|
|
"``__name__`` attribute."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:54
|
|
msgid "Return the code object associated with the function object *op*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:59
|
|
msgid "Return the globals dictionary associated with the function object *op*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:64
|
|
msgid ""
|
|
"Return the *__module__* attribute of the function object *op*. This is "
|
|
"normally a string containing the module name, but can be set to any other "
|
|
"object by Python code."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:71
|
|
msgid ""
|
|
"Return the argument default values of the function object *op*. This can be "
|
|
"a tuple of arguments or *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:77
|
|
msgid ""
|
|
"Set the argument default values for the function object *op*. *defaults* "
|
|
"must be *Py_None* or a tuple."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:80 ../Doc/c-api/function.rst:94
|
|
#: ../Doc/c-api/function.rst:108
|
|
msgid "Raises :exc:`SystemError` and returns ``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:85
|
|
msgid ""
|
|
"Return the closure associated with the function object *op*. This can be "
|
|
"*NULL* or a tuple of cell objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:91
|
|
msgid ""
|
|
"Set the closure associated with the function object *op*. *closure* must be "
|
|
"*Py_None* or a tuple of cell objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:99
|
|
msgid ""
|
|
"Return the annotations of the function object *op*. This can be a mutable "
|
|
"dictionary or *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/function.rst:105
|
|
msgid ""
|
|
"Set the annotations for the function object *op*. *annotations* must be a "
|
|
"dictionary or *Py_None*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:6
|
|
msgid "Supporting Cyclic Garbage Collection"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:8
|
|
msgid ""
|
|
"Python's support for detecting and collecting garbage which involves "
|
|
"circular references requires support from object types which are \"containers"
|
|
"\" for other objects which may also be containers. Types which do not store "
|
|
"references to other objects, or which only store references to atomic types "
|
|
"(such as numbers or strings), do not need to provide any explicit support "
|
|
"for garbage collection."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:15
|
|
msgid ""
|
|
"To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of "
|
|
"the type object must include the :const:`Py_TPFLAGS_HAVE_GC` and provide an "
|
|
"implementation of the :c:member:`~PyTypeObject.tp_traverse` handler. If "
|
|
"instances of the type are mutable, a :c:member:`~PyTypeObject.tp_clear` "
|
|
"implementation must also be provided."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:24
|
|
msgid ""
|
|
"Objects with a type with this flag set must conform with the rules "
|
|
"documented here. For convenience these objects will be referred to as "
|
|
"container objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:28
|
|
msgid "Constructors for container types must conform to two rules:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:30
|
|
msgid ""
|
|
"The memory for the object must be allocated using :c:func:`PyObject_GC_New` "
|
|
"or :c:func:`PyObject_GC_NewVar`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:33
|
|
msgid ""
|
|
"Once all the fields which may contain references to other containers are "
|
|
"initialized, it must call :c:func:`PyObject_GC_Track`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:39
|
|
msgid ""
|
|
"Analogous to :c:func:`PyObject_New` but for container objects with the :"
|
|
"const:`Py_TPFLAGS_HAVE_GC` flag set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:45
|
|
msgid ""
|
|
"Analogous to :c:func:`PyObject_NewVar` but for container objects with the :"
|
|
"const:`Py_TPFLAGS_HAVE_GC` flag set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:51
|
|
msgid ""
|
|
"Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the "
|
|
"resized object or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:57
|
|
msgid ""
|
|
"Adds the object *op* to the set of container objects tracked by the "
|
|
"collector. The collector can run at unexpected times so objects must be "
|
|
"valid while being tracked. This should be called once all the fields "
|
|
"followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, "
|
|
"usually near the end of the constructor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:66
|
|
msgid ""
|
|
"A macro version of :c:func:`PyObject_GC_Track`. It should not be used for "
|
|
"extension modules."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:69
|
|
msgid ""
|
|
"Similarly, the deallocator for the object must conform to a similar pair of "
|
|
"rules:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:72
|
|
msgid ""
|
|
"Before fields which refer to other containers are invalidated, :c:func:"
|
|
"`PyObject_GC_UnTrack` must be called."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:75
|
|
msgid ""
|
|
"The object's memory must be deallocated using :c:func:`PyObject_GC_Del`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:80
|
|
msgid ""
|
|
"Releases memory allocated to an object using :c:func:`PyObject_GC_New` or :c:"
|
|
"func:`PyObject_GC_NewVar`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:86
|
|
msgid ""
|
|
"Remove the object *op* from the set of container objects tracked by the "
|
|
"collector. Note that :c:func:`PyObject_GC_Track` can be called again on "
|
|
"this object to add it back to the set of tracked objects. The deallocator (:"
|
|
"c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object "
|
|
"before any of the fields used by the :c:member:`~PyTypeObject.tp_traverse` "
|
|
"handler become invalid."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:95
|
|
msgid ""
|
|
"A macro version of :c:func:`PyObject_GC_UnTrack`. It should not be used for "
|
|
"extension modules."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:98
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function "
|
|
"parameter of this type:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:103
|
|
msgid ""
|
|
"Type of the visitor function passed to the :c:member:`~PyTypeObject."
|
|
"tp_traverse` handler. The function should be called with an object to "
|
|
"traverse as *object* and the third parameter to the :c:member:`~PyTypeObject."
|
|
"tp_traverse` handler as *arg*. The Python core uses several visitor "
|
|
"functions to implement cyclic garbage detection; it's not expected that "
|
|
"users will need to write their own visitor functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:110
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_traverse` handler must have the following "
|
|
"type:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:115
|
|
msgid ""
|
|
"Traversal function for a container object. Implementations must call the "
|
|
"*visit* function for each object directly contained by *self*, with the "
|
|
"parameters to *visit* being the contained object and the *arg* value passed "
|
|
"to the handler. The *visit* function must not be called with a *NULL* "
|
|
"object argument. If *visit* returns a non-zero value that value should be "
|
|
"returned immediately."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:122
|
|
msgid ""
|
|
"To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:"
|
|
"func:`Py_VISIT` macro is provided. In order to use this macro, the :c:"
|
|
"member:`~PyTypeObject.tp_traverse` implementation must name its arguments "
|
|
"exactly *visit* and *arg*:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:129
|
|
msgid ""
|
|
"If *o* is not *NULL*, call the *visit* callback, with arguments *o* and "
|
|
"*arg*. If *visit* returns a non-zero value, then return it. Using this "
|
|
"macro, :c:member:`~PyTypeObject.tp_traverse` handlers look like::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:142
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:"
|
|
"`inquiry` type, or *NULL* if the object is immutable."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gcsupport.rst:148
|
|
msgid ""
|
|
"Drop references that may have created reference cycles. Immutable objects "
|
|
"do not have to define this method since they can never directly create "
|
|
"reference cycles. Note that the object must still be valid after calling "
|
|
"this method (don't just call :c:func:`Py_DECREF` on a reference). The "
|
|
"collector will call this method if it detects that this object is involved "
|
|
"in a reference cycle."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gen.rst:6
|
|
msgid "Generator Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gen.rst:8
|
|
msgid ""
|
|
"Generator objects are what Python uses to implement generator iterators. "
|
|
"They are normally created by iterating over a function that yields values, "
|
|
"rather than explicitly calling :c:func:`PyGen_New` or :c:func:"
|
|
"`PyGen_NewWithQualName`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gen.rst:15
|
|
msgid "The C structure used for generator objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gen.rst:20
|
|
msgid "The type object corresponding to generator objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gen.rst:25
|
|
msgid "Return true if *ob* is a generator object; *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gen.rst:30
|
|
msgid "Return true if *ob*'s type is *PyGen_Type*; *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gen.rst:35
|
|
msgid ""
|
|
"Create and return a new generator object based on the *frame* object. A "
|
|
"reference to *frame* is stolen by this function. The argument must not be "
|
|
"*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/gen.rst:41
|
|
msgid ""
|
|
"Create and return a new generator object based on the *frame* object, with "
|
|
"``__name__`` and ``__qualname__`` set to *name* and *qualname*. A reference "
|
|
"to *frame* is stolen by this function. The *frame* argument must not be "
|
|
"*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:6
|
|
msgid "Importing Modules"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:16
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below, "
|
|
"leaving the *globals* and *locals* arguments set to *NULL* and *level* set "
|
|
"to 0. When the *name* argument contains a dot (when it specifies a "
|
|
"submodule of a package), the *fromlist* argument is set to the list "
|
|
"``['*']`` so that the return value is the named module rather than the top-"
|
|
"level package containing it as would otherwise be the case. (Unfortunately, "
|
|
"this has an additional side effect when *name* in fact specifies a "
|
|
"subpackage instead of a submodule: the submodules specified in the package's "
|
|
"``__all__`` variable are loaded.) Return a new reference to the imported "
|
|
"module, or *NULL* with an exception set on failure. A failing import of a "
|
|
"module doesn't leave the module in :data:`sys.modules`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:28 ../Doc/c-api/import.rst:89
|
|
msgid "This function always uses absolute imports."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:33
|
|
msgid "This function is a deprecated alias of :c:func:`PyImport_ImportModule`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:35
|
|
msgid ""
|
|
"This function used to fail immediately when the import lock was held by "
|
|
"another thread. In Python 3.3 though, the locking scheme switched to per-"
|
|
"module locks for most purposes, so this function's special behaviour isn't "
|
|
"needed anymore."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:46
|
|
msgid ""
|
|
"Import a module. This is best described by referring to the built-in Python "
|
|
"function :func:`__import__`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:49 ../Doc/c-api/import.rst:65
|
|
msgid ""
|
|
"The return value is a new reference to the imported module or top-level "
|
|
"package, or *NULL* with an exception set on failure. Like for :func:"
|
|
"`__import__`, the return value when a submodule of a package was requested "
|
|
"is normally the top-level package, unless a non-empty *fromlist* was given."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:55
|
|
msgid ""
|
|
"Failing imports remove incomplete module objects, like with :c:func:"
|
|
"`PyImport_ImportModule`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:61
|
|
msgid ""
|
|
"Import a module. This is best described by referring to the built-in Python "
|
|
"function :func:`__import__`, as the standard :func:`__import__` function "
|
|
"calls this function directly."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:75
|
|
msgid ""
|
|
"Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is a "
|
|
"UTF-8 encoded string instead of a Unicode object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:78
|
|
msgid "Negative values for *level* are no longer accepted."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:83
|
|
msgid ""
|
|
"This is a higher-level interface that calls the current \"import hook "
|
|
"function\" (with an explicit *level* of 0, meaning absolute import). It "
|
|
"invokes the :func:`__import__` function from the ``__builtins__`` of the "
|
|
"current globals. This means that the import is done using whatever import "
|
|
"hooks are installed in the current environment."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:94
|
|
msgid ""
|
|
"Reload a module. Return a new reference to the reloaded module, or *NULL* "
|
|
"with an exception set on failure (the module still exists in this case)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:100
|
|
msgid ""
|
|
"Return the module object corresponding to a module name. The *name* "
|
|
"argument may be of the form ``package.module``. First check the modules "
|
|
"dictionary if there's one there, and if not, create a new one and insert it "
|
|
"in the modules dictionary. Return *NULL* with an exception set on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:107
|
|
msgid ""
|
|
"This function does not load or import the module; if the module wasn't "
|
|
"already loaded, you will get an empty module object. Use :c:func:"
|
|
"`PyImport_ImportModule` or one of its variants to import a module. Package "
|
|
"structures implied by a dotted name for *name* are not created if not "
|
|
"already present."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:117
|
|
msgid ""
|
|
"Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8 "
|
|
"encoded string instead of a Unicode object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:125
|
|
msgid ""
|
|
"Given a module name (possibly of the form ``package.module``) and a code "
|
|
"object read from a Python bytecode file or obtained from the built-in "
|
|
"function :func:`compile`, load the module. Return a new reference to the "
|
|
"module object, or *NULL* with an exception set if an error occurred. *name* "
|
|
"is removed from :attr:`sys.modules` in error cases, even if *name* was "
|
|
"already in :attr:`sys.modules` on entry to :c:func:"
|
|
"`PyImport_ExecCodeModule`. Leaving incompletely initialized modules in :"
|
|
"attr:`sys.modules` is dangerous, as imports of such modules have no way to "
|
|
"know that the module object is an unknown (and probably damaged with respect "
|
|
"to the module author's intents) state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:135
|
|
msgid ""
|
|
"The module's :attr:`__spec__` and :attr:`__loader__` will be set, if not set "
|
|
"already, with the appropriate values. The spec's loader will be set to the "
|
|
"module's ``__loader__`` (if set) and to an instance of :class:"
|
|
"`SourceFileLoader` otherwise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:140
|
|
msgid ""
|
|
"The module's :attr:`__file__` attribute will be set to the code object's :c:"
|
|
"member:`co_filename`. If applicable, :attr:`__cached__` will also be set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:144
|
|
msgid ""
|
|
"This function will reload the module if it was already imported. See :c:"
|
|
"func:`PyImport_ReloadModule` for the intended way to reload a module."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:147
|
|
msgid ""
|
|
"If *name* points to a dotted name of the form ``package.module``, any "
|
|
"package structures not already created will still not be created."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:150
|
|
msgid ""
|
|
"See also :c:func:`PyImport_ExecCodeModuleEx` and :c:func:"
|
|
"`PyImport_ExecCodeModuleWithPathnames`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:156
|
|
msgid ""
|
|
"Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute "
|
|
"of the module object is set to *pathname* if it is non-``NULL``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:159
|
|
msgid "See also :c:func:`PyImport_ExecCodeModuleWithPathnames`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:164
|
|
msgid ""
|
|
"Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__` "
|
|
"attribute of the module object is set to *cpathname* if it is non-``NULL``. "
|
|
"Of the three functions, this is the preferred one to use."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:173
|
|
msgid ""
|
|
"Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and "
|
|
"*cpathname* are UTF-8 encoded strings. Attempts are also made to figure out "
|
|
"what the value for *pathname* should be from *cpathname* if the former is "
|
|
"set to ``NULL``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:179
|
|
msgid ""
|
|
"Uses :func:`imp.source_from_cache()` in calculating the source path if only "
|
|
"the bytecode path is provided."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:186
|
|
msgid ""
|
|
"Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` "
|
|
"file). The magic number should be present in the first four bytes of the "
|
|
"bytecode file, in little-endian byte order. Returns -1 on error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:190
|
|
msgid "Return value of -1 upon failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:196
|
|
msgid ""
|
|
"Return the magic tag string for :pep:`3147` format Python bytecode file "
|
|
"names. Keep in mind that the value at ``sys.implementation.cache_tag`` is "
|
|
"authoritative and should be used instead of this function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:204
|
|
msgid ""
|
|
"Return the dictionary used for the module administration (a.k.a. ``sys."
|
|
"modules``). Note that this is a per-interpreter variable."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:210
|
|
msgid ""
|
|
"Return a finder object for a :data:`sys.path`/:attr:`pkg.__path__` item "
|
|
"*path*, possibly by fetching it from the :data:`sys.path_importer_cache` "
|
|
"dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook "
|
|
"is found that can handle the path item. Return ``None`` if no hook could; "
|
|
"this tells our caller that the :term:`path based finder` could not find a "
|
|
"finder for this path item. Cache the result in :data:`sys."
|
|
"path_importer_cache`. Return a new reference to the finder object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:221
|
|
msgid "Initialize the import mechanism. For internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:226
|
|
msgid "Empty the module table. For internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:231
|
|
msgid "Finalize the import mechanism. For internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:236
|
|
msgid "For internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:241
|
|
msgid ""
|
|
"Load a frozen module named *name*. Return ``1`` for success, ``0`` if the "
|
|
"module is not found, and ``-1`` with an exception set if the initialization "
|
|
"failed. To access the imported module on a successful load, use :c:func:"
|
|
"`PyImport_ImportModule`. (Note the misnomer --- this function would reload "
|
|
"the module if it was already imported.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:249
|
|
msgid "The ``__file__`` attribute is no longer set on the module."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:255
|
|
msgid ""
|
|
"Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a "
|
|
"UTF-8 encoded string instead of a Unicode object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:263
|
|
msgid ""
|
|
"This is the structure type definition for frozen module descriptors, as "
|
|
"generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the "
|
|
"Python source distribution). Its definition, found in :file:`Include/import."
|
|
"h`, is::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:277
|
|
msgid ""
|
|
"This pointer is initialized to point to an array of :c:type:`struct _frozen` "
|
|
"records, terminated by one whose members are all *NULL* or zero. When a "
|
|
"frozen module is imported, it is searched in this table. Third-party code "
|
|
"could play tricks with this to provide a dynamically created collection of "
|
|
"frozen modules."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:285
|
|
msgid ""
|
|
"Add a single module to the existing table of built-in modules. This is a "
|
|
"convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning "
|
|
"``-1`` if the table could not be extended. The new module can be imported "
|
|
"by the name *name*, and uses the function *initfunc* as the initialization "
|
|
"function called on the first attempted import. This should be called "
|
|
"before :c:func:`Py_Initialize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:295
|
|
msgid ""
|
|
"Structure describing a single entry in the list of built-in modules. Each "
|
|
"of these structures gives the name and initialization function for a module "
|
|
"built into the interpreter. The name is an ASCII encoded string. Programs "
|
|
"which embed Python may use an array of these structures in conjunction with :"
|
|
"c:func:`PyImport_ExtendInittab` to provide additional built-in modules. The "
|
|
"structure is defined in :file:`Include/import.h` as::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/import.rst:310
|
|
msgid ""
|
|
"Add a collection of modules to the table of built-in modules. The *newtab* "
|
|
"array must end with a sentinel entry which contains *NULL* for the :attr:"
|
|
"`name` field; failure to provide the sentinel value can result in a memory "
|
|
"fault. Returns ``0`` on success or ``-1`` if insufficient memory could be "
|
|
"allocated to extend the internal table. In the event of failure, no modules "
|
|
"are added to the internal table. This should be called before :c:func:"
|
|
"`Py_Initialize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/index.rst:5
|
|
msgid "Python/C API Reference Manual"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/index.rst:7
|
|
msgid ""
|
|
"This manual documents the API used by C and C++ programmers who want to "
|
|
"write extension modules or embed Python. It is a companion to :ref:"
|
|
"`extending-index`, which describes the general principles of extension "
|
|
"writing but does not document the API functions in detail."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:8
|
|
msgid "Initialization, Finalization, and Threads"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:12
|
|
msgid "Initializing and finalizing the interpreter"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:30
|
|
msgid ""
|
|
"Initialize the Python interpreter. In an application embedding Python, "
|
|
"this should be called before using any other Python/C API functions; with "
|
|
"the exception of :c:func:`Py_SetProgramName`, :c:func:`Py_SetPythonHome` "
|
|
"and :c:func:`Py_SetPath`. This initializes the table of loaded modules "
|
|
"(``sys.modules``), and creates the fundamental modules :mod:`builtins`, :mod:"
|
|
"`__main__` and :mod:`sys`. It also initializes the module search path "
|
|
"(``sys.path``). It does not set ``sys.argv``; use :c:func:`PySys_SetArgvEx` "
|
|
"for that. This is a no-op when called for a second time (without calling :c:"
|
|
"func:`Py_FinalizeEx` first). There is no return value; it is a fatal error "
|
|
"if the initialization fails."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:41
|
|
msgid ""
|
|
"On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which "
|
|
"will also affect non-Python uses of the console using the C Runtime."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:47
|
|
msgid ""
|
|
"This function works like :c:func:`Py_Initialize` if *initsigs* is 1. If "
|
|
"*initsigs* is 0, it skips initialization registration of signal handlers, "
|
|
"which might be useful when Python is embedded."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:54
|
|
msgid ""
|
|
"Return true (nonzero) when the Python interpreter has been initialized, "
|
|
"false (zero) if not. After :c:func:`Py_FinalizeEx` is called, this returns "
|
|
"false until :c:func:`Py_Initialize` is called again."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:61
|
|
msgid ""
|
|
"Undo all initializations made by :c:func:`Py_Initialize` and subsequent use "
|
|
"of Python/C API functions, and destroy all sub-interpreters (see :c:func:"
|
|
"`Py_NewInterpreter` below) that were created and not yet destroyed since the "
|
|
"last call to :c:func:`Py_Initialize`. Ideally, this frees all memory "
|
|
"allocated by the Python interpreter. This is a no-op when called for a "
|
|
"second time (without calling :c:func:`Py_Initialize` again first). Normally "
|
|
"the return value is 0. If there were errors during finalization (flushing "
|
|
"buffered data), -1 is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:70
|
|
msgid ""
|
|
"This function is provided for a number of reasons. An embedding application "
|
|
"might want to restart Python without having to restart the application "
|
|
"itself. An application that has loaded the Python interpreter from a "
|
|
"dynamically loadable library (or DLL) might want to free all memory "
|
|
"allocated by Python before unloading the DLL. During a hunt for memory leaks "
|
|
"in an application a developer might want to free all memory allocated by "
|
|
"Python before exiting from the application."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:78
|
|
msgid ""
|
|
"**Bugs and caveats:** The destruction of modules and objects in modules is "
|
|
"done in random order; this may cause destructors (:meth:`__del__` methods) "
|
|
"to fail when they depend on other objects (even functions) or modules. "
|
|
"Dynamically loaded extension modules loaded by Python are not unloaded. "
|
|
"Small amounts of memory allocated by the Python interpreter may not be freed "
|
|
"(if you find a leak, please report it). Memory tied up in circular "
|
|
"references between objects is not freed. Some memory allocated by extension "
|
|
"modules may not be freed. Some extensions may not work properly if their "
|
|
"initialization routine is called more than once; this can happen if an "
|
|
"application calls :c:func:`Py_Initialize` and :c:func:`Py_FinalizeEx` more "
|
|
"than once."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:94
|
|
msgid ""
|
|
"This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that "
|
|
"disregards the return value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:99
|
|
msgid "Process-wide parameters"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:109
|
|
msgid ""
|
|
"This function should be called before :c:func:`Py_Initialize`, if it is "
|
|
"called at all. It specifies which encoding and error handling to use with "
|
|
"standard IO, with the same meanings as in :func:`str.encode`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:113
|
|
msgid ""
|
|
"It overrides :envvar:`PYTHONIOENCODING` values, and allows embedding code to "
|
|
"control IO encoding when the environment variable does not work."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:116
|
|
msgid ""
|
|
"``encoding`` and/or ``errors`` may be NULL to use :envvar:`PYTHONIOENCODING` "
|
|
"and/or default values (depending on other settings)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:120
|
|
msgid ""
|
|
"Note that :data:`sys.stderr` always uses the \"backslashreplace\" error "
|
|
"handler, regardless of this (or any other) setting."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:123
|
|
msgid ""
|
|
"If :c:func:`Py_FinalizeEx` is called, this function will need to be called "
|
|
"again in order to affect subsequent calls to :c:func:`Py_Initialize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:126
|
|
msgid ""
|
|
"Returns 0 if successful, a nonzero value on error (e.g. calling after the "
|
|
"interpreter has already been initialized)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:139
|
|
msgid ""
|
|
"This function should be called before :c:func:`Py_Initialize` is called for "
|
|
"the first time, if it is called at all. It tells the interpreter the value "
|
|
"of the ``argv[0]`` argument to the :c:func:`main` function of the program "
|
|
"(converted to wide characters). This is used by :c:func:`Py_GetPath` and "
|
|
"some other functions below to find the Python run-time libraries relative to "
|
|
"the interpreter executable. The default value is ``'python'``. The "
|
|
"argument should point to a zero-terminated wide character string in static "
|
|
"storage whose contents will not change for the duration of the program's "
|
|
"execution. No code in the Python interpreter will change the contents of "
|
|
"this storage."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:150 ../Doc/c-api/init.rst:264
|
|
#: ../Doc/c-api/init.rst:366 ../Doc/c-api/init.rst:393
|
|
#: ../Doc/c-api/init.rst:410
|
|
msgid ""
|
|
"Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a :c:type:"
|
|
"`wchar_*` string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:158
|
|
msgid ""
|
|
"Return the program name set with :c:func:`Py_SetProgramName`, or the "
|
|
"default. The returned string points into static storage; the caller should "
|
|
"not modify its value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:165
|
|
msgid ""
|
|
"Return the *prefix* for installed platform-independent files. This is "
|
|
"derived through a number of complicated rules from the program name set "
|
|
"with :c:func:`Py_SetProgramName` and some environment variables; for "
|
|
"example, if the program name is ``'/usr/local/bin/python'``, the prefix is "
|
|
"``'/usr/local'``. The returned string points into static storage; the caller "
|
|
"should not modify its value. This corresponds to the :makevar:`prefix` "
|
|
"variable in the top-level :file:`Makefile` and the ``--prefix`` argument to "
|
|
"the :program:`configure` script at build time. The value is available to "
|
|
"Python code as ``sys.prefix``. It is only useful on Unix. See also the next "
|
|
"function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:178
|
|
msgid ""
|
|
"Return the *exec-prefix* for installed platform-*dependent* files. This is "
|
|
"derived through a number of complicated rules from the program name set "
|
|
"with :c:func:`Py_SetProgramName` and some environment variables; for "
|
|
"example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix "
|
|
"is ``'/usr/local'``. The returned string points into static storage; the "
|
|
"caller should not modify its value. This corresponds to the :makevar:"
|
|
"`exec_prefix` variable in the top-level :file:`Makefile` and the ``--exec-"
|
|
"prefix`` argument to the :program:`configure` script at build time. The "
|
|
"value is available to Python code as ``sys.exec_prefix``. It is only useful "
|
|
"on Unix."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:188
|
|
msgid ""
|
|
"Background: The exec-prefix differs from the prefix when platform dependent "
|
|
"files (such as executables and shared libraries) are installed in a "
|
|
"different directory tree. In a typical installation, platform dependent "
|
|
"files may be installed in the :file:`/usr/local/plat` subtree while platform "
|
|
"independent may be installed in :file:`/usr/local`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:194
|
|
msgid ""
|
|
"Generally speaking, a platform is a combination of hardware and software "
|
|
"families, e.g. Sparc machines running the Solaris 2.x operating system are "
|
|
"considered the same platform, but Intel machines running Solaris 2.x are "
|
|
"another platform, and Intel machines running Linux are yet another "
|
|
"platform. Different major revisions of the same operating system generally "
|
|
"also form different platforms. Non-Unix operating systems are a different "
|
|
"story; the installation strategies on those systems are so different that "
|
|
"the prefix and exec-prefix are meaningless, and set to the empty string. "
|
|
"Note that compiled Python bytecode files are platform independent (but not "
|
|
"independent from the Python version by which they were compiled!)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:205
|
|
msgid ""
|
|
"System administrators will know how to configure the :program:`mount` or :"
|
|
"program:`automount` programs to share :file:`/usr/local` between platforms "
|
|
"while having :file:`/usr/local/plat` be a different filesystem for each "
|
|
"platform."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:217
|
|
msgid ""
|
|
"Return the full program name of the Python executable; this is computed as "
|
|
"a side-effect of deriving the default module search path from the program "
|
|
"name (set by :c:func:`Py_SetProgramName` above). The returned string points "
|
|
"into static storage; the caller should not modify its value. The value is "
|
|
"available to Python code as ``sys.executable``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:231
|
|
msgid ""
|
|
"Return the default module search path; this is computed from the program "
|
|
"name (set by :c:func:`Py_SetProgramName` above) and some environment "
|
|
"variables. The returned string consists of a series of directory names "
|
|
"separated by a platform dependent delimiter character. The delimiter "
|
|
"character is ``':'`` on Unix and Mac OS X, ``';'`` on Windows. The returned "
|
|
"string points into static storage; the caller should not modify its value. "
|
|
"The list :data:`sys.path` is initialized with this value on interpreter "
|
|
"startup; it can be (and usually is) modified later to change the search path "
|
|
"for loading modules."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:251
|
|
msgid ""
|
|
"Set the default module search path. If this function is called before :c:"
|
|
"func:`Py_Initialize`, then :c:func:`Py_GetPath` won't attempt to compute a "
|
|
"default search path but uses the one provided instead. This is useful if "
|
|
"Python is embedded by an application that has full knowledge of the location "
|
|
"of all modules. The path components should be separated by the platform "
|
|
"dependent delimiter character, which is ``':'`` on Unix and Mac OS X, "
|
|
"``';'`` on Windows."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:259
|
|
msgid ""
|
|
"This also causes :data:`sys.executable` to be set only to the raw program "
|
|
"name (see :c:func:`Py_SetProgramName`) and for :data:`sys.prefix` and :data:"
|
|
"`sys.exec_prefix` to be empty. It is up to the caller to modify these if "
|
|
"required after calling :c:func:`Py_Initialize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:267
|
|
msgid ""
|
|
"The path argument is copied internally, so the caller may free it after the "
|
|
"call completes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:273
|
|
msgid ""
|
|
"Return the version of this Python interpreter. This is a string that looks "
|
|
"something like ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:280
|
|
msgid ""
|
|
"The first word (up to the first space character) is the current Python "
|
|
"version; the first three characters are the major and minor version "
|
|
"separated by a period. The returned string points into static storage; the "
|
|
"caller should not modify its value. The value is available to Python code "
|
|
"as :data:`sys.version`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:290
|
|
msgid ""
|
|
"Return the platform identifier for the current platform. On Unix, this is "
|
|
"formed from the \"official\" name of the operating system, converted to "
|
|
"lower case, followed by the major revision number; e.g., for Solaris 2.x, "
|
|
"which is also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, "
|
|
"it is ``'darwin'``. On Windows, it is ``'win'``. The returned string "
|
|
"points into static storage; the caller should not modify its value. The "
|
|
"value is available to Python code as ``sys.platform``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:301
|
|
msgid ""
|
|
"Return the official copyright string for the current Python version, for "
|
|
"example"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:303
|
|
msgid "``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:307
|
|
msgid ""
|
|
"The returned string points into static storage; the caller should not modify "
|
|
"its value. The value is available to Python code as ``sys.copyright``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:313
|
|
msgid ""
|
|
"Return an indication of the compiler used to build the current Python "
|
|
"version, in square brackets, for example::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:320 ../Doc/c-api/init.rst:334
|
|
msgid ""
|
|
"The returned string points into static storage; the caller should not modify "
|
|
"its value. The value is available to Python code as part of the variable "
|
|
"``sys.version``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:327
|
|
msgid ""
|
|
"Return information about the sequence number and build date and time of the "
|
|
"current Python interpreter instance, for example ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:346
|
|
msgid ""
|
|
"Set :data:`sys.argv` based on *argc* and *argv*. These parameters are "
|
|
"similar to those passed to the program's :c:func:`main` function with the "
|
|
"difference that the first entry should refer to the script file to be "
|
|
"executed rather than the executable hosting the Python interpreter. If "
|
|
"there isn't a script that will be run, the first entry in *argv* can be an "
|
|
"empty string. If this function fails to initialize :data:`sys.argv`, a "
|
|
"fatal condition is signalled using :c:func:`Py_FatalError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:354
|
|
msgid ""
|
|
"If *updatepath* is zero, this is all the function does. If *updatepath* is "
|
|
"non-zero, the function also modifies :data:`sys.path` according to the "
|
|
"following algorithm:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:358
|
|
msgid ""
|
|
"If the name of an existing script is passed in ``argv[0]``, the absolute "
|
|
"path of the directory where the script is located is prepended to :data:`sys."
|
|
"path`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:361
|
|
msgid ""
|
|
"Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point to an "
|
|
"existing file name), an empty string is prepended to :data:`sys.path`, which "
|
|
"is the same as prepending the current working directory (``\".\"``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:370
|
|
msgid ""
|
|
"It is recommended that applications embedding the Python interpreter for "
|
|
"purposes other than executing a single script pass 0 as *updatepath*, and "
|
|
"update :data:`sys.path` themselves if desired. See `CVE-2008-5983 <https://"
|
|
"cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:375
|
|
msgid ""
|
|
"On versions before 3.1.3, you can achieve the same effect by manually "
|
|
"popping the first :data:`sys.path` element after having called :c:func:"
|
|
"`PySys_SetArgv`, for example using::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:389
|
|
msgid ""
|
|
"This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to "
|
|
"1 unless the :program:`python` interpreter was started with the :option:`-I`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:396
|
|
msgid "The *updatepath* value depends on :option:`-I`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:401
|
|
msgid ""
|
|
"Set the default \"home\" directory, that is, the location of the standard "
|
|
"Python libraries. See :envvar:`PYTHONHOME` for the meaning of the argument "
|
|
"string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:405
|
|
msgid ""
|
|
"The argument should point to a zero-terminated character string in static "
|
|
"storage whose contents will not change for the duration of the program's "
|
|
"execution. No code in the Python interpreter will change the contents of "
|
|
"this storage."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:416
|
|
msgid ""
|
|
"Return the default \"home\", that is, the value set by a previous call to :c:"
|
|
"func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME` "
|
|
"environment variable if it is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:424
|
|
msgid "Thread State and the Global Interpreter Lock"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:431
|
|
msgid ""
|
|
"The Python interpreter is not fully thread-safe. In order to support multi-"
|
|
"threaded Python programs, there's a global lock, called the :term:`global "
|
|
"interpreter lock` or :term:`GIL`, that must be held by the current thread "
|
|
"before it can safely access Python objects. Without the lock, even the "
|
|
"simplest operations could cause problems in a multi-threaded program: for "
|
|
"example, when two threads simultaneously increment the reference count of "
|
|
"the same object, the reference count could end up being incremented only "
|
|
"once instead of twice."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:441
|
|
msgid ""
|
|
"Therefore, the rule exists that only the thread that has acquired the :term:"
|
|
"`GIL` may operate on Python objects or call Python/C API functions. In order "
|
|
"to emulate concurrency of execution, the interpreter regularly tries to "
|
|
"switch threads (see :func:`sys.setswitchinterval`). The lock is also "
|
|
"released around potentially blocking I/O operations like reading or writing "
|
|
"a file, so that other Python threads can run in the meantime."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:452
|
|
msgid ""
|
|
"The Python interpreter keeps some thread-specific bookkeeping information "
|
|
"inside a data structure called :c:type:`PyThreadState`. There's also one "
|
|
"global variable pointing to the current :c:type:`PyThreadState`: it can be "
|
|
"retrieved using :c:func:`PyThreadState_Get`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:458
|
|
msgid "Releasing the GIL from extension code"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:460
|
|
msgid ""
|
|
"Most extension code manipulating the :term:`GIL` has the following simple "
|
|
"structure::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:469
|
|
msgid "This is so common that a pair of macros exists to simplify it::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:479
|
|
msgid ""
|
|
"The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a "
|
|
"hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the "
|
|
"block. These two macros are still available when Python is compiled without "
|
|
"thread support (they simply have an empty expansion)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:484
|
|
msgid ""
|
|
"When thread support is enabled, the block above expands to the following "
|
|
"code::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:496
|
|
msgid ""
|
|
"Here is how these functions work: the global interpreter lock is used to "
|
|
"protect the pointer to the current thread state. When releasing the lock "
|
|
"and saving the thread state, the current thread state pointer must be "
|
|
"retrieved before the lock is released (since another thread could "
|
|
"immediately acquire the lock and store its own thread state in the global "
|
|
"variable). Conversely, when acquiring the lock and restoring the thread "
|
|
"state, the lock must be acquired before storing the thread state pointer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:505
|
|
msgid ""
|
|
"Calling system I/O functions is the most common use case for releasing the "
|
|
"GIL, but it can also be useful before calling long-running computations "
|
|
"which don't need access to Python objects, such as compression or "
|
|
"cryptographic functions operating over memory buffers. For example, the "
|
|
"standard :mod:`zlib` and :mod:`hashlib` modules release the GIL when "
|
|
"compressing or hashing data."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:516
|
|
msgid "Non-Python created threads"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:518
|
|
msgid ""
|
|
"When threads are created using the dedicated Python APIs (such as the :mod:"
|
|
"`threading` module), a thread state is automatically associated to them and "
|
|
"the code showed above is therefore correct. However, when threads are "
|
|
"created from C (for example by a third-party library with its own thread "
|
|
"management), they don't hold the GIL, nor is there a thread state structure "
|
|
"for them."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:525
|
|
msgid ""
|
|
"If you need to call Python code from these threads (often this will be part "
|
|
"of a callback API provided by the aforementioned third-party library), you "
|
|
"must first register these threads with the interpreter by creating a thread "
|
|
"state data structure, then acquiring the GIL, and finally storing their "
|
|
"thread state pointer, before you can start using the Python/C API. When you "
|
|
"are done, you should reset the thread state pointer, release the GIL, and "
|
|
"finally free the thread state data structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:533
|
|
msgid ""
|
|
"The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions "
|
|
"do all of the above automatically. The typical idiom for calling into "
|
|
"Python from a C thread is::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:547
|
|
msgid ""
|
|
"Note that the :c:func:`PyGILState_\\*` functions assume there is only one "
|
|
"global interpreter (created automatically by :c:func:`Py_Initialize`). "
|
|
"Python supports the creation of additional interpreters (using :c:func:"
|
|
"`Py_NewInterpreter`), but mixing multiple interpreters and the :c:func:"
|
|
"`PyGILState_\\*` API is unsupported."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:553
|
|
msgid ""
|
|
"Another important thing to note about threads is their behaviour in the face "
|
|
"of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a "
|
|
"process forks only the thread that issued the fork will exist. That also "
|
|
"means any locks held by other threads will never be released. Python solves "
|
|
"this for :func:`os.fork` by acquiring the locks it uses internally before "
|
|
"the fork, and releasing them afterwards. In addition, it resets any :ref:"
|
|
"`lock-objects` in the child. When extending or embedding Python, there is no "
|
|
"way to inform Python of additional (non-Python) locks that need to be "
|
|
"acquired before or reset after a fork. OS facilities such as :c:func:"
|
|
"`pthread_atfork` would need to be used to accomplish the same thing. "
|
|
"Additionally, when extending or embedding Python, calling :c:func:`fork` "
|
|
"directly rather than through :func:`os.fork` (and returning to or calling "
|
|
"into Python) may result in a deadlock by one of Python's internal locks "
|
|
"being held by a thread that is defunct after the fork. :c:func:"
|
|
"`PyOS_AfterFork` tries to reset the necessary locks, but is not always able "
|
|
"to."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:572
|
|
msgid "High-level API"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:574
|
|
msgid ""
|
|
"These are the most commonly used types and functions when writing C "
|
|
"extension code, or when embedding the Python interpreter:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:579
|
|
msgid ""
|
|
"This data structure represents the state shared by a number of cooperating "
|
|
"threads. Threads belonging to the same interpreter share their module "
|
|
"administration and a few other internal items. There are no public members "
|
|
"in this structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:584
|
|
msgid ""
|
|
"Threads belonging to different interpreters initially share nothing, except "
|
|
"process state like available memory, open file descriptors and such. The "
|
|
"global interpreter lock is also shared by all threads, regardless of to "
|
|
"which interpreter they belong."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:592
|
|
msgid ""
|
|
"This data structure represents the state of a single thread. The only "
|
|
"public data member is :c:type:`PyInterpreterState \\*`:attr:`interp`, which "
|
|
"points to this thread's interpreter state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:605
|
|
msgid ""
|
|
"Initialize and acquire the global interpreter lock. It should be called in "
|
|
"the main thread before creating a second thread or engaging in any other "
|
|
"thread operations such as ``PyEval_ReleaseThread(tstate)``. It is not needed "
|
|
"before calling :c:func:`PyEval_SaveThread` or :c:func:`PyEval_RestoreThread`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:610
|
|
msgid "This is a no-op when called for a second time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:612
|
|
msgid ""
|
|
"This function cannot be called before :c:func:`Py_Initialize()` anymore."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:619
|
|
msgid ""
|
|
"When only the main thread exists, no GIL operations are needed. This is a "
|
|
"common situation (most Python programs do not use threads), and the lock "
|
|
"operations slow the interpreter down a bit. Therefore, the lock is not "
|
|
"created initially. This situation is equivalent to having acquired the "
|
|
"lock: when there is only a single thread, all object accesses are safe. "
|
|
"Therefore, when this function initializes the global interpreter lock, it "
|
|
"also acquires it. Before the Python :mod:`_thread` module creates a new "
|
|
"thread, knowing that either it has the lock or the lock hasn't been created "
|
|
"yet, it calls :c:func:`PyEval_InitThreads`. When this call returns, it is "
|
|
"guaranteed that the lock has been created and that the calling thread has "
|
|
"acquired it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:630
|
|
msgid ""
|
|
"It is **not** safe to call this function when it is unknown which thread (if "
|
|
"any) currently has the global interpreter lock."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:633
|
|
msgid ""
|
|
"This function is not available when thread support is disabled at compile "
|
|
"time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:638
|
|
msgid ""
|
|
"Returns a non-zero value if :c:func:`PyEval_InitThreads` has been called. "
|
|
"This function can be called without holding the GIL, and therefore can be "
|
|
"used to avoid calls to the locking API when running single-threaded. This "
|
|
"function is not available when thread support is disabled at compile time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:646
|
|
msgid ""
|
|
"Release the global interpreter lock (if it has been created and thread "
|
|
"support is enabled) and reset the thread state to *NULL*, returning the "
|
|
"previous thread state (which is not *NULL*). If the lock has been created, "
|
|
"the current thread must have acquired it. (This function is available even "
|
|
"when thread support is disabled at compile time.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:655
|
|
msgid ""
|
|
"Acquire the global interpreter lock (if it has been created and thread "
|
|
"support is enabled) and set the thread state to *tstate*, which must not be "
|
|
"*NULL*. If the lock has been created, the current thread must not have "
|
|
"acquired it, otherwise deadlock ensues. (This function is available even "
|
|
"when thread support is disabled at compile time.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:664
|
|
msgid ""
|
|
"Return the current thread state. The global interpreter lock must be held. "
|
|
"When the current thread state is *NULL*, this issues a fatal error (so that "
|
|
"the caller needn't check for *NULL*)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:671
|
|
msgid ""
|
|
"Swap the current thread state with the thread state given by the argument "
|
|
"*tstate*, which may be *NULL*. The global interpreter lock must be held and "
|
|
"is not released."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:678
|
|
msgid ""
|
|
"This function is called from :c:func:`PyOS_AfterFork` to ensure that newly "
|
|
"created child processes don't hold locks referring to threads which are not "
|
|
"running in the child process."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:683
|
|
msgid ""
|
|
"The following functions use thread-local storage, and are not compatible "
|
|
"with sub-interpreters:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:688
|
|
msgid ""
|
|
"Ensure that the current thread is ready to call the Python C API regardless "
|
|
"of the current state of Python, or of the global interpreter lock. This may "
|
|
"be called as many times as desired by a thread as long as each call is "
|
|
"matched with a call to :c:func:`PyGILState_Release`. In general, other "
|
|
"thread-related APIs may be used between :c:func:`PyGILState_Ensure` and :c:"
|
|
"func:`PyGILState_Release` calls as long as the thread state is restored to "
|
|
"its previous state before the Release(). For example, normal usage of the :"
|
|
"c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros "
|
|
"is acceptable."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:698
|
|
msgid ""
|
|
"The return value is an opaque \"handle\" to the thread state when :c:func:"
|
|
"`PyGILState_Ensure` was called, and must be passed to :c:func:"
|
|
"`PyGILState_Release` to ensure Python is left in the same state. Even though "
|
|
"recursive calls are allowed, these handles *cannot* be shared - each unique "
|
|
"call to :c:func:`PyGILState_Ensure` must save the handle for its call to :c:"
|
|
"func:`PyGILState_Release`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:705
|
|
msgid ""
|
|
"When the function returns, the current thread will hold the GIL and be able "
|
|
"to call arbitrary Python code. Failure is a fatal error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:711
|
|
msgid ""
|
|
"Release any resources previously acquired. After this call, Python's state "
|
|
"will be the same as it was prior to the corresponding :c:func:"
|
|
"`PyGILState_Ensure` call (but generally this state will be unknown to the "
|
|
"caller, hence the use of the GILState API)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:716
|
|
msgid ""
|
|
"Every call to :c:func:`PyGILState_Ensure` must be matched by a call to :c:"
|
|
"func:`PyGILState_Release` on the same thread."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:722
|
|
msgid ""
|
|
"Get the current thread state for this thread. May return ``NULL`` if no "
|
|
"GILState API has been used on the current thread. Note that the main thread "
|
|
"always has such a thread-state, even if no auto-thread-state call has been "
|
|
"made on the main thread. This is mainly a helper/diagnostic function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:730
|
|
msgid ""
|
|
"Return 1 if the current thread is holding the GIL and 0 otherwise. This "
|
|
"function can be called from any thread at any time. Only if it has had its "
|
|
"Python thread state initialized and currently is holding the GIL will it "
|
|
"return 1. This is mainly a helper/diagnostic function. It can be useful for "
|
|
"example in callback contexts or memory allocation functions when knowing "
|
|
"that the GIL is locked can allow the caller to perform sensitive actions or "
|
|
"otherwise behave differently."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:742
|
|
msgid ""
|
|
"The following macros are normally used without a trailing semicolon; look "
|
|
"for example usage in the Python source distribution."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:748
|
|
msgid ""
|
|
"This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();"
|
|
"``. Note that it contains an opening brace; it must be matched with a "
|
|
"following :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further "
|
|
"discussion of this macro. It is a no-op when thread support is disabled at "
|
|
"compile time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:756
|
|
msgid ""
|
|
"This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it "
|
|
"contains a closing brace; it must be matched with an earlier :c:macro:"
|
|
"`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of this "
|
|
"macro. It is a no-op when thread support is disabled at compile time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:764
|
|
msgid ""
|
|
"This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to :"
|
|
"c:macro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op "
|
|
"when thread support is disabled at compile time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:771
|
|
msgid ""
|
|
"This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to :"
|
|
"c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable "
|
|
"declaration. It is a no-op when thread support is disabled at compile time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:777
|
|
msgid "Low-level API"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:779
|
|
msgid ""
|
|
"All of the following functions are only available when thread support is "
|
|
"enabled at compile time, and must be called only when the global interpreter "
|
|
"lock has been created."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:786
|
|
msgid ""
|
|
"Create a new interpreter state object. The global interpreter lock need not "
|
|
"be held, but may be held if it is necessary to serialize calls to this "
|
|
"function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:793
|
|
msgid ""
|
|
"Reset all information in an interpreter state object. The global "
|
|
"interpreter lock must be held."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:799
|
|
msgid ""
|
|
"Destroy an interpreter state object. The global interpreter lock need not "
|
|
"be held. The interpreter state must have been reset with a previous call "
|
|
"to :c:func:`PyInterpreterState_Clear`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:806
|
|
msgid ""
|
|
"Create a new thread state object belonging to the given interpreter object. "
|
|
"The global interpreter lock need not be held, but may be held if it is "
|
|
"necessary to serialize calls to this function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:813
|
|
msgid ""
|
|
"Reset all information in a thread state object. The global interpreter lock "
|
|
"must be held."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:819
|
|
msgid ""
|
|
"Destroy a thread state object. The global interpreter lock need not be "
|
|
"held. The thread state must have been reset with a previous call to :c:func:"
|
|
"`PyThreadState_Clear`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:826
|
|
msgid ""
|
|
"Return a dictionary in which extensions can store thread-specific state "
|
|
"information. Each extension should use a unique key to use to store state "
|
|
"in the dictionary. It is okay to call this function when no current thread "
|
|
"state is available. If this function returns *NULL*, no exception has been "
|
|
"raised and the caller should assume no current thread state is available."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:835
|
|
msgid ""
|
|
"Asynchronously raise an exception in a thread. The *id* argument is the "
|
|
"thread id of the target thread; *exc* is the exception object to be raised. "
|
|
"This function does not steal any references to *exc*. To prevent naive "
|
|
"misuse, you must write your own C extension to call this. Must be called "
|
|
"with the GIL held. Returns the number of thread states modified; this is "
|
|
"normally one, but will be zero if the thread id isn't found. If *exc* is :"
|
|
"const:`NULL`, the pending exception (if any) for the thread is cleared. This "
|
|
"raises no exceptions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:846
|
|
msgid ""
|
|
"Acquire the global interpreter lock and set the current thread state to "
|
|
"*tstate*, which should not be *NULL*. The lock must have been created "
|
|
"earlier. If this thread already has the lock, deadlock ensues."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:850
|
|
msgid ""
|
|
":c:func:`PyEval_RestoreThread` is a higher-level function which is always "
|
|
"available (even when thread support isn't enabled or when threads have not "
|
|
"been initialized)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:857
|
|
msgid ""
|
|
"Reset the current thread state to *NULL* and release the global interpreter "
|
|
"lock. The lock must have been created earlier and must be held by the "
|
|
"current thread. The *tstate* argument, which must not be *NULL*, is only "
|
|
"used to check that it represents the current thread state --- if it isn't, a "
|
|
"fatal error is reported."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:863
|
|
msgid ""
|
|
":c:func:`PyEval_SaveThread` is a higher-level function which is always "
|
|
"available (even when thread support isn't enabled or when threads have not "
|
|
"been initialized)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:870
|
|
msgid ""
|
|
"Acquire the global interpreter lock. The lock must have been created "
|
|
"earlier. If this thread already has the lock, a deadlock ensues."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:873
|
|
msgid ""
|
|
"This function does not update the current thread state. Please use :c:func:"
|
|
"`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread` instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:881
|
|
msgid ""
|
|
"Release the global interpreter lock. The lock must have been created "
|
|
"earlier."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:883
|
|
msgid ""
|
|
"This function does not update the current thread state. Please use :c:func:"
|
|
"`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread` instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:892
|
|
msgid "Sub-interpreter support"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:894
|
|
msgid ""
|
|
"While in most uses, you will only embed a single Python interpreter, there "
|
|
"are cases where you need to create several independent interpreters in the "
|
|
"same process and perhaps even in the same thread. Sub-interpreters allow "
|
|
"you to do that. You can switch between sub-interpreters using the :c:func:"
|
|
"`PyThreadState_Swap` function. You can create and destroy them using the "
|
|
"following functions:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:912
|
|
msgid ""
|
|
"Create a new sub-interpreter. This is an (almost) totally separate "
|
|
"environment for the execution of Python code. In particular, the new "
|
|
"interpreter has separate, independent versions of all imported modules, "
|
|
"including the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:"
|
|
"`sys`. The table of loaded modules (``sys.modules``) and the module search "
|
|
"path (``sys.path``) are also separate. The new environment has no ``sys."
|
|
"argv`` variable. It has new standard I/O stream file objects ``sys.stdin``, "
|
|
"``sys.stdout`` and ``sys.stderr`` (however these refer to the same "
|
|
"underlying file descriptors)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:922
|
|
msgid ""
|
|
"The return value points to the first thread state created in the new sub-"
|
|
"interpreter. This thread state is made in the current thread state. Note "
|
|
"that no actual thread is created; see the discussion of thread states "
|
|
"below. If creation of the new interpreter is unsuccessful, *NULL* is "
|
|
"returned; no exception is set since the exception state is stored in the "
|
|
"current thread state and there may not be a current thread state. (Like all "
|
|
"other Python/C API functions, the global interpreter lock must be held "
|
|
"before calling this function and is still held when it returns; however, "
|
|
"unlike most other Python/C API functions, there needn't be a current thread "
|
|
"state on entry.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:937
|
|
msgid ""
|
|
"Extension modules are shared between (sub-)interpreters as follows: the "
|
|
"first time a particular extension is imported, it is initialized normally, "
|
|
"and a (shallow) copy of its module's dictionary is squirreled away. When "
|
|
"the same extension is imported by another (sub-)interpreter, a new module is "
|
|
"initialized and filled with the contents of this copy; the extension's "
|
|
"``init`` function is not called. Note that this is different from what "
|
|
"happens when an extension is imported after the interpreter has been "
|
|
"completely re-initialized by calling :c:func:`Py_FinalizeEx` and :c:func:"
|
|
"`Py_Initialize`; in that case, the extension's ``initmodule`` function *is* "
|
|
"called again."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:954
|
|
msgid ""
|
|
"Destroy the (sub-)interpreter represented by the given thread state. The "
|
|
"given thread state must be the current thread state. See the discussion of "
|
|
"thread states below. When the call returns, the current thread state is "
|
|
"*NULL*. All thread states associated with this interpreter are destroyed. "
|
|
"(The global interpreter lock must be held before calling this function and "
|
|
"is still held when it returns.) :c:func:`Py_FinalizeEx` will destroy all "
|
|
"sub-interpreters that haven't been explicitly destroyed at that point."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:964
|
|
msgid "Bugs and caveats"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:966
|
|
msgid ""
|
|
"Because sub-interpreters (and the main interpreter) are part of the same "
|
|
"process, the insulation between them isn't perfect --- for example, using "
|
|
"low-level file operations like :func:`os.close` they can (accidentally or "
|
|
"maliciously) affect each other's open files. Because of the way extensions "
|
|
"are shared between (sub-)interpreters, some extensions may not work "
|
|
"properly; this is especially likely when the extension makes use of (static) "
|
|
"global variables, or when the extension manipulates its module's dictionary "
|
|
"after its initialization. It is possible to insert objects created in one "
|
|
"sub-interpreter into a namespace of another sub-interpreter; this should be "
|
|
"done with great care to avoid sharing user-defined functions, methods, "
|
|
"instances or classes between sub-interpreters, since import operations "
|
|
"executed by such objects may affect the wrong (sub-)interpreter's dictionary "
|
|
"of loaded modules."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:980
|
|
msgid ""
|
|
"Also note that combining this functionality with :c:func:`PyGILState_\\*` "
|
|
"APIs is delicate, because these APIs assume a bijection between Python "
|
|
"thread states and OS-level threads, an assumption broken by the presence of "
|
|
"sub-interpreters. It is highly recommended that you don't switch sub-"
|
|
"interpreters between a pair of matching :c:func:`PyGILState_Ensure` and :c:"
|
|
"func:`PyGILState_Release` calls. Furthermore, extensions (such as :mod:"
|
|
"`ctypes`) using these APIs to allow calling of Python code from non-Python "
|
|
"created threads will probably be broken when using sub-interpreters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:991
|
|
msgid "Asynchronous Notifications"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:993
|
|
msgid ""
|
|
"A mechanism is provided to make asynchronous notifications to the main "
|
|
"interpreter thread. These notifications take the form of a function pointer "
|
|
"and a void pointer argument."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1002
|
|
msgid ""
|
|
"Schedule a function to be called from the main interpreter thread. On "
|
|
"success, 0 is returned and *func* is queued for being called in the main "
|
|
"thread. On failure, -1 is returned without setting any exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1006
|
|
msgid ""
|
|
"When successfully queued, *func* will be *eventually* called from the main "
|
|
"interpreter thread with the argument *arg*. It will be called "
|
|
"asynchronously with respect to normally running Python code, but with both "
|
|
"these conditions met:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1011
|
|
msgid "on a :term:`bytecode` boundary;"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1012
|
|
msgid ""
|
|
"with the main thread holding the :term:`global interpreter lock` (*func* can "
|
|
"therefore use the full C API)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1015
|
|
msgid ""
|
|
"*func* must return 0 on success, or -1 on failure with an exception set. "
|
|
"*func* won't be interrupted to perform another asynchronous notification "
|
|
"recursively, but it can still be interrupted to switch threads if the global "
|
|
"interpreter lock is released."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1020
|
|
msgid ""
|
|
"This function doesn't need a current thread state to run, and it doesn't "
|
|
"need the global interpreter lock."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1024
|
|
msgid ""
|
|
"This is a low-level function, only useful for very special cases. There is "
|
|
"no guarantee that *func* will be called as quick as possible. If the main "
|
|
"thread is busy executing a system call, *func* won't be called before the "
|
|
"system call returns. This function is generally **not** suitable for "
|
|
"calling Python code from arbitrary C threads. Instead, use the :ref:"
|
|
"`PyGILState API<gilstate>`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1036
|
|
msgid "Profiling and Tracing"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1041
|
|
msgid ""
|
|
"The Python interpreter provides some low-level support for attaching "
|
|
"profiling and execution tracing facilities. These are used for profiling, "
|
|
"debugging, and coverage analysis tools."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1045
|
|
msgid ""
|
|
"This C interface allows the profiling or tracing code to avoid the overhead "
|
|
"of calling through Python-level callable objects, making a direct C function "
|
|
"call instead. The essential attributes of the facility have not changed; "
|
|
"the interface allows trace functions to be installed per-thread, and the "
|
|
"basic events reported to the trace function are the same as had been "
|
|
"reported to the Python-level trace functions in previous versions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1055
|
|
msgid ""
|
|
"The type of the trace function registered using :c:func:`PyEval_SetProfile` "
|
|
"and :c:func:`PyEval_SetTrace`. The first parameter is the object passed to "
|
|
"the registration function as *obj*, *frame* is the frame object to which the "
|
|
"event pertains, *what* is one of the constants :const:`PyTrace_CALL`, :const:"
|
|
"`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`, :const:"
|
|
"`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, or :const:"
|
|
"`PyTrace_C_RETURN`, and *arg* depends on the value of *what*:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1064
|
|
msgid "Value of *what*"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1064
|
|
msgid "Meaning of *arg*"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1066
|
|
msgid ":const:`PyTrace_CALL`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1066 ../Doc/c-api/init.rst:1071
|
|
msgid "Always *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1068
|
|
msgid ":const:`PyTrace_EXCEPTION`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1068
|
|
msgid "Exception information as returned by :func:`sys.exc_info`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1071
|
|
msgid ":const:`PyTrace_LINE`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1073
|
|
msgid ":const:`PyTrace_RETURN`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1073
|
|
msgid ""
|
|
"Value being returned to the caller, or *NULL* if caused by an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1076
|
|
msgid ":const:`PyTrace_C_CALL`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1076 ../Doc/c-api/init.rst:1078
|
|
#: ../Doc/c-api/init.rst:1080
|
|
msgid "Function object being called."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1078
|
|
msgid ":const:`PyTrace_C_EXCEPTION`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1080
|
|
msgid ":const:`PyTrace_C_RETURN`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1086
|
|
msgid ""
|
|
"The value of the *what* parameter to a :c:type:`Py_tracefunc` function when "
|
|
"a new call to a function or method is being reported, or a new entry into a "
|
|
"generator. Note that the creation of the iterator for a generator function "
|
|
"is not reported as there is no control transfer to the Python bytecode in "
|
|
"the corresponding frame."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1095
|
|
msgid ""
|
|
"The value of the *what* parameter to a :c:type:`Py_tracefunc` function when "
|
|
"an exception has been raised. The callback function is called with this "
|
|
"value for *what* when after any bytecode is processed after which the "
|
|
"exception becomes set within the frame being executed. The effect of this "
|
|
"is that as exception propagation causes the Python stack to unwind, the "
|
|
"callback is called upon return to each frame as the exception propagates. "
|
|
"Only trace functions receives these events; they are not needed by the "
|
|
"profiler."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1106
|
|
msgid ""
|
|
"The value passed as the *what* parameter to a trace function (but not a "
|
|
"profiling function) when a line-number event is being reported."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1112
|
|
msgid ""
|
|
"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when "
|
|
"a call is returning without propagating an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1118
|
|
msgid ""
|
|
"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when "
|
|
"a C function is about to be called."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1124
|
|
msgid ""
|
|
"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when "
|
|
"a C function has raised an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1130
|
|
msgid ""
|
|
"The value for the *what* parameter to :c:type:`Py_tracefunc` functions when "
|
|
"a C function has returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1136
|
|
msgid ""
|
|
"Set the profiler function to *func*. The *obj* parameter is passed to the "
|
|
"function as its first parameter, and may be any Python object, or *NULL*. "
|
|
"If the profile function needs to maintain state, using a different value for "
|
|
"*obj* for each thread provides a convenient and thread-safe place to store "
|
|
"it. The profile function is called for all monitored events except the line-"
|
|
"number events."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1146
|
|
msgid ""
|
|
"Set the tracing function to *func*. This is similar to :c:func:"
|
|
"`PyEval_SetProfile`, except the tracing function does receive line-number "
|
|
"events."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1152
|
|
msgid ""
|
|
"Return a tuple of function call counts. There are constants defined for the "
|
|
"positions within the tuple:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1156
|
|
msgid "Name"
|
|
msgstr "Nom"
|
|
|
|
#: ../Doc/c-api/init.rst:1156
|
|
msgid "Value"
|
|
msgstr "Valeur"
|
|
|
|
#: ../Doc/c-api/init.rst:1158
|
|
msgid ":const:`PCALL_ALL`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1160
|
|
msgid ":const:`PCALL_FUNCTION`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1160
|
|
msgid "1"
|
|
msgstr "1"
|
|
|
|
#: ../Doc/c-api/init.rst:1162
|
|
msgid ":const:`PCALL_FAST_FUNCTION`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1162
|
|
msgid "2"
|
|
msgstr "2"
|
|
|
|
#: ../Doc/c-api/init.rst:1164
|
|
msgid ":const:`PCALL_FASTER_FUNCTION`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1164
|
|
msgid "3"
|
|
msgstr "3"
|
|
|
|
#: ../Doc/c-api/init.rst:1166
|
|
msgid ":const:`PCALL_METHOD`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1166
|
|
msgid "4"
|
|
msgstr "4"
|
|
|
|
#: ../Doc/c-api/init.rst:1168
|
|
msgid ":const:`PCALL_BOUND_METHOD`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1168
|
|
msgid "5"
|
|
msgstr "5"
|
|
|
|
#: ../Doc/c-api/init.rst:1170
|
|
msgid ":const:`PCALL_CFUNCTION`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1170
|
|
msgid "6"
|
|
msgstr "6"
|
|
|
|
#: ../Doc/c-api/init.rst:1172
|
|
msgid ":const:`PCALL_TYPE`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1172
|
|
msgid "7"
|
|
msgstr "7"
|
|
|
|
#: ../Doc/c-api/init.rst:1174
|
|
msgid ":const:`PCALL_GENERATOR`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1174
|
|
msgid "8"
|
|
msgstr "8"
|
|
|
|
#: ../Doc/c-api/init.rst:1176
|
|
msgid ":const:`PCALL_OTHER`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1176
|
|
msgid "9"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1178
|
|
msgid ":const:`PCALL_POP`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1178
|
|
msgid "10"
|
|
msgstr "10"
|
|
|
|
#: ../Doc/c-api/init.rst:1181
|
|
msgid ""
|
|
":const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created. :"
|
|
"const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is "
|
|
"used."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1184
|
|
msgid ""
|
|
"If there is a method call where the call can be optimized by changing the "
|
|
"argument tuple and calling the function directly, it gets recorded twice."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1188
|
|
msgid ""
|
|
"This function is only present if Python is compiled with :const:"
|
|
"`CALL_PROFILE` defined."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1194
|
|
msgid "Advanced Debugger Support"
|
|
msgstr "Support avancé du debugger"
|
|
|
|
#: ../Doc/c-api/init.rst:1199
|
|
msgid ""
|
|
"These functions are only intended to be used by advanced debugging tools."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1204
|
|
msgid ""
|
|
"Return the interpreter state object at the head of the list of all such "
|
|
"objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1209
|
|
msgid ""
|
|
"Return the next interpreter state object after *interp* from the list of all "
|
|
"such objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1215
|
|
msgid ""
|
|
"Return the pointer to the first :c:type:`PyThreadState` object in the list "
|
|
"of threads associated with the interpreter *interp*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/init.rst:1221
|
|
msgid ""
|
|
"Return the next thread state object after *tstate* from the list of all such "
|
|
"objects belonging to the same :c:type:`PyInterpreterState` object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:8
|
|
msgid "Introduction"
|
|
msgstr "Introduction"
|
|
|
|
#: ../Doc/c-api/intro.rst:10
|
|
msgid ""
|
|
"The Application Programmer's Interface to Python gives C and C++ programmers "
|
|
"access to the Python interpreter at a variety of levels. The API is equally "
|
|
"usable from C++, but for brevity it is generally referred to as the Python/C "
|
|
"API. There are two fundamentally different reasons for using the Python/C "
|
|
"API. The first reason is to write *extension modules* for specific purposes; "
|
|
"these are C modules that extend the Python interpreter. This is probably "
|
|
"the most common use. The second reason is to use Python as a component in a "
|
|
"larger application; this technique is generally referred to as :dfn:"
|
|
"`embedding` Python in an application."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:20
|
|
msgid ""
|
|
"Writing an extension module is a relatively well-understood process, where "
|
|
"a \"cookbook\" approach works well. There are several tools that automate "
|
|
"the process to some extent. While people have embedded Python in other "
|
|
"applications since its early existence, the process of embedding Python is "
|
|
"less straightforward than writing an extension."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:26
|
|
msgid ""
|
|
"Many API functions are useful independent of whether you're embedding or "
|
|
"extending Python; moreover, most applications that embed Python will need "
|
|
"to provide a custom extension as well, so it's probably a good idea to "
|
|
"become familiar with writing an extension before attempting to embed Python "
|
|
"in a real application."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:36
|
|
msgid "Include Files"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:38
|
|
msgid ""
|
|
"All function, type and macro definitions needed to use the Python/C API are "
|
|
"included in your code by the following line::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:43
|
|
msgid ""
|
|
"This implies inclusion of the following standard headers: ``<stdio.h>``, "
|
|
"``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib."
|
|
"h>`` (if available)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:49
|
|
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/c-api/intro.rst:53
|
|
msgid ""
|
|
"All user visible names defined by Python.h (except those defined by the "
|
|
"included standard headers) have one of the prefixes ``Py`` or ``_Py``. "
|
|
"Names beginning with ``_Py`` are for internal use by the Python "
|
|
"implementation and should not be used by extension writers. Structure member "
|
|
"names do not have a reserved prefix."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:58
|
|
msgid ""
|
|
"**Important:** user code should never define names that begin with ``Py`` or "
|
|
"``_Py``. This confuses the reader, and jeopardizes the portability of the "
|
|
"user code to future Python versions, which may define additional names "
|
|
"beginning with one of these prefixes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:63
|
|
msgid ""
|
|
"The header files are typically installed with Python. On Unix, these are "
|
|
"located in the directories :file:`{prefix}/include/pythonversion/` and :file:"
|
|
"`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and :envvar:"
|
|
"`exec_prefix` are defined by the corresponding parameters to Python's :"
|
|
"program:`configure` script and *version* is ``'%d.%d' % sys."
|
|
"version_info[:2]``. On Windows, the headers are installed in :file:"
|
|
"`{prefix}/include`, where :envvar:`prefix` is the installation directory "
|
|
"specified to the installer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:72
|
|
msgid ""
|
|
"To include the headers, place both directories (if different) on your "
|
|
"compiler's search path for includes. Do *not* place the parent directories "
|
|
"on the search path and then use ``#include <pythonX.Y/Python.h>``; this will "
|
|
"break on multi-platform builds since the platform independent headers under :"
|
|
"envvar:`prefix` include the platform specific headers from :envvar:"
|
|
"`exec_prefix`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:79
|
|
msgid ""
|
|
"C++ users should note that though the API is defined entirely using C, the "
|
|
"header files do properly declare the entry points to be ``extern \"C\"``, so "
|
|
"there is no need to do anything special to use the API from C++."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:87
|
|
msgid "Objects, Types and Reference Counts"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:91
|
|
msgid ""
|
|
"Most Python/C API functions have one or more arguments as well as a return "
|
|
"value of type :c:type:`PyObject\\*`. This type is a pointer to an opaque "
|
|
"data type representing an arbitrary Python object. Since all Python object "
|
|
"types are treated the same way by the Python language in most situations (e."
|
|
"g., assignments, scope rules, and argument passing), it is only fitting that "
|
|
"they should be represented by a single C type. Almost all Python objects "
|
|
"live on the heap: you never declare an automatic or static variable of type :"
|
|
"c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\\*` can "
|
|
"be declared. The sole exception are the type objects; since these must "
|
|
"never be deallocated, they are typically static :c:type:`PyTypeObject` "
|
|
"objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:102
|
|
msgid ""
|
|
"All Python objects (even Python integers) have a :dfn:`type` and a :dfn:"
|
|
"`reference count`. An object's type determines what kind of object it is (e."
|
|
"g., an integer, a list, or a user-defined function; there are many more as "
|
|
"explained in :ref:`types`). For each of the well-known types there is a "
|
|
"macro to check whether an object is of that type; for instance, "
|
|
"``PyList_Check(a)`` is true if (and only if) the object pointed to by *a* is "
|
|
"a Python list."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:113
|
|
msgid "Reference Counts"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:115
|
|
msgid ""
|
|
"The reference count is important because today's computers have a finite "
|
|
"(and often severely limited) memory size; it counts how many different "
|
|
"places there are that have a reference to an object. Such a place could be "
|
|
"another object, or a global (or static) C variable, or a local variable in "
|
|
"some C function. When an object's reference count becomes zero, the object "
|
|
"is deallocated. If it contains references to other objects, their "
|
|
"reference count is decremented. Those other objects may be deallocated in "
|
|
"turn, if this decrement makes their reference count become zero, and so on. "
|
|
"(There's an obvious problem with objects that reference each other here; "
|
|
"for now, the solution is \"don't do that.\")"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:130
|
|
msgid ""
|
|
"Reference counts are always manipulated explicitly. The normal way is to "
|
|
"use the macro :c:func:`Py_INCREF` to increment an object's reference count "
|
|
"by one, and :c:func:`Py_DECREF` to decrement it by one. The :c:func:"
|
|
"`Py_DECREF` macro is considerably more complex than the incref one, since it "
|
|
"must check whether the reference count becomes zero and then cause the "
|
|
"object's deallocator to be called. The deallocator is a function pointer "
|
|
"contained in the object's type structure. The type-specific deallocator "
|
|
"takes care of decrementing the reference counts for other objects contained "
|
|
"in the object if this is a compound object type, such as a list, as well as "
|
|
"performing any additional finalization that's needed. There's no chance "
|
|
"that the reference count can overflow; at least as many bits are used to "
|
|
"hold the reference count as there are distinct memory locations in virtual "
|
|
"memory (assuming ``sizeof(Py_ssize_t) >= sizeof(void*)``). Thus, the "
|
|
"reference count increment is a simple operation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:144
|
|
msgid ""
|
|
"It is not necessary to increment an object's reference count for every "
|
|
"local variable that contains a pointer to an object. In theory, the "
|
|
"object's reference count goes up by one when the variable is made to point "
|
|
"to it and it goes down by one when the variable goes out of scope. "
|
|
"However, these two cancel each other out, so at the end the reference count "
|
|
"hasn't changed. The only real reason to use the reference count is to "
|
|
"prevent the object from being deallocated as long as our variable is "
|
|
"pointing to it. If we know that there is at least one other reference to "
|
|
"the object that lives at least as long as our variable, there is no need to "
|
|
"increment the reference count temporarily. An important situation where "
|
|
"this arises is in objects that are passed as arguments to C functions in an "
|
|
"extension module that are called from Python; the call mechanism guarantees "
|
|
"to hold a reference to every argument for the duration of the call."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:158
|
|
msgid ""
|
|
"However, a common pitfall is to extract an object from a list and hold on to "
|
|
"it for a while without incrementing its reference count. Some other "
|
|
"operation might conceivably remove the object from the list, decrementing "
|
|
"its reference count and possible deallocating it. The real danger is that "
|
|
"innocent-looking operations may invoke arbitrary Python code which could do "
|
|
"this; there is a code path which allows control to flow back to the user "
|
|
"from a :c:func:`Py_DECREF`, so almost any operation is potentially dangerous."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:166
|
|
msgid ""
|
|
"A safe approach is to always use the generic operations (functions whose "
|
|
"name begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or "
|
|
"``PyMapping_``). These operations always increment the reference count of "
|
|
"the object they return. This leaves the caller with the responsibility to "
|
|
"call :c:func:`Py_DECREF` when they are done with the result; this soon "
|
|
"becomes second nature."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:176
|
|
msgid "Reference Count Details"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:178
|
|
msgid ""
|
|
"The reference count behavior of functions in the Python/C API is best "
|
|
"explained in terms of *ownership of references*. Ownership pertains to "
|
|
"references, never to objects (objects are not owned: they are always "
|
|
"shared). \"Owning a reference\" means being responsible for calling "
|
|
"Py_DECREF on it when the reference is no longer needed. Ownership can also "
|
|
"be transferred, meaning that the code that receives ownership of the "
|
|
"reference then becomes responsible for eventually decref'ing it by calling :"
|
|
"c:func:`Py_DECREF` or :c:func:`Py_XDECREF` when it's no longer needed---or "
|
|
"passing on this responsibility (usually to its caller). When a function "
|
|
"passes ownership of a reference on to its caller, the caller is said to "
|
|
"receive a *new* reference. When no ownership is transferred, the caller is "
|
|
"said to *borrow* the reference. Nothing needs to be done for a borrowed "
|
|
"reference."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:191
|
|
msgid ""
|
|
"Conversely, when a calling function passes in a reference to an object, "
|
|
"there are two possibilities: the function *steals* a reference to the "
|
|
"object, or it does not. *Stealing a reference* means that when you pass a "
|
|
"reference to a function, that function assumes that it now owns that "
|
|
"reference, and you are not responsible for it any longer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:201
|
|
msgid ""
|
|
"Few functions steal references; the two notable exceptions are :c:func:"
|
|
"`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference to "
|
|
"the item (but not to the tuple or list into which the item is put!). These "
|
|
"functions were designed to steal a reference because of a common idiom for "
|
|
"populating a tuple or list with newly created objects; for example, the code "
|
|
"to create the tuple ``(1, 2, \"three\")`` could look like this (forgetting "
|
|
"about error handling for the moment; a better way to code this is shown "
|
|
"below)::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:216
|
|
msgid ""
|
|
"Here, :c:func:`PyLong_FromLong` returns a new reference which is immediately "
|
|
"stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object "
|
|
"although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab "
|
|
"another reference before calling the reference-stealing function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:221
|
|
msgid ""
|
|
"Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple "
|
|
"items; :c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to "
|
|
"do this since tuples are an immutable data type. You should only use :c:"
|
|
"func:`PyTuple_SetItem` for tuples that you are creating yourself."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:226
|
|
msgid ""
|
|
"Equivalent code for populating a list can be written using :c:func:"
|
|
"`PyList_New` and :c:func:`PyList_SetItem`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:229
|
|
msgid ""
|
|
"However, in practice, you will rarely use these ways of creating and "
|
|
"populating a tuple or list. There's a generic function, :c:func:"
|
|
"`Py_BuildValue`, that can create most common objects from C values, directed "
|
|
"by a :dfn:`format string`. For example, the above two blocks of code could "
|
|
"be replaced by the following (which also takes care of the error checking)::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:240
|
|
msgid ""
|
|
"It is much more common to use :c:func:`PyObject_SetItem` and friends with "
|
|
"items whose references you are only borrowing, like arguments that were "
|
|
"passed in to the function you are writing. In that case, their behaviour "
|
|
"regarding reference counts is much saner, since you don't have to increment "
|
|
"a reference count so you can give a reference away (\"have it be stolen\"). "
|
|
"For example, this function sets all items of a list (actually, any mutable "
|
|
"sequence) to a given item::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:270
|
|
msgid ""
|
|
"The situation is slightly different for function return values. While "
|
|
"passing a reference to most functions does not change your ownership "
|
|
"responsibilities for that reference, many functions that return a reference "
|
|
"to an object give you ownership of the reference. The reason is simple: in "
|
|
"many cases, the returned object is created on the fly, and the reference "
|
|
"you get is the only reference to the object. Therefore, the generic "
|
|
"functions that return object references, like :c:func:`PyObject_GetItem` "
|
|
"and :c:func:`PySequence_GetItem`, always return a new reference (the caller "
|
|
"becomes the owner of the reference)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:279
|
|
msgid ""
|
|
"It is important to realize that whether you own a reference returned by a "
|
|
"function depends on which function you call only --- *the plumage* (the type "
|
|
"of the object passed as an argument to the function) *doesn't enter into it!"
|
|
"* Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, "
|
|
"you don't own the reference --- but if you obtain the same item from the "
|
|
"same list using :c:func:`PySequence_GetItem` (which happens to take exactly "
|
|
"the same arguments), you do own a reference to the returned object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:291
|
|
msgid ""
|
|
"Here is an example of how you could write a function that computes the sum "
|
|
"of the items in a list of integers; once using :c:func:`PyList_GetItem`, "
|
|
"and once using :c:func:`PySequence_GetItem`. ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:355
|
|
msgid "Types"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:357
|
|
msgid ""
|
|
"There are few other data types that play a significant role in the Python/C "
|
|
"API; most are simple C types such as :c:type:`int`, :c:type:`long`, :c:type:"
|
|
"`double` and :c:type:`char\\*`. A few structure types are used to describe "
|
|
"static tables used to list the functions exported by a module or the data "
|
|
"attributes of a new object type, and another is used to describe the value "
|
|
"of a complex number. These will be discussed together with the functions "
|
|
"that use them."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:369
|
|
msgid "Exceptions"
|
|
msgstr "Les exceptions"
|
|
|
|
#: ../Doc/c-api/intro.rst:371
|
|
msgid ""
|
|
"The Python programmer only needs to deal with exceptions if specific error "
|
|
"handling is required; unhandled exceptions are automatically propagated to "
|
|
"the caller, then to the caller's caller, and so on, until they reach the top-"
|
|
"level interpreter, where they are reported to the user accompanied by a "
|
|
"stack traceback."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:379
|
|
msgid ""
|
|
"For C programmers, however, error checking always has to be explicit. All "
|
|
"functions in the Python/C API can raise exceptions, unless an explicit claim "
|
|
"is made otherwise in a function's documentation. In general, when a "
|
|
"function encounters an error, it sets an exception, discards any object "
|
|
"references that it owns, and returns an error indicator. If not documented "
|
|
"otherwise, this indicator is either *NULL* or ``-1``, depending on the "
|
|
"function's return type. A few functions return a Boolean true/false result, "
|
|
"with false indicating an error. Very few functions return no explicit error "
|
|
"indicator or have an ambiguous return value, and require explicit testing "
|
|
"for errors with :c:func:`PyErr_Occurred`. These exceptions are always "
|
|
"explicitly documented."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:394
|
|
msgid ""
|
|
"Exception state is maintained in per-thread storage (this is equivalent to "
|
|
"using global storage in an unthreaded application). A thread can be in one "
|
|
"of two states: an exception has occurred, or not. The function :c:func:"
|
|
"`PyErr_Occurred` can be used to check for this: it returns a borrowed "
|
|
"reference to the exception type object when an exception has occurred, and "
|
|
"*NULL* otherwise. There are a number of functions to set the exception "
|
|
"state: :c:func:`PyErr_SetString` is the most common (though not the most "
|
|
"general) function to set the exception state, and :c:func:`PyErr_Clear` "
|
|
"clears the exception state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:404
|
|
msgid ""
|
|
"The full exception state consists of three objects (all of which can be "
|
|
"*NULL*): the exception type, the corresponding exception value, and the "
|
|
"traceback. These have the same meanings as the Python result of ``sys."
|
|
"exc_info()``; however, they are not the same: the Python objects represent "
|
|
"the last exception being handled by a Python :keyword:`try` ... :keyword:"
|
|
"`except` statement, while the C level exception state only exists while an "
|
|
"exception is being passed on between C functions until it reaches the Python "
|
|
"bytecode interpreter's main loop, which takes care of transferring it to "
|
|
"``sys.exc_info()`` and friends."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:416
|
|
msgid ""
|
|
"Note that starting with Python 1.5, the preferred, thread-safe way to access "
|
|
"the exception state from Python code is to call the function :func:`sys."
|
|
"exc_info`, which returns the per-thread exception state for Python code. "
|
|
"Also, the semantics of both ways to access the exception state have changed "
|
|
"so that a function which catches an exception will save and restore its "
|
|
"thread's exception state so as to preserve the exception state of its "
|
|
"caller. This prevents common bugs in exception handling code caused by an "
|
|
"innocent-looking function overwriting the exception being handled; it also "
|
|
"reduces the often unwanted lifetime extension for objects that are "
|
|
"referenced by the stack frames in the traceback."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:427
|
|
msgid ""
|
|
"As a general principle, a function that calls another function to perform "
|
|
"some task should check whether the called function raised an exception, and "
|
|
"if so, pass the exception state on to its caller. It should discard any "
|
|
"object references that it owns, and return an error indicator, but it "
|
|
"should *not* set another exception --- that would overwrite the exception "
|
|
"that was just raised, and lose important information about the exact cause "
|
|
"of the error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:436
|
|
msgid ""
|
|
"A simple example of detecting exceptions and passing them on is shown in "
|
|
"the :c:func:`sum_sequence` example above. It so happens that this example "
|
|
"doesn't need to clean up any owned references when it detects an error. The "
|
|
"following example function shows some error cleanup. First, to remind you "
|
|
"why you like Python, we show the equivalent Python code::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:451
|
|
msgid "Here is the corresponding C code, in all its glory::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:503
|
|
msgid ""
|
|
"This example represents an endorsed use of the ``goto`` statement in C! It "
|
|
"illustrates the use of :c:func:`PyErr_ExceptionMatches` and :c:func:"
|
|
"`PyErr_Clear` to handle specific exceptions, and the use of :c:func:"
|
|
"`Py_XDECREF` to dispose of owned references that may be *NULL* (note the "
|
|
"``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a "
|
|
"*NULL* reference). It is important that the variables used to hold owned "
|
|
"references are initialized to *NULL* for this to work; likewise, the "
|
|
"proposed return value is initialized to ``-1`` (failure) and only set to "
|
|
"success after the final call made is successful."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:517
|
|
msgid "Embedding Python"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:519
|
|
msgid ""
|
|
"The one important task that only embedders (as opposed to extension writers) "
|
|
"of the Python interpreter have to worry about is the initialization, and "
|
|
"possibly the finalization, of the Python interpreter. Most functionality of "
|
|
"the interpreter can only be used after the interpreter has been initialized."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:532
|
|
msgid ""
|
|
"The basic initialization function is :c:func:`Py_Initialize`. This "
|
|
"initializes the table of loaded modules, and creates the fundamental "
|
|
"modules :mod:`builtins`, :mod:`__main__`, and :mod:`sys`. It also "
|
|
"initializes the module search path (``sys.path``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:539
|
|
msgid ""
|
|
":c:func:`Py_Initialize` does not set the \"script argument list\" (``sys."
|
|
"argv``). If this variable is needed by Python code that will be executed "
|
|
"later, it must be set explicitly with a call to ``PySys_SetArgvEx(argc, "
|
|
"argv, updatepath)`` after the call to :c:func:`Py_Initialize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:544
|
|
msgid ""
|
|
"On most systems (in particular, on Unix and Windows, although the details "
|
|
"are slightly different), :c:func:`Py_Initialize` calculates the module "
|
|
"search path based upon its best guess for the location of the standard "
|
|
"Python interpreter executable, assuming that the Python library is found in "
|
|
"a fixed location relative to the Python interpreter executable. In "
|
|
"particular, it looks for a directory named :file:`lib/python{X.Y}` relative "
|
|
"to the parent directory where the executable named :file:`python` is found "
|
|
"on the shell command search path (the environment variable :envvar:`PATH`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:553
|
|
msgid ""
|
|
"For instance, if the Python executable is found in :file:`/usr/local/bin/"
|
|
"python`, it will assume that the libraries are in :file:`/usr/local/lib/"
|
|
"python{X.Y}`. (In fact, this particular path is also the \"fallback\" "
|
|
"location, used when no executable file named :file:`python` is found along :"
|
|
"envvar:`PATH`.) The user can override this behavior by setting the "
|
|
"environment variable :envvar:`PYTHONHOME`, or insert additional directories "
|
|
"in front of the standard path by setting :envvar:`PYTHONPATH`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:568
|
|
msgid ""
|
|
"The embedding application can steer the search by calling "
|
|
"``Py_SetProgramName(file)`` *before* calling :c:func:`Py_Initialize`. Note "
|
|
"that :envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is "
|
|
"still inserted in front of the standard path. An application that requires "
|
|
"total control has to provide its own implementation of :c:func:"
|
|
"`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and :c:"
|
|
"func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:578
|
|
msgid ""
|
|
"Sometimes, it is desirable to \"uninitialize\" Python. For instance, the "
|
|
"application may want to start over (make another call to :c:func:"
|
|
"`Py_Initialize`) or the application is simply done with its use of Python "
|
|
"and wants to free memory allocated by Python. This can be accomplished by "
|
|
"calling :c:func:`Py_FinalizeEx`. The function :c:func:`Py_IsInitialized` "
|
|
"returns true if Python is currently in the initialized state. More "
|
|
"information about these functions is given in a later chapter. Notice that :"
|
|
"c:func:`Py_FinalizeEx` does *not* free all memory allocated by the Python "
|
|
"interpreter, e.g. memory allocated by extension modules currently cannot be "
|
|
"released."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:592
|
|
msgid "Debugging Builds"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:594
|
|
msgid ""
|
|
"Python can be built with several macros to enable extra checks of the "
|
|
"interpreter and extension modules. These checks tend to add a large amount "
|
|
"of overhead to the runtime so they are not enabled by default."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:598
|
|
msgid ""
|
|
"A full list of the various types of debugging builds is in the file :file:"
|
|
"`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are "
|
|
"available that support tracing of reference counts, debugging the memory "
|
|
"allocator, or low-level profiling of the main interpreter loop. Only the "
|
|
"most frequently-used builds will be described in the remainder of this "
|
|
"section."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:604
|
|
msgid ""
|
|
"Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined "
|
|
"produces what is generally meant by \"a debug build\" of Python. :c:macro:"
|
|
"`Py_DEBUG` is enabled in the Unix build by adding ``--with-pydebug`` to the :"
|
|
"file:`./configure` command. It is also implied by the presence of the not-"
|
|
"Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is "
|
|
"enabled in the Unix build, compiler optimization is disabled."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:611
|
|
msgid ""
|
|
"In addition to the reference count debugging described below, the following "
|
|
"extra checks are performed:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:614
|
|
msgid "Extra checks are added to the object allocator."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:616
|
|
msgid "Extra checks are added to the parser and compiler."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:618
|
|
msgid ""
|
|
"Downcasts from wide types to narrow types are checked for loss of "
|
|
"information."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:620
|
|
msgid ""
|
|
"A number of assertions are added to the dictionary and set implementations. "
|
|
"In addition, the set object acquires a :meth:`test_c_api` method."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:623
|
|
msgid "Sanity checks of the input arguments are added to frame creation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:625
|
|
msgid ""
|
|
"The storage for ints is initialized with a known invalid pattern to catch "
|
|
"reference to uninitialized digits."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:628
|
|
msgid ""
|
|
"Low-level tracing and extra exception checking are added to the runtime "
|
|
"virtual machine."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:631
|
|
msgid "Extra checks are added to the memory arena implementation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:633
|
|
msgid "Extra debugging is added to the thread module."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:635
|
|
msgid "There may be additional checks not mentioned here."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:637
|
|
msgid ""
|
|
"Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, "
|
|
"a circular doubly linked list of active objects is maintained by adding two "
|
|
"extra fields to every :c:type:`PyObject`. Total allocations are tracked as "
|
|
"well. Upon exit, all existing references are printed. (In interactive mode "
|
|
"this happens after every statement run by the interpreter.) Implied by :c:"
|
|
"macro:`Py_DEBUG`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:643
|
|
msgid ""
|
|
"Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source "
|
|
"distribution for more detailed information."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iter.rst:6
|
|
msgid "Iterator Protocol"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iter.rst:8
|
|
msgid "There are two functions specifically for working with iterators."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iter.rst:12
|
|
msgid "Return true if the object *o* supports the iterator protocol."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iter.rst:17
|
|
msgid ""
|
|
"Return the next value from the iteration *o*. The object must be an "
|
|
"iterator (it is up to the caller to check this). If there are no remaining "
|
|
"values, returns *NULL* with no exception set. If an error occurs while "
|
|
"retrieving the item, returns *NULL* and passes along the exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iter.rst:22
|
|
msgid ""
|
|
"To write a loop which iterates over an iterator, the C code should look "
|
|
"something like this::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iterator.rst:6
|
|
msgid "Iterator Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iterator.rst:8
|
|
msgid ""
|
|
"Python provides two general-purpose iterator objects. The first, a sequence "
|
|
"iterator, works with an arbitrary sequence supporting the :meth:"
|
|
"`__getitem__` method. The second works with a callable object and a "
|
|
"sentinel value, calling the callable for each item in the sequence, and "
|
|
"ending the iteration when the sentinel value is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iterator.rst:17
|
|
msgid ""
|
|
"Type object for iterator objects returned by :c:func:`PySeqIter_New` and the "
|
|
"one-argument form of the :func:`iter` built-in function for built-in "
|
|
"sequence types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iterator.rst:24
|
|
msgid "Return true if the type of *op* is :c:data:`PySeqIter_Type`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iterator.rst:29
|
|
msgid ""
|
|
"Return an iterator that works with a general sequence object, *seq*. The "
|
|
"iteration ends when the sequence raises :exc:`IndexError` for the "
|
|
"subscripting operation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iterator.rst:36
|
|
msgid ""
|
|
"Type object for iterator objects returned by :c:func:`PyCallIter_New` and "
|
|
"the two-argument form of the :func:`iter` built-in function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iterator.rst:42
|
|
msgid "Return true if the type of *op* is :c:data:`PyCallIter_Type`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/iterator.rst:47
|
|
msgid ""
|
|
"Return a new iterator. The first parameter, *callable*, can be any Python "
|
|
"callable object that can be called with no parameters; each call to it "
|
|
"should return the next item in the iteration. When *callable* returns a "
|
|
"value equal to *sentinel*, the iteration will be terminated."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:6
|
|
msgid "List Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:13
|
|
msgid "This subtype of :c:type:`PyObject` represents a Python list object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:18
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python list type. "
|
|
"This is the same object as :class:`list` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:24
|
|
msgid ""
|
|
"Return true if *p* is a list object or an instance of a subtype of the list "
|
|
"type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:30
|
|
msgid ""
|
|
"Return true if *p* is a list object, but not an instance of a subtype of the "
|
|
"list type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:36
|
|
msgid "Return a new list of length *len* on success, or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:40
|
|
msgid ""
|
|
"If *len* is greater than zero, the returned list object's items are set to "
|
|
"``NULL``. Thus you cannot use abstract API functions such as :c:func:"
|
|
"`PySequence_SetItem` or expose the object to Python code before setting all "
|
|
"items to a real object with :c:func:`PyList_SetItem`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:50
|
|
msgid ""
|
|
"Return the length of the list object in *list*; this is equivalent to "
|
|
"``len(list)`` on a list object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:56
|
|
msgid "Macro form of :c:func:`PyList_Size` without error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:61
|
|
msgid ""
|
|
"Return the object at position *index* in the list pointed to by *list*. The "
|
|
"position must be positive, indexing from the end of the list is not "
|
|
"supported. If *index* is out of bounds, return *NULL* and set an :exc:"
|
|
"`IndexError` exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:69
|
|
msgid "Macro form of :c:func:`PyList_GetItem` without error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:74
|
|
msgid ""
|
|
"Set the item at index *index* in list to *item*. Return ``0`` on success or "
|
|
"``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:79
|
|
msgid ""
|
|
"This function \"steals\" a reference to *item* and discards a reference to "
|
|
"an item already in the list at the affected position."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:85
|
|
msgid ""
|
|
"Macro form of :c:func:`PyList_SetItem` without error checking. This is "
|
|
"normally only used to fill in new lists where there is no previous content."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:90
|
|
msgid ""
|
|
"This macro \"steals\" a reference to *item*, and, unlike :c:func:"
|
|
"`PyList_SetItem`, does *not* discard a reference to any item that is being "
|
|
"replaced; any reference in *list* at position *i* will be leaked."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:98
|
|
msgid ""
|
|
"Insert the item *item* into list *list* in front of index *index*. Return "
|
|
"``0`` if successful; return ``-1`` and set an exception if unsuccessful. "
|
|
"Analogous to ``list.insert(index, item)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:105
|
|
msgid ""
|
|
"Append the object *item* at the end of list *list*. Return ``0`` if "
|
|
"successful; return ``-1`` and set an exception if unsuccessful. Analogous "
|
|
"to ``list.append(item)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:112
|
|
msgid ""
|
|
"Return a list of the objects in *list* containing the objects *between* "
|
|
"*low* and *high*. Return *NULL* and set an exception if unsuccessful. "
|
|
"Analogous to ``list[low:high]``. Negative indices, as when slicing from "
|
|
"Python, are not supported."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:120
|
|
msgid ""
|
|
"Set the slice of *list* between *low* and *high* to the contents of "
|
|
"*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may "
|
|
"be *NULL*, indicating the assignment of an empty list (slice deletion). "
|
|
"Return ``0`` on success, ``-1`` on failure. Negative indices, as when "
|
|
"slicing from Python, are not supported."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:129
|
|
msgid ""
|
|
"Sort the items of *list* in place. Return ``0`` on success, ``-1`` on "
|
|
"failure. This is equivalent to ``list.sort()``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:135
|
|
msgid ""
|
|
"Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on "
|
|
"failure. This is the equivalent of ``list.reverse()``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/list.rst:143
|
|
msgid ""
|
|
"Return a new tuple object containing the contents of *list*; equivalent to "
|
|
"``tuple(list)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:6
|
|
msgid "Integer Objects"
|
|
msgstr "Objets *Integer*"
|
|
|
|
#: ../Doc/c-api/long.rst:11
|
|
msgid ""
|
|
"All integers are implemented as \"long\" integer objects of arbitrary size."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:15
|
|
msgid "This subtype of :c:type:`PyObject` represents a Python integer object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:20
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python integer type. "
|
|
"This is the same object as :class:`int` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:26
|
|
msgid ""
|
|
"Return true if its argument is a :c:type:`PyLongObject` or a subtype of :c:"
|
|
"type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:32
|
|
msgid ""
|
|
"Return true if its argument is a :c:type:`PyLongObject`, but not a subtype "
|
|
"of :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:38
|
|
msgid ""
|
|
"Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:40
|
|
msgid ""
|
|
"The current implementation keeps an array of integer objects for all "
|
|
"integers between ``-5`` and ``256``, when you create an int in that range "
|
|
"you actually just get back a reference to the existing object. So it should "
|
|
"be possible to change the value of ``1``. I suspect the behaviour of Python "
|
|
"in this case is undefined. :-)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:49
|
|
msgid ""
|
|
"Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, "
|
|
"or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:55
|
|
msgid ""
|
|
"Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or "
|
|
"*NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:61
|
|
msgid ""
|
|
"Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or "
|
|
"*NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:67
|
|
msgid ""
|
|
"Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or "
|
|
"*NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:73
|
|
msgid ""
|
|
"Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long "
|
|
"long`, or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:79
|
|
msgid ""
|
|
"Return a new :c:type:`PyLongObject` object from the integer part of *v*, or "
|
|
"*NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:85
|
|
msgid ""
|
|
"Return a new :c:type:`PyLongObject` based on the string value in *str*, "
|
|
"which is interpreted according to the radix in *base*. If *pend* is non-"
|
|
"*NULL*, *\\*pend* will point to the first character in *str* which follows "
|
|
"the representation of the number. If *base* is ``0``, the radix will be "
|
|
"determined based on the leading characters of *str*: if *str* starts with "
|
|
"``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` "
|
|
"or ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or "
|
|
"``'0B'``, radix 2 will be used; otherwise radix 10 will be used. If *base* "
|
|
"is not ``0``, it must be between ``2`` and ``36``, inclusive. Leading "
|
|
"spaces are ignored. If there are no digits, :exc:`ValueError` will be "
|
|
"raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:99
|
|
msgid ""
|
|
"Convert a sequence of Unicode digits to a Python integer value. The Unicode "
|
|
"string is first encoded to a byte string using :c:func:"
|
|
"`PyUnicode_EncodeDecimal` and then converted using :c:func:"
|
|
"`PyLong_FromString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:105
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using PyLong_FromUnicodeObject()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:105
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyLong_FromUnicodeObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:110
|
|
msgid ""
|
|
"Convert a sequence of Unicode digits in the string *u* to a Python integer "
|
|
"value. The Unicode string is first encoded to a byte string using :c:func:"
|
|
"`PyUnicode_EncodeDecimal` and then converted using :c:func:"
|
|
"`PyLong_FromString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:120
|
|
msgid ""
|
|
"Create a Python integer from the pointer *p*. The pointer value can be "
|
|
"retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:131 ../Doc/c-api/long.rst:141
|
|
msgid ""
|
|
"Return a C :c:type:`long` representation of *obj*. If *obj* is not an "
|
|
"instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method "
|
|
"(if present) to convert it to a :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:135 ../Doc/c-api/long.rst:160
|
|
msgid ""
|
|
"Raise :exc:`OverflowError` if the value of *obj* is out of range for a :c:"
|
|
"type:`long`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:145
|
|
msgid ""
|
|
"If the value of *obj* is greater than :const:`LONG_MAX` or less than :const:"
|
|
"`LONG_MIN`, set *\\*overflow* to ``1`` or ``-1``, respectively, and return "
|
|
"``-1``; otherwise, set *\\*overflow* to ``0``. If any other exception "
|
|
"occurs set *\\*overflow* to ``0`` and return ``-1`` as usual."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:156 ../Doc/c-api/long.rst:166
|
|
msgid ""
|
|
"Return a C :c:type:`long long` representation of *obj*. If *obj* is not an "
|
|
"instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method "
|
|
"(if present) to convert it to a :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:170
|
|
msgid ""
|
|
"If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than :"
|
|
"const:`PY_LLONG_MIN`, set *\\*overflow* to ``1`` or ``-1``, respectively, "
|
|
"and return ``-1``; otherwise, set *\\*overflow* to ``0``. If any other "
|
|
"exception occurs set *\\*overflow* to ``0`` and return ``-1`` as usual."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:184
|
|
msgid ""
|
|
"Return a C :c:type:`Py_ssize_t` representation of *pylong*. *pylong* must "
|
|
"be an instance of :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:187
|
|
msgid ""
|
|
"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:"
|
|
"type:`Py_ssize_t`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:197
|
|
msgid ""
|
|
"Return a C :c:type:`unsigned long` representation of *pylong*. *pylong* "
|
|
"must be an instance of :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:200
|
|
msgid ""
|
|
"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:"
|
|
"type:`unsigned long`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:206
|
|
msgid ""
|
|
"Return a C :c:type:`size_t` representation of *pylong*. *pylong* must be an "
|
|
"instance of :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:209
|
|
msgid ""
|
|
"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:"
|
|
"type:`size_t`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:218
|
|
msgid ""
|
|
"Return a C :c:type:`unsigned long long` representation of *pylong*. "
|
|
"*pylong* must be an instance of :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:221
|
|
msgid ""
|
|
"Raise :exc:`OverflowError` if the value of *pylong* is out of range for an :"
|
|
"c:type:`unsigned long long`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:224
|
|
msgid ""
|
|
"A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:230
|
|
msgid ""
|
|
"Return a C :c:type:`unsigned long` representation of *obj*. If *obj* is not "
|
|
"an instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method "
|
|
"(if present) to convert it to a :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:234
|
|
msgid ""
|
|
"If the value of *obj* is out of range for an :c:type:`unsigned long`, return "
|
|
"the reduction of that value modulo :const:`ULONG_MAX + 1`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:240
|
|
msgid ""
|
|
"Return a C :c:type:`unsigned long long` representation of *obj*. If *obj* "
|
|
"is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__` "
|
|
"method (if present) to convert it to a :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:244
|
|
msgid ""
|
|
"If the value of *obj* is out of range for an :c:type:`unsigned long long`, "
|
|
"return the reduction of that value modulo :const:`PY_ULLONG_MAX + 1`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:250
|
|
msgid ""
|
|
"Return a C :c:type:`double` representation of *pylong*. *pylong* must be an "
|
|
"instance of :c:type:`PyLongObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:253
|
|
msgid ""
|
|
"Raise :exc:`OverflowError` if the value of *pylong* is out of range for a :c:"
|
|
"type:`double`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/long.rst:259
|
|
msgid ""
|
|
"Convert a Python integer *pylong* to a C :c:type:`void` pointer. If *pylong* "
|
|
"cannot be converted, an :exc:`OverflowError` will be raised. This is only "
|
|
"assured to produce a usable :c:type:`void` pointer for values created with :"
|
|
"c:func:`PyLong_FromVoidPtr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:6
|
|
msgid "Mapping Protocol"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:11
|
|
msgid ""
|
|
"Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. "
|
|
"This function always succeeds."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:20
|
|
msgid ""
|
|
"Returns the number of keys in object *o* on success, and ``-1`` on failure. "
|
|
"For objects that do not provide mapping protocol, this is equivalent to the "
|
|
"Python expression ``len(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:27 ../Doc/c-api/mapping.rst:33
|
|
msgid ""
|
|
"Remove the mapping for object *key* from the object *o*. Return ``-1`` on "
|
|
"failure. This is equivalent to the Python statement ``del o[key]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:39
|
|
msgid ""
|
|
"On success, return ``1`` if the mapping object has the key *key* and ``0`` "
|
|
"otherwise. This is equivalent to the Python expression ``key in o``. This "
|
|
"function always succeeds."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:46
|
|
msgid ""
|
|
"Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. "
|
|
"This is equivalent to the Python expression ``key in o``. This function "
|
|
"always succeeds."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:53
|
|
msgid ""
|
|
"On success, return a list or tuple of the keys in object *o*. On failure, "
|
|
"return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:59
|
|
msgid ""
|
|
"On success, return a list or tuple of the values in object *o*. On failure, "
|
|
"return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:65
|
|
msgid ""
|
|
"On success, return a list or tuple of the items in object *o*, where each "
|
|
"item is a tuple containing a key-value pair. On failure, return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:71 ../Doc/c-api/object.rst:385
|
|
msgid ""
|
|
"Return element of *o* corresponding to the object *key* or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``o[key]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/mapping.rst:77
|
|
msgid ""
|
|
"Map the object *key* to the value *v* in object *o*. Returns ``-1`` on "
|
|
"failure. This is the equivalent of the Python statement ``o[key] = v``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:6
|
|
msgid "Data marshalling support"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:8
|
|
msgid ""
|
|
"These routines allow C code to work with serialized objects using the same "
|
|
"data format as the :mod:`marshal` module. There are functions to write data "
|
|
"into the serialization format, and additional functions that can be used to "
|
|
"read the data back. Files used to store marshalled data must be opened in "
|
|
"binary mode."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:14
|
|
msgid "Numeric values are stored with the least significant byte first."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:16
|
|
msgid ""
|
|
"The module supports two versions of the data format: version 0 is the "
|
|
"historical version, version 1 shares interned strings in the file, and upon "
|
|
"unmarshalling. Version 2 uses a binary format for floating point numbers. "
|
|
"*Py_MARSHAL_VERSION* indicates the current file format (currently 2)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:24
|
|
msgid ""
|
|
"Marshal a :c:type:`long` integer, *value*, to *file*. This will only write "
|
|
"the least-significant 32 bits of *value*; regardless of the size of the "
|
|
"native :c:type:`long` type. *version* indicates the file format."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:31
|
|
msgid ""
|
|
"Marshal a Python object, *value*, to *file*. *version* indicates the file "
|
|
"format."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:37
|
|
msgid ""
|
|
"Return a string object containing the marshalled representation of *value*. "
|
|
"*version* indicates the file format."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:41
|
|
msgid "The following functions allow marshalled values to be read back in."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:43
|
|
msgid ""
|
|
"XXX What about error detection? It appears that reading past the end of the "
|
|
"file will always result in a negative numeric value (where that's relevant), "
|
|
"but it's not clear that negative values won't be handled properly when "
|
|
"there's no error. What's the right way to tell? Should only non-negative "
|
|
"values be written using these routines?"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:52
|
|
msgid ""
|
|
"Return a C :c:type:`long` from the data stream in a :c:type:`FILE\\*` opened "
|
|
"for reading. Only a 32-bit value can be read in using this function, "
|
|
"regardless of the native size of :c:type:`long`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:56 ../Doc/c-api/marshal.rst:65
|
|
msgid "On error, raise an exception and return ``-1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:61
|
|
msgid ""
|
|
"Return a C :c:type:`short` from the data stream in a :c:type:`FILE\\*` "
|
|
"opened for reading. Only a 16-bit value can be read in using this function, "
|
|
"regardless of the native size of :c:type:`short`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:70
|
|
msgid ""
|
|
"Return a Python object from the data stream in a :c:type:`FILE\\*` opened "
|
|
"for reading."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:73 ../Doc/c-api/marshal.rst:87
|
|
#: ../Doc/c-api/marshal.rst:96
|
|
msgid ""
|
|
"On error, sets the appropriate exception (:exc:`EOFError` or :exc:"
|
|
"`TypeError`) and returns *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:79
|
|
msgid ""
|
|
"Return a Python object from the data stream in a :c:type:`FILE\\*` opened "
|
|
"for reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function "
|
|
"assumes that no further objects will be read from the file, allowing it to "
|
|
"aggressively load file data into memory so that the de-serialization can "
|
|
"operate from data in memory rather than reading a byte at a time from the "
|
|
"file. Only use these variant if you are certain that you won't be reading "
|
|
"anything else from the file."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/marshal.rst:93
|
|
msgid ""
|
|
"Return a Python object from the data stream in a character buffer containing "
|
|
"*len* bytes pointed to by *string*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:8
|
|
msgid "Memory Management"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:17
|
|
msgid "Overview"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:19
|
|
msgid ""
|
|
"Memory management in Python involves a private heap containing all Python "
|
|
"objects and data structures. The management of this private heap is ensured "
|
|
"internally by the *Python memory manager*. The Python memory manager has "
|
|
"different components which deal with various dynamic storage management "
|
|
"aspects, like sharing, segmentation, preallocation or caching."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:25
|
|
msgid ""
|
|
"At the lowest level, a raw memory allocator ensures that there is enough "
|
|
"room in the private heap for storing all Python-related data by interacting "
|
|
"with the memory manager of the operating system. On top of the raw memory "
|
|
"allocator, several object-specific allocators operate on the same heap and "
|
|
"implement distinct memory management policies adapted to the peculiarities "
|
|
"of every object type. For example, integer objects are managed differently "
|
|
"within the heap than strings, tuples or dictionaries because integers imply "
|
|
"different storage requirements and speed/space tradeoffs. The Python memory "
|
|
"manager thus delegates some of the work to the object-specific allocators, "
|
|
"but ensures that the latter operate within the bounds of the private heap."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:36
|
|
msgid ""
|
|
"It is important to understand that the management of the Python heap is "
|
|
"performed by the interpreter itself and that the user has no control over "
|
|
"it, even if she regularly manipulates object pointers to memory blocks "
|
|
"inside that heap. The allocation of heap space for Python objects and other "
|
|
"internal buffers is performed on demand by the Python memory manager through "
|
|
"the Python/C API functions listed in this document."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:49
|
|
msgid ""
|
|
"To avoid memory corruption, extension writers should never try to operate on "
|
|
"Python objects with the functions exported by the C library: :c:func:"
|
|
"`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will "
|
|
"result in mixed calls between the C allocator and the Python memory manager "
|
|
"with fatal consequences, because they implement different algorithms and "
|
|
"operate on different heaps. However, one may safely allocate and release "
|
|
"memory blocks with the C library allocator for individual purposes, as shown "
|
|
"in the following example::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:68
|
|
msgid ""
|
|
"In this example, the memory request for the I/O buffer is handled by the C "
|
|
"library allocator. The Python memory manager is involved only in the "
|
|
"allocation of the string object returned as a result."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:72
|
|
msgid ""
|
|
"In most situations, however, it is recommended to allocate memory from the "
|
|
"Python heap specifically because the latter is under control of the Python "
|
|
"memory manager. For example, this is required when the interpreter is "
|
|
"extended with new object types written in C. Another reason for using the "
|
|
"Python heap is the desire to *inform* the Python memory manager about the "
|
|
"memory needs of the extension module. Even when the requested memory is used "
|
|
"exclusively for internal, highly-specific purposes, delegating all memory "
|
|
"requests to the Python memory manager causes the interpreter to have a more "
|
|
"accurate image of its memory footprint as a whole. Consequently, under "
|
|
"certain circumstances, the Python memory manager may or may not trigger "
|
|
"appropriate actions, like garbage collection, memory compaction or other "
|
|
"preventive procedures. Note that by using the C library allocator as shown "
|
|
"in the previous example, the allocated memory for the I/O buffer escapes "
|
|
"completely the Python memory manager."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:88
|
|
msgid ""
|
|
"The :envvar:`PYTHONMALLOC` environment variable can be used to configure the "
|
|
"memory allocators used by Python."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:91
|
|
msgid ""
|
|
"The :envvar:`PYTHONMALLOCSTATS` environment variable can be used to print "
|
|
"statistics of the :ref:`pymalloc memory allocator <pymalloc>` every time a "
|
|
"new pymalloc object arena is created, and on shutdown."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:97
|
|
msgid "Raw Memory Interface"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:99
|
|
msgid ""
|
|
"The following function sets are wrappers to the system allocator. These "
|
|
"functions are thread-safe, the :term:`GIL <global interpreter lock>` does "
|
|
"not need to be held."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:103
|
|
msgid ""
|
|
"The default raw memory block allocator uses the following functions: :c:func:"
|
|
"`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`; call "
|
|
"``malloc(1)`` (or ``calloc(1, 1)``) when requesting zero bytes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:111 ../Doc/c-api/memory.rst:181
|
|
msgid ""
|
|
"Allocates *n* bytes and returns a pointer of type :c:type:`void\\*` to the "
|
|
"allocated memory, or *NULL* if the request fails."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:114
|
|
msgid ""
|
|
"Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as "
|
|
"if ``PyMem_RawMalloc(1)`` had been called instead. The memory will not have "
|
|
"been initialized in any way."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:121 ../Doc/c-api/memory.rst:191
|
|
msgid ""
|
|
"Allocates *nelem* elements each whose size in bytes is *elsize* and returns "
|
|
"a pointer of type :c:type:`void\\*` to the allocated memory, or *NULL* if "
|
|
"the request fails. The memory is initialized to zeros."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:125
|
|
msgid ""
|
|
"Requesting zero elements or elements of size zero bytes returns a distinct "
|
|
"non-*NULL* pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been "
|
|
"called instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:134 ../Doc/c-api/memory.rst:204
|
|
msgid ""
|
|
"Resizes the memory block pointed to by *p* to *n* bytes. The contents will "
|
|
"be unchanged to the minimum of the old and the new sizes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:137
|
|
msgid ""
|
|
"If *p* is *NULL*, the call is equivalent to ``PyMem_RawMalloc(n)``; else if "
|
|
"*n* is equal to zero, the memory block is resized but is not freed, and the "
|
|
"returned pointer is non-*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:141
|
|
msgid ""
|
|
"Unless *p* is *NULL*, it must have been returned by a previous call to :c:"
|
|
"func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or :c:func:"
|
|
"`PyMem_RawCalloc`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:145
|
|
msgid ""
|
|
"If the request fails, :c:func:`PyMem_RawRealloc` returns *NULL* and *p* "
|
|
"remains a valid pointer to the previous memory area."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:151
|
|
msgid ""
|
|
"Frees the memory block pointed to by *p*, which must have been returned by a "
|
|
"previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or :c:"
|
|
"func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_Free(p)`` has been called "
|
|
"before, undefined behavior occurs."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:156 ../Doc/c-api/memory.rst:225
|
|
msgid "If *p* is *NULL*, no operation is performed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:162
|
|
msgid "Memory Interface"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:164
|
|
msgid ""
|
|
"The following function sets, modeled after the ANSI C standard, but "
|
|
"specifying behavior when requesting zero bytes, are available for allocating "
|
|
"and releasing memory from the Python heap."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:168
|
|
msgid ""
|
|
"By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:172
|
|
msgid ""
|
|
"The :term:`GIL <global interpreter lock>` must be held when using these "
|
|
"functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:177
|
|
msgid ""
|
|
"The default allocator is now pymalloc instead of system :c:func:`malloc`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:184
|
|
msgid ""
|
|
"Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as "
|
|
"if ``PyMem_Malloc(1)`` had been called instead. The memory will not have "
|
|
"been initialized in any way."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:195
|
|
msgid ""
|
|
"Requesting zero elements or elements of size zero bytes returns a distinct "
|
|
"non-*NULL* pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been called "
|
|
"instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:207
|
|
msgid ""
|
|
"If *p* is *NULL*, the call is equivalent to ``PyMem_Malloc(n)``; else if *n* "
|
|
"is equal to zero, the memory block is resized but is not freed, and the "
|
|
"returned pointer is non-*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:211
|
|
msgid ""
|
|
"Unless *p* is *NULL*, it must have been returned by a previous call to :c:"
|
|
"func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:214
|
|
msgid ""
|
|
"If the request fails, :c:func:`PyMem_Realloc` returns *NULL* and *p* remains "
|
|
"a valid pointer to the previous memory area."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:220
|
|
msgid ""
|
|
"Frees the memory block pointed to by *p*, which must have been returned by a "
|
|
"previous call to :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:"
|
|
"`PyMem_Calloc`. Otherwise, or if ``PyMem_Free(p)`` has been called before, "
|
|
"undefined behavior occurs."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:227
|
|
msgid ""
|
|
"The following type-oriented macros are provided for convenience. Note that "
|
|
"*TYPE* refers to any C type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:233
|
|
msgid ""
|
|
"Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes "
|
|
"of memory. Returns a pointer cast to :c:type:`TYPE\\*`. The memory will "
|
|
"not have been initialized in any way."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:240
|
|
msgid ""
|
|
"Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n * "
|
|
"sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\\*`. On "
|
|
"return, *p* will be a pointer to the new memory area, or *NULL* in the event "
|
|
"of failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:245
|
|
msgid ""
|
|
"This is a C preprocessor macro; *p* is always reassigned. Save the original "
|
|
"value of *p* to avoid losing memory when handling errors."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:251
|
|
msgid "Same as :c:func:`PyMem_Free`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:253
|
|
msgid ""
|
|
"In addition, the following macro sets are provided for calling the Python "
|
|
"memory allocator directly, without involving the C API functions listed "
|
|
"above. However, note that their use does not preserve binary compatibility "
|
|
"across Python versions and is therefore deprecated in extension modules."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:258
|
|
msgid "``PyMem_MALLOC(size)``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:259
|
|
msgid "``PyMem_NEW(type, size)``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:260
|
|
msgid "``PyMem_REALLOC(ptr, size)``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:261
|
|
msgid "``PyMem_RESIZE(ptr, type, size)``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:262
|
|
msgid "``PyMem_FREE(ptr)``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:263
|
|
msgid "``PyMem_DEL(ptr)``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:267
|
|
msgid "Customize Memory Allocators"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:273
|
|
msgid ""
|
|
"Structure used to describe a memory block allocator. The structure has four "
|
|
"fields:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:277 ../Doc/c-api/memory.rst:414
|
|
#: ../Doc/c-api/structures.rst:129 ../Doc/c-api/structures.rst:241
|
|
#: ../Doc/c-api/tuple.rst:145 ../Doc/c-api/tuple.rst:168
|
|
msgid "Field"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:279 ../Doc/c-api/memory.rst:416
|
|
msgid "``void *ctx``"
|
|
msgstr "``void *ctx``"
|
|
|
|
#: ../Doc/c-api/memory.rst:279 ../Doc/c-api/memory.rst:416
|
|
msgid "user context passed as first argument"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:281
|
|
msgid "``void* malloc(void *ctx, size_t size)``"
|
|
msgstr "``void* malloc(void *ctx, size_t size)``"
|
|
|
|
#: ../Doc/c-api/memory.rst:281
|
|
msgid "allocate a memory block"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:283
|
|
msgid "``void* calloc(void *ctx, size_t nelem, size_t elsize)``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:283
|
|
msgid "allocate a memory block initialized with zeros"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:286
|
|
msgid "``void* realloc(void *ctx, void *ptr, size_t new_size)``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:286
|
|
msgid "allocate or resize a memory block"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:288
|
|
msgid "``void free(void *ctx, void *ptr)``"
|
|
msgstr "``void free(void *ctx, void *ptr)``"
|
|
|
|
#: ../Doc/c-api/memory.rst:288
|
|
msgid "free a memory block"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:291
|
|
msgid ""
|
|
"The :c:type:`PyMemAllocator` structure was renamed to :c:type:"
|
|
"`PyMemAllocatorEx` and a new ``calloc`` field was added."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:298
|
|
msgid "Enum used to identify an allocator domain. Domains:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:302 ../Doc/c-api/memory.rst:311
|
|
#: ../Doc/c-api/memory.rst:320
|
|
msgid "Functions:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:304
|
|
msgid ":c:func:`PyMem_RawMalloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:305
|
|
msgid ":c:func:`PyMem_RawRealloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:306
|
|
msgid ":c:func:`PyMem_RawCalloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:307
|
|
msgid ":c:func:`PyMem_RawFree`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:313
|
|
msgid ":c:func:`PyMem_Malloc`,"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:314
|
|
msgid ":c:func:`PyMem_Realloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:315
|
|
msgid ":c:func:`PyMem_Calloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:316
|
|
msgid ":c:func:`PyMem_Free`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:322
|
|
msgid ":c:func:`PyObject_Malloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:323
|
|
msgid ":c:func:`PyObject_Realloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:324
|
|
msgid ":c:func:`PyObject_Calloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:325
|
|
msgid ":c:func:`PyObject_Free`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:329
|
|
msgid "Get the memory block allocator of the specified domain."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:334
|
|
msgid "Set the memory block allocator of the specified domain."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:336
|
|
msgid ""
|
|
"The new allocator must return a distinct non-NULL pointer when requesting "
|
|
"zero bytes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:339
|
|
msgid ""
|
|
"For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be thread-"
|
|
"safe: the :term:`GIL <global interpreter lock>` is not held when the "
|
|
"allocator is called."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:343
|
|
msgid ""
|
|
"If the new allocator is not a hook (does not call the previous allocator), "
|
|
"the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the "
|
|
"debug hooks on top on the new allocator."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:350
|
|
msgid "Setup hooks to detect bugs in the Python memory allocator functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:352
|
|
msgid ""
|
|
"Newly allocated memory is filled with the byte ``0xCB``, freed memory is "
|
|
"filled with the byte ``0xDB``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:355
|
|
msgid "Runtime checks:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:357
|
|
msgid ""
|
|
"Detect API violations, ex: :c:func:`PyObject_Free` called on a buffer "
|
|
"allocated by :c:func:`PyMem_Malloc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:359
|
|
msgid "Detect write before the start of the buffer (buffer underflow)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:360
|
|
msgid "Detect write after the end of the buffer (buffer overflow)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:361
|
|
msgid ""
|
|
"Check that the :term:`GIL <global interpreter lock>` is held when allocator "
|
|
"functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) and :"
|
|
"c:data:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) domains are called"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:366
|
|
msgid ""
|
|
"On error, the debug hooks use the :mod:`tracemalloc` module to get the "
|
|
"traceback where a memory block was allocated. The traceback is only "
|
|
"displayed if :mod:`tracemalloc` is tracing Python memory allocations and the "
|
|
"memory block was traced."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:371
|
|
msgid ""
|
|
"These hooks are installed by default if Python is compiled in debug mode. "
|
|
"The :envvar:`PYTHONMALLOC` environment variable can be used to install debug "
|
|
"hooks on a Python compiled in release mode."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:375
|
|
msgid ""
|
|
"This function now also works on Python compiled in release mode. On error, "
|
|
"the debug hooks now use :mod:`tracemalloc` to get the traceback where a "
|
|
"memory block was allocated. The debug hooks now also check if the GIL is "
|
|
"held when functions of :c:data:`PYMEM_DOMAIN_OBJ` and :c:data:"
|
|
"`PYMEM_DOMAIN_MEM` domains are called."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:386
|
|
msgid "The pymalloc allocator"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:388
|
|
msgid ""
|
|
"Python has a *pymalloc* allocator optimized for small objects (smaller or "
|
|
"equal to 512 bytes) with a short lifetime. It uses memory mappings called "
|
|
"\"arenas\" with a fixed size of 256 KB. It falls back to :c:func:"
|
|
"`PyMem_RawMalloc` and :c:func:`PyMem_RawRealloc` for allocations larger than "
|
|
"512 bytes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:393
|
|
msgid ""
|
|
"*pymalloc* is the default allocator of the :c:data:`PYMEM_DOMAIN_MEM` (ex: :"
|
|
"c:func:`PyObject_Malloc`) and :c:data:`PYMEM_DOMAIN_OBJ` (ex: :c:func:"
|
|
"`PyObject_Malloc`) domains."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:397
|
|
msgid "The arena allocator uses the following functions:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:399
|
|
msgid ":c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows,"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:400
|
|
msgid ":c:func:`mmap` and :c:func:`munmap` if available,"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:401
|
|
msgid ":c:func:`malloc` and :c:func:`free` otherwise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:404
|
|
msgid "Customize pymalloc Arena Allocator"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:410
|
|
msgid ""
|
|
"Structure used to describe an arena allocator. The structure has three "
|
|
"fields:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:418
|
|
msgid "``void* alloc(void *ctx, size_t size)``"
|
|
msgstr "``void* alloc(void *ctx, size_t size)``"
|
|
|
|
#: ../Doc/c-api/memory.rst:418
|
|
msgid "allocate an arena of size bytes"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:420
|
|
msgid "``void free(void *ctx, size_t size, void *ptr)``"
|
|
msgstr "``void free(void *ctx, size_t size, void *ptr)``"
|
|
|
|
#: ../Doc/c-api/memory.rst:420
|
|
msgid "free an arena"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:425
|
|
msgid "Get the arena allocator."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:429
|
|
msgid "Set the arena allocator."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:435
|
|
msgid "Examples"
|
|
msgstr "Exemples"
|
|
|
|
#: ../Doc/c-api/memory.rst:437
|
|
msgid ""
|
|
"Here is the example from section :ref:`memoryoverview`, rewritten so that "
|
|
"the I/O buffer is allocated from the Python heap by using the first function "
|
|
"set::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:450
|
|
msgid "The same code using the type-oriented function set::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:462
|
|
msgid ""
|
|
"Note that in the two examples above, the buffer is always manipulated via "
|
|
"functions belonging to the same set. Indeed, it is required to use the same "
|
|
"memory API family for a given memory block, so that the risk of mixing "
|
|
"different allocators is reduced to a minimum. The following code sequence "
|
|
"contains two errors, one of which is labeled as *fatal* because it mixes two "
|
|
"different allocators operating on different heaps. ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:477
|
|
msgid ""
|
|
"In addition to the functions aimed at handling raw memory blocks from the "
|
|
"Python heap, objects in Python are allocated and released with :c:func:"
|
|
"`PyObject_New`, :c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memory.rst:481
|
|
msgid ""
|
|
"These will be explained in the next chapter on defining and implementing new "
|
|
"object types in C."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memoryview.rst:9
|
|
msgid "MemoryView objects"
|
|
msgstr "Objets de type MemoryView"
|
|
|
|
#: ../Doc/c-api/memoryview.rst:11
|
|
msgid ""
|
|
"A :class:`memoryview` object exposes the C level :ref:`buffer interface "
|
|
"<bufferobjects>` as a Python object which can then be passed around like any "
|
|
"other object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memoryview.rst:18
|
|
msgid ""
|
|
"Create a memoryview object from an object that provides the buffer "
|
|
"interface. If *obj* supports writable buffer exports, the memoryview object "
|
|
"will be read/write, otherwise it may be either read-only or read/write at "
|
|
"the discretion of the exporter."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memoryview.rst:25
|
|
msgid ""
|
|
"Create a memoryview object using *mem* as the underlying buffer. *flags* can "
|
|
"be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memoryview.rst:32
|
|
msgid ""
|
|
"Create a memoryview object wrapping the given buffer structure *view*. For "
|
|
"simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred "
|
|
"function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memoryview.rst:38
|
|
msgid ""
|
|
"Create a memoryview object to a :term:`contiguous` chunk of memory (in "
|
|
"either 'C' or 'F'ortran *order*) from an object that defines the buffer "
|
|
"interface. If memory is contiguous, the memoryview object points to the "
|
|
"original memory. Otherwise, a copy is made and the memoryview points to a "
|
|
"new bytes object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memoryview.rst:47
|
|
msgid ""
|
|
"Return true if the object *obj* is a memoryview object. It is not currently "
|
|
"allowed to create subclasses of :class:`memoryview`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memoryview.rst:53
|
|
msgid ""
|
|
"Return a pointer to the memoryview's private copy of the exporter's buffer. "
|
|
"*mview* **must** be a memoryview instance; this macro doesn't check its "
|
|
"type, you must do it yourself or you will risk crashes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/memoryview.rst:59
|
|
msgid ""
|
|
"Return either a pointer to the exporting object that the memoryview is based "
|
|
"on or *NULL* if the memoryview has been created by one of the functions :c:"
|
|
"func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`. *mview* "
|
|
"**must** be a memoryview instance."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:6
|
|
msgid "Instance Method Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:10
|
|
msgid ""
|
|
"An instance method is a wrapper for a :c:data:`PyCFunction` and the new way "
|
|
"to bind a :c:data:`PyCFunction` to a class object. It replaces the former "
|
|
"call ``PyMethod_New(func, NULL, class)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:17
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python instance "
|
|
"method type. It is not exposed to Python programs."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:23
|
|
msgid ""
|
|
"Return true if *o* is an instance method object (has type :c:data:"
|
|
"`PyInstanceMethod_Type`). The parameter must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:29
|
|
msgid ""
|
|
"Return a new instance method object, with *func* being any callable object "
|
|
"*func* is the function that will be called when the instance method is "
|
|
"called."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:36
|
|
msgid "Return the function object associated with the instance method *im*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:41
|
|
msgid ""
|
|
"Macro version of :c:func:`PyInstanceMethod_Function` which avoids error "
|
|
"checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:47
|
|
msgid "Method Objects"
|
|
msgstr "Les objets méthode"
|
|
|
|
#: ../Doc/c-api/method.rst:51
|
|
msgid ""
|
|
"Methods are bound function objects. Methods are always bound to an instance "
|
|
"of a user-defined class. Unbound methods (methods bound to a class object) "
|
|
"are no longer available."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:60
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python method type. "
|
|
"This is exposed to Python programs as ``types.MethodType``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:66
|
|
msgid ""
|
|
"Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). "
|
|
"The parameter must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:72
|
|
msgid ""
|
|
"Return a new method object, with *func* being any callable object and *self* "
|
|
"the instance the method should be bound. *func* is the function that will be "
|
|
"called when the method is called. *self* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:79
|
|
msgid "Return the function object associated with the method *meth*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:84
|
|
msgid ""
|
|
"Macro version of :c:func:`PyMethod_Function` which avoids error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:89
|
|
msgid "Return the instance associated with the method *meth*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/method.rst:94
|
|
msgid "Macro version of :c:func:`PyMethod_Self` which avoids error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:6
|
|
msgid "Module Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:15
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python module type. "
|
|
"This is exposed to Python programs as ``types.ModuleType``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:21
|
|
msgid "Return true if *p* is a module object, or a subtype of a module object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:26
|
|
msgid ""
|
|
"Return true if *p* is a module object, but not a subtype of :c:data:"
|
|
"`PyModule_Type`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:39
|
|
msgid ""
|
|
"Return a new module object with the :attr:`__name__` attribute set to "
|
|
"*name*. The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, "
|
|
"and :attr:`__loader__` attributes are filled in (all but :attr:`__name__` "
|
|
"are set to ``None``); the caller is responsible for providing a :attr:"
|
|
"`__file__` attribute."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:47
|
|
msgid ":attr:`__package__` and :attr:`__loader__` are set to ``None``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:53
|
|
msgid ""
|
|
"Similar to :c:func:`PyImport_NewObject`, but the name is a UTF-8 encoded "
|
|
"string instead of a Unicode object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:61
|
|
msgid ""
|
|
"Return the dictionary object that implements *module*'s namespace; this "
|
|
"object is the same as the :attr:`~object.__dict__` attribute of the module "
|
|
"object. If *module* is not a module object (or a subtype of a module "
|
|
"object), :exc:`SystemError` is raised and *NULL* is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:66
|
|
msgid ""
|
|
"It is recommended extensions use other :c:func:`PyModule_\\*` and :c:func:"
|
|
"`PyObject_\\*` functions rather than directly manipulate a module's :attr:"
|
|
"`~object.__dict__`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:77
|
|
msgid ""
|
|
"Return *module*'s :attr:`__name__` value. If the module does not provide "
|
|
"one, or if it is not a string, :exc:`SystemError` is raised and *NULL* is "
|
|
"returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:85
|
|
msgid ""
|
|
"Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to "
|
|
"``'utf-8'``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:90
|
|
msgid ""
|
|
"Return the \"state\" of the module, that is, a pointer to the block of "
|
|
"memory allocated at module creation time, or *NULL*. See :c:member:"
|
|
"`PyModuleDef.m_size`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:97
|
|
msgid ""
|
|
"Return a pointer to the :c:type:`PyModuleDef` struct from which the module "
|
|
"was created, or *NULL* if the module wasn't created from a definition."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:107
|
|
msgid ""
|
|
"Return the name of the file from which *module* was loaded using *module*'s :"
|
|
"attr:`__file__` attribute. If this is not defined, or if it is not a "
|
|
"unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return "
|
|
"a reference to a Unicode object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:117
|
|
msgid ""
|
|
"Similar to :c:func:`PyModule_GetFilenameObject` but return the filename "
|
|
"encoded to 'utf-8'."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:120
|
|
msgid ""
|
|
":c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on "
|
|
"unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:128
|
|
msgid "Initializing C modules"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:130
|
|
msgid ""
|
|
"Modules objects are usually created from extension modules (shared libraries "
|
|
"which export an initialization function), or compiled-in modules (where the "
|
|
"initialization function is added using :c:func:`PyImport_AppendInittab`). "
|
|
"See :ref:`building` or :ref:`extending-with-embedding` for details."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:135
|
|
msgid ""
|
|
"The initialization function can either pass a module definition instance to :"
|
|
"c:func:`PyModule_Create`, and return the resulting module object, or request "
|
|
"\"multi-phase initialization\" by returning the definition struct itself."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:141
|
|
msgid ""
|
|
"The module definition struct, which holds all information needed to create a "
|
|
"module object. There is usually only one statically initialized variable of "
|
|
"this type for each module."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:147
|
|
msgid "Always initialize this member to :const:`PyModuleDef_HEAD_INIT`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:151
|
|
msgid "Name for the new module."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:155
|
|
msgid ""
|
|
"Docstring for the module; usually a docstring variable created with :c:func:"
|
|
"`PyDoc_STRVAR` is used."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:160
|
|
msgid ""
|
|
"Module state may be kept in a per-module memory area that can be retrieved "
|
|
"with :c:func:`PyModule_GetState`, rather than in static globals. This makes "
|
|
"modules safe for use in multiple sub-interpreters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:164
|
|
msgid ""
|
|
"This memory area is allocated based on *m_size* on module creation, and "
|
|
"freed when the module object is deallocated, after the :c:member:`m_free` "
|
|
"function has been called, if present."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:168
|
|
msgid ""
|
|
"Setting ``m_size`` to ``-1`` means that the module does not support sub-"
|
|
"interpreters, because it has global state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:171
|
|
msgid ""
|
|
"Setting it to a non-negative value means that the module can be re-"
|
|
"initialized and specifies the additional amount of memory it requires for "
|
|
"its state. Non-negative ``m_size`` is required for multi-phase "
|
|
"initialization."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:176
|
|
msgid "See :PEP:`3121` for more details."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:180
|
|
msgid ""
|
|
"A pointer to a table of module-level functions, described by :c:type:"
|
|
"`PyMethodDef` values. Can be *NULL* if no functions are present."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:185
|
|
msgid ""
|
|
"An array of slot definitions for multi-phase initialization, terminated by a "
|
|
"``{0, NULL}`` entry. When using single-phase initialization, *m_slots* must "
|
|
"be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:191
|
|
msgid ""
|
|
"Prior to version 3.5, this member was always set to *NULL*, and was defined "
|
|
"as:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:198
|
|
msgid ""
|
|
"A traversal function to call during GC traversal of the module object, or "
|
|
"*NULL* if not needed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:203
|
|
msgid ""
|
|
"A clear function to call during GC clearing of the module object, or *NULL* "
|
|
"if not needed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:208
|
|
msgid ""
|
|
"A function to call during deallocation of the module object, or *NULL* if "
|
|
"not needed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:212
|
|
msgid "Single-phase initialization"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:214
|
|
msgid ""
|
|
"The module initialization function may create and return the module object "
|
|
"directly. This is referred to as \"single-phase initialization\", and uses "
|
|
"one of the following two module creation functions:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:220
|
|
msgid ""
|
|
"Create a new module object, given the definition in *def*. This behaves "
|
|
"like :c:func:`PyModule_Create2` with *module_api_version* set to :const:"
|
|
"`PYTHON_API_VERSION`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:227
|
|
msgid ""
|
|
"Create a new module object, given the definition in *def*, assuming the API "
|
|
"version *module_api_version*. If that version does not match the version of "
|
|
"the running interpreter, a :exc:`RuntimeWarning` is emitted."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:233
|
|
msgid ""
|
|
"Most uses of this function should be using :c:func:`PyModule_Create` "
|
|
"instead; only use this if you are sure you need it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:236
|
|
msgid ""
|
|
"Before it is returned from in the initialization function, the resulting "
|
|
"module object is typically populated using functions like :c:func:"
|
|
"`PyModule_AddObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:242
|
|
msgid "Multi-phase initialization"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:244
|
|
msgid ""
|
|
"An alternate way to specify extensions is to request \"multi-phase "
|
|
"initialization\". Extension modules created this way behave more like Python "
|
|
"modules: the initialization is split between the *creation phase*, when the "
|
|
"module object is created, and the *execution phase*, when it is populated. "
|
|
"The distinction is similar to the :py:meth:`__new__` and :py:meth:`__init__` "
|
|
"methods of classes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:251
|
|
msgid ""
|
|
"Unlike modules created using single-phase initialization, these modules are "
|
|
"not singletons: if the *sys.modules* entry is removed and the module is re-"
|
|
"imported, a new module object is created, and the old module is subject to "
|
|
"normal garbage collection -- as with Python modules. By default, multiple "
|
|
"modules created from the same definition should be independent: changes to "
|
|
"one should not affect the others. This means that all state should be "
|
|
"specific to the module object (using e.g. using :c:func:"
|
|
"`PyModule_GetState`), or its contents (such as the module's :attr:`__dict__` "
|
|
"or individual classes created with :c:func:`PyType_FromSpec`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:261
|
|
msgid ""
|
|
"All modules created using multi-phase initialization are expected to "
|
|
"support :ref:`sub-interpreters <sub-interpreter-support>`. Making sure "
|
|
"multiple modules are independent is typically enough to achieve this."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:265
|
|
msgid ""
|
|
"To request multi-phase initialization, the initialization function "
|
|
"(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty :"
|
|
"c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef`` "
|
|
"instance must be initialized with the following function:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:272
|
|
msgid ""
|
|
"Ensures a module definition is a properly initialized Python object that "
|
|
"correctly reports its type and reference count."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:275
|
|
msgid "Returns *def* cast to ``PyObject*``, or *NULL* if an error occurred."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:279
|
|
msgid ""
|
|
"The *m_slots* member of the module definition must point to an array of "
|
|
"``PyModuleDef_Slot`` structures:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:286
|
|
msgid "A slot ID, chosen from the available values explained below."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:290
|
|
msgid "Value of the slot, whose meaning depends on the slot ID."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:294
|
|
msgid "The *m_slots* array must be terminated by a slot with id 0."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:296
|
|
msgid "The available slot types are:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:300
|
|
msgid ""
|
|
"Specifies a function that is called to create the module object itself. The "
|
|
"*value* pointer of this slot must point to a function of the signature:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:305
|
|
msgid ""
|
|
"The function receives a :py:class:`~importlib.machinery.ModuleSpec` "
|
|
"instance, as defined in :PEP:`451`, and the module definition. It should "
|
|
"return a new module object, or set an error and return *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:310
|
|
msgid ""
|
|
"This function should be kept minimal. In particular, it should not call "
|
|
"arbitrary Python code, as trying to import the same module again may result "
|
|
"in an infinite loop."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:314
|
|
msgid ""
|
|
"Multiple ``Py_mod_create`` slots may not be specified in one module "
|
|
"definition."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:317
|
|
msgid ""
|
|
"If ``Py_mod_create`` is not specified, the import machinery will create a "
|
|
"normal module object using :c:func:`PyModule_New`. The name is taken from "
|
|
"*spec*, not the definition, to allow extension modules to dynamically adjust "
|
|
"to their place in the module hierarchy and be imported under different names "
|
|
"through symlinks, all while sharing a single module definition."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:323
|
|
msgid ""
|
|
"There is no requirement for the returned object to be an instance of :c:type:"
|
|
"`PyModule_Type`. Any type can be used, as long as it supports setting and "
|
|
"getting import-related attributes. However, only ``PyModule_Type`` instances "
|
|
"may be returned if the ``PyModuleDef`` has non-*NULL* ``m_traverse``, "
|
|
"``m_clear``, ``m_free``; non-zero ``m_size``; or slots other than "
|
|
"``Py_mod_create``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:332
|
|
msgid ""
|
|
"Specifies a function that is called to *execute* the module. This is "
|
|
"equivalent to executing the code of a Python module: typically, this "
|
|
"function adds classes and constants to the module. The signature of the "
|
|
"function is:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:339
|
|
msgid ""
|
|
"If multiple ``Py_mod_exec`` slots are specified, they are processed in the "
|
|
"order they appear in the *m_slots* array."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:342
|
|
msgid "See :PEP:`489` for more details on multi-phase initialization."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:345
|
|
msgid "Low-level module creation functions"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:347
|
|
msgid ""
|
|
"The following functions are called under the hood when using multi-phase "
|
|
"initialization. They can be used directly, for example when creating module "
|
|
"objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and "
|
|
"``PyModule_ExecDef`` must be called to fully initialize a module."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:354
|
|
msgid ""
|
|
"Create a new module object, given the definition in *module* and the "
|
|
"ModuleSpec *spec*. This behaves like :c:func:`PyModule_FromDefAndSpec2` "
|
|
"with *module_api_version* set to :const:`PYTHON_API_VERSION`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:362
|
|
msgid ""
|
|
"Create a new module object, given the definition in *module* and the "
|
|
"ModuleSpec *spec*, assuming the API version *module_api_version*. If that "
|
|
"version does not match the version of the running interpreter, a :exc:"
|
|
"`RuntimeWarning` is emitted."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:369
|
|
msgid ""
|
|
"Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec` "
|
|
"instead; only use this if you are sure you need it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:376
|
|
msgid "Process any execution slots (:c:data:`Py_mod_exec`) given in *def*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:382
|
|
msgid ""
|
|
"Set the docstring for *module* to *docstring*. This function is called "
|
|
"automatically when creating a module from ``PyModuleDef``, using either "
|
|
"``PyModule_Create`` or ``PyModule_FromDefAndSpec``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:391
|
|
msgid ""
|
|
"Add the functions from the *NULL* terminated *functions* array to *module*. "
|
|
"Refer to the :c:type:`PyMethodDef` documentation for details on individual "
|
|
"entries (due to the lack of a shared module namespace, module level "
|
|
"\"functions\" implemented in C typically receive the module as their first "
|
|
"parameter, making them similar to instance methods on Python classes). This "
|
|
"function is called automatically when creating a module from "
|
|
"``PyModuleDef``, using either ``PyModule_Create`` or "
|
|
"``PyModule_FromDefAndSpec``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:403
|
|
msgid "Support functions"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:405
|
|
msgid ""
|
|
"The module initialization function (if using single phase initialization) or "
|
|
"a function called from a module execution slot (if using multi-phase "
|
|
"initialization), can use the following functions to help initialize the "
|
|
"module state:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:412
|
|
msgid ""
|
|
"Add an object to *module* as *name*. This is a convenience function which "
|
|
"can be used from the module's initialization function. This steals a "
|
|
"reference to *value*. Return ``-1`` on error, ``0`` on success."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:418
|
|
msgid ""
|
|
"Add an integer constant to *module* as *name*. This convenience function "
|
|
"can be used from the module's initialization function. Return ``-1`` on "
|
|
"error, ``0`` on success."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:425
|
|
msgid ""
|
|
"Add a string constant to *module* as *name*. This convenience function can "
|
|
"be used from the module's initialization function. The string *value* must "
|
|
"be *NULL*-terminated. Return ``-1`` on error, ``0`` on success."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:432
|
|
msgid ""
|
|
"Add an int constant to *module*. The name and the value are taken from "
|
|
"*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int "
|
|
"constant *AF_INET* with the value of *AF_INET* to *module*. Return ``-1`` on "
|
|
"error, ``0`` on success."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:440
|
|
msgid "Add a string constant to *module*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:444
|
|
msgid "Module lookup"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:446
|
|
msgid ""
|
|
"Single-phase initialization creates singleton modules that can be looked up "
|
|
"in the context of the current interpreter. This allows the module object to "
|
|
"be retrieved later with only a reference to the module definition."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:450
|
|
msgid ""
|
|
"These functions will not work on modules created using multi-phase "
|
|
"initialization, since multiple such modules can be created from a single "
|
|
"definition."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:455
|
|
msgid ""
|
|
"Returns the module object that was created from *def* for the current "
|
|
"interpreter. This method requires that the module object has been attached "
|
|
"to the interpreter state with :c:func:`PyState_AddModule` beforehand. In "
|
|
"case the corresponding module object is not found or has not been attached "
|
|
"to the interpreter state yet, it returns *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:462
|
|
msgid ""
|
|
"Attaches the module object passed to the function to the interpreter state. "
|
|
"This allows the module object to be accessible via :c:func:"
|
|
"`PyState_FindModule`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:465
|
|
msgid "Only effective on modules created using single-phase initialization."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/module.rst:471
|
|
msgid ""
|
|
"Removes the module object created from *def* from the interpreter state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/none.rst:6
|
|
msgid "The None Object"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/none.rst:10
|
|
msgid ""
|
|
"Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in "
|
|
"the Python/C API. Since ``None`` is a singleton, testing for object "
|
|
"identity (using ``==`` in C) is sufficient. There is no :c:func:"
|
|
"`PyNone_Check` function for the same reason."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/none.rst:18
|
|
msgid ""
|
|
"The Python ``None`` object, denoting lack of value. This object has no "
|
|
"methods. It needs to be treated just like any other object with respect to "
|
|
"reference counts."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/none.rst:25
|
|
msgid ""
|
|
"Properly handle returning :c:data:`Py_None` from within a C function (that "
|
|
"is, increment the reference count of None and return it.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:6
|
|
msgid "Number Protocol"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:11
|
|
msgid ""
|
|
"Returns ``1`` if the object *o* provides numeric protocols, and false "
|
|
"otherwise. This function always succeeds."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:17
|
|
msgid ""
|
|
"Returns the result of adding *o1* and *o2*, or *NULL* on failure. This is "
|
|
"the equivalent of the Python expression ``o1 + o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:23
|
|
msgid ""
|
|
"Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. "
|
|
"This is the equivalent of the Python expression ``o1 - o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:29
|
|
msgid ""
|
|
"Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. This "
|
|
"is the equivalent of the Python expression ``o1 * o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:35
|
|
msgid ""
|
|
"Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``o1 @ o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:43
|
|
msgid ""
|
|
"Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is "
|
|
"equivalent to the \"classic\" division of integers."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:49
|
|
msgid ""
|
|
"Return a reasonable approximation for the mathematical value of *o1* divided "
|
|
"by *o2*, or *NULL* on failure. The return value is \"approximate\" because "
|
|
"binary floating point numbers are approximate; it is not possible to "
|
|
"represent all real numbers in base two. This function can return a floating "
|
|
"point value when passed two integers."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:58
|
|
msgid ""
|
|
"Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. This "
|
|
"is the equivalent of the Python expression ``o1 % o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:66
|
|
msgid ""
|
|
"See the built-in function :func:`divmod`. Returns *NULL* on failure. This "
|
|
"is the equivalent of the Python expression ``divmod(o1, o2)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:74
|
|
msgid ""
|
|
"See the built-in function :func:`pow`. Returns *NULL* on failure. This is "
|
|
"the equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is "
|
|
"optional. If *o3* is to be ignored, pass :c:data:`Py_None` in its place "
|
|
"(passing *NULL* for *o3* would cause an illegal memory access)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:82
|
|
msgid ""
|
|
"Returns the negation of *o* on success, or *NULL* on failure. This is the "
|
|
"equivalent of the Python expression ``-o``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:88
|
|
msgid ""
|
|
"Returns *o* on success, or *NULL* on failure. This is the equivalent of the "
|
|
"Python expression ``+o``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:96
|
|
msgid ""
|
|
"Returns the absolute value of *o*, or *NULL* on failure. This is the "
|
|
"equivalent of the Python expression ``abs(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:102
|
|
msgid ""
|
|
"Returns the bitwise negation of *o* on success, or *NULL* on failure. This "
|
|
"is the equivalent of the Python expression ``~o``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:108
|
|
msgid ""
|
|
"Returns the result of left shifting *o1* by *o2* on success, or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``o1 << o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:114
|
|
msgid ""
|
|
"Returns the result of right shifting *o1* by *o2* on success, or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``o1 >> o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:120
|
|
msgid ""
|
|
"Returns the \"bitwise and\" of *o1* and *o2* on success and *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``o1 & o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:126
|
|
msgid ""
|
|
"Returns the \"bitwise exclusive or\" of *o1* by *o2* on success, or *NULL* "
|
|
"on failure. This is the equivalent of the Python expression ``o1 ^ o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:132
|
|
msgid ""
|
|
"Returns the \"bitwise or\" of *o1* and *o2* on success, or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``o1 | o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:138
|
|
msgid ""
|
|
"Returns the result of adding *o1* and *o2*, or *NULL* on failure. The "
|
|
"operation is done *in-place* when *o1* supports it. This is the equivalent "
|
|
"of the Python statement ``o1 += o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:145
|
|
msgid ""
|
|
"Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. The "
|
|
"operation is done *in-place* when *o1* supports it. This is the equivalent "
|
|
"of the Python statement ``o1 -= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:152
|
|
msgid ""
|
|
"Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. The "
|
|
"operation is done *in-place* when *o1* supports it. This is the equivalent "
|
|
"of the Python statement ``o1 *= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:159
|
|
msgid ""
|
|
"Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on "
|
|
"failure. The operation is done *in-place* when *o1* supports it. This is "
|
|
"the equivalent of the Python statement ``o1 @= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:168
|
|
msgid ""
|
|
"Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on "
|
|
"failure. The operation is done *in-place* when *o1* supports it. This is "
|
|
"the equivalent of the Python statement ``o1 //= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:175
|
|
msgid ""
|
|
"Return a reasonable approximation for the mathematical value of *o1* divided "
|
|
"by *o2*, or *NULL* on failure. The return value is \"approximate\" because "
|
|
"binary floating point numbers are approximate; it is not possible to "
|
|
"represent all real numbers in base two. This function can return a floating "
|
|
"point value when passed two integers. The operation is done *in-place* when "
|
|
"*o1* supports it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:184
|
|
msgid ""
|
|
"Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. The "
|
|
"operation is done *in-place* when *o1* supports it. This is the equivalent "
|
|
"of the Python statement ``o1 %= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:193
|
|
msgid ""
|
|
"See the built-in function :func:`pow`. Returns *NULL* on failure. The "
|
|
"operation is done *in-place* when *o1* supports it. This is the equivalent "
|
|
"of the Python statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-"
|
|
"place variant of ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, "
|
|
"pass :c:data:`Py_None` in its place (passing *NULL* for *o3* would cause an "
|
|
"illegal memory access)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:202
|
|
msgid ""
|
|
"Returns the result of left shifting *o1* by *o2* on success, or *NULL* on "
|
|
"failure. The operation is done *in-place* when *o1* supports it. This is "
|
|
"the equivalent of the Python statement ``o1 <<= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:209
|
|
msgid ""
|
|
"Returns the result of right shifting *o1* by *o2* on success, or *NULL* on "
|
|
"failure. The operation is done *in-place* when *o1* supports it. This is "
|
|
"the equivalent of the Python statement ``o1 >>= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:216
|
|
msgid ""
|
|
"Returns the \"bitwise and\" of *o1* and *o2* on success and *NULL* on "
|
|
"failure. The operation is done *in-place* when *o1* supports it. This is "
|
|
"the equivalent of the Python statement ``o1 &= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:223
|
|
msgid ""
|
|
"Returns the \"bitwise exclusive or\" of *o1* by *o2* on success, or *NULL* "
|
|
"on failure. The operation is done *in-place* when *o1* supports it. This "
|
|
"is the equivalent of the Python statement ``o1 ^= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:230
|
|
msgid ""
|
|
"Returns the \"bitwise or\" of *o1* and *o2* on success, or *NULL* on "
|
|
"failure. The operation is done *in-place* when *o1* supports it. This is "
|
|
"the equivalent of the Python statement ``o1 |= o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:239
|
|
msgid ""
|
|
"Returns the *o* converted to an integer object on success, or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``int(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:247
|
|
msgid ""
|
|
"Returns the *o* converted to a float object on success, or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``float(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:253
|
|
msgid ""
|
|
"Returns the *o* converted to a Python int on success or *NULL* with a :exc:"
|
|
"`TypeError` exception raised on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:259
|
|
msgid ""
|
|
"Returns the integer *n* converted to base *base* as a string. The *base* "
|
|
"argument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, the returned "
|
|
"string is prefixed with a base marker of ``'0b'``, ``'0o'``, or ``'0x'``, "
|
|
"respectively. If *n* is not a Python int, it is converted with :c:func:"
|
|
"`PyNumber_Index` first."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:268
|
|
msgid ""
|
|
"Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an "
|
|
"integer. If the call fails, an exception is raised and -1 is returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:271
|
|
msgid ""
|
|
"If *o* can be converted to a Python int but the attempt to convert to a "
|
|
"Py_ssize_t value would raise an :exc:`OverflowError`, then the *exc* "
|
|
"argument is the type of exception that will be raised (usually :exc:"
|
|
"`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the "
|
|
"exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a "
|
|
"negative integer or *PY_SSIZE_T_MAX* for a positive integer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/number.rst:281
|
|
msgid ""
|
|
"Returns True if *o* is an index integer (has the nb_index slot of the "
|
|
"tp_as_number structure filled in)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objbuffer.rst:4
|
|
msgid "Old Buffer Protocol"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objbuffer.rst:8
|
|
msgid ""
|
|
"These functions were part of the \"old buffer protocol\" API in Python 2. In "
|
|
"Python 3, this protocol doesn't exist anymore but the functions are still "
|
|
"exposed to ease porting 2.x code. They act as a compatibility wrapper "
|
|
"around the :ref:`new buffer protocol <bufferobjects>`, but they don't give "
|
|
"you control over the lifetime of the resources acquired when a buffer is "
|
|
"exported."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objbuffer.rst:15
|
|
msgid ""
|
|
"Therefore, it is recommended that you call :c:func:`PyObject_GetBuffer` (or "
|
|
"the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the :c:func:"
|
|
"`PyArg_ParseTuple` family of functions) to get a buffer view over an object, "
|
|
"and :c:func:`PyBuffer_Release` when the buffer view can be released."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objbuffer.rst:23
|
|
msgid ""
|
|
"Returns a pointer to a read-only memory location usable as character-based "
|
|
"input. The *obj* argument must support the single-segment character buffer "
|
|
"interface. On success, returns ``0``, sets *buffer* to the memory location "
|
|
"and *buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:"
|
|
"`TypeError` on error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objbuffer.rst:32
|
|
msgid ""
|
|
"Returns a pointer to a read-only memory location containing arbitrary data. "
|
|
"The *obj* argument must support the single-segment readable buffer "
|
|
"interface. On success, returns ``0``, sets *buffer* to the memory location "
|
|
"and *buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:"
|
|
"`TypeError` on error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objbuffer.rst:41
|
|
msgid ""
|
|
"Returns ``1`` if *o* supports the single-segment readable buffer interface. "
|
|
"Otherwise returns ``0``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objbuffer.rst:47
|
|
msgid ""
|
|
"Returns a pointer to a writable memory location. The *obj* argument must "
|
|
"support the single-segment, character buffer interface. On success, returns "
|
|
"``0``, sets *buffer* to the memory location and *buffer_len* to the buffer "
|
|
"length. Returns ``-1`` and sets a :exc:`TypeError` on error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:6
|
|
msgid "Object Protocol"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:11
|
|
msgid ""
|
|
"The ``NotImplemented`` singleton, used to signal that an operation is not "
|
|
"implemented for the given type combination."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:17
|
|
msgid ""
|
|
"Properly handle returning :c:data:`Py_NotImplemented` from within a C "
|
|
"function (that is, increment the reference count of NotImplemented and "
|
|
"return it)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:24
|
|
msgid ""
|
|
"Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags "
|
|
"argument is used to enable certain printing options. The only option "
|
|
"currently supported is :const:`Py_PRINT_RAW`; if given, the :func:`str` of "
|
|
"the object is written instead of the :func:`repr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:32 ../Doc/c-api/object.rst:39
|
|
msgid ""
|
|
"Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. "
|
|
"This is equivalent to the Python expression ``hasattr(o, attr_name)``. This "
|
|
"function always succeeds."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:46
|
|
msgid ""
|
|
"Retrieve an attribute named *attr_name* from object *o*. Returns the "
|
|
"attribute value on success, or *NULL* on failure. This is the equivalent of "
|
|
"the Python expression ``o.attr_name``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:53
|
|
msgid ""
|
|
"Retrieve an attribute named *attr_name* from object *o*. Returns the "
|
|
"attribute value on success, or *NULL* on failure. This is the equivalent of "
|
|
"the Python expression ``o.attr_name``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:60
|
|
msgid ""
|
|
"Generic attribute getter function that is meant to be put into a type "
|
|
"object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary "
|
|
"of classes in the object's MRO as well as an attribute in the object's :attr:"
|
|
"`~object.__dict__` (if present). As outlined in :ref:`descriptors`, data "
|
|
"descriptors take preference over instance attributes, while non-data "
|
|
"descriptors don't. Otherwise, an :exc:`AttributeError` is raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:70 ../Doc/c-api/object.rst:81
|
|
msgid ""
|
|
"Set the value of the attribute named *attr_name*, for object *o*, to the "
|
|
"value *v*. Raise an exception and return ``-1`` on failure; return ``0`` on "
|
|
"success. This is the equivalent of the Python statement ``o.attr_name = v``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:75
|
|
msgid ""
|
|
"If *v* is *NULL*, the attribute is deleted, however this feature is "
|
|
"deprecated in favour of using :c:func:`PyObject_DelAttr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:86
|
|
msgid ""
|
|
"If *v* is *NULL*, the attribute is deleted, however this feature is "
|
|
"deprecated in favour of using :c:func:`PyObject_DelAttrString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:92
|
|
msgid ""
|
|
"Generic attribute setter and deleter function that is meant to be put into a "
|
|
"type object's :c:member:`~PyTypeObject.tp_setattro` slot. It looks for a "
|
|
"data descriptor in the dictionary of classes in the object's MRO, and if "
|
|
"found it takes preference over setting or deleting the attribute in the "
|
|
"instance dictionary. Otherwise, the attribute is set or deleted in the "
|
|
"object's :attr:`~object.__dict__` (if present). On success, ``0`` is "
|
|
"returned, otherwise an :exc:`AttributeError` is raised and ``-1`` is "
|
|
"returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:104 ../Doc/c-api/object.rst:110
|
|
msgid ""
|
|
"Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on "
|
|
"failure. This is the equivalent of the Python statement ``del o.attr_name``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:116
|
|
msgid ""
|
|
"A generic implementation for the getter of a ``__dict__`` descriptor. It "
|
|
"creates the dictionary if necessary."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:124
|
|
msgid ""
|
|
"A generic implementation for the setter of a ``__dict__`` descriptor. This "
|
|
"implementation does not allow the dictionary to be deleted."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:132
|
|
msgid ""
|
|
"Compare the values of *o1* and *o2* using the operation specified by *opid*, "
|
|
"which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, :const:"
|
|
"`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, ``<=``, "
|
|
"``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of the "
|
|
"Python expression ``o1 op o2``, where ``op`` is the operator corresponding "
|
|
"to *opid*. Returns the value of the comparison on success, or *NULL* on "
|
|
"failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:142
|
|
msgid ""
|
|
"Compare the values of *o1* and *o2* using the operation specified by *opid*, "
|
|
"which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, :const:"
|
|
"`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, ``<=``, "
|
|
"``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error, "
|
|
"``0`` if the result is false, ``1`` otherwise. This is the equivalent of the "
|
|
"Python expression ``o1 op o2``, where ``op`` is the operator corresponding "
|
|
"to *opid*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:151
|
|
msgid ""
|
|
"If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool` "
|
|
"will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:158
|
|
msgid ""
|
|
"Compute a string representation of object *o*. Returns the string "
|
|
"representation on success, *NULL* on failure. This is the equivalent of the "
|
|
"Python expression ``repr(o)``. Called by the :func:`repr` built-in function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:162 ../Doc/c-api/object.rst:186
|
|
#: ../Doc/c-api/veryhigh.rst:332
|
|
msgid ""
|
|
"This function now includes a debug assertion to help ensure that it does not "
|
|
"silently discard an active exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:170
|
|
msgid ""
|
|
"As :c:func:`PyObject_Repr`, compute a string representation of object *o*, "
|
|
"but escape the non-ASCII characters in the string returned by :c:func:"
|
|
"`PyObject_Repr` with ``\\x``, ``\\u`` or ``\\U`` escapes. This generates a "
|
|
"string similar to that returned by :c:func:`PyObject_Repr` in Python 2. "
|
|
"Called by the :func:`ascii` built-in function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:181
|
|
msgid ""
|
|
"Compute a string representation of object *o*. Returns the string "
|
|
"representation on success, *NULL* on failure. This is the equivalent of the "
|
|
"Python expression ``str(o)``. Called by the :func:`str` built-in function "
|
|
"and, therefore, by the :func:`print` function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:194
|
|
msgid ""
|
|
"Compute a bytes representation of object *o*. *NULL* is returned on failure "
|
|
"and a bytes object on success. This is equivalent to the Python expression "
|
|
"``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``, a TypeError "
|
|
"is raised when *o* is an integer instead of a zero-initialized bytes object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:203
|
|
msgid ""
|
|
"Return ``1`` if the class *derived* is identical to or derived from the "
|
|
"class *cls*, otherwise return ``0``. In case of an error, return ``-1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:206 ../Doc/c-api/object.rst:225
|
|
msgid ""
|
|
"If *cls* is a tuple, the check will be done against every entry in *cls*. "
|
|
"The result will be ``1`` when at least one of the checks returns ``1``, "
|
|
"otherwise it will be ``0``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:210
|
|
msgid ""
|
|
"If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to "
|
|
"determine the subclass status as described in :pep:`3119`. Otherwise, "
|
|
"*derived* is a subclass of *cls* if it is a direct or indirect subclass, i."
|
|
"e. contained in ``cls.__mro__``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:215
|
|
msgid ""
|
|
"Normally only class objects, i.e. instances of :class:`type` or a derived "
|
|
"class, are considered classes. However, objects can override this by having "
|
|
"a :attr:`__bases__` attribute (which must be a tuple of base classes)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:222
|
|
msgid ""
|
|
"Return ``1`` if *inst* is an instance of the class *cls* or a subclass of "
|
|
"*cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:229
|
|
msgid ""
|
|
"If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to "
|
|
"determine the subclass status as described in :pep:`3119`. Otherwise, "
|
|
"*inst* is an instance of *cls* if its class is a subclass of *cls*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:233
|
|
msgid ""
|
|
"An instance *inst* can override what is considered its class by having a :"
|
|
"attr:`__class__` attribute."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:236
|
|
msgid ""
|
|
"An object *cls* can override if it is considered a class, and what its base "
|
|
"classes are, by having a :attr:`__bases__` attribute (which must be a tuple "
|
|
"of base classes)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:243
|
|
msgid ""
|
|
"Determine if the object *o* is callable. Return ``1`` if the object is "
|
|
"callable and ``0`` otherwise. This function always succeeds."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:249
|
|
msgid ""
|
|
"Call a callable Python object *callable_object*, with arguments given by the "
|
|
"tuple *args*, and named arguments given by the dictionary *kw*. If no named "
|
|
"arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an "
|
|
"empty tuple if no arguments are needed. Returns the result of the call on "
|
|
"success, or *NULL* on failure. This is the equivalent of the Python "
|
|
"expression ``callable_object(*args, **kw)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:259
|
|
msgid ""
|
|
"Call a callable Python object *callable_object*, with arguments given by the "
|
|
"tuple *args*. If no arguments are needed, then *args* may be *NULL*. "
|
|
"Returns the result of the call on success, or *NULL* on failure. This is "
|
|
"the equivalent of the Python expression ``callable_object(*args)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:267
|
|
msgid ""
|
|
"Call a callable Python object *callable*, with a variable number of C "
|
|
"arguments. The C arguments are described using a :c:func:`Py_BuildValue` "
|
|
"style format string. The format may be *NULL*, indicating that no arguments "
|
|
"are provided. Returns the result of the call on success, or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression "
|
|
"``callable(*args)``. Note that if you only pass :c:type:`PyObject \\*` "
|
|
"args, :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:275
|
|
msgid "The type of *format* was changed from ``char *``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:281
|
|
msgid ""
|
|
"Call the method named *method* of object *o* with a variable number of C "
|
|
"arguments. The C arguments are described by a :c:func:`Py_BuildValue` "
|
|
"format string that should produce a tuple. The format may be *NULL*, "
|
|
"indicating that no arguments are provided. Returns the result of the call on "
|
|
"success, or *NULL* on failure. This is the equivalent of the Python "
|
|
"expression ``o.method(args)``. Note that if you only pass :c:type:`PyObject "
|
|
"\\*` args, :c:func:`PyObject_CallMethodObjArgs` is a faster alternative."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:289
|
|
msgid "The types of *method* and *format* were changed from ``char *``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:295
|
|
msgid ""
|
|
"Call a callable Python object *callable*, with a variable number of :c:type:"
|
|
"`PyObject\\*` arguments. The arguments are provided as a variable number of "
|
|
"parameters followed by *NULL*. Returns the result of the call on success, or "
|
|
"*NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:303
|
|
msgid ""
|
|
"Calls a method of the object *o*, where the name of the method is given as a "
|
|
"Python string object in *name*. It is called with a variable number of :c:"
|
|
"type:`PyObject\\*` arguments. The arguments are provided as a variable "
|
|
"number of parameters followed by *NULL*. Returns the result of the call on "
|
|
"success, or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:314
|
|
msgid ""
|
|
"Compute and return the hash value of an object *o*. On failure, return "
|
|
"``-1``. This is the equivalent of the Python expression ``hash(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:317
|
|
msgid ""
|
|
"The return type is now Py_hash_t. This is a signed integer the same size as "
|
|
"Py_ssize_t."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:324
|
|
msgid ""
|
|
"Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and "
|
|
"return ``-1``. This function receives special treatment when stored in a "
|
|
"``tp_hash`` slot, allowing a type to explicitly indicate to the interpreter "
|
|
"that it is not hashable."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:332
|
|
msgid ""
|
|
"Returns ``1`` if the object *o* is considered to be true, and ``0`` "
|
|
"otherwise. This is equivalent to the Python expression ``not not o``. On "
|
|
"failure, return ``-1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:339
|
|
msgid ""
|
|
"Returns ``0`` if the object *o* is considered to be true, and ``1`` "
|
|
"otherwise. This is equivalent to the Python expression ``not o``. On "
|
|
"failure, return ``-1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:348
|
|
msgid ""
|
|
"When *o* is non-*NULL*, returns a type object corresponding to the object "
|
|
"type of object *o*. On failure, raises :exc:`SystemError` and returns "
|
|
"*NULL*. This is equivalent to the Python expression ``type(o)``. This "
|
|
"function increments the reference count of the return value. There's really "
|
|
"no reason to use this function instead of the common expression ``o-"
|
|
">ob_type``, which returns a pointer of type :c:type:`PyTypeObject\\*`, "
|
|
"except when the incremented reference count is needed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:359
|
|
msgid ""
|
|
"Return true if the object *o* is of type *type* or a subtype of *type*. "
|
|
"Both parameters must be non-*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:368
|
|
msgid ""
|
|
"Return the length of object *o*. If the object *o* provides either the "
|
|
"sequence and mapping protocols, the sequence length is returned. On error, "
|
|
"``-1`` is returned. This is the equivalent to the Python expression "
|
|
"``len(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:375
|
|
msgid ""
|
|
"Return an estimated length for the object *o*. First try to return its "
|
|
"actual length, then an estimate using :meth:`~object.__length_hint__`, and "
|
|
"finally return the default value. On error return ``-1``. This is the "
|
|
"equivalent to the Python expression ``operator.length_hint(o, default)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:391
|
|
msgid ""
|
|
"Map the object *key* to the value *v*. Raise an exception and return ``-1`` "
|
|
"on failure; return ``0`` on success. This is the equivalent of the Python "
|
|
"statement ``o[key] = v``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:398
|
|
msgid ""
|
|
"Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is "
|
|
"the equivalent of the Python statement ``del o[key]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:404
|
|
msgid ""
|
|
"This is equivalent to the Python expression ``dir(o)``, returning a "
|
|
"(possibly empty) list of strings appropriate for the object argument, or "
|
|
"*NULL* if there was an error. If the argument is *NULL*, this is like the "
|
|
"Python ``dir()``, returning the names of the current locals; in this case, "
|
|
"if no execution frame is active then *NULL* is returned but :c:func:"
|
|
"`PyErr_Occurred` will return false."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/object.rst:413
|
|
msgid ""
|
|
"This is equivalent to the Python expression ``iter(o)``. It returns a new "
|
|
"iterator for the object argument, or the object itself if the object is "
|
|
"already an iterator. Raises :exc:`TypeError` and returns *NULL* if the "
|
|
"object cannot be iterated."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objimpl.rst:7
|
|
msgid "Object Implementation Support"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/objimpl.rst:9
|
|
msgid ""
|
|
"This chapter describes the functions, types, and macros used when defining "
|
|
"new object types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:8
|
|
msgid "Reference Counting"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:10
|
|
msgid ""
|
|
"The macros in this section are used for managing reference counts of Python "
|
|
"objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:16
|
|
msgid ""
|
|
"Increment the reference count for object *o*. The object must not be "
|
|
"*NULL*; if you aren't sure that it isn't *NULL*, use :c:func:`Py_XINCREF`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:22
|
|
msgid ""
|
|
"Increment the reference count for object *o*. The object may be *NULL*, in "
|
|
"which case the macro has no effect."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:28
|
|
msgid ""
|
|
"Decrement the reference count for object *o*. The object must not be "
|
|
"*NULL*; if you aren't sure that it isn't *NULL*, use :c:func:`Py_XDECREF`. "
|
|
"If the reference count reaches zero, the object's type's deallocation "
|
|
"function (which must not be *NULL*) is invoked."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:35
|
|
msgid ""
|
|
"The deallocation function can cause arbitrary Python code to be invoked (e."
|
|
"g. when a class instance with a :meth:`__del__` method is deallocated). "
|
|
"While exceptions in such code are not propagated, the executed code has free "
|
|
"access to all Python global variables. This means that any object that is "
|
|
"reachable from a global variable should be in a consistent state before :c:"
|
|
"func:`Py_DECREF` is invoked. For example, code to delete an object from a "
|
|
"list should copy a reference to the deleted object in a temporary variable, "
|
|
"update the list data structure, and then call :c:func:`Py_DECREF` for the "
|
|
"temporary variable."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:47
|
|
msgid ""
|
|
"Decrement the reference count for object *o*. The object may be *NULL*, in "
|
|
"which case the macro has no effect; otherwise the effect is the same as for :"
|
|
"c:func:`Py_DECREF`, and the same warning applies."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:54
|
|
msgid ""
|
|
"Decrement the reference count for object *o*. The object may be *NULL*, in "
|
|
"which case the macro has no effect; otherwise the effect is the same as for :"
|
|
"c:func:`Py_DECREF`, except that the argument is also set to *NULL*. The "
|
|
"warning for :c:func:`Py_DECREF` does not apply with respect to the object "
|
|
"passed because the macro carefully uses a temporary variable and sets the "
|
|
"argument to *NULL* before decrementing its reference count."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:61
|
|
msgid ""
|
|
"It is a good idea to use this macro whenever decrementing the value of a "
|
|
"variable that might be traversed during garbage collection."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:65
|
|
msgid ""
|
|
"The following functions are for runtime dynamic embedding of Python: "
|
|
"``Py_IncRef(PyObject *o)``, ``Py_DecRef(PyObject *o)``. They are simply "
|
|
"exported function versions of :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF`, "
|
|
"respectively."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/refcounting.rst:70
|
|
msgid ""
|
|
"The following functions or macros are only for use within the interpreter "
|
|
"core: :c:func:`_Py_Dealloc`, :c:func:`_Py_ForgetReference`, :c:func:"
|
|
"`_Py_NewReference`, as well as the global variable :c:data:`_Py_RefTotal`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/reflection.rst:6
|
|
msgid "Reflection"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/reflection.rst:10
|
|
msgid ""
|
|
"Return a dictionary of the builtins in the current execution frame, or the "
|
|
"interpreter of the thread state if no frame is currently executing."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/reflection.rst:16
|
|
msgid ""
|
|
"Return a dictionary of the local variables in the current execution frame, "
|
|
"or *NULL* if no frame is currently executing."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/reflection.rst:22
|
|
msgid ""
|
|
"Return a dictionary of the global variables in the current execution frame, "
|
|
"or *NULL* if no frame is currently executing."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/reflection.rst:28
|
|
msgid ""
|
|
"Return the current thread state's frame, which is *NULL* if no frame is "
|
|
"currently executing."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/reflection.rst:34
|
|
msgid "Return the line number that *frame* is currently executing."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/reflection.rst:39
|
|
msgid ""
|
|
"Return the name of *func* if it is a function, class or instance object, "
|
|
"else the name of *func*\\s type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/reflection.rst:45
|
|
msgid ""
|
|
"Return a description string, depending on the type of *func*. Return values "
|
|
"include \"()\" for functions and methods, \" constructor\", \" instance\", "
|
|
"and \" object\". Concatenated with the result of :c:func:"
|
|
"`PyEval_GetFuncName`, the result will be a description of *func*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:6
|
|
msgid "Sequence Protocol"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:11
|
|
msgid ""
|
|
"Return ``1`` if the object provides sequence protocol, and ``0`` otherwise. "
|
|
"This function always succeeds."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:20
|
|
msgid ""
|
|
"Returns the number of objects in sequence *o* on success, and ``-1`` on "
|
|
"failure. For objects that do not provide sequence protocol, this is "
|
|
"equivalent to the Python expression ``len(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:27
|
|
msgid ""
|
|
"Return the concatenation of *o1* and *o2* on success, and *NULL* on failure. "
|
|
"This is the equivalent of the Python expression ``o1 + o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:33
|
|
msgid ""
|
|
"Return the result of repeating sequence object *o* *count* times, or *NULL* "
|
|
"on failure. This is the equivalent of the Python expression ``o * count``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:39
|
|
msgid ""
|
|
"Return the concatenation of *o1* and *o2* on success, and *NULL* on failure. "
|
|
"The operation is done *in-place* when *o1* supports it. This is the "
|
|
"equivalent of the Python expression ``o1 += o2``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:46
|
|
msgid ""
|
|
"Return the result of repeating sequence object *o* *count* times, or *NULL* "
|
|
"on failure. The operation is done *in-place* when *o* supports it. This is "
|
|
"the equivalent of the Python expression ``o *= count``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:53
|
|
msgid ""
|
|
"Return the *i*\\ th element of *o*, or *NULL* on failure. This is the "
|
|
"equivalent of the Python expression ``o[i]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:59
|
|
msgid ""
|
|
"Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on "
|
|
"failure. This is the equivalent of the Python expression ``o[i1:i2]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:65
|
|
msgid ""
|
|
"Assign object *v* to the *i*\\ th element of *o*. Raise an exception and "
|
|
"return ``-1`` on failure; return ``0`` on success. This is the equivalent "
|
|
"of the Python statement ``o[i] = v``. This function *does not* steal a "
|
|
"reference to *v*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:70
|
|
msgid ""
|
|
"If *v* is *NULL*, the element is deleted, however this feature is deprecated "
|
|
"in favour of using :c:func:`PySequence_DelItem`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:76
|
|
msgid ""
|
|
"Delete the *i*\\ th element of object *o*. Returns ``-1`` on failure. This "
|
|
"is the equivalent of the Python statement ``del o[i]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:82
|
|
msgid ""
|
|
"Assign the sequence object *v* to the slice in sequence object *o* from *i1* "
|
|
"to *i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:88
|
|
msgid ""
|
|
"Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` "
|
|
"on failure. This is the equivalent of the Python statement ``del o[i1:i2]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:94
|
|
msgid ""
|
|
"Return the number of occurrences of *value* in *o*, that is, return the "
|
|
"number of keys for which ``o[key] == value``. On failure, return ``-1``. "
|
|
"This is equivalent to the Python expression ``o.count(value)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:101
|
|
msgid ""
|
|
"Determine if *o* contains *value*. If an item in *o* is equal to *value*, "
|
|
"return ``1``, otherwise return ``0``. On error, return ``-1``. This is "
|
|
"equivalent to the Python expression ``value in o``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:108
|
|
msgid ""
|
|
"Return the first index *i* for which ``o[i] == value``. On error, return "
|
|
"``-1``. This is equivalent to the Python expression ``o.index(value)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:114
|
|
msgid ""
|
|
"Return a list object with the same contents as the sequence or iterable *o*, "
|
|
"or *NULL* on failure. The returned list is guaranteed to be new. This is "
|
|
"equivalent to the Python expression ``list(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:123
|
|
msgid ""
|
|
"Return a tuple object with the same contents as the arbitrary sequence *o* "
|
|
"or *NULL* on failure. If *o* is a tuple, a new reference will be returned, "
|
|
"otherwise a tuple will be constructed with the appropriate contents. This "
|
|
"is equivalent to the Python expression ``tuple(o)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:131
|
|
msgid ""
|
|
"Return the sequence *o* as a list, unless it is already a tuple or list, in "
|
|
"which case *o* is returned. Use :c:func:`PySequence_Fast_GET_ITEM` to "
|
|
"access the members of the result. Returns *NULL* on failure. If the object "
|
|
"is not a sequence, raises :exc:`TypeError` with *m* as the message text."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:139
|
|
msgid ""
|
|
"Return the *i*\\ th element of *o*, assuming that *o* was returned by :c:"
|
|
"func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:145
|
|
msgid ""
|
|
"Return the underlying array of PyObject pointers. Assumes that *o* was "
|
|
"returned by :c:func:`PySequence_Fast` and *o* is not *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:148
|
|
msgid ""
|
|
"Note, if a list gets resized, the reallocation may relocate the items array. "
|
|
"So, only use the underlying array pointer in contexts where the sequence "
|
|
"cannot change."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:155
|
|
msgid ""
|
|
"Return the *i*\\ th element of *o* or *NULL* on failure. Macro form of :c:"
|
|
"func:`PySequence_GetItem` but without checking that :c:func:"
|
|
"`PySequence_Check` on *o* is true and without adjustment for negative "
|
|
"indices."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sequence.rst:163
|
|
msgid ""
|
|
"Returns the length of *o*, assuming that *o* was returned by :c:func:"
|
|
"`PySequence_Fast` and that *o* is not *NULL*. The size can also be gotten "
|
|
"by calling :c:func:`PySequence_Size` on *o*, but :c:func:"
|
|
"`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list or "
|
|
"tuple."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:6
|
|
msgid "Set Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:15
|
|
msgid ""
|
|
"This section details the public API for :class:`set` and :class:`frozenset` "
|
|
"objects. Any functionality not listed below is best accessed using the "
|
|
"either the abstract object protocol (including :c:func:"
|
|
"`PyObject_CallMethod`, :c:func:`PyObject_RichCompareBool`, :c:func:"
|
|
"`PyObject_Hash`, :c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:"
|
|
"`PyObject_Print`, and :c:func:`PyObject_GetIter`) or the abstract number "
|
|
"protocol (including :c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:"
|
|
"func:`PyNumber_Or`, :c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`, :"
|
|
"c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and :c:func:"
|
|
"`PyNumber_InPlaceXor`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:29
|
|
msgid ""
|
|
"This subtype of :c:type:`PyObject` is used to hold the internal data for "
|
|
"both :class:`set` and :class:`frozenset` objects. It is like a :c:type:"
|
|
"`PyDictObject` in that it is a fixed size for small sets (much like tuple "
|
|
"storage) and will point to a separate, variable sized block of memory for "
|
|
"medium and large sized sets (much like list storage). None of the fields of "
|
|
"this structure should be considered public and are subject to change. All "
|
|
"access should be done through the documented API rather than by manipulating "
|
|
"the values in the structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:40
|
|
msgid ""
|
|
"This is an instance of :c:type:`PyTypeObject` representing the Python :class:"
|
|
"`set` type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:46
|
|
msgid ""
|
|
"This is an instance of :c:type:`PyTypeObject` representing the Python :class:"
|
|
"`frozenset` type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:49
|
|
msgid ""
|
|
"The following type check macros work on pointers to any Python object. "
|
|
"Likewise, the constructor functions work with any iterable Python object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:55
|
|
msgid ""
|
|
"Return true if *p* is a :class:`set` object or an instance of a subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:59
|
|
msgid ""
|
|
"Return true if *p* is a :class:`frozenset` object or an instance of a "
|
|
"subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:64
|
|
msgid ""
|
|
"Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or "
|
|
"an instance of a subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:70
|
|
msgid ""
|
|
"Return true if *p* is a :class:`set` object or a :class:`frozenset` object "
|
|
"but not an instance of a subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:76
|
|
msgid ""
|
|
"Return true if *p* is a :class:`frozenset` object but not an instance of a "
|
|
"subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:82
|
|
msgid ""
|
|
"Return a new :class:`set` containing objects returned by the *iterable*. "
|
|
"The *iterable* may be *NULL* to create a new empty set. Return the new set "
|
|
"on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is "
|
|
"not actually iterable. The constructor is also useful for copying a set "
|
|
"(``c=set(s)``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:91
|
|
msgid ""
|
|
"Return a new :class:`frozenset` containing objects returned by the "
|
|
"*iterable*. The *iterable* may be *NULL* to create a new empty frozenset. "
|
|
"Return the new set on success or *NULL* on failure. Raise :exc:`TypeError` "
|
|
"if *iterable* is not actually iterable."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:97
|
|
msgid ""
|
|
"The following functions and macros are available for instances of :class:"
|
|
"`set` or :class:`frozenset` or instances of their subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:105
|
|
msgid ""
|
|
"Return the length of a :class:`set` or :class:`frozenset` object. Equivalent "
|
|
"to ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a :"
|
|
"class:`set`, :class:`frozenset`, or an instance of a subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:112
|
|
msgid "Macro form of :c:func:`PySet_Size` without error checking."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:117
|
|
msgid ""
|
|
"Return 1 if found, 0 if not found, and -1 if an error is encountered. "
|
|
"Unlike the Python :meth:`__contains__` method, this function does not "
|
|
"automatically convert unhashable sets into temporary frozensets. Raise a :"
|
|
"exc:`TypeError` if the *key* is unhashable. Raise :exc:`PyExc_SystemError` "
|
|
"if *anyset* is not a :class:`set`, :class:`frozenset`, or an instance of a "
|
|
"subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:126
|
|
msgid ""
|
|
"Add *key* to a :class:`set` instance. Also works with :class:`frozenset` "
|
|
"instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the "
|
|
"values of brand new frozensets before they are exposed to other code). "
|
|
"Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if the *key* "
|
|
"is unhashable. Raise a :exc:`MemoryError` if there is no room to grow. "
|
|
"Raise a :exc:`SystemError` if *set* is not an instance of :class:`set` or "
|
|
"its subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:135
|
|
msgid ""
|
|
"The following functions are available for instances of :class:`set` or its "
|
|
"subtypes but not for instances of :class:`frozenset` or its subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:141
|
|
msgid ""
|
|
"Return 1 if found and removed, 0 if not found (no action taken), and -1 if "
|
|
"an error is encountered. Does not raise :exc:`KeyError` for missing keys. "
|
|
"Raise a :exc:`TypeError` if the *key* is unhashable. Unlike the Python :"
|
|
"meth:`~set.discard` method, this function does not automatically convert "
|
|
"unhashable sets into temporary frozensets. Raise :exc:`PyExc_SystemError` if "
|
|
"*set* is not an instance of :class:`set` or its subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:151
|
|
msgid ""
|
|
"Return a new reference to an arbitrary object in the *set*, and removes the "
|
|
"object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if "
|
|
"the set is empty. Raise a :exc:`SystemError` if *set* is not an instance of :"
|
|
"class:`set` or its subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/set.rst:159
|
|
msgid "Empty an existing set of all elements."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:6
|
|
msgid "Slice Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:11
|
|
msgid ""
|
|
"The type object for slice objects. This is the same as :class:`slice` in "
|
|
"the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:17
|
|
msgid "Return true if *ob* is a slice object; *ob* must not be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:22
|
|
msgid ""
|
|
"Return a new slice object with the given values. The *start*, *stop*, and "
|
|
"*step* parameters are used as the values of the slice object attributes of "
|
|
"the same names. Any of the values may be *NULL*, in which case the ``None`` "
|
|
"will be used for the corresponding attribute. Return *NULL* if the new "
|
|
"object could not be allocated."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:31
|
|
msgid ""
|
|
"Retrieve the start, stop and step indices from the slice object *slice*, "
|
|
"assuming a sequence of length *length*. Treats indices greater than *length* "
|
|
"as errors."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:35
|
|
msgid ""
|
|
"Returns 0 on success and -1 on error with no exception set (unless one of "
|
|
"the indices was not :const:`None` and failed to be converted to an integer, "
|
|
"in which case -1 is returned with an exception set)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:39
|
|
msgid "You probably do not want to use this function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:41 ../Doc/c-api/slice.rst:56
|
|
msgid ""
|
|
"The parameter type for the *slice* parameter was ``PySliceObject*`` before."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:48
|
|
msgid ""
|
|
"Usable replacement for :c:func:`PySlice_GetIndices`. Retrieve the start, "
|
|
"stop, and step indices from the slice object *slice* assuming a sequence of "
|
|
"length *length*, and store the length of the slice in *slicelength*. Out of "
|
|
"bounds indices are clipped in a manner consistent with the handling of "
|
|
"normal slices."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/slice.rst:54
|
|
msgid "Returns 0 on success and -1 on error with exception set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/stable.rst:7
|
|
msgid "Stable Application Binary Interface"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/stable.rst:9
|
|
msgid ""
|
|
"Traditionally, the C API of Python will change with every release. Most "
|
|
"changes will be source-compatible, typically by only adding API, rather than "
|
|
"changing existing API or removing API (although some interfaces do get "
|
|
"removed after being deprecated first)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/stable.rst:14
|
|
msgid ""
|
|
"Unfortunately, the API compatibility does not extend to binary compatibility "
|
|
"(the ABI). The reason is primarily the evolution of struct definitions, "
|
|
"where addition of a new field, or changing the type of a field, might not "
|
|
"break the API, but can break the ABI. As a consequence, extension modules "
|
|
"need to be recompiled for every Python release (although an exception is "
|
|
"possible on Unix when none of the affected interfaces are used). In "
|
|
"addition, on Windows, extension modules link with a specific pythonXY.dll "
|
|
"and need to be recompiled to link with a newer one."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/stable.rst:23
|
|
msgid ""
|
|
"Since Python 3.2, a subset of the API has been declared to guarantee a "
|
|
"stable ABI. Extension modules wishing to use this API (called \"limited API"
|
|
"\") need to define ``Py_LIMITED_API``. A number of interpreter details then "
|
|
"become hidden from the extension module; in return, a module is built that "
|
|
"works on any 3.x version (x>=2) without recompilation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/stable.rst:29
|
|
msgid ""
|
|
"In some cases, the stable ABI needs to be extended with new functions. "
|
|
"Extension modules wishing to use these new APIs need to set "
|
|
"``Py_LIMITED_API`` to the ``PY_VERSION_HEX`` value (see :ref:"
|
|
"`apiabiversion`) of the minimum Python version they want to support (e.g. "
|
|
"``0x03030000`` for Python 3.3). Such modules will work on all subsequent "
|
|
"Python releases, but fail to load (because of missing symbols) on the older "
|
|
"releases."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/stable.rst:36
|
|
msgid ""
|
|
"As of Python 3.2, the set of functions available to the limited API is "
|
|
"documented in :pep:`384`. In the C API documentation, API elements that are "
|
|
"not part of the limited API are marked as \"Not part of the limited API.\""
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:6
|
|
msgid "Common Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:8
|
|
msgid ""
|
|
"There are a large number of structures which are used in the definition of "
|
|
"object types for Python. This section describes these structures and how "
|
|
"they are used."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:12
|
|
msgid ""
|
|
"All Python objects ultimately share a small number of fields at the "
|
|
"beginning of the object's representation in memory. These are represented "
|
|
"by the :c:type:`PyObject` and :c:type:`PyVarObject` types, which are "
|
|
"defined, in turn, by the expansions of some macros also used, whether "
|
|
"directly or indirectly, in the definition of all other Python objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:21
|
|
msgid ""
|
|
"All object types are extensions of this type. This is a type which contains "
|
|
"the information Python needs to treat a pointer to an object as an object. "
|
|
"In a normal \"release\" build, it contains only the object's reference count "
|
|
"and a pointer to the corresponding type object. Nothing is actually declared "
|
|
"to be a :c:type:`PyObject`, but every pointer to a Python object can be cast "
|
|
"to a :c:type:`PyObject*`. Access to the members must be done by using the "
|
|
"macros :c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:33
|
|
msgid ""
|
|
"This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size` "
|
|
"field. This is only used for objects that have some notion of *length*. "
|
|
"This type does not often appear in the Python/C API. Access to the members "
|
|
"must be done by using the macros :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, "
|
|
"and :c:macro:`Py_SIZE`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:42
|
|
msgid ""
|
|
"This is a macro used when declaring new types which represent objects "
|
|
"without a varying length. The PyObject_HEAD macro expands to::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:47
|
|
msgid "See documentation of :c:type:`PyObject` above."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:52
|
|
msgid ""
|
|
"This is a macro used when declaring new types which represent objects with a "
|
|
"length that varies from instance to instance. The PyObject_VAR_HEAD macro "
|
|
"expands to::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:58
|
|
msgid "See documentation of :c:type:`PyVarObject` above."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:63
|
|
msgid ""
|
|
"This macro is used to access the :attr:`ob_type` member of a Python object. "
|
|
"It expands to::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:71
|
|
msgid ""
|
|
"This macro is used to access the :attr:`ob_refcnt` member of a Python "
|
|
"object. It expands to::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:80
|
|
msgid ""
|
|
"This macro is used to access the :attr:`ob_size` member of a Python object. "
|
|
"It expands to::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:88
|
|
msgid ""
|
|
"This is a macro which expands to initialization values for a new :c:type:"
|
|
"`PyObject` type. This macro expands to::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:97
|
|
msgid ""
|
|
"This is a macro which expands to initialization values for a new :c:type:"
|
|
"`PyVarObject` type, including the :attr:`ob_size` field. This macro expands "
|
|
"to::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:107
|
|
msgid ""
|
|
"Type of the functions used to implement most Python callables in C. "
|
|
"Functions of this type take two :c:type:`PyObject\\*` parameters and return "
|
|
"one such value. If the return value is *NULL*, an exception shall have been "
|
|
"set. If not *NULL*, the return value is interpreted as the return value of "
|
|
"the function as exposed in Python. The function must return a new reference."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:117
|
|
msgid ""
|
|
"Type of the functions used to implement Python callables in C that take "
|
|
"keyword arguments: they take three :c:type:`PyObject\\*` parameters and "
|
|
"return one such value. See :c:type:`PyCFunction` above for the meaning of "
|
|
"the return value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:125
|
|
msgid ""
|
|
"Structure used to describe a method of an extension type. This structure "
|
|
"has four fields:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:129 ../Doc/c-api/structures.rst:241
|
|
#: ../Doc/c-api/tuple.rst:145 ../Doc/c-api/tuple.rst:168
|
|
msgid "C Type"
|
|
msgstr "Type C"
|
|
|
|
#: ../Doc/c-api/structures.rst:131
|
|
msgid ":attr:`ml_name`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:131 ../Doc/c-api/structures.rst:139
|
|
#: ../Doc/c-api/structures.rst:243 ../Doc/c-api/structures.rst:256
|
|
#: ../Doc/c-api/structures.rst:272
|
|
msgid "char \\*"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:131
|
|
msgid "name of the method"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:133
|
|
msgid ":attr:`ml_meth`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:133
|
|
msgid "PyCFunction"
|
|
msgstr "PyCFunction"
|
|
|
|
#: ../Doc/c-api/structures.rst:133
|
|
msgid "pointer to the C implementation"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:136
|
|
msgid ":attr:`ml_flags`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:136
|
|
msgid "flag bits indicating how the call should be constructed"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:139
|
|
msgid ":attr:`ml_doc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:139 ../Doc/c-api/structures.rst:256
|
|
msgid "points to the contents of the docstring"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:143
|
|
msgid ""
|
|
"The :attr:`ml_meth` is a C function pointer. The functions may be of "
|
|
"different types, but they always return :c:type:`PyObject\\*`. If the "
|
|
"function is not of the :c:type:`PyCFunction`, the compiler will require a "
|
|
"cast in the method table. Even though :c:type:`PyCFunction` defines the "
|
|
"first parameter as :c:type:`PyObject\\*`, it is common that the method "
|
|
"implementation uses the specific C type of the *self* object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:150
|
|
msgid ""
|
|
"The :attr:`ml_flags` field is a bitfield which can include the following "
|
|
"flags. The individual flags indicate either a calling convention or a "
|
|
"binding convention. Of the calling convention flags, only :const:"
|
|
"`METH_VARARGS` and :const:`METH_KEYWORDS` can be combined (but note that :"
|
|
"const:`METH_KEYWORDS` alone is equivalent to ``METH_VARARGS | "
|
|
"METH_KEYWORDS``). Any of the calling convention flags can be combined with a "
|
|
"binding flag."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:160
|
|
msgid ""
|
|
"This is the typical calling convention, where the methods have the type :c:"
|
|
"type:`PyCFunction`. The function expects two :c:type:`PyObject\\*` values. "
|
|
"The first one is the *self* object for methods; for module functions, it is "
|
|
"the module object. The second parameter (often called *args*) is a tuple "
|
|
"object representing all arguments. This parameter is typically processed "
|
|
"using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:170
|
|
msgid ""
|
|
"Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. "
|
|
"The function expects three parameters: *self*, *args*, and a dictionary of "
|
|
"all the keyword arguments. The flag is typically combined with :const:"
|
|
"`METH_VARARGS`, and the parameters are typically processed using :c:func:"
|
|
"`PyArg_ParseTupleAndKeywords`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:179
|
|
msgid ""
|
|
"Methods without parameters don't need to check whether arguments are given "
|
|
"if they are listed with the :const:`METH_NOARGS` flag. They need to be of "
|
|
"type :c:type:`PyCFunction`. The first parameter is typically named *self* "
|
|
"and will hold a reference to the module or object instance. In all cases "
|
|
"the second parameter will be *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:188
|
|
msgid ""
|
|
"Methods with a single object argument can be listed with the :const:`METH_O` "
|
|
"flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``\"O\"`` "
|
|
"argument. They have the type :c:type:`PyCFunction`, with the *self* "
|
|
"parameter, and a :c:type:`PyObject\\*` parameter representing the single "
|
|
"argument."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:194
|
|
msgid ""
|
|
"These two constants are not used to indicate the calling convention but the "
|
|
"binding when use with methods of classes. These may not be used for "
|
|
"functions defined for modules. At most one of these flags may be set for "
|
|
"any given method."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:204
|
|
msgid ""
|
|
"The method will be passed the type object as the first parameter rather than "
|
|
"an instance of the type. This is used to create *class methods*, similar to "
|
|
"what is created when using the :func:`classmethod` built-in function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:214
|
|
msgid ""
|
|
"The method will be passed *NULL* as the first parameter rather than an "
|
|
"instance of the type. This is used to create *static methods*, similar to "
|
|
"what is created when using the :func:`staticmethod` built-in function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:218
|
|
msgid ""
|
|
"One other constant controls whether a method is loaded in place of another "
|
|
"definition with the same method name."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:224
|
|
msgid ""
|
|
"The method will be loaded in place of existing definitions. Without "
|
|
"*METH_COEXIST*, the default is to skip repeated definitions. Since slot "
|
|
"wrappers are loaded before the method table, the existence of a "
|
|
"*sq_contains* slot, for example, would generate a wrapped method named :meth:"
|
|
"`__contains__` and preclude the loading of a corresponding PyCFunction with "
|
|
"the same name. With the flag defined, the PyCFunction will be loaded in "
|
|
"place of the wrapper object and will co-exist with the slot. This is "
|
|
"helpful because calls to PyCFunctions are optimized more than wrapper object "
|
|
"calls."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:237
|
|
msgid ""
|
|
"Structure which describes an attribute of a type which corresponds to a C "
|
|
"struct member. Its fields are:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:243
|
|
msgid ":attr:`name`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:243
|
|
msgid "name of the member"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:245
|
|
msgid ":attr:`type`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:245
|
|
msgid "the type of the member in the C struct"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:248
|
|
msgid ":attr:`offset`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:248
|
|
msgid ""
|
|
"the offset in bytes that the member is located on the type's object struct"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:252
|
|
msgid ":attr:`flags`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:252
|
|
msgid "flag bits indicating if the field should be read-only or writable"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:256
|
|
msgid ":attr:`doc`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:260
|
|
msgid ""
|
|
":attr:`type` can be one of many ``T_`` macros corresponding to various C "
|
|
"types. When the member is accessed in Python, it will be converted to the "
|
|
"equivalent Python type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:265
|
|
msgid "Macro name"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:265
|
|
msgid "C type"
|
|
msgstr "Type C"
|
|
|
|
#: ../Doc/c-api/structures.rst:267
|
|
msgid "T_SHORT"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:267
|
|
msgid "short"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:268
|
|
msgid "T_INT"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:269
|
|
msgid "T_LONG"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:270
|
|
msgid "T_FLOAT"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:270
|
|
msgid "float"
|
|
msgstr "float"
|
|
|
|
#: ../Doc/c-api/structures.rst:271
|
|
msgid "T_DOUBLE"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:271
|
|
msgid "double"
|
|
msgstr "double"
|
|
|
|
#: ../Doc/c-api/structures.rst:272
|
|
msgid "T_STRING"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:273
|
|
msgid "T_OBJECT"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:273 ../Doc/c-api/structures.rst:274
|
|
msgid "PyObject \\*"
|
|
msgstr "PyObject \\*"
|
|
|
|
#: ../Doc/c-api/structures.rst:274
|
|
msgid "T_OBJECT_EX"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:275
|
|
msgid "T_CHAR"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:275 ../Doc/c-api/structures.rst:276
|
|
#: ../Doc/c-api/structures.rst:281
|
|
msgid "char"
|
|
msgstr "char"
|
|
|
|
#: ../Doc/c-api/structures.rst:276
|
|
msgid "T_BYTE"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:277
|
|
msgid "T_UBYTE"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:277
|
|
msgid "unsigned char"
|
|
msgstr "unsigned char"
|
|
|
|
#: ../Doc/c-api/structures.rst:278
|
|
msgid "T_UINT"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:279
|
|
msgid "T_USHORT"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:279
|
|
msgid "unsigned short"
|
|
msgstr "unsigned short"
|
|
|
|
#: ../Doc/c-api/structures.rst:280
|
|
msgid "T_ULONG"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:281
|
|
msgid "T_BOOL"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:282
|
|
msgid "T_LONGLONG"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:282 ../Doc/c-api/unicode.rst:469
|
|
#: ../Doc/c-api/unicode.rst:472
|
|
msgid "long long"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:283
|
|
msgid "T_ULONGLONG"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:283 ../Doc/c-api/unicode.rst:475
|
|
msgid "unsigned long long"
|
|
msgstr "unsigned long long"
|
|
|
|
#: ../Doc/c-api/structures.rst:284
|
|
msgid "T_PYSSIZET"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:287
|
|
msgid ""
|
|
":c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that :c:macro:"
|
|
"`T_OBJECT` returns ``None`` if the member is *NULL* and :c:macro:"
|
|
"`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use :c:macro:"
|
|
"`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX` "
|
|
"handles use of the :keyword:`del` statement on that attribute more correctly "
|
|
"than :c:macro:`T_OBJECT`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/structures.rst:294
|
|
msgid ""
|
|
":attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for "
|
|
"read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies :c:"
|
|
"macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` "
|
|
"members can be deleted. (They are set to *NULL*)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:6
|
|
msgid "Operating System Utilities"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:10
|
|
msgid ""
|
|
"Return the file system representation for *path*. If the object is a :class:"
|
|
"`str` or :class:`bytes` object, then its reference count is incremented. If "
|
|
"the object implements the :class:`os.PathLike` interface, then :meth:`~os."
|
|
"PathLike.__fspath__` is returned as long as it is a :class:`str` or :class:"
|
|
"`bytes` object. Otherwise :exc:`TypeError` is raised and ``NULL`` is "
|
|
"returned."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:22
|
|
msgid ""
|
|
"Return true (nonzero) if the standard I/O file *fp* with name *filename* is "
|
|
"deemed interactive. This is the case for files for which "
|
|
"``isatty(fileno(fp))`` is true. If the global flag :c:data:"
|
|
"`Py_InteractiveFlag` is true, this function also returns true if the "
|
|
"*filename* pointer is *NULL* or if the name is equal to one of the strings "
|
|
"``'<stdin>'`` or ``'???'``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:31
|
|
msgid ""
|
|
"Function to update some internal state after a process fork; this should be "
|
|
"called in the new process if the Python interpreter will continue to be "
|
|
"used. If a new executable is loaded into the new process, this function does "
|
|
"not need to be called."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:39
|
|
msgid ""
|
|
"Return true when the interpreter runs out of stack space. This is a "
|
|
"reliable check, but is only available when :const:`USE_STACKCHECK` is "
|
|
"defined (currently on Windows using the Microsoft Visual C++ compiler). :"
|
|
"const:`USE_STACKCHECK` will be defined automatically; you should never "
|
|
"change the definition in your own code."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:48
|
|
msgid ""
|
|
"Return the current signal handler for signal *i*. This is a thin wrapper "
|
|
"around either :c:func:`sigaction` or :c:func:`signal`. Do not call those "
|
|
"functions directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:"
|
|
"type:`void (\\*)(int)`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:56
|
|
msgid ""
|
|
"Set the signal handler for signal *i* to be *h*; return the old signal "
|
|
"handler. This is a thin wrapper around either :c:func:`sigaction` or :c:func:"
|
|
"`signal`. Do not call those functions directly! :c:type:"
|
|
"`PyOS_sighandler_t` is a typedef alias for :c:type:`void (\\*)(int)`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:63
|
|
msgid ""
|
|
"Decode a byte string from the locale encoding with the :ref:`surrogateescape "
|
|
"error handler <surrogateescape>`: undecodable bytes are decoded as "
|
|
"characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a "
|
|
"surrogate character, escape the bytes using the surrogateescape error "
|
|
"handler instead of decoding them."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:69
|
|
msgid ""
|
|
"Return a pointer to a newly allocated wide character string, use :c:func:"
|
|
"`PyMem_RawFree` to free the memory. If size is not ``NULL``, write the "
|
|
"number of wide characters excluding the null character into ``*size``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:73
|
|
msgid ""
|
|
"Return ``NULL`` on decoding error or memory allocation error. If *size* is "
|
|
"not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to "
|
|
"``(size_t)-2`` on decoding error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:77
|
|
msgid ""
|
|
"Decoding errors should never happen, unless there is a bug in the C library."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:80
|
|
msgid ""
|
|
"Use the :c:func:`Py_EncodeLocale` function to encode the character string "
|
|
"back to a byte string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:85
|
|
msgid ""
|
|
"The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and :c:func:"
|
|
"`PyUnicode_DecodeLocaleAndSize` functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:93
|
|
msgid ""
|
|
"Encode a wide character string to the locale encoding with the :ref:"
|
|
"`surrogateescape error handler <surrogateescape>`: surrogate characters in "
|
|
"the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:97
|
|
msgid ""
|
|
"Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free` "
|
|
"to free the memory. Return ``NULL`` on encoding error or memory allocation "
|
|
"error"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:101
|
|
msgid ""
|
|
"If error_pos is not ``NULL``, ``*error_pos`` is set to the index of the "
|
|
"invalid character on encoding error, or set to ``(size_t)-1`` otherwise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:104
|
|
msgid ""
|
|
"Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back "
|
|
"to a wide character string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:109
|
|
msgid ""
|
|
"The :c:func:`PyUnicode_EncodeFSDefault` and :c:func:`PyUnicode_EncodeLocale` "
|
|
"functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:118
|
|
msgid "System Functions"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:120
|
|
msgid ""
|
|
"These are utility functions that make functionality from the :mod:`sys` "
|
|
"module accessible to C code. They all work with the current interpreter "
|
|
"thread's :mod:`sys` module's dict, which is contained in the internal thread "
|
|
"state structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:126
|
|
msgid ""
|
|
"Return the object *name* from the :mod:`sys` module or *NULL* if it does not "
|
|
"exist, without setting an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:131
|
|
msgid ""
|
|
"Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which "
|
|
"case *name* is deleted from the sys module. Returns ``0`` on success, ``-1`` "
|
|
"on error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:137
|
|
msgid "Reset :data:`sys.warnoptions` to an empty list."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:141
|
|
msgid "Append *s* to :data:`sys.warnoptions`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:145
|
|
msgid "Append *unicode* to :data:`sys.warnoptions`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:149
|
|
msgid ""
|
|
"Set :data:`sys.path` to a list object of paths found in *path* which should "
|
|
"be a list of paths separated with the platform's search path delimiter (``:"
|
|
"`` on Unix, ``;`` on Windows)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:155
|
|
msgid ""
|
|
"Write the output string described by *format* to :data:`sys.stdout`. No "
|
|
"exceptions are raised, even if truncation occurs (see below)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:158
|
|
msgid ""
|
|
"*format* should limit the total size of the formatted output string to 1000 "
|
|
"bytes or less -- after 1000 bytes, the output string is truncated. In "
|
|
"particular, this means that no unrestricted \"%s\" formats should occur; "
|
|
"these should be limited using \"%.<N>s\" where <N> is a decimal number "
|
|
"calculated so that <N> plus the maximum size of other formatted text does "
|
|
"not exceed 1000 bytes. Also watch out for \"%f\", which can print hundreds "
|
|
"of digits for very large numbers."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:166
|
|
msgid ""
|
|
"If a problem occurs, or :data:`sys.stdout` is unset, the formatted message "
|
|
"is written to the real (C level) *stdout*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:171
|
|
msgid ""
|
|
"As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr* "
|
|
"instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:176
|
|
msgid ""
|
|
"Function similar to PySys_WriteStdout() but format the message using :c:func:"
|
|
"`PyUnicode_FromFormatV` and don't truncate the message to an arbitrary "
|
|
"length."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:184
|
|
msgid ""
|
|
"As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr* "
|
|
"instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:191
|
|
msgid ""
|
|
"Parse *s* as a set of :option:`-X` options and add them to the current "
|
|
"options mapping as returned by :c:func:`PySys_GetXOptions`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:198
|
|
msgid ""
|
|
"Return the current dictionary of :option:`-X` options, similarly to :data:"
|
|
"`sys._xoptions`. On error, *NULL* is returned and an exception is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:208
|
|
msgid "Process Control"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:215
|
|
msgid ""
|
|
"Print a fatal error message and kill the process. No cleanup is performed. "
|
|
"This function should only be invoked when a condition is detected that would "
|
|
"make it dangerous to continue using the Python interpreter; e.g., when the "
|
|
"object administration appears to be corrupted. On Unix, the standard C "
|
|
"library function :c:func:`abort` is called which will attempt to produce a :"
|
|
"file:`core` file."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:229
|
|
msgid ""
|
|
"Exit the current process. This calls :c:func:`Py_FinalizeEx` and then calls "
|
|
"the standard C library function ``exit(status)``. If :c:func:"
|
|
"`Py_FinalizeEx` indicates an error, the exit status is set to 120."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:233
|
|
msgid "Errors from finalization no longer ignored."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/sys.rst:243
|
|
msgid ""
|
|
"Register a cleanup function to be called by :c:func:`Py_FinalizeEx`. The "
|
|
"cleanup function will be called with no arguments and should return no "
|
|
"value. At most 32 cleanup functions can be registered. When the "
|
|
"registration is successful, :c:func:`Py_AtExit` returns ``0``; on failure, "
|
|
"it returns ``-1``. The cleanup function registered last is called first. "
|
|
"Each cleanup function will be called at most once. Since Python's internal "
|
|
"finalization will have completed before the cleanup function, no Python APIs "
|
|
"should be called by *func*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:6
|
|
msgid "Tuple Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:13
|
|
msgid "This subtype of :c:type:`PyObject` represents a Python tuple object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:18
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python tuple type; it "
|
|
"is the same object as :class:`tuple` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:24
|
|
msgid ""
|
|
"Return true if *p* is a tuple object or an instance of a subtype of the "
|
|
"tuple type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:30
|
|
msgid ""
|
|
"Return true if *p* is a tuple object, but not an instance of a subtype of "
|
|
"the tuple type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:36
|
|
msgid "Return a new tuple object of size *len*, or *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:41
|
|
msgid ""
|
|
"Return a new tuple object of size *n*, or *NULL* on failure. The tuple "
|
|
"values are initialized to the subsequent *n* C arguments pointing to Python "
|
|
"objects. ``PyTuple_Pack(2, a, b)`` is equivalent to "
|
|
"``Py_BuildValue(\"(OO)\", a, b)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:48
|
|
msgid "Take a pointer to a tuple object, and return the size of that tuple."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:53
|
|
msgid ""
|
|
"Return the size of the tuple *p*, which must be non-*NULL* and point to a "
|
|
"tuple; no error checking is performed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:59
|
|
msgid ""
|
|
"Return the object at position *pos* in the tuple pointed to by *p*. If "
|
|
"*pos* is out of bounds, return *NULL* and sets an :exc:`IndexError` "
|
|
"exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:65
|
|
msgid "Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:70
|
|
msgid ""
|
|
"Take a slice of the tuple pointed to by *p* from *low* to *high* and return "
|
|
"it as a new tuple."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:76
|
|
msgid ""
|
|
"Insert a reference to object *o* at position *pos* of the tuple pointed to "
|
|
"by *p*. Return ``0`` on success."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:81 ../Doc/c-api/tuple.rst:91
|
|
#: ../Doc/c-api/tuple.rst:209 ../Doc/c-api/tuple.rst:218
|
|
msgid "This function \"steals\" a reference to *o*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:86
|
|
msgid ""
|
|
"Like :c:func:`PyTuple_SetItem`, but does no error checking, and should "
|
|
"*only* be used to fill in brand new tuples."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:96
|
|
msgid ""
|
|
"Can be used to resize a tuple. *newsize* will be the new length of the "
|
|
"tuple. Because tuples are *supposed* to be immutable, this should only be "
|
|
"used if there is only one reference to the object. Do *not* use this if the "
|
|
"tuple may already be known to some other part of the code. The tuple will "
|
|
"always grow or shrink at the end. Think of this as destroying the old tuple "
|
|
"and creating a new one, only more efficiently. Returns ``0`` on success. "
|
|
"Client code should never assume that the resulting value of ``*p`` will be "
|
|
"the same as before calling this function. If the object referenced by ``*p`` "
|
|
"is replaced, the original ``*p`` is destroyed. On failure, returns ``-1`` "
|
|
"and sets ``*p`` to *NULL*, and raises :exc:`MemoryError` or :exc:"
|
|
"`SystemError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:114
|
|
msgid "Struct Sequence Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:116
|
|
msgid ""
|
|
"Struct sequence objects are the C equivalent of :func:`~collections."
|
|
"namedtuple` objects, i.e. a sequence whose items can also be accessed "
|
|
"through attributes. To create a struct sequence, you first have to create a "
|
|
"specific struct sequence type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:123
|
|
msgid ""
|
|
"Create a new struct sequence type from the data in *desc*, described below. "
|
|
"Instances of the resulting type can be created with :c:func:"
|
|
"`PyStructSequence_New`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:129
|
|
msgid "Initializes a struct sequence type *type* from *desc* in place."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:134
|
|
msgid ""
|
|
"The same as ``PyStructSequence_InitType``, but returns ``0`` on success and "
|
|
"``-1`` on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:142
|
|
msgid "Contains the meta information of a struct sequence type to create."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:147 ../Doc/c-api/tuple.rst:170
|
|
msgid "``name``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:147 ../Doc/c-api/tuple.rst:149
|
|
#: ../Doc/c-api/tuple.rst:170 ../Doc/c-api/tuple.rst:175
|
|
msgid "``char *``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:147
|
|
msgid "name of the struct sequence type"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:149 ../Doc/c-api/tuple.rst:175
|
|
msgid "``doc``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:149
|
|
msgid "pointer to docstring for the type or NULL to omit"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:152
|
|
msgid "``fields``"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:152
|
|
msgid "``PyStructSequence_Field *``"
|
|
msgstr "``PyStructSequence_Field *``"
|
|
|
|
#: ../Doc/c-api/tuple.rst:152
|
|
msgid "pointer to *NULL*-terminated array with field names of the new type"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:155
|
|
msgid "``n_in_sequence``"
|
|
msgstr "``n_in_sequence``"
|
|
|
|
#: ../Doc/c-api/tuple.rst:155
|
|
msgid "``int``"
|
|
msgstr "``int``"
|
|
|
|
#: ../Doc/c-api/tuple.rst:155
|
|
msgid "number of fields visible to the Python side (if used as tuple)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:162
|
|
msgid ""
|
|
"Describes a field of a struct sequence. As a struct sequence is modeled as a "
|
|
"tuple, all fields are typed as :c:type:`PyObject\\*`. The index in the :"
|
|
"attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which "
|
|
"field of the struct sequence is described."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:170
|
|
msgid ""
|
|
"name for the field or *NULL* to end the list of named fields, set to "
|
|
"PyStructSequence_UnnamedField to leave unnamed"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:175
|
|
msgid "field docstring or *NULL* to omit"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:181
|
|
msgid "Special value for a field name to leave it unnamed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:186
|
|
msgid ""
|
|
"Creates an instance of *type*, which must have been created with :c:func:"
|
|
"`PyStructSequence_NewType`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:192
|
|
msgid ""
|
|
"Return the object at position *pos* in the struct sequence pointed to by "
|
|
"*p*. No bounds checking is performed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:198
|
|
msgid "Macro equivalent of :c:func:`PyStructSequence_GetItem`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:203
|
|
msgid ""
|
|
"Sets the field at index *pos* of the struct sequence *p* to value *o*. "
|
|
"Like :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand "
|
|
"new instances."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/tuple.rst:214
|
|
msgid "Macro equivalent of :c:func:`PyStructSequence_SetItem`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:6 ../Doc/c-api/typeobj.rst:6
|
|
msgid "Type Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:13
|
|
msgid "The C structure of the objects used to describe built-in types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:18
|
|
msgid ""
|
|
"This is the type object for type objects; it is the same object as :class:"
|
|
"`type` in the Python layer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:24
|
|
msgid ""
|
|
"Return true if the object *o* is a type object, including instances of types "
|
|
"derived from the standard type object. Return false in all other cases."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:30
|
|
msgid ""
|
|
"Return true if the object *o* is a type object, but not a subtype of the "
|
|
"standard type object. Return false in all other cases."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:36
|
|
msgid "Clear the internal lookup cache. Return the current version tag."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:40
|
|
msgid ""
|
|
"Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This "
|
|
"function is primarily meant for use with `Py_LIMITED_API`; the individual "
|
|
"flag bits are guaranteed to be stable across Python releases, but access to :"
|
|
"c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:50
|
|
msgid ""
|
|
"Invalidate the internal lookup cache for the type and all of its subtypes. "
|
|
"This function must be called after any manual modification of the attributes "
|
|
"or base classes of the type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:57
|
|
msgid ""
|
|
"Return true if the type object *o* sets the feature *feature*. Type "
|
|
"features are denoted by single bit flags."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:63
|
|
msgid ""
|
|
"Return true if the type object includes support for the cycle detector; this "
|
|
"tests the type flag :const:`Py_TPFLAGS_HAVE_GC`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:69
|
|
msgid "Return true if *a* is a subtype of *b*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:71
|
|
msgid ""
|
|
"This function only checks for actual subtypes, which means that :meth:"
|
|
"`~class.__subclasscheck__` is not called on *b*. Call :c:func:"
|
|
"`PyObject_IsSubclass` to do the same check that :func:`issubclass` would do."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:79
|
|
msgid ""
|
|
"Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type "
|
|
"object. Use Python's default memory allocation mechanism to allocate a new "
|
|
"instance and initialize all its contents to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:85
|
|
msgid ""
|
|
"Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type "
|
|
"object. Create a new instance using the type's :c:member:`~PyTypeObject."
|
|
"tp_alloc` slot."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:90
|
|
msgid ""
|
|
"Finalize a type object. This should be called on all type objects to finish "
|
|
"their initialization. This function is responsible for adding inherited "
|
|
"slots from a type's base class. Return ``0`` on success, or return ``-1`` "
|
|
"and sets an exception on error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:97
|
|
msgid ""
|
|
"Creates and returns a heap type object from the *spec* passed to the "
|
|
"function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:101
|
|
msgid ""
|
|
"Creates and returns a heap type object from the *spec*. In addition to that, "
|
|
"the created heap type contains all types contained by the *bases* tuple as "
|
|
"base types. This allows the caller to reference other heap types as base "
|
|
"types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/type.rst:109
|
|
msgid ""
|
|
"Return the function pointer stored in the given slot. If the result is "
|
|
"*NULL*, this indicates that either the slot is *NULL*, or that the function "
|
|
"was called with invalid parameters. Callers will typically cast the result "
|
|
"pointer into the appropriate function type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:8
|
|
msgid ""
|
|
"Perhaps one of the most important structures of the Python object system is "
|
|
"the structure that defines a new type: the :c:type:`PyTypeObject` "
|
|
"structure. Type objects can be handled using any of the :c:func:`PyObject_"
|
|
"\\*` or :c:func:`PyType_\\*` functions, but do not offer much that's "
|
|
"interesting to most Python applications. These objects are fundamental to "
|
|
"how objects behave, so they are very important to the interpreter itself and "
|
|
"to any extension module that implements new types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:16
|
|
msgid ""
|
|
"Type objects are fairly large compared to most of the standard types. The "
|
|
"reason for the size is that each type object stores a large number of "
|
|
"values, mostly C function pointers, each of which implements a small part of "
|
|
"the type's functionality. The fields of the type object are examined in "
|
|
"detail in this section. The fields will be described in the order in which "
|
|
"they occur in the structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:23
|
|
msgid ""
|
|
"Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc, "
|
|
"intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, "
|
|
"freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, "
|
|
"reprfunc, hashfunc"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:28
|
|
msgid ""
|
|
"The structure definition for :c:type:`PyTypeObject` can be found in :file:"
|
|
"`Include/object.h`. For convenience of reference, this repeats the "
|
|
"definition found there:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:35
|
|
msgid ""
|
|
"The type object structure extends the :c:type:`PyVarObject` structure. The :"
|
|
"attr:`ob_size` field is used for dynamic types (created by :func:"
|
|
"`type_new`, usually called from a class statement). Note that :c:data:"
|
|
"`PyType_Type` (the metatype) initializes :c:member:`~PyTypeObject."
|
|
"tp_itemsize`, which means that its instances (i.e. type objects) *must* have "
|
|
"the :attr:`ob_size` field."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:45
|
|
msgid ""
|
|
"These fields are only present when the macro ``Py_TRACE_REFS`` is defined. "
|
|
"Their initialization to *NULL* is taken care of by the "
|
|
"``PyObject_HEAD_INIT`` macro. For statically allocated objects, these "
|
|
"fields always remain *NULL*. For dynamically allocated objects, these two "
|
|
"fields are used to link the object into a doubly-linked list of *all* live "
|
|
"objects on the heap. This could be used for various debugging purposes; "
|
|
"currently the only use is to print the objects that are still alive at the "
|
|
"end of a run when the environment variable :envvar:`PYTHONDUMPREFS` is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:54
|
|
msgid "These fields are not inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:59
|
|
msgid ""
|
|
"This is the type object's reference count, initialized to ``1`` by the "
|
|
"``PyObject_HEAD_INIT`` macro. Note that for statically allocated type "
|
|
"objects, the type's instances (objects whose :attr:`ob_type` points back to "
|
|
"the type) do *not* count as references. But for dynamically allocated type "
|
|
"objects, the instances *do* count as references."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:65 ../Doc/c-api/typeobj.rst:94
|
|
#: ../Doc/c-api/typeobj.rst:122
|
|
msgid "This field is not inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:70
|
|
msgid ""
|
|
"This is the type's type, in other words its metatype. It is initialized by "
|
|
"the argument to the ``PyObject_HEAD_INIT`` macro, and its value should "
|
|
"normally be ``&PyType_Type``. However, for dynamically loadable extension "
|
|
"modules that must be usable on Windows (at least), the compiler complains "
|
|
"that this is not a valid initializer. Therefore, the convention is to pass "
|
|
"*NULL* to the ``PyObject_HEAD_INIT`` macro and to initialize this field "
|
|
"explicitly at the start of the module's initialization function, before "
|
|
"doing anything else. This is typically done like this::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:81
|
|
msgid ""
|
|
"This should be done before any instances of the type are created. :c:func:"
|
|
"`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so, initializes "
|
|
"it to the :attr:`ob_type` field of the base class. :c:func:`PyType_Ready` "
|
|
"will not change this field if it is non-zero."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:86 ../Doc/c-api/typeobj.rst:188
|
|
#: ../Doc/c-api/typeobj.rst:253 ../Doc/c-api/typeobj.rst:320
|
|
#: ../Doc/c-api/typeobj.rst:338 ../Doc/c-api/typeobj.rst:664
|
|
#: ../Doc/c-api/typeobj.rst:681 ../Doc/c-api/typeobj.rst:776
|
|
#: ../Doc/c-api/typeobj.rst:871 ../Doc/c-api/typeobj.rst:964
|
|
#: ../Doc/c-api/typeobj.rst:1019
|
|
msgid "This field is inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:91
|
|
msgid ""
|
|
"For statically allocated type objects, this should be initialized to zero. "
|
|
"For dynamically allocated type objects, this field has a special internal "
|
|
"meaning."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:99
|
|
msgid ""
|
|
"Pointer to a NUL-terminated string containing the name of the type. For "
|
|
"types that are accessible as module globals, the string should be the full "
|
|
"module name, followed by a dot, followed by the type name; for built-in "
|
|
"types, it should be just the type name. If the module is a submodule of a "
|
|
"package, the full package name is part of the full module name. For "
|
|
"example, a type named :class:`T` defined in module :mod:`M` in subpackage :"
|
|
"mod:`Q` in package :mod:`P` should have the :c:member:`~PyTypeObject."
|
|
"tp_name` initializer ``\"P.Q.M.T\"``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:107
|
|
msgid ""
|
|
"For dynamically allocated type objects, this should just be the type name, "
|
|
"and the module name explicitly stored in the type dict as the value for key "
|
|
"``'__module__'``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:111
|
|
msgid ""
|
|
"For statically allocated type objects, the tp_name field should contain a "
|
|
"dot. Everything before the last dot is made accessible as the :attr:"
|
|
"`__module__` attribute, and everything after the last dot is made accessible "
|
|
"as the :attr:`~definition.__name__` attribute."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:116
|
|
msgid ""
|
|
"If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is "
|
|
"made accessible as the :attr:`~definition.__name__` attribute, and the :attr:"
|
|
"`__module__` attribute is undefined (unless explicitly set in the "
|
|
"dictionary, as explained above). This means your type will be impossible to "
|
|
"pickle. Additionally, it will not be listed in module documentations "
|
|
"created with pydoc."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:128
|
|
msgid ""
|
|
"These fields allow calculating the size in bytes of instances of the type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:130
|
|
msgid ""
|
|
"There are two kinds of types: types with fixed-length instances have a zero :"
|
|
"c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length "
|
|
"instances have a non-zero :c:member:`~PyTypeObject.tp_itemsize` field. For "
|
|
"a type with fixed-length instances, all instances have the same size, given "
|
|
"in :c:member:`~PyTypeObject.tp_basicsize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:135
|
|
msgid ""
|
|
"For a type with variable-length instances, the instances must have an :attr:"
|
|
"`ob_size` field, and the instance size is :c:member:`~PyTypeObject."
|
|
"tp_basicsize` plus N times :c:member:`~PyTypeObject.tp_itemsize`, where N is "
|
|
"the \"length\" of the object. The value of N is typically stored in the "
|
|
"instance's :attr:`ob_size` field. There are exceptions: for example, ints "
|
|
"use a negative :attr:`ob_size` to indicate a negative number, and N is "
|
|
"``abs(ob_size)`` there. Also, the presence of an :attr:`ob_size` field in "
|
|
"the instance layout doesn't mean that the instance structure is variable-"
|
|
"length (for example, the structure for the list type has fixed-length "
|
|
"instances, yet those instances have a meaningful :attr:`ob_size` field)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:146
|
|
msgid ""
|
|
"The basic size includes the fields in the instance declared by the macro :c:"
|
|
"macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to "
|
|
"declare the instance struct) and this in turn includes the :attr:`_ob_prev` "
|
|
"and :attr:`_ob_next` fields if they are present. This means that the only "
|
|
"correct way to get an initializer for the :c:member:`~PyTypeObject."
|
|
"tp_basicsize` is to use the ``sizeof`` operator on the struct used to "
|
|
"declare the instance layout. The basic size does not include the GC header "
|
|
"size."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:154
|
|
msgid ""
|
|
"These fields are inherited separately by subtypes. If the base type has a "
|
|
"non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to "
|
|
"set :c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a "
|
|
"subtype (though this depends on the implementation of the base type)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:159
|
|
msgid ""
|
|
"A note about alignment: if the variable items require a particular "
|
|
"alignment, this should be taken care of by the value of :c:member:"
|
|
"`~PyTypeObject.tp_basicsize`. Example: suppose a type implements an array "
|
|
"of ``double``. :c:member:`~PyTypeObject.tp_itemsize` is ``sizeof(double)``. "
|
|
"It is the programmer's responsibility that :c:member:`~PyTypeObject."
|
|
"tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the "
|
|
"alignment requirement for ``double``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:169
|
|
msgid ""
|
|
"A pointer to the instance destructor function. This function must be "
|
|
"defined unless the type guarantees that its instances will never be "
|
|
"deallocated (as is the case for the singletons ``None`` and ``Ellipsis``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:173
|
|
msgid ""
|
|
"The destructor function is called by the :c:func:`Py_DECREF` and :c:func:"
|
|
"`Py_XDECREF` macros when the new reference count is zero. At this point, "
|
|
"the instance is still in existence, but there are no references to it. The "
|
|
"destructor function should free all references which the instance owns, free "
|
|
"all memory buffers owned by the instance (using the freeing function "
|
|
"corresponding to the allocation function used to allocate the buffer), and "
|
|
"finally (as its last action) call the type's :c:member:`~PyTypeObject."
|
|
"tp_free` function. If the type is not subtypable (doesn't have the :const:"
|
|
"`Py_TPFLAGS_BASETYPE` flag bit set), it is permissible to call the object "
|
|
"deallocator directly instead of via :c:member:`~PyTypeObject.tp_free`. The "
|
|
"object deallocator should be the one used to allocate the instance; this is "
|
|
"normally :c:func:`PyObject_Del` if the instance was allocated using :c:func:"
|
|
"`PyObject_New` or :c:func:`PyObject_VarNew`, or :c:func:`PyObject_GC_Del` if "
|
|
"the instance was allocated using :c:func:`PyObject_GC_New` or :c:func:"
|
|
"`PyObject_GC_NewVar`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:193
|
|
msgid "Reserved slot, formerly used for print formatting in Python 2.x."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:198
|
|
msgid "An optional pointer to the get-attribute-string function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:200
|
|
msgid ""
|
|
"This field is deprecated. When it is defined, it should point to a function "
|
|
"that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, "
|
|
"but taking a C string instead of a Python string object to give the "
|
|
"attribute name. The signature is the same as for :c:func:"
|
|
"`PyObject_GetAttrString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:205
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_getattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_getattr` "
|
|
"and :c:member:`~PyTypeObject.tp_getattro` from its base type when the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject."
|
|
"tp_getattro` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:212 ../Doc/c-api/typeobj.rst:356
|
|
msgid ""
|
|
"An optional pointer to the function for setting and deleting attributes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:214
|
|
msgid ""
|
|
"This field is deprecated. When it is defined, it should point to a function "
|
|
"that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, "
|
|
"but taking a C string instead of a Python string object to give the "
|
|
"attribute name. The signature is the same as for :c:func:"
|
|
"`PyObject_SetAttrString`, but setting *v* to *NULL* to delete an attribute "
|
|
"must be supported."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:220
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_setattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` "
|
|
"and :c:member:`~PyTypeObject.tp_setattro` from its base type when the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject."
|
|
"tp_setattro` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:227
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement :term:`awaitable` and :term:`asynchronous iterator` "
|
|
"protocols at the C-level. See :ref:`async-structs` for details."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:231
|
|
msgid "Formerly known as ``tp_compare`` and ``tp_reserved``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:239
|
|
msgid ""
|
|
"An optional pointer to a function that implements the built-in function :"
|
|
"func:`repr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:242
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_Repr`; it must return a "
|
|
"string or a Unicode object. Ideally, this function should return a string "
|
|
"that, when passed to :func:`eval`, given a suitable environment, returns an "
|
|
"object with the same value. If this is not feasible, it should return a "
|
|
"string starting with ``'<'`` and ending with ``'>'`` from which both the "
|
|
"type and the value of the object can be deduced."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:249
|
|
msgid ""
|
|
"When this field is not set, a string of the form ``<%s object at %p>`` is "
|
|
"returned, where ``%s`` is replaced by the type name, and ``%p`` by the "
|
|
"object's memory address."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:257
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement the number protocol. These fields are documented "
|
|
"in :ref:`number-structs`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:261
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the "
|
|
"contained fields are inherited individually."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:267
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement the sequence protocol. These fields are documented "
|
|
"in :ref:`sequence-structs`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:271
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the "
|
|
"contained fields are inherited individually."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:277
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement the mapping protocol. These fields are documented "
|
|
"in :ref:`mapping-structs`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:281
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the "
|
|
"contained fields are inherited individually."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:289
|
|
msgid ""
|
|
"An optional pointer to a function that implements the built-in function :"
|
|
"func:`hash`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:292
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_Hash`; it must return a "
|
|
"value of the type Py_hash_t. The value ``-1`` should not be returned as a "
|
|
"normal return value; when an error occurs during the computation of the hash "
|
|
"value, the function should set an exception and return ``-1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:297
|
|
msgid ""
|
|
"This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to "
|
|
"block inheritance of the hash method from a parent type. This is interpreted "
|
|
"as the equivalent of ``__hash__ = None`` at the Python level, causing "
|
|
"``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note "
|
|
"that the converse is also true - setting ``__hash__ = None`` on a class at "
|
|
"the Python level will result in the ``tp_hash`` slot being set to :c:func:"
|
|
"`PyObject_HashNotImplemented`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:305
|
|
msgid ""
|
|
"When this field is not set, an attempt to take the hash of the object "
|
|
"raises :exc:`TypeError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:308
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_richcompare`: a subtype inherits both of :c:member:`~PyTypeObject."
|
|
"tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's :c:"
|
|
"member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` "
|
|
"are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:316
|
|
msgid ""
|
|
"An optional pointer to a function that implements calling the object. This "
|
|
"should be *NULL* if the object is not callable. The signature is the same "
|
|
"as for :c:func:`PyObject_Call`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:325
|
|
msgid ""
|
|
"An optional pointer to a function that implements the built-in operation :"
|
|
"func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls "
|
|
"the constructor for that type. This constructor calls :c:func:"
|
|
"`PyObject_Str` to do the actual work, and :c:func:`PyObject_Str` will call "
|
|
"this handler.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:330
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_Str`; it must return a "
|
|
"string or a Unicode object. This function should return a \"friendly\" "
|
|
"string representation of the object, as this is the representation that will "
|
|
"be used, among other things, by the :func:`print` function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:335
|
|
msgid ""
|
|
"When this field is not set, :c:func:`PyObject_Repr` is called to return a "
|
|
"string representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:343
|
|
msgid "An optional pointer to the get-attribute function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:345
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_GetAttr`. It is usually "
|
|
"convenient to set this field to :c:func:`PyObject_GenericGetAttr`, which "
|
|
"implements the normal way of looking for object attributes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:349
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_getattr`: a subtype inherits both :c:member:`~PyTypeObject.tp_getattr` "
|
|
"and :c:member:`~PyTypeObject.tp_getattro` from its base type when the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject."
|
|
"tp_getattro` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:358
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_SetAttr`, but setting *v* "
|
|
"to *NULL* to delete an attribute must be supported. It is usually "
|
|
"convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which "
|
|
"implements the normal way of setting object attributes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:363
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_setattr`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` "
|
|
"and :c:member:`~PyTypeObject.tp_setattro` from its base type when the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject."
|
|
"tp_setattro` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:370
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement the buffer interface. These fields are documented "
|
|
"in :ref:`buffer-structs`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:374
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the "
|
|
"contained fields are inherited individually."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:380
|
|
msgid ""
|
|
"This field is a bit mask of various flags. Some flags indicate variant "
|
|
"semantics for certain situations; others are used to indicate that certain "
|
|
"fields in the type object (or in the extension structures referenced via :c:"
|
|
"member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject."
|
|
"tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and :c:member:"
|
|
"`~PyTypeObject.tp_as_buffer`) that were historically not always present are "
|
|
"valid; if such a flag bit is clear, the type fields it guards must not be "
|
|
"accessed and must be considered to have a zero or *NULL* value instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:388
|
|
msgid ""
|
|
"Inheritance of this field is complicated. Most flag bits are inherited "
|
|
"individually, i.e. if the base type has a flag bit set, the subtype inherits "
|
|
"this flag bit. The flag bits that pertain to extension structures are "
|
|
"strictly inherited if the extension structure is inherited, i.e. the base "
|
|
"type's value of the flag bit is copied into the subtype together with a "
|
|
"pointer to the extension structure. The :const:`Py_TPFLAGS_HAVE_GC` flag "
|
|
"bit is inherited together with the :c:member:`~PyTypeObject.tp_traverse` "
|
|
"and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the :const:"
|
|
"`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the :c:member:"
|
|
"`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in "
|
|
"the subtype exist and have *NULL* values."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:399
|
|
msgid ""
|
|
"The following bit masks are currently defined; these can be ORed together "
|
|
"using the ``|`` operator to form the value of the :c:member:`~PyTypeObject."
|
|
"tp_flags` field. The macro :c:func:`PyType_HasFeature` takes a type and a "
|
|
"flags value, *tp* and *f*, and checks whether ``tp->tp_flags & f`` is non-"
|
|
"zero."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:407
|
|
msgid ""
|
|
"This bit is set when the type object itself is allocated on the heap. In "
|
|
"this case, the :attr:`ob_type` field of its instances is considered a "
|
|
"reference to the type, and the type object is INCREF'ed when a new instance "
|
|
"is created, and DECREF'ed when an instance is destroyed (this does not apply "
|
|
"to instances of subtypes; only the type referenced by the instance's ob_type "
|
|
"gets INCREF'ed or DECREF'ed)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:417
|
|
msgid ""
|
|
"This bit is set when the type can be used as the base type of another type. "
|
|
"If this bit is clear, the type cannot be subtyped (similar to a \"final\" "
|
|
"class in Java)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:424
|
|
msgid ""
|
|
"This bit is set when the type object has been fully initialized by :c:func:"
|
|
"`PyType_Ready`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:430
|
|
msgid ""
|
|
"This bit is set while :c:func:`PyType_Ready` is in the process of "
|
|
"initializing the type object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:436
|
|
msgid ""
|
|
"This bit is set when the object supports garbage collection. If this bit is "
|
|
"set, instances must be created using :c:func:`PyObject_GC_New` and destroyed "
|
|
"using :c:func:`PyObject_GC_Del`. More information in section :ref:"
|
|
"`supporting-cycle-detection`. This bit also implies that the GC-related "
|
|
"fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject."
|
|
"tp_clear` are present in the type object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:446
|
|
msgid ""
|
|
"This is a bitmask of all the bits that pertain to the existence of certain "
|
|
"fields in the type object and its extension structures. Currently, it "
|
|
"includes the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`, :"
|
|
"const:`Py_TPFLAGS_HAVE_VERSION_TAG`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:461
|
|
msgid ""
|
|
"These flags are used by functions such as :c:func:`PyLong_Check` to quickly "
|
|
"determine if a type is a subclass of a built-in type; such specific checks "
|
|
"are faster than a generic check, like :c:func:`PyObject_IsInstance`. Custom "
|
|
"types that inherit from built-ins should have their :c:member:`~PyTypeObject."
|
|
"tp_flags` set appropriately, or the code that interacts with such types will "
|
|
"behave differently depending on what kind of check is used."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:472
|
|
msgid ""
|
|
"This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is "
|
|
"present in the type structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:480
|
|
msgid ""
|
|
"An optional pointer to a NUL-terminated C string giving the docstring for "
|
|
"this type object. This is exposed as the :attr:`__doc__` attribute on the "
|
|
"type and instances of the type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:484
|
|
msgid "This field is *not* inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:489
|
|
msgid ""
|
|
"An optional pointer to a traversal function for the garbage collector. This "
|
|
"is only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More "
|
|
"information about Python's garbage collection scheme can be found in "
|
|
"section :ref:`supporting-cycle-detection`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:494
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage "
|
|
"collector to detect reference cycles. A typical implementation of a :c:"
|
|
"member:`~PyTypeObject.tp_traverse` function simply calls :c:func:`Py_VISIT` "
|
|
"on each of the instance's members that are Python objects. For example, "
|
|
"this is function :c:func:`local_traverse` from the :mod:`_thread` extension "
|
|
"module::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:509
|
|
msgid ""
|
|
"Note that :c:func:`Py_VISIT` is called only on those members that can "
|
|
"participate in reference cycles. Although there is also a ``self->key`` "
|
|
"member, it can only be *NULL* or a Python string and therefore cannot be "
|
|
"part of a reference cycle."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:513
|
|
msgid ""
|
|
"On the other hand, even if you know a member can never be part of a cycle, "
|
|
"as a debugging aid you may want to visit it anyway just so the :mod:`gc` "
|
|
"module's :func:`~gc.get_referents` function will include it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:517
|
|
msgid ""
|
|
"Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to :c:"
|
|
"func:`local_traverse` to have these specific names; don't name them just "
|
|
"anything."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:521
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_clear` and the :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:"
|
|
"member:`~PyTypeObject.tp_traverse`, and :c:member:`~PyTypeObject.tp_clear` "
|
|
"are all inherited from the base type if they are all zero in the subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:529
|
|
msgid ""
|
|
"An optional pointer to a clear function for the garbage collector. This is "
|
|
"only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:532
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_clear` member function is used to break "
|
|
"reference cycles in cyclic garbage detected by the garbage collector. Taken "
|
|
"together, all :c:member:`~PyTypeObject.tp_clear` functions in the system "
|
|
"must combine to break all reference cycles. This is subtle, and if in any "
|
|
"doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For example, "
|
|
"the tuple type does not implement a :c:member:`~PyTypeObject.tp_clear` "
|
|
"function, because it's possible to prove that no reference cycle can be "
|
|
"composed entirely of tuples. Therefore the :c:member:`~PyTypeObject."
|
|
"tp_clear` functions of other types must be sufficient to break any cycle "
|
|
"containing a tuple. This isn't immediately obvious, and there's rarely a "
|
|
"good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:542
|
|
msgid ""
|
|
"Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the "
|
|
"instance's references to those of its members that may be Python objects, "
|
|
"and set its pointers to those members to *NULL*, as in the following "
|
|
"example::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:556
|
|
msgid ""
|
|
"The :c:func:`Py_CLEAR` macro should be used, because clearing references is "
|
|
"delicate: the reference to the contained object must not be decremented "
|
|
"until after the pointer to the contained object is set to *NULL*. This is "
|
|
"because decrementing the reference count may cause the contained object to "
|
|
"become trash, triggering a chain of reclamation activity that may include "
|
|
"invoking arbitrary Python code (due to finalizers, or weakref callbacks, "
|
|
"associated with the contained object). If it's possible for such code to "
|
|
"reference *self* again, it's important that the pointer to the contained "
|
|
"object be *NULL* at that time, so that *self* knows the contained object can "
|
|
"no longer be used. The :c:func:`Py_CLEAR` macro performs the operations in "
|
|
"a safe order."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:567
|
|
msgid ""
|
|
"Because the goal of :c:member:`~PyTypeObject.tp_clear` functions is to break "
|
|
"reference cycles, it's not necessary to clear contained objects like Python "
|
|
"strings or Python integers, which can't participate in reference cycles. On "
|
|
"the other hand, it may be convenient to clear all contained Python objects, "
|
|
"and write the type's :c:member:`~PyTypeObject.tp_dealloc` function to "
|
|
"invoke :c:member:`~PyTypeObject.tp_clear`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:573
|
|
msgid ""
|
|
"More information about Python's garbage collection scheme can be found in "
|
|
"section :ref:`supporting-cycle-detection`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:576
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_traverse` and the :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:"
|
|
"member:`~PyTypeObject.tp_traverse`, and :c:member:`~PyTypeObject.tp_clear` "
|
|
"are all inherited from the base type if they are all zero in the subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:584
|
|
msgid ""
|
|
"An optional pointer to the rich comparison function, whose signature is "
|
|
"``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``. The first "
|
|
"parameter is guaranteed to be an instance of the type that is defined by :c:"
|
|
"type:`PyTypeObject`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:589
|
|
msgid ""
|
|
"The function should return the result of the comparison (usually ``Py_True`` "
|
|
"or ``Py_False``). If the comparison is undefined, it must return "
|
|
"``Py_NotImplemented``, if another error occurred it must return ``NULL`` and "
|
|
"set an exception condition."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:596
|
|
msgid ""
|
|
"If you want to implement a type for which only a limited set of comparisons "
|
|
"makes sense (e.g. ``==`` and ``!=``, but not ``<`` and friends), directly "
|
|
"raise :exc:`TypeError` in the rich comparison function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:600
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_hash`: a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:"
|
|
"member:`~PyTypeObject.tp_hash` when the subtype's :c:member:`~PyTypeObject."
|
|
"tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:605
|
|
msgid ""
|
|
"The following constants are defined to be used as the third argument for :c:"
|
|
"member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:609
|
|
msgid "Constant"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:609
|
|
msgid "Comparison"
|
|
msgstr "Comparaison"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:611
|
|
msgid ":const:`Py_LT`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:611
|
|
msgid "``<``"
|
|
msgstr "``<``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:613
|
|
msgid ":const:`Py_LE`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:613
|
|
msgid "``<=``"
|
|
msgstr "``<=``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:615
|
|
msgid ":const:`Py_EQ`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:615
|
|
msgid "``==``"
|
|
msgstr "``==``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:617
|
|
msgid ":const:`Py_NE`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:617
|
|
msgid "``!=``"
|
|
msgstr "``!=``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:619
|
|
msgid ":const:`Py_GT`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:619
|
|
msgid "``>``"
|
|
msgstr "``>``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:621
|
|
msgid ":const:`Py_GE`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:621
|
|
msgid "``>=``"
|
|
msgstr "``>=``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:627
|
|
msgid ""
|
|
"If the instances of this type are weakly referenceable, this field is "
|
|
"greater than zero and contains the offset in the instance structure of the "
|
|
"weak reference list head (ignoring the GC header, if present); this offset "
|
|
"is used by :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\\*` "
|
|
"functions. The instance structure needs to include a field of type :c:type:"
|
|
"`PyObject\\*` which is initialized to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:634
|
|
msgid ""
|
|
"Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that "
|
|
"is the list head for weak references to the type object itself."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:637
|
|
msgid ""
|
|
"This field is inherited by subtypes, but see the rules listed below. A "
|
|
"subtype may override this offset; this means that the subtype uses a "
|
|
"different weak reference list head than the base type. Since the list head "
|
|
"is always found via :c:member:`~PyTypeObject.tp_weaklistoffset`, this should "
|
|
"not be a problem."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:642
|
|
msgid ""
|
|
"When a type defined by a class statement has no :attr:`~object.__slots__` "
|
|
"declaration, and none of its base types are weakly referenceable, the type "
|
|
"is made weakly referenceable by adding a weak reference list head slot to "
|
|
"the instance layout and setting the :c:member:`~PyTypeObject."
|
|
"tp_weaklistoffset` of that slot's offset."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:647
|
|
msgid ""
|
|
"When a type's :attr:`__slots__` declaration contains a slot named :attr:"
|
|
"`__weakref__`, that slot becomes the weak reference list head for instances "
|
|
"of the type, and the slot's offset is stored in the type's :c:member:"
|
|
"`~PyTypeObject.tp_weaklistoffset`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:652
|
|
msgid ""
|
|
"When a type's :attr:`__slots__` declaration does not contain a slot named :"
|
|
"attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject."
|
|
"tp_weaklistoffset` from its base type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:658
|
|
msgid ""
|
|
"An optional pointer to a function that returns an iterator for the object. "
|
|
"Its presence normally signals that the instances of this type are iterable "
|
|
"(although sequences may be iterable without this function)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:662
|
|
msgid "This function has the same signature as :c:func:`PyObject_GetIter`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:669
|
|
msgid ""
|
|
"An optional pointer to a function that returns the next item in an iterator. "
|
|
"When the iterator is exhausted, it must return *NULL*; a :exc:"
|
|
"`StopIteration` exception may or may not be set. When another error occurs, "
|
|
"it must return *NULL* too. Its presence signals that the instances of this "
|
|
"type are iterators."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:675
|
|
msgid ""
|
|
"Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` "
|
|
"function, and that function should return the iterator instance itself (not "
|
|
"a new iterator instance)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:679
|
|
msgid "This function has the same signature as :c:func:`PyIter_Next`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:686
|
|
msgid ""
|
|
"An optional pointer to a static *NULL*-terminated array of :c:type:"
|
|
"`PyMethodDef` structures, declaring regular methods of this type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:689
|
|
msgid ""
|
|
"For each entry in the array, an entry is added to the type's dictionary "
|
|
"(see :c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:692
|
|
msgid ""
|
|
"This field is not inherited by subtypes (methods are inherited through a "
|
|
"different mechanism)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:698
|
|
msgid ""
|
|
"An optional pointer to a static *NULL*-terminated array of :c:type:"
|
|
"`PyMemberDef` structures, declaring regular data members (fields or slots) "
|
|
"of instances of this type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:702
|
|
msgid ""
|
|
"For each entry in the array, an entry is added to the type's dictionary "
|
|
"(see :c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:705
|
|
msgid ""
|
|
"This field is not inherited by subtypes (members are inherited through a "
|
|
"different mechanism)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:711
|
|
msgid ""
|
|
"An optional pointer to a static *NULL*-terminated array of :c:type:"
|
|
"`PyGetSetDef` structures, declaring computed attributes of instances of this "
|
|
"type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:714
|
|
msgid ""
|
|
"For each entry in the array, an entry is added to the type's dictionary "
|
|
"(see :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:717
|
|
msgid ""
|
|
"This field is not inherited by subtypes (computed attributes are inherited "
|
|
"through a different mechanism)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:722
|
|
msgid "Docs for PyGetSetDef::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:738
|
|
msgid ""
|
|
"An optional pointer to a base type from which type properties are "
|
|
"inherited. At this level, only single inheritance is supported; multiple "
|
|
"inheritance require dynamically creating a type object by calling the "
|
|
"metatype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:742
|
|
msgid ""
|
|
"This field is not inherited by subtypes (obviously), but it defaults to "
|
|
"``&PyBaseObject_Type`` (which to Python programmers is known as the type :"
|
|
"class:`object`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:749
|
|
msgid "The type's dictionary is stored here by :c:func:`PyType_Ready`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:751
|
|
msgid ""
|
|
"This field should normally be initialized to *NULL* before PyType_Ready is "
|
|
"called; it may also be initialized to a dictionary containing initial "
|
|
"attributes for the type. Once :c:func:`PyType_Ready` has initialized the "
|
|
"type, extra attributes for the type may be added to this dictionary only if "
|
|
"they don't correspond to overloaded operations (like :meth:`__add__`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:757
|
|
msgid ""
|
|
"This field is not inherited by subtypes (though the attributes defined in "
|
|
"here are inherited through a different mechanism)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:762
|
|
msgid ""
|
|
"It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify :c:"
|
|
"member:`~PyTypeObject.tp_dict` with the dictionary C-API."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:768
|
|
msgid "An optional pointer to a \"descriptor get\" function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:770 ../Doc/c-api/typeobj.rst:784
|
|
#: ../Doc/c-api/typeobj.rst:856 ../Doc/c-api/typeobj.rst:878
|
|
#: ../Doc/c-api/typeobj.rst:909
|
|
msgid "The function signature is ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:781
|
|
msgid ""
|
|
"An optional pointer to a function for setting and deleting a descriptor's "
|
|
"value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:788
|
|
msgid ""
|
|
"The *value* argument is set to *NULL* to delete the value. This field is "
|
|
"inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:796
|
|
msgid ""
|
|
"If the instances of this type have a dictionary containing instance "
|
|
"variables, this field is non-zero and contains the offset in the instances "
|
|
"of the type of the instance variable dictionary; this offset is used by :c:"
|
|
"func:`PyObject_GenericGetAttr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:801
|
|
msgid ""
|
|
"Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is "
|
|
"the dictionary for attributes of the type object itself."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:804
|
|
msgid ""
|
|
"If the value of this field is greater than zero, it specifies the offset "
|
|
"from the start of the instance structure. If the value is less than zero, "
|
|
"it specifies the offset from the *end* of the instance structure. A "
|
|
"negative offset is more expensive to use, and should only be used when the "
|
|
"instance structure contains a variable-length part. This is used for "
|
|
"example to add an instance variable dictionary to subtypes of :class:`str` "
|
|
"or :class:`tuple`. Note that the :c:member:`~PyTypeObject.tp_basicsize` "
|
|
"field should account for the dictionary added to the end in that case, even "
|
|
"though the dictionary is not included in the basic object layout. On a "
|
|
"system with a pointer size of 4 bytes, :c:member:`~PyTypeObject."
|
|
"tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is at "
|
|
"the very end of the structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:816
|
|
msgid ""
|
|
"The real dictionary offset in an instance can be computed from a negative :c:"
|
|
"member:`~PyTypeObject.tp_dictoffset` as follows::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:823
|
|
msgid ""
|
|
"where :c:member:`~PyTypeObject.tp_basicsize`, :c:member:`~PyTypeObject."
|
|
"tp_itemsize` and :c:member:`~PyTypeObject.tp_dictoffset` are taken from the "
|
|
"type object, and :attr:`ob_size` is taken from the instance. The absolute "
|
|
"value is taken because ints use the sign of :attr:`ob_size` to store the "
|
|
"sign of the number. (There's never a need to do this calculation yourself; "
|
|
"it is done for you by :c:func:`_PyObject_GetDictPtr`.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:829
|
|
msgid ""
|
|
"This field is inherited by subtypes, but see the rules listed below. A "
|
|
"subtype may override this offset; this means that the subtype instances "
|
|
"store the dictionary at a difference offset than the base type. Since the "
|
|
"dictionary is always found via :c:member:`~PyTypeObject.tp_dictoffset`, this "
|
|
"should not be a problem."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:834
|
|
msgid ""
|
|
"When a type defined by a class statement has no :attr:`~object.__slots__` "
|
|
"declaration, and none of its base types has an instance variable dictionary, "
|
|
"a dictionary slot is added to the instance layout and the :c:member:"
|
|
"`~PyTypeObject.tp_dictoffset` is set to that slot's offset."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:839
|
|
msgid ""
|
|
"When a type defined by a class statement has a :attr:`__slots__` "
|
|
"declaration, the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` "
|
|
"from its base type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:842
|
|
msgid ""
|
|
"(Adding a slot named :attr:`~object.__dict__` to the :attr:`__slots__` "
|
|
"declaration does not have the expected effect, it just causes confusion. "
|
|
"Maybe this should be added as a feature just like :attr:`__weakref__` "
|
|
"though.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:849
|
|
msgid "An optional pointer to an instance initialization function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:851
|
|
msgid ""
|
|
"This function corresponds to the :meth:`__init__` method of classes. Like :"
|
|
"meth:`__init__`, it is possible to create an instance without calling :meth:"
|
|
"`__init__`, and it is possible to reinitialize an instance by calling its :"
|
|
"meth:`__init__` method again."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:860
|
|
msgid ""
|
|
"The self argument is the instance to be initialized; the *args* and *kwds* "
|
|
"arguments represent positional and keyword arguments of the call to :meth:"
|
|
"`__init__`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:864
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_init` function, if not *NULL*, is called "
|
|
"when an instance is created normally by calling its type, after the type's :"
|
|
"c:member:`~PyTypeObject.tp_new` function has returned an instance of the "
|
|
"type. If the :c:member:`~PyTypeObject.tp_new` function returns an instance "
|
|
"of some other type that is not a subtype of the original type, no :c:member:"
|
|
"`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject."
|
|
"tp_new` returns an instance of a subtype of the original type, the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_init` is called."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:876
|
|
msgid "An optional pointer to an instance allocation function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:882
|
|
msgid ""
|
|
"The purpose of this function is to separate memory allocation from memory "
|
|
"initialization. It should return a pointer to a block of memory of adequate "
|
|
"length for the instance, suitably aligned, and initialized to zeros, but "
|
|
"with :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type "
|
|
"argument. If the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, "
|
|
"the object's :attr:`ob_size` field should be initialized to *nitems* and the "
|
|
"length of the allocated memory block should be ``tp_basicsize + "
|
|
"nitems*tp_itemsize``, rounded up to a multiple of ``sizeof(void*)``; "
|
|
"otherwise, *nitems* is not used and the length of the block should be :c:"
|
|
"member:`~PyTypeObject.tp_basicsize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:892
|
|
msgid ""
|
|
"Do not use this function to do any other instance initialization, not even "
|
|
"to allocate additional memory; that should be done by :c:member:"
|
|
"`~PyTypeObject.tp_new`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:895
|
|
msgid ""
|
|
"This field is inherited by static subtypes, but not by dynamic subtypes "
|
|
"(subtypes created by a class statement); in the latter, this field is always "
|
|
"set to :c:func:`PyType_GenericAlloc`, to force a standard heap allocation "
|
|
"strategy. That is also the recommended value for statically defined types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:903
|
|
msgid "An optional pointer to an instance creation function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:905
|
|
msgid ""
|
|
"If this function is *NULL* for a particular type, that type cannot be called "
|
|
"to create new instances; presumably there is some other way to create "
|
|
"instances, like a factory function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:913
|
|
msgid ""
|
|
"The subtype argument is the type of the object being created; the *args* and "
|
|
"*kwds* arguments represent positional and keyword arguments of the call to "
|
|
"the type. Note that subtype doesn't have to equal the type whose :c:member:"
|
|
"`~PyTypeObject.tp_new` function is called; it may be a subtype of that type "
|
|
"(but not an unrelated type)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:919
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_new` function should call ``subtype-"
|
|
">tp_alloc(subtype, nitems)`` to allocate space for the object, and then do "
|
|
"only as much further initialization as is absolutely necessary. "
|
|
"Initialization that can safely be ignored or repeated should be placed in "
|
|
"the :c:member:`~PyTypeObject.tp_init` handler. A good rule of thumb is that "
|
|
"for immutable types, all initialization should take place in :c:member:"
|
|
"`~PyTypeObject.tp_new`, while for mutable types, most initialization should "
|
|
"be deferred to :c:member:`~PyTypeObject.tp_init`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:927
|
|
msgid ""
|
|
"This field is inherited by subtypes, except it is not inherited by static "
|
|
"types whose :c:member:`~PyTypeObject.tp_base` is *NULL* or "
|
|
"``&PyBaseObject_Type``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:933
|
|
msgid ""
|
|
"An optional pointer to an instance deallocation function. Its signature is :"
|
|
"c:type:`freefunc`::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:938
|
|
msgid ""
|
|
"An initializer that is compatible with this signature is :c:func:"
|
|
"`PyObject_Free`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:940
|
|
msgid ""
|
|
"This field is inherited by static subtypes, but not by dynamic subtypes "
|
|
"(subtypes created by a class statement); in the latter, this field is set to "
|
|
"a deallocator suitable to match :c:func:`PyType_GenericAlloc` and the value "
|
|
"of the :const:`Py_TPFLAGS_HAVE_GC` flag bit."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:948
|
|
msgid "An optional pointer to a function called by the garbage collector."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:950
|
|
msgid ""
|
|
"The garbage collector needs to know whether a particular object is "
|
|
"collectible or not. Normally, it is sufficient to look at the object's "
|
|
"type's :c:member:`~PyTypeObject.tp_flags` field, and check the :const:"
|
|
"`Py_TPFLAGS_HAVE_GC` flag bit. But some types have a mixture of statically "
|
|
"and dynamically allocated instances, and the statically allocated instances "
|
|
"are not collectible. Such types should define this function; it should "
|
|
"return ``1`` for a collectible instance, and ``0`` for a non-collectible "
|
|
"instance. The signature is ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:960
|
|
msgid ""
|
|
"(The only example of this are types themselves. The metatype, :c:data:"
|
|
"`PyType_Type`, defines this function to distinguish between statically and "
|
|
"dynamically allocated types.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:969
|
|
msgid "Tuple of base types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:971
|
|
msgid ""
|
|
"This is set for types created by a class statement. It should be *NULL* for "
|
|
"statically defined types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:974
|
|
msgid "This field is not inherited."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:979
|
|
msgid ""
|
|
"Tuple containing the expanded set of base types, starting with the type "
|
|
"itself and ending with :class:`object`, in Method Resolution Order."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:982
|
|
msgid ""
|
|
"This field is not inherited; it is calculated fresh by :c:func:"
|
|
"`PyType_Ready`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:987
|
|
msgid ""
|
|
"An optional pointer to an instance finalization function. Its signature is :"
|
|
"c:type:`destructor`::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:992
|
|
msgid ""
|
|
"If :c:member:`~PyTypeObject.tp_finalize` is set, the interpreter calls it "
|
|
"once when finalizing an instance. It is called either from the garbage "
|
|
"collector (if the instance is part of an isolated reference cycle) or just "
|
|
"before the object is deallocated. Either way, it is guaranteed to be called "
|
|
"before attempting to break reference cycles, ensuring that it finds the "
|
|
"object in a sane state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:999
|
|
msgid ""
|
|
":c:member:`~PyTypeObject.tp_finalize` should not mutate the current "
|
|
"exception status; therefore, a recommended way to write a non-trivial "
|
|
"finalizer is::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1016
|
|
msgid ""
|
|
"For this field to be taken into account (even through inheritance), you must "
|
|
"also set the :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1023
|
|
msgid "\"Safe object finalization\" (:pep:`442`)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1028
|
|
msgid "Unused. Not inherited. Internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1033
|
|
msgid ""
|
|
"List of weak references to subclasses. Not inherited. Internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1038
|
|
msgid ""
|
|
"Weak reference list head, for weak references to this type object. Not "
|
|
"inherited. Internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1041
|
|
msgid ""
|
|
"The remaining fields are only defined if the feature test macro :const:"
|
|
"`COUNT_ALLOCS` is defined, and are for internal use only. They are "
|
|
"documented here for completeness. None of these fields are inherited by "
|
|
"subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1049
|
|
msgid "Number of allocations."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1054
|
|
msgid "Number of frees."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1059
|
|
msgid "Maximum simultaneously allocated objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1064
|
|
msgid ""
|
|
"Pointer to the next type object with a non-zero :c:member:`~PyTypeObject."
|
|
"tp_allocs` field."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1066
|
|
msgid ""
|
|
"Also, note that, in a garbage collected Python, tp_dealloc may be called "
|
|
"from any Python thread, not just the thread which created the object (if the "
|
|
"object becomes part of a refcount cycle, that cycle might be collected by a "
|
|
"garbage collection on any thread). This is not a problem for Python API "
|
|
"calls, since the thread on which tp_dealloc is called will own the Global "
|
|
"Interpreter Lock (GIL). However, if the object being destroyed in turn "
|
|
"destroys objects from some other C or C++ library, care should be taken to "
|
|
"ensure that destroying those objects on the thread which called tp_dealloc "
|
|
"will not violate any assumptions of the library."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1080
|
|
msgid "Number Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1087
|
|
msgid ""
|
|
"This structure holds pointers to the functions which an object uses to "
|
|
"implement the number protocol. Each function is used by the function of "
|
|
"similar name documented in the :ref:`number` section."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1091 ../Doc/c-api/typeobj.rst:1364
|
|
msgid "Here is the structure definition::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1138
|
|
msgid ""
|
|
"Binary and ternary functions must check the type of all their operands, and "
|
|
"implement the necessary conversions (at least one of the operands is an "
|
|
"instance of the defined type). If the operation is not defined for the "
|
|
"given operands, binary and ternary functions must return "
|
|
"``Py_NotImplemented``, if another error occurred they must return ``NULL`` "
|
|
"and set an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1147
|
|
msgid ""
|
|
"The :c:data:`nb_reserved` field should always be ``NULL``. It was "
|
|
"previously called :c:data:`nb_long`, and was renamed in Python 3.0.1."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1155
|
|
msgid "Mapping Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1162
|
|
msgid ""
|
|
"This structure holds pointers to the functions which an object uses to "
|
|
"implement the mapping protocol. It has three members:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1167
|
|
msgid ""
|
|
"This function is used by :c:func:`PyMapping_Length` and :c:func:"
|
|
"`PyObject_Size`, and has the same signature. This slot may be set to *NULL* "
|
|
"if the object has no defined length."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1173
|
|
msgid ""
|
|
"This function is used by :c:func:`PyObject_GetItem` and has the same "
|
|
"signature. This slot must be filled for the :c:func:`PyMapping_Check` "
|
|
"function to return ``1``, it can be *NULL* otherwise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1179
|
|
msgid ""
|
|
"This function is used by :c:func:`PyObject_SetItem` and :c:func:"
|
|
"`PyObject_DelItem`. It has the same signature as :c:func:"
|
|
"`PyObject_SetItem`, but *v* can also be set to *NULL* to delete an item. If "
|
|
"this slot is *NULL*, the object does not support item assignment and "
|
|
"deletion."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1189
|
|
msgid "Sequence Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1196
|
|
msgid ""
|
|
"This structure holds pointers to the functions which an object uses to "
|
|
"implement the sequence protocol."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1201
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_Size` and :c:func:"
|
|
"`PyObject_Size`, and has the same signature."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1206
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_Concat` and has the same "
|
|
"signature. It is also used by the ``+`` operator, after trying the numeric "
|
|
"addition via the :c:member:`~PyTypeObject.tp_as_number.nb_add` slot."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1212
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_Repeat` and has the same "
|
|
"signature. It is also used by the ``*`` operator, after trying numeric "
|
|
"multiplication via the :c:member:`~PyTypeObject.tp_as_number.nb_multiply` "
|
|
"slot."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1219
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_GetItem` and has the same "
|
|
"signature. This slot must be filled for the :c:func:`PySequence_Check` "
|
|
"function to return ``1``, it can be *NULL* otherwise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1223
|
|
msgid ""
|
|
"Negative indexes are handled as follows: if the :attr:`sq_length` slot is "
|
|
"filled, it is called and the sequence length is used to compute a positive "
|
|
"index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*, "
|
|
"the index is passed as is to the function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1230
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_SetItem` and has the same "
|
|
"signature. This slot may be left to *NULL* if the object does not support "
|
|
"item assignment and deletion."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1236
|
|
msgid ""
|
|
"This function may be used by :c:func:`PySequence_Contains` and has the same "
|
|
"signature. This slot may be left to *NULL*, in this case :c:func:"
|
|
"`PySequence_Contains` simply traverses the sequence until it finds a match."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1243
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_InPlaceConcat` and has the same "
|
|
"signature. It should modify its first operand, and return it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1248
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same "
|
|
"signature. It should modify its first operand, and return it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1258
|
|
msgid "Buffer Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1266
|
|
msgid ""
|
|
"This structure holds pointers to the functions required by the :ref:`Buffer "
|
|
"protocol <bufferobjects>`. The protocol defines how an exporter object can "
|
|
"expose its internal data to consumer objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1272 ../Doc/c-api/typeobj.rst:1321
|
|
#: ../Doc/c-api/typeobj.rst:1374 ../Doc/c-api/typeobj.rst:1385
|
|
#: ../Doc/c-api/typeobj.rst:1396
|
|
msgid "The signature of this function is::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1276
|
|
msgid ""
|
|
"Handle a request to *exporter* to fill in *view* as specified by *flags*. "
|
|
"Except for point (3), an implementation of this function MUST take these "
|
|
"steps:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1280
|
|
msgid ""
|
|
"Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`, "
|
|
"set :c:data:`view->obj` to *NULL* and return -1."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1283
|
|
msgid "Fill in the requested fields."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1285
|
|
msgid "Increment an internal counter for the number of exports."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1287
|
|
msgid ""
|
|
"Set :c:data:`view->obj` to *exporter* and increment :c:data:`view->obj`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1289
|
|
msgid "Return 0."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1291
|
|
msgid ""
|
|
"If *exporter* is part of a chain or tree of buffer providers, two main "
|
|
"schemes can be used:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1294
|
|
msgid ""
|
|
"Re-export: Each member of the tree acts as the exporting object and sets :c:"
|
|
"data:`view->obj` to a new reference to itself."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1297
|
|
msgid ""
|
|
"Redirect: The buffer request is redirected to the root object of the tree. "
|
|
"Here, :c:data:`view->obj` will be a new reference to the root object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1301
|
|
msgid ""
|
|
"The individual fields of *view* are described in section :ref:`Buffer "
|
|
"structure <buffer-structure>`, the rules how an exporter must react to "
|
|
"specific requests are in section :ref:`Buffer request types <buffer-request-"
|
|
"types>`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1306
|
|
msgid ""
|
|
"All memory pointed to in the :c:type:`Py_buffer` structure belongs to the "
|
|
"exporter and must remain valid until there are no consumers left. :c:member:"
|
|
"`~Py_buffer.format`, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer."
|
|
"strides`, :c:member:`~Py_buffer.suboffsets` and :c:member:`~Py_buffer."
|
|
"internal` are read-only for the consumer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1313
|
|
msgid ""
|
|
":c:func:`PyBuffer_FillInfo` provides an easy way of exposing a simple bytes "
|
|
"buffer while dealing correctly with all request types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1316
|
|
msgid ""
|
|
":c:func:`PyObject_GetBuffer` is the interface for the consumer that wraps "
|
|
"this function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1325
|
|
msgid ""
|
|
"Handle a request to release the resources of the buffer. If no resources "
|
|
"need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be "
|
|
"*NULL*. Otherwise, a standard implementation of this function will take "
|
|
"these optional steps:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1330
|
|
msgid "Decrement an internal counter for the number of exports."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1332
|
|
msgid "If the counter is 0, free all memory associated with *view*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1334
|
|
msgid ""
|
|
"The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep "
|
|
"track of buffer-specific resources. This field is guaranteed to remain "
|
|
"constant, while a consumer MAY pass a copy of the original buffer as the "
|
|
"*view* argument."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1340
|
|
msgid ""
|
|
"This function MUST NOT decrement :c:data:`view->obj`, since that is done "
|
|
"automatically in :c:func:`PyBuffer_Release` (this scheme is useful for "
|
|
"breaking reference cycles)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1345
|
|
msgid ""
|
|
":c:func:`PyBuffer_Release` is the interface for the consumer that wraps this "
|
|
"function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1353
|
|
msgid "Async Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1361
|
|
msgid ""
|
|
"This structure holds pointers to the functions required to implement :term:"
|
|
"`awaitable` and :term:`asynchronous iterator` objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1378
|
|
msgid ""
|
|
"The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must "
|
|
"return ``1`` for it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1381
|
|
msgid ""
|
|
"This slot may be set to *NULL* if an object is not an :term:`awaitable`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1389
|
|
msgid ""
|
|
"Must return an :term:`awaitable` object. See :meth:`__anext__` for details."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1391
|
|
msgid ""
|
|
"This slot may be set to *NULL* if an object does not implement asynchronous "
|
|
"iteration protocol."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1400
|
|
msgid ""
|
|
"Must return an :term:`awaitable` object. See :meth:`__anext__` for details. "
|
|
"This slot may be set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:6
|
|
msgid "Unicode Objects and Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:12
|
|
msgid "Unicode Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:14
|
|
msgid ""
|
|
"Since the implementation of :pep:`393` in Python 3.3, Unicode objects "
|
|
"internally use a variety of representations, in order to allow handling the "
|
|
"complete range of Unicode characters while staying memory efficient. There "
|
|
"are special cases for strings where all code points are below 128, 256, or "
|
|
"65536; otherwise, code points must be below 1114112 (which is the full "
|
|
"Unicode range)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:20
|
|
msgid ""
|
|
":c:type:`Py_UNICODE*` and UTF-8 representations are created on demand and "
|
|
"cached in the Unicode object. The :c:type:`Py_UNICODE*` representation is "
|
|
"deprecated and inefficient; it should be avoided in performance- or memory-"
|
|
"sensitive situations."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:25
|
|
msgid ""
|
|
"Due to the transition between the old APIs and the new APIs, unicode objects "
|
|
"can internally be in two states depending on how they were created:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:28
|
|
msgid ""
|
|
"\"canonical\" unicode objects are all objects created by a non-deprecated "
|
|
"unicode API. They use the most efficient representation allowed by the "
|
|
"implementation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:32
|
|
msgid ""
|
|
"\"legacy\" unicode objects have been created through one of the deprecated "
|
|
"APIs (typically :c:func:`PyUnicode_FromUnicode`) and only bear the :c:type:"
|
|
"`Py_UNICODE*` representation; you will have to call :c:func:"
|
|
"`PyUnicode_READY` on them before calling any other API."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:39
|
|
msgid "Unicode Type"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:41
|
|
msgid ""
|
|
"These are the basic Unicode object types used for the Unicode implementation "
|
|
"in Python:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:48
|
|
msgid ""
|
|
"These types are typedefs for unsigned integer types wide enough to contain "
|
|
"characters of 32 bits, 16 bits and 8 bits, respectively. When dealing with "
|
|
"single Unicode characters, use :c:type:`Py_UCS4`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:57
|
|
msgid ""
|
|
"This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit "
|
|
"type depending on the platform."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:60
|
|
msgid ""
|
|
"In previous versions, this was a 16-bit type or a 32-bit type depending on "
|
|
"whether you selected a \"narrow\" or \"wide\" Unicode version of Python at "
|
|
"build time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:70
|
|
msgid ""
|
|
"These subtypes of :c:type:`PyObject` represent a Python Unicode object. In "
|
|
"almost all cases, they shouldn't be used directly, since all API functions "
|
|
"that deal with Unicode objects take and return :c:type:`PyObject` pointers."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:79
|
|
msgid ""
|
|
"This instance of :c:type:`PyTypeObject` represents the Python Unicode type. "
|
|
"It is exposed to Python code as ``str``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:83
|
|
msgid ""
|
|
"The following APIs are really C macros and can be used to do fast checks and "
|
|
"to access internal read-only data of Unicode objects:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:88
|
|
msgid ""
|
|
"Return true if the object *o* is a Unicode object or an instance of a "
|
|
"Unicode subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:94
|
|
msgid ""
|
|
"Return true if the object *o* is a Unicode object, but not an instance of a "
|
|
"subtype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:100
|
|
msgid ""
|
|
"Ensure the string object *o* is in the \"canonical\" representation. This "
|
|
"is required before using any of the access macros described below."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:105
|
|
msgid ""
|
|
"Returns 0 on success and -1 with an exception set on failure, which in "
|
|
"particular happens if memory allocation fails."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:113
|
|
msgid ""
|
|
"Return the length of the Unicode string, in code points. *o* has to be a "
|
|
"Unicode object in the \"canonical\" representation (not checked)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:123
|
|
msgid ""
|
|
"Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4 "
|
|
"integer types for direct character access. No checks are performed if the "
|
|
"canonical representation has the correct character size; use :c:func:"
|
|
"`PyUnicode_KIND` to select the right macro. Make sure :c:func:"
|
|
"`PyUnicode_READY` has been called before accessing this."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:137
|
|
msgid "Return values of the :c:func:`PyUnicode_KIND` macro."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:144
|
|
msgid ""
|
|
"Return one of the PyUnicode kind constants (see above) that indicate how "
|
|
"many bytes per character this Unicode object uses to store its data. *o* "
|
|
"has to be a Unicode object in the \"canonical\" representation (not checked)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:155
|
|
msgid ""
|
|
"Return a void pointer to the raw unicode buffer. *o* has to be a Unicode "
|
|
"object in the \"canonical\" representation (not checked)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:164
|
|
msgid ""
|
|
"Write into a canonical representation *data* (as obtained with :c:func:"
|
|
"`PyUnicode_DATA`). This macro does not do any sanity checks and is intended "
|
|
"for usage in loops. The caller should cache the *kind* value and *data* "
|
|
"pointer as obtained from other macro calls. *index* is the index in the "
|
|
"string (starts at 0) and *value* is the new code point value which should be "
|
|
"written to that location."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:176
|
|
msgid ""
|
|
"Read a code point from a canonical representation *data* (as obtained with :"
|
|
"c:func:`PyUnicode_DATA`). No checks or ready calls are performed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:184
|
|
msgid ""
|
|
"Read a character from a Unicode object *o*, which must be in the \"canonical"
|
|
"\" representation. This is less efficient than :c:func:`PyUnicode_READ` if "
|
|
"you do multiple consecutive reads."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:193
|
|
msgid ""
|
|
"Return the maximum code point that is suitable for creating another string "
|
|
"based on *o*, which must be in the \"canonical\" representation. This is "
|
|
"always an approximation but more efficient than iterating over the string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:207
|
|
msgid ""
|
|
"Return the size of the deprecated :c:type:`Py_UNICODE` representation, in "
|
|
"code units (this includes surrogate pairs as 2 units). *o* has to be a "
|
|
"Unicode object (not checked)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:213 ../Doc/c-api/unicode.rst:223
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Unicode API, please migrate to using PyUnicode_GET_LENGTH()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:213 ../Doc/c-api/unicode.rst:223
|
|
msgid ""
|
|
"Part of the old-style Unicode API, please migrate to using :c:func:"
|
|
"`PyUnicode_GET_LENGTH`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:218
|
|
msgid ""
|
|
"Return the size of the deprecated :c:type:`Py_UNICODE` representation in "
|
|
"bytes. *o* has to be a Unicode object (not checked)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:229
|
|
msgid ""
|
|
"Return a pointer to a :c:type:`Py_UNICODE` representation of the object. "
|
|
"The returned buffer is always terminated with an extra null code point. It "
|
|
"may also contain embedded null code points, which would cause the string to "
|
|
"be truncated when used in most C functions. The ``AS_DATA`` form casts the "
|
|
"pointer to :c:type:`const char *`. The *o* argument has to be a Unicode "
|
|
"object (not checked)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:236
|
|
msgid ""
|
|
"This macro is now inefficient -- because in many cases the :c:type:"
|
|
"`Py_UNICODE` representation does not exist and needs to be created -- and "
|
|
"can fail (return *NULL* with an exception set). Try to port the code to use "
|
|
"the new :c:func:`PyUnicode_nBYTE_DATA` macros or use :c:func:"
|
|
"`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:245
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Unicode API, please migrate to using the PyUnicode_nBYTE_DATA() "
|
|
"family of macros."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:245
|
|
msgid ""
|
|
"Part of the old-style Unicode API, please migrate to using the :c:func:"
|
|
"`PyUnicode_nBYTE_DATA` family of macros."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:249
|
|
msgid "Unicode Character Properties"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:251
|
|
msgid ""
|
|
"Unicode provides many different character properties. The most often needed "
|
|
"ones are available through these macros which are mapped to C functions "
|
|
"depending on the Python configuration."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:258
|
|
msgid "Return 1 or 0 depending on whether *ch* is a whitespace character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:263
|
|
msgid "Return 1 or 0 depending on whether *ch* is a lowercase character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:268
|
|
msgid "Return 1 or 0 depending on whether *ch* is an uppercase character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:273
|
|
msgid "Return 1 or 0 depending on whether *ch* is a titlecase character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:278
|
|
msgid "Return 1 or 0 depending on whether *ch* is a linebreak character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:283
|
|
msgid "Return 1 or 0 depending on whether *ch* is a decimal character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:288
|
|
msgid "Return 1 or 0 depending on whether *ch* is a digit character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:293
|
|
msgid "Return 1 or 0 depending on whether *ch* is a numeric character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:298
|
|
msgid "Return 1 or 0 depending on whether *ch* is an alphabetic character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:303
|
|
msgid "Return 1 or 0 depending on whether *ch* is an alphanumeric character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:308
|
|
msgid ""
|
|
"Return 1 or 0 depending on whether *ch* is a printable character. "
|
|
"Nonprintable characters are those characters defined in the Unicode "
|
|
"character database as \"Other\" or \"Separator\", excepting the ASCII space "
|
|
"(0x20) which is considered printable. (Note that printable characters in "
|
|
"this context are those which should not be escaped when :func:`repr` is "
|
|
"invoked on a string. It has no bearing on the handling of strings written "
|
|
"to :data:`sys.stdout` or :data:`sys.stderr`.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:317
|
|
msgid "These APIs can be used for fast direct character conversions:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:322
|
|
msgid "Return the character *ch* converted to lower case."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:324 ../Doc/c-api/unicode.rst:332
|
|
#: ../Doc/c-api/unicode.rst:340
|
|
msgid "This function uses simple case mappings."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:330
|
|
msgid "Return the character *ch* converted to upper case."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:338
|
|
msgid "Return the character *ch* converted to title case."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:346
|
|
msgid ""
|
|
"Return the character *ch* converted to a decimal positive integer. Return "
|
|
"``-1`` if this is not possible. This macro does not raise exceptions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:352
|
|
msgid ""
|
|
"Return the character *ch* converted to a single digit integer. Return ``-1`` "
|
|
"if this is not possible. This macro does not raise exceptions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:358
|
|
msgid ""
|
|
"Return the character *ch* converted to a double. Return ``-1.0`` if this is "
|
|
"not possible. This macro does not raise exceptions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:362
|
|
msgid "These APIs can be used to work with surrogates:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:366
|
|
msgid "Check if *ch* is a surrogate (``0xD800 <= ch <= 0xDFFF``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:370
|
|
msgid "Check if *ch* is a high surrogate (``0xD800 <= ch <= 0xDBFF``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:374
|
|
msgid "Check if *ch* is a low surrogate (``0xDC00 <= ch <= 0xDFFF``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:378
|
|
msgid ""
|
|
"Join two surrogate characters and return a single Py_UCS4 value. *high* and "
|
|
"*low* are respectively the leading and trailing surrogates in a surrogate "
|
|
"pair."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:384
|
|
msgid "Creating and accessing Unicode strings"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:386
|
|
msgid ""
|
|
"To create Unicode objects and access their basic sequence properties, use "
|
|
"these APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:391
|
|
msgid ""
|
|
"Create a new Unicode object. *maxchar* should be the true maximum code "
|
|
"point to be placed in the string. As an approximation, it can be rounded up "
|
|
"to the nearest value in the sequence 127, 255, 65535, 1114111."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:395
|
|
msgid ""
|
|
"This is the recommended way to allocate a new Unicode object. Objects "
|
|
"created using this function are not resizable."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:404
|
|
msgid ""
|
|
"Create a new Unicode object with the given *kind* (possible values are :c:"
|
|
"macro:`PyUnicode_1BYTE_KIND` etc., as returned by :c:func:"
|
|
"`PyUnicode_KIND`). The *buffer* must point to an array of *size* units of "
|
|
"1, 2 or 4 bytes per character, as given by the kind."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:414
|
|
msgid ""
|
|
"Create a Unicode object from the char buffer *u*. The bytes will be "
|
|
"interpreted as being UTF-8 encoded. The buffer is copied into the new "
|
|
"object. If the buffer is not *NULL*, the return value might be a shared "
|
|
"object, i.e. modification of the data is not allowed."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:419
|
|
msgid ""
|
|
"If *u* is *NULL*, this function behaves like :c:func:`PyUnicode_FromUnicode` "
|
|
"with the buffer set to *NULL*. This usage is deprecated in favor of :c:func:"
|
|
"`PyUnicode_New`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:426
|
|
msgid ""
|
|
"Create a Unicode object from a UTF-8 encoded null-terminated char buffer *u*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:432
|
|
msgid ""
|
|
"Take a C :c:func:`printf`\\ -style *format* string and a variable number of "
|
|
"arguments, calculate the size of the resulting Python unicode string and "
|
|
"return a string with the values formatted into it. The variable arguments "
|
|
"must be C types and must correspond exactly to the format characters in the "
|
|
"*format* ASCII-encoded string. The following format characters are allowed:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:451
|
|
msgid "A single character, represented as a C int."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:463
|
|
msgid ":attr:`%li`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:463
|
|
msgid "Exactly equivalent to ``printf(\"%li\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:469
|
|
msgid ":attr:`%lld`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:469
|
|
msgid "Exactly equivalent to ``printf(\"%lld\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:472
|
|
msgid ":attr:`%lli`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:472
|
|
msgid "Exactly equivalent to ``printf(\"%lli\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:475
|
|
msgid ":attr:`%llu`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:475
|
|
msgid "Exactly equivalent to ``printf(\"%llu\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:481
|
|
msgid ":attr:`%zi`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:481
|
|
msgid "Exactly equivalent to ``printf(\"%zi\")``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:504
|
|
msgid ":attr:`%A`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:504 ../Doc/c-api/unicode.rst:507
|
|
#: ../Doc/c-api/unicode.rst:516 ../Doc/c-api/unicode.rst:519
|
|
msgid "PyObject\\*"
|
|
msgstr "PyObject\\*"
|
|
|
|
#: ../Doc/c-api/unicode.rst:504
|
|
msgid "The result of calling :func:`ascii`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:507
|
|
msgid ":attr:`%U`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:507
|
|
msgid "A unicode object."
|
|
msgstr "Un objet unicode."
|
|
|
|
#: ../Doc/c-api/unicode.rst:509
|
|
msgid ":attr:`%V`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:509
|
|
msgid "PyObject\\*, char \\*"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:509
|
|
msgid ""
|
|
"A unicode object (which may be *NULL*) and a null-terminated C character "
|
|
"array as a second parameter (which will be used, if the first parameter is "
|
|
"*NULL*)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:516
|
|
msgid ":attr:`%S`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:516
|
|
msgid "The result of calling :c:func:`PyObject_Str`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:519
|
|
msgid ":attr:`%R`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:519
|
|
msgid "The result of calling :c:func:`PyObject_Repr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:523
|
|
msgid ""
|
|
"An unrecognized format character causes all the rest of the format string to "
|
|
"be copied as-is to the result string, and any extra arguments discarded."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:527
|
|
msgid ""
|
|
"The width formatter unit is number of characters rather than bytes. The "
|
|
"precision formatter unit is number of bytes for ``\"%s\"`` and ``\"%V\"`` "
|
|
"(if the ``PyObject*`` argument is NULL), and a number of characters for ``"
|
|
"\"%A\"``, ``\"%U\"``, ``\"%S\"``, ``\"%R\"`` and ``\"%V\"`` (if the "
|
|
"``PyObject*`` argument is not NULL)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:533
|
|
msgid "Support for ``\"%lld\"`` and ``\"%llu\"`` added."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:536
|
|
msgid "Support for ``\"%li\"``, ``\"%lli\"`` and ``\"%zi\"`` added."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:539
|
|
msgid ""
|
|
"Support width and precision formatter for ``\"%s\"``, ``\"%A\"``, ``\"%U"
|
|
"\"``, ``\"%V\"``, ``\"%S\"``, ``\"%R\"`` added."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:546
|
|
msgid ""
|
|
"Identical to :c:func:`PyUnicode_FromFormat` except that it takes exactly two "
|
|
"arguments."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:553
|
|
msgid "Decode an encoded object *obj* to a Unicode object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:555
|
|
msgid ""
|
|
":class:`bytes`, :class:`bytearray` and other :term:`bytes-like objects "
|
|
"<bytes-like object>` are decoded according to the given *encoding* and using "
|
|
"the error handling defined by *errors*. Both can be *NULL* to have the "
|
|
"interface use the default values (see :ref:`builtincodecs` for details)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:561
|
|
msgid ""
|
|
"All other objects, including Unicode objects, cause a :exc:`TypeError` to be "
|
|
"set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:564
|
|
msgid ""
|
|
"The API returns *NULL* if there was an error. The caller is responsible for "
|
|
"decref'ing the returned objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:570
|
|
msgid "Return the length of the Unicode object, in code points."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:581
|
|
msgid ""
|
|
"Copy characters from one Unicode object into another. This function "
|
|
"performs character conversion when necessary and falls back to :c:func:"
|
|
"`memcpy` if possible. Returns ``-1`` and sets an exception on error, "
|
|
"otherwise returns the number of copied characters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:592
|
|
msgid ""
|
|
"Fill a string with a character: write *fill_char* into ``unicode[start:start"
|
|
"+length]``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:595
|
|
msgid ""
|
|
"Fail if *fill_char* is bigger than the string maximum character, or if the "
|
|
"string has more than 1 reference."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:598
|
|
msgid ""
|
|
"Return the number of written character, or return ``-1`` and raise an "
|
|
"exception on error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:607
|
|
msgid ""
|
|
"Write a character to a string. The string must have been created through :c:"
|
|
"func:`PyUnicode_New`. Since Unicode strings are supposed to be immutable, "
|
|
"the string must not be shared, or have been hashed yet."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:611
|
|
msgid ""
|
|
"This function checks that *unicode* is a Unicode object, that the index is "
|
|
"not out of bounds, and that the object can be modified safely (i.e. that it "
|
|
"its reference count is one)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:620
|
|
msgid ""
|
|
"Read a character from a string. This function checks that *unicode* is a "
|
|
"Unicode object and the index is not out of bounds, in contrast to the macro "
|
|
"version :c:func:`PyUnicode_READ_CHAR`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:630
|
|
msgid ""
|
|
"Return a substring of *str*, from character index *start* (included) to "
|
|
"character index *end* (excluded). Negative indices are not supported."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:639
|
|
msgid ""
|
|
"Copy the string *u* into a UCS4 buffer, including a null character, if "
|
|
"*copy_null* is set. Returns *NULL* and sets an exception on error (in "
|
|
"particular, a :exc:`SystemError` if *buflen* is smaller than the length of "
|
|
"*u*). *buffer* is returned on success."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:649
|
|
msgid ""
|
|
"Copy the string *u* into a new UCS4 buffer that is allocated using :c:func:"
|
|
"`PyMem_Malloc`. If this fails, *NULL* is returned with a :exc:`MemoryError` "
|
|
"set. The returned buffer always has an extra null code point appended."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:658
|
|
msgid "Deprecated Py_UNICODE APIs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:661
|
|
msgid "Deprecated since version 3.3, will be removed in version 4.0."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:662
|
|
msgid ""
|
|
"These API functions are deprecated with the implementation of :pep:`393`. "
|
|
"Extension modules can continue using them, as they will not be removed in "
|
|
"Python 3.x, but need to be aware that their use can now cause performance "
|
|
"and memory hits."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:669
|
|
msgid ""
|
|
"Create a Unicode object from the Py_UNICODE buffer *u* of the given size. "
|
|
"*u* may be *NULL* which causes the contents to be undefined. It is the "
|
|
"user's responsibility to fill in the needed data. The buffer is copied into "
|
|
"the new object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:674
|
|
msgid ""
|
|
"If the buffer is not *NULL*, the return value might be a shared object. "
|
|
"Therefore, modification of the resulting Unicode object is only allowed when "
|
|
"*u* is *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:678
|
|
msgid ""
|
|
"If the buffer is *NULL*, :c:func:`PyUnicode_READY` must be called once the "
|
|
"string content has been filled before using any of the access macros such "
|
|
"as :c:func:`PyUnicode_KIND`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:682
|
|
msgid ""
|
|
"Please migrate to using :c:func:`PyUnicode_FromKindAndData` or :c:func:"
|
|
"`PyUnicode_New`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:688
|
|
msgid ""
|
|
"Return a read-only pointer to the Unicode object's internal :c:type:"
|
|
"`Py_UNICODE` buffer, or *NULL* on error. This will create the :c:type:"
|
|
"`Py_UNICODE*` representation of the object if it is not yet available. The "
|
|
"buffer is always terminated with an extra null code point. Note that the "
|
|
"resulting :c:type:`Py_UNICODE` string may also contain embedded null code "
|
|
"points, which would cause the string to be truncated when used in most C "
|
|
"functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:696
|
|
msgid ""
|
|
"Please migrate to using :c:func:`PyUnicode_AsUCS4`, :c:func:"
|
|
"`PyUnicode_Substring`, :c:func:`PyUnicode_ReadChar` or similar new APIs."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:703
|
|
msgid ""
|
|
"Create a Unicode object by replacing all decimal digits in :c:type:"
|
|
"`Py_UNICODE` buffer of the given *size* by ASCII digits 0--9 according to "
|
|
"their decimal value. Return *NULL* if an exception occurs."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:710
|
|
msgid ""
|
|
"Like :c:func:`PyUnicode_AsUnicode`, but also saves the :c:func:`Py_UNICODE` "
|
|
"array length (excluding the extra null terminator) in *size*. Note that the "
|
|
"resulting :c:type:`Py_UNICODE*` string may contain embedded null code "
|
|
"points, which would cause the string to be truncated when used in most C "
|
|
"functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:721
|
|
msgid ""
|
|
"Create a copy of a Unicode string ending with a null code point. Return "
|
|
"*NULL* and raise a :exc:`MemoryError` exception on memory allocation "
|
|
"failure, otherwise return a new allocated buffer (use :c:func:`PyMem_Free` "
|
|
"to free the buffer). Note that the resulting :c:type:`Py_UNICODE*` string "
|
|
"may contain embedded null code points, which would cause the string to be "
|
|
"truncated when used in most C functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:730
|
|
msgid ""
|
|
"Please migrate to using :c:func:`PyUnicode_AsUCS4Copy` or similar new APIs."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:735
|
|
msgid ""
|
|
"Return the size of the deprecated :c:type:`Py_UNICODE` representation, in "
|
|
"code units (this includes surrogate pairs as 2 units)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:738
|
|
msgid "Please migrate to using :c:func:`PyUnicode_GetLength`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:743
|
|
msgid ""
|
|
"Copy an instance of a Unicode subtype to a new true Unicode object if "
|
|
"necessary. If *obj* is already a true Unicode object (not a subtype), return "
|
|
"the reference with incremented refcount."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:747
|
|
msgid ""
|
|
"Objects other than Unicode or its subtypes will cause a :exc:`TypeError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:751
|
|
msgid "Locale Encoding"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:753
|
|
msgid ""
|
|
"The current locale encoding can be used to decode text from the operating "
|
|
"system."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:760
|
|
msgid ""
|
|
"Decode a string from the current locale encoding. The supported error "
|
|
"handlers are ``\"strict\"`` and ``\"surrogateescape\"`` (:pep:`383`). The "
|
|
"decoder uses ``\"strict\"`` error handler if *errors* is ``NULL``. *str* "
|
|
"must end with a null character but cannot contain embedded null characters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:766
|
|
msgid ""
|
|
"Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` to decode a string from :c:"
|
|
"data:`Py_FileSystemDefaultEncoding` (the locale encoding read at Python "
|
|
"startup)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:772 ../Doc/c-api/unicode.rst:860
|
|
msgid "The :c:func:`Py_DecodeLocale` function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:779
|
|
msgid ""
|
|
"Similar to :c:func:`PyUnicode_DecodeLocaleAndSize`, but compute the string "
|
|
"length using :c:func:`strlen`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:787
|
|
msgid ""
|
|
"Encode a Unicode object to the current locale encoding. The supported error "
|
|
"handlers are ``\"strict\"`` and ``\"surrogateescape\"`` (:pep:`383`). The "
|
|
"encoder uses ``\"strict\"`` error handler if *errors* is ``NULL``. Return a :"
|
|
"class:`bytes` object. *unicode* cannot contain embedded null characters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:793
|
|
msgid ""
|
|
"Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to :c:data:"
|
|
"`Py_FileSystemDefaultEncoding` (the locale encoding read at Python startup)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:799 ../Doc/c-api/unicode.rst:896
|
|
msgid "The :c:func:`Py_EncodeLocale` function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:805
|
|
msgid "File System Encoding"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:807
|
|
msgid ""
|
|
"To encode and decode file names and other environment strings, :c:data:"
|
|
"`Py_FileSystemDefaultEncoding` should be used as the encoding, and :c:data:"
|
|
"`Py_FileSystemDefaultEncodeErrors` should be used as the error handler (:pep:"
|
|
"`383` and :pep:`529`). To encode file names to :class:`bytes` during "
|
|
"argument parsing, the ``\"O&\"`` converter should be used, passing :c:func:"
|
|
"`PyUnicode_FSConverter` as the conversion function:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:816
|
|
msgid ""
|
|
"ParseTuple converter: encode :class:`str` objects -- obtained directly or "
|
|
"through the :class:`os.PathLike` interface -- to :class:`bytes` using :c:"
|
|
"func:`PyUnicode_EncodeFSDefault`; :class:`bytes` objects are output as-is. "
|
|
"*result* must be a :c:type:`PyBytesObject*` which must be released when it "
|
|
"is no longer used."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:824 ../Doc/c-api/unicode.rst:841
|
|
msgid "Accepts a :term:`path-like object`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:827
|
|
msgid ""
|
|
"To decode file names to :class:`str` during argument parsing, the ``\"O&\"`` "
|
|
"converter should be used, passing :c:func:`PyUnicode_FSDecoder` as the "
|
|
"conversion function:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:833
|
|
msgid ""
|
|
"ParseTuple converter: decode :class:`bytes` objects -- obtained either "
|
|
"directly or indirectly through the :class:`os.PathLike` interface -- to :"
|
|
"class:`str` using :c:func:`PyUnicode_DecodeFSDefaultAndSize`; :class:`str` "
|
|
"objects are output as-is. *result* must be a :c:type:`PyUnicodeObject*` "
|
|
"which must be released when it is no longer used."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:847
|
|
msgid ""
|
|
"Decode a string using :c:data:`Py_FileSystemDefaultEncoding` and the :c:data:"
|
|
"`Py_FileSystemDefaultEncodeErrors` error handler."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:850 ../Doc/c-api/unicode.rst:871
|
|
#: ../Doc/c-api/unicode.rst:887
|
|
msgid ""
|
|
"If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the "
|
|
"locale encoding."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:853
|
|
msgid ""
|
|
":c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the "
|
|
"locale encoding and cannot be modified later. If you need to decode a string "
|
|
"from the current locale encoding, use :c:func:"
|
|
"`PyUnicode_DecodeLocaleAndSize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:862 ../Doc/c-api/unicode.rst:876
|
|
#: ../Doc/c-api/unicode.rst:900
|
|
msgid "Use :c:data:`Py_FileSystemDefaultEncodeErrors` error handler."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:868
|
|
msgid ""
|
|
"Decode a null-terminated string using :c:data:`Py_FileSystemDefaultEncoding` "
|
|
"and the :c:data:`Py_FileSystemDefaultEncodeErrors` error handler."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:874
|
|
msgid ""
|
|
"Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` if you know the string length."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:882
|
|
msgid ""
|
|
"Encode a Unicode object to :c:data:`Py_FileSystemDefaultEncoding` with the :"
|
|
"c:data:`Py_FileSystemDefaultEncodeErrors` error handler, and return :class:"
|
|
"`bytes`. Note that the resulting :class:`bytes` object may contain null "
|
|
"bytes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:890
|
|
msgid ""
|
|
":c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the "
|
|
"locale encoding and cannot be modified later. If you need to encode a string "
|
|
"to the current locale encoding, use :c:func:`PyUnicode_EncodeLocale`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:904
|
|
msgid "wchar_t Support"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:906
|
|
msgid ":c:type:`wchar_t` support for platforms which support it:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:910
|
|
msgid ""
|
|
"Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given "
|
|
"*size*. Passing -1 as the *size* indicates that the function must itself "
|
|
"compute the length, using wcslen. Return *NULL* on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:918
|
|
msgid ""
|
|
"Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At "
|
|
"most *size* :c:type:`wchar_t` characters are copied (excluding a possibly "
|
|
"trailing null termination character). Return the number of :c:type:"
|
|
"`wchar_t` characters copied or -1 in case of an error. Note that the "
|
|
"resulting :c:type:`wchar_t*` string may or may not be null-terminated. It "
|
|
"is the responsibility of the caller to make sure that the :c:type:`wchar_t*` "
|
|
"string is null-terminated in case this is required by the application. Also, "
|
|
"note that the :c:type:`wchar_t*` string might contain null characters, which "
|
|
"would cause the string to be truncated when used with most C functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:931
|
|
msgid ""
|
|
"Convert the Unicode object to a wide character string. The output string "
|
|
"always ends with a null character. If *size* is not *NULL*, write the number "
|
|
"of wide characters (excluding the trailing null termination character) into *"
|
|
"\\*size*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:936
|
|
msgid ""
|
|
"Returns a buffer allocated by :c:func:`PyMem_Alloc` (use :c:func:"
|
|
"`PyMem_Free` to free it) on success. On error, returns *NULL*, *\\*size* is "
|
|
"undefined and raises a :exc:`MemoryError`. Note that the resulting :c:type:"
|
|
"`wchar_t` string might contain null characters, which would cause the string "
|
|
"to be truncated when used with most C functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:946
|
|
msgid "UCS4 Support"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:961
|
|
msgid ""
|
|
"These utility functions work on strings of :c:type:`Py_UCS4` characters and "
|
|
"otherwise behave like the C standard library functions with the same name."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:968
|
|
msgid "Built-in Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:970
|
|
msgid ""
|
|
"Python provides a set of built-in codecs which are written in C for speed. "
|
|
"All of these codecs are directly usable via the following functions."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:973
|
|
msgid ""
|
|
"Many of the following APIs take two arguments encoding and errors, and they "
|
|
"have the same semantics as the ones of the built-in :func:`str` string "
|
|
"object constructor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:977
|
|
msgid ""
|
|
"Setting encoding to *NULL* causes the default encoding to be used which is "
|
|
"ASCII. The file system calls should use :c:func:`PyUnicode_FSConverter` for "
|
|
"encoding file names. This uses the variable :c:data:"
|
|
"`Py_FileSystemDefaultEncoding` internally. This variable should be treated "
|
|
"as read-only: on some systems, it will be a pointer to a static string, on "
|
|
"others, it will change at run-time (such as when the application invokes "
|
|
"setlocale)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:985
|
|
msgid ""
|
|
"Error handling is set by errors which may also be set to *NULL* meaning to "
|
|
"use the default handling defined for the codec. Default error handling for "
|
|
"all built-in codecs is \"strict\" (:exc:`ValueError` is raised)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:989
|
|
msgid ""
|
|
"The codecs all use a similar interface. Only deviation from the following "
|
|
"generic ones are documented for simplicity."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:994
|
|
msgid "Generic Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:996
|
|
msgid "These are the generic codec APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1002
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the encoded string *s*. "
|
|
"*encoding* and *errors* have the same meaning as the parameters of the same "
|
|
"name in the :func:`str` built-in function. The codec to be used is looked "
|
|
"up using the Python codec registry. Return *NULL* if an exception was "
|
|
"raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1012
|
|
msgid ""
|
|
"Encode a Unicode object and return the result as Python bytes object. "
|
|
"*encoding* and *errors* have the same meaning as the parameters of the same "
|
|
"name in the Unicode :meth:`~str.encode` method. The codec to be used is "
|
|
"looked up using the Python codec registry. Return *NULL* if an exception was "
|
|
"raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1022
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a "
|
|
"Python bytes object. *encoding* and *errors* have the same meaning as the "
|
|
"parameters of the same name in the Unicode :meth:`~str.encode` method. The "
|
|
"codec to be used is looked up using the Python codec registry. Return "
|
|
"*NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1030
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using "
|
|
"PyUnicode_AsEncodedString()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1030
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsEncodedString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1034
|
|
msgid "UTF-8 Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1036
|
|
msgid "These are the UTF-8 codec APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1041
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string "
|
|
"*s*. Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1048
|
|
msgid ""
|
|
"If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF8`. If "
|
|
"*consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not "
|
|
"be treated as an error. Those bytes will not be decoded and the number of "
|
|
"bytes that have been decoded will be stored in *consumed*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1056
|
|
msgid ""
|
|
"Encode a Unicode object using UTF-8 and return the result as Python bytes "
|
|
"object. Error handling is \"strict\". Return *NULL* if an exception was "
|
|
"raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1063
|
|
msgid ""
|
|
"Return a pointer to the UTF-8 encoding of the Unicode object, and store the "
|
|
"size of the encoded representation (in bytes) in *size*. The *size* "
|
|
"argument can be *NULL*; in this case no size will be stored. The returned "
|
|
"buffer always has an extra null byte appended (not included in *size*), "
|
|
"regardless of whether there are any other null code points."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1069
|
|
msgid ""
|
|
"In the case of an error, *NULL* is returned with an exception set and no "
|
|
"*size* is stored."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1072
|
|
msgid ""
|
|
"This caches the UTF-8 representation of the string in the Unicode object, "
|
|
"and subsequent calls will return a pointer to the same buffer. The caller "
|
|
"is not responsible for deallocating the buffer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1081
|
|
msgid "As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1088
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 "
|
|
"and return a Python bytes object. Return *NULL* if an exception was raised "
|
|
"by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1094
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using PyUnicode_AsUTF8String() "
|
|
"or PyUnicode_AsUTF8AndSize()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1094
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsUTF8String` or :c:func:`PyUnicode_AsUTF8AndSize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1098
|
|
msgid "UTF-32 Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1100
|
|
msgid "These are the UTF-32 codec APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1106
|
|
msgid ""
|
|
"Decode *size* bytes from a UTF-32 encoded buffer string and return the "
|
|
"corresponding Unicode object. *errors* (if non-*NULL*) defines the error "
|
|
"handling. It defaults to \"strict\"."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1110 ../Doc/c-api/unicode.rst:1183
|
|
msgid ""
|
|
"If *byteorder* is non-*NULL*, the decoder starts decoding using the given "
|
|
"byte order::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1117
|
|
msgid ""
|
|
"If ``*byteorder`` is zero, and the first four bytes of the input data are a "
|
|
"byte order mark (BOM), the decoder switches to this byte order and the BOM "
|
|
"is not copied into the resulting Unicode string. If ``*byteorder`` is "
|
|
"``-1`` or ``1``, any byte order mark is copied to the output."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1122 ../Doc/c-api/unicode.rst:1196
|
|
msgid ""
|
|
"After completion, *\\*byteorder* is set to the current byte order at the end "
|
|
"of input data."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1125 ../Doc/c-api/unicode.rst:1199
|
|
msgid "If *byteorder* is *NULL*, the codec starts in native order mode."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1127 ../Doc/c-api/unicode.rst:1163
|
|
#: ../Doc/c-api/unicode.rst:1201 ../Doc/c-api/unicode.rst:1238
|
|
msgid "Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1133
|
|
msgid ""
|
|
"If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF32`. If "
|
|
"*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF32Stateful` will not "
|
|
"treat trailing incomplete UTF-32 byte sequences (such as a number of bytes "
|
|
"not divisible by four) as an error. Those bytes will not be decoded and the "
|
|
"number of bytes that have been decoded will be stored in *consumed*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1142
|
|
msgid ""
|
|
"Return a Python byte string using the UTF-32 encoding in native byte order. "
|
|
"The string always starts with a BOM mark. Error handling is \"strict\". "
|
|
"Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1150
|
|
msgid ""
|
|
"Return a Python bytes object holding the UTF-32 encoded value of the Unicode "
|
|
"data in *s*. Output is written according to the following byte order::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1157 ../Doc/c-api/unicode.rst:1231
|
|
msgid ""
|
|
"If byteorder is ``0``, the output string will always start with the Unicode "
|
|
"BOM mark (U+FEFF). In the other two modes, no BOM mark is prepended."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1160
|
|
msgid ""
|
|
"If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output as a "
|
|
"single code point."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1167
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using PyUnicode_AsUTF32String()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1167
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsUTF32String`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1171
|
|
msgid "UTF-16 Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1173
|
|
msgid "These are the UTF-16 codec APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1179
|
|
msgid ""
|
|
"Decode *size* bytes from a UTF-16 encoded buffer string and return the "
|
|
"corresponding Unicode object. *errors* (if non-*NULL*) defines the error "
|
|
"handling. It defaults to \"strict\"."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1190
|
|
msgid ""
|
|
"If ``*byteorder`` is zero, and the first two bytes of the input data are a "
|
|
"byte order mark (BOM), the decoder switches to this byte order and the BOM "
|
|
"is not copied into the resulting Unicode string. If ``*byteorder`` is "
|
|
"``-1`` or ``1``, any byte order mark is copied to the output (where it will "
|
|
"result in either a ``\\ufeff`` or a ``\\ufffe`` character)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1207
|
|
msgid ""
|
|
"If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF16`. If "
|
|
"*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF16Stateful` will not "
|
|
"treat trailing incomplete UTF-16 byte sequences (such as an odd number of "
|
|
"bytes or a split surrogate pair) as an error. Those bytes will not be "
|
|
"decoded and the number of bytes that have been decoded will be stored in "
|
|
"*consumed*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1216
|
|
msgid ""
|
|
"Return a Python byte string using the UTF-16 encoding in native byte order. "
|
|
"The string always starts with a BOM mark. Error handling is \"strict\". "
|
|
"Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1224
|
|
msgid ""
|
|
"Return a Python bytes object holding the UTF-16 encoded value of the Unicode "
|
|
"data in *s*. Output is written according to the following byte order::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1234
|
|
msgid ""
|
|
"If *Py_UNICODE_WIDE* is defined, a single :c:type:`Py_UNICODE` value may get "
|
|
"represented as a surrogate pair. If it is not defined, each :c:type:"
|
|
"`Py_UNICODE` values is interpreted as a UCS-2 character."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1242
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using PyUnicode_AsUTF16String()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1242
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsUTF16String`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1246
|
|
msgid "UTF-7 Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1248
|
|
msgid "These are the UTF-7 codec APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1253
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string "
|
|
"*s*. Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1260
|
|
msgid ""
|
|
"If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF7`. If "
|
|
"*consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will "
|
|
"not be treated as an error. Those bytes will not be decoded and the number "
|
|
"of bytes that have been decoded will be stored in *consumed*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1269
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and "
|
|
"return a Python bytes object. Return *NULL* if an exception was raised by "
|
|
"the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1273
|
|
msgid ""
|
|
"If *base64SetO* is nonzero, \"Set O\" (punctuation that has no otherwise "
|
|
"special meaning) will be encoded in base-64. If *base64WhiteSpace* is "
|
|
"nonzero, whitespace will be encoded in base-64. Both are set to zero for "
|
|
"the Python \"utf-7\" codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1280 ../Doc/c-api/unicode.rst:1471
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1280 ../Doc/c-api/unicode.rst:1471
|
|
msgid "Part of the old-style :c:type:`Py_UNICODE` API."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1285
|
|
msgid "Unicode-Escape Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1287
|
|
msgid "These are the \"Unicode Escape\" codec APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1293
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the Unicode-Escape "
|
|
"encoded string *s*. Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1299
|
|
msgid ""
|
|
"Encode a Unicode object using Unicode-Escape and return the result as Python "
|
|
"string object. Error handling is \"strict\". Return *NULL* if an exception "
|
|
"was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1306
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-"
|
|
"Escape and return a Python string object. Return *NULL* if an exception was "
|
|
"raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1312
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using "
|
|
"PyUnicode_AsUnicodeEscapeString()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1312
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsUnicodeEscapeString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1316
|
|
msgid "Raw-Unicode-Escape Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1318
|
|
msgid "These are the \"Raw Unicode Escape\" codec APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1324
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape "
|
|
"encoded string *s*. Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1330
|
|
msgid ""
|
|
"Encode a Unicode object using Raw-Unicode-Escape and return the result as "
|
|
"Python string object. Error handling is \"strict\". Return *NULL* if an "
|
|
"exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1338
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-"
|
|
"Escape and return a Python string object. Return *NULL* if an exception was "
|
|
"raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1344
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using "
|
|
"PyUnicode_AsRawUnicodeEscapeString()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1344
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsRawUnicodeEscapeString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1348
|
|
msgid "Latin-1 Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1350
|
|
msgid ""
|
|
"These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 "
|
|
"Unicode ordinals and only these are accepted by the codecs during encoding."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1356
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the Latin-1 encoded "
|
|
"string *s*. Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1362
|
|
msgid ""
|
|
"Encode a Unicode object using Latin-1 and return the result as Python bytes "
|
|
"object. Error handling is \"strict\". Return *NULL* if an exception was "
|
|
"raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1369
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and "
|
|
"return a Python bytes object. Return *NULL* if an exception was raised by "
|
|
"the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1375
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using PyUnicode_AsLatin1String()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1375
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsLatin1String`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1379
|
|
msgid "ASCII Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1381
|
|
msgid ""
|
|
"These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All "
|
|
"other codes generate errors."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1387
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the ASCII encoded string "
|
|
"*s*. Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1393
|
|
msgid ""
|
|
"Encode a Unicode object using ASCII and return the result as Python bytes "
|
|
"object. Error handling is \"strict\". Return *NULL* if an exception was "
|
|
"raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1400
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and "
|
|
"return a Python bytes object. Return *NULL* if an exception was raised by "
|
|
"the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1406
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using PyUnicode_AsASCIIString()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1406
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsASCIIString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1410
|
|
msgid "Character Map Codecs"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1412
|
|
msgid ""
|
|
"This codec is special in that it can be used to implement many different "
|
|
"codecs (and this is in fact what was done to obtain most of the standard "
|
|
"codecs included in the :mod:`encodings` package). The codec uses mapping to "
|
|
"encode and decode characters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1417
|
|
msgid ""
|
|
"Decoding mappings must map single string characters to single Unicode "
|
|
"characters, integers (which are then interpreted as Unicode ordinals) or "
|
|
"None (meaning \"undefined mapping\" and causing an error)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1421
|
|
msgid ""
|
|
"Encoding mappings must map single Unicode characters to single string "
|
|
"characters, integers (which are then interpreted as Latin-1 ordinals) or "
|
|
"None (meaning \"undefined mapping\" and causing an error)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1425
|
|
msgid ""
|
|
"The mapping objects provided must only support the __getitem__ mapping "
|
|
"interface."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1428
|
|
msgid ""
|
|
"If a character lookup fails with a LookupError, the character is copied as-"
|
|
"is meaning that its ordinal value will be interpreted as Unicode or Latin-1 "
|
|
"ordinal resp. Because of this, mappings only need to contain those mappings "
|
|
"which map characters to different code points."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1433
|
|
msgid "These are the mapping codec APIs:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1438
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the encoded string *s* "
|
|
"using the given *mapping* object. Return *NULL* if an exception was raised "
|
|
"by the codec. If *mapping* is *NULL* latin-1 decoding will be done. Else it "
|
|
"can be a dictionary mapping byte or a unicode string, which is treated as a "
|
|
"lookup table. Byte values greater that the length of the string and U+FFFE "
|
|
"\"characters\" are treated as \"undefined mapping\"."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1448
|
|
msgid ""
|
|
"Encode a Unicode object using the given *mapping* object and return the "
|
|
"result as Python string object. Error handling is \"strict\". Return "
|
|
"*NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1452
|
|
msgid "The following codec API is special in that maps Unicode to Unicode."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1458
|
|
msgid ""
|
|
"Translate a :c:type:`Py_UNICODE` buffer of the given *size* by applying a "
|
|
"character mapping *table* to it and return the resulting Unicode object. "
|
|
"Return *NULL* when an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1462
|
|
msgid ""
|
|
"The *mapping* table must map Unicode ordinal integers to Unicode ordinal "
|
|
"integers or None (causing deletion of the character)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1465 ../Doc/c-api/unicode.rst:1582
|
|
msgid ""
|
|
"Mapping tables need only provide the :meth:`__getitem__` interface; "
|
|
"dictionaries and sequences work well. Unmapped character ordinals (ones "
|
|
"which cause a :exc:`LookupError`) are left untouched and are copied as-is."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1478
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given "
|
|
"*mapping* object and return a Python string object. Return *NULL* if an "
|
|
"exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1484
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using "
|
|
"PyUnicode_AsCharmapString()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1484
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsCharmapString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1488
|
|
msgid "MBCS codecs for Windows"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1490
|
|
msgid ""
|
|
"These are the MBCS codec APIs. They are currently only available on Windows "
|
|
"and use the Win32 MBCS converters to implement the conversions. Note that "
|
|
"MBCS (or DBCS) is a class of encodings, not just one. The target encoding "
|
|
"is defined by the user settings on the machine running the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1497
|
|
msgid ""
|
|
"Create a Unicode object by decoding *size* bytes of the MBCS encoded string "
|
|
"*s*. Return *NULL* if an exception was raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1504
|
|
msgid ""
|
|
"If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeMBCS`. If "
|
|
"*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeMBCSStateful` will not "
|
|
"decode trailing lead byte and the number of bytes that have been decoded "
|
|
"will be stored in *consumed*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1512
|
|
msgid ""
|
|
"Encode a Unicode object using MBCS and return the result as Python bytes "
|
|
"object. Error handling is \"strict\". Return *NULL* if an exception was "
|
|
"raised by the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1519
|
|
msgid ""
|
|
"Encode the Unicode object using the specified code page and return a Python "
|
|
"bytes object. Return *NULL* if an exception was raised by the codec. Use :c:"
|
|
"data:`CP_ACP` code page to get the MBCS encoder."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1528
|
|
msgid ""
|
|
"Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and "
|
|
"return a Python bytes object. Return *NULL* if an exception was raised by "
|
|
"the codec."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1534
|
|
msgid ""
|
|
"Deprecated since version 3.3, will be removed in version 4.0: Part of the "
|
|
"old-style Py_UNICODE API; please migrate to using PyUnicode_AsMBCSString() "
|
|
"or PyUnicode_EncodeCodePage()."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1534
|
|
msgid ""
|
|
"Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using :c:"
|
|
"func:`PyUnicode_AsMBCSString` or :c:func:`PyUnicode_EncodeCodePage`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1538
|
|
msgid "Methods & Slots"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1544
|
|
msgid "Methods and Slot Functions"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1546
|
|
msgid ""
|
|
"The following APIs are capable of handling Unicode objects and strings on "
|
|
"input (we refer to them as strings in the descriptions) and return Unicode "
|
|
"objects or integers as appropriate."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1550
|
|
msgid "They all return *NULL* or ``-1`` if an exception occurs."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1555
|
|
msgid "Concat two strings giving a new Unicode string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1560
|
|
msgid ""
|
|
"Split a string giving a list of Unicode strings. If *sep* is *NULL*, "
|
|
"splitting will be done at all whitespace substrings. Otherwise, splits "
|
|
"occur at the given separator. At most *maxsplit* splits will be done. If "
|
|
"negative, no limit is set. Separators are not included in the resulting "
|
|
"list."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1568
|
|
msgid ""
|
|
"Split a Unicode string at line breaks, returning a list of Unicode strings. "
|
|
"CRLF is considered to be one line break. If *keepend* is 0, the Line break "
|
|
"characters are not included in the resulting strings."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1576
|
|
msgid ""
|
|
"Translate a string by applying a character mapping table to it and return "
|
|
"the resulting Unicode object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1579
|
|
msgid ""
|
|
"The mapping table must map Unicode ordinal integers to Unicode ordinal "
|
|
"integers or None (causing deletion of the character)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1586
|
|
msgid ""
|
|
"*errors* has the usual meaning for codecs. It may be *NULL* which indicates "
|
|
"to use the default error handling."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1592
|
|
msgid ""
|
|
"Join a sequence of strings using the given *separator* and return the "
|
|
"resulting Unicode string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1599
|
|
msgid ""
|
|
"Return 1 if *substr* matches ``str[start:end]`` at the given tail end "
|
|
"(*direction* == -1 means to do a prefix match, *direction* == 1 a suffix "
|
|
"match), 0 otherwise. Return ``-1`` if an error occurred."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1607
|
|
msgid ""
|
|
"Return the first position of *substr* in ``str[start:end]`` using the given "
|
|
"*direction* (*direction* == 1 means to do a forward search, *direction* == "
|
|
"-1 a backward search). The return value is the index of the first match; a "
|
|
"value of ``-1`` indicates that no match was found, and ``-2`` indicates that "
|
|
"an error occurred and an exception has been set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1617
|
|
msgid ""
|
|
"Return the first position of the character *ch* in ``str[start:end]`` using "
|
|
"the given *direction* (*direction* == 1 means to do a forward search, "
|
|
"*direction* == -1 a backward search). The return value is the index of the "
|
|
"first match; a value of ``-1`` indicates that no match was found, and ``-2`` "
|
|
"indicates that an error occurred and an exception has been set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1629
|
|
msgid ""
|
|
"Return the number of non-overlapping occurrences of *substr* in ``str[start:"
|
|
"end]``. Return ``-1`` if an error occurred."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1636
|
|
msgid ""
|
|
"Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* "
|
|
"and return the resulting Unicode object. *maxcount* == -1 means replace all "
|
|
"occurrences."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1643
|
|
msgid ""
|
|
"Compare two strings and return -1, 0, 1 for less than, equal, and greater "
|
|
"than, respectively."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1649
|
|
msgid ""
|
|
"Compare a unicode object, *uni*, with *string* and return -1, 0, 1 for less "
|
|
"than, equal, and greater than, respectively. It is best to pass only ASCII-"
|
|
"encoded strings, but the function interprets the input string as ISO-8859-1 "
|
|
"if it contains non-ASCII characters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1657
|
|
msgid "Rich compare two unicode strings and return one of the following:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1659
|
|
msgid "``NULL`` in case an exception was raised"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1660
|
|
msgid ":const:`Py_True` or :const:`Py_False` for successful comparisons"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1661
|
|
msgid ":const:`Py_NotImplemented` in case the type combination is unknown"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1663
|
|
msgid ""
|
|
"Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a :exc:"
|
|
"`UnicodeWarning` in case the conversion of the arguments to Unicode fails "
|
|
"with a :exc:`UnicodeDecodeError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1667
|
|
msgid ""
|
|
"Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:"
|
|
"`Py_EQ`, :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1673
|
|
msgid ""
|
|
"Return a new string object from *format* and *args*; this is analogous to "
|
|
"``format % args``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1679
|
|
msgid ""
|
|
"Check whether *element* is contained in *container* and return true or false "
|
|
"accordingly."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1682
|
|
msgid ""
|
|
"*element* has to coerce to a one element Unicode string. ``-1`` is returned "
|
|
"if there was an error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1688
|
|
msgid ""
|
|
"Intern the argument *\\*string* in place. The argument must be the address "
|
|
"of a pointer variable pointing to a Python unicode string object. If there "
|
|
"is an existing interned string that is the same as *\\*string*, it sets *"
|
|
"\\*string* to it (decrementing the reference count of the old string object "
|
|
"and incrementing the reference count of the interned string object), "
|
|
"otherwise it leaves *\\*string* alone and interns it (incrementing its "
|
|
"reference count). (Clarification: even though there is a lot of talk about "
|
|
"reference counts, think of this function as reference-count-neutral; you own "
|
|
"the object after the call if and only if you owned it before the call.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/unicode.rst:1701
|
|
msgid ""
|
|
"A combination of :c:func:`PyUnicode_FromString` and :c:func:"
|
|
"`PyUnicode_InternInPlace`, returning either a new unicode string object that "
|
|
"has been interned, or a new (\"owned\") reference to an earlier interned "
|
|
"string object with the same value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/utilities.rst:7
|
|
msgid "Utilities"
|
|
msgstr "Utilitaires"
|
|
|
|
#: ../Doc/c-api/utilities.rst:9
|
|
msgid ""
|
|
"The functions in this chapter perform various utility tasks, ranging from "
|
|
"helping C code be more portable across platforms, using Python modules from "
|
|
"C, and parsing function arguments and constructing Python values from C "
|
|
"values."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:8
|
|
msgid "The Very High Level Layer"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:10
|
|
msgid ""
|
|
"The functions in this chapter will let you execute Python source code given "
|
|
"in a file or a buffer, but they will not let you interact in a more detailed "
|
|
"way with the interpreter."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:14
|
|
msgid ""
|
|
"Several of these functions accept a start symbol from the grammar as a "
|
|
"parameter. The available start symbols are :const:`Py_eval_input`, :const:"
|
|
"`Py_file_input`, and :const:`Py_single_input`. These are described "
|
|
"following the functions which accept them as parameters."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:19
|
|
msgid ""
|
|
"Note also that several of these functions take :c:type:`FILE\\*` "
|
|
"parameters. One particular issue which needs to be handled carefully is "
|
|
"that the :c:type:`FILE` structure for different C libraries can be different "
|
|
"and incompatible. Under Windows (at least), it is possible for dynamically "
|
|
"linked extensions to actually use different libraries, so care should be "
|
|
"taken that :c:type:`FILE\\*` parameters are only passed to these functions "
|
|
"if it is certain that they were created by the same library that the Python "
|
|
"runtime is using."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:30
|
|
msgid ""
|
|
"The main program for the standard interpreter. This is made available for "
|
|
"programs which embed Python. The *argc* and *argv* parameters should be "
|
|
"prepared exactly as those which are passed to a C program's :c:func:`main` "
|
|
"function (converted to wchar_t according to the user's locale). It is "
|
|
"important to note that the argument list may be modified (but the contents "
|
|
"of the strings pointed to by the argument list are not). The return value "
|
|
"will be ``0`` if the interpreter exits normally (i.e., without an "
|
|
"exception), ``1`` if the interpreter exits due to an exception, or ``2`` if "
|
|
"the parameter list does not represent a valid Python command line."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:40
|
|
msgid ""
|
|
"Note that if an otherwise unhandled :exc:`SystemExit` is raised, this "
|
|
"function will not return ``1``, but exit the process, as long as "
|
|
"``Py_InspectFlag`` is not set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:47
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, "
|
|
"leaving *closeit* set to ``0`` and *flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:53
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, "
|
|
"leaving the *closeit* argument set to ``0``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:59
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, "
|
|
"leaving the *flags* argument set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:65
|
|
msgid ""
|
|
"If *fp* refers to a file associated with an interactive device (console or "
|
|
"terminal input or Unix pseudo-terminal), return the value of :c:func:"
|
|
"`PyRun_InteractiveLoop`, otherwise return the result of :c:func:"
|
|
"`PyRun_SimpleFile`. *filename* is decoded from the filesystem encoding (:"
|
|
"func:`sys.getfilesystemencoding`). If *filename* is *NULL*, this function "
|
|
"uses ``\"???\"`` as the filename."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:75
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below, "
|
|
"leaving the *PyCompilerFlags\\** argument set to NULL."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:81
|
|
msgid ""
|
|
"Executes the Python source code from *command* in the :mod:`__main__` module "
|
|
"according to the *flags* argument. If :mod:`__main__` does not already "
|
|
"exist, it is created. Returns ``0`` on success or ``-1`` if an exception "
|
|
"was raised. If there was an error, there is no way to get the exception "
|
|
"information. For the meaning of *flags*, see below."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:87
|
|
msgid ""
|
|
"Note that if an otherwise unhandled :exc:`SystemExit` is raised, this "
|
|
"function will not return ``-1``, but exit the process, as long as "
|
|
"``Py_InspectFlag`` is not set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:94
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, "
|
|
"leaving *closeit* set to ``0`` and *flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:100
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, "
|
|
"leaving *flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:106
|
|
msgid ""
|
|
"Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is "
|
|
"read from *fp* instead of an in-memory string. *filename* should be the name "
|
|
"of the file, it is decoded from the filesystem encoding (:func:`sys."
|
|
"getfilesystemencoding`). If *closeit* is true, the file is closed before "
|
|
"PyRun_SimpleFileExFlags returns."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:115
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below, "
|
|
"leaving *flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:121
|
|
msgid ""
|
|
"Read and execute a single statement from a file associated with an "
|
|
"interactive device according to the *flags* argument. The user will be "
|
|
"prompted using ``sys.ps1`` and ``sys.ps2``. *filename* is decoded from the "
|
|
"filesystem encoding (:func:`sys.getfilesystemencoding`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:126
|
|
msgid ""
|
|
"Returns ``0`` when the input was executed successfully, ``-1`` if there was "
|
|
"an exception, or an error code from the :file:`errcode.h` include file "
|
|
"distributed as part of Python if there was a parse error. (Note that :file:"
|
|
"`errcode.h` is not included by :file:`Python.h`, so must be included "
|
|
"specifically if needed.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:135
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` "
|
|
"below, leaving *flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:141
|
|
msgid ""
|
|
"Read and execute statements from a file associated with an interactive "
|
|
"device until EOF is reached. The user will be prompted using ``sys.ps1`` "
|
|
"and ``sys.ps2``. *filename* is decoded from the filesystem encoding (:func:"
|
|
"`sys.getfilesystemencoding`). Returns ``0`` at EOF."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:149
|
|
msgid ""
|
|
"Can be set to point to a function with the prototype ``int func(void)``. "
|
|
"The function will be called when Python's interpreter prompt is about to "
|
|
"become idle and wait for user input from the terminal. The return value is "
|
|
"ignored. Overriding this hook can be used to integrate the interpreter's "
|
|
"prompt with other event loops, as done in the :file:`Modules/_tkinter.c` in "
|
|
"the Python source code."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:160
|
|
msgid ""
|
|
"Can be set to point to a function with the prototype ``char *func(FILE "
|
|
"*stdin, FILE *stdout, char *prompt)``, overriding the default function used "
|
|
"to read a single line of input at the interpreter's prompt. The function is "
|
|
"expected to output the string *prompt* if it's not *NULL*, and then read a "
|
|
"line of input from the provided standard input file, returning the resulting "
|
|
"string. For example, The :mod:`readline` module sets this hook to provide "
|
|
"line-editing and tab-completion features."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:169
|
|
msgid ""
|
|
"The result must be a string allocated by :c:func:`PyMem_RawMalloc` or :c:"
|
|
"func:`PyMem_RawRealloc`, or *NULL* if an error occurred."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:172
|
|
msgid ""
|
|
"The result must be allocated by :c:func:`PyMem_RawMalloc` or :c:func:"
|
|
"`PyMem_RawRealloc`, instead of being allocated by :c:func:`PyMem_Malloc` or :"
|
|
"c:func:`PyMem_Realloc`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:180
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:"
|
|
"`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set to "
|
|
"*NULL* and *flags* set to ``0``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:187
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:"
|
|
"`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set to "
|
|
"*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:194
|
|
msgid ""
|
|
"Parse Python source code from *str* using the start token *start* according "
|
|
"to the *flags* argument. The result can be used to create a code object "
|
|
"which can be evaluated efficiently. This is useful if a code fragment must "
|
|
"be evaluated many times. *filename* is decoded from the filesystem encoding "
|
|
"(:func:`sys.getfilesystemencoding`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:203
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` "
|
|
"below, leaving *flags* set to ``0``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:209
|
|
msgid ""
|
|
"Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python "
|
|
"source code is read from *fp* instead of an in-memory string."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:215
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving "
|
|
"*flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:221
|
|
msgid ""
|
|
"Execute Python source code from *str* in the context specified by the "
|
|
"objects *globals* and *locals* with the compiler flags specified by "
|
|
"*flags*. *globals* must be a dictionary; *locals* can be any object that "
|
|
"implements the mapping protocol. The parameter *start* specifies the start "
|
|
"token that should be used to parse the source code."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:227
|
|
msgid ""
|
|
"Returns the result of executing the code as a Python object, or *NULL* if an "
|
|
"exception was raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:233
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving "
|
|
"*closeit* set to ``0`` and *flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:239
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving "
|
|
"*flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:245
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving "
|
|
"*closeit* set to ``0``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:251
|
|
msgid ""
|
|
"Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read "
|
|
"from *fp* instead of an in-memory string. *filename* should be the name of "
|
|
"the file, it is decoded from the filesystem encoding (:func:`sys."
|
|
"getfilesystemencoding`). If *closeit* is true, the file is closed before :c:"
|
|
"func:`PyRun_FileExFlags` returns."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:260
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`Py_CompileStringFlags` below, "
|
|
"leaving *flags* set to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:266
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, "
|
|
"with *optimize* set to ``-1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:272
|
|
msgid ""
|
|
"Parse and compile the Python source code in *str*, returning the resulting "
|
|
"code object. The start token is given by *start*; this can be used to "
|
|
"constrain the code which can be compiled and should be :const:"
|
|
"`Py_eval_input`, :const:`Py_file_input`, or :const:`Py_single_input`. The "
|
|
"filename specified by *filename* is used to construct the code object and "
|
|
"may appear in tracebacks or :exc:`SyntaxError` exception messages. This "
|
|
"returns *NULL* if the code cannot be parsed or compiled."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:280
|
|
msgid ""
|
|
"The integer *optimize* specifies the optimization level of the compiler; a "
|
|
"value of ``-1`` selects the optimization level of the interpreter as given "
|
|
"by :option:`-O` options. Explicit levels are ``0`` (no optimization; "
|
|
"``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) "
|
|
"or ``2`` (docstrings are removed too)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:291
|
|
msgid ""
|
|
"Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string "
|
|
"decoded from the filesystem encoding (:func:`os.fsdecode`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:298
|
|
msgid ""
|
|
"This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just the "
|
|
"code object, and global and local variables. The other arguments are set to "
|
|
"*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:305
|
|
msgid ""
|
|
"Evaluate a precompiled code object, given a particular environment for its "
|
|
"evaluation. This environment consists of a dictionary of global variables, "
|
|
"a mapping object of local variables, arrays of arguments, keywords and "
|
|
"defaults, and a closure tuple of cells."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:313
|
|
msgid ""
|
|
"The C structure of the objects used to describe frame objects. The fields of "
|
|
"this type are subject to change at any time."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:319
|
|
msgid ""
|
|
"Evaluate an execution frame. This is a simplified interface to :c:func:"
|
|
"`PyEval_EvalFrameEx`, for backward compatibility."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:325
|
|
msgid ""
|
|
"This is the main, unvarnished function of Python interpretation. It is "
|
|
"literally 2000 lines long. The code object associated with the execution "
|
|
"frame *f* is executed, interpreting bytecode and executing calls as needed. "
|
|
"The additional *throwflag* parameter can mostly be ignored - if true, then "
|
|
"it causes an exception to immediately be thrown; this is used for the :meth:"
|
|
"`~generator.throw` methods of generator objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:339
|
|
msgid ""
|
|
"This function changes the flags of the current evaluation frame, and returns "
|
|
"true on success, false on failure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:347
|
|
msgid ""
|
|
"The start symbol from the Python grammar for isolated expressions; for use "
|
|
"with :c:func:`Py_CompileString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:355
|
|
msgid ""
|
|
"The start symbol from the Python grammar for sequences of statements as read "
|
|
"from a file or other source; for use with :c:func:`Py_CompileString`. This "
|
|
"is the symbol to use when compiling arbitrarily long Python source code."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:364
|
|
msgid ""
|
|
"The start symbol from the Python grammar for a single statement; for use "
|
|
"with :c:func:`Py_CompileString`. This is the symbol used for the interactive "
|
|
"interpreter loop."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:371
|
|
msgid ""
|
|
"This is the structure used to hold compiler flags. In cases where code is "
|
|
"only being compiled, it is passed as ``int flags``, and in cases where code "
|
|
"is being executed, it is passed as ``PyCompilerFlags *flags``. In this "
|
|
"case, ``from __future__ import`` can modify *flags*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:376
|
|
msgid ""
|
|
"Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated "
|
|
"as equal to ``0``, and any modification due to ``from __future__ import`` is "
|
|
"discarded. ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/veryhigh.rst:387
|
|
msgid ""
|
|
"This bit can be set in *flags* to cause division operator ``/`` to be "
|
|
"interpreted as \"true division\" according to :pep:`238`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:6
|
|
msgid "Weak Reference Objects"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:8
|
|
msgid ""
|
|
"Python supports *weak references* as first-class objects. There are two "
|
|
"specific object types which directly implement weak references. The first "
|
|
"is a simple reference object, and the second acts as a proxy for the "
|
|
"original object as much as it can."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:16
|
|
msgid "Return true if *ob* is either a reference or proxy object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:21
|
|
msgid "Return true if *ob* is a reference object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:26
|
|
msgid "Return true if *ob* is a proxy object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:31
|
|
msgid ""
|
|
"Return a weak reference object for the object *ob*. This will always return "
|
|
"a new reference, but is not guaranteed to create a new object; an existing "
|
|
"reference object may be returned. The second parameter, *callback*, can be "
|
|
"a callable object that receives notification when *ob* is garbage collected; "
|
|
"it should accept a single parameter, which will be the weak reference object "
|
|
"itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a weakly-"
|
|
"referencable object, or if *callback* is not callable, ``None``, or *NULL*, "
|
|
"this will return *NULL* and raise :exc:`TypeError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:43
|
|
msgid ""
|
|
"Return a weak reference proxy object for the object *ob*. This will always "
|
|
"return a new reference, but is not guaranteed to create a new object; an "
|
|
"existing proxy object may be returned. The second parameter, *callback*, "
|
|
"can be a callable object that receives notification when *ob* is garbage "
|
|
"collected; it should accept a single parameter, which will be the weak "
|
|
"reference object itself. *callback* may also be ``None`` or *NULL*. If *ob* "
|
|
"is not a weakly-referencable object, or if *callback* is not callable, "
|
|
"``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:55
|
|
msgid ""
|
|
"Return the referenced object from a weak reference, *ref*. If the referent "
|
|
"is no longer live, returns :const:`Py_None`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:60
|
|
msgid ""
|
|
"This function returns a **borrowed reference** to the referenced object. "
|
|
"This means that you should always call :c:func:`Py_INCREF` on the object "
|
|
"except if you know that it cannot be destroyed while you are still using it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/weakref.rst:68
|
|
msgid ""
|
|
"Similar to :c:func:`PyWeakref_GetObject`, but implemented as a macro that "
|
|
"does no error checking."
|
|
msgstr ""
|