diff options
| -rw-r--r-- | Doc/c-api/newtypes.rst | 1855 | ||||
| -rw-r--r-- | Doc/library/optparse.rst | 29 | ||||
| -rw-r--r-- | Doc/library/os.rst | 14 | ||||
| -rw-r--r-- | Doc/library/sqlite3.rst | 34 | ||||
| -rw-r--r-- | Doc/library/xml.sax.utils.rst | 6 | ||||
| -rw-r--r-- | Doc/library/zipfile.rst | 3 | ||||
| -rw-r--r-- | Doc/whatsnew/2.6.rst | 7 | ||||
| -rw-r--r-- | Lib/curses/textpad.py | 36 | ||||
| -rwxr-xr-x | Lib/mailbox.py | 5 | ||||
| -rw-r--r-- | Lib/subprocess.py | 33 | ||||
| -rw-r--r-- | Lib/test/curses_tests.py | 46 | ||||
| -rw-r--r-- | Lib/test/test_mailbox.py | 14 | ||||
| -rw-r--r-- | Lib/test/test_os.py | 5 | ||||
| -rw-r--r-- | Lib/test/test_subprocess.py | 4 | ||||
| -rw-r--r-- | Lib/test/test_zipfile.py | 21 | ||||
| -rw-r--r-- | Lib/zipfile.py | 19 | ||||
| -rw-r--r-- | Misc/ACKS | 2 | ||||
| -rw-r--r-- | Modules/_sqlite/cursor.c | 6 | ||||
| -rw-r--r-- | Modules/posixmodule.c | 19 | ||||
| -rw-r--r-- | Modules/socketmodule.c | 25 |
20 files changed, 278 insertions, 1905 deletions
diff --git a/Doc/c-api/newtypes.rst b/Doc/c-api/newtypes.rst deleted file mode 100644 index 8c72ef1..0000000 --- a/Doc/c-api/newtypes.rst +++ /dev/null @@ -1,1855 +0,0 @@ -.. highlightlang:: c - - -.. _newtypes: - -***************************** -Object Implementation Support -***************************** - -This chapter describes the functions, types, and macros used when defining new -object types. - - -.. _allocating-objects: - -Allocating Objects on the Heap -============================== - - -.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type) - - -.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size) - - -.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type) - - Initialize a newly-allocated object *op* with its type and initial reference. - Returns the initialized object. If *type* indicates that the object - participates in the cyclic garbage detector, it is added to the detector's set - of observed objects. Other fields of the object are not affected. - - -.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size) - - This does everything :cfunc:`PyObject_Init` does, and also initializes the - length information for a variable-size object. - - -.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type) - - Allocate a new Python object using the C structure type *TYPE* and the Python - type object *type*. Fields not defined by the Python object header are not - initialized; the object's reference count will be one. The size of the memory - allocation is determined from the :attr:`tp_basicsize` field of the type object. - - -.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size) - - Allocate a new Python object using the C structure type *TYPE* and the Python - type object *type*. Fields not defined by the Python object header are not - initialized. The allocated memory allows for the *TYPE* structure plus *size* - fields of the size given by the :attr:`tp_itemsize` field of *type*. This is - useful for implementing objects like tuples, which are able to determine their - size at construction time. Embedding the array of fields into the same - allocation decreases the number of allocations, improving the memory management - efficiency. - - -.. cfunction:: void PyObject_Del(PyObject *op) - - Releases memory allocated to an object using :cfunc:`PyObject_New` or - :cfunc:`PyObject_NewVar`. This is normally called from the :attr:`tp_dealloc` - handler specified in the object's type. The fields of the object should not be - accessed after this call as the memory is no longer a valid Python object. - - -.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods) - - Create a new module object based on a name and table of functions, returning - the new module object; the *methods* argument can be *NULL* if no methods are - to be defined for the module. - - -.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc) - - Create a new module object based on a name and table of functions, returning - the new module object. The *methods* argument can be *NULL* if no methods - are to be defined for the module. If *doc* is non-*NULL*, it will be used to - define the docstring for the module. - - -.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver) - - Create a new module object based on a name and table of functions, returning - the new module object. The *methods* argument can be *NULL* if no methods - are to be defined for the module. If *doc* is non-*NULL*, it will be used to - define the docstring for the module. If *self* is non-*NULL*, it will passed - to the functions of the module as their (otherwise *NULL*) first parameter. - (This was added as an experimental feature, and there are no known uses in - the current version of Python.) For *apiver*, the only value which should be - passed is defined by the constant :const:`PYTHON_API_VERSION`. - - .. note:: - - Most uses of this function should probably be using the :cfunc:`Py_InitModule3` - instead; only use this if you are sure you need it. - - -.. cvar:: PyObject _Py_NoneStruct - - Object which is visible in Python as ``None``. This should only be accessed - using the :cmacro:`Py_None` macro, which evaluates to a pointer to this - object. - - -.. _common-structs: - -Common Object Structures -======================== - -There are a large number of structures which are used in the definition of -object types for Python. This section describes these structures and how they -are used. - -All Python objects ultimately share a small number of fields at the beginning of -the object's representation in memory. These are represented by the -:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn, by -the expansions of some macros also used, whether directly or indirectly, in the -definition of all other Python objects. - - -.. ctype:: PyObject - - All object types are extensions of this type. This is a type which contains the - information Python needs to treat a pointer to an object as an object. In a - normal "release" build, it contains only the objects reference count and a - pointer to the corresponding type object. It corresponds to the fields defined - by the expansion of the ``PyObject_HEAD`` macro. - - -.. ctype:: PyVarObject - - This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` field. - This is only used for objects that have some notion of *length*. This type does - not often appear in the Python/C API. It corresponds to the fields defined by - the expansion of the ``PyObject_VAR_HEAD`` macro. - -These macros are used in the definition of :ctype:`PyObject` and -:ctype:`PyVarObject`: - -.. XXX need to document PEP 3123 changes here - -.. cmacro:: PyObject_HEAD - - This is a macro which expands to the declarations of the fields of the - :ctype:`PyObject` type; it is used when declaring new types which represent - objects without a varying length. The specific fields it expands to depend on - the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is not - defined, and :cmacro:`PyObject_HEAD` expands to:: - - Py_ssize_t ob_refcnt; - PyTypeObject *ob_type; - - When :cmacro:`Py_TRACE_REFS` is defined, it expands to:: - - PyObject *_ob_next, *_ob_prev; - Py_ssize_t ob_refcnt; - PyTypeObject *ob_type; - - -.. cmacro:: PyObject_VAR_HEAD - - This is a macro which expands to the declarations of the fields of the - :ctype:`PyVarObject` type; it is used when declaring new types which represent - objects with a length that varies from instance to instance. This macro always - expands to:: - - PyObject_HEAD - Py_ssize_t ob_size; - - Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own - expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`. - -.. cmacro:: PyObject_HEAD_INIT - - -.. ctype:: PyCFunction - - Type of the functions used to implement most Python callables in C. Functions of - this type take two :ctype:`PyObject\*` parameters and return one such value. If - the return value is *NULL*, an exception shall have been set. If not *NULL*, - the return value is interpreted as the return value of the function as exposed - in Python. The function must return a new reference. - - -.. ctype:: PyCFunctionWithKeywords - - Type of the functions used to implement Python callables in C that take - keyword arguments: they take three :ctype:`PyObject\*` parameters and return - one such value. See :ctype:`PyCFunction` above for the meaning of the return - value. - - -.. ctype:: PyMethodDef - - Structure used to describe a method of an extension type. This structure has - four fields: - - +------------------+-------------+-------------------------------+ - | Field | C Type | Meaning | - +==================+=============+===============================+ - | :attr:`ml_name` | char \* | name of the method | - +------------------+-------------+-------------------------------+ - | :attr:`ml_meth` | PyCFunction | pointer to the C | - | | | implementation | - +------------------+-------------+-------------------------------+ - | :attr:`ml_flags` | int | flag bits indicating how the | - | | | call should be constructed | - +------------------+-------------+-------------------------------+ - | :attr:`ml_doc` | char \* | points to the contents of the | - | | | docstring | - +------------------+-------------+-------------------------------+ - -The :attr:`ml_meth` is a C function pointer. The functions may be of different -types, but they always return :ctype:`PyObject\*`. If the function is not of -the :ctype:`PyCFunction`, the compiler will require a cast in the method table. -Even though :ctype:`PyCFunction` defines the first parameter as -:ctype:`PyObject\*`, it is common that the method implementation uses a the -specific C type of the *self* object. - -The :attr:`ml_flags` field is a bitfield which can include the following flags. -The individual flags indicate either a calling convention or a binding -convention. Of the calling convention flags, only :const:`METH_VARARGS` and -:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS` -alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling -convention flags can be combined with a binding flag. - - -.. data:: METH_VARARGS - - This is the typical calling convention, where the methods have the type - :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. The - first one is the *self* object for methods; for module functions, it has the - value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was - used). The second parameter (often called *args*) is a tuple object - representing all arguments. This parameter is typically processed using - :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`. - - -.. data:: METH_KEYWORDS - - Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. The - function expects three parameters: *self*, *args*, and a dictionary of all the - keyword arguments. The flag is typically combined with :const:`METH_VARARGS`, - and the parameters are typically processed using - :cfunc:`PyArg_ParseTupleAndKeywords`. - - -.. data:: METH_NOARGS - - Methods without parameters don't need to check whether arguments are given if - they are listed with the :const:`METH_NOARGS` flag. They need to be of type - :ctype:`PyCFunction`. When used with object methods, the first parameter is - typically named ``self`` and will hold a reference to the object instance. In - all cases the second parameter will be *NULL*. - - -.. data:: METH_O - - Methods with a single object argument can be listed with the :const:`METH_O` - flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument. - They have the type :ctype:`PyCFunction`, with the *self* parameter, and a - :ctype:`PyObject\*` parameter representing the single argument. - - -These two constants are not used to indicate the calling convention but the -binding when use with methods of classes. These may not be used for functions -defined for modules. At most one of these flags may be set for any given -method. - - -.. data:: METH_CLASS - - .. index:: builtin: classmethod - - The method will be passed the type object as the first parameter rather than an - instance of the type. This is used to create *class methods*, similar to what - is created when using the :func:`classmethod` built-in function. - - -.. data:: METH_STATIC - - .. index:: builtin: staticmethod - - The method will be passed *NULL* as the first parameter rather than an instance - of the type. This is used to create *static methods*, similar to what is - created when using the :func:`staticmethod` built-in function. - -One other constant controls whether a method is loaded in place of another -definition with the same method name. - - -.. data:: METH_COEXIST - - The method will be loaded in place of existing definitions. Without - *METH_COEXIST*, the default is to skip repeated definitions. Since slot - wrappers are loaded before the method table, the existence of a *sq_contains* - slot, for example, would generate a wrapped method named :meth:`__contains__` - and preclude the loading of a corresponding PyCFunction with the same name. - With the flag defined, the PyCFunction will be loaded in place of the wrapper - object and will co-exist with the slot. This is helpful because calls to - PyCFunctions are optimized more than wrapper object calls. - - -.. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name) - - Return a bound method object for an extension type implemented in C. This can - be useful in the implementation of a :attr:`tp_getattro` or :attr:`tp_getattr` - handler that does not use the :cfunc:`PyObject_GenericGetAttr` function. - - -.. _type-structs: - -Type Objects -============ - -Perhaps one of the most important structures of the Python object system is the -structure that defines a new type: the :ctype:`PyTypeObject` structure. Type -objects can be handled using any of the :cfunc:`PyObject_\*` or -:cfunc:`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. - -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. - -Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc, -intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, -freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, -cmpfunc, reprfunc, hashfunc - -The structure definition for :ctype:`PyTypeObject` can be found in -:file:`Include/object.h`. For convenience of reference, this repeats the -definition found there: - -.. literalinclude:: ../includes/typestruct.h - - -The type object structure extends the :ctype:`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 :cdata:`PyType_Type` (the -metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e. -type objects) *must* have the :attr:`ob_size` field. - - -.. cmember:: PyObject* PyObject._ob_next - PyObject* PyObject._ob_prev - - 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. - - These fields are not inherited by subtypes. - - -.. cmember:: Py_ssize_t PyObject.ob_refcnt - - 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. - - This field is not inherited by subtypes. - - -.. cmember:: PyTypeObject* PyObject.ob_type - - 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:: - - Foo_Type.ob_type = &PyType_Type; - - This should be done before any instances of the type are created. - :cfunc:`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. - :cfunc:`PyType_Ready` will not change this field if it is non-zero. - - 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. - - -.. cmember:: Py_ssize_t PyVarObject.ob_size - - For statically allocated type objects, this should be initialized to zero. For - dynamically allocated type objects, this field has a special internal meaning. - - This field is not inherited by subtypes. - - -.. cmember:: char* PyTypeObject.tp_name - - 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 :attr:`tp_name` initializer ``"P.Q.M.T"``. - - 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__'``. - - 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:`__name__` attribute. - - If no dot is present, the entire :attr:`tp_name` field is made accessible as the - :attr:`__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. - - This field is not inherited by subtypes. - - -.. cmember:: Py_ssize_t PyTypeObject.tp_basicsize - Py_ssize_t PyTypeObject.tp_itemsize - - These fields allow calculating the size in bytes of instances of the type. - - There are two kinds of types: types with fixed-length instances have a zero - :attr:`tp_itemsize` field, types with variable-length instances have a non-zero - :attr:`tp_itemsize` field. For a type with fixed-length instances, all - instances have the same size, given in :attr:`tp_basicsize`. - - For a type with variable-length instances, the instances must have an - :attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N - times :attr:`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). - - The basic size includes the fields in the instance declared by the macro - :cmacro:`PyObject_HEAD` or :cmacro:`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 :attr:`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 :attr:`tp_basicsize`). - - These fields are inherited separately by subtypes. If the base type has a - non-zero :attr:`tp_itemsize`, it is generally not safe to set - :attr:`tp_itemsize` to a different non-zero value in a subtype (though this - depends on the implementation of the base type). - - A note about alignment: if the variable items require a particular alignment, - this should be taken care of by the value of :attr:`tp_basicsize`. Example: - suppose a type implements an array of ``double``. :attr:`tp_itemsize` is - ``sizeof(double)``. It is the programmer's responsibility that - :attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the - alignment requirement for ``double``). - - -.. cmember:: destructor PyTypeObject.tp_dealloc - - 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``). - - The destructor function is called by the :cfunc:`Py_DECREF` and - :cfunc:`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 :attr:`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 - :attr:`tp_free`. The object deallocator should be the one used to allocate the - instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated - using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or - :cfunc:`PyObject_GC_Del` if the instance was allocated using - :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`. - - This field is inherited by subtypes. - - -.. cmember:: printfunc PyTypeObject.tp_print - - An optional pointer to the instance print function. - - 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` instance), the - instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to - a string. These are also called when the type's :attr:`tp_print` field is - *NULL*. A type should never implement :attr:`tp_print` in a way that produces - different output than :attr:`tp_repr` or :attr:`tp_str` would. - - The print function is called with the same signature as :cfunc:`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 :attr:`tp_str` - would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance - should be printed the same was as :attr:`tp_repr` would format it. It should - return ``-1`` and set an exception condition when an error occurred during the - comparison. - - It is possible that the :attr:`tp_print` field will be deprecated. In any case, - it is recommended not to define :attr:`tp_print`, but instead to rely on - :attr:`tp_repr` and :attr:`tp_str` for printing. - - This field is inherited by subtypes. - - -.. cmember:: getattrfunc PyTypeObject.tp_getattr - - An optional pointer to the get-attribute-string function. - - This field is deprecated. When it is defined, it should point to a function - that acts the same as the :attr:`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 :cfunc:`PyObject_GetAttrString`. - - This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype - inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when - the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*. - - -.. cmember:: setattrfunc PyTypeObject.tp_setattr - - An optional pointer to the set-attribute-string function. - - This field is deprecated. When it is defined, it should point to a function - that acts the same as the :attr:`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 :cfunc:`PyObject_SetAttrString`. - - This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype - inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when - the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*. - - -.. cmember:: cmpfunc PyTypeObject.tp_compare - - An optional pointer to the three-way comparison function. - - The signature is the same as for :cfunc:`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. - - This field is inherited by subtypes together with :attr:`tp_richcompare` and - :attr:`tp_hash`: a subtypes inherits all three of :attr:`tp_compare`, - :attr:`tp_richcompare`, and :attr:`tp_hash` when the subtype's - :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*. - - -.. cmember:: reprfunc PyTypeObject.tp_repr - - .. index:: builtin: repr - - An optional pointer to a function that implements the built-in function - :func:`repr`. - - The signature is the same as for :cfunc:`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. - - 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. - - This field is inherited by subtypes. - -.. cmember:: PyNumberMethods* tp_as_number - - 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`. - - The :attr:`tp_as_number` field is not inherited, but the contained fields are - inherited individually. - - -.. cmember:: PySequenceMethods* tp_as_sequence - - 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`. - - The :attr:`tp_as_sequence` field is not inherited, but the contained fields - are inherited individually. - - -.. cmember:: PyMappingMethods* tp_as_mapping - - 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`. - - The :attr:`tp_as_mapping` field is not inherited, but the contained fields - are inherited individually. - - -.. cmember:: hashfunc PyTypeObject.tp_hash - - .. index:: builtin: hash - - An optional pointer to a function that implements the built-in function - :func:`hash`. - - The signature is the same as for :cfunc:`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``. - - When this field is not set, two possibilities exist: if the :attr:`tp_compare` - and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on - the object's address is returned; otherwise, a :exc:`TypeError` is raised. - - This field is inherited by subtypes together with :attr:`tp_richcompare` and - :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`, - :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's - :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*. - - -.. cmember:: ternaryfunc PyTypeObject.tp_call - - 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 :cfunc:`PyObject_Call`. - - This field is inherited by subtypes. - - -.. cmember:: reprfunc PyTypeObject.tp_str - - 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 :cfunc:`PyObject_Str` to do - the actual work, and :cfunc:`PyObject_Str` will call this handler.) - - The signature is the same as for :cfunc:`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, - among other things, by the :func:`print` function. - - When this field is not set, :cfunc:`PyObject_Repr` is called to return a string - representation. - - This field is inherited by subtypes. - - -.. cmember:: getattrofunc PyTypeObject.tp_getattro - - An optional pointer to the get-attribute function. - - The signature is the same as for :cfunc:`PyObject_GetAttr`. It is usually - convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which - implements the normal way of looking for object attributes. - - This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype - inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when - the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*. - - -.. cmember:: setattrofunc PyTypeObject.tp_setattro - - An optional pointer to the set-attribute function. - - The signature is the same as for :cfunc:`PyObject_SetAttr`. It is usually - convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which - implements the normal way of setting object attributes. - - This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype - inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when - the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*. - - -.. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer - - 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`. - - The :attr:`tp_as_buffer` field is not inherited, but the contained fields are - inherited individually. - - -.. cmember:: long PyTypeObject.tp_flags - - 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 - :attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and - :attr:`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. - - 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 :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the - :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the - :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as - indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL* - values. - - The following bit masks are currently defined; these can be ORed together using - the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro - :cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and - checks whether ``tp->tp_flags & f`` is non-zero. - - - .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER - - If this bit is set, the :ctype:`PyBufferProcs` struct referenced by - :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field. - - - .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN - - If this bit is set, the :ctype:`PySequenceMethods` struct referenced by - :attr:`tp_as_sequence` has the :attr:`sq_contains` field. - - - .. data:: Py_TPFLAGS_GC - - This bit is obsolete. The bit it used to name is no longer in use. The symbol - is now defined as zero. - - - .. data:: Py_TPFLAGS_HAVE_INPLACEOPS - - If this bit is set, the :ctype:`PySequenceMethods` struct referenced by - :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by - :attr:`tp_as_number` contain the fields for in-place operators. In particular, - this means that the :ctype:`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 - :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and - :attr:`sq_inplace_repeat`. - - - .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE - - If this bit is set, the type object has the :attr:`tp_richcompare` field, as - well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields. - - - .. data:: Py_TPFLAGS_HAVE_WEAKREFS - - If this bit is set, the :attr:`tp_weaklistoffset` field is defined. Instances - of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field - has a value greater than zero. - - - .. data:: Py_TPFLAGS_HAVE_ITER - - If this bit is set, the type object has the :attr:`tp_iter` and - :attr:`tp_iternext` fields. - - - .. data:: Py_TPFLAGS_HAVE_CLASS - - If this bit is set, the type object has several new fields defined starting in - Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`, - :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`, - :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`, - :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`, - :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`. - - - .. data:: Py_TPFLAGS_HEAPTYPE - - 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). - - - .. data:: Py_TPFLAGS_BASETYPE - - 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). - - - .. data:: Py_TPFLAGS_READY - - This bit is set when the type object has been fully initialized by - :cfunc:`PyType_Ready`. - - - .. data:: Py_TPFLAGS_READYING - - This bit is set while :cfunc:`PyType_Ready` is in the process of initializing - the type object. - - - .. data:: Py_TPFLAGS_HAVE_GC - - This bit is set when the object supports garbage collection. If this bit - is set, instances must be created using :cfunc:`PyObject_GC_New` and - destroyed using :cfunc:`PyObject_GC_Del`. More information in section - :ref:`supporting-cycle-detection`. This bit also implies that the - GC-related fields :attr:`tp_traverse` and :attr:`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. - - - .. data:: Py_TPFLAGS_DEFAULT - - 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`. - - -.. cmember:: char* PyTypeObject.tp_doc - - 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. - - This field is *not* inherited by subtypes. - -The following three fields only exist if the -:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set. - - -.. cmember:: traverseproc PyTypeObject.tp_traverse - - 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`. - - The :attr:`tp_traverse` pointer is used by the garbage collector to detect - reference cycles. A typical implementation of a :attr:`tp_traverse` function - simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python - objects. For exampe, this is function :cfunc:`local_traverse` from the - :mod:`thread` extension module:: - - static int - local_traverse(localobject *self, visitproc visit, void *arg) - { - Py_VISIT(self->args); - Py_VISIT(self->kw); - Py_VISIT(self->dict); - return 0; - } - - Note that :cfunc:`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. - - 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:`get_referents` function will include it. - - Note that :cfunc:`Py_VISIT` requires the *visit* and *arg* parameters to - :cfunc:`local_traverse` to have these specific names; don't name them just - anything. - - This field is inherited by subtypes together with :attr:`tp_clear` and the - :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and - :attr:`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. - - -.. cmember:: inquiry PyTypeObject.tp_clear - - 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. - - The :attr:`tp_clear` member function is used to break reference cycles in cyclic - garbage detected by the garbage collector. Taken together, all :attr:`tp_clear` - functions in the system must combine to break all reference cycles. This is - subtle, and if in any doubt supply a :attr:`tp_clear` function. For example, - the tuple type does not implement a :attr:`tp_clear` function, because it's - possible to prove that no reference cycle can be composed entirely of tuples. - Therefore the :attr:`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 :attr:`tp_clear`. - - Implementations of :attr:`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:: - - static int - local_clear(localobject *self) - { - Py_CLEAR(self->key); - Py_CLEAR(self->args); - Py_CLEAR(self->kw); - Py_CLEAR(self->dict); - return 0; - } - - The :cfunc:`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 - :cfunc:`Py_CLEAR` macro performs the operations in a safe order. - - Because the goal of :attr:`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 - :attr:`tp_dealloc` function to invoke :attr:`tp_clear`. - - More information about Python's garbage collection scheme can be found in - section :ref:`supporting-cycle-detection`. - - This field is inherited by subtypes together with :attr:`tp_traverse` and the - :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and - :attr:`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. - - -.. cmember:: richcmpfunc PyTypeObject.tp_richcompare - - An optional pointer to the rich comparison function. - - The signature is the same as for :cfunc:`PyObject_RichCompare`. 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. - - This field is inherited by subtypes together with :attr:`tp_compare` and - :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`, - :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's - :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*. - - The following constants are defined to be used as the third argument for - :attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`: - - +----------------+------------+ - | Constant | Comparison | - +================+============+ - | :const:`Py_LT` | ``<`` | - +----------------+------------+ - | :const:`Py_LE` | ``<=`` | - +----------------+------------+ - | :const:`Py_EQ` | ``==`` | - +----------------+------------+ - | :const:`Py_NE` | ``!=`` | - +----------------+------------+ - | :const:`Py_GT` | ``>`` | - +----------------+------------+ - | :const:`Py_GE` | ``>=`` | - +----------------+------------+ - -The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is -set. - - -.. cmember:: long PyTypeObject.tp_weaklistoffset - - 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 - :cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions. The - instance structure needs to include a field of type :ctype:`PyObject\*` which is - initialized to *NULL*. - - Do not confuse this field with :attr:`tp_weaklist`; that is the list head for - weak references to the type object itself. - - 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 - :attr:`tp_weaklistoffset`, this should not be a problem. - - When a type defined by a class statement has no :attr:`__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 :attr:`tp_weaklistoffset` of that slot's offset. - - 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 - :attr:`tp_weaklistoffset`. - - When a type's :attr:`__slots__` declaration does not contain a slot named - :attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its - base type. - -The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is -set. - - -.. cmember:: getiterfunc PyTypeObject.tp_iter - - 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). - - This function has the same signature as :cfunc:`PyObject_GetIter`. - - This field is inherited by subtypes. - - -.. cmember:: iternextfunc PyTypeObject.tp_iternext - - An optional pointer to a function that returns the next item in an iterator, or - raises :exc:`StopIteration` when the iterator is exhausted. 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:`__next__` method). - - Iterator types should also define the :attr:`tp_iter` function, and that - function should return the iterator instance itself (not a new iterator - instance). - - This function has the same signature as :cfunc:`PyIter_Next`. - - This field is inherited by subtypes. - -The next fields, up to and including :attr:`tp_weaklist`, only exist if the -:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set. - - -.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods - - An optional pointer to a static *NULL*-terminated array of :ctype:`PyMethodDef` - structures, declaring regular methods of this type. - - For each entry in the array, an entry is added to the type's dictionary (see - :attr:`tp_dict` below) containing a method descriptor. - - This field is not inherited by subtypes (methods are inherited through a - different mechanism). - - -.. cmember:: struct PyMemberDef* PyTypeObject.tp_members - - An optional pointer to a static *NULL*-terminated array of :ctype:`PyMemberDef` - structures, declaring regular data members (fields or slots) of instances of - this type. - - For each entry in the array, an entry is added to the type's dictionary (see - :attr:`tp_dict` below) containing a member descriptor. - - This field is not inherited by subtypes (members are inherited through a - different mechanism). - - -.. cmember:: struct PyGetSetDef* PyTypeObject.tp_getset - - An optional pointer to a static *NULL*-terminated array of :ctype:`PyGetSetDef` - structures, declaring computed attributes of instances of this type. - - For each entry in the array, an entry is added to the type's dictionary (see - :attr:`tp_dict` below) containing a getset descriptor. - - This field is not inherited by subtypes (computed attributes are inherited - through a different mechanism). - - Docs for PyGetSetDef (XXX belong elsewhere):: - - typedef PyObject *(*getter)(PyObject *, void *); - typedef int (*setter)(PyObject *, PyObject *, void *); - - typedef struct PyGetSetDef { - char *name; /* attribute name */ - getter get; /* C function to get the attribute */ - setter set; /* C function to set the attribute */ - char *doc; /* optional doc string */ - void *closure; /* optional additional data for getter and setter */ - } PyGetSetDef; - - -.. cmember:: PyTypeObject* PyTypeObject.tp_base - - 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. - - 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`). - - -.. cmember:: PyObject* PyTypeObject.tp_dict - - The type's dictionary is stored here by :cfunc:`PyType_Ready`. - - 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 :cfunc:`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__`). - - This field is not inherited by subtypes (though the attributes defined in here - are inherited through a different mechanism). - - -.. cmember:: descrgetfunc PyTypeObject.tp_descr_get - - An optional pointer to a "descriptor get" function. - - The function signature is :: - - PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); - - XXX explain. - - This field is inherited by subtypes. - - -.. cmember:: descrsetfunc PyTypeObject.tp_descr_set - - An optional pointer to a "descriptor set" function. - - The function signature is :: - - int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); - - This field is inherited by subtypes. - - XXX explain. - - -.. cmember:: long PyTypeObject.tp_dictoffset - - 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 - :cfunc:`PyObject_GenericGetAttr`. - - Do not confuse this field with :attr:`tp_dict`; that is the dictionary for - attributes of the type object itself. - - 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 :attr:`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, - :attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is - at the very end of the structure. - - The real dictionary offset in an instance can be computed from a negative - :attr:`tp_dictoffset` as follows:: - - dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset - if dictoffset is not aligned on sizeof(void*): - round up to sizeof(void*) - - where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`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 :cfunc:`_PyObject_GetDictPtr`.) - - 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 :attr:`tp_dictoffset`, this should not be a problem. - - When a type defined by a class statement has no :attr:`__slots__` declaration, - and none of its base types has an instance variable dictionary, a dictionary - slot is added to the instance layout and the :attr:`tp_dictoffset` is set to - that slot's offset. - - When a type defined by a class statement has a :attr:`__slots__` declaration, - the type inherits its :attr:`tp_dictoffset` from its base type. - - (Adding a slot named :attr:`__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.) - - -.. cmember:: initproc PyTypeObject.tp_init - - An optional pointer to an instance initialization function. - - 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. - - The function signature is :: - - int tp_init(PyObject *self, PyObject *args, PyObject *kwds) - - 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__`. - - The :attr:`tp_init` function, if not *NULL*, is called when an instance is - created normally by calling its type, after the type's :attr:`tp_new` function - has returned an instance of the type. If the :attr:`tp_new` function returns an - instance of some other type that is not a subtype of the original type, no - :attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a - subtype of the original type, the subtype's :attr:`tp_init` is called. (VERSION - NOTE: described here is what is implemented in Python 2.2.1 and later. In - Python 2.2, the :attr:`tp_init` of the type of the object returned by - :attr:`tp_new` was always called, if not *NULL*.) - - This field is inherited by subtypes. - - -.. cmember:: allocfunc PyTypeObject.tp_alloc - - An optional pointer to an instance allocation function. - - The function signature is :: - - PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems) - - 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 :attr:`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 :attr:`tp_basicsize`. - - Do not use this function to do any other instance initialization, not even to - allocate additional memory; that should be done by :attr:`tp_new`. - - 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 :cfunc:`PyType_GenericAlloc`, to force a standard heap allocation strategy. - That is also the recommended value for statically defined types. - - -.. cmember:: newfunc PyTypeObject.tp_new - - An optional pointer to an instance creation function. - - 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. - - The function signature is :: - - PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds) - - 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 :attr:`tp_new` - function is called; it may be a subtype of that type (but not an unrelated - type). - - The :attr:`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 :attr:`tp_init` handler. A good - rule of thumb is that for immutable types, all initialization should take place - in :attr:`tp_new`, while for mutable types, most initialization should be - deferred to :attr:`tp_init`. - - This field is inherited by subtypes, except it is not inherited by static types - whose :attr:`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. - - -.. cmember:: destructor PyTypeObject.tp_free - - An optional pointer to an instance deallocation function. - - The signature of this function has changed slightly: in Python 2.2 and 2.2.1, - its signature is :ctype:`destructor`:: - - void tp_free(PyObject *) - - In Python 2.3 and beyond, its signature is :ctype:`freefunc`:: - - void tp_free(void *) - - The only initializer that is compatible with both versions is ``PyObject_Free``, - whose definition has suitably adapted in Python 2.3. - - 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 :cfunc:`PyType_GenericAlloc` and the value of the - :const:`Py_TPFLAGS_HAVE_GC` flag bit. - - -.. cmember:: inquiry PyTypeObject.tp_is_gc - - An optional pointer to a function called by the garbage collector. - - 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 - :attr:`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 :: - - int tp_is_gc(PyObject *self) - - (The only example of this are types themselves. The metatype, - :cdata:`PyType_Type`, defines this function to distinguish between statically - and dynamically allocated types.) - - 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.) - - -.. cmember:: PyObject* PyTypeObject.tp_bases - - Tuple of base types. - - This is set for types created by a class statement. It should be *NULL* for - statically defined types. - - This field is not inherited. - - -.. cmember:: PyObject* PyTypeObject.tp_mro - - Tuple containing the expanded set of base types, starting with the type itself - and ending with :class:`object`, in Method Resolution Order. - - This field is not inherited; it is calculated fresh by :cfunc:`PyType_Ready`. - - -.. cmember:: PyObject* PyTypeObject.tp_cache - - Unused. Not inherited. Internal use only. - - -.. cmember:: PyObject* PyTypeObject.tp_subclasses - - List of weak references to subclasses. Not inherited. Internal use only. - - -.. cmember:: PyObject* PyTypeObject.tp_weaklist - - Weak reference list head, for weak references to this type object. Not - inherited. Internal use only. - -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. - - -.. cmember:: Py_ssize_t PyTypeObject.tp_allocs - - Number of allocations. - - -.. cmember:: Py_ssize_t PyTypeObject.tp_frees - - Number of frees. - - -.. cmember:: Py_ssize_t PyTypeObject.tp_maxalloc - - Maximum simultaneously allocated objects. - - -.. cmember:: PyTypeObject* PyTypeObject.tp_next - - Pointer to the next type object with a non-zero :attr:`tp_allocs` field. - -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. - - -.. _number-structs: - -Number Object Structures -======================== - -.. sectionauthor:: Amaury Forgeot d'Arc - - -.. ctype:: PyNumberMethods - - This structure holds pointers to the functions which an object uses to - implement the number protocol. Each function is used by the function of - similar name documented in the :ref:`number` section. - - Here is the structure definition:: - - typedef struct { - binaryfunc nb_add; - binaryfunc nb_subtract; - binaryfunc nb_multiply; - binaryfunc nb_remainder; - binaryfunc nb_divmod; - ternaryfunc nb_power; - unaryfunc nb_negative; - unaryfunc nb_positive; - unaryfunc nb_absolute; - inquiry nb_bool; - unaryfunc nb_invert; - binaryfunc nb_lshift; - binaryfunc nb_rshift; - binaryfunc nb_and; - binaryfunc nb_xor; - binaryfunc nb_or; - int nb_reserved; /* unused, must be zero */ - unaryfunc nb_int; - unaryfunc nb_long; - unaryfunc nb_float; - - unaryfunc nb_oct; /* not used anymore, must be zero */ - unaryfunc nb_hex; /* not used anymore, must be zero */ - - binaryfunc nb_inplace_add; - binaryfunc nb_inplace_subtract; - binaryfunc nb_inplace_multiply; - binaryfunc nb_inplace_remainder; - ternaryfunc nb_inplace_power; - binaryfunc nb_inplace_lshift; - binaryfunc nb_inplace_rshift; - binaryfunc nb_inplace_and; - binaryfunc nb_inplace_xor; - binaryfunc nb_inplace_or; - - binaryfunc nb_floor_divide; - binaryfunc nb_true_divide; - binaryfunc nb_inplace_floor_divide; - binaryfunc nb_inplace_true_divide; - - unaryfunc nb_index; - } PyNumberMethods; - - .. note:: - - 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). 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. - - -.. _mapping-structs: - -Mapping Object Structures -========================= - -.. sectionauthor:: Amaury Forgeot d'Arc - - -.. ctype:: PyMappingMethods - - This structure holds pointers to the functions which an object uses to - implement the mapping protocol. It has three members: - -.. cmember:: lenfunc PyMappingMethods.mp_length - - This function is used by :cfunc:`PyMapping_Length` and - :cfunc:`PyObject_Size`, and has the same signature. This slot may be set to - *NULL* if the object has no defined length. - -.. cmember:: binaryfunc PyMappingMethods.mp_subscript - - This function is used by :cfunc:`PyObject_GetItem` and has the same - signature. This slot must be filled for the :cfunc:`PyMapping_Check` - function to return ``1``, it can be *NULL* otherwise. - -.. cmember:: objobjargproc PyMappingMethods.mp_ass_subscript - - This function is used by :cfunc:`PyObject_SetItem` and has the same - signature. If this slot is *NULL*, the object does not support item - assignment. - - -.. _sequence-structs: - -Sequence Object Structures -========================== - -.. sectionauthor:: Amaury Forgeot d'Arc - - -.. ctype:: PySequenceMethods - - This structure holds pointers to the functions which an object uses to - implement the sequence protocol. - -.. cmember:: lenfunc PySequenceMethods.sq_length - - This function is used by :cfunc:`PySequence_Size` and :cfunc:`PyObject_Size`, - and has the same signature. - -.. cmember:: binaryfunc PySequenceMethods.sq_concat - - This function is used by :cfunc:`PySequence_Concat` and has the same - signature. It is also used by the ``+`` operator, after trying the numeric - addition via the :attr:`tp_as_number.nb_add` slot. - -.. cmember:: ssizeargfunc PySequenceMethods.sq_repeat - - This function is used by :cfunc:`PySequence_Repeat` and has the same - signature. It is also used by the ``*`` operator, after trying numeric - multiplication via the :attr:`tp_as_number.nb_mul` slot. - -.. cmember:: ssizeargfunc PySequenceMethods.sq_item - - This function is used by :cfunc:`PySequence_GetItem` and has the same - signature. This slot must be filled for the :cfunc:`PySequence_Check` - function to return ``1``, it can be *NULL* otherwise. - - 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. - -.. cmember:: ssizeobjargproc PySequenceMethods.sq_ass_item - - This function is used by :cfunc:`PySequence_SetItem` and has the same - signature. This slot may be left to *NULL* if the object does not support - item assignment. - -.. cmember:: objobjproc PySequenceMethods.sq_contains - - This function may be used by :cfunc:`PySequence_Contains` and has the same - signature. This slot may be left to *NULL*, in this case - :cfunc:`PySequence_Contains` simply traverses the sequence until it finds a - match. - -.. cmember:: binaryfunc PySequenceMethods.sq_inplace_concat - - This function is used by :cfunc:`PySequence_InPlaceConcat` and has the same - signature. It should modify its first operand, and return it. - -.. cmember:: ssizeargfunc PySequenceMethods.sq_inplace_repeat - - This function is used by :cfunc:`PySequence_InPlaceRepeat` and has the same - signature. It should modify its first operand, and return it. - -.. XXX need to explain precedence between mapping and sequence -.. XXX explains when to implement the sq_inplace_* slots - - -.. _buffer-structs: - -Buffer Object Structures -======================== - -.. sectionauthor:: Greg J. Stein <greg@lyra.org> - - -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. - -If an object does not export the buffer interface, then its :attr:`tp_as_buffer` -member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the -:attr:`tp_as_buffer` will point to a :ctype:`PyBufferProcs` structure. - -.. note:: - - It is very important that your :ctype:`PyTypeObject` structure uses - :const:`Py_TPFLAGS_DEFAULT` for the value of the :attr:`tp_flags` member rather - than ``0``. This tells the Python runtime that your :ctype:`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. - - -.. ctype:: PyBufferProcs - - Structure used to hold the function pointers which define an implementation of - the buffer protocol. - - The first slot is :attr:`bf_getreadbuffer`, of type :ctype:`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. - - The next slot is :attr:`bf_getwritebuffer` having type - :ctype:`getwritebufferproc`. This slot may be *NULL* if the object does not - allow writing into its returned buffers. - - The third slot is :attr:`bf_getsegcount`, with type :ctype:`getsegcountproc`. - This slot must not be *NULL* and is used to inform the caller how many segments - the object contains. Simple objects such as :ctype:`PyString_Type` and - :ctype:`PyBuffer_Type` objects contain a single segment. - - .. index:: single: PyType_HasFeature() - - The last slot is :attr:`bf_getcharbuffer`, of type :ctype:`getcharbufferproc`. - This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER` - flag is present in the :attr:`tp_flags` field of the object's - :ctype:`PyTypeObject`. Before using this slot, the caller should test whether it - is present by using the :cfunc:`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. - - .. note:: - - 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. - - -.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER - - 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*. - - -.. ctype:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr) - - 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. - - -.. ctype:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr) - - 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. - - .. Why doesn't it raise ValueError for this one? - GJS: because you shouldn't be calling it with an invalid - segment. That indicates a blatant programming error in the C code. - - -.. ctype:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp) - - 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. - - -.. ctype:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr) - - Return the size of the segment *segment* that *ptrptr* is set to. ``*ptrptr`` - is set to the memory buffer. Returns ``-1`` on error. - - -.. _supporting-iteration: - -Supporting the Iterator Protocol -================================ - - -.. _supporting-cycle-detection: - -Supporting Cyclic Garbage Collection -==================================== - -Python's support for detecting and collecting garbage which involves circular -references requires support from object types which are "containers" for other -objects which may also be containers. Types which do not store references to -other objects, or which only store references to atomic types (such as numbers -or strings), do not need to provide any explicit support for garbage collection. - -To create a container type, the :attr:`tp_flags` field of the type object must -include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the -:attr:`tp_traverse` handler. If instances of the type are mutable, a -:attr:`tp_clear` implementation must also be provided. - - -.. data:: Py_TPFLAGS_HAVE_GC - - Objects with a type with this flag set must conform with the rules documented - here. For convenience these objects will be referred to as container objects. - -Constructors for container types must conform to two rules: - -#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New` or - :cfunc:`PyObject_GC_VarNew`. - -#. Once all the fields which may contain references to other containers are - initialized, it must call :cfunc:`PyObject_GC_Track`. - - -.. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type) - - Analogous to :cfunc:`PyObject_New` but for container objects with the - :const:`Py_TPFLAGS_HAVE_GC` flag set. - - -.. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size) - - Analogous to :cfunc:`PyObject_NewVar` but for container objects with the - :const:`Py_TPFLAGS_HAVE_GC` flag set. - - -.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t) - - Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the resized - object or *NULL* on failure. - - -.. cfunction:: void PyObject_GC_Track(PyObject *op) - - Adds the object *op* to the set of container objects tracked by the collector. - The collector can run at unexpected times so objects must be valid while being - tracked. This should be called once all the fields followed by the - :attr:`tp_traverse` handler become valid, usually near the end of the - constructor. - - -.. cfunction:: void _PyObject_GC_TRACK(PyObject *op) - - A macro version of :cfunc:`PyObject_GC_Track`. It should not be used for - extension modules. - -Similarly, the deallocator for the object must conform to a similar pair of -rules: - -#. Before fields which refer to other containers are invalidated, - :cfunc:`PyObject_GC_UnTrack` must be called. - -#. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`. - - -.. cfunction:: void PyObject_GC_Del(void *op) - - Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or - :cfunc:`PyObject_GC_NewVar`. - - -.. cfunction:: void PyObject_GC_UnTrack(void *op) - - Remove the object *op* from the set of container objects tracked by the - collector. Note that :cfunc:`PyObject_GC_Track` can be called again on this - object to add it back to the set of tracked objects. The deallocator - (:attr:`tp_dealloc` handler) should call this for the object before any of the - fields used by the :attr:`tp_traverse` handler become invalid. - - -.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op) - - A macro version of :cfunc:`PyObject_GC_UnTrack`. It should not be used for - extension modules. - -The :attr:`tp_traverse` handler accepts a function parameter of this type: - - -.. ctype:: int (*visitproc)(PyObject *object, void *arg) - - Type of the visitor function passed to the :attr:`tp_traverse` handler. The - function should be called with an object to traverse as *object* and the third - parameter to the :attr:`tp_traverse` handler as *arg*. The Python core uses - several visitor functions to implement cyclic garbage detection; it's not - expected that users will need to write their own visitor functions. - -The :attr:`tp_traverse` handler must have the following type: - - -.. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg) - - Traversal function for a container object. Implementations must call the - *visit* function for each object directly contained by *self*, with the - parameters to *visit* being the contained object and the *arg* value passed to - the handler. The *visit* function must not be called with a *NULL* object - argument. If *visit* returns a non-zero value that value should be returned - immediately. - -To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is -provided. In order to use this macro, the :attr:`tp_traverse` implementation -must name its arguments exactly *visit* and *arg*: - - -.. cfunction:: void Py_VISIT(PyObject *o) - - Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a - non-zero value, then return it. Using this macro, :attr:`tp_traverse` handlers - look like:: - - static int - my_traverse(Noddy *self, visitproc visit, void *arg) - { - Py_VISIT(self->foo); - Py_VISIT(self->bar); - return 0; - } - -The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if -the object is immutable. - - -.. ctype:: int (*inquiry)(PyObject *self) - - Drop references that may have created reference cycles. Immutable objects do - not have to define this method since they can never directly create reference - cycles. Note that the object must still be valid after calling this method - (don't just call :cfunc:`Py_DECREF` on a reference). The collector will call - this method if it detects that this object is involved in a reference cycle. - diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index e6668b6..1b1b8ba 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -535,6 +535,35 @@ help message: default value. If an option has no default value (or the default value is ``None``), ``%default`` expands to ``none``. +When dealing with many options, it is convenient to group these +options for better help output. An :class:`OptionParser` can contain +several option groups, each of which can contain several options. + +Continuing with the parser defined above, adding an +:class:`OptionGroup` to a parser is easy:: + + group = OptionGroup(parser, "Dangerous Options", + "Caution: use these options at your own risk. " + "It is believed that some of them bite.") + group.add_option("-g", action="store_true", help="Group option.") + parser.add_option_group(group) + +This would result in the following help output:: + + usage: [options] arg1 arg2 + + options: + -h, --help show this help message and exit + -v, --verbose make lots of noise [default] + -q, --quiet be vewwy quiet (I'm hunting wabbits) + -fFILE, --file=FILE write output to FILE + -mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate' + [default], 'expert' + + Dangerous Options: + Caution: use of these options is at your own risk. It is believed that + some of them bite. + -g Group option. .. _optparse-printing-version-string: diff --git a/Doc/library/os.rst b/Doc/library/os.rst index c4f6e64..66316dd 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -378,6 +378,20 @@ by file descriptors. :func:`fdopen`, use its :meth:`close` method. +.. function:: closerange(fd_low, fd_high) + + Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive), + ignoring errors. Availability: Macintosh, Unix, Windows. Equivalent to:: + + for fd in xrange(fd_low, fd_high): + try: + os.close(fd) + except OSError: + pass + + .. versionadded:: 2.6 + + .. function:: device_encoding(fd) Return a string describing the encoding of the device associated with *fd* diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 9d12d34..02c2fa4 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1,4 +1,3 @@ - :mod:`sqlite3` --- DB-API 2.0 interface for SQLite databases ============================================================ @@ -387,7 +386,7 @@ A :class:`Cursor` instance has the following attributes and methods: .. method:: Cursor.execute(sql, [parameters]) - Executes a SQL statement. The SQL statement may be parametrized (i. e. + Executes an SQL statement. The SQL statement may be parametrized (i. e. placeholders instead of SQL literals). The :mod:`sqlite3` module supports two kinds of placeholders: question marks (qmark style) and named placeholders (named style). @@ -408,7 +407,7 @@ A :class:`Cursor` instance has the following attributes and methods: .. method:: Cursor.executemany(sql, seq_of_parameters) - Executes a SQL command against all parameter sequences or mappings found in + Executes an SQL command against all parameter sequences or mappings found in the sequence *sql*. The :mod:`sqlite3` module also allows using an :term:`iterator` yielding parameters instead of a sequence. @@ -432,6 +431,35 @@ A :class:`Cursor` instance has the following attributes and methods: .. literalinclude:: ../includes/sqlite3/executescript.py +.. method:: Cursor.fetchone() + + Fetches the next row of a query result set, returning a single sequence, + or ``None`` when no more data is available. + + +.. method:: Cursor.fetchmany([size=cursor.arraysize]) + + Fetches the next set of rows of a query result, returning a list. An empty + list is returned when no more rows are available. + + The number of rows to fetch per call is specified by the *size* parameter. + If it is not given, the cursor's arraysize determines the number of rows + to be fetched. The method should try to fetch as many rows as indicated by + the size parameter. If this is not possible due to the specified number of + rows not being available, fewer rows may be returned. + + Note there are performance considerations involved with the *size* parameter. + For optimal performance, it is usually best to use the arraysize attribute. + If the *size* parameter is used, then it is best for it to retain the same + value from one :meth:`fetchmany` call to the next. + +.. method:: Cursor.fetchall() + + Fetches all (remaining) rows of a query result, returning a list. Note that + the cursor's arraysize attribute can affect the performance of this operation. + An empty list is returned when no rows are available. + + .. attribute:: Cursor.rowcount Although the :class:`Cursor` class of the :mod:`sqlite3` module implements this diff --git a/Doc/library/xml.sax.utils.rst b/Doc/library/xml.sax.utils.rst index cd16348..43bf69e 100644 --- a/Doc/library/xml.sax.utils.rst +++ b/Doc/library/xml.sax.utils.rst @@ -19,7 +19,8 @@ or as base classes. You can escape other strings of data by passing a dictionary as the optional *entities* parameter. The keys and values must all be strings; each key will be - replaced with its corresponding value. + replaced with its corresponding value. The characters ``'&'``, ``'<'`` and + ``'>'`` are always escaped, even if *entities* is provided. .. function:: unescape(data[, entities]) @@ -28,7 +29,8 @@ or as base classes. You can unescape other strings of data by passing a dictionary as the optional *entities* parameter. The keys and values must all be strings; each key will be - replaced with its corresponding value. + replaced with its corresponding value. ``'&'``, ``'<'``, and ``'>'`` + are always unescaped, even if *entities* is provided. .. function:: quoteattr(data[, entities]) diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index f647bca..c90f946 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -19,7 +19,8 @@ added to individual archive members---for which see the :ref:`zipinfo-objects` documentation). It can handle ZIP files that use the ZIP64 extensions (that is ZIP files that are more than 4 GByte in size). It supports decryption of encrypted files in ZIP archives, but it currently cannot -create an encrypted file. +create an encrypted file. Decryption is extremely slow as it is +implemented in native python rather than C. For other archive formats, see the :mod:`bz2`, :mod:`gzip`, and :mod:`tarfile` modules. diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index e386b36..83101bd 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -868,16 +868,19 @@ complete list of changes, or look through the CVS logs for all the details. .. Revision 57769 - * A new method in the :mod:`curses` module: for a window, :meth:`chgat` changes the display characters for a certain number of characters on a single line. + (Contributed by Fabian Kreutz.) :: # Boldface text starting at y=0,x=21 # and affecting the rest of the line. stdscr.chgat(0,21, curses.A_BOLD) - (Contributed by Fabian Kreutz.) + The :class:`Textbox` class in the :mod:`curses.textpad` module + now supports editing in insert mode as well as overwrite mode. + Insert mode is enabled by supplying a true value for the *insert_mode* + parameter when creating the :class:`Textbox` instance. * The :mod:`decimal` module was updated to version 1.66 of `the General Decimal Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`__. New features diff --git a/Lib/curses/textpad.py b/Lib/curses/textpad.py index 24a964a..a05b82b 100644 --- a/Lib/curses/textpad.py +++ b/Lib/curses/textpad.py @@ -39,8 +39,9 @@ class Textbox: KEY_LEFT = Ctrl-B, KEY_RIGHT = Ctrl-F, KEY_UP = Ctrl-P, KEY_DOWN = Ctrl-N KEY_BACKSPACE = Ctrl-h """ - def __init__(self, win): + def __init__(self, win, insert_mode=False): self.win = win + self.insert_mode = insert_mode (self.maxy, self.maxx) = win.getmaxyx() self.maxy = self.maxy - 1 self.maxx = self.maxx - 1 @@ -49,9 +50,10 @@ class Textbox: win.keypad(1) def _end_of_line(self, y): - "Go to the location of the first blank on the given line." + """Go to the location of the first blank on the given line, + returning the index of the last non-blank character.""" last = self.maxx - while 1: + while True: if ascii.ascii(self.win.inch(y, last)) != ascii.SP: last = min(self.maxx, last+1) break @@ -60,19 +62,31 @@ class Textbox: last = last - 1 return last + def _insert_printable_char(self, ch): + (y, x) = self.win.getyx() + if y < self.maxy or x < self.maxx: + if self.insert_mode: + oldch = self.win.inch() + # The try-catch ignores the error we trigger from some curses + # versions by trying to write into the lowest-rightmost spot + # in the window. + try: + self.win.addch(ch) + except curses.error: + pass + if self.insert_mode: + (backy, backx) = self.win.getyx() + if ascii.isprint(oldch): + self._insert_printable_char(oldch) + self.win.move(backy, backx) + def do_command(self, ch): "Process a single editing command." (y, x) = self.win.getyx() self.lastcmd = ch if ascii.isprint(ch): if y < self.maxy or x < self.maxx: - # The try-catch ignores the error we trigger from some curses - # versions by trying to write into the lowest-rightmost spot - # in the window. - try: - self.win.addch(ch) - except curses.error: - pass + self._insert_printable_char(ch) elif ch == ascii.SOH: # ^a self.win.move(y, 0) elif ch in (ascii.STX,curses.KEY_LEFT, ascii.BS,curses.KEY_BACKSPACE): @@ -139,7 +153,7 @@ class Textbox: if stop == 0 and self.stripspaces: continue for x in range(self.maxx+1): - if self.stripspaces and x == stop: + if self.stripspaces and x > stop: break result = result + chr(ascii.ascii(self.win.inch(y, x))) if self.maxy > 0: diff --git a/Lib/mailbox.py b/Lib/mailbox.py index 13e3eb7..d2db53f 100755 --- a/Lib/mailbox.py +++ b/Lib/mailbox.py @@ -313,7 +313,10 @@ class Maildir(Mailbox): subpath = self._lookup(key) f = open(os.path.join(self._path, subpath), 'r') try: - msg = MaildirMessage(f) + if self._factory: + msg = self._factory(f) + else: + msg = MaildirMessage(f) finally: f.close() subdir, name = os.path.split(subpath) diff --git a/Lib/subprocess.py b/Lib/subprocess.py index 56e05a3..5aee34d 100644 --- a/Lib/subprocess.py +++ b/Lib/subprocess.py @@ -289,6 +289,7 @@ mswindows = (sys.platform == "win32") import io import os import traceback +import gc # Exception classes used by this module. class CalledProcessError(Exception): @@ -397,8 +398,8 @@ def list2cmdline(seq): 2) A string surrounded by double quotation marks is interpreted as a single argument, regardless of white space - contained within. A quoted string can be embedded in an - argument. + or pipe characters contained within. A quoted string can be + embedded in an argument. 3) A double quotation mark preceded by a backslash is interpreted as a literal double quotation mark. @@ -424,7 +425,7 @@ def list2cmdline(seq): if result: result.append(' ') - needquote = (" " in arg) or ("\t" in arg) or arg == "" + needquote = (" " in arg) or ("\t" in arg) or ("|" in arg) or not arg if needquote: result.append('"') @@ -433,7 +434,7 @@ def list2cmdline(seq): # Don't know if we need to double yet. bs_buf.append(c) elif c == '"': - # Double backspaces. + # Double backslashes. result.append('\\' * len(bs_buf)*2) bs_buf = [] result.append('\\"') @@ -444,7 +445,7 @@ def list2cmdline(seq): bs_buf = [] result.append(c) - # Add remaining backspaces, if any. + # Add remaining backslashes, if any. if bs_buf: result.extend(bs_buf) @@ -887,13 +888,8 @@ class Popen(object): def _close_fds(self, but): - for i in range(3, MAXFD): - if i == but: - continue - try: - os.close(i) - except: - pass + os.closerange(3, but) + os.closerange(but + 1, MAXFD) def _execute_child(self, args, executable, preexec_fn, close_fds, @@ -921,7 +917,16 @@ class Popen(object): errpipe_read, errpipe_write = os.pipe() self._set_cloexec_flag(errpipe_write) - self.pid = os.fork() + gc_was_enabled = gc.isenabled() + # Disable gc to avoid bug where gc -> file_dealloc -> + # write to stderr -> hang. http://bugs.python.org/issue1336 + gc.disable() + try: + self.pid = os.fork() + except: + if gc_was_enabled: + gc.enable() + raise self._child_created = True if self.pid == 0: # Child @@ -982,6 +987,8 @@ class Popen(object): os._exit(255) # Parent + if gc_was_enabled: + gc.enable() os.close(errpipe_write) if p2cread is not None and p2cwrite is not None: os.close(p2cread) diff --git a/Lib/test/curses_tests.py b/Lib/test/curses_tests.py new file mode 100644 index 0000000..7dedbbc --- /dev/null +++ b/Lib/test/curses_tests.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python +# +# $Id: ncurses.py 36559 2004-07-18 05:56:09Z tim_one $ +# +# Interactive test suite for the curses module. +# This script displays various things and the user should verify whether +# they display correctly. +# + +import curses +from curses import textpad + +def test_textpad(stdscr, insert_mode=False): + ncols, nlines = 8, 3 + uly, ulx = 3, 2 + if insert_mode: + mode = 'insert mode' + else: + mode = 'overwrite mode' + + stdscr.addstr(uly-3, ulx, "Use Ctrl-G to end editing (%s)." % mode) + stdscr.addstr(uly-2, ulx, "Be sure to try typing in the lower-right corner.") + win = curses.newwin(nlines, ncols, uly, ulx) + textpad.rectangle(stdscr, uly-1, ulx-1, uly + nlines, ulx + ncols) + stdscr.refresh() + + box = textpad.Textbox(win, insert_mode) + contents = box.edit() + stdscr.addstr(uly+ncols+2, 0, "Text entered in the box\n") + stdscr.addstr(repr(contents)) + stdscr.addstr('\n') + stdscr.addstr('Press any key') + stdscr.getch() + + for i in range(3): + stdscr.move(uly+ncols+2 + i, 0) + stdscr.clrtoeol() + +def main(stdscr): + stdscr.clear() + test_textpad(stdscr, False) + test_textpad(stdscr, True) + + +if __name__ == '__main__': + curses.wrapper(main) diff --git a/Lib/test/test_mailbox.py b/Lib/test/test_mailbox.py index a714255..918116a 100644 --- a/Lib/test/test_mailbox.py +++ b/Lib/test/test_mailbox.py @@ -506,6 +506,20 @@ class TestMaildir(TestMailbox): self.assertEqual(msg_returned.get_flags(), 'S') self.assertEqual(msg_returned.get_payload(), '3') + def test_consistent_factory(self): + # Add a message. + msg = mailbox.MaildirMessage(self._template % 0) + msg.set_subdir('cur') + msg.set_flags('RF') + key = self._box.add(msg) + + # Create new mailbox with + class FakeMessage(mailbox.MaildirMessage): + pass + box = mailbox.Maildir(self._path, factory=FakeMessage) + msg2 = box.get_message(key) + self.assert_(isinstance(msg2, FakeMessage)) + def test_initialize_new(self): # Initialize a non-existent mailbox self.tearDown() diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py index 15ed557..6cabb82 100644 --- a/Lib/test/test_os.py +++ b/Lib/test/test_os.py @@ -20,6 +20,11 @@ class FileTests(unittest.TestCase): os.close(f) self.assert_(os.access(test_support.TESTFN, os.W_OK)) + def test_closerange(self): + f = os.open(test_support.TESTFN, os.O_CREAT|os.O_RDWR) + # close a fd that is open, and one that isn't + os.closerange(f, f+2) + self.assertRaises(OSError, os.write, f, "a") # Test attributes on return values from os.*stat* family. class StatAttributeTests(unittest.TestCase): diff --git a/Lib/test/test_subprocess.py b/Lib/test/test_subprocess.py index a46bc38..e6acce3 100644 --- a/Lib/test/test_subprocess.py +++ b/Lib/test/test_subprocess.py @@ -413,6 +413,8 @@ class ProcessTestCase(unittest.TestCase): '"a b c" d e') self.assertEqual(subprocess.list2cmdline(['ab"c', '\\', 'd']), 'ab\\"c \\ d') + self.assertEqual(subprocess.list2cmdline(['ab"c', ' \\', 'd']), + 'ab\\"c " \\\\" d') self.assertEqual(subprocess.list2cmdline(['a\\\\\\b', 'de fg', 'h']), 'a\\\\\\b "de fg" h') self.assertEqual(subprocess.list2cmdline(['a\\"b', 'c', 'd']), @@ -423,6 +425,8 @@ class ProcessTestCase(unittest.TestCase): '"a\\\\b\\ c" d e') self.assertEqual(subprocess.list2cmdline(['ab', '']), 'ab ""') + self.assertEqual(subprocess.list2cmdline(['echo', 'foo|bar']), + 'echo "foo|bar"') def test_poll(self): diff --git a/Lib/test/test_zipfile.py b/Lib/test/test_zipfile.py index 7e401da..1b14d2a 100644 --- a/Lib/test/test_zipfile.py +++ b/Lib/test/test_zipfile.py @@ -686,31 +686,52 @@ class DecryptionTests(unittest.TestCase): b'\x1a\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x01\x00 \x00\xb6\x81' b'\x00\x00\x00\x00test.txtPK\x05\x06\x00\x00\x00\x00\x01\x00\x01\x006\x00' b'\x00\x00L\x00\x00\x00\x00\x00' ) + data2 = ( + b'PK\x03\x04\x14\x00\t\x00\x08\x00\xcf}38xu\xaa\xb2\x14\x00\x00\x00\x00\x02' + b'\x00\x00\x04\x00\x15\x00zeroUT\t\x00\x03\xd6\x8b\x92G\xda\x8b\x92GUx\x04' + b'\x00\xe8\x03\xe8\x03\xc7<M\xb5a\xceX\xa3Y&\x8b{oE\xd7\x9d\x8c\x98\x02\xc0' + b'PK\x07\x08xu\xaa\xb2\x14\x00\x00\x00\x00\x02\x00\x00PK\x01\x02\x17\x03' + b'\x14\x00\t\x00\x08\x00\xcf}38xu\xaa\xb2\x14\x00\x00\x00\x00\x02\x00\x00' + b'\x04\x00\r\x00\x00\x00\x00\x00\x00\x00\x00\x00\xa4\x81\x00\x00\x00\x00ze' + b'roUT\x05\x00\x03\xd6\x8b\x92GUx\x00\x00PK\x05\x06\x00\x00\x00\x00\x01' + b'\x00\x01\x00?\x00\x00\x00[\x00\x00\x00\x00\x00' ) plain = b'zipfile.py encryption test' + plain2 = b'\x00'*512 def setUp(self): fp = open(TESTFN, "wb") fp.write(self.data) fp.close() self.zip = zipfile.ZipFile(TESTFN, "r") + fp = open(TESTFN2, "wb") + fp.write(self.data2) + fp.close() + self.zip2 = zipfile.ZipFile(TESTFN2, "r") def tearDown(self): self.zip.close() os.unlink(TESTFN) + self.zip2.close() + os.unlink(TESTFN2) def testNoPassword(self): # Reading the encrypted file without password # must generate a RunTime exception self.assertRaises(RuntimeError, self.zip.read, "test.txt") + self.assertRaises(RuntimeError, self.zip2.read, "zero") def testBadPassword(self): self.zip.setpassword(b"perl") self.assertRaises(RuntimeError, self.zip.read, "test.txt") + self.zip2.setpassword(b"perl") + self.assertRaises(RuntimeError, self.zip2.read, "zero") def testGoodPassword(self): self.zip.setpassword(b"python") self.assertEquals(self.zip.read("test.txt"), self.plain) + self.zip2.setpassword(b"12345") + self.assertEquals(self.zip2.read("zero"), self.plain2) class TestsWithRandomBinaryFiles(unittest.TestCase): diff --git a/Lib/zipfile.py b/Lib/zipfile.py index 9f98728..2865c0a 100644 --- a/Lib/zipfile.py +++ b/Lib/zipfile.py @@ -34,9 +34,9 @@ ZIP_DEFLATED = 8 # Other ZIP compression methods not supported # Here are some struct module formats for reading headers -structEndArchive = "<4s4H2lH" # 9 items, end of archive, 22 bytes +structEndArchive = "<4s4H2LH" # 9 items, end of archive, 22 bytes stringEndArchive = b"PK\005\006" # magic number for end of archive record -structCentralDir = "<4s4B4HlLL5HLl"# 19 items, central directory, 46 bytes +structCentralDir = "<4s4B4HlLL5HLL"# 19 items, central directory, 46 bytes stringCentralDir = b"PK\001\002" # magic number for central directory structFileHeader = "<4s2B4HlLL2H" # 12 items, file header record, 30 bytes stringFileHeader = b"PK\003\004" # magic number for file header @@ -188,6 +188,7 @@ class ZipInfo (object): 'CRC', 'compress_size', 'file_size', + '_raw_time', ) def __init__(self, filename="NoName", date_time=(1980,1,1,0,0,0)): @@ -303,7 +304,7 @@ class _ZipDecrypter: ZIP supports a password-based form of encryption. Even though known plaintext attacks have been found against it, it is still useful - for low-level securicy. + to be able to get data out of such a file. Usage: zd = _ZipDecrypter(mypwd) @@ -690,6 +691,7 @@ class ZipFile: x.CRC, x.compress_size, x.file_size) = centdir[1:12] x.volume, x.internal_attr, x.external_attr = centdir[15:18] # Convert date/time code to (year, month, day, hour, min, sec) + x._raw_time = t x.date_time = ( (d>>9)+1980, (d>>5)&0xF, d&0x1F, t>>11, (t>>5)&0x3F, (t&0x1F) * 2 ) @@ -800,11 +802,18 @@ class ZipFile: # The first 12 bytes in the cypher stream is an encryption header # used to strengthen the algorithm. The first 11 bytes are # completely random, while the 12th contains the MSB of the CRC, + # or the MSB of the file time depending on the header type # and is used to check the correctness of the password. bytes = zef_file.read(12) h = list(map(zd, bytes[0:12])) - if h[11] != ((zinfo.CRC>>24) & 255): - raise RuntimeError("Bad password for file %s" % name) + if zinfo.flag_bits & 0x8: + # compare against the file type from extended local headers + check_byte = (zinfo._raw_time >> 8) & 0xff + else: + # compare against the CRC otherwise + check_byte = (zinfo.CRC >> 24) & 0xff + if h[11] != check_byte: + raise RuntimeError("Bad password for file", name) # build and return a ZipExtFile if zd is None: @@ -593,6 +593,7 @@ Chad J. Schroeder Sam Schulenburg Stefan Schwarzer Dietmar Schwertberger +Federico Schwindt Barry Scott Steven Scott Nick Seidenman @@ -701,6 +702,7 @@ Bob Watson Aaron Watters Henrik Weber Corran Webster +Stefan Wehr Zack Weinberg Edward Welbourne Cliff Wells diff --git a/Modules/_sqlite/cursor.c b/Modules/_sqlite/cursor.c index d723cdb..6b81851 100644 --- a/Modules/_sqlite/cursor.c +++ b/Modules/_sqlite/cursor.c @@ -973,11 +973,11 @@ static PyMethodDef cursor_methods[] = { {"executescript", (PyCFunction)pysqlite_cursor_executescript, METH_VARARGS, PyDoc_STR("Executes a multiple SQL statements at once. Non-standard.")}, {"fetchone", (PyCFunction)pysqlite_cursor_fetchone, METH_NOARGS, - PyDoc_STR("Fetches several rows from the resultset.")}, + PyDoc_STR("Fetches one row from the resultset.")}, {"fetchmany", (PyCFunction)pysqlite_cursor_fetchmany, METH_VARARGS, - PyDoc_STR("Fetches all rows from the resultset.")}, + PyDoc_STR("Fetches several rows from the resultset.")}, {"fetchall", (PyCFunction)pysqlite_cursor_fetchall, METH_NOARGS, - PyDoc_STR("Fetches one row from the resultset.")}, + PyDoc_STR("Fetches all rows from the resultset.")}, {"close", (PyCFunction)pysqlite_cursor_close, METH_NOARGS, PyDoc_STR("Closes the cursor.")}, {"setinputsizes", (PyCFunction)pysqlite_noop, METH_VARARGS, diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index f3df9b7..9fe5790 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -4716,6 +4716,24 @@ posix_close(PyObject *self, PyObject *args) } +PyDoc_STRVAR(posix_closerange__doc__, +"closerange(fd_low, fd_high)\n\n\ +Closes all file descriptors in [fd_low, fd_high), ignoring errors."); + +static PyObject * +posix_closerange(PyObject *self, PyObject *args) +{ + int fd_from, fd_to, i; + if (!PyArg_ParseTuple(args, "ii:closerange", &fd_from, &fd_to)) + return NULL; + Py_BEGIN_ALLOW_THREADS + for (i = fd_from; i < fd_to; i++) + close(i); + Py_END_ALLOW_THREADS + Py_RETURN_NONE; +} + + PyDoc_STRVAR(posix_dup__doc__, "dup(fd) -> fd2\n\n\ Return a duplicate of a file descriptor."); @@ -6919,6 +6937,7 @@ static PyMethodDef posix_methods[] = { #endif /* HAVE_TCSETPGRP */ {"open", posix_open, METH_VARARGS, posix_open__doc__}, {"close", posix_close, METH_VARARGS, posix_close__doc__}, + {"closerange", posix_closerange, METH_VARARGS, posix_closerange__doc__}, {"device_encoding", device_encoding, METH_VARARGS, device_encoding__doc__}, {"dup", posix_dup, METH_VARARGS, posix_dup__doc__}, {"dup2", posix_dup2, METH_VARARGS, posix_dup2__doc__}, diff --git a/Modules/socketmodule.c b/Modules/socketmodule.c index 37e7caa..5eb5a1e 100644 --- a/Modules/socketmodule.c +++ b/Modules/socketmodule.c @@ -1904,15 +1904,22 @@ internal_connect(PySocketSockObject *s, struct sockaddr *addr, int addrlen, #else if (s->sock_timeout > 0.0) { - if (res < 0 && errno == EINPROGRESS && IS_SELECTABLE(s)) { - timeout = internal_select(s, 1); - if (timeout == 0) { - res = connect(s->sock_fd, addr, addrlen); - if (res < 0 && errno == EISCONN) - res = 0; - } - else if (timeout == -1) - res = errno; /* had error */ + if (res < 0 && errno == EINPROGRESS && IS_SELECTABLE(s)) { + timeout = internal_select(s, 1); + if (timeout == 0) { + /* Bug #1019808: in case of an EINPROGRESS, + use getsockopt(SO_ERROR) to get the real + error. */ + socklen_t res_size = sizeof res; + (void)getsockopt(s->sock_fd, SOL_SOCKET, + SO_ERROR, &res, &res_size); + if (res == EISCONN) + res = 0; + errno = res; + } + else if (timeout == -1) { + res = errno; /* had error */ + } else res = EWOULDBLOCK; /* timed out */ } |