cpython: 1ed4e4a168bb (original) (raw)

Mercurial > cpython

changeset 102083:1ed4e4a168bb 2.7

Issue #24314: Add links for general attributes like __name__, __dict__ [#24314]

Martin Panter vadmium+py@gmail.com
date	Sat, 18 Jun 2016 03:57:31 +0000
parents	a09ae70f3489
children	ac8338546ca8
files	Doc/c-api/class.rst Doc/c-api/module.rst Doc/c-api/typeobj.rst Doc/library/__builtin__.rst Doc/library/functions.rst Doc/library/functools.rst Doc/library/inspect.rst Doc/library/restricted.rst Doc/library/stdtypes.rst Doc/reference/datamodel.rst Doc/tutorial/classes.rst Doc/whatsnew/2.1.rst Doc/whatsnew/2.2.rst Doc/whatsnew/2.3.rst
diffstat	14 files changed, 73 insertions(+), 68 deletions(-)[+] [-] 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

line wrap: on

line diff

--- a/Doc/c-api/class.rst +++ b/Doc/c-api/class.rst @@ -61,5 +61,5 @@ There are very few functions specific to 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.

--- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -51,10 +51,10 @@ There are only a few functions special t .. 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)

--- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -117,10 +117,10 @@ type objects) must have the :attr:ob_[](#l3.3) For statically allocated type objects, the tp_name field should contain a dot.[](#l3.4) 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.

--- a/Doc/library/builtin.rst +++ b/Doc/library/builtin.rst @@ -39,6 +39,6 @@ that wants to implement an :func:open 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.

--- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -311,7 +311,7 @@ section. :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 @@ section. 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 @@ section. .. 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

--- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -185,7 +185,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.

--- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -335,9 +335,11 @@ Note: 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 @@ Note: 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.

--- a/Doc/library/restricted.rst +++ b/Doc/library/restricted.rst @@ -48,7 +48,7 @@ deemed to be restricted. 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:

--- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2927,9 +2927,10 @@ an (external) definition for a module 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'[](#l9.14) (built-in)>. If loaded from a file, they are written as ``<module 'os' from @@ -3156,9 +3157,10 @@ types, where they are relevant. Some of 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.

--- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -481,6 +481,24 @@ Callable types .. tabularcolumns:: |l|L|l|

```
 .. index::[](#l10.7)
```

    single: __doc__ (function attribute)[](#l10.8)

    single: __name__ (function attribute)[](#l10.9)

    single: __module__ (function attribute)[](#l10.10)

    single: __dict__ (function attribute)[](#l10.11)

    single: __defaults__ (function attribute)[](#l10.12)

    single: __code__ (function attribute)[](#l10.13)

    single: __globals__ (function attribute)[](#l10.14)

    single: __closure__ (function attribute)[](#l10.15)

    single: func_doc (function attribute)[](#l10.16)

    single: func_name (function attribute)[](#l10.17)

    single: func_dict (function attribute)[](#l10.18)

    single: func_defaults (function attribute)[](#l10.19)

    single: func_code (function attribute)[](#l10.20)

    single: func_globals (function attribute)[](#l10.21)

    single: func_closure (function attribute)[](#l10.22)

```
    pair: global; namespace[](#l10.23)
```

 | :attr:`__name__`      | The function's name.          | Writable  |[](#l10.32)

 | :attr:`~definition.\  | The function's name           | Writable  |[](#l10.33)

 | __name__`             |                               |           |[](#l10.34)
 | :attr:`func_name`     |                               |           |[](#l10.35)
 +-----------------------+-------------------------------+-----------+[](#l10.36)
 | :attr:`__module__`    | The name of the module the    | Writable  |[](#l10.37)

 | :attr:`__dict__`      | The namespace supporting      | Writable  |[](#l10.42)

 | :attr:`func_dict`     | arbitrary function            |           |[](#l10.43)

 |                       | attributes.                   |           |[](#l10.44)

 | :attr:`~object.\      | The namespace supporting      | Writable  |[](#l10.45)

 | __dict__`             | arbitrary function            |           |[](#l10.46)

 | :attr:`func_dict`     | attributes.                   |           |[](#l10.47)
 +-----------------------+-------------------------------+-----------+[](#l10.48)
 | :attr:`__closure__`   | ``None`` or a tuple of cells  | Read-only |[](#l10.49)
 | :attr:`func_closure`  | that contain bindings for the |           |[](#l10.50)

@@ -540,24 +559,6 @@ Callable types Additional information about a function's definition can be retrieved from its code object; see the description of internal types below.

```
 .. index::[](#l10.55)
```

    single: __doc__ (function attribute)[](#l10.56)

    single: __name__ (function attribute)[](#l10.57)

    single: __module__ (function attribute)[](#l10.58)

    single: __dict__ (function attribute)[](#l10.59)

    single: __defaults__ (function attribute)[](#l10.60)

    single: __code__ (function attribute)[](#l10.61)

    single: __globals__ (function attribute)[](#l10.62)

    single: __closure__ (function attribute)[](#l10.63)

    single: func_doc (function attribute)[](#l10.64)

    single: func_name (function attribute)[](#l10.65)

    single: func_dict (function attribute)[](#l10.66)

    single: func_defaults (function attribute)[](#l10.67)

    single: func_code (function attribute)[](#l10.68)

    single: func_globals (function attribute)[](#l10.69)

    single: func_closure (function attribute)[](#l10.70)

```
    pair: global; namespace[](#l10.71)
```

- User-defined methods .. index:: object: method @@ -571,7 +572,7 @@ Callable types :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[](#l10.80)

 ``im_func.__doc__``); :attr:`~definition.__name__` is the method name (same as[](#l10.81)
 ``im_func.__name__``); :attr:`__module__` is the name of the module the method[](#l10.82)
 was defined in, or ``None`` if unavailable.[](#l10.83)

@@ -683,7 +684,7 @@ Callable types 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[](#l10.89)

 unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is[](#l10.90)
 set to ``None`` (but see the next item); :attr:`__module__` is the name of[](#l10.91)
 the module the function was defined in or ``None`` if unavailable.[](#l10.92)

@@ -744,7 +745,7 @@ Modules .. 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 @@ Classes 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 @@ Classes 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 @@ Class instances 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 @@ method (a so-called descriptor class) 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)

--- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -905,8 +905,8 @@ Examples:: .. 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.

--- a/Doc/whatsnew/2.1.rst +++ b/Doc/whatsnew/2.1.rst @@ -442,8 +442,8 @@ Python syntax:: 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.

--- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -157,7 +157,7 @@ attributes and methods were supported by 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 @@ possible, as well as more exotic constru 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 @@ However, Python 2.2's support for :dfn:[](#l13.21) to trap attribute references. Writing a :meth:getattr method is[](#l13.22) complicated because to avoid recursion you can't use regular attribute accesses[](#l13.23) inside them, and instead have to mess around with the contents of[](#l13.24) -:attr:dict. :meth:getattr methods also end up being called by Python[](#l13.25) +:attr:object.dict. :meth:getattr methods also end up being called by Python[](#l13.26) when it checks for other methods such as :meth:repr or :meth:coerce,[](#l13.27) and so have to be written with this in mind. Finally, calling a function on[](#l13.28) every attribute access results in a sizable performance loss.[](#l13.29) @@ -357,15 +357,15 @@ write::[](#l13.30) That is certainly clearer and easier to write than a pair of[](#l13.31) :meth:getattr/:meth:setattr methods that check for the :attr:size[](#l13.32) attribute and handle it specially while retrieving all other attributes from the[](#l13.33) -instance's :attr:dict. Accesses to :attr:size are also the only ones[](#l13.34) +instance's :attr:object.dict. Accesses to :attr:size are also the only ones[](#l13.35) which have to perform the work of calling a function, so references to other[](#l13.36) attributes run at their usual speed.[](#l13.37) [](#l13.38) Finally, it's possible to constrain the list of attributes that can be[](#l13.39) -referenced on an object using the new :attr:slots class attribute. Python[](#l13.40) +referenced on an object using the new :attr:object.slots class attribute. Python[](#l13.41) objects are usually very dynamic; at any time it's possible to define a new[](#l13.42) attribute on an instance by just doing ``obj.new_attr=1``. A new-style class[](#l13.43) -can define a class attribute named :attr:slots to limit the legal[](#l13.44) +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 @@ attributes to a particular set of names 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:

--- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -1111,10 +1111,10 @@ Here are all of the changes that Python <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 @@ Changes to Python's build process and to

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.