# Copyright (C) 2001-2018, Python Software Foundation # For licence information, see README file. # msgid "" msgstr "" "Project-Id-Version: Python 3\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2020-08-24 09:01+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: FRENCH \n" "Language: fr\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: extending/newtypes.rst:7 msgid "Defining Extension Types: Assorted Topics" msgstr "" #: extending/newtypes.rst:11 msgid "" "This section aims to give a quick fly-by on the various type methods you can " "implement and what they do." msgstr "" #: extending/newtypes.rst:14 msgid "" "Here is the definition of :c:type:`PyTypeObject`, with some fields only used " "in debug builds omitted:" msgstr "" #: extending/newtypes.rst:20 msgid "" "Now that's a *lot* of methods. Don't worry too much though -- if you have a " "type you want to define, the chances are very good that you will only " "implement a handful of these." msgstr "" #: extending/newtypes.rst:24 msgid "" "As you probably expect by now, we're going to go over this and give more " "information about the various handlers. We won't go in the order they are " "defined in the structure, because there is a lot of historical baggage that " "impacts the ordering of the fields. It's often easiest to find an example " "that includes the fields you need and then change the values to suit your " "new type. ::" msgstr "" #: extending/newtypes.rst:33 msgid "" "The name of the type -- as mentioned in the previous chapter, this will " "appear in various places, almost entirely for diagnostic purposes. Try to " "choose something that will be helpful in such a situation! ::" msgstr "" #: extending/newtypes.rst:39 msgid "" "These fields tell the runtime how much memory to allocate when new objects " "of this type are created. Python has some built-in support for variable " "length structures (think: strings, tuples) which is where the :c:member:" "`~PyTypeObject.tp_itemsize` field comes in. This will be dealt with " "later. ::" msgstr "" #: extending/newtypes.rst:46 msgid "" "Here you can put a string (or its address) that you want returned when the " "Python script references ``obj.__doc__`` to retrieve the doc string." msgstr "" #: extending/newtypes.rst:49 msgid "" "Now we come to the basic type methods -- the ones most extension types will " "implement." msgstr "" #: extending/newtypes.rst:54 msgid "Finalization and De-allocation" msgstr "" #: extending/newtypes.rst:66 msgid "" "This function is called when the reference count of the instance of your " "type is reduced to zero and the Python interpreter wants to reclaim it. If " "your type has memory to free or other clean-up to perform, you can put it " "here. The object itself needs to be freed here as well. Here is an example " "of this function::" msgstr "" #: extending/newtypes.rst:83 msgid "" "One important requirement of the deallocator function is that it leaves any " "pending exceptions alone. This is important since deallocators are " "frequently called as the interpreter unwinds the Python stack; when the " "stack is unwound due to an exception (rather than normal returns), nothing " "is done to protect the deallocators from seeing that an exception has " "already been set. Any actions which a deallocator performs which may cause " "additional Python code to be executed may detect that an exception has been " "set. This can lead to misleading errors from the interpreter. The proper " "way to protect against this is to save a pending exception before performing " "the unsafe action, and restoring it when done. This can be done using the :" "c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::" msgstr "" #: extending/newtypes.rst:122 msgid "" "There are limitations to what you can safely do in a deallocator function. " "First, if your type supports garbage collection (using :c:member:" "`~PyTypeObject.tp_traverse` and/or :c:member:`~PyTypeObject.tp_clear`), some " "of the object's members can have been cleared or finalized by the time :c:" "member:`~PyTypeObject.tp_dealloc` is called. Second, in :c:member:" "`~PyTypeObject.tp_dealloc`, your object is in an unstable state: its " "reference count is equal to zero. Any call to a non-trivial object or API " "(as in the example above) might end up calling :c:member:`~PyTypeObject." "tp_dealloc` again, causing a double free and a crash." msgstr "" #: extending/newtypes.rst:131 msgid "" "Starting with Python 3.4, it is recommended not to put any complex " "finalization code in :c:member:`~PyTypeObject.tp_dealloc`, and instead use " "the new :c:member:`~PyTypeObject.tp_finalize` type method." msgstr "" #: extending/newtypes.rst:136 msgid ":pep:`442` explains the new finalization scheme." msgstr "" #: extending/newtypes.rst:143 msgid "Object Presentation" msgstr "" #: extending/newtypes.rst:145 msgid "" "In Python, there are two ways to generate a textual representation of an " "object: the :func:`repr` function, and the :func:`str` function. (The :func:" "`print` function just calls :func:`str`.) These handlers are both optional." msgstr "" #: extending/newtypes.rst:154 msgid "" "The :c:member:`~PyTypeObject.tp_repr` handler should return a string object " "containing a representation of the instance for which it is called. Here is " "a simple example::" msgstr "" #: extending/newtypes.rst:165 msgid "" "If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the " "interpreter will supply a representation that uses the type's :c:member:" "`~PyTypeObject.tp_name` and a uniquely-identifying value for the object." msgstr "" #: extending/newtypes.rst:169 msgid "" "The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what the :c:" "member:`~PyTypeObject.tp_repr` handler described above is to :func:`repr`; " "that is, it is called when Python code calls :func:`str` on an instance of " "your object. Its implementation is very similar to the :c:member:" "`~PyTypeObject.tp_repr` function, but the resulting string is intended for " "human consumption. If :c:member:`~PyTypeObject.tp_str` is not specified, " "the :c:member:`~PyTypeObject.tp_repr` handler is used instead." msgstr "" #: extending/newtypes.rst:176 msgid "Here is a simple example::" msgstr "" #: extending/newtypes.rst:188 msgid "Attribute Management" msgstr "" #: extending/newtypes.rst:190 msgid "" "For every object which can support attributes, the corresponding type must " "provide the functions that control how the attributes are resolved. There " "needs to be a function which can retrieve attributes (if any are defined), " "and another to set attributes (if setting attributes is allowed). Removing " "an attribute is a special case, for which the new value passed to the " "handler is ``NULL``." msgstr "" #: extending/newtypes.rst:196 msgid "" "Python supports two pairs of attribute handlers; a type that supports " "attributes only needs to implement the functions for one pair. The " "difference is that one pair takes the name of the attribute as a :c:type:" "`char\\*`, while the other accepts a :c:type:`PyObject\\*`. Each type can " "use whichever pair makes more sense for the implementation's convenience. ::" msgstr "" #: extending/newtypes.rst:208 msgid "" "If accessing attributes of an object is always a simple operation (this will " "be explained shortly), there are generic implementations which can be used " "to provide the :c:type:`PyObject\\*` version of the attribute management " "functions. The actual need for type-specific attribute handlers almost " "completely disappeared starting with Python 2.2, though there are many " "examples which have not been updated to use some of the new generic " "mechanism that is available." msgstr "" #: extending/newtypes.rst:219 msgid "Generic Attribute Management" msgstr "" #: extending/newtypes.rst:221 msgid "" "Most extension types only use *simple* attributes. So, what makes the " "attributes simple? There are only a couple of conditions that must be met:" msgstr "" #: extending/newtypes.rst:224 msgid "" "The name of the attributes must be known when :c:func:`PyType_Ready` is " "called." msgstr "" #: extending/newtypes.rst:227 msgid "" "No special processing is needed to record that an attribute was looked up or " "set, nor do actions need to be taken based on the value." msgstr "" #: extending/newtypes.rst:230 msgid "" "Note that this list does not place any restrictions on the values of the " "attributes, when the values are computed, or how relevant data is stored." msgstr "" #: extending/newtypes.rst:233 msgid "" "When :c:func:`PyType_Ready` is called, it uses three tables referenced by " "the type object to create :term:`descriptor`\\s which are placed in the " "dictionary of the type object. Each descriptor controls access to one " "attribute of the instance object. Each of the tables is optional; if all " "three are ``NULL``, instances of the type will only have attributes that are " "inherited from their base type, and should leave the :c:member:" "`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields " "``NULL`` as well, allowing the base type to handle attributes." msgstr "" #: extending/newtypes.rst:241 msgid "The tables are declared as three fields of the type object::" msgstr "" #: extending/newtypes.rst:247 msgid "" "If :c:member:`~PyTypeObject.tp_methods` is not ``NULL``, it must refer to an " "array of :c:type:`PyMethodDef` structures. Each entry in the table is an " "instance of this structure::" msgstr "" #: extending/newtypes.rst:258 msgid "" "One entry should be defined for each method provided by the type; no entries " "are needed for methods inherited from a base type. One additional entry is " "needed at the end; it is a sentinel that marks the end of the array. The :" "attr:`ml_name` field of the sentinel must be ``NULL``." msgstr "" #: extending/newtypes.rst:263 msgid "" "The second table is used to define attributes which map directly to data " "stored in the instance. A variety of primitive C types are supported, and " "access may be read-only or read-write. The structures in the table are " "defined as::" msgstr "" #: extending/newtypes.rst:275 msgid "" "For each entry in the table, a :term:`descriptor` will be constructed and " "added to the type which will be able to extract a value from the instance " "structure. The :attr:`type` field should contain one of the type codes " "defined in the :file:`structmember.h` header; the value will be used to " "determine how to convert Python values to and from C values. The :attr:" "`flags` field is used to store flags which control how the attribute can be " "accessed." msgstr "" #: extending/newtypes.rst:282 msgid "" "The following flag constants are defined in :file:`structmember.h`; they may " "be combined using bitwise-OR." msgstr "" #: extending/newtypes.rst:286 msgid "Constant" msgstr "Constante" #: extending/newtypes.rst:286 msgid "Meaning" msgstr "Signification" #: extending/newtypes.rst:288 msgid ":const:`READONLY`" msgstr "" #: extending/newtypes.rst:288 msgid "Never writable." msgstr "" #: extending/newtypes.rst:290 msgid ":const:`READ_RESTRICTED`" msgstr "" #: extending/newtypes.rst:290 msgid "Not readable in restricted mode." msgstr "" #: extending/newtypes.rst:292 msgid ":const:`WRITE_RESTRICTED`" msgstr "" #: extending/newtypes.rst:292 msgid "Not writable in restricted mode." msgstr "" #: extending/newtypes.rst:294 msgid ":const:`RESTRICTED`" msgstr "" #: extending/newtypes.rst:294 msgid "Not readable or writable in restricted mode." msgstr "" #: extending/newtypes.rst:303 msgid "" "An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` " "table to build descriptors that are used at runtime is that any attribute " "defined this way can have an associated doc string simply by providing the " "text in the table. An application can use the introspection API to retrieve " "the descriptor from the class object, and get the doc string using its :attr:" "`__doc__` attribute." msgstr "" #: extending/newtypes.rst:309 msgid "" "As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry " "with a :attr:`name` value of ``NULL`` is required." msgstr "" #: extending/newtypes.rst:323 msgid "Type-specific Attribute Management" msgstr "" #: extending/newtypes.rst:325 msgid "" "For simplicity, only the :c:type:`char\\*` version will be demonstrated " "here; the type of the name parameter is the only difference between the :c:" "type:`char\\*` and :c:type:`PyObject\\*` flavors of the interface. This " "example effectively does the same thing as the generic example above, but " "does not use the generic support added in Python 2.2. It explains how the " "handler functions are called, so that if you do need to extend their " "functionality, you'll understand what needs to be done." msgstr "" #: extending/newtypes.rst:333 msgid "" "The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object " "requires an attribute look-up. It is called in the same situations where " "the :meth:`__getattr__` method of a class would be called." msgstr "" #: extending/newtypes.rst:337 msgid "Here is an example::" msgstr "Voici un exemple ::" #: extending/newtypes.rst:353 msgid "" "The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:" "`__setattr__` or :meth:`__delattr__` method of a class instance would be " "called. When an attribute should be deleted, the third parameter will be " "``NULL``. Here is an example that simply raises an exception; if this were " "really all you wanted, the :c:member:`~PyTypeObject.tp_setattr` handler " "should be set to ``NULL``. ::" msgstr "" #: extending/newtypes.rst:367 msgid "Object Comparison" msgstr "" #: extending/newtypes.rst:373 msgid "" "The :c:member:`~PyTypeObject.tp_richcompare` handler is called when " "comparisons are needed. It is analogous to the :ref:`rich comparison " "methods `, like :meth:`__lt__`, and also called by :c:func:" "`PyObject_RichCompare` and :c:func:`PyObject_RichCompareBool`." msgstr "" #: extending/newtypes.rst:378 msgid "" "This function is called with two Python objects and the operator as " "arguments, where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, " "``Py_GT``, ``Py_LT`` or ``Py_GT``. It should compare the two objects with " "respect to the specified operator and return ``Py_True`` or ``Py_False`` if " "the comparison is successful, ``Py_NotImplemented`` to indicate that " "comparison is not implemented and the other object's comparison method " "should be tried, or ``NULL`` if an exception was set." msgstr "" #: extending/newtypes.rst:386 msgid "" "Here is a sample implementation, for a datatype that is considered equal if " "the size of an internal pointer is equal::" msgstr "" #: extending/newtypes.rst:416 msgid "Abstract Protocol Support" msgstr "" #: extending/newtypes.rst:418 msgid "" "Python supports a variety of *abstract* 'protocols;' the specific interfaces " "provided to use these interfaces are documented in :ref:`abstract`." msgstr "" #: extending/newtypes.rst:422 msgid "" "A number of these abstract interfaces were defined early in the development " "of the Python implementation. In particular, the number, mapping, and " "sequence protocols have been part of Python since the beginning. Other " "protocols have been added over time. For protocols which depend on several " "handler routines from the type implementation, the older protocols have been " "defined as optional blocks of handlers referenced by the type object. For " "newer protocols there are additional slots in the main type object, with a " "flag bit being set to indicate that the slots are present and should be " "checked by the interpreter. (The flag bit does not indicate that the slot " "values are non-``NULL``. The flag may be set to indicate the presence of a " "slot, but a slot may still be unfilled.) ::" msgstr "" #: extending/newtypes.rst:437 msgid "" "If you wish your object to be able to act like a number, a sequence, or a " "mapping object, then you place the address of a structure that implements " "the C type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, or :c:" "type:`PyMappingMethods`, respectively. It is up to you to fill in this " "structure with appropriate values. You can find examples of the use of each " "of these in the :file:`Objects` directory of the Python source " "distribution. ::" msgstr "" #: extending/newtypes.rst:446 msgid "" "This function, if you choose to provide it, should return a hash number for " "an instance of your data type. Here is a simple example::" msgstr "" #: extending/newtypes.rst:459 msgid "" ":c:type:`Py_hash_t` is a signed integer type with a platform-varying width. " "Returning ``-1`` from :c:member:`~PyTypeObject.tp_hash` indicates an error, " "which is why you should be careful to avoid returning it when hash " "computation is successful, as seen above." msgstr "" #: extending/newtypes.rst:468 msgid "" "This function is called when an instance of your data type is \"called\", " "for example, if ``obj1`` is an instance of your data type and the Python " "script contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` " "handler is invoked." msgstr "" #: extending/newtypes.rst:472 msgid "This function takes three arguments:" msgstr "" #: extending/newtypes.rst:474 msgid "" "*self* is the instance of the data type which is the subject of the call. If " "the call is ``obj1('hello')``, then *self* is ``obj1``." msgstr "" #: extending/newtypes.rst:477 msgid "" "*args* is a tuple containing the arguments to the call. You can use :c:func:" "`PyArg_ParseTuple` to extract the arguments." msgstr "" #: extending/newtypes.rst:480 msgid "" "*kwds* is a dictionary of keyword arguments that were passed. If this is non-" "``NULL`` and you support keyword arguments, use :c:func:" "`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do not want " "to support keyword arguments and this is non-``NULL``, raise a :exc:" "`TypeError` with a message saying that keyword arguments are not supported." msgstr "" #: extending/newtypes.rst:486 msgid "Here is a toy ``tp_call`` implementation::" msgstr "" #: extending/newtypes.rst:512 msgid "" "These functions provide support for the iterator protocol. Both handlers " "take exactly one parameter, the instance for which they are being called, " "and return a new reference. In the case of an error, they should set an " "exception and return ``NULL``. :c:member:`~PyTypeObject.tp_iter` " "corresponds to the Python :meth:`__iter__` method, while :c:member:" "`~PyTypeObject.tp_iternext` corresponds to the Python :meth:`~iterator." "__next__` method." msgstr "" #: extending/newtypes.rst:519 msgid "" "Any :term:`iterable` object must implement the :c:member:`~PyTypeObject." "tp_iter` handler, which must return an :term:`iterator` object. Here the " "same guidelines apply as for Python classes:" msgstr "" #: extending/newtypes.rst:523 msgid "" "For collections (such as lists and tuples) which can support multiple " "independent iterators, a new iterator should be created and returned by each " "call to :c:member:`~PyTypeObject.tp_iter`." msgstr "" #: extending/newtypes.rst:526 msgid "" "Objects which can only be iterated over once (usually due to side effects of " "iteration, such as file objects) can implement :c:member:`~PyTypeObject." "tp_iter` by returning a new reference to themselves -- and should also " "therefore implement the :c:member:`~PyTypeObject.tp_iternext` handler." msgstr "" #: extending/newtypes.rst:531 msgid "" "Any :term:`iterator` object should implement both :c:member:`~PyTypeObject." "tp_iter` and :c:member:`~PyTypeObject.tp_iternext`. An iterator's :c:member:" "`~PyTypeObject.tp_iter` handler should return a new reference to the " "iterator. Its :c:member:`~PyTypeObject.tp_iternext` handler should return a " "new reference to the next object in the iteration, if there is one. If the " "iteration has reached the end, :c:member:`~PyTypeObject.tp_iternext` may " "return ``NULL`` without setting an exception, or it may set :exc:" "`StopIteration` *in addition* to returning ``NULL``; avoiding the exception " "can yield slightly better performance. If an actual error occurs, :c:member:" "`~PyTypeObject.tp_iternext` should always set an exception and return " "``NULL``." msgstr "" #: extending/newtypes.rst:547 msgid "Weak Reference Support" msgstr "" #: extending/newtypes.rst:549 msgid "" "One of the goals of Python's weak reference implementation is to allow any " "type to participate in the weak reference mechanism without incurring the " "overhead on performance-critical objects (such as numbers)." msgstr "" #: extending/newtypes.rst:554 msgid "Documentation for the :mod:`weakref` module." msgstr "" #: extending/newtypes.rst:556 msgid "" "For an object to be weakly referencable, the extension type must do two " "things:" msgstr "" #: extending/newtypes.rst:558 msgid "" "Include a :c:type:`PyObject\\*` field in the C object structure dedicated to " "the weak reference mechanism. The object's constructor should leave it " "``NULL`` (which is automatic when using the default :c:member:`~PyTypeObject." "tp_alloc`)." msgstr "" #: extending/newtypes.rst:563 msgid "" "Set the :c:member:`~PyTypeObject.tp_weaklistoffset` type member to the " "offset of the aforementioned field in the C object structure, so that the " "interpreter knows how to access and modify that field." msgstr "" #: extending/newtypes.rst:567 msgid "" "Concretely, here is how a trivial object structure would be augmented with " "the required field::" msgstr "" #: extending/newtypes.rst:575 msgid "And the corresponding member in the statically-declared type object::" msgstr "" #: extending/newtypes.rst:583 msgid "" "The only further addition is that ``tp_dealloc`` needs to clear any weak " "references (by calling :c:func:`PyObject_ClearWeakRefs`) if the field is non-" "``NULL``::" msgstr "" #: extending/newtypes.rst:599 msgid "More Suggestions" msgstr "" #: extending/newtypes.rst:601 msgid "" "In order to learn how to implement any specific method for your new data " "type, get the :term:`CPython` source code. Go to the :file:`Objects` " "directory, then search the C source files for ``tp_`` plus the function you " "want (for example, ``tp_richcompare``). You will find examples of the " "function you want to implement." msgstr "" #: extending/newtypes.rst:607 msgid "" "When you need to verify that an object is a concrete instance of the type " "you are implementing, use the :c:func:`PyObject_TypeCheck` function. A " "sample of its use might be something like the following::" msgstr "" #: extending/newtypes.rst:618 msgid "Download CPython source releases." msgstr "" #: extending/newtypes.rst:618 msgid "https://www.python.org/downloads/source/" msgstr "" #: extending/newtypes.rst:620 msgid "" "The CPython project on GitHub, where the CPython source code is developed." msgstr "" #: extending/newtypes.rst:621 msgid "https://github.com/python/cpython" msgstr ""