[Python-checkins] cpython (2.7): Issue 19195: Improved cross-references in C API documentation.
serhiy.storchaka
python-checkins at python.org
Wed Oct 9 13:00:31 CEST 2013
http://hg.python.org/cpython/rev/9b855a701e28
changeset: 86173:9b855a701e28
branch: 2.7
parent: 86170:ac826284fdd1
user: Serhiy Storchaka <storchaka at gmail.com>
date: Wed Oct 09 13:25:21 2013 +0300
summary:
Issue 19195: Improved cross-references in C API documentation.
files:
Doc/c-api/codec.rst | 8 ++++----
Doc/c-api/file.rst | 3 ++-
Doc/c-api/object.rst | 20 ++++++++++----------
Doc/c-api/set.rst | 2 +-
Doc/c-api/typeobj.rst | 8 ++++----
Doc/c-api/unicode.rst | 6 +++---
Doc/c-api/veryhigh.rst | 2 +-
Doc/extending/building.rst | 5 +++--
Doc/extending/extending.rst | 6 +++---
Doc/extending/newtypes.rst | 2 +-
10 files changed, 32 insertions(+), 30 deletions(-)
diff --git a/Doc/c-api/codec.rst b/Doc/c-api/codec.rst
--- a/Doc/c-api/codec.rst
+++ b/Doc/c-api/codec.rst
@@ -52,19 +52,19 @@
.. 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
diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -111,7 +111,8 @@
.. 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
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -47,8 +47,8 @@
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.
@@ -72,8 +72,8 @@
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)
@@ -180,9 +180,9 @@
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.
.. versionadded:: 2.1
@@ -196,9 +196,9 @@
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)
diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst
--- a/Doc/c-api/set.rst
+++ b/Doc/c-api/set.rst
@@ -156,7 +156,7 @@
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.
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -603,7 +603,7 @@
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
@@ -733,7 +733,7 @@
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.
@@ -927,7 +927,7 @@
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.
@@ -935,7 +935,7 @@
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.)
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -455,9 +455,9 @@
Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python
string 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 using the Python codec registry. Return *NULL* if an exception was
- raised by the codec.
+ of the same name in the Unicode :meth:`~unicode.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.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -265,7 +265,7 @@
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)
diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst
--- a/Doc/extending/building.rst
+++ b/Doc/extending/building.rst
@@ -58,8 +58,9 @@
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
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -845,9 +845,9 @@
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
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -152,7 +152,7 @@
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
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list