# SOME DESCRIPTIVE TITLE.

# Copyright (C) 1990-2020, Python Software Foundation

# This file is distributed under the same license as the Python package.

#

# Translators:

msgid ""

msgstr ""

"Project-Id-Version: Python 2.7\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2020-02-09 18:46+0900\n"

"PO-Revision-Date: 2020-02-29 01:48+0000\n"

"Last-Translator: Marco Rougeth <marco@rougeth.com>\n"

"Language-Team: Portuguese (Brazil) (http://www.transifex.com/python-doc/python-27/language/pt_BR/)\n"

"Language: pt_BR\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Plural-Forms: nplurals=2; plural=(n > 1);\n"

#: ../../extending/newtypes.rst:8

msgid "Defining New Types"

msgstr "Definindo Novos Tipos"

#: ../../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 ""

#: ../../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 ""

#: ../../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 ""

#: ../../extending/newtypes.rst:34

msgid "The Basics"

msgstr "O básico"

#: ../../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 ""

#: ../../extending/newtypes.rst:43

msgid ""

"So, if you want to define a new object type, you need to create a new type "

"object."

msgstr ""

#: ../../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 ""

#: ../../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 ""

#: ../../extending/newtypes.rst:55

msgid "The first bit that will be new is::"

msgstr ""

#: ../../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 ""

#: ../../extending/newtypes.rst:71

msgid ""

"For contrast, let's take a look at the corresponding definition for standard"

" Python integers::"

msgstr ""

#: ../../extending/newtypes.rst:79

msgid "Moving on, we come to the crunch --- the type object. ::"

msgstr ""

#: ../../extending/newtypes.rst:105

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 ""

#: ../../extending/newtypes.rst:110

msgid ""

"This is so important that we're going to pick the top of it apart still "

"further::"

msgstr ""

#: ../../extending/newtypes.rst:115

msgid "This line is a bit of a wart; what we'd like to write is::"

msgstr ""

#: ../../extending/newtypes.rst:119

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 ""

#: ../../extending/newtypes.rst:125

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 ""

#: ../../extending/newtypes.rst:133

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 ""

#: ../../extending/newtypes.rst:141

msgid ""

"This is so that Python knows how much memory to allocate when you call "

":c:func:`PyObject_New`."

msgstr ""

#: ../../extending/newtypes.rst:146

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 ""

#: ../../extending/newtypes.rst:160

msgid ""

"This has to do with variable length objects like lists and strings. Ignore "

"this for now."

msgstr ""

#: ../../extending/newtypes.rst:163

msgid ""

"Skipping a number of type methods that we don't provide, we set the class "

"flags to :const:`Py_TPFLAGS_DEFAULT`. ::"

msgstr ""

#: ../../extending/newtypes.rst:168

msgid ""

"All types should include this constant in their flags. It enables all of "

"the members defined by the current version of Python."

msgstr ""

#: ../../extending/newtypes.rst:171

msgid ""

"We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::"

msgstr ""

#: ../../extending/newtypes.rst:175

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 ""

#: ../../extending/newtypes.rst:179

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 ""

#: ../../extending/newtypes.rst:193

msgid ""

"All the other type methods are *NULL*, so we'll go over them later --- "

"that's for a later section!"

msgstr ""

#: ../../extending/newtypes.rst:196

msgid ""

"Everything else in the file should be familiar, except for some code in "

":c:func:`initnoddy`::"

msgstr ""

#: ../../extending/newtypes.rst:202

msgid ""

"This initializes the :class:`Noddy` type, filing in a number of members, "

"including :attr:`ob_type` that we initially set to *NULL*. ::"

msgstr ""

#: ../../extending/newtypes.rst:207

msgid ""

"This adds the type to the module dictionary. This allows us to create "

":class:`Noddy` instances by calling the :class:`Noddy` class::"

msgstr ""

#: ../../extending/newtypes.rst:213

msgid ""

"That's it! All that remains is to build it; put the above code in a file "

"called :file:`noddy.c` and ::"

msgstr ""

#: ../../extending/newtypes.rst:220

msgid "in a file called :file:`setup.py`; then typing"

msgstr ""

#: ../../extending/newtypes.rst:226

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 ""

#: ../../extending/newtypes.rst:230

msgid "That wasn't so hard, was it?"

msgstr "Isso não foi tão difícil, foi?"

#: ../../extending/newtypes.rst:232

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 ""

#: ../../extending/newtypes.rst:237

msgid "Adding data and methods to the Basic example"

msgstr "Adicionando dados e métodos ao exemplo básico"

#: ../../extending/newtypes.rst:239

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:`noddy2` that adds these capabilities:"

msgstr ""

#: ../../extending/newtypes.rst:246

msgid "This version of the module has a number of changes."

msgstr "Esta versão do módulo possui várias alterações."

#: ../../extending/newtypes.rst:248

msgid "We've added an extra include::"

msgstr "Nós adicionamos uma inclusão extra ::"

#: ../../extending/newtypes.rst:252

msgid ""

"This include provides declarations that we use to handle attributes, as "

"described a bit later."

msgstr ""

"Esta inclusão fornece declarações que usamos para manipular atributos, "

"conforme descrito um pouco mais tarde."

#: ../../extending/newtypes.rst:255

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 ""

#: ../../extending/newtypes.rst:258

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 ""

#: ../../extending/newtypes.rst:262

msgid "The object structure is updated accordingly::"

msgstr "A estrutura do objeto é atualizada de acordo ::"

#: ../../extending/newtypes.rst:271

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 ""

#: ../../extending/newtypes.rst:282

msgid "which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::"

msgstr ""

#: ../../extending/newtypes.rst:286

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 ""

#: ../../extending/newtypes.rst:292

msgid ""

"We want to make sure that the first and last names are initialized to empty "

"strings, so we provide a new method::"

msgstr ""

#: ../../extending/newtypes.rst:322

msgid "and install it in the :c:member:`~PyTypeObject.tp_new` member::"

msgstr ""

#: ../../extending/newtypes.rst:326

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 ""

#: ../../extending/newtypes.rst:337

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 ""

#: ../../extending/newtypes.rst:349

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 ""

#: ../../extending/newtypes.rst:358

msgid "We provide an initialization function::"

msgstr ""

#: ../../extending/newtypes.rst:389

msgid "by filling the :c:member:`~PyTypeObject.tp_init` slot. ::"

msgstr ""

#: ../../extending/newtypes.rst:393

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 ""

#: ../../extending/newtypes.rst:400

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 ""

#: ../../extending/newtypes.rst:411

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 ""

#: ../../extending/newtypes.rst:418

msgid "when we absolutely know that the reference count is greater than 1"

msgstr ""

#: ../../extending/newtypes.rst:420

msgid ""

"when we know that deallocation of the object [#]_ will not cause any calls "

"back into our type's code"

msgstr ""

#: ../../extending/newtypes.rst:423

msgid ""

"when decrementing a reference count in a "

":c:member:`~PyTypeObject.tp_dealloc` handler when garbage-collections is not"

" supported [#]_"

msgstr ""

#: ../../extending/newtypes.rst:426

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 ""

#: ../../extending/newtypes.rst:439

msgid ""

"and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::"

msgstr ""

#: ../../extending/newtypes.rst:443

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 ""

#: ../../extending/newtypes.rst:447

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 ""

#: ../../extending/newtypes.rst:454

msgid ""

"We define a single method, :meth:`name`, that outputs the objects name as "

"the concatenation of the first and last names. ::"

msgstr ""

#: ../../extending/newtypes.rst:489

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 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 ""

#: ../../extending/newtypes.rst:499

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 ""

#: ../../extending/newtypes.rst:505

msgid ""

"Now that we've defined the method, we need to create an array of method "

"definitions::"

msgstr ""

"Agora que definimos o método, precisamos criar uma matriz de definições de "

"métodos:"

#: ../../extending/newtypes.rst:515

msgid "and assign them to the :c:member:`~PyTypeObject.tp_methods` slot::"

msgstr ""

#: ../../extending/newtypes.rst:519

msgid ""

"Note that we used the :const:`METH_NOARGS` flag to indicate that the method "

"is passed no arguments."

msgstr ""

#: ../../extending/newtypes.rst:522

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 ""

#: ../../extending/newtypes.rst:529

msgid ""

"We rename :c:func:`initnoddy` to :c:func:`initnoddy2` and update the module "

"name passed to :c:func:`Py_InitModule3`."

msgstr ""

#: ../../extending/newtypes.rst:532

msgid "Finally, we update our :file:`setup.py` file to build the new module::"

msgstr ""

#: ../../extending/newtypes.rst:543

msgid "Providing finer control over data attributes"

msgstr "Fornecendo controle mais preciso sobre atributos de dados"

#: ../../extending/newtypes.rst:545

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 ""

#: ../../extending/newtypes.rst:554

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 ""

#: ../../extending/newtypes.rst:585

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 ""

#: ../../extending/newtypes.rst:591

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 ""

#: ../../extending/newtypes.rst:596

msgid "We create an array of :c:type:`PyGetSetDef` structures::"

msgstr ""

#: ../../extending/newtypes.rst:610

msgid "and register it in the :c:member:`~PyTypeObject.tp_getset` slot::"

msgstr "e registra isso num slot :c:member:`~PyTypeObject.tp_getset`::"

#: ../../extending/newtypes.rst:614

msgid "to register our attribute getters and setters."

msgstr ""

#: ../../extending/newtypes.rst:616

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 ""

#: ../../extending/newtypes.rst:619

msgid "We also remove the member definitions for these attributes::"

msgstr "Também removemos as definições de membros para esses atributos:"

#: ../../extending/newtypes.rst:627

msgid ""

"We also need to update the :c:member:`~PyTypeObject.tp_init` handler to only"

" allow strings [#]_ to be passed::"

msgstr ""

#: ../../extending/newtypes.rst:659

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 ""

#: ../../extending/newtypes.rst:666

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 ""

#: ../../extending/newtypes.rst:672

msgid "Supporting cyclic garbage collection"

msgstr "Apoiando a coleta de lixo cíclica"

#: ../../extending/newtypes.rst:674

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 ""

#: ../../extending/newtypes.rst:682

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 ""

#: ../../extending/newtypes.rst:687

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 ""

#: ../../extending/newtypes.rst:696

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 ""

#: ../../extending/newtypes.rst:704

msgid ""

"The traversal method provides access to subobjects that could participate in"

" cycles::"

msgstr ""

#: ../../extending/newtypes.rst:726

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 ""

#: ../../extending/newtypes.rst:732

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 ""

#: ../../extending/newtypes.rst:746

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 ""

#: ../../extending/newtypes.rst:750

msgid ""

"We also need to provide a method for clearing any subobjects that can "

"participate in cycles."

msgstr ""

#: ../../extending/newtypes.rst:771

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 ""

#: ../../extending/newtypes.rst:781

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 ""

#: ../../extending/newtypes.rst:793

msgid ""

"Note that :c:func:`Noddy_dealloc` may call arbitrary functions through "

"``__del__`` method or weakref callback. It means circular GC can be "

"triggered inside the function. Since GC assumes reference count is not "

"zero, we need to untrack the object from GC by calling "

":c:func:`PyObject_GC_UnTrack` before clearing members. Here is reimplemented"

" deallocator which uses :c:func:`PyObject_GC_UnTrack` and "

":c:func:`Noddy_clear`."

msgstr ""

#: ../../extending/newtypes.rst:810

msgid ""

"Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::"

msgstr ""

#: ../../extending/newtypes.rst:814

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 ""

#: ../../extending/newtypes.rst:820

msgid "Subclassing other types"

msgstr "Subclassificando outros tipos"

#: ../../extending/newtypes.rst:822

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 ""

#: ../../extending/newtypes.rst:827

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 ""

#: ../../extending/newtypes.rst:845

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 ""

#: ../../extending/newtypes.rst:853

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 ""

#: ../../extending/newtypes.rst:857

msgid ""

"When a Python object is a :class:`Shoddy` instance, its *PyObject\\** "

"pointer can be safely cast to both *PyListObject\\** and *Shoddy\\**. ::"

msgstr ""

#: ../../extending/newtypes.rst:869

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 ""

#: ../../extending/newtypes.rst:872

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 ""

#: ../../extending/newtypes.rst:877

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 ""

#: ../../extending/newtypes.rst:899

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 ""

#: ../../extending/newtypes.rst:904

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 ""

#: ../../extending/newtypes.rst:911

msgid "Type Methods"

msgstr "Métodosw Type"

#: ../../extending/newtypes.rst:913

msgid ""

"This section aims to give a quick fly-by on the various type methods you can"

" implement and what they do."

msgstr ""

#: ../../extending/newtypes.rst:916

msgid ""

"Here is the definition of :c:type:`PyTypeObject`, with some fields only used"

" in debug builds omitted:"

msgstr ""

#: ../../extending/newtypes.rst:922

msgid ""

"Now that's a *lot* of methods. Don't worry too much though - if you have a "

"type you want to define, the chances are very good that you will only "

"implement a handful of these."

msgstr ""

#: ../../extending/newtypes.rst:926

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 ""

#: ../../extending/newtypes.rst:936

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 ""

#: ../../extending/newtypes.rst:942

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 ""

#: ../../extending/newtypes.rst:949

msgid ""

"Here you can put a string (or its address) that you want returned when the "

"Python script references ``obj.__doc__`` to retrieve the doc string."

msgstr ""

#: ../../extending/newtypes.rst:952

msgid ""

"Now we come to the basic type methods---the ones most extension types will "

"implement."

msgstr ""

#: ../../extending/newtypes.rst:957

msgid "Finalization and De-allocation"

msgstr ""

#: ../../extending/newtypes.rst:969

msgid ""

"This function is called when the reference count of the instance of your "

"type is reduced to zero and the Python interpreter wants to reclaim it. If "

"your type has memory to free or other clean-up to perform, you can put it "

"here. The object itself needs to be freed here as well. Here is an example"

" of this function::"

msgstr ""

#: ../../extending/newtypes.rst:986

msgid ""

"One important requirement of the deallocator function is that it leaves any "

"pending exceptions alone. This is important since deallocators are "

"frequently called as the interpreter unwinds the Python stack; when the "

"stack is unwound due to an exception (rather than normal returns), nothing "

"is done to protect the deallocators from seeing that an exception has "

"already been set. Any actions which a deallocator performs which may cause "

"additional Python code to be executed may detect that an exception has been "

"set. This can lead to misleading errors from the interpreter. The proper "

"way to protect against this is to save a pending exception before performing"

" the unsafe action, and restoring it when done. This can be done using the "

":c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::"

msgstr ""

#: ../../extending/newtypes.rst:1027

msgid "Object Presentation"

msgstr ""

#: ../../extending/newtypes.rst:1033

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 ""

#: ../../extending/newtypes.rst:1042

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 ""

#: ../../extending/newtypes.rst:1049

msgid ""

"The :c:member:`~PyTypeObject.tp_repr` handler should return a string object "

"containing a representation of the instance for which it is called. Here is"

" a simple example::"

msgstr ""

#: ../../extending/newtypes.rst:1060

msgid ""

"If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the "

"interpreter will supply a representation that uses the type's "

":c:member:`~PyTypeObject.tp_name` and a uniquely-identifying value for the "

"object."

msgstr ""

#: ../../extending/newtypes.rst:1064

msgid ""

"The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what the "

":c:member:`~PyTypeObject.tp_repr` handler described above is to "

":func:`repr`; that is, it is called when Python code calls :func:`str` on an"

" instance of your object. Its implementation is very similar to the "

":c:member:`~PyTypeObject.tp_repr` function, but the resulting string is "

"intended for human consumption. If :c:member:`~PyTypeObject.tp_str` is not "

"specified, the :c:member:`~PyTypeObject.tp_repr` handler is used instead."

msgstr ""

#: ../../extending/newtypes.rst:1071

msgid "Here is a simple example::"

msgstr ""

#: ../../extending/newtypes.rst:1080

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 ""

#: ../../extending/newtypes.rst:1086

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 ""

#: ../../extending/newtypes.rst:1090

msgid ""

"The print function receives a file object as an argument. You will likely "

"want to write to that file object."

msgstr ""

#: ../../extending/newtypes.rst:1093

msgid "Here is a sample print function::"

msgstr ""

#: ../../extending/newtypes.rst:1111

msgid "Attribute Management"

msgstr ""

#: ../../extending/newtypes.rst:1113

msgid ""

"For every object which can support attributes, the corresponding type must "

"provide the functions that control how the attributes are resolved. There "

"needs to be a function which can retrieve attributes (if any are defined), "

"and another to set attributes (if setting attributes is allowed). Removing "

"an attribute is a special case, for which the new value passed to the "

"handler is *NULL*."

msgstr ""

#: ../../extending/newtypes.rst:1119

msgid ""

"Python supports two pairs of attribute handlers; a type that supports "

"attributes only needs to implement the functions for one pair. The "

"difference is that one pair takes the name of the attribute as a "

":c:type:`char\\*`, while the other accepts a :c:type:`PyObject\\*`. Each "

"type can use whichever pair makes more sense for the implementation's "

"convenience. ::"

msgstr ""

#: ../../extending/newtypes.rst:1131

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."