.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
- Get an :class:`IncrementalEncoder` object for the given *encoding*.
+ Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*.
.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
- Get an :class:`IncrementalDecoder` object for the given *encoding*.
+ Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*.
.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
- Get a :class:`StreamReader` factory function for the given *encoding*.
+ Get a :class:`~codecs.StreamReader` factory function for the given *encoding*.
.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
- Get a :class:`StreamWriter` factory function for the given *encoding*.
+ Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*.
Registry API for Unicode encoding error handlers
Return the file descriptor associated with *p* as an :c:type:`int`. If the
object is an integer, its value is returned. If not, the
- object's :meth:`fileno` method is called if it exists; the method must return
- an integer, which is returned as the file descriptor value. Sets an
- exception and returns ``-1`` on failure.
+ object's :meth:`~io.IOBase.fileno` method is called if it exists; the
+ method must return an integer, which is returned as the file descriptor
+ value. Sets an exception and returns ``-1`` on failure.
.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
.. index:: single: EOFError (built-in exception)
Equivalent to ``p.readline([n])``, this function reads one line from the
- object *p*. *p* may be a file object or any object with a :meth:`readline`
+ object *p*. *p* may be a file object or any object with a
+ :meth:`~io.IOBase.readline`
method. If *n* is ``0``, exactly one line is read, regardless of the length of
the line. If *n* is greater than ``0``, no more than *n* bytes will be read
from the file; a partial line can be returned. In both cases, an empty string
Generic attribute getter function that is meant to be put into a type
object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
of classes in the object's MRO as well as an attribute in the object's
- :attr:`__dict__` (if present). As outlined in :ref:`descriptors`, data
- descriptors take preference over instance attributes, while non-data
+ :attr:`~object.__dict__` (if present). As outlined in :ref:`descriptors`,
+ data descriptors take preference over instance attributes, while non-data
descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
object's ``tp_setattro`` slot. It looks for a data descriptor in the
dictionary of classes in the object's MRO, and if found it takes preference
over setting the attribute in the instance dictionary. Otherwise, the
- attribute is set in the object's :attr:`__dict__` (if present). Otherwise,
- an :exc:`AttributeError` is raised and ``-1`` is returned.
+ attribute is set in the object's :attr:`~object.__dict__` (if present).
+ Otherwise, an :exc:`AttributeError` is raised and ``-1`` is returned.
.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
be done against every entry in *cls*. The result will be ``1`` when at least one
of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
class instance and *cls* is neither a type object, nor a class object, nor a
- tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship
- of the value of that attribute with *cls* will be used to determine the result
- of this function.
+ tuple, *inst* must have a :attr:`~instance.__class__` attribute --- the
+ class relationship of the value of that attribute with *cls* will be used
+ to determine the result of this function.
Subclass determination is done in a fairly straightforward way, but includes a
either is not a class object, a more general mechanism is used to determine the
class relationship of the two objects. When testing if *B* is a subclass of
*A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*
-are different objects, *B*'s :attr:`__bases__` attribute is searched in a
-depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
-is considered sufficient for this determination.
+are different objects, *B*'s :attr:`~class.__bases__` attribute is searched in
+a depth-first fashion for *A* --- the presence of the :attr:`~class.__bases__`
+attribute is considered sufficient for this determination.
.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
- :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`discard`
+ :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
method, this function does not automatically convert unhashable sets into
temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
instance of :class:`set` or its subtype.
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.
+ :func:`~gc.get_referents` function will include it.
Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
:c:func:`local_traverse` to have these specific names; don't name them just
reference list head than the base type. Since the list head is always found via
:c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem.
- When a type defined by a class statement has no :attr:`__slots__` declaration,
+ When a type defined by a class statement has no :attr:`~object.__slots__` declaration,
and none of its base types are weakly referenceable, the type is made weakly
referenceable by adding a weak reference list head slot to the instance layout
and setting the :c:member:`~PyTypeObject.tp_weaklistoffset` of that slot's offset.
dictionary at a difference offset than the base type. Since the dictionary is
always found via :c:member:`~PyTypeObject.tp_dictoffset`, this should not be a problem.
- When a type defined by a class statement has no :attr:`__slots__` declaration,
+ When a type defined by a class statement has no :attr:`~object.__slots__` declaration,
and none of its base types has an instance variable dictionary, a dictionary
slot is added to the instance layout and the :c:member:`~PyTypeObject.tp_dictoffset` is set to
that slot's offset.
When a type defined by a class statement has a :attr:`__slots__` declaration,
the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` from its base type.
- (Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does
+ (Adding a slot named :attr:`~object.__dict__` to the :attr:`__slots__` declaration does
not have the expected effect, it just causes confusion. Maybe this should be
added as a feature just like :attr:`__weakref__` though.)
Create a Unicode object by decoding *size* bytes of the encoded string *s*.
*encoding* and *errors* have the same meaning as the parameters of the same name
- in the :func:`unicode` built-in function. The codec to be used is looked up
+ in the :func:`str` built-in function. The codec to be used is looked up
using the Python codec registry. Return *NULL* if an exception was raised by
the codec.
Encode a Unicode object and return the result as Python bytes object.
*encoding* and *errors* have the same meaning as the parameters of the same
- name in the Unicode :meth:`encode` method. The codec to be used is looked up
+ name in the Unicode :meth:`~str.encode` method. The codec to be used is looked up
using the Python codec registry. Return *NULL* if an exception was raised by
the codec.
Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python
bytes object. *encoding* and *errors* have the same meaning as the
- parameters of the same name in the Unicode :meth:`encode` method. The codec
+ parameters of the same name in the Unicode :meth:`~str.encode` method. The codec
to be used is looked up using the Python codec registry. Return *NULL* if an
exception was raised by the codec.
frame *f* is executed, interpreting bytecode and executing calls as needed.
The additional *throwflag* parameter can mostly be ignored - if true, then
it causes an exception to immediately be thrown; this is used for the
- :meth:`throw` methods of generator objects.
+ :meth:`~generator.throw` methods of generator objects.
.. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
It is common to pre-compute arguments to :func:`setup`, to better structure the
driver script. In the example above, the\ ``ext_modules`` argument to
:func:`setup` is a list of extension modules, each of which is an instance of
-the :class:`Extension`. In the example, the instance defines an extension named
-``demo`` which is build by compiling a single source file, :file:`demo.c`.
+the :class:`~distutils.extension.Extension`. In the example, the instance
+defines an extension named ``demo`` which is build by compiling a single source
+file, :file:`demo.c`.
In many cases, building an extension is more complex, since additional
preprocessor defines and libraries may be needed. This is demonstrated in the
The cycle detector is able to detect garbage cycles and can reclaim them so long
as there are no finalizers implemented in Python (:meth:`__del__` methods).
When there are such finalizers, the detector exposes the cycles through the
-:mod:`gc` module (specifically, the
-``garbage`` variable in that module). The :mod:`gc` module also exposes a way
-to run the detector (the :func:`collect` function), as well as configuration
+:mod:`gc` module (specifically, the :attr:`~gc.garbage` variable in that module).
+The :mod:`gc` module also exposes a way to run the detector (the
+:func:`~gc.collect` function), as well as configuration
interfaces and the ability to disable the detector at runtime. The cycle
detector is considered an optional component; though it is included by default,
it can be disabled at build time using the :option:`--without-cycle-gc` option
If you want your type to be subclassable from Python, and your type has the same
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
inheritance. A Python subclass of your type will have to list your type first
- in its :attr:`__bases__`, or else it will not be able to call your type's
+ in its :attr:`~class.__bases__`, or else it will not be able to call your type's
:meth:`__new__` method without getting an error. You can avoid this problem by
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
base type does. Most of the time, this will be true anyway, because either your
projects / python / commitdiff