Changeset 391 for python/trunk/Doc/reference/datamodel.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/reference/datamodel.rst (modified) (26 diffs)

python/trunk/Doc/reference/datamodel.rst

@@ -67 +67 @@
    module for information on controlling the collection of cyclic garbage.
    Other implementations act differently and CPython may change.
+   Do not depend on immediate finalization of objects when they become
+   unreachable (ex: always close files).
 
 Note that the use of the implementation's tracing or debugging facilities may
@@ -410 +412 @@
       These represent a mutable set. They are created by the built-in :func:`set`
       constructor and can be modified afterwards by several methods, such as
-      :meth:`add`.
+      :meth:`~set.add`.
 
    Frozen sets
@@ -479 +481 @@
 
       Special attributes:
+
+      .. tabularcolumns:: |l|L|l|
 
       +-----------------------+-------------------------------+-----------+
@@ -572 +576 @@
 
       .. versionchanged:: 2.6
-         For 3.0 forward-compatibility, :attr:`im_func` is also available as
+         For Python 3 forward-compatibility, :attr:`im_func` is also available as
          :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`.
 
@@ -620 +624 @@
 
       When a user-defined method object is created by retrieving a class method object
-      from a class or instance, its :attr:`im_self` attribute is the class itself (the
-      same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is
-      the function object underlying the class method.
+      from a class or instance, its :attr:`im_self` attribute is the class itself, and
+      its :attr:`im_func` attribute is the function object underlying the class method.
 
       When an unbound user-defined method object is called, the underlying function
@@ -659 +662 @@
       function`.  Such a function, when called, always returns an iterator object
       which can be used to execute the body of the function:  calling the iterator's
-      :meth:`next` method will cause the function to execute until it provides a value
+      :meth:`~iterator.next` method will cause the function to execute until
+      it provides a value
       using the :keyword:`yield` statement.  When the function executes a
       :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
@@ -690 +694 @@
       a built-in method is ``alist.append()``, assuming *alist* is a list object. In
       this case, the special read-only attribute :attr:`__self__` is set to the object
-      denoted by *list*.
+      denoted by *alist*.
 
    Class Types
@@ -739 +743 @@
    Special read-only attribute: :attr:`__dict__` is the module's namespace as a
    dictionary object.
+
+   .. impl-detail::
+
+      Because of the way CPython clears module dictionaries, the module
+      dictionary will be cleared when the module falls out of scope even if the
+      dictionary still has live references.  To avoid this, copy the dictionary
+      or keep the module around while using its dictionary directly.
 
    .. index::
@@ -787 +798 @@
    transformed into an unbound user-defined method object whose :attr:`im_class`
    attribute is :class:`C`. When it would yield a class method object, it is
-   transformed into a bound user-defined method object whose :attr:`im_class`
-   and :attr:`im_self` attributes are both :class:`C`.  When it would yield a
+   transformed into a bound user-defined method object whose
+   :attr:`im_self` attribute is :class:`C`.  When it would yield a
    static method object, it is transformed into the object wrapped by the static
    method object. See section :ref:`descriptors` for another way in which
@@ -812 +823 @@
    Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
    the module name in which the class was defined; :attr:`__dict__` is the
-   dictionary containing the class's namespace; :attr:`__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 class's
-   documentation string, or None if undefined.
+   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
+   class's documentation string, or None if undefined.
 
 Class instances
@@ -860 +871 @@
       single: __class__ (instance attribute)
 
-   Special attributes: :attr:`__dict__` is the attribute dictionary;
-   :attr:`__class__` is the instance's class.
+   Special attributes: :attr:`~object.__dict__` is the attribute dictionary;
+   :attr:`~instance.__class__` is the instance's class.
 
 Files
@@ -908 +919 @@
       objects, code objects are immutable and contain no references (directly or
       indirectly) to mutable objects.
+
+      .. index::
+         single: co_argcount (code object attribute)
+         single: co_code (code object attribute)
+         single: co_consts (code object attribute)
+         single: co_filename (code object attribute)
+         single: co_firstlineno (code object attribute)
+         single: co_flags (code object attribute)
+         single: co_lnotab (code object attribute)
+         single: co_name (code object attribute)
+         single: co_names (code object attribute)
+         single: co_nlocals (code object attribute)
+         single: co_stacksize (code object attribute)
+         single: co_varnames (code object attribute)
+         single: co_cellvars (code object attribute)
+         single: co_freevars (code object attribute)
 
       Special read-only attributes: :attr:`co_name` gives the function name;
@@ -926 +953 @@
       :attr:`co_flags` is an integer encoding a number of flags for the interpreter.
 
-      .. index::
-         single: co_argcount (code object attribute)
-         single: co_code (code object attribute)
-         single: co_consts (code object attribute)
-         single: co_filename (code object attribute)
-         single: co_firstlineno (code object attribute)
-         single: co_flags (code object attribute)
-         single: co_lnotab (code object attribute)
-         single: co_name (code object attribute)
-         single: co_names (code object attribute)
-         single: co_nlocals (code object attribute)
-         single: co_stacksize (code object attribute)
-         single: co_varnames (code object attribute)
-         single: co_cellvars (code object attribute)
-         single: co_freevars (code object attribute)
-
       .. index:: object: generator
 
@@ -1060 +1071 @@
          single: step (slice object attribute)
 
-      Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is
-      the upper bound; :attr:`step` is the step value; each is ``None`` if omitted.
-      These attributes can have any type.
+      Special read-only attributes: :attr:`~slice.start` is the lower bound;
+      :attr:`~slice.stop` is the upper bound; :attr:`~slice.step` is the step
+      value; each is ``None`` if omitted.  These attributes can have any type.
 
       Slice objects support one method:
@@ -1141 +1152 @@
    single: class; old-style
 
-Old-style classes are removed in Python 3.0, leaving only the semantics of
+Old-style classes are removed in Python 3, leaving only the semantics of
 new-style classes.
 
@@ -1169 +1180 @@
 object being modelled.  For example, some sequences may work well with retrieval
 of individual elements, but extracting a slice may not make sense.  (One example
-of this is the :class:`NodeList` interface in the W3C's Document Object Model.)
+of this is the :class:`~xml.dom.NodeList` interface in the W3C's Document
+Object Model.)
 
 
@@ -1274 +1286 @@
       called.
 
+   See also the :option:`-R` command-line option.
+
 
 .. method:: object.__repr__(self)
@@ -1354 +1368 @@
 
    To automatically generate ordering operations from a single root operation,
-   see the `Total Ordering recipe in the ASPN cookbook
-   <http://code.activestate.com/recipes/576529/>`_\.
+   see :func:`functools.total_ordering`.
 
 .. method:: object.__cmp__(self, other)
@@ -1532 +1545 @@
 
 The following methods only apply when an instance of the class containing the
-method (a so-called *descriptor* class) appears in the class dictionary of
-another new-style class, known as the *owner* class. In the examples below, "the
-attribute" refers to the attribute whose name is the key of the property in the
-owner class' ``__dict__``.  Descriptors can only be implemented as new-style
-classes themselves.
+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__`.
 
 
@@ -1601 +1614 @@
    obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A``
    immediately preceding ``B`` and then invokes the descriptor with the call:
-   ``A.__dict__['m'].__get__(obj, A)``.
+   ``A.__dict__['m'].__get__(obj, obj.__class__)``.
 
 For instance bindings, the precedence of descriptor invocation depends on the
-which descriptor methods are defined.  Normally, data descriptors define both
-:meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the
-:meth:`__get__` method.  Data descriptors always override a redefinition in an
+which descriptor methods are defined.  A descriptor can define any combination
+of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`.  If it does not
+define :meth:`__get__`, then accessing the attribute will return the descriptor
+object itself unless there is a value in the object's instance dictionary.  If
+the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data
+descriptor; if it defines neither, it is a non-data descriptor.  Normally, data
+descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data
+descriptors have just the :meth:`__get__` method.  Data descriptors with
+:meth:`__set__` and :meth:`__get__` defined always override a redefinition in an
 instance dictionary.  In contrast, non-data descriptors can be overridden by
-instances. [#]_
+instances.
 
 Python methods (including :func:`staticmethod` and :func:`classmethod`) are
@@ -1756 +1775 @@
 property creation, proxies, frameworks, and automatic resource
 locking/synchronization.
+
+
+Customizing instance and subclass checks
+----------------------------------------
+
+.. versionadded:: 2.6
+
+The following methods are used to override the default behavior of the
+:func:`isinstance` and :func:`issubclass` built-in functions.
+
+In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
+order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
+classes" to any class or type (including built-in types), including other
+ABCs.
+
+.. method:: class.__instancecheck__(self, instance)
+
+   Return true if *instance* should be considered a (direct or indirect)
+   instance of *class*. If defined, called to implement ``isinstance(instance,
+   class)``.
+
+
+.. method:: class.__subclasscheck__(self, subclass)
+
+   Return true if *subclass* should be considered a (direct or indirect)
+   subclass of *class*.  If defined, called to implement ``issubclass(subclass,
+   class)``.
+
+
+Note that these methods are looked up on the type (metaclass) of a class.  They
+cannot be defined as class methods in the actual class.  This is consistent with
+the lookup of special methods that are called on instances, only in this
+case the instance is itself a class.
+
+.. seealso::
+
+   :pep:`3119` - Introducing Abstract Base Classes
+      Includes the specification for customizing :func:`isinstance` and
+      :func:`issubclass` behavior through :meth:`~class.__instancecheck__` and
+      :meth:`~class.__subclasscheck__`, with motivation for this functionality
+      in the context of adding Abstract Base Classes (see the :mod:`abc`
+      module) to the language.
 
 
@@ -1788 +1849 @@
 :meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`,
 :meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`,
-:meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar
+:meth:`pop`, :meth:`popitem`, :meth:`!copy`, and :meth:`update` behaving similar
 to those for Python's standard dictionary objects.  The :mod:`UserDict` module
 provides a :class:`DictMixin` class to help create those methods from a base set
@@ -2178 +2239 @@
 evolved, the coercion rules have become hard to document precisely; documenting
 what one version of one particular implementation does is undesirable.  Instead,
-here are some informal guidelines regarding coercion.  In Python 3.0, coercion
+here are some informal guidelines regarding coercion.  In Python 3, coercion
 will not be supported.
 
@@ -2253 +2314 @@
 *
 
-  In ``x * y``, if one operator is a sequence that implements sequence
+  In ``x * y``, if one operand is a sequence that implements sequence
   repetition, and the other is an integer (:class:`int` or :class:`long`),
   sequence repetition is invoked.
@@ -2266 +2327 @@
 
   In the current implementation, the built-in numeric types :class:`int`,
-  :class:`long` and :class:`float` do not use coercion; the type :class:`complex`
-  however does use coercion for binary operators and rich comparisons, despite
-  the above rules.  The difference can become apparent when subclassing these
-  types.  Over time, the type :class:`complex` may be fixed to avoid coercion.
+  :class:`long`, :class:`float`, and :class:`complex` do not use coercion.
   All these types implement a :meth:`__coerce__` method, for use by the built-in
   :func:`coerce` function.
+
+  .. versionchanged:: 2.7
+
+     The complex type no longer makes implicit calls to the :meth:`__coerce__`
+     method for mixed-type binary arithmetic operations.
 
 
@@ -2435 +2498 @@
    lead to some very strange behaviour if it is handled incorrectly.
 
-.. [#] A descriptor can define any combination of :meth:`__get__`,
-   :meth:`__set__` and :meth:`__delete__`.  If it does not define :meth:`__get__`,
-   then accessing the attribute even on an instance will return the descriptor
-   object itself.  If the descriptor defines :meth:`__set__` and/or
-   :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a
-   non-data descriptor.
-
 .. [#] For operands of the same type, it is assumed that if the non-reflected method
    (such as :meth:`__add__`) fails the operation is not supported, which is why the