# SOME DESCRIPTIVE TITLE. # Copyright (C) 2001-2018, Python Software Foundation # This file is distributed under the same license as the Python package. # FIRST AUTHOR , 2018. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Python 3.6\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2018-05-26 11:10+0900\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" "Generated-By: Babel 2.5.1\n" #: ../Doc/extending/newtypes_tutorial.rst:7 msgid "Defining Extension Types: Tutorial" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:14 msgid "" "Python allows the writer of a C extension module to define new types that" " can be manipulated from Python code, much like the built-in :class:`str`" " and :class:`list` types. The code for all extension types follows a " "pattern, but there are some details that you need to understand before " "you can get started. This document is a gentle introduction to the " "topic." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:24 msgid "The Basics" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:26 msgid "" "The :term:`CPython` runtime sees all Python objects as variables of type " ":c:type:`PyObject\\*`, which serves as a \"base type\" for all Python " "objects. The :c:type:`PyObject` structure itself only contains the " "object's :term:`reference count` and a pointer to the object's \"type " "object\". This is where the action is; the type object determines which " "(C) functions get called by the interpreter when, for instance, an " "attribute gets looked up on an object, a method called, or it is " "multiplied by another object. These C functions are called \"type " "methods\"." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:35 msgid "" "So, if you want to define a new extension type, you need to create a new " "type object." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:38 msgid "" "This sort of thing can only be explained by example, so here's a minimal," " but complete, module that defines a new type named :class:`Custom` " "inside a C extension module :mod:`custom`:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:43 msgid "" "What we're showing here is the traditional way of defining *static* " "extension types. It should be adequate for most uses. The C API also " "allows defining heap-allocated extension types using the " ":c:func:`PyType_FromSpec` function, which isn't covered in this tutorial." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:50 msgid "" "Now that's quite a bit to take in at once, but hopefully bits will seem " "familiar from the previous chapter. This file defines three things:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:53 msgid "" "What a :class:`Custom` **object** contains: this is the ``CustomObject`` " "struct, which is allocated once for each :class:`Custom` instance." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:55 msgid "" "How the :class:`Custom` **type** behaves: this is the ``CustomType`` " "struct, which defines a set of flags and function pointers that the " "interpreter inspects when specific operations are requested." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:58 msgid "" "How to initialize the :mod:`custom` module: this is the ``PyInit_custom``" " function and the associated ``custommodule`` struct." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:61 msgid "The first bit is::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:67 msgid "" "This is what a Custom object will contain. ``PyObject_HEAD`` is " "mandatory at the start of each object struct and defines a field called " "``ob_base`` of type :c:type:`PyObject`, containing a pointer to a type " "object and a reference count (these can be accessed using the macros " ":c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE` respectively). The reason " "for the macro is to abstract away the layout and to enable additional " "fields in debug builds." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:75 msgid "" "There is no semicolon above after the :c:macro:`PyObject_HEAD` macro. Be " "wary of adding one by accident: some compilers will complain." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:78 msgid "" "Of course, objects generally store additional data besides the standard " "``PyObject_HEAD`` boilerplate; for example, here is the definition for " "standard Python floats::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:87 msgid "The second bit is the definition of the type object. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:99 msgid "" "We recommend using C99-style designated initializers as above, to avoid " "listing all the :c:type:`PyTypeObject` fields that you don't care about " "and also to avoid caring about the fields' declaration order." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:103 msgid "" "The actual definition of :c:type:`PyTypeObject` in :file:`object.h` has " "many more :ref:`fields ` than 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_tutorial.rst:108 msgid "We're going to pick it apart, one field at a time::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:112 msgid "" "This line is mandatory boilerplate to initialize the ``ob_base`` field " "mentioned above. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:117 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_tutorial.rst:127 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:`custom` and the type is :class:`Custom`, so we set the type name to" " :class:`custom.Custom`. Using the real dotted import path is important " "to make your type compatible with the :mod:`pydoc` and :mod:`pickle` " "modules. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:136 msgid "" "This is so that Python knows how much memory to allocate when creating " "new :class:`Custom` instances. :c:member:`~PyTypeObject.tp_itemsize` is " "only used for variable-sized objects and should otherwise be zero." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:142 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_tutorial.rst:152 msgid "We set the class flags to :const:`Py_TPFLAGS_DEFAULT`. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:156 msgid "" "All types should include this constant in their flags. It enables all of" " the members defined until at least Python 3.3. If you need further " "members, you will need to OR the corresponding flags." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:160 msgid "" "We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`." " ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:164 msgid "" "To enable object creation, we have to provide a " ":c:member:`~PyTypeObject.tp_new` handler. This is the equivalent of the " "Python method :meth:`__new__`, but has to be specified explicitly. In " "this case, we can just use the default implementation provided by the API" " function :c:func:`PyType_GenericNew`. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:171 msgid "" "Everything else in the file should be familiar, except for some code in " ":c:func:`PyInit_custom`::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:177 msgid "" "This initializes the :class:`Custom` type, filling in a number of members" " to the appropriate default values, including :attr:`ob_type` that we " "initially set to *NULL*. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:183 msgid "" "This adds the type to the module dictionary. This allows us to create " ":class:`Custom` instances by calling the :class:`Custom` class:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:191 msgid "" "That's it! All that remains is to build it; put the above code in a file" " called :file:`custom.c` and:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:200 msgid "in a file called :file:`setup.py`; then typing" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:206 msgid "" "at a shell should produce a file :file:`custom.so` in a subdirectory; " "move to that directory and fire up Python --- you should be able to " "``import custom`` and play around with Custom objects." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:210 msgid "That wasn't so hard, was it?" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:212 msgid "" "Of course, the current Custom type is pretty uninteresting. It has no " "data and doesn't do anything. It can't even be subclassed." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:216 msgid "" "While this documentation showcases the standard :mod:`distutils` module " "for building C extensions, it is recommended in real-world use cases to " "use the newer and better-maintained ``setuptools`` library. " "Documentation on how to do this is out of scope for this document and can" " be found in the `Python Packaging User's Guide " "`_." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:224 msgid "Adding data and methods to the Basic example" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:226 msgid "" "Let's extend the basic example to add some data and methods. Let's also " "make the type usable as a base class. We'll create a new module, " ":mod:`custom2` that adds these capabilities:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:233 msgid "This version of the module has a number of changes." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:235 msgid "We've added an extra include::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:239 msgid "" "This include provides declarations that we use to handle attributes, as " "described a bit later." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:242 msgid "" "The :class:`Custom` type now has three data attributes in its C struct, " "*first*, *last*, and *number*. The *first* and *last* variables are " "Python strings containing first and last names. The *number* attribute " "is a C integer." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:246 msgid "The object structure is updated accordingly::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:255 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_tutorial.rst:266 msgid "which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:270 msgid "" "This method first clears the reference counts of the two Python " "attributes. :c:func:`Py_XDECREF` correctly handles the case where its " "argument is *NULL* (which might happen here if ``tp_new`` failed midway)." " It then calls the :c:member:`~PyTypeObject.tp_free` member of the " "object's type (computed by ``Py_TYPE(self)``) to free the object's " "memory. Note that the object's type might not be :class:`CustomType`, " "because the object may be an instance of a subclass." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:279 msgid "" "The explicit cast to ``destructor`` above is needed because we defined " "``Custom_dealloc`` to take a ``CustomObject *`` argument, but the " "``tp_dealloc`` function pointer expects to receive a ``PyObject *`` " "argument. Otherwise, the compiler will emit a warning. This is object-" "oriented polymorphism, in C!" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:285 msgid "" "We want to make sure that the first and last names are initialized to " "empty strings, so we provide a ``tp_new`` implementation::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:309 msgid "and install it in the :c:member:`~PyTypeObject.tp_new` member::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:313 msgid "" "The ``tp_new`` handler is responsible for creating (as opposed to " "initializing) objects of the type. It is exposed in Python as the " ":meth:`__new__` method. It is not required to define a ``tp_new`` member," " and indeed many extension types will simply reuse " ":c:func:`PyType_GenericNew` as done in the first version of the " "``Custom`` type above. In this case, we use the ``tp_new`` handler to " "initialize the ``first`` and ``last`` attributes to non-*NULL* default " "values." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:321 msgid "" "``tp_new`` is passed the type being instantiated (not necessarily " "``CustomType``, if a subclass is instantiated) and any arguments passed " "when the type was called, and is expected to return the instance created." " ``tp_new`` handlers always accept positional and keyword arguments, but" " they often ignore the arguments, leaving the argument handling to " "initializer (a.k.a. ``tp_init`` in C or ``__init__`` in Python) methods." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:329 msgid "" "``tp_new`` shouldn't call ``tp_init`` explicitly, as the interpreter will" " do it itself." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:332 msgid "" "The ``tp_new`` implementation calls the " ":c:member:`~PyTypeObject.tp_alloc` slot to allocate memory::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:337 msgid "" "Since memory allocation may fail, we must check the " ":c:member:`~PyTypeObject.tp_alloc` result against *NULL* before " "proceeding." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:341 msgid "" "We didn'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 strategy." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:347 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_tutorial.rst:357 msgid "" "We also define an initialization function which accepts arguments to " "provide initial values for our instance::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:386 msgid "by filling the :c:member:`~PyTypeObject.tp_init` slot. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:390 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. Initializers always accept positional and keyword arguments, " "and they should return either ``0`` on success or ``-1`` on error." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:395 msgid "" "Unlike the ``tp_new`` handler, there is no guarantee that ``tp_init`` is " "called at all (for example, the :mod:`pickle` module by default doesn't " "call :meth:`__init__` on unpickled instances). It can also 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 attribute values. We might be tempted, for example to assign the " "``first`` member like this::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:409 msgid "" "But this would be risky. Our type doesn't restrict the type of the " "``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 " "``first`` member; or that destructor could release the :term:`Global " "interpreter Lock` and let arbitrary code run in other threads that " "accesses and modifies our object." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:416 msgid "" "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_tutorial.rst:420 msgid "when we absolutely know that the reference count is greater than 1;" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:422 msgid "" "when we know that deallocation of the object [#]_ will neither release " "the :term:`GIL` nor cause any calls back into our type's code;" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:425 msgid "" "when decrementing a reference count in a " ":c:member:`~PyTypeObject.tp_dealloc` handler on a type which doesn't " "support cyclic garbage collection [#]_." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:428 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_tutorial.rst:441 msgid "and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:445 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_tutorial.rst:449 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_tutorial.rst:456 msgid "" "We define a single method, :meth:`Custom.name()`, that outputs the " "objects name as the concatenation of the first and last names. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:473 msgid "" "The method is implemented as a C function that takes a :class:`Custom` " "(or :class:`Custom` subclass) instance as the first argument. Methods " "always take an instance as the first argument. Methods often take " "positional and keyword arguments as well, but in this case we don't take " "any and don't need to accept a positional argument tuple or keyword " "argument dictionary. This method is equivalent to the Python method:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:485 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_tutorial.rst:491 msgid "" "Now that we've defined the method, we need to create an array of method " "definitions::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:501 msgid "" "(note that we used the :const:`METH_NOARGS` flag to indicate that the " "method is expecting no arguments other than *self*)" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:504 msgid "and assign it to the :c:member:`~PyTypeObject.tp_methods` slot::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:508 msgid "" "Finally, we'll make our type usable as a base class for subclassing. " "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_tutorial.rst:515 msgid "" "We rename :c:func:`PyInit_custom` to :c:func:`PyInit_custom2`, update the" " module name in the :c:type:`PyModuleDef` struct, and update the full " "class name in the :c:type:`PyTypeObject` struct." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:519 msgid "Finally, we update our :file:`setup.py` file to build the new module:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:532 msgid "Providing finer control over data attributes" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:534 msgid "" "In this section, we'll provide finer control over how the :attr:`first` " "and :attr:`last` attributes are set in the :class:`Custom` 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_tutorial.rst:543 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_tutorial.rst:574 msgid "" "The getter function is passed a :class:`Custom` object and a \"closure\"," " which is a 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_tutorial.rst:580 msgid "" "The setter function is passed the :class:`Custom` 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 its new value is not a string." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:585 msgid "We create an array of :c:type:`PyGetSetDef` structures::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:595 msgid "and register it in the :c:member:`~PyTypeObject.tp_getset` slot::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:599 msgid "" "The last item in a :c:type:`PyGetSetDef` structure is the \"closure\" " "mentioned above. In this case, we aren't using a closure, so we just " "pass *NULL*." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:602 msgid "We also remove the member definitions for these attributes::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:610 msgid "" "We also need to update the :c:member:`~PyTypeObject.tp_init` handler to " "only allow strings [#]_ to be passed::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:639 msgid "" "With these changes, we can assure that the ``first`` and ``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 ``tp_dealloc`` implementation, where there is the " "possibility that the initialization of these members failed in " "``tp_new``." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:646 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_tutorial.rst:652 msgid "Supporting cyclic garbage collection" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:654 msgid "" "Python has a :term:`cyclic garbage collector (GC) ` " "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_tutorial.rst:664 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_tutorial.rst:669 msgid "" "In the second version of the :class:`Custom` example, we allowed any kind" " of object to be stored in the :attr:`first` or :attr:`last` attributes " "[#]_. Besides, in the second and third versions, we allowed subclassing " ":class:`Custom`, and subclasses may add arbitrary attributes. For any of" " those two reasons, :class:`Custom` objects can participate in cycles:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:683 msgid "" "To allow a :class:`Custom` instance participating in a reference cycle to" " be properly detected and collected by the cyclic GC, our :class:`Custom`" " type needs to fill two additional slots and to enable a flag that " "enables these slots:" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:690 msgid "" "First, the traversal method lets the cyclic GC know about subobjects that" " could participate in cycles::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:710 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_tutorial.rst:716 msgid "" "Python provides a :c:func:`Py_VISIT` macro that automates calling visit " "functions. With :c:func:`Py_VISIT`, we can minimize the amount of " "boilerplate in ``Custom_traverse``::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:729 msgid "" "The :c:member:`~PyTypeObject.tp_traverse` implementation must name its " "arguments exactly *visit* and *arg* in order to use :c:func:`Py_VISIT`." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:732 msgid "" "Second, we need to provide a method for clearing any subobjects that can " "participate in cycles::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:743 msgid "" "Notice the use of the :c:func:`Py_CLEAR` macro. It is the recommended " "and safe way to clear data attributes of arbitrary types while " "decrementing their reference counts. If you were to call " ":c:func:`Py_XDECREF` instead on the attribute before setting it to " "*NULL*, there is a possibility that the attribute's destructor would call" " back into code that reads the attribute again (*especially* if there is " "a reference cycle)." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:751 msgid "You could emulate :c:func:`Py_CLEAR` by writing::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:758 msgid "" "Nevertheless, it is much easier and less error-prone to always use " ":c:func:`Py_CLEAR` when deleting an attribute. Don't try to micro-" "optimize at the expense of robustness!" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:762 msgid "" "The deallocator ``Custom_dealloc`` may call arbitrary code when clearing " "attributes. It means the circular GC can be triggered inside the " "function. Since the GC assumes reference count is not zero, we need to " "untrack the object from the GC by calling :c:func:`PyObject_GC_UnTrack` " "before clearing members. Here is our reimplemented deallocator using " ":c:func:`PyObject_GC_UnTrack` and ``Custom_clear``::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:777 msgid "Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:781 msgid "" "That's pretty much it. If we had written custom " ":c:member:`~PyTypeObject.tp_alloc` or :c:member:`~PyTypeObject.tp_free` " "handlers, we'd need to modify them for cyclic garbage collection. Most " "extensions will use the versions automatically provided." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:787 msgid "Subclassing other types" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:789 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 :c:type:`PyTypeObject` it needs. It can " "be difficult to share these :c:type:`PyTypeObject` structures between " "extension modules." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:794 msgid "" "In this example we will create a :class:`SubList` 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_tutorial.rst:814 msgid "" "As you can see, the source code closely resembles the :class:`Custom` " "examples in previous sections. We will break down the main differences " "between them. ::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:822 msgid "" "The primary difference for derived type objects is that the base type's " "object structure must be the first value. The base type will already " "include the :c:func:`PyObject_HEAD` at the beginning of its structure." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:826 msgid "" "When a Python object is a :class:`SubList` instance, its ``PyObject *`` " "pointer can be safely cast to both ``PyListObject *`` and ``SubListObject" " *``::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:838 msgid "" "We see above how to call through to the :attr:`__init__` method of the " "base type." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:841 msgid "" "This pattern is important when writing a type with custom " ":c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_dealloc`" " members. The :c:member:`~PyTypeObject.tp_new` handler should not " "actually create the memory for the object with its " ":c:member:`~PyTypeObject.tp_alloc`, but let the base class handle it by " "calling its own :c:member:`~PyTypeObject.tp_new`." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:847 msgid "" "The :c:type:`PyTypeObject` struct supports a " ":c:member:`~PyTypeObject.tp_base` specifying the type's concrete base " "class. Due to cross-platform compiler issues, you can't fill that field " "directly with a reference to :c:type:`PyList_Type`; it should be done " "later in the module initialization function::" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:870 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 " "an existing type, it is not necessary to fill out the " ":c:member:`~PyTypeObject.tp_alloc` slot with :c:func:`PyType_GenericNew` " "-- the allocation function from the base type will be inherited." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:876 msgid "" "After that, calling :c:func:`PyType_Ready` and adding the type object to " "the module is the same as with the basic :class:`Custom` examples." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:881 msgid "Footnotes" msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:882 msgid "" "This is true when we know that the object is a basic type, like a string " "or a float." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:885 msgid "" "We relied on this in the :c:member:`~PyTypeObject.tp_dealloc` handler in " "this example, because our type doesn't support garbage collection." msgstr "" #: ../Doc/extending/newtypes_tutorial.rst:888 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_tutorial.rst:894 msgid "" "Also, even with our attributes restricted to strings instances, the user " "could pass arbitrary :class:`str` subclasses and therefore still create " "reference cycles." msgstr ""