mirror of https://github.com/python/cpython.git
Issue #24314: Merge doc links from 3.5
This commit is contained in:
Martin Panter
commit
2fec611a70
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
||||
|
|
|
|||
|
|
@ -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__`.
|
||||
|
||||
|
|
@ -1449,7 +1449,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
|
||||
|
|
@ -1467,11 +1467,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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -355,8 +355,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
|
||||
|
|
@ -369,11 +370,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.
|
||||
|
||||
|
|
|
|||
|
|
@ -4361,9 +4361,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: ``<module 'sys'
|
||||
(built-in)>``. If loaded from a file, they are written as ``<module 'os' from
|
||||
|
|
@ -4576,14 +4577,16 @@ types, where they are relevant. Some of these are not reported by the
|
|||
The tuple of base classes of a class object.
|
||||
|
||||
|
||||
.. attribute:: class.__name__
|
||||
.. attribute:: definition.__name__
|
||||
|
||||
The name of the class or type.
|
||||
The name of the class, function, method, descriptor, or
|
||||
generator instance.
|
||||
|
||||
|
||||
.. attribute:: class.__qualname__
|
||||
.. attribute:: definition.__qualname__
|
||||
|
||||
The :term:`qualified name` of the class or type.
|
||||
The :term:`qualified name` of the class, function, method, descriptor,
|
||||
or generator instance.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
|
|
|||
|
|
@ -454,6 +454,19 @@ Callable types
|
|||
|
||||
.. 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: __closure__ (function attribute)
|
||||
single: __code__ (function attribute)
|
||||
single: __globals__ (function attribute)
|
||||
single: __annotations__ (function attribute)
|
||||
single: __kwdefaults__ (function attribute)
|
||||
pair: global; namespace
|
||||
|
||||
+-------------------------+-------------------------------+-----------+
|
||||
| Attribute | Meaning | |
|
||||
+=========================+===============================+===========+
|
||||
|
|
@ -462,10 +475,11 @@ Callable types
|
|||
| | unavailable; not inherited by | |
|
||||
| | subclasses | |
|
||||
+-------------------------+-------------------------------+-----------+
|
||||
| :attr:`__name__` | The function's name | Writable |
|
||||
| :attr:`~definition.\ | The function's name | Writable |
|
||||
| __name__` | | |
|
||||
+-------------------------+-------------------------------+-----------+
|
||||
| :attr:`__qualname__` | The function's | Writable |
|
||||
| | :term:`qualified name` | |
|
||||
| :attr:`~definition.\ | The function's | Writable |
|
||||
| __qualname__` | :term:`qualified name` | |
|
||||
| | | |
|
||||
| | .. versionadded:: 3.3 | |
|
||||
+-------------------------+-------------------------------+-----------+
|
||||
|
|
@ -489,7 +503,7 @@ Callable types
|
|||
| | module in which the function | |
|
||||
| | was defined. | |
|
||||
+-------------------------+-------------------------------+-----------+
|
||||
| :attr:`__dict__` | The namespace supporting | Writable |
|
||||
| :attr:`~object.__dict__`| The namespace supporting | Writable |
|
||||
| | arbitrary function | |
|
||||
| | attributes. | |
|
||||
+-------------------------+-------------------------------+-----------+
|
||||
|
|
@ -519,19 +533,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::
|
||||
single: __doc__ (function attribute)
|
||||
single: __name__ (function attribute)
|
||||
single: __module__ (function attribute)
|
||||
single: __dict__ (function attribute)
|
||||
single: __defaults__ (function attribute)
|
||||
single: __closure__ (function attribute)
|
||||
single: __code__ (function attribute)
|
||||
single: __globals__ (function attribute)
|
||||
single: __annotations__ (function attribute)
|
||||
single: __kwdefaults__ (function attribute)
|
||||
pair: global; namespace
|
||||
|
||||
Instance methods
|
||||
.. index::
|
||||
object: method
|
||||
|
|
@ -550,7 +551,7 @@ Callable types
|
|||
|
||||
Special read-only attributes: :attr:`__self__` is the class instance object,
|
||||
:attr:`__func__` is the function object; :attr:`__doc__` is the method's
|
||||
documentation (same as ``__func__.__doc__``); :attr:`__name__` is the
|
||||
documentation (same as ``__func__.__doc__``); :attr:`~definition.__name__` is the
|
||||
method name (same as ``__func__.__name__``); :attr:`__module__` is the
|
||||
name of the module the method was defined in, or ``None`` if unavailable.
|
||||
|
||||
|
|
@ -637,7 +638,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
|
||||
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.
|
||||
|
||||
|
|
@ -687,7 +688,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::
|
||||
|
|
@ -743,7 +744,7 @@ Custom classes
|
|||
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__`.
|
||||
:attr:`~object.__dict__`.
|
||||
|
||||
.. index:: triple: class; attribute; assignment
|
||||
|
||||
|
|
@ -761,8 +762,8 @@ Custom 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
|
||||
|
|
@ -785,7 +786,7 @@ Class instances
|
|||
class method objects are also transformed; 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 class attribute is found, and the
|
||||
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.
|
||||
|
||||
|
|
@ -1467,7 +1468,7 @@ method (a so-called *descriptor* class) appears in an *owner* class (the
|
|||
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)
|
||||
|
|
|
|||
|
|
@ -951,8 +951,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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -157,7 +157,7 @@ attributes and methods were supported by an object. There were some informal
|
|||
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 constructs.
|
|||
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:`properties` will often be a simpler way
|
|||
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 @@ write::
|
|||
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 @@ 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:
|
||||
|
|
|
|||
|
|
@ -1111,10 +1111,10 @@ Here are all of the changes that Python 2.3 makes to the core Python language.
|
|||
<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 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.
|
||||
|
|
|
|||
|
|
@ -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__`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue