From bae5d81f5d1f388aad48c2ce1aee8682b157e1bd Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Sat, 18 Jun 2016 03:57:31 +0000 Subject: Issue #24314: Fix doc links for general attributes like __name__, __dict__ --- Doc/c-api/module.rst | 4 ++-- Doc/c-api/typeobj.rst | 4 ++-- Doc/library/builtins.rst | 2 +- Doc/library/enum.rst | 2 +- Doc/library/functions.rst | 10 ++++----- Doc/library/functools.rst | 2 +- Doc/library/inspect.rst | 9 ++++---- Doc/library/stdtypes.rst | 15 +++++++------ Doc/reference/datamodel.rst | 51 +++++++++++++++++++++++---------------------- Doc/tutorial/classes.rst | 4 ++-- Doc/whatsnew/2.1.rst | 4 ++-- Doc/whatsnew/2.2.rst | 14 ++++++------- Doc/whatsnew/2.3.rst | 8 +++---- Doc/whatsnew/3.0.rst | 4 ++-- 14 files changed, 69 insertions(+), 64 deletions(-) diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 904b4b1..34f8443 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -59,10 +59,10 @@ Module Objects .. index:: single: __dict__ (module attribute) Return the dictionary object that implements *module*'s namespace; this object - is the same as the :attr:`__dict__` attribute of the module object. This + is the same as the :attr:`~object.__dict__` attribute of the module object. This function never fails. It is recommended extensions use other :c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly - manipulate a module's :attr:`__dict__`. + manipulate a module's :attr:`~object.__dict__`. .. c:function:: PyObject* PyModule_GetNameObject(PyObject *module) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index ac589b8..2c448a0 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -111,10 +111,10 @@ type objects) *must* have the :attr:`ob_size` field. 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. + :attr:`~definition.__name__` attribute. If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the - :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined + :attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined (unless explicitly set in the dictionary, as explained above). This means your type will be impossible to pickle. diff --git a/Doc/library/builtins.rst b/Doc/library/builtins.rst index 4b589a5..8fb1fef 100644 --- a/Doc/library/builtins.rst +++ b/Doc/library/builtins.rst @@ -37,6 +37,6 @@ that wants to implement an :func:`open` function that wraps the built-in As an implementation detail, most modules have the name ``__builtins__`` made available as part of their globals. The value of ``__builtins__`` is normally -either this module or the value of this module's :attr:`__dict__` attribute. +either this module or the value of this module's :attr:`~object.__dict__` attribute. Since this is an implementation detail, it may not be used by alternate implementations of Python. diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 60467b4..a3d5afc 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -431,7 +431,7 @@ The solution is to specify the module name explicitly as follows:: the source, pickling will be disabled. The new pickle protocol 4 also, in some circumstances, relies on -:attr:`__qualname__` being set to the location where pickle will be able +:attr:`~definition.__qualname__` being set to the location where pickle will be able to find the class. For example, if the class was made available in class SomeData in the global scope:: diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index c3563f3..e609463 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -304,7 +304,7 @@ are always available. They are listed here in alphabetical order. :func:`dir` reports their attributes. If the object does not provide :meth:`__dir__`, the function tries its best to - gather information from the object's :attr:`__dict__` attribute, if defined, and + gather information from the object's :attr:`~object.__dict__` attribute, if defined, and from its type object. The resulting list is not necessarily complete, and may be inaccurate when the object has a custom :func:`__getattr__`. @@ -1446,7 +1446,7 @@ are always available. They are listed here in alphabetical order. With three arguments, return a new type object. This is essentially a dynamic form of the :keyword:`class` statement. The *name* string is the - class name and becomes the :attr:`~class.__name__` attribute; the *bases* + class name and becomes the :attr:`~definition.__name__` attribute; the *bases* tuple itemizes the base classes and becomes the :attr:`~class.__bases__` attribute; and the *dict* dictionary is the namespace containing definitions for class body and is copied to a standard dictionary to become the @@ -1464,11 +1464,11 @@ are always available. They are listed here in alphabetical order. .. function:: vars([object]) Return the :attr:`~object.__dict__` attribute for a module, class, instance, - or any other object with a :attr:`__dict__` attribute. + or any other object with a :attr:`~object.__dict__` attribute. - Objects such as modules and instances have an updateable :attr:`__dict__` + Objects such as modules and instances have an updateable :attr:`~object.__dict__` attribute; however, other objects may have write restrictions on their - :attr:`__dict__` attributes (for example, classes use a + :attr:`~object.__dict__` attributes (for example, classes use a dictproxy to prevent direct dictionary updates). Without an argument, :func:`vars` acts like :func:`locals`. Note, the diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index abdd66f..127e3fa 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -474,7 +474,7 @@ have three read-only attributes: :class:`partial` objects are like :class:`function` objects in that they are callable, weak referencable, and can have attributes. There are some important -differences. For instance, the :attr:`__name__` and :attr:`__doc__` attributes +differences. For instance, the :attr:`~definition.__name__` and :attr:`__doc__` attributes are not created automatically. Also, :class:`partial` objects defined in classes behave like static methods and do not transform into bound methods during instance attribute look-up. diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index b28d0f9..8e7ed19 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -374,8 +374,9 @@ attributes: are true. This, for example, is true of ``int.__add__``. An object passing this test - has a :attr:`__get__` attribute but not a :attr:`__set__` attribute, but - beyond that the set of attributes varies. :attr:`__name__` is usually + has a :meth:`~object.__get__` method but not a :meth:`~object.__set__` + method, but beyond that the set of attributes varies. A + :attr:`~definition.__name__` attribute is usually sensible, and :attr:`__doc__` often is. Methods implemented via descriptors that also pass one of the other tests @@ -388,11 +389,11 @@ attributes: Return true if the object is a data descriptor. - Data descriptors have both a :attr:`__get__` and a :attr:`__set__` attribute. + Data descriptors have both a :attr:`~object.__get__` and a :attr:`~object.__set__` method. Examples are properties (defined in Python), getsets, and members. The latter two are defined in C and there are more specific tests available for those types, which is robust across Python implementations. Typically, data - descriptors will also have :attr:`__name__` and :attr:`__doc__` attributes + descriptors will also have :attr:`~definition.__name__` and :attr:`__doc__` attributes (properties, getsets, and members have both of these attributes), but this is not guaranteed. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index e8a488e..db1c2d0 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -4360,9 +4360,10 @@ an (external) *definition* for a module named *foo* somewhere.) A special attribute of every module is :attr:`~object.__dict__`. This is the dictionary containing the module's symbol table. Modifying this dictionary will actually change the module's symbol table, but direct assignment to the -:attr:`__dict__` attribute is not possible (you can write +:attr:`~object.__dict__` attribute is not possible (you can write ``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write -``m.__dict__ = {}``). Modifying :attr:`__dict__` directly is not recommended. +``m.__dict__ = {}``). Modifying :attr:`~object.__dict__` directly is +not recommended. Modules built into the interpreter are written like this: ````. If loaded from a file, they are written as ``>> class C(object): @@ -383,7 +383,7 @@ attributes to a particular set of names. An example will make this clear:: AttributeError: 'C' object has no attribute 'newattr' Note how you get an :exc:`AttributeError` on the attempt to assign to an -attribute not listed in :attr:`__slots__`. +attribute not listed in :attr:`~object.__slots__`. .. _sect-rellinks: diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst index b8cdcf1..fe8368e 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -1111,10 +1111,10 @@ Here are all of the changes that Python 2.3 makes to the core Python language. * One of the noted incompatibilities between old- and new-style classes has been - removed: you can now assign to the :attr:`__name__` and :attr:`__bases__` + removed: you can now assign to the :attr:`~definition.__name__` and :attr:`~class.__bases__` attributes of new-style classes. There are some restrictions on what can be - assigned to :attr:`__bases__` along the lines of those relating to assigning to - an instance's :attr:`__class__` attribute. + assigned to :attr:`~class.__bases__` along the lines of those relating to assigning to + an instance's :attr:`~instance.__class__` attribute. .. ====================================================================== @@ -1920,7 +1920,7 @@ Changes to Python's build process and to the C API include: * If you dynamically allocate type objects in your extension, you should be aware of a change in the rules relating to the :attr:`__module__` and - :attr:`__name__` attributes. In summary, you will want to ensure the type's + :attr:`~definition.__name__` attributes. In summary, you will want to ensure the type's dictionary contains a ``'__module__'`` key; making the module name the part of the type name leading up to the final period will no longer have the desired effect. For more detail, read the API reference documentation or the source. diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst index 044d7be..f53e4f8 100644 --- a/Doc/whatsnew/3.0.rst +++ b/Doc/whatsnew/3.0.rst @@ -783,8 +783,8 @@ Operators And Special Methods :attr:`func_closure`, :attr:`func_code`, :attr:`func_defaults`, :attr:`func_dict`, :attr:`func_doc`, :attr:`func_globals`, :attr:`func_name` were renamed to :attr:`__closure__`, - :attr:`__code__`, :attr:`__defaults__`, :attr:`__dict__`, - :attr:`__doc__`, :attr:`__globals__`, :attr:`__name__`, + :attr:`__code__`, :attr:`__defaults__`, :attr:`~object.__dict__`, + :attr:`__doc__`, :attr:`__globals__`, :attr:`~definition.__name__`, respectively. * :meth:`__nonzero__` is now :meth:`__bool__`. -- cgit v0.12