forked from AFPy/python-docs-fr
1462 lines
56 KiB
Plaintext
1462 lines
56 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
||
# Copyright (C) 1990-2016, Python Software Foundation
|
||
# This file is distributed under the same license as the Python package.
|
||
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
||
#
|
||
#, fuzzy
|
||
msgid ""
|
||
msgstr ""
|
||
"Project-Id-Version: Python 2.7\n"
|
||
"Report-Msgid-Bugs-To: \n"
|
||
"POT-Creation-Date: 2016-10-30 10:44+0100\n"
|
||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
||
"Language-Team: LANGUAGE <LL@li.org>\n"
|
||
"MIME-Version: 1.0\n"
|
||
"Content-Type: text/plain; charset=UTF-8\n"
|
||
"Content-Transfer-Encoding: 8bit\n"
|
||
|
||
#: ../Doc/extending/newtypes.rst:8
|
||
msgid "Defining New Types"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:15
|
||
msgid ""
|
||
"As mentioned in the last chapter, Python allows the writer of an extension "
|
||
"module to define new types that can be manipulated from Python code, much "
|
||
"like strings and lists in core Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:19
|
||
msgid ""
|
||
"This is not hard; the code for all extension types follows a pattern, but "
|
||
"there are some details that you need to understand before you can get "
|
||
"started."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:24
|
||
msgid ""
|
||
"The way new types are defined changed dramatically (and for the better) in "
|
||
"Python 2.2. This document documents how to define new types for Python 2.2 "
|
||
"and later. If you need to support older versions of Python, you will need "
|
||
"to refer to `older versions of this documentation <https://www.python.org/"
|
||
"doc/versions/>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:34
|
||
msgid "The Basics"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:36
|
||
msgid ""
|
||
"The Python runtime sees all Python objects as variables of type :c:type:"
|
||
"`PyObject\\*`. A :c:type:`PyObject` is not a very magnificent object - it "
|
||
"just contains the refcount and a pointer to the object's \"type object\". "
|
||
"This is where the action is; the type object determines which (C) functions "
|
||
"get called when, for instance, an attribute gets looked up on an object or "
|
||
"it is multiplied by another object. These C functions are called \"type "
|
||
"methods\"."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:43
|
||
msgid ""
|
||
"So, if you want to define a new object type, you need to create a new type "
|
||
"object."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:46
|
||
msgid ""
|
||
"This sort of thing can only be explained by example, so here's a minimal, "
|
||
"but complete, module that defines a new type:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:52
|
||
msgid ""
|
||
"Now that's quite a bit to take in at once, but hopefully bits will seem "
|
||
"familiar from the last chapter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:55
|
||
msgid "The first bit that will be new is::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:61
|
||
msgid ""
|
||
"This is what a Noddy object will contain---in this case, nothing more than "
|
||
"every Python object contains, namely a refcount and a pointer to a type "
|
||
"object. These are the fields the ``PyObject_HEAD`` macro brings in. The "
|
||
"reason for the macro is to standardize the layout and to enable special "
|
||
"debugging fields in debug builds. Note that there is no semicolon after the "
|
||
"``PyObject_HEAD`` macro; one is included in the macro definition. Be wary "
|
||
"of adding one by accident; it's easy to do from habit, and your compiler "
|
||
"might not complain, but someone else's probably will! (On Windows, MSVC is "
|
||
"known to call this an error and refuse to compile the code.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:71
|
||
msgid ""
|
||
"For contrast, let's take a look at the corresponding definition for standard "
|
||
"Python integers::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:79
|
||
msgid "Moving on, we come to the crunch --- the type object. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:106
|
||
msgid ""
|
||
"Now if you go and look up the definition of :c:type:`PyTypeObject` in :file:"
|
||
"`object.h` you'll see that it has many more fields that the definition "
|
||
"above. The remaining fields will be filled with zeros by the C compiler, "
|
||
"and it's common practice to not specify them explicitly unless you need them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:111
|
||
msgid ""
|
||
"This is so important that we're going to pick the top of it apart still "
|
||
"further::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:116
|
||
msgid "This line is a bit of a wart; what we'd like to write is::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:120
|
||
msgid ""
|
||
"as the type of a type object is \"type\", but this isn't strictly conforming "
|
||
"C and some compilers complain. Fortunately, this member will be filled in "
|
||
"for us by :c:func:`PyType_Ready`. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:126
|
||
msgid ""
|
||
"The :attr:`ob_size` field of the header is not used; its presence in the "
|
||
"type structure is a historical artifact that is maintained for binary "
|
||
"compatibility with extension modules compiled for older versions of Python. "
|
||
"Always set this field to zero. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:133
|
||
msgid ""
|
||
"The name of our type. This will appear in the default textual "
|
||
"representation of our objects and in some error messages, for example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:141
|
||
msgid ""
|
||
"Note that the name is a dotted name that includes both the module name and "
|
||
"the name of the type within the module. The module in this case is :mod:"
|
||
"`noddy` and the type is :class:`Noddy`, so we set the type name to :class:"
|
||
"`noddy.Noddy`. One side effect of using an undotted name is that the pydoc "
|
||
"documentation tool will not list the new type in the module documentation. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:149
|
||
msgid ""
|
||
"This is so that Python knows how much memory to allocate when you call :c:"
|
||
"func:`PyObject_New`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:154
|
||
msgid ""
|
||
"If you want your type to be subclassable from Python, and your type has the "
|
||
"same :c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have "
|
||
"problems with multiple inheritance. A Python subclass of your type will "
|
||
"have to list your type first in its :attr:`~class.__bases__`, or else it "
|
||
"will not be able to call your type's :meth:`__new__` method without getting "
|
||
"an error. You can avoid this problem by ensuring that your type has a "
|
||
"larger value for :c:member:`~PyTypeObject.tp_basicsize` than its base type "
|
||
"does. Most of the time, this will be true anyway, because either your base "
|
||
"type will be :class:`object`, or else you will be adding data members to "
|
||
"your base type, and therefore increasing its size."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:168
|
||
msgid ""
|
||
"This has to do with variable length objects like lists and strings. Ignore "
|
||
"this for now."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:171
|
||
msgid ""
|
||
"Skipping a number of type methods that we don't provide, we set the class "
|
||
"flags to :const:`Py_TPFLAGS_DEFAULT`. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:176
|
||
msgid ""
|
||
"All types should include this constant in their flags. It enables all of "
|
||
"the members defined by the current version of Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:179
|
||
msgid ""
|
||
"We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:183
|
||
msgid ""
|
||
"Now we get into the type methods, the things that make your objects "
|
||
"different from the others. We aren't going to implement any of these in "
|
||
"this version of the module. We'll expand this example later to have more "
|
||
"interesting behavior."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:187
|
||
msgid ""
|
||
"For now, all we want to be able to do is to create new :class:`Noddy` "
|
||
"objects. To enable object creation, we have to provide a :c:member:"
|
||
"`~PyTypeObject.tp_new` implementation. In this case, we can just use the "
|
||
"default implementation provided by the API function :c:func:"
|
||
"`PyType_GenericNew`. We'd like to just assign this to the :c:member:"
|
||
"`~PyTypeObject.tp_new` slot, but we can't, for portability sake, On some "
|
||
"platforms or compilers, we can't statically initialize a structure member "
|
||
"with a function defined in another C module, so, instead, we'll assign the :"
|
||
"c:member:`~PyTypeObject.tp_new` slot in the module initialization function "
|
||
"just before calling :c:func:`PyType_Ready`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:201
|
||
msgid ""
|
||
"All the other type methods are *NULL*, so we'll go over them later --- "
|
||
"that's for a later section!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:204
|
||
msgid ""
|
||
"Everything else in the file should be familiar, except for some code in :c:"
|
||
"func:`initnoddy`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:210
|
||
msgid ""
|
||
"This initializes the :class:`Noddy` type, filing in a number of members, "
|
||
"including :attr:`ob_type` that we initially set to *NULL*. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:215
|
||
msgid ""
|
||
"This adds the type to the module dictionary. This allows us to create :"
|
||
"class:`Noddy` instances by calling the :class:`Noddy` class::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:221
|
||
msgid ""
|
||
"That's it! All that remains is to build it; put the above code in a file "
|
||
"called :file:`noddy.c` and ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:228
|
||
msgid "in a file called :file:`setup.py`; then typing"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:234
|
||
msgid ""
|
||
"at a shell should produce a file :file:`noddy.so` in a subdirectory; move to "
|
||
"that directory and fire up Python --- you should be able to ``import noddy`` "
|
||
"and play around with Noddy objects."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:238
|
||
msgid "That wasn't so hard, was it?"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:240
|
||
msgid ""
|
||
"Of course, the current Noddy type is pretty uninteresting. It has no data "
|
||
"and doesn't do anything. It can't even be subclassed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:245
|
||
msgid "Adding data and methods to the Basic example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:247
|
||
msgid ""
|
||
"Let's expend the basic example to add some data and methods. Let's also "
|
||
"make the type usable as a base class. We'll create a new module, :mod:"
|
||
"`noddy2` that adds these capabilities:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:254
|
||
msgid "This version of the module has a number of changes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:256
|
||
msgid "We've added an extra include::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:260
|
||
msgid ""
|
||
"This include provides declarations that we use to handle attributes, as "
|
||
"described a bit later."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:263
|
||
msgid ""
|
||
"The name of the :class:`Noddy` object structure has been shortened to :class:"
|
||
"`Noddy`. The type object name has been shortened to :class:`NoddyType`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:266
|
||
msgid ""
|
||
"The :class:`Noddy` type now has three data attributes, *first*, *last*, and "
|
||
"*number*. The *first* and *last* variables are Python strings containing "
|
||
"first and last names. The *number* attribute is an integer."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:270
|
||
msgid "The object structure is updated accordingly::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:279
|
||
msgid ""
|
||
"Because we now have data to manage, we have to be more careful about object "
|
||
"allocation and deallocation. At a minimum, we need a deallocation method::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:290
|
||
msgid "which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:294
|
||
msgid ""
|
||
"This method decrements the reference counts of the two Python attributes. We "
|
||
"use :c:func:`Py_XDECREF` here because the :attr:`first` and :attr:`last` "
|
||
"members could be *NULL*. It then calls the :c:member:`~PyTypeObject."
|
||
"tp_free` member of the object's type to free the object's memory. Note that "
|
||
"the object's type might not be :class:`NoddyType`, because the object may be "
|
||
"an instance of a subclass."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:300
|
||
msgid ""
|
||
"We want to make sure that the first and last names are initialized to empty "
|
||
"strings, so we provide a new method::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:330
|
||
msgid "and install it in the :c:member:`~PyTypeObject.tp_new` member::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:334
|
||
msgid ""
|
||
"The new member is responsible for creating (as opposed to initializing) "
|
||
"objects of the type. It is exposed in Python as the :meth:`__new__` "
|
||
"method. See the paper titled \"Unifying types and classes in Python\" for a "
|
||
"detailed discussion of the :meth:`__new__` method. One reason to implement "
|
||
"a new method is to assure the initial values of instance variables. In this "
|
||
"case, we use the new method to make sure that the initial values of the "
|
||
"members :attr:`first` and :attr:`last` are not *NULL*. If we didn't care "
|
||
"whether the initial values were *NULL*, we could have used :c:func:"
|
||
"`PyType_GenericNew` as our new method, as we did before. :c:func:"
|
||
"`PyType_GenericNew` initializes all of the instance variable members to "
|
||
"*NULL*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:345
|
||
msgid ""
|
||
"The new method is a static method that is passed the type being instantiated "
|
||
"and any arguments passed when the type was called, and that returns the new "
|
||
"object created. New methods always accept positional and keyword arguments, "
|
||
"but they often ignore the arguments, leaving the argument handling to "
|
||
"initializer methods. Note that if the type supports subclassing, the type "
|
||
"passed may not be the type being defined. The new method calls the tp_alloc "
|
||
"slot to allocate memory. We don't fill the :c:member:`~PyTypeObject."
|
||
"tp_alloc` slot ourselves. Rather :c:func:`PyType_Ready` fills it for us by "
|
||
"inheriting it from our base class, which is :class:`object` by default. "
|
||
"Most types use the default allocation."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:357
|
||
msgid ""
|
||
"If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one "
|
||
"that calls a base type's :c:member:`~PyTypeObject.tp_new` or :meth:"
|
||
"`__new__`), you must *not* try to determine what method to call using method "
|
||
"resolution order at runtime. Always statically determine what type you are "
|
||
"going to call, and call its :c:member:`~PyTypeObject.tp_new` directly, or "
|
||
"via ``type->tp_base->tp_new``. If you do not do this, Python subclasses of "
|
||
"your type that also inherit from other Python-defined classes may not work "
|
||
"correctly. (Specifically, you may not be able to create instances of such "
|
||
"subclasses without getting a :exc:`TypeError`.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:366
|
||
msgid "We provide an initialization function::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:397
|
||
msgid "by filling the :c:member:`~PyTypeObject.tp_init` slot. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:401
|
||
msgid ""
|
||
"The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as the :meth:"
|
||
"`__init__` method. It is used to initialize an object after it's created. "
|
||
"Unlike the new method, we can't guarantee that the initializer is called. "
|
||
"The initializer isn't called when unpickling objects and it can be "
|
||
"overridden. Our initializer accepts arguments to provide initial values for "
|
||
"our instance. Initializers always accept positional and keyword arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:408
|
||
msgid ""
|
||
"Initializers can be called multiple times. Anyone can call the :meth:"
|
||
"`__init__` method on our objects. For this reason, we have to be extra "
|
||
"careful when assigning the new values. We might be tempted, for example to "
|
||
"assign the :attr:`first` member like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:419
|
||
msgid ""
|
||
"But this would be risky. Our type doesn't restrict the type of the :attr:"
|
||
"`first` member, so it could be any kind of object. It could have a "
|
||
"destructor that causes code to be executed that tries to access the :attr:"
|
||
"`first` member. To be paranoid and protect ourselves against this "
|
||
"possibility, we almost always reassign members before decrementing their "
|
||
"reference counts. When don't we have to do this?"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:426
|
||
msgid "when we absolutely know that the reference count is greater than 1"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:428
|
||
msgid ""
|
||
"when we know that deallocation of the object [#]_ will not cause any calls "
|
||
"back into our type's code"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:431
|
||
msgid ""
|
||
"when decrementing a reference count in a :c:member:`~PyTypeObject."
|
||
"tp_dealloc` handler when garbage-collections is not supported [#]_"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:434
|
||
msgid ""
|
||
"We want to expose our instance variables as attributes. There are a number "
|
||
"of ways to do that. The simplest way is to define member definitions::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:447
|
||
msgid ""
|
||
"and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:451
|
||
msgid ""
|
||
"Each member definition has a member name, type, offset, access flags and "
|
||
"documentation string. See the :ref:`Generic-Attribute-Management` section "
|
||
"below for details."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:455
|
||
msgid ""
|
||
"A disadvantage of this approach is that it doesn't provide a way to restrict "
|
||
"the types of objects that can be assigned to the Python attributes. We "
|
||
"expect the first and last names to be strings, but any Python objects can be "
|
||
"assigned. Further, the attributes can be deleted, setting the C pointers to "
|
||
"*NULL*. Even though we can make sure the members are initialized to non-"
|
||
"*NULL* values, the members can be set to *NULL* if the attributes are "
|
||
"deleted."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:462
|
||
msgid ""
|
||
"We define a single method, :meth:`name`, that outputs the objects name as "
|
||
"the concatenation of the first and last names. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:497
|
||
msgid ""
|
||
"The method is implemented as a C function that takes a :class:`Noddy` (or :"
|
||
"class:`Noddy` subclass) instance as the first argument. Methods always take "
|
||
"an instance as the first argument. Methods often take positional and keyword "
|
||
"arguments as well, but in this cased we don't take any and don't need to "
|
||
"accept a positional argument tuple or keyword argument dictionary. This "
|
||
"method is equivalent to the Python method::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:507
|
||
msgid ""
|
||
"Note that we have to check for the possibility that our :attr:`first` and :"
|
||
"attr:`last` members are *NULL*. This is because they can be deleted, in "
|
||
"which case they are set to *NULL*. It would be better to prevent deletion "
|
||
"of these attributes and to restrict the attribute values to be strings. "
|
||
"We'll see how to do that in the next section."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:513
|
||
msgid ""
|
||
"Now that we've defined the method, we need to create an array of method "
|
||
"definitions::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:523
|
||
msgid "and assign them to the :c:member:`~PyTypeObject.tp_methods` slot::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:527
|
||
msgid ""
|
||
"Note that we used the :const:`METH_NOARGS` flag to indicate that the method "
|
||
"is passed no arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:530
|
||
msgid ""
|
||
"Finally, we'll make our type usable as a base class. We've written our "
|
||
"methods carefully so far so that they don't make any assumptions about the "
|
||
"type of the object being created or used, so all we need to do is to add "
|
||
"the :const:`Py_TPFLAGS_BASETYPE` to our class flag definition::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:537
|
||
msgid ""
|
||
"We rename :c:func:`initnoddy` to :c:func:`initnoddy2` and update the module "
|
||
"name passed to :c:func:`Py_InitModule3`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:540
|
||
msgid "Finally, we update our :file:`setup.py` file to build the new module::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:551
|
||
msgid "Providing finer control over data attributes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:553
|
||
msgid ""
|
||
"In this section, we'll provide finer control over how the :attr:`first` and :"
|
||
"attr:`last` attributes are set in the :class:`Noddy` example. In the "
|
||
"previous version of our module, the instance variables :attr:`first` and :"
|
||
"attr:`last` could be set to non-string values or even deleted. We want to "
|
||
"make sure that these attributes always contain strings."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:562
|
||
msgid ""
|
||
"To provide greater control, over the :attr:`first` and :attr:`last` "
|
||
"attributes, we'll use custom getter and setter functions. Here are the "
|
||
"functions for getting and setting the :attr:`first` attribute::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:593
|
||
msgid ""
|
||
"The getter function is passed a :class:`Noddy` object and a \"closure\", "
|
||
"which is void pointer. In this case, the closure is ignored. (The closure "
|
||
"supports an advanced usage in which definition data is passed to the getter "
|
||
"and setter. This could, for example, be used to allow a single set of getter "
|
||
"and setter functions that decide the attribute to get or set based on data "
|
||
"in the closure.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:599
|
||
msgid ""
|
||
"The setter function is passed the :class:`Noddy` object, the new value, and "
|
||
"the closure. The new value may be *NULL*, in which case the attribute is "
|
||
"being deleted. In our setter, we raise an error if the attribute is deleted "
|
||
"or if the attribute value is not a string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:604
|
||
msgid "We create an array of :c:type:`PyGetSetDef` structures::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:618
|
||
msgid "and register it in the :c:member:`~PyTypeObject.tp_getset` slot::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:622
|
||
msgid "to register our attribute getters and setters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:624
|
||
msgid ""
|
||
"The last item in a :c:type:`PyGetSetDef` structure is the closure mentioned "
|
||
"above. In this case, we aren't using the closure, so we just pass *NULL*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:627
|
||
msgid "We also remove the member definitions for these attributes::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:635
|
||
msgid ""
|
||
"We also need to update the :c:member:`~PyTypeObject.tp_init` handler to only "
|
||
"allow strings [#]_ to be passed::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:667
|
||
msgid ""
|
||
"With these changes, we can assure that the :attr:`first` and :attr:`last` "
|
||
"members are never *NULL* so we can remove checks for *NULL* values in almost "
|
||
"all cases. This means that most of the :c:func:`Py_XDECREF` calls can be "
|
||
"converted to :c:func:`Py_DECREF` calls. The only place we can't change these "
|
||
"calls is in the deallocator, where there is the possibility that the "
|
||
"initialization of these members failed in the constructor."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:674
|
||
msgid ""
|
||
"We also rename the module initialization function and module name in the "
|
||
"initialization function, as we did before, and we add an extra definition to "
|
||
"the :file:`setup.py` file."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:680
|
||
msgid "Supporting cyclic garbage collection"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:682
|
||
msgid ""
|
||
"Python has a cyclic-garbage collector that can identify unneeded objects "
|
||
"even when their reference counts are not zero. This can happen when objects "
|
||
"are involved in cycles. For example, consider::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:690
|
||
msgid ""
|
||
"In this example, we create a list that contains itself. When we delete it, "
|
||
"it still has a reference from itself. Its reference count doesn't drop to "
|
||
"zero. Fortunately, Python's cyclic-garbage collector will eventually figure "
|
||
"out that the list is garbage and free it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:695
|
||
msgid ""
|
||
"In the second version of the :class:`Noddy` example, we allowed any kind of "
|
||
"object to be stored in the :attr:`first` or :attr:`last` attributes. [#]_ "
|
||
"This means that :class:`Noddy` objects can participate in cycles::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:704
|
||
msgid ""
|
||
"This is pretty silly, but it gives us an excuse to add support for the "
|
||
"cyclic-garbage collector to the :class:`Noddy` example. To support cyclic "
|
||
"garbage collection, types need to fill two slots and set a class flag that "
|
||
"enables these slots:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:712
|
||
msgid ""
|
||
"The traversal method provides access to subobjects that could participate in "
|
||
"cycles::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:734
|
||
msgid ""
|
||
"For each subobject that can participate in cycles, we need to call the :c:"
|
||
"func:`visit` function, which is passed to the traversal method. The :c:func:"
|
||
"`visit` function takes as arguments the subobject and the extra argument "
|
||
"*arg* passed to the traversal method. It returns an integer value that must "
|
||
"be returned if it is non-zero."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:740
|
||
msgid ""
|
||
"Python 2.4 and higher provide a :c:func:`Py_VISIT` macro that automates "
|
||
"calling visit functions. With :c:func:`Py_VISIT`, :c:func:`Noddy_traverse` "
|
||
"can be simplified::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:754
|
||
msgid ""
|
||
"Note that the :c:member:`~PyTypeObject.tp_traverse` implementation must name "
|
||
"its arguments exactly *visit* and *arg* in order to use :c:func:`Py_VISIT`. "
|
||
"This is to encourage uniformity across these boring implementations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:758
|
||
msgid ""
|
||
"We also need to provide a method for clearing any subobjects that can "
|
||
"participate in cycles. We implement the method and reimplement the "
|
||
"deallocator to use it::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:785
|
||
msgid ""
|
||
"Notice the use of a temporary variable in :c:func:`Noddy_clear`. We use the "
|
||
"temporary variable so that we can set each member to *NULL* before "
|
||
"decrementing its reference count. We do this because, as was discussed "
|
||
"earlier, if the reference count drops to zero, we might cause code to run "
|
||
"that calls back into the object. In addition, because we now support "
|
||
"garbage collection, we also have to worry about code being run that triggers "
|
||
"garbage collection. If garbage collection is run, our :c:member:"
|
||
"`~PyTypeObject.tp_traverse` handler could get called. We can't take a chance "
|
||
"of having :c:func:`Noddy_traverse` called when a member's reference count "
|
||
"has dropped to zero and its value hasn't been set to *NULL*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:795
|
||
msgid ""
|
||
"Python 2.4 and higher provide a :c:func:`Py_CLEAR` that automates the "
|
||
"careful decrementing of reference counts. With :c:func:`Py_CLEAR`, the :c:"
|
||
"func:`Noddy_clear` function can be simplified::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:807
|
||
msgid ""
|
||
"Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:811
|
||
msgid ""
|
||
"That's pretty much it. If we had written custom :c:member:`~PyTypeObject."
|
||
"tp_alloc` or :c:member:`~PyTypeObject.tp_free` slots, we'd need to modify "
|
||
"them for cyclic-garbage collection. Most extensions will use the versions "
|
||
"automatically provided."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:817
|
||
msgid "Subclassing other types"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:819
|
||
msgid ""
|
||
"It is possible to create new extension types that are derived from existing "
|
||
"types. It is easiest to inherit from the built in types, since an extension "
|
||
"can easily use the :class:`PyTypeObject` it needs. It can be difficult to "
|
||
"share these :class:`PyTypeObject` structures between extension modules."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:824
|
||
msgid ""
|
||
"In this example we will create a :class:`Shoddy` type that inherits from the "
|
||
"built-in :class:`list` type. The new type will be completely compatible with "
|
||
"regular lists, but will have an additional :meth:`increment` method that "
|
||
"increases an internal counter. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:842
|
||
msgid ""
|
||
"As you can see, the source code closely resembles the :class:`Noddy` "
|
||
"examples in previous sections. We will break down the main differences "
|
||
"between them. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:850
|
||
msgid ""
|
||
"The primary difference for derived type objects is that the base type's "
|
||
"object structure must be the first value. The base type will already include "
|
||
"the :c:func:`PyObject_HEAD` at the beginning of its structure."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:854
|
||
msgid ""
|
||
"When a Python object is a :class:`Shoddy` instance, its *PyObject\\** "
|
||
"pointer can be safely cast to both *PyListObject\\** and *Shoddy\\**. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:866
|
||
msgid ""
|
||
"In the :attr:`__init__` method for our type, we can see how to call through "
|
||
"to the :attr:`__init__` method of the base type."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:869
|
||
msgid ""
|
||
"This pattern is important when writing a type with custom :attr:`new` and :"
|
||
"attr:`dealloc` methods. The :attr:`new` method should not actually create "
|
||
"the memory for the object with :c:member:`~PyTypeObject.tp_alloc`, that will "
|
||
"be handled by the base class when calling its :c:member:`~PyTypeObject."
|
||
"tp_new`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:874
|
||
msgid ""
|
||
"When filling out the :c:func:`PyTypeObject` for the :class:`Shoddy` type, "
|
||
"you see a slot for :c:func:`tp_base`. Due to cross platform compiler issues, "
|
||
"you can't fill that field directly with the :c:func:`PyList_Type`; it can be "
|
||
"done later in the module's :c:func:`init` function. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:896
|
||
msgid ""
|
||
"Before calling :c:func:`PyType_Ready`, the type structure must have the :c:"
|
||
"member:`~PyTypeObject.tp_base` slot filled in. When we are deriving a new "
|
||
"type, it is not necessary to fill out the :c:member:`~PyTypeObject.tp_alloc` "
|
||
"slot with :c:func:`PyType_GenericNew` -- the allocate function from the base "
|
||
"type will be inherited."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:901
|
||
msgid ""
|
||
"After that, calling :c:func:`PyType_Ready` and adding the type object to the "
|
||
"module is the same as with the basic :class:`Noddy` examples."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:908
|
||
msgid "Type Methods"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:910
|
||
msgid ""
|
||
"This section aims to give a quick fly-by on the various type methods you can "
|
||
"implement and what they do."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:913
|
||
msgid ""
|
||
"Here is the definition of :c:type:`PyTypeObject`, with some fields only used "
|
||
"in debug builds omitted:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:919
|
||
msgid ""
|
||
"Now that's a *lot* of methods. Don't worry too much though - if you have a "
|
||
"type you want to define, the chances are very good that you will only "
|
||
"implement a handful of these."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:923
|
||
msgid ""
|
||
"As you probably expect by now, we're going to go over this and give more "
|
||
"information about the various handlers. We won't go in the order they are "
|
||
"defined in the structure, because there is a lot of historical baggage that "
|
||
"impacts the ordering of the fields; be sure your type initialization keeps "
|
||
"the fields in the right order! It's often easiest to find an example that "
|
||
"includes all the fields you need (even if they're initialized to ``0``) and "
|
||
"then change the values to suit your new type. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:933
|
||
msgid ""
|
||
"The name of the type - as mentioned in the last section, this will appear in "
|
||
"various places, almost entirely for diagnostic purposes. Try to choose "
|
||
"something that will be helpful in such a situation! ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:939
|
||
msgid ""
|
||
"These fields tell the runtime how much memory to allocate when new objects "
|
||
"of this type are created. Python has some built-in support for variable "
|
||
"length structures (think: strings, lists) which is where the :c:member:"
|
||
"`~PyTypeObject.tp_itemsize` field comes in. This will be dealt with "
|
||
"later. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:946
|
||
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 ""
|
||
"Ici vous pouvez mettre une chaîne (ou son adresse) que vous voulez renvoyer "
|
||
"lorsque le script Python référence ``obj.__doc__`` pour récupérer le "
|
||
"*docstring*."
|
||
|
||
#: ../Doc/extending/newtypes.rst:949
|
||
msgid ""
|
||
"Now we come to the basic type methods---the ones most extension types will "
|
||
"implement."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:954
|
||
msgid "Finalization and De-allocation"
|
||
msgstr "Finalisation et de-allocation"
|
||
|
||
#: ../Doc/extending/newtypes.rst:966
|
||
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, put it here. The "
|
||
"object itself needs to be freed here as well. Here is an example of this "
|
||
"function::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:982
|
||
msgid ""
|
||
"One important requirement of the deallocator function is that it leaves any "
|
||
"pending exceptions alone. This is important since deallocators are "
|
||
"frequently called as the interpreter unwinds the Python stack; when the "
|
||
"stack is unwound due to an exception (rather than normal returns), nothing "
|
||
"is done to protect the deallocators from seeing that an exception has "
|
||
"already been set. Any actions which a deallocator performs which may cause "
|
||
"additional Python code to be executed may detect that an exception has been "
|
||
"set. This can lead to misleading errors from the interpreter. The proper "
|
||
"way to protect against this is to save a pending exception before performing "
|
||
"the unsafe action, and restoring it when done. This can be done using the :"
|
||
"c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1023
|
||
msgid "Object Presentation"
|
||
msgstr "Présentation de l'objet"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1029
|
||
msgid ""
|
||
"In Python, there are three ways to generate a textual representation of an "
|
||
"object: the :func:`repr` function (or equivalent back-tick syntax), the :"
|
||
"func:`str` function, and the :keyword:`print` statement. For most objects, "
|
||
"the :keyword:`print` statement is equivalent to the :func:`str` function, "
|
||
"but it is possible to special-case printing to a :c:type:`FILE\\*` if "
|
||
"necessary; this should only be done if efficiency is identified as a problem "
|
||
"and profiling suggests that creating a temporary string object to be written "
|
||
"to a file is too expensive."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1038
|
||
msgid ""
|
||
"These handlers are all optional, and most types at most need to implement "
|
||
"the :c:member:`~PyTypeObject.tp_str` and :c:member:`~PyTypeObject.tp_repr` "
|
||
"handlers. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1045
|
||
msgid ""
|
||
"The :c:member:`~PyTypeObject.tp_repr` handler should return a string object "
|
||
"containing a representation of the instance for which it is called. Here is "
|
||
"a simple example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1056
|
||
msgid ""
|
||
"If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the "
|
||
"interpreter will supply a representation that uses the type's :c:member:"
|
||
"`~PyTypeObject.tp_name` and a uniquely-identifying value for the object."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1060
|
||
msgid ""
|
||
"The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what the :c:"
|
||
"member:`~PyTypeObject.tp_repr` handler described above is to :func:`repr`; "
|
||
"that is, it is called when Python code calls :func:`str` on an instance of "
|
||
"your object. Its implementation is very similar to the :c:member:"
|
||
"`~PyTypeObject.tp_repr` function, but the resulting string is intended for "
|
||
"human consumption. If :c:member:`~PyTypeObject.tp_str` is not specified, "
|
||
"the :c:member:`~PyTypeObject.tp_repr` handler is used instead."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1067
|
||
msgid "Here is a simple example::"
|
||
msgstr "Voici un exemple simple ::"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1076
|
||
msgid ""
|
||
"The print function will be called whenever Python needs to \"print\" an "
|
||
"instance of the type. For example, if 'node' is an instance of type "
|
||
"TreeNode, then the print function is called when Python code calls::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1082
|
||
msgid ""
|
||
"There is a flags argument and one flag, :const:`Py_PRINT_RAW`, and it "
|
||
"suggests that you print without string quotes and possibly without "
|
||
"interpreting escape sequences."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1086
|
||
msgid ""
|
||
"The print function receives a file object as an argument. You will likely "
|
||
"want to write to that file object."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1089
|
||
msgid "Here is a sample print function::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1107
|
||
msgid "Attribute Management"
|
||
msgstr "Gestion des attributs"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1109
|
||
msgid ""
|
||
"For every object which can support attributes, the corresponding type must "
|
||
"provide the functions that control how the attributes are resolved. There "
|
||
"needs to be a function which can retrieve attributes (if any are defined), "
|
||
"and another to set attributes (if setting attributes is allowed). Removing "
|
||
"an attribute is a special case, for which the new value passed to the "
|
||
"handler is *NULL*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1115
|
||
msgid ""
|
||
"Python supports two pairs of attribute handlers; a type that supports "
|
||
"attributes only needs to implement the functions for one pair. The "
|
||
"difference is that one pair takes the name of the attribute as a :c:type:"
|
||
"`char\\*`, while the other accepts a :c:type:`PyObject\\*`. Each type can "
|
||
"use whichever pair makes more sense for the implementation's convenience. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1127
|
||
msgid ""
|
||
"If accessing attributes of an object is always a simple operation (this will "
|
||
"be explained shortly), there are generic implementations which can be used "
|
||
"to provide the :c:type:`PyObject\\*` version of the attribute management "
|
||
"functions. The actual need for type-specific attribute handlers almost "
|
||
"completely disappeared starting with Python 2.2, though there are many "
|
||
"examples which have not been updated to use some of the new generic "
|
||
"mechanism that is available."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1138
|
||
msgid "Generic Attribute Management"
|
||
msgstr "Gestion des attributs génériques"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1142
|
||
msgid ""
|
||
"Most extension types only use *simple* attributes. So, what makes the "
|
||
"attributes simple? There are only a couple of conditions that must be met:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1145
|
||
msgid ""
|
||
"The name of the attributes must be known when :c:func:`PyType_Ready` is "
|
||
"called."
|
||
msgstr ""
|
||
"Le nom des attributs doivent être déjà connus lorsqu'on lance :c:func:"
|
||
"`PyType_Ready`."
|
||
|
||
#: ../Doc/extending/newtypes.rst:1148
|
||
msgid ""
|
||
"No special processing is needed to record that an attribute was looked up or "
|
||
"set, nor do actions need to be taken based on the value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1151
|
||
msgid ""
|
||
"Note that this list does not place any restrictions on the values of the "
|
||
"attributes, when the values are computed, or how relevant data is stored."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1154
|
||
msgid ""
|
||
"When :c:func:`PyType_Ready` is called, it uses three tables referenced by "
|
||
"the type object to create :term:`descriptor`\\s which are placed in the "
|
||
"dictionary of the type object. Each descriptor controls access to one "
|
||
"attribute of the instance object. Each of the tables is optional; if all "
|
||
"three are *NULL*, instances of the type will only have attributes that are "
|
||
"inherited from their base type, and should leave the :c:member:"
|
||
"`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields "
|
||
"*NULL* as well, allowing the base type to handle attributes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1162
|
||
msgid "The tables are declared as three fields of the type object::"
|
||
msgstr ""
|
||
"Les tables sont déclarées sous la forme de trois champs de type objet ::"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1168
|
||
msgid ""
|
||
"If :c:member:`~PyTypeObject.tp_methods` is not *NULL*, it must refer to an "
|
||
"array of :c:type:`PyMethodDef` structures. Each entry in the table is an "
|
||
"instance of this structure::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1179
|
||
msgid ""
|
||
"One entry should be defined for each method provided by the type; no entries "
|
||
"are needed for methods inherited from a base type. One additional entry is "
|
||
"needed at the end; it is a sentinel that marks the end of the array. The :"
|
||
"attr:`ml_name` field of the sentinel must be *NULL*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1184
|
||
msgid ""
|
||
"XXX Need to refer to some unified discussion of the structure fields, shared "
|
||
"with the next section."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1187
|
||
msgid ""
|
||
"The second table is used to define attributes which map directly to data "
|
||
"stored in the instance. A variety of primitive C types are supported, and "
|
||
"access may be read-only or read-write. The structures in the table are "
|
||
"defined as::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1199
|
||
msgid ""
|
||
"For each entry in the table, a :term:`descriptor` will be constructed and "
|
||
"added to the type which will be able to extract a value from the instance "
|
||
"structure. The :attr:`type` field should contain one of the type codes "
|
||
"defined in the :file:`structmember.h` header; the value will be used to "
|
||
"determine how to convert Python values to and from C values. The :attr:"
|
||
"`flags` field is used to store flags which control how the attribute can be "
|
||
"accessed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1206
|
||
msgid "XXX Need to move some of this to a shared section!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1208
|
||
msgid ""
|
||
"The following flag constants are defined in :file:`structmember.h`; they may "
|
||
"be combined using bitwise-OR."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1212
|
||
msgid "Constant"
|
||
msgstr "Constante"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1212
|
||
msgid "Meaning"
|
||
msgstr "Signification"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1214
|
||
msgid ":const:`READONLY`"
|
||
msgstr ":const:`READONLY`"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1214
|
||
msgid "Never writable."
|
||
msgstr "Jamais disponible en écriture."
|
||
|
||
#: ../Doc/extending/newtypes.rst:1216
|
||
msgid ":const:`RO`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1216
|
||
msgid "Shorthand for :const:`READONLY`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1218
|
||
msgid ":const:`READ_RESTRICTED`"
|
||
msgstr ":const:`READ_RESTRICTED`"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1218
|
||
msgid "Not readable in restricted mode."
|
||
msgstr "Non disponible en lecture, dans le mode restreint."
|
||
|
||
#: ../Doc/extending/newtypes.rst:1220
|
||
msgid ":const:`WRITE_RESTRICTED`"
|
||
msgstr ":const:`WRITE_RESTRICTED`"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1220
|
||
msgid "Not writable in restricted mode."
|
||
msgstr "Non disponible en écriture dans le mode restreint."
|
||
|
||
#: ../Doc/extending/newtypes.rst:1222
|
||
msgid ":const:`RESTRICTED`"
|
||
msgstr ":const:`RESTRICTED`"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1222
|
||
msgid "Not readable or writable in restricted mode."
|
||
msgstr "Non disponible en lecture ou écriture, en mode restreint."
|
||
|
||
#: ../Doc/extending/newtypes.rst:1232
|
||
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 ""
|
||
"Un avantage intéressant de l'utilisation de la table :c:member:"
|
||
"`~PyTypeObject.tp_members` pour construire les descripteurs qui sont "
|
||
"utilisés à l'exécution, est que à tout attribut défini de cette façon on "
|
||
"peut associer un *docstring*, en écrivant simplement le texte dans la table. "
|
||
"Une application peut utiliser l'API d'introspection pour récupérer le "
|
||
"descripteur de l'objet de classe, et utiliser son attribut :attr:`__doc__` "
|
||
"pour renvoyer le *docstring*."
|
||
|
||
#: ../Doc/extending/newtypes.rst:1238
|
||
msgid ""
|
||
"As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry "
|
||
"with a :attr:`name` value of *NULL* is required."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1252
|
||
msgid "Type-specific Attribute Management"
|
||
msgstr "Gestion des attributs de type spécifiques"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1254
|
||
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. The value in showing "
|
||
"this is two-fold: it demonstrates how basic attribute management can be done "
|
||
"in a way that is portable to older versions of Python, and explains how the "
|
||
"handler functions are called, so that if you do need to extend their "
|
||
"functionality, you'll understand what needs to be done."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1264
|
||
msgid ""
|
||
"The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object "
|
||
"requires an attribute look-up. It is called in the same situations where "
|
||
"the :meth:`__getattr__` method of a class would be called."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1268
|
||
msgid ""
|
||
"A likely way to handle this is (1) to implement a set of functions (such as :"
|
||
"c:func:`newdatatype_getSize` and :c:func:`newdatatype_setSize` in the "
|
||
"example below), (2) provide a method table listing these functions, and (3) "
|
||
"provide a getattr function that returns the result of a lookup in that "
|
||
"table. The method table uses the same structure as the :c:member:"
|
||
"`~PyTypeObject.tp_methods` field of the type object."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1275
|
||
msgid "Here is an example::"
|
||
msgstr "Voici un exemple : ::"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1291
|
||
msgid ""
|
||
"The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:"
|
||
"`__setattr__` or :meth:`__delattr__` method of a class instance would be "
|
||
"called. When an attribute should be deleted, the third parameter will be "
|
||
"*NULL*. Here is an example that simply raises an exception; if this were "
|
||
"really all you wanted, the :c:member:`~PyTypeObject.tp_setattr` handler "
|
||
"should be set to *NULL*. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1306
|
||
msgid "Object Comparison"
|
||
msgstr "Comparaison des objets"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1312
|
||
msgid ""
|
||
"The :c:member:`~PyTypeObject.tp_compare` handler is called when comparisons "
|
||
"are needed and the object does not implement the specific rich comparison "
|
||
"method which matches the requested comparison. (It is always used if "
|
||
"defined and the :c:func:`PyObject_Compare` or :c:func:`PyObject_Cmp` "
|
||
"functions are used, or if :func:`cmp` is used from Python.) It is analogous "
|
||
"to the :meth:`__cmp__` method. This function should return ``-1`` if *obj1* "
|
||
"is less than *obj2*, ``0`` if they are equal, and ``1`` if *obj1* is greater "
|
||
"than *obj2*. (It was previously allowed to return arbitrary negative or "
|
||
"positive integers for less than and greater than, respectively; as of Python "
|
||
"2.2, this is no longer allowed. In the future, other return values may be "
|
||
"assigned a different meaning.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1323
|
||
msgid ""
|
||
"A :c:member:`~PyTypeObject.tp_compare` handler may raise an exception. In "
|
||
"this case it should return a negative value. The caller has to test for the "
|
||
"exception using :c:func:`PyErr_Occurred`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1327
|
||
msgid "Here is a sample implementation::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1350
|
||
msgid "Abstract Protocol Support"
|
||
msgstr "Support pour le protocole abstrait"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1352
|
||
msgid ""
|
||
"Python supports a variety of *abstract* 'protocols;' the specific interfaces "
|
||
"provided to use these interfaces are documented in :ref:`abstract`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1356
|
||
msgid ""
|
||
"A number of these abstract interfaces were defined early in the development "
|
||
"of the Python implementation. In particular, the number, mapping, and "
|
||
"sequence protocols have been part of Python since the beginning. Other "
|
||
"protocols have been added over time. For protocols which depend on several "
|
||
"handler routines from the type implementation, the older protocols have been "
|
||
"defined as optional blocks of handlers referenced by the type object. For "
|
||
"newer protocols there are additional slots in the main type object, with a "
|
||
"flag bit being set to indicate that the slots are present and should be "
|
||
"checked by the interpreter. (The flag bit does not indicate that the slot "
|
||
"values are non-*NULL*. The flag may be set to indicate the presence of a "
|
||
"slot, but a slot may still be unfilled.) ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1371
|
||
msgid ""
|
||
"If you wish your object to be able to act like a number, a sequence, or a "
|
||
"mapping object, then you place the address of a structure that implements "
|
||
"the C type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, or :c:"
|
||
"type:`PyMappingMethods`, respectively. It is up to you to fill in this "
|
||
"structure with appropriate values. You can find examples of the use of each "
|
||
"of these in the :file:`Objects` directory of the Python source "
|
||
"distribution. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1380
|
||
msgid ""
|
||
"This function, if you choose to provide it, should return a hash number for "
|
||
"an instance of your data type. Here is a moderately pointless example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1396
|
||
msgid ""
|
||
"This function is called when an instance of your data type is \"called\", "
|
||
"for example, if ``obj1`` is an instance of your data type and the Python "
|
||
"script contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` "
|
||
"handler is invoked."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1400
|
||
msgid "This function takes three arguments:"
|
||
msgstr "Cette fonction prend trois arguments :"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1402
|
||
msgid ""
|
||
"*arg1* is the instance of the data type which is the subject of the call. If "
|
||
"the call is ``obj1('hello')``, then *arg1* is ``obj1``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1405
|
||
msgid ""
|
||
"*arg2* is a tuple containing the arguments to the call. You can use :c:func:"
|
||
"`PyArg_ParseTuple` to extract the arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1408
|
||
msgid ""
|
||
"*arg3* is a dictionary of keyword arguments that were passed. If this is non-"
|
||
"*NULL* and you support keyword arguments, use :c:func:"
|
||
"`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do not want "
|
||
"to support keyword arguments and this is non-*NULL*, raise a :exc:"
|
||
"`TypeError` with a message saying that keyword arguments are not supported."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1414
|
||
msgid ""
|
||
"Here is a desultory example of the implementation of the call function. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1440
|
||
msgid "XXX some fields need to be added here... ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1447
|
||
msgid ""
|
||
"These functions provide support for the iterator protocol. Any object which "
|
||
"wishes to support iteration over its contents (which may be generated during "
|
||
"iteration) must implement the ``tp_iter`` handler. Objects which are "
|
||
"returned by a ``tp_iter`` handler must implement both the ``tp_iter`` and "
|
||
"``tp_iternext`` handlers. Both handlers take exactly one parameter, the "
|
||
"instance for which they are being called, and return a new reference. In "
|
||
"the case of an error, they should set an exception and return *NULL*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1455
|
||
msgid ""
|
||
"For an object which represents an iterable collection, the ``tp_iter`` "
|
||
"handler must return an iterator object. The iterator object is responsible "
|
||
"for maintaining the state of the iteration. For collections which can "
|
||
"support multiple iterators which do not interfere with each other (as lists "
|
||
"and tuples do), a new iterator should be created and returned. Objects "
|
||
"which can only be iterated over once (usually due to side effects of "
|
||
"iteration) should implement this handler by returning a new reference to "
|
||
"themselves, and should also implement the ``tp_iternext`` handler. File "
|
||
"objects are an example of such an iterator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1465
|
||
msgid ""
|
||
"Iterator objects should implement both handlers. The ``tp_iter`` handler "
|
||
"should return a new reference to the iterator (this is the same as the "
|
||
"``tp_iter`` handler for objects which can only be iterated over "
|
||
"destructively). The ``tp_iternext`` handler should return a new reference "
|
||
"to the next object in the iteration if there is one. If the iteration has "
|
||
"reached the end, it may return *NULL* without setting an exception or it may "
|
||
"set :exc:`StopIteration`; avoiding the exception can yield slightly better "
|
||
"performance. If an actual error occurs, it should set an exception and "
|
||
"return *NULL*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1478
|
||
msgid "Weak Reference Support"
|
||
msgstr "Prise en charge de la référence faible"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1480
|
||
msgid ""
|
||
"One of the goals of Python's weak-reference implementation is to allow any "
|
||
"type to participate in the weak reference mechanism without incurring the "
|
||
"overhead on those objects which do not benefit by weak referencing (such as "
|
||
"numbers)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1484
|
||
msgid ""
|
||
"For an object to be weakly referencable, the extension must include a :c:"
|
||
"type:`PyObject\\*` field in the instance structure for the use of the weak "
|
||
"reference mechanism; it must be initialized to *NULL* by the object's "
|
||
"constructor. It must also set the :c:member:`~PyTypeObject."
|
||
"tp_weaklistoffset` field of the corresponding type object to the offset of "
|
||
"the field. For example, the instance type is defined with the following "
|
||
"structure::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1498
|
||
msgid "The statically-declared type object for instances is defined this way::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1515
|
||
msgid ""
|
||
"The type constructor is responsible for initializing the weak reference list "
|
||
"to *NULL*::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1527
|
||
msgid ""
|
||
"The only further addition is that the destructor needs to call the weak "
|
||
"reference manager to clear any weak references. This is only required if "
|
||
"the weak reference list is non-*NULL*::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1546
|
||
msgid "More Suggestions"
|
||
msgstr "Plus de suggestions"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1548
|
||
msgid ""
|
||
"Remember that you can omit most of these functions, in which case you "
|
||
"provide ``0`` as a value. There are type definitions for each of the "
|
||
"functions you must provide. They are in :file:`object.h` in the Python "
|
||
"include directory that comes with the source distribution of Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1553
|
||
msgid ""
|
||
"In order to learn how to implement any specific method for your new data "
|
||
"type, do the following: Download and unpack the Python source distribution. "
|
||
"Go the :file:`Objects` directory, then search the C source files for ``tp_`` "
|
||
"plus the function you want (for example, ``tp_print`` or ``tp_compare``). "
|
||
"You will find examples of the function you want to implement."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1559
|
||
msgid ""
|
||
"When you need to verify that an object is an instance of the type you are "
|
||
"implementing, use the :c:func:`PyObject_TypeCheck` function. A sample of its "
|
||
"use might be something like the following::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1569
|
||
msgid "Footnotes"
|
||
msgstr "Notes"
|
||
|
||
#: ../Doc/extending/newtypes.rst:1570
|
||
msgid ""
|
||
"This is true when we know that the object is a basic type, like a string or "
|
||
"a float."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1573
|
||
msgid ""
|
||
"We relied on this in the :c:member:`~PyTypeObject.tp_dealloc` handler in "
|
||
"this example, because our type doesn't support garbage collection. Even if a "
|
||
"type supports garbage collection, there are calls that can be made to "
|
||
"\"untrack\" the object from garbage collection, however, these calls are "
|
||
"advanced and not covered here."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1578
|
||
msgid ""
|
||
"We now know that the first and last members are strings, so perhaps we could "
|
||
"be less careful about decrementing their reference counts, however, we "
|
||
"accept instances of string subclasses. Even though deallocating normal "
|
||
"strings won't call back into our objects, we can't guarantee that "
|
||
"deallocating an instance of a string subclass won't call back into our "
|
||
"objects."
|
||
msgstr ""
|
||
|
||
#: ../Doc/extending/newtypes.rst:1584
|
||
msgid ""
|
||
"Even in the third version, we aren't guaranteed to avoid cycles. Instances "
|
||
"of string subclasses are allowed and string subclasses could allow cycles "
|
||
"even if normal strings don't."
|
||
msgstr ""
|