forked from AFPy/python-docs-fr
1778 lines
69 KiB
Plaintext
1778 lines
69 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/c-api/typeobj.rst:6
|
|
msgid "Type Objects"
|
|
msgstr "Objets type"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:8
|
|
msgid ""
|
|
"Perhaps one of the most important structures of the Python object system is "
|
|
"the structure that defines a new type: the :c:type:`PyTypeObject` "
|
|
"structure. Type objects can be handled using any of the :c:func:`PyObject_"
|
|
"\\*` or :c:func:`PyType_\\*` functions, but do not offer much that's "
|
|
"interesting to most Python applications. These objects are fundamental to "
|
|
"how objects behave, so they are very important to the interpreter itself and "
|
|
"to any extension module that implements new types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:16
|
|
msgid ""
|
|
"Type objects are fairly large compared to most of the standard types. The "
|
|
"reason for the size is that each type object stores a large number of "
|
|
"values, mostly C function pointers, each of which implements a small part of "
|
|
"the type's functionality. The fields of the type object are examined in "
|
|
"detail in this section. The fields will be described in the order in which "
|
|
"they occur in the structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:23
|
|
msgid ""
|
|
"Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc, "
|
|
"intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, "
|
|
"freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, "
|
|
"cmpfunc, reprfunc, hashfunc"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:28
|
|
msgid ""
|
|
"The structure definition for :c:type:`PyTypeObject` can be found in :file:"
|
|
"`Include/object.h`. For convenience of reference, this repeats the "
|
|
"definition found there:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:35
|
|
msgid ""
|
|
"The type object structure extends the :c:type:`PyVarObject` structure. The :"
|
|
"attr:`ob_size` field is used for dynamic types (created by :func:"
|
|
"`type_new`, usually called from a class statement). Note that :c:data:"
|
|
"`PyType_Type` (the metatype) initializes :c:member:`~PyTypeObject."
|
|
"tp_itemsize`, which means that its instances (i.e. type objects) *must* have "
|
|
"the :attr:`ob_size` field."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:45
|
|
msgid ""
|
|
"These fields are only present when the macro ``Py_TRACE_REFS`` is defined. "
|
|
"Their initialization to *NULL* is taken care of by the "
|
|
"``PyObject_HEAD_INIT`` macro. For statically allocated objects, these "
|
|
"fields always remain *NULL*. For dynamically allocated objects, these two "
|
|
"fields are used to link the object into a doubly-linked list of *all* live "
|
|
"objects on the heap. This could be used for various debugging purposes; "
|
|
"currently the only use is to print the objects that are still alive at the "
|
|
"end of a run when the environment variable :envvar:`PYTHONDUMPREFS` is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:54
|
|
msgid "These fields are not inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:59
|
|
msgid ""
|
|
"This is the type object's reference count, initialized to ``1`` by the "
|
|
"``PyObject_HEAD_INIT`` macro. Note that for statically allocated type "
|
|
"objects, the type's instances (objects whose :attr:`ob_type` points back to "
|
|
"the type) do *not* count as references. But for dynamically allocated type "
|
|
"objects, the instances *do* count as references."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:65 ../Doc/c-api/typeobj.rst:100
|
|
#: ../Doc/c-api/typeobj.rst:128
|
|
msgid "This field is not inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:67
|
|
msgid ""
|
|
"This field used to be an :c:type:`int` type. This might require changes in "
|
|
"your code for properly supporting 64-bit systems."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:74
|
|
msgid ""
|
|
"This is the type's type, in other words its metatype. It is initialized by "
|
|
"the argument to the ``PyObject_HEAD_INIT`` macro, and its value should "
|
|
"normally be ``&PyType_Type``. However, for dynamically loadable extension "
|
|
"modules that must be usable on Windows (at least), the compiler complains "
|
|
"that this is not a valid initializer. Therefore, the convention is to pass "
|
|
"*NULL* to the ``PyObject_HEAD_INIT`` macro and to initialize this field "
|
|
"explicitly at the start of the module's initialization function, before "
|
|
"doing anything else. This is typically done like this::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:85
|
|
msgid ""
|
|
"This should be done before any instances of the type are created. :c:func:"
|
|
"`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so, initializes "
|
|
"it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1 and later "
|
|
"it is initialized to the :attr:`ob_type` field of the base class. :c:func:"
|
|
"`PyType_Ready` will not change this field if it is non-zero."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:91
|
|
msgid ""
|
|
"In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in "
|
|
"2.3 and beyond, it is inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:97
|
|
msgid ""
|
|
"For statically allocated type objects, this should be initialized to zero. "
|
|
"For dynamically allocated type objects, this field has a special internal "
|
|
"meaning."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:105
|
|
msgid ""
|
|
"Pointer to a NUL-terminated string containing the name of the type. For "
|
|
"types that are accessible as module globals, the string should be the full "
|
|
"module name, followed by a dot, followed by the type name; for built-in "
|
|
"types, it should be just the type name. If the module is a submodule of a "
|
|
"package, the full package name is part of the full module name. For "
|
|
"example, a type named :class:`T` defined in module :mod:`M` in subpackage :"
|
|
"mod:`Q` in package :mod:`P` should have the :c:member:`~PyTypeObject."
|
|
"tp_name` initializer ``\"P.Q.M.T\"``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:113
|
|
msgid ""
|
|
"For dynamically allocated type objects, this should just be the type name, "
|
|
"and the module name explicitly stored in the type dict as the value for key "
|
|
"``'__module__'``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:117
|
|
msgid ""
|
|
"For statically allocated type objects, the tp_name field should contain a "
|
|
"dot. Everything before the last dot is made accessible as the :attr:"
|
|
"`__module__` attribute, and everything after the last dot is made accessible "
|
|
"as the :attr:`~definition.__name__` attribute."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:122
|
|
msgid ""
|
|
"If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is "
|
|
"made accessible as the :attr:`~definition.__name__` attribute, and the :attr:"
|
|
"`__module__` attribute is undefined (unless explicitly set in the "
|
|
"dictionary, as explained above). This means your type will be impossible to "
|
|
"pickle. Additionally, it will not be listed in module documentations "
|
|
"created with pydoc."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:134
|
|
msgid ""
|
|
"These fields allow calculating the size in bytes of instances of the type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:136
|
|
msgid ""
|
|
"There are two kinds of types: types with fixed-length instances have a zero :"
|
|
"c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length "
|
|
"instances have a non-zero :c:member:`~PyTypeObject.tp_itemsize` field. For "
|
|
"a type with fixed-length instances, all instances have the same size, given "
|
|
"in :c:member:`~PyTypeObject.tp_basicsize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:141
|
|
msgid ""
|
|
"For a type with variable-length instances, the instances must have an :attr:"
|
|
"`ob_size` field, and the instance size is :c:member:`~PyTypeObject."
|
|
"tp_basicsize` plus N times :c:member:`~PyTypeObject.tp_itemsize`, where N is "
|
|
"the \"length\" of the object. The value of N is typically stored in the "
|
|
"instance's :attr:`ob_size` field. There are exceptions: for example, long "
|
|
"ints use a negative :attr:`ob_size` to indicate a negative number, and N is "
|
|
"``abs(ob_size)`` there. Also, the presence of an :attr:`ob_size` field in "
|
|
"the instance layout doesn't mean that the instance structure is variable-"
|
|
"length (for example, the structure for the list type has fixed-length "
|
|
"instances, yet those instances have a meaningful :attr:`ob_size` field)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:152
|
|
msgid ""
|
|
"The basic size includes the fields in the instance declared by the macro :c:"
|
|
"macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to "
|
|
"declare the instance struct) and this in turn includes the :attr:`_ob_prev` "
|
|
"and :attr:`_ob_next` fields if they are present. This means that the only "
|
|
"correct way to get an initializer for the :c:member:`~PyTypeObject."
|
|
"tp_basicsize` is to use the ``sizeof`` operator on the struct used to "
|
|
"declare the instance layout. The basic size does not include the GC header "
|
|
"size (this is new in Python 2.2; in 2.1 and 2.0, the GC header size was "
|
|
"included in :c:member:`~PyTypeObject.tp_basicsize`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:161
|
|
msgid ""
|
|
"These fields are inherited separately by subtypes. If the base type has a "
|
|
"non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to "
|
|
"set :c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a "
|
|
"subtype (though this depends on the implementation of the base type)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:166
|
|
msgid ""
|
|
"A note about alignment: if the variable items require a particular "
|
|
"alignment, this should be taken care of by the value of :c:member:"
|
|
"`~PyTypeObject.tp_basicsize`. Example: suppose a type implements an array "
|
|
"of ``double``. :c:member:`~PyTypeObject.tp_itemsize` is ``sizeof(double)``. "
|
|
"It is the programmer's responsibility that :c:member:`~PyTypeObject."
|
|
"tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the "
|
|
"alignment requirement for ``double``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:176
|
|
msgid ""
|
|
"A pointer to the instance destructor function. This function must be "
|
|
"defined unless the type guarantees that its instances will never be "
|
|
"deallocated (as is the case for the singletons ``None`` and ``Ellipsis``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:180
|
|
msgid ""
|
|
"The destructor function is called by the :c:func:`Py_DECREF` and :c:func:"
|
|
"`Py_XDECREF` macros when the new reference count is zero. At this point, "
|
|
"the instance is still in existence, but there are no references to it. The "
|
|
"destructor function should free all references which the instance owns, free "
|
|
"all memory buffers owned by the instance (using the freeing function "
|
|
"corresponding to the allocation function used to allocate the buffer), and "
|
|
"finally (as its last action) call the type's :c:member:`~PyTypeObject."
|
|
"tp_free` function. If the type is not subtypable (doesn't have the :const:"
|
|
"`Py_TPFLAGS_BASETYPE` flag bit set), it is permissible to call the object "
|
|
"deallocator directly instead of via :c:member:`~PyTypeObject.tp_free`. The "
|
|
"object deallocator should be the one used to allocate the instance; this is "
|
|
"normally :c:func:`PyObject_Del` if the instance was allocated using :c:func:"
|
|
"`PyObject_New` or :c:func:`PyObject_VarNew`, or :c:func:`PyObject_GC_Del` if "
|
|
"the instance was allocated using :c:func:`PyObject_GC_New` or :c:func:"
|
|
"`PyObject_GC_NewVar`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:195 ../Doc/c-api/typeobj.rst:224
|
|
#: ../Doc/c-api/typeobj.rst:288 ../Doc/c-api/typeobj.rst:356
|
|
#: ../Doc/c-api/typeobj.rst:374 ../Doc/c-api/typeobj.rst:764
|
|
#: ../Doc/c-api/typeobj.rst:782 ../Doc/c-api/typeobj.rst:875
|
|
#: ../Doc/c-api/typeobj.rst:886 ../Doc/c-api/typeobj.rst:971
|
|
msgid "This field is inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:200
|
|
msgid "An optional pointer to the instance print function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:202
|
|
msgid ""
|
|
"The print function is only called when the instance is printed to a *real* "
|
|
"file; when it is printed to a pseudo-file (like a :class:`~StringIO."
|
|
"StringIO` instance), the instance's :c:member:`~PyTypeObject.tp_repr` or :c:"
|
|
"member:`~PyTypeObject.tp_str` function is called to convert it to a string. "
|
|
"These are also called when the type's :c:member:`~PyTypeObject.tp_print` "
|
|
"field is *NULL*. A type should never implement :c:member:`~PyTypeObject."
|
|
"tp_print` in a way that produces different output than :c:member:"
|
|
"`~PyTypeObject.tp_repr` or :c:member:`~PyTypeObject.tp_str` would."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:209
|
|
msgid ""
|
|
"The print function is called with the same signature as :c:func:"
|
|
"`PyObject_Print`: ``int tp_print(PyObject *self, FILE *file, int flags)``. "
|
|
"The *self* argument is the instance to be printed. The *file* argument is "
|
|
"the stdio file to which it is to be printed. The *flags* argument is "
|
|
"composed of flag bits. The only flag bit currently defined is :const:"
|
|
"`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW` flag bit is set, the instance "
|
|
"should be printed the same way as :c:member:`~PyTypeObject.tp_str` would "
|
|
"format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance "
|
|
"should be printed the same was as :c:member:`~PyTypeObject.tp_repr` would "
|
|
"format it. It should return ``-1`` and set an exception condition when an "
|
|
"error occurred during the comparison."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:220
|
|
msgid ""
|
|
"It is possible that the :c:member:`~PyTypeObject.tp_print` field will be "
|
|
"deprecated. In any case, it is recommended not to define :c:member:"
|
|
"`~PyTypeObject.tp_print`, but instead to rely on :c:member:`~PyTypeObject."
|
|
"tp_repr` and :c:member:`~PyTypeObject.tp_str` for printing."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:229
|
|
msgid "An optional pointer to the get-attribute-string function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:231
|
|
msgid ""
|
|
"This field is deprecated. When it is defined, it should point to a function "
|
|
"that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, "
|
|
"but taking a C string instead of a Python string object to give the "
|
|
"attribute name. The signature is the same as for :c:func:"
|
|
"`PyObject_GetAttrString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:236
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_getattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_getattr` "
|
|
"and :c:member:`~PyTypeObject.tp_getattro` from its base type when the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject."
|
|
"tp_getattro` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:243
|
|
msgid "An optional pointer to the set-attribute-string function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:245
|
|
msgid ""
|
|
"This field is deprecated. When it is defined, it should point to a function "
|
|
"that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, "
|
|
"but taking a C string instead of a Python string object to give the "
|
|
"attribute name. The signature is the same as for :c:func:"
|
|
"`PyObject_SetAttrString`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:250
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_setattro`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` "
|
|
"and :c:member:`~PyTypeObject.tp_setattro` from its base type when the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject."
|
|
"tp_setattro` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:257
|
|
msgid "An optional pointer to the three-way comparison function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:259
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_Compare`. The function "
|
|
"should return ``1`` if *self* greater than *other*, ``0`` if *self* is equal "
|
|
"to *other*, and ``-1`` if *self* less than *other*. It should return ``-1`` "
|
|
"and set an exception condition when an error occurred during the comparison."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:264
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`: a subtypes inherits "
|
|
"all three of :c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject."
|
|
"tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash` when the subtype's :c:"
|
|
"member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject.tp_richcompare`, "
|
|
"and :c:member:`~PyTypeObject.tp_hash` are all *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:274
|
|
msgid ""
|
|
"An optional pointer to a function that implements the built-in function :"
|
|
"func:`repr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:277
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_Repr`; it must return a "
|
|
"string or a Unicode object. Ideally, this function should return a string "
|
|
"that, when passed to :func:`eval`, given a suitable environment, returns an "
|
|
"object with the same value. If this is not feasible, it should return a "
|
|
"string starting with ``'<'`` and ending with ``'>'`` from which both the "
|
|
"type and the value of the object can be deduced."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:284
|
|
msgid ""
|
|
"When this field is not set, a string of the form ``<%s object at %p>`` is "
|
|
"returned, where ``%s`` is replaced by the type name, and ``%p`` by the "
|
|
"object's memory address."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:292
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement the number protocol. These fields are documented "
|
|
"in :ref:`number-structs`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:296
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the "
|
|
"contained fields are inherited individually."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:302
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement the sequence protocol. These fields are documented "
|
|
"in :ref:`sequence-structs`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:306
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the "
|
|
"contained fields are inherited individually."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:312
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement the mapping protocol. These fields are documented "
|
|
"in :ref:`mapping-structs`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:316
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the "
|
|
"contained fields are inherited individually."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:324
|
|
msgid ""
|
|
"An optional pointer to a function that implements the built-in function :"
|
|
"func:`hash`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:327
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_Hash`; it must return a C "
|
|
"long. The value ``-1`` should not be returned as a normal return value; "
|
|
"when an error occurs during the computation of the hash value, the function "
|
|
"should set an exception and return ``-1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:332
|
|
msgid ""
|
|
"This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to "
|
|
"block inheritance of the hash method from a parent type. This is interpreted "
|
|
"as the equivalent of ``__hash__ = None`` at the Python level, causing "
|
|
"``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note "
|
|
"that the converse is also true - setting ``__hash__ = None`` on a class at "
|
|
"the Python level will result in the ``tp_hash`` slot being set to :c:func:"
|
|
"`PyObject_HashNotImplemented`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:340
|
|
msgid ""
|
|
"When this field is not set, two possibilities exist: if the :c:member:"
|
|
"`~PyTypeObject.tp_compare` and :c:member:`~PyTypeObject.tp_richcompare` "
|
|
"fields are both *NULL*, a default hash value based on the object's address "
|
|
"is returned; otherwise, a :exc:`TypeError` is raised."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:344
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_richcompare` and :c:member:`~PyTypeObject.tp_compare`: a subtypes "
|
|
"inherits all three of :c:member:`~PyTypeObject.tp_compare`, :c:member:"
|
|
"`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash`, when "
|
|
"the subtype's :c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject."
|
|
"tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are all *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:352
|
|
msgid ""
|
|
"An optional pointer to a function that implements calling the object. This "
|
|
"should be *NULL* if the object is not callable. The signature is the same "
|
|
"as for :c:func:`PyObject_Call`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:361
|
|
msgid ""
|
|
"An optional pointer to a function that implements the built-in operation :"
|
|
"func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls "
|
|
"the constructor for that type. This constructor calls :c:func:"
|
|
"`PyObject_Str` to do the actual work, and :c:func:`PyObject_Str` will call "
|
|
"this handler.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:366
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_Str`; it must return a "
|
|
"string or a Unicode object. This function should return a \"friendly\" "
|
|
"string representation of the object, as this is the representation that will "
|
|
"be used by the print statement."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:371
|
|
msgid ""
|
|
"When this field is not set, :c:func:`PyObject_Repr` is called to return a "
|
|
"string representation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:379
|
|
msgid "An optional pointer to the get-attribute function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:381
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_GetAttr`. It is usually "
|
|
"convenient to set this field to :c:func:`PyObject_GenericGetAttr`, which "
|
|
"implements the normal way of looking for object attributes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:385
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_getattr`: a subtype inherits both :c:member:`~PyTypeObject.tp_getattr` "
|
|
"and :c:member:`~PyTypeObject.tp_getattro` from its base type when the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject."
|
|
"tp_getattro` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:392
|
|
msgid "An optional pointer to the set-attribute function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:394
|
|
msgid ""
|
|
"The signature is the same as for :c:func:`PyObject_SetAttr`. It is usually "
|
|
"convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which "
|
|
"implements the normal way of setting object attributes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:398
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_setattr`: a subtype inherits both :c:member:`~PyTypeObject.tp_setattr` "
|
|
"and :c:member:`~PyTypeObject.tp_setattro` from its base type when the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject."
|
|
"tp_setattro` are both *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:405
|
|
msgid ""
|
|
"Pointer to an additional structure that contains fields relevant only to "
|
|
"objects which implement the buffer interface. These fields are documented "
|
|
"in :ref:`buffer-structs`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:409
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the "
|
|
"contained fields are inherited individually."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:415
|
|
msgid ""
|
|
"This field is a bit mask of various flags. Some flags indicate variant "
|
|
"semantics for certain situations; others are used to indicate that certain "
|
|
"fields in the type object (or in the extension structures referenced via :c:"
|
|
"member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject."
|
|
"tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and :c:member:"
|
|
"`~PyTypeObject.tp_as_buffer`) that were historically not always present are "
|
|
"valid; if such a flag bit is clear, the type fields it guards must not be "
|
|
"accessed and must be considered to have a zero or *NULL* value instead."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:423
|
|
msgid ""
|
|
"Inheritance of this field is complicated. Most flag bits are inherited "
|
|
"individually, i.e. if the base type has a flag bit set, the subtype inherits "
|
|
"this flag bit. The flag bits that pertain to extension structures are "
|
|
"strictly inherited if the extension structure is inherited, i.e. the base "
|
|
"type's value of the flag bit is copied into the subtype together with a "
|
|
"pointer to the extension structure. The :const:`Py_TPFLAGS_HAVE_GC` flag "
|
|
"bit is inherited together with the :c:member:`~PyTypeObject.tp_traverse` "
|
|
"and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the :const:"
|
|
"`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the :c:member:"
|
|
"`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in "
|
|
"the subtype exist (as indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` "
|
|
"flag bit) and have *NULL* values."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:435
|
|
msgid ""
|
|
"The following bit masks are currently defined; these can be ORed together "
|
|
"using the ``|`` operator to form the value of the :c:member:`~PyTypeObject."
|
|
"tp_flags` field. The macro :c:func:`PyType_HasFeature` takes a type and a "
|
|
"flags value, *tp* and *f*, and checks whether ``tp->tp_flags & f`` is non-"
|
|
"zero."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:443
|
|
msgid ""
|
|
"If this bit is set, the :c:type:`PyBufferProcs` struct referenced by :c:"
|
|
"member:`~PyTypeObject.tp_as_buffer` has the :attr:`bf_getcharbuffer` field."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:449
|
|
msgid ""
|
|
"If this bit is set, the :c:type:`PySequenceMethods` struct referenced by :c:"
|
|
"member:`~PyTypeObject.tp_as_sequence` has the :attr:`sq_contains` field."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:455
|
|
msgid ""
|
|
"This bit is obsolete. The bit it used to name is no longer in use. The "
|
|
"symbol is now defined as zero."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:461
|
|
msgid ""
|
|
"If this bit is set, the :c:type:`PySequenceMethods` struct referenced by :c:"
|
|
"member:`~PyTypeObject.tp_as_sequence` and the :c:type:`PyNumberMethods` "
|
|
"structure referenced by :c:member:`~PyTypeObject.tp_as_number` contain the "
|
|
"fields for in-place operators. In particular, this means that the :c:type:"
|
|
"`PyNumberMethods` structure has the fields :attr:`nb_inplace_add`, :attr:"
|
|
"`nb_inplace_subtract`, :attr:`nb_inplace_multiply`, :attr:"
|
|
"`nb_inplace_divide`, :attr:`nb_inplace_remainder`, :attr:"
|
|
"`nb_inplace_power`, :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :"
|
|
"attr:`nb_inplace_and`, :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; "
|
|
"and the :c:type:`PySequenceMethods` struct has the fields :attr:"
|
|
"`sq_inplace_concat` and :attr:`sq_inplace_repeat`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:476
|
|
msgid ""
|
|
"If this bit is set, the binary and ternary operations in the :c:type:"
|
|
"`PyNumberMethods` structure referenced by :c:member:`~PyTypeObject."
|
|
"tp_as_number` accept arguments of arbitrary object types, and do their own "
|
|
"type conversions if needed. If this bit is clear, those operations require "
|
|
"that all arguments have the current type as their type, and the caller is "
|
|
"supposed to perform a coercion operation first. This applies to :attr:"
|
|
"`nb_add`, :attr:`nb_subtract`, :attr:`nb_multiply`, :attr:`nb_divide`, :attr:"
|
|
"`nb_remainder`, :attr:`nb_divmod`, :attr:`nb_power`, :attr:`nb_lshift`, :"
|
|
"attr:`nb_rshift`, :attr:`nb_and`, :attr:`nb_xor`, and :attr:`nb_or`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:489
|
|
msgid ""
|
|
"If this bit is set, the type object has the :c:member:`~PyTypeObject."
|
|
"tp_richcompare` field, as well as the :c:member:`~PyTypeObject.tp_traverse` "
|
|
"and the :c:member:`~PyTypeObject.tp_clear` fields."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:495
|
|
msgid ""
|
|
"If this bit is set, the :c:member:`~PyTypeObject.tp_weaklistoffset` field is "
|
|
"defined. Instances of a type are weakly referenceable if the type's :c:"
|
|
"member:`~PyTypeObject.tp_weaklistoffset` field has a value greater than zero."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:502
|
|
msgid ""
|
|
"If this bit is set, the type object has the :c:member:`~PyTypeObject."
|
|
"tp_iter` and :c:member:`~PyTypeObject.tp_iternext` fields."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:508
|
|
msgid ""
|
|
"If this bit is set, the type object has several new fields defined starting "
|
|
"in Python 2.2: :c:member:`~PyTypeObject.tp_methods`, :c:member:"
|
|
"`~PyTypeObject.tp_members`, :c:member:`~PyTypeObject.tp_getset`, :c:member:"
|
|
"`~PyTypeObject.tp_base`, :c:member:`~PyTypeObject.tp_dict`, :c:member:"
|
|
"`~PyTypeObject.tp_descr_get`, :c:member:`~PyTypeObject.tp_descr_set`, :c:"
|
|
"member:`~PyTypeObject.tp_dictoffset`, :c:member:`~PyTypeObject.tp_init`, :c:"
|
|
"member:`~PyTypeObject.tp_alloc`, :c:member:`~PyTypeObject.tp_new`, :c:member:"
|
|
"`~PyTypeObject.tp_free`, :c:member:`~PyTypeObject.tp_is_gc`, :c:member:"
|
|
"`~PyTypeObject.tp_bases`, :c:member:`~PyTypeObject.tp_mro`, :c:member:"
|
|
"`~PyTypeObject.tp_cache`, :c:member:`~PyTypeObject.tp_subclasses`, and :c:"
|
|
"member:`~PyTypeObject.tp_weaklist`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:518
|
|
msgid ""
|
|
"This bit is set when the type object itself is allocated on the heap. In "
|
|
"this case, the :attr:`ob_type` field of its instances is considered a "
|
|
"reference to the type, and the type object is INCREF'ed when a new instance "
|
|
"is created, and DECREF'ed when an instance is destroyed (this does not apply "
|
|
"to instances of subtypes; only the type referenced by the instance's ob_type "
|
|
"gets INCREF'ed or DECREF'ed)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:528
|
|
msgid ""
|
|
"This bit is set when the type can be used as the base type of another type. "
|
|
"If this bit is clear, the type cannot be subtyped (similar to a \"final\" "
|
|
"class in Java)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:535
|
|
msgid ""
|
|
"This bit is set when the type object has been fully initialized by :c:func:"
|
|
"`PyType_Ready`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:541
|
|
msgid ""
|
|
"This bit is set while :c:func:`PyType_Ready` is in the process of "
|
|
"initializing the type object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:547
|
|
msgid ""
|
|
"This bit is set when the object supports garbage collection. If this bit is "
|
|
"set, instances must be created using :c:func:`PyObject_GC_New` and destroyed "
|
|
"using :c:func:`PyObject_GC_Del`. More information in section :ref:"
|
|
"`supporting-cycle-detection`. This bit also implies that the GC-related "
|
|
"fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject."
|
|
"tp_clear` are present in the type object; but those fields also exist when :"
|
|
"const:`Py_TPFLAGS_HAVE_GC` is clear but :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` "
|
|
"is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:559
|
|
msgid ""
|
|
"This is a bitmask of all the bits that pertain to the existence of certain "
|
|
"fields in the type object and its extension structures. Currently, it "
|
|
"includes the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`, :const:"
|
|
"`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`, :const:"
|
|
"`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`, :const:"
|
|
"`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:569
|
|
msgid ""
|
|
"An optional pointer to a NUL-terminated C string giving the docstring for "
|
|
"this type object. This is exposed as the :attr:`__doc__` attribute on the "
|
|
"type and instances of the type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:573
|
|
msgid "This field is *not* inherited by subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:575
|
|
msgid ""
|
|
"The following three fields only exist if the :const:"
|
|
"`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:581
|
|
msgid ""
|
|
"An optional pointer to a traversal function for the garbage collector. This "
|
|
"is only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More "
|
|
"information about Python's garbage collection scheme can be found in "
|
|
"section :ref:`supporting-cycle-detection`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:586
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage "
|
|
"collector to detect reference cycles. A typical implementation of a :c:"
|
|
"member:`~PyTypeObject.tp_traverse` function simply calls :c:func:`Py_VISIT` "
|
|
"on each of the instance's members that are Python objects. For example, "
|
|
"this is function :c:func:`local_traverse` from the :mod:`thread` extension "
|
|
"module::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:601
|
|
msgid ""
|
|
"Note that :c:func:`Py_VISIT` is called only on those members that can "
|
|
"participate in reference cycles. Although there is also a ``self->key`` "
|
|
"member, it can only be *NULL* or a Python string and therefore cannot be "
|
|
"part of a reference cycle."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:605
|
|
msgid ""
|
|
"On the other hand, even if you know a member can never be part of a cycle, "
|
|
"as a debugging aid you may want to visit it anyway just so the :mod:`gc` "
|
|
"module's :func:`~gc.get_referents` function will include it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:609
|
|
msgid ""
|
|
"Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to :c:"
|
|
"func:`local_traverse` to have these specific names; don't name them just "
|
|
"anything."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:613
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_clear` and the :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:"
|
|
"member:`~PyTypeObject.tp_traverse`, and :c:member:`~PyTypeObject.tp_clear` "
|
|
"are all inherited from the base type if they are all zero in the subtype "
|
|
"*and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:622
|
|
msgid ""
|
|
"An optional pointer to a clear function for the garbage collector. This is "
|
|
"only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:625
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_clear` member function is used to break "
|
|
"reference cycles in cyclic garbage detected by the garbage collector. Taken "
|
|
"together, all :c:member:`~PyTypeObject.tp_clear` functions in the system "
|
|
"must combine to break all reference cycles. This is subtle, and if in any "
|
|
"doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For example, "
|
|
"the tuple type does not implement a :c:member:`~PyTypeObject.tp_clear` "
|
|
"function, because it's possible to prove that no reference cycle can be "
|
|
"composed entirely of tuples. Therefore the :c:member:`~PyTypeObject."
|
|
"tp_clear` functions of other types must be sufficient to break any cycle "
|
|
"containing a tuple. This isn't immediately obvious, and there's rarely a "
|
|
"good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:635
|
|
msgid ""
|
|
"Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the "
|
|
"instance's references to those of its members that may be Python objects, "
|
|
"and set its pointers to those members to *NULL*, as in the following "
|
|
"example::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:649
|
|
msgid ""
|
|
"The :c:func:`Py_CLEAR` macro should be used, because clearing references is "
|
|
"delicate: the reference to the contained object must not be decremented "
|
|
"until after the pointer to the contained object is set to *NULL*. This is "
|
|
"because decrementing the reference count may cause the contained object to "
|
|
"become trash, triggering a chain of reclamation activity that may include "
|
|
"invoking arbitrary Python code (due to finalizers, or weakref callbacks, "
|
|
"associated with the contained object). If it's possible for such code to "
|
|
"reference *self* again, it's important that the pointer to the contained "
|
|
"object be *NULL* at that time, so that *self* knows the contained object can "
|
|
"no longer be used. The :c:func:`Py_CLEAR` macro performs the operations in "
|
|
"a safe order."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:660
|
|
msgid ""
|
|
"Because the goal of :c:member:`~PyTypeObject.tp_clear` functions is to break "
|
|
"reference cycles, it's not necessary to clear contained objects like Python "
|
|
"strings or Python integers, which can't participate in reference cycles. On "
|
|
"the other hand, it may be convenient to clear all contained Python objects, "
|
|
"and write the type's :c:member:`~PyTypeObject.tp_dealloc` function to "
|
|
"invoke :c:member:`~PyTypeObject.tp_clear`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:666
|
|
msgid ""
|
|
"More information about Python's garbage collection scheme can be found in "
|
|
"section :ref:`supporting-cycle-detection`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:669
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_traverse` and the :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:"
|
|
"member:`~PyTypeObject.tp_traverse`, and :c:member:`~PyTypeObject.tp_clear` "
|
|
"are all inherited from the base type if they are all zero in the subtype "
|
|
"*and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:678
|
|
msgid ""
|
|
"An optional pointer to the rich comparison function, whose signature is "
|
|
"``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:681
|
|
msgid ""
|
|
"The function should return the result of the comparison (usually ``Py_True`` "
|
|
"or ``Py_False``). If the comparison is undefined, it must return "
|
|
"``Py_NotImplemented``, if another error occurred it must return ``NULL`` and "
|
|
"set an exception condition."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:688
|
|
msgid ""
|
|
"If you want to implement a type for which only a limited set of comparisons "
|
|
"makes sense (e.g. ``==`` and ``!=``, but not ``<`` and friends), directly "
|
|
"raise :exc:`TypeError` in the rich comparison function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:692
|
|
msgid ""
|
|
"This field is inherited by subtypes together with :c:member:`~PyTypeObject."
|
|
"tp_compare` and :c:member:`~PyTypeObject.tp_hash`: a subtype inherits all "
|
|
"three of :c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject."
|
|
"tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash`, when the subtype's :"
|
|
"c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject."
|
|
"tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash` are all *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:697
|
|
msgid ""
|
|
"The following constants are defined to be used as the third argument for :c:"
|
|
"member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:701
|
|
msgid "Constant"
|
|
msgstr "Constante"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:701
|
|
msgid "Comparison"
|
|
msgstr "Comparaison"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:703
|
|
msgid ":const:`Py_LT`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:703
|
|
msgid "``<``"
|
|
msgstr "``<``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:705
|
|
msgid ":const:`Py_LE`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:705
|
|
msgid "``<=``"
|
|
msgstr "``<=``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:707
|
|
msgid ":const:`Py_EQ`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:707
|
|
msgid "``==``"
|
|
msgstr "``==``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:709
|
|
msgid ":const:`Py_NE`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:709
|
|
msgid "``!=``"
|
|
msgstr "``!=``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:711
|
|
msgid ":const:`Py_GT`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:711
|
|
msgid "``>``"
|
|
msgstr "``>``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:713
|
|
msgid ":const:`Py_GE`"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:713
|
|
msgid "``>=``"
|
|
msgstr "``>=``"
|
|
|
|
#: ../Doc/c-api/typeobj.rst:717
|
|
msgid ""
|
|
"The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit "
|
|
"is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:722
|
|
msgid ""
|
|
"If the instances of this type are weakly referenceable, this field is "
|
|
"greater than zero and contains the offset in the instance structure of the "
|
|
"weak reference list head (ignoring the GC header, if present); this offset "
|
|
"is used by :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\\*` "
|
|
"functions. The instance structure needs to include a field of type :c:type:"
|
|
"`PyObject\\*` which is initialized to *NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:729
|
|
msgid ""
|
|
"Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that "
|
|
"is the list head for weak references to the type object itself."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:732
|
|
msgid ""
|
|
"This field is inherited by subtypes, but see the rules listed below. A "
|
|
"subtype may override this offset; this means that the subtype uses a "
|
|
"different weak reference list head than the base type. Since the list head "
|
|
"is always found via :c:member:`~PyTypeObject.tp_weaklistoffset`, this should "
|
|
"not be a problem."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:737
|
|
msgid ""
|
|
"When a type defined by a class statement has no :attr:`~object.__slots__` "
|
|
"declaration, and none of its base types are weakly referenceable, the type "
|
|
"is made weakly referenceable by adding a weak reference list head slot to "
|
|
"the instance layout and setting the :c:member:`~PyTypeObject."
|
|
"tp_weaklistoffset` of that slot's offset."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:742
|
|
msgid ""
|
|
"When a type's :attr:`__slots__` declaration contains a slot named :attr:"
|
|
"`__weakref__`, that slot becomes the weak reference list head for instances "
|
|
"of the type, and the slot's offset is stored in the type's :c:member:"
|
|
"`~PyTypeObject.tp_weaklistoffset`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:747
|
|
msgid ""
|
|
"When a type's :attr:`__slots__` declaration does not contain a slot named :"
|
|
"attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject."
|
|
"tp_weaklistoffset` from its base type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:751
|
|
msgid ""
|
|
"The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_ITER` flag bit "
|
|
"is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:757
|
|
msgid ""
|
|
"An optional pointer to a function that returns an iterator for the object. "
|
|
"Its presence normally signals that the instances of this type are iterable "
|
|
"(although sequences may be iterable without this function, and classic "
|
|
"instances always have this function, even if they don't define an :meth:"
|
|
"`__iter__` method)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:762
|
|
msgid "This function has the same signature as :c:func:`PyObject_GetIter`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:769
|
|
msgid ""
|
|
"An optional pointer to a function that returns the next item in an iterator. "
|
|
"When the iterator is exhausted, it must return *NULL*; a :exc:"
|
|
"`StopIteration` exception may or may not be set. When another error occurs, "
|
|
"it must return *NULL* too. Its presence normally signals that the instances "
|
|
"of this type are iterators (although classic instances always have this "
|
|
"function, even if they don't define a :meth:`~iterator.next` method)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:776
|
|
msgid ""
|
|
"Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` "
|
|
"function, and that function should return the iterator instance itself (not "
|
|
"a new iterator instance)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:780
|
|
msgid "This function has the same signature as :c:func:`PyIter_Next`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:784
|
|
msgid ""
|
|
"The next fields, up to and including :c:member:`~PyTypeObject.tp_weaklist`, "
|
|
"only exist if the :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:790
|
|
msgid ""
|
|
"An optional pointer to a static *NULL*-terminated array of :c:type:"
|
|
"`PyMethodDef` structures, declaring regular methods of this type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:793
|
|
msgid ""
|
|
"For each entry in the array, an entry is added to the type's dictionary "
|
|
"(see :c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:796
|
|
msgid ""
|
|
"This field is not inherited by subtypes (methods are inherited through a "
|
|
"different mechanism)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:802
|
|
msgid ""
|
|
"An optional pointer to a static *NULL*-terminated array of :c:type:"
|
|
"`PyMemberDef` structures, declaring regular data members (fields or slots) "
|
|
"of instances of this type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:806
|
|
msgid ""
|
|
"For each entry in the array, an entry is added to the type's dictionary "
|
|
"(see :c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:809
|
|
msgid ""
|
|
"This field is not inherited by subtypes (members are inherited through a "
|
|
"different mechanism)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:815
|
|
msgid ""
|
|
"An optional pointer to a static *NULL*-terminated array of :c:type:"
|
|
"`PyGetSetDef` structures, declaring computed attributes of instances of this "
|
|
"type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:818
|
|
msgid ""
|
|
"For each entry in the array, an entry is added to the type's dictionary "
|
|
"(see :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:821
|
|
msgid ""
|
|
"This field is not inherited by subtypes (computed attributes are inherited "
|
|
"through a different mechanism)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:826
|
|
msgid "Docs for PyGetSetDef::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:842
|
|
msgid ""
|
|
"An optional pointer to a base type from which type properties are "
|
|
"inherited. At this level, only single inheritance is supported; multiple "
|
|
"inheritance require dynamically creating a type object by calling the "
|
|
"metatype."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:846
|
|
msgid ""
|
|
"This field is not inherited by subtypes (obviously), but it defaults to "
|
|
"``&PyBaseObject_Type`` (which to Python programmers is known as the type :"
|
|
"class:`object`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:853
|
|
msgid "The type's dictionary is stored here by :c:func:`PyType_Ready`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:855
|
|
msgid ""
|
|
"This field should normally be initialized to *NULL* before PyType_Ready is "
|
|
"called; it may also be initialized to a dictionary containing initial "
|
|
"attributes for the type. Once :c:func:`PyType_Ready` has initialized the "
|
|
"type, extra attributes for the type may be added to this dictionary only if "
|
|
"they don't correspond to overloaded operations (like :meth:`__add__`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:861
|
|
msgid ""
|
|
"This field is not inherited by subtypes (though the attributes defined in "
|
|
"here are inherited through a different mechanism)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:867
|
|
msgid "An optional pointer to a \"descriptor get\" function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:869 ../Doc/c-api/typeobj.rst:882
|
|
#: ../Doc/c-api/typeobj.rst:953 ../Doc/c-api/typeobj.rst:978
|
|
#: ../Doc/c-api/typeobj.rst:1009
|
|
msgid "The function signature is ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:880
|
|
msgid "An optional pointer to a \"descriptor set\" function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:893
|
|
msgid ""
|
|
"If the instances of this type have a dictionary containing instance "
|
|
"variables, this field is non-zero and contains the offset in the instances "
|
|
"of the type of the instance variable dictionary; this offset is used by :c:"
|
|
"func:`PyObject_GenericGetAttr`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:898
|
|
msgid ""
|
|
"Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is "
|
|
"the dictionary for attributes of the type object itself."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:901
|
|
msgid ""
|
|
"If the value of this field is greater than zero, it specifies the offset "
|
|
"from the start of the instance structure. If the value is less than zero, "
|
|
"it specifies the offset from the *end* of the instance structure. A "
|
|
"negative offset is more expensive to use, and should only be used when the "
|
|
"instance structure contains a variable-length part. This is used for "
|
|
"example to add an instance variable dictionary to subtypes of :class:`str` "
|
|
"or :class:`tuple`. Note that the :c:member:`~PyTypeObject.tp_basicsize` "
|
|
"field should account for the dictionary added to the end in that case, even "
|
|
"though the dictionary is not included in the basic object layout. On a "
|
|
"system with a pointer size of 4 bytes, :c:member:`~PyTypeObject."
|
|
"tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is at "
|
|
"the very end of the structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:913
|
|
msgid ""
|
|
"The real dictionary offset in an instance can be computed from a negative :c:"
|
|
"member:`~PyTypeObject.tp_dictoffset` as follows::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:920
|
|
msgid ""
|
|
"where :c:member:`~PyTypeObject.tp_basicsize`, :c:member:`~PyTypeObject."
|
|
"tp_itemsize` and :c:member:`~PyTypeObject.tp_dictoffset` are taken from the "
|
|
"type object, and :attr:`ob_size` is taken from the instance. The absolute "
|
|
"value is taken because long ints use the sign of :attr:`ob_size` to store "
|
|
"the sign of the number. (There's never a need to do this calculation "
|
|
"yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:926
|
|
msgid ""
|
|
"This field is inherited by subtypes, but see the rules listed below. A "
|
|
"subtype may override this offset; this means that the subtype instances "
|
|
"store the dictionary at a difference offset than the base type. Since the "
|
|
"dictionary is always found via :c:member:`~PyTypeObject.tp_dictoffset`, this "
|
|
"should not be a problem."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:931
|
|
msgid ""
|
|
"When a type defined by a class statement has no :attr:`~object.__slots__` "
|
|
"declaration, and none of its base types has an instance variable dictionary, "
|
|
"a dictionary slot is added to the instance layout and the :c:member:"
|
|
"`~PyTypeObject.tp_dictoffset` is set to that slot's offset."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:936
|
|
msgid ""
|
|
"When a type defined by a class statement has a :attr:`__slots__` "
|
|
"declaration, the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` "
|
|
"from its base type."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:939
|
|
msgid ""
|
|
"(Adding a slot named :attr:`~object.__dict__` to the :attr:`__slots__` "
|
|
"declaration does not have the expected effect, it just causes confusion. "
|
|
"Maybe this should be added as a feature just like :attr:`__weakref__` "
|
|
"though.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:946
|
|
msgid "An optional pointer to an instance initialization function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:948
|
|
msgid ""
|
|
"This function corresponds to the :meth:`__init__` method of classes. Like :"
|
|
"meth:`__init__`, it is possible to create an instance without calling :meth:"
|
|
"`__init__`, and it is possible to reinitialize an instance by calling its :"
|
|
"meth:`__init__` method again."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:957
|
|
msgid ""
|
|
"The self argument is the instance to be initialized; the *args* and *kwds* "
|
|
"arguments represent positional and keyword arguments of the call to :meth:"
|
|
"`__init__`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:961
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_init` function, if not *NULL*, is called "
|
|
"when an instance is created normally by calling its type, after the type's :"
|
|
"c:member:`~PyTypeObject.tp_new` function has returned an instance of the "
|
|
"type. If the :c:member:`~PyTypeObject.tp_new` function returns an instance "
|
|
"of some other type that is not a subtype of the original type, no :c:member:"
|
|
"`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject."
|
|
"tp_new` returns an instance of a subtype of the original type, the "
|
|
"subtype's :c:member:`~PyTypeObject.tp_init` is called. (VERSION NOTE: "
|
|
"described here is what is implemented in Python 2.2.1 and later. In Python "
|
|
"2.2, the :c:member:`~PyTypeObject.tp_init` of the type of the object "
|
|
"returned by :c:member:`~PyTypeObject.tp_new` was always called, if not "
|
|
"*NULL*.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:976
|
|
msgid "An optional pointer to an instance allocation function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:982
|
|
msgid ""
|
|
"The purpose of this function is to separate memory allocation from memory "
|
|
"initialization. It should return a pointer to a block of memory of adequate "
|
|
"length for the instance, suitably aligned, and initialized to zeros, but "
|
|
"with :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type "
|
|
"argument. If the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, "
|
|
"the object's :attr:`ob_size` field should be initialized to *nitems* and the "
|
|
"length of the allocated memory block should be ``tp_basicsize + "
|
|
"nitems*tp_itemsize``, rounded up to a multiple of ``sizeof(void*)``; "
|
|
"otherwise, *nitems* is not used and the length of the block should be :c:"
|
|
"member:`~PyTypeObject.tp_basicsize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:992
|
|
msgid ""
|
|
"Do not use this function to do any other instance initialization, not even "
|
|
"to allocate additional memory; that should be done by :c:member:"
|
|
"`~PyTypeObject.tp_new`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:995
|
|
msgid ""
|
|
"This field is inherited by static subtypes, but not by dynamic subtypes "
|
|
"(subtypes created by a class statement); in the latter, this field is always "
|
|
"set to :c:func:`PyType_GenericAlloc`, to force a standard heap allocation "
|
|
"strategy. That is also the recommended value for statically defined types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1003
|
|
msgid "An optional pointer to an instance creation function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1005
|
|
msgid ""
|
|
"If this function is *NULL* for a particular type, that type cannot be called "
|
|
"to create new instances; presumably there is some other way to create "
|
|
"instances, like a factory function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1013
|
|
msgid ""
|
|
"The subtype argument is the type of the object being created; the *args* and "
|
|
"*kwds* arguments represent positional and keyword arguments of the call to "
|
|
"the type. Note that subtype doesn't have to equal the type whose :c:member:"
|
|
"`~PyTypeObject.tp_new` function is called; it may be a subtype of that type "
|
|
"(but not an unrelated type)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1019
|
|
msgid ""
|
|
"The :c:member:`~PyTypeObject.tp_new` function should call ``subtype-"
|
|
">tp_alloc(subtype, nitems)`` to allocate space for the object, and then do "
|
|
"only as much further initialization as is absolutely necessary. "
|
|
"Initialization that can safely be ignored or repeated should be placed in "
|
|
"the :c:member:`~PyTypeObject.tp_init` handler. A good rule of thumb is that "
|
|
"for immutable types, all initialization should take place in :c:member:"
|
|
"`~PyTypeObject.tp_new`, while for mutable types, most initialization should "
|
|
"be deferred to :c:member:`~PyTypeObject.tp_init`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1027
|
|
msgid ""
|
|
"This field is inherited by subtypes, except it is not inherited by static "
|
|
"types whose :c:member:`~PyTypeObject.tp_base` is *NULL* or "
|
|
"``&PyBaseObject_Type``. The latter exception is a precaution so that old "
|
|
"extension types don't become callable simply by being linked with Python 2.2."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1035
|
|
msgid "An optional pointer to an instance deallocation function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1037
|
|
msgid ""
|
|
"The signature of this function has changed slightly: in Python 2.2 and "
|
|
"2.2.1, its signature is :c:type:`destructor`::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1042
|
|
msgid "In Python 2.3 and beyond, its signature is :c:type:`freefunc`::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1046
|
|
msgid ""
|
|
"The only initializer that is compatible with both versions is "
|
|
"``_PyObject_Del``, whose definition has suitably adapted in Python 2.3."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1049
|
|
msgid ""
|
|
"This field is inherited by static subtypes, but not by dynamic subtypes "
|
|
"(subtypes created by a class statement); in the latter, this field is set to "
|
|
"a deallocator suitable to match :c:func:`PyType_GenericAlloc` and the value "
|
|
"of the :const:`Py_TPFLAGS_HAVE_GC` flag bit."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1057
|
|
msgid "An optional pointer to a function called by the garbage collector."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1059
|
|
msgid ""
|
|
"The garbage collector needs to know whether a particular object is "
|
|
"collectible or not. Normally, it is sufficient to look at the object's "
|
|
"type's :c:member:`~PyTypeObject.tp_flags` field, and check the :const:"
|
|
"`Py_TPFLAGS_HAVE_GC` flag bit. But some types have a mixture of statically "
|
|
"and dynamically allocated instances, and the statically allocated instances "
|
|
"are not collectible. Such types should define this function; it should "
|
|
"return ``1`` for a collectible instance, and ``0`` for a non-collectible "
|
|
"instance. The signature is ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1069
|
|
msgid ""
|
|
"(The only example of this are types themselves. The metatype, :c:data:"
|
|
"`PyType_Type`, defines this function to distinguish between statically and "
|
|
"dynamically allocated types.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1073
|
|
msgid ""
|
|
"This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was "
|
|
"not inherited. It is inherited in 2.2.1 and later versions.)"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1079
|
|
msgid "Tuple of base types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1081
|
|
msgid ""
|
|
"This is set for types created by a class statement. It should be *NULL* for "
|
|
"statically defined types."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1084
|
|
msgid "This field is not inherited."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1089
|
|
msgid ""
|
|
"Tuple containing the expanded set of base types, starting with the type "
|
|
"itself and ending with :class:`object`, in Method Resolution Order."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1092
|
|
msgid ""
|
|
"This field is not inherited; it is calculated fresh by :c:func:"
|
|
"`PyType_Ready`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1097
|
|
msgid "Unused. Not inherited. Internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1102
|
|
msgid ""
|
|
"List of weak references to subclasses. Not inherited. Internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1107
|
|
msgid ""
|
|
"Weak reference list head, for weak references to this type object. Not "
|
|
"inherited. Internal use only."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1110
|
|
msgid ""
|
|
"The remaining fields are only defined if the feature test macro :const:"
|
|
"`COUNT_ALLOCS` is defined, and are for internal use only. They are "
|
|
"documented here for completeness. None of these fields are inherited by "
|
|
"subtypes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1118
|
|
msgid "Number of allocations."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1123
|
|
msgid "Number of frees."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1128
|
|
msgid "Maximum simultaneously allocated objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1133
|
|
msgid ""
|
|
"Pointer to the next type object with a non-zero :c:member:`~PyTypeObject."
|
|
"tp_allocs` field."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1135
|
|
msgid ""
|
|
"Also, note that, in a garbage collected Python, tp_dealloc may be called "
|
|
"from any Python thread, not just the thread which created the object (if the "
|
|
"object becomes part of a refcount cycle, that cycle might be collected by a "
|
|
"garbage collection on any thread). This is not a problem for Python API "
|
|
"calls, since the thread on which tp_dealloc is called will own the Global "
|
|
"Interpreter Lock (GIL). However, if the object being destroyed in turn "
|
|
"destroys objects from some other C or C++ library, care should be taken to "
|
|
"ensure that destroying those objects on the thread which called tp_dealloc "
|
|
"will not violate any assumptions of the library."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1149
|
|
msgid "Number Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1156
|
|
msgid ""
|
|
"This structure holds pointers to the functions which an object uses to "
|
|
"implement the number protocol. Almost every function below is used by the "
|
|
"function of similar name documented in the :ref:`number` section."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1160
|
|
msgid "Here is the structure definition::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1211
|
|
msgid ""
|
|
"Binary and ternary functions may receive different kinds of arguments, "
|
|
"depending on the flag bit :const:`Py_TPFLAGS_CHECKTYPES`:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1214
|
|
msgid ""
|
|
"If :const:`Py_TPFLAGS_CHECKTYPES` is not set, the function arguments are "
|
|
"guaranteed to be of the object's type; the caller is responsible for calling "
|
|
"the coercion method specified by the :attr:`nb_coerce` member to convert the "
|
|
"arguments:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1221
|
|
msgid ""
|
|
"This function is used by :c:func:`PyNumber_CoerceEx` and has the same "
|
|
"signature. The first argument is always a pointer to an object of the "
|
|
"defined type. If the conversion to a common \"larger\" type is possible, "
|
|
"the function replaces the pointers with new references to the converted "
|
|
"objects and returns ``0``. If the conversion is not possible, the function "
|
|
"returns ``1``. If an error condition is set, it will return ``-1``."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1228
|
|
msgid ""
|
|
"If the :const:`Py_TPFLAGS_CHECKTYPES` flag is set, binary and ternary "
|
|
"functions must check the type of all their operands, and implement the "
|
|
"necessary conversions (at least one of the operands is an instance of the "
|
|
"defined type). This is the recommended way; with Python 3 coercion will "
|
|
"disappear completely."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1234
|
|
msgid ""
|
|
"If the operation is not defined for the given operands, binary and ternary "
|
|
"functions must return ``Py_NotImplemented``, if another error occurred they "
|
|
"must return ``NULL`` and set an exception."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1242
|
|
msgid "Mapping Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1249
|
|
msgid ""
|
|
"This structure holds pointers to the functions which an object uses to "
|
|
"implement the mapping protocol. It has three members:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1254
|
|
msgid ""
|
|
"This function is used by :c:func:`PyMapping_Length` and :c:func:"
|
|
"`PyObject_Size`, and has the same signature. This slot may be set to *NULL* "
|
|
"if the object has no defined length."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1260
|
|
msgid ""
|
|
"This function is used by :c:func:`PyObject_GetItem` and has the same "
|
|
"signature. This slot must be filled for the :c:func:`PyMapping_Check` "
|
|
"function to return ``1``, it can be *NULL* otherwise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1266
|
|
msgid ""
|
|
"This function is used by :c:func:`PyObject_SetItem` and has the same "
|
|
"signature. If this slot is *NULL*, the object does not support item "
|
|
"assignment."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1274
|
|
msgid "Sequence Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1281
|
|
msgid ""
|
|
"This structure holds pointers to the functions which an object uses to "
|
|
"implement the sequence protocol."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1286
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_Size` and :c:func:"
|
|
"`PyObject_Size`, and has the same signature."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1291
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_Concat` and has the same "
|
|
"signature. It is also used by the ``+`` operator, after trying the numeric "
|
|
"addition via the :c:member:`~PyTypeObject.tp_as_number.nb_add` slot."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1297
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_Repeat` and has the same "
|
|
"signature. It is also used by the ``*`` operator, after trying numeric "
|
|
"multiplication via the :c:member:`~PyTypeObject.tp_as_number.nb_multiply` "
|
|
"slot."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1304
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_GetItem` and has the same "
|
|
"signature. This slot must be filled for the :c:func:`PySequence_Check` "
|
|
"function to return ``1``, it can be *NULL* otherwise."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1308
|
|
msgid ""
|
|
"Negative indexes are handled as follows: if the :attr:`sq_length` slot is "
|
|
"filled, it is called and the sequence length is used to compute a positive "
|
|
"index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*, "
|
|
"the index is passed as is to the function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1315
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_SetItem` and has the same "
|
|
"signature. This slot may be left to *NULL* if the object does not support "
|
|
"item assignment."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1321
|
|
msgid ""
|
|
"This function may be used by :c:func:`PySequence_Contains` and has the same "
|
|
"signature. This slot may be left to *NULL*, in this case :c:func:"
|
|
"`PySequence_Contains` simply traverses the sequence until it finds a match."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1328
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_InPlaceConcat` and has the same "
|
|
"signature. It should modify its first operand, and return it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1333
|
|
msgid ""
|
|
"This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same "
|
|
"signature. It should modify its first operand, and return it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1343
|
|
msgid "Buffer Object Structures"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1348
|
|
msgid ""
|
|
"The buffer interface exports a model where an object can expose its internal "
|
|
"data as a set of chunks of data, where each chunk is specified as a pointer/"
|
|
"length pair. These chunks are called :dfn:`segments` and are presumed to be "
|
|
"non-contiguous in memory."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1353
|
|
msgid ""
|
|
"If an object does not export the buffer interface, then its :c:member:"
|
|
"`~PyTypeObject.tp_as_buffer` member in the :c:type:`PyTypeObject` structure "
|
|
"should be *NULL*. Otherwise, the :c:member:`~PyTypeObject.tp_as_buffer` "
|
|
"will point to a :c:type:`PyBufferProcs` structure."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1359
|
|
msgid ""
|
|
"It is very important that your :c:type:`PyTypeObject` structure uses :const:"
|
|
"`Py_TPFLAGS_DEFAULT` for the value of the :c:member:`~PyTypeObject.tp_flags` "
|
|
"member rather than ``0``. This tells the Python runtime that your :c:type:"
|
|
"`PyBufferProcs` structure contains the :attr:`bf_getcharbuffer` slot. Older "
|
|
"versions of Python did not have this member, so a new Python interpreter "
|
|
"using an old extension needs to be able to test for its presence before "
|
|
"using it."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1369
|
|
msgid ""
|
|
"Structure used to hold the function pointers which define an implementation "
|
|
"of the buffer protocol."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1372
|
|
msgid ""
|
|
"The first slot is :attr:`bf_getreadbuffer`, of type :c:type:"
|
|
"`getreadbufferproc`. If this slot is *NULL*, then the object does not "
|
|
"support reading from the internal data. This is non-sensical, so "
|
|
"implementors should fill this in, but callers should test that the slot "
|
|
"contains a non-*NULL* value."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1377
|
|
msgid ""
|
|
"The next slot is :attr:`bf_getwritebuffer` having type :c:type:"
|
|
"`getwritebufferproc`. This slot may be *NULL* if the object does not allow "
|
|
"writing into its returned buffers."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1381
|
|
msgid ""
|
|
"The third slot is :attr:`bf_getsegcount`, with type :c:type:"
|
|
"`getsegcountproc`. This slot must not be *NULL* and is used to inform the "
|
|
"caller how many segments the object contains. Simple objects such as :c:"
|
|
"type:`PyString_Type` and :c:type:`PyBuffer_Type` objects contain a single "
|
|
"segment."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1388
|
|
msgid ""
|
|
"The last slot is :attr:`bf_getcharbuffer`, of type :c:type:"
|
|
"`getcharbufferproc`. This slot will only be present if the :const:"
|
|
"`Py_TPFLAGS_HAVE_GETCHARBUFFER` flag is present in the :c:member:"
|
|
"`~PyTypeObject.tp_flags` field of the object's :c:type:`PyTypeObject`. "
|
|
"Before using this slot, the caller should test whether it is present by "
|
|
"using the :c:func:`PyType_HasFeature` function. If the flag is present, :"
|
|
"attr:`bf_getcharbuffer` may be *NULL*, indicating that the object's contents "
|
|
"cannot be used as *8-bit characters*. The slot function may also raise an "
|
|
"error if the object's contents cannot be interpreted as 8-bit characters. "
|
|
"For example, if the object is an array which is configured to hold floating "
|
|
"point values, an exception may be raised if a caller attempts to use :attr:"
|
|
"`bf_getcharbuffer` to fetch a sequence of 8-bit characters. This notion of "
|
|
"exporting the internal buffers as \"text\" is used to distinguish between "
|
|
"objects that are binary in nature, and those which have character-based "
|
|
"content."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1404
|
|
msgid ""
|
|
"The current policy seems to state that these characters may be multi-byte "
|
|
"characters. This implies that a buffer size of *N* does not mean there are "
|
|
"*N* characters present."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1411
|
|
msgid ""
|
|
"Flag bit set in the type structure to indicate that the :attr:"
|
|
"`bf_getcharbuffer` slot is known. This being set does not indicate that the "
|
|
"object supports the buffer interface or that the :attr:`bf_getcharbuffer` "
|
|
"slot is non-*NULL*."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1418
|
|
msgid ""
|
|
"Return a pointer to a readable segment of the buffer in ``*ptrptr``. This "
|
|
"function is allowed to raise an exception, in which case it must return "
|
|
"``-1``. The *segment* which is specified must be zero or positive, and "
|
|
"strictly less than the number of segments returned by the :attr:"
|
|
"`bf_getsegcount` slot function. On success, it returns the length of the "
|
|
"segment, and sets ``*ptrptr`` to a pointer to that memory."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1428
|
|
msgid ""
|
|
"Return a pointer to a writable memory buffer in ``*ptrptr``, and the length "
|
|
"of that segment as the function return value. The memory buffer must "
|
|
"correspond to buffer segment *segment*. Must return ``-1`` and set an "
|
|
"exception on error. :exc:`TypeError` should be raised if the object only "
|
|
"supports read-only buffers, and :exc:`SystemError` should be raised when "
|
|
"*segment* specifies a segment that doesn't exist."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1442
|
|
msgid ""
|
|
"Return the number of memory segments which comprise the buffer. If *lenp* "
|
|
"is not *NULL*, the implementation must report the sum of the sizes (in "
|
|
"bytes) of all segments in ``*lenp``. The function cannot fail."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/typeobj.rst:1449
|
|
msgid ""
|
|
"Return the size of the segment *segment* that *ptrptr* is set to. "
|
|
"``*ptrptr`` is set to the memory buffer. Returns ``-1`` on error."
|
|
msgstr ""
|