[Python-checkins] cpython (2.7): Issue #24314: Add links for general attributes like __name__, __dict__
martin.panter
python-checkins at python.org
Sat Jun 18 04:23:13 EDT 2016
https://hg.python.org/cpython/rev/1ed4e4a168bb
changeset: 102083:1ed4e4a168bb
branch: 2.7
parent: 102078:a09ae70f3489
user: Martin Panter <vadmium+py at gmail.com>
date: Sat Jun 18 03:57:31 2016 +0000
summary:
Issue #24314: Add links for general attributes like __name__, __dict__
files:
Doc/c-api/class.rst | 2 +-
Doc/c-api/module.rst | 4 +-
Doc/c-api/typeobj.rst | 4 +-
Doc/library/__builtin__.rst | 2 +-
Doc/library/functions.rst | 10 ++--
Doc/library/functools.rst | 2 +-
Doc/library/inspect.rst | 12 ++--
Doc/library/restricted.rst | 2 +-
Doc/library/stdtypes.rst | 12 ++--
Doc/reference/datamodel.rst | 61 ++++++++++++------------
Doc/tutorial/classes.rst | 4 +-
Doc/whatsnew/2.1.rst | 4 +-
Doc/whatsnew/2.2.rst | 14 ++--
Doc/whatsnew/2.3.rst | 8 +-
14 files changed, 73 insertions(+), 68 deletions(-)
diff --git a/Doc/c-api/class.rst b/Doc/c-api/class.rst
--- a/Doc/c-api/class.rst
+++ b/Doc/c-api/class.rst
@@ -61,5 +61,5 @@
Create a new instance of a specific class without calling its constructor.
*class* is the class of new object. The *dict* parameter will be used as the
- object's :attr:`__dict__`; if *NULL*, a new dictionary will be created for the
+ object's :attr:`~object.__dict__`; if *NULL*, a new dictionary will be created for the
instance.
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -51,10 +51,10 @@
.. 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:: char* PyModule_GetName(PyObject *module)
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
@@ -117,10 +117,10 @@
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/__builtin__.rst b/Doc/library/__builtin__.rst
--- a/Doc/library/__builtin__.rst
+++ b/Doc/library/__builtin__.rst
@@ -39,6 +39,6 @@
Most modules have the name ``__builtins__`` (note the ``'s'``) made available
as part of their globals. The value of ``__builtins__`` is normally either
- this module or the value of this modules's :attr:`__dict__` attribute. Since
+ this module or the value of this modules'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/functions.rst b/Doc/library/functions.rst
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -311,7 +311,7 @@
: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__`.
@@ -1477,7 +1477,7 @@
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* tuple
+ 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 becomes the :attr:`~object.__dict__` attribute. For example, the
@@ -1545,11 +1545,11 @@
.. 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, new-style classes use a
+ :attr:`~object.__dict__` attributes (for example, new-style 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
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -185,7 +185,7 @@
: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
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -335,9 +335,11 @@
are true.
This is new as of Python 2.2, and, 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 sensible, and :attr:`__doc__` often is.
+ ``int.__add__``. An object passing this test
+ 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
return false from the :func:`ismethoddescriptor` test, simply because the
@@ -349,11 +351,11 @@
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/restricted.rst b/Doc/library/restricted.rst
--- a/Doc/library/restricted.rst
+++ b/Doc/library/restricted.rst
@@ -48,7 +48,7 @@
Python code executing in restricted mode faces a number of limitations that are
designed to prevent it from escaping from the padded cell. For instance, the
function object attribute :attr:`func_globals` and the class and instance object
-attribute :attr:`__dict__` are unavailable.
+attribute :attr:`~object.__dict__` are unavailable.
Two modules provide the framework for setting up restricted execution
environments:
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2927,9 +2927,10 @@
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: ``<module 'sys'
(built-in)>``. If loaded from a file, they are written as ``<module 'os' from
@@ -3156,9 +3157,10 @@
The tuple of base classes of a class object.
-.. attribute:: class.__name__
-
- The name of the class or type.
+.. attribute:: definition.__name__
+
+ The name of the class, type, function, method, descriptor, or
+ generator instance.
The following attributes are only supported by :term:`new-style class`\ es.
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -481,6 +481,24 @@
.. tabularcolumns:: |l|L|l|
+ .. index::
+ single: __doc__ (function attribute)
+ single: __name__ (function attribute)
+ single: __module__ (function attribute)
+ single: __dict__ (function attribute)
+ single: __defaults__ (function attribute)
+ single: __code__ (function attribute)
+ single: __globals__ (function attribute)
+ single: __closure__ (function attribute)
+ single: func_doc (function attribute)
+ single: func_name (function attribute)
+ single: func_dict (function attribute)
+ single: func_defaults (function attribute)
+ single: func_code (function attribute)
+ single: func_globals (function attribute)
+ single: func_closure (function attribute)
+ pair: global; namespace
+
+-----------------------+-------------------------------+-----------+
| Attribute | Meaning | |
+=======================+===============================+===========+
@@ -488,7 +506,8 @@
| :attr:`func_doc` | string, or ``None`` if | |
| | unavailable. | |
+-----------------------+-------------------------------+-----------+
- | :attr:`__name__` | The function's name. | Writable |
+ | :attr:`~definition.\ | The function's name | Writable |
+ | __name__` | | |
| :attr:`func_name` | | |
+-----------------------+-------------------------------+-----------+
| :attr:`__module__` | The name of the module the | Writable |
@@ -511,9 +530,9 @@
| | module in which the function | |
| | was defined. | |
+-----------------------+-------------------------------+-----------+
- | :attr:`__dict__` | The namespace supporting | Writable |
- | :attr:`func_dict` | arbitrary function | |
- | | attributes. | |
+ | :attr:`~object.\ | The namespace supporting | Writable |
+ | __dict__` | arbitrary function | |
+ | :attr:`func_dict` | attributes. | |
+-----------------------+-------------------------------+-----------+
| :attr:`__closure__` | ``None`` or a tuple of cells | Read-only |
| :attr:`func_closure` | that contain bindings for the | |
@@ -540,24 +559,6 @@
Additional information about a function's definition can be retrieved from its
code object; see the description of internal types below.
- .. index::
- single: __doc__ (function attribute)
- single: __name__ (function attribute)
- single: __module__ (function attribute)
- single: __dict__ (function attribute)
- single: __defaults__ (function attribute)
- single: __code__ (function attribute)
- single: __globals__ (function attribute)
- single: __closure__ (function attribute)
- single: func_doc (function attribute)
- single: func_name (function attribute)
- single: func_dict (function attribute)
- single: func_defaults (function attribute)
- single: func_code (function attribute)
- single: func_globals (function attribute)
- single: func_closure (function attribute)
- pair: global; namespace
-
User-defined methods
.. index::
object: method
@@ -571,7 +572,7 @@
:attr:`im_func` is the function object; :attr:`im_class` is the class of
:attr:`im_self` for bound methods or the class that asked for the method for
unbound methods; :attr:`__doc__` is the method's documentation (same as
- ``im_func.__doc__``); :attr:`__name__` is the method name (same as
+ ``im_func.__doc__``); :attr:`~definition.__name__` is the method name (same as
``im_func.__name__``); :attr:`__module__` is the name of the module the method
was defined in, or ``None`` if unavailable.
@@ -683,7 +684,7 @@
standard built-in module). The number and type of the arguments are
determined by the C function. Special read-only attributes:
:attr:`__doc__` is the function's documentation string, or ``None`` if
- unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is
+ unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is
set to ``None`` (but see the next item); :attr:`__module__` is the name of
the module the function was defined in or ``None`` if unavailable.
@@ -744,7 +745,7 @@
.. index:: single: __dict__ (module attribute)
- Special read-only attribute: :attr:`__dict__` is the module's namespace as a
+ Special read-only attribute: :attr:`~object.__dict__` is the module's namespace as a
dictionary object.
.. impl-detail::
@@ -806,7 +807,7 @@
static method object, it is transformed into the object wrapped by the static
method object. See section :ref:`descriptors` for another way in which
attributes retrieved from a class may differ from those actually contained in
- its :attr:`__dict__` (note that only new-style classes support descriptors).
+ its :attr:`~object.__dict__` (note that only new-style classes support descriptors).
.. index:: triple: class; attribute; assignment
@@ -824,8 +825,8 @@
single: __bases__ (class attribute)
single: __doc__ (class attribute)
- Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
- the module name in which the class was defined; :attr:`__dict__` is the
+ Special attributes: :attr:`~definition.__name__` is the class name; :attr:`__module__` is
+ the module name in which the class was defined; :attr:`~object.__dict__` is the
dictionary containing the class's namespace; :attr:`~class.__bases__` is a
tuple (possibly empty or a singleton) containing the base classes, in the
order of their occurrence in the base class list; :attr:`__doc__` is the
@@ -851,7 +852,7 @@
objects are also transformed, as if they had been retrieved from class
:class:`C`; see above under "Classes". See section :ref:`descriptors` for
another way in which attributes of a class retrieved via its instances may
- differ from the objects actually stored in the class's :attr:`__dict__`. If no
+ differ from the objects actually stored in the class's :attr:`~object.__dict__`. If no
class attribute is found, and the object's class has a :meth:`__getattr__`
method, that is called to satisfy the lookup.
@@ -1554,7 +1555,7 @@
descriptor must be in either the owner's class dictionary or in the class
dictionary for one of its parents). In the examples below, "the attribute"
refers to the attribute whose name is the key of the property in the owner
-class' :attr:`__dict__`.
+class' :attr:`~object.__dict__`.
.. method:: object.__get__(self, instance, owner)
diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst
--- a/Doc/tutorial/classes.rst
+++ b/Doc/tutorial/classes.rst
@@ -905,8 +905,8 @@
.. rubric:: Footnotes
.. [#] Except for one thing. Module objects have a secret read-only attribute called
- :attr:`__dict__` which returns the dictionary used to implement the module's
- namespace; the name :attr:`__dict__` is an attribute but not a global name.
+ :attr:`~object.__dict__` which returns the dictionary used to implement the module's
+ namespace; the name :attr:`~object.__dict__` is an attribute but not a global name.
Obviously, using this violates the abstraction of namespace implementation, and
should be restricted to things like post-mortem debuggers.
diff --git a/Doc/whatsnew/2.1.rst b/Doc/whatsnew/2.1.rst
--- a/Doc/whatsnew/2.1.rst
+++ b/Doc/whatsnew/2.1.rst
@@ -442,8 +442,8 @@
f.grammar = "A ::= B (C D)*"
The dictionary containing attributes can be accessed as the function's
-:attr:`__dict__`. Unlike the :attr:`__dict__` attribute of class instances, in
-functions you can actually assign a new dictionary to :attr:`__dict__`, though
+:attr:`~object.__dict__`. Unlike the :attr:`~object.__dict__` attribute of class instances, in
+functions you can actually assign a new dictionary to :attr:`~object.__dict__`, though
the new value is restricted to a regular Python dictionary; you *can't* be
tricky and set it to a :class:`UserDict` instance, or any other random object
that behaves like a mapping.
diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst
--- a/Doc/whatsnew/2.2.rst
+++ b/Doc/whatsnew/2.2.rst
@@ -157,7 +157,7 @@
conventions, such as defining :attr:`__members__` and :attr:`__methods__`
attributes that were lists of names, but often the author of an extension type
or a class wouldn't bother to define them. You could fall back on inspecting
-the :attr:`__dict__` of an object, but when class inheritance or an arbitrary
+the :attr:`~object.__dict__` of an object, but when class inheritance or an arbitrary
:meth:`__getattr__` hook were in use this could still be inaccurate.
The one big idea underlying the new class model is that an API for describing
@@ -169,7 +169,7 @@
Attribute descriptors are objects that live inside class objects, and have a few
attributes of their own:
-* :attr:`__name__` is the attribute's name.
+* :attr:`~definition.__name__` is the attribute's name.
* :attr:`__doc__` is the attribute's docstring.
@@ -329,7 +329,7 @@
to trap attribute references. Writing a :meth:`__getattr__` method is
complicated because to avoid recursion you can't use regular attribute accesses
inside them, and instead have to mess around with the contents of
-:attr:`__dict__`. :meth:`__getattr__` methods also end up being called by Python
+:attr:`~object.__dict__`. :meth:`__getattr__` methods also end up being called by Python
when it checks for other methods such as :meth:`__repr__` or :meth:`__coerce__`,
and so have to be written with this in mind. Finally, calling a function on
every attribute access results in a sizable performance loss.
@@ -357,15 +357,15 @@
That is certainly clearer and easier to write than a pair of
:meth:`__getattr__`/:meth:`__setattr__` methods that check for the :attr:`size`
attribute and handle it specially while retrieving all other attributes from the
-instance's :attr:`__dict__`. Accesses to :attr:`size` are also the only ones
+instance's :attr:`~object.__dict__`. Accesses to :attr:`size` are also the only ones
which have to perform the work of calling a function, so references to other
attributes run at their usual speed.
Finally, it's possible to constrain the list of attributes that can be
-referenced on an object using the new :attr:`__slots__` class attribute. Python
+referenced on an object using the new :attr:`~object.__slots__` class attribute. Python
objects are usually very dynamic; at any time it's possible to define a new
attribute on an instance by just doing ``obj.new_attr=1``. A new-style class
-can define a class attribute named :attr:`__slots__` to limit the legal
+can define a class attribute named :attr:`~object.__slots__` to limit the legal
attributes to a particular set of names. An example will make this clear::
>>> class C(object):
@@ -383,7 +383,7 @@
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
--- a/Doc/whatsnew/2.3.rst
+++ b/Doc/whatsnew/2.3.rst
@@ -1111,10 +1111,10 @@
<type '_socket.socket'>
* 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 @@
* 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.
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list