# SOME DESCRIPTIVE TITLE. # Copyright (C) 2001-2016, Python Software Foundation # This file is distributed under the same license as the Python package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Python 3.6\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2016-10-17 21:44+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../Doc/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 `. " "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 `. 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 `." 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 `. 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 `." 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 ` 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 `. 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 ` 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 " "`)." 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 `, " "*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 `." 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 `_." 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`." 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: ````, " "````, ````, ````, ```` and ```` (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 ``; 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 ` 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 ` 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 `." msgstr "" #: ../Doc/c-api/memory.rst:172 msgid "" "The :term:`GIL ` 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 ` 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 ` 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 " "` 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 `. 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 `, 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 ` 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 " "``''`` 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 `: 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 `: 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 \"%.s\" where is a decimal number " "calculated so that 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 `. 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 `, the rules how an exporter must react to " "specific requests are in section :ref:`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 " "` 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 ""