#6928: fix class docs w.r.t. new metaclasses.

This commit is contained in:
Georg Brandl 2010-08-02 18:10:13 +00:00
parent 502c3eb52f
commit 65e5f80c48
1 changed files with 24 additions and 26 deletions

View File

@ -552,24 +552,27 @@ Class definitions
A class definition defines a class object (see section :ref:`types`):
.. XXX need to document PEP 3115 changes here (new metaclasses)
.. productionlist::
classdef: [`decorators`] "class" `classname` [`inheritance`] ":" `suite`
inheritance: "(" [`expression_list`] ")"
inheritance: "(" [`argument_list` [","] ] ")"
classname: `identifier`
A class definition is an executable statement. It first evaluates the
inheritance list, if present. Each item in the inheritance list should evaluate
to a class object or class type which allows subclassing. The class's suite is
then executed in a new execution frame (see section :ref:`naming`), using a
newly created local namespace and the original global namespace. (Usually, the
suite contains only function definitions.) When the class's suite finishes
execution, its execution frame is discarded but its local namespace is
saved. [#]_ A class object is then created using the inheritance list for the
base classes and the saved local namespace for the attribute dictionary. The
class name is bound to this class object in the original local namespace.
A class definition is an executable statement. The inheritance list usually
gives a list of base classes (see :ref:`metaclasses` for more advanced uses), so
each item in the list should evaluate to a class object which allows
subclassing.
The class's suite is then executed in a new execution frame (see :ref:`naming`),
using a newly created local namespace and the original global namespace.
(Usually, the suite contains mostly function definitions.) When the class's
suite finishes execution, its execution frame is discarded but its local
namespace is saved. [#]_ A class object is then created using the inheritance
list for the base classes and the saved local namespace for the attribute
dictionary. The class name is bound to this class object in the original local
namespace.
Class creation can be customized heavily using :ref:`metaclasses <metaclasses>`.
Classes can also be decorated; as with functions, ::
@ -583,25 +586,20 @@ is equivalent to ::
Foo = f1(arg)(f2(Foo))
**Programmer's note:** Variables defined in the class definition are class
variables; they are shared by instances. Instance variables can be set in a
method with ``self.name = value``. Both class and instance variables are
accessible through the notation "``self.name``", and an instance variable hides
a class variable with the same name when accessed in this way. Class variables
can be used as defaults for instance variables, but using mutable values there
can lead to unexpected results. Descriptors can be used to create instance
variables with different implementation details.
attributes; they are shared by instances. Instance attributes can be set in a
method with ``self.name = value``. Both class and instance attributes are
accessible through the notation "``self.name``", and an instance attribute hides
a class attribute with the same name when accessed in this way. Class
attributes can be used as defaults for instance attributes, but using mutable
values there can lead to unexpected results. :ref:`Descriptors <descriptors>`
can be used to create instance variables with different implementation details.
.. XXX add link to descriptor docs above
.. seealso::
:pep:`3116` - Metaclasses in Python 3
:pep:`3129` - Class Decorators
Class definitions, like function definitions, may be wrapped by one or more
:term:`decorator` expressions. The evaluation rules for the decorator
expressions are the same as for functions. The result must be a class object,
which is then bound to the class name.
.. rubric:: Footnotes