Move the 3k reST doc tree in place.
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
new file mode 100644
index 0000000..e7587f6
--- /dev/null
+++ b/Doc/reference/compound_stmts.rst
@@ -0,0 +1,554 @@
+
+.. _compound:
+
+*******************
+Compound statements
+*******************
+
+.. index:: pair: compound; statement
+
+Compound statements contain (groups of) other statements; they affect or control
+the execution of those other statements in some way. In general, compound
+statements span multiple lines, although in simple incarnations a whole compound
+statement may be contained in one line.
+
+The :keyword:`if`, :keyword:`while` and :keyword:`for` statements implement
+traditional control flow constructs. :keyword:`try` specifies exception
+handlers and/or cleanup code for a group of statements. Function and class
+definitions are also syntactically compound statements.
+
+.. index::
+ single: clause
+ single: suite
+
+Compound statements consist of one or more 'clauses.' A clause consists of a
+header and a 'suite.' The clause headers of a particular compound statement are
+all at the same indentation level. Each clause header begins with a uniquely
+identifying keyword and ends with a colon. A suite is a group of statements
+controlled by a clause. A suite can be one or more semicolon-separated simple
+statements on the same line as the header, following the header's colon, or it
+can be one or more indented statements on subsequent lines. Only the latter
+form of suite can contain nested compound statements; the following is illegal,
+mostly because it wouldn't be clear to which :keyword:`if` clause a following
+:keyword:`else` clause would belong: ::
+
+ if test1: if test2: print x
+
+Also note that the semicolon binds tighter than the colon in this context, so
+that in the following example, either all or none of the :keyword:`print`
+statements are executed::
+
+ if x < y < z: print x; print y; print z
+
+Summarizing:
+
+.. productionlist::
+ compound_stmt: `if_stmt`
+ : | `while_stmt`
+ : | `for_stmt`
+ : | `try_stmt`
+ : | `with_stmt`
+ : | `funcdef`
+ : | `classdef`
+ suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT
+ statement: `stmt_list` NEWLINE | `compound_stmt`
+ stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"]
+
+.. index::
+ single: NEWLINE token
+ single: DEDENT token
+ pair: dangling; else
+
+Note that statements always end in a ``NEWLINE`` possibly followed by a
+``DEDENT``. Also note that optional continuation clauses always begin with a
+keyword that cannot start a statement, thus there are no ambiguities (the
+'dangling :keyword:`else`' problem is solved in Python by requiring nested
+:keyword:`if` statements to be indented).
+
+The formatting of the grammar rules in the following sections places each clause
+on a separate line for clarity.
+
+
+.. _if:
+
+The :keyword:`if` statement
+===========================
+
+.. index:: statement: if
+
+The :keyword:`if` statement is used for conditional execution:
+
+.. productionlist::
+ if_stmt: "if" `expression` ":" `suite`
+ : ( "elif" `expression` ":" `suite` )*
+ : ["else" ":" `suite`]
+
+.. index::
+ keyword: elif
+ keyword: else
+
+It selects exactly one of the suites by evaluating the expressions one by one
+until one is found to be true (see section :ref:`booleans` for the definition of
+true and false); then that suite is executed (and no other part of the
+:keyword:`if` statement is executed or evaluated). If all expressions are
+false, the suite of the :keyword:`else` clause, if present, is executed.
+
+
+.. _while:
+
+The :keyword:`while` statement
+==============================
+
+.. index::
+ statement: while
+ pair: loop; statement
+
+The :keyword:`while` statement is used for repeated execution as long as an
+expression is true:
+
+.. productionlist::
+ while_stmt: "while" `expression` ":" `suite`
+ : ["else" ":" `suite`]
+
+.. index:: keyword: else
+
+This repeatedly tests the expression and, if it is true, executes the first
+suite; if the expression is false (which may be the first time it is tested) the
+suite of the :keyword:`else` clause, if present, is executed and the loop
+terminates.
+
+.. index::
+ statement: break
+ statement: continue
+
+A :keyword:`break` statement executed in the first suite terminates the loop
+without executing the :keyword:`else` clause's suite. A :keyword:`continue`
+statement executed in the first suite skips the rest of the suite and goes back
+to testing the expression.
+
+
+.. _for:
+
+The :keyword:`for` statement
+============================
+
+.. index::
+ statement: for
+ pair: loop; statement
+
+.. index:: object: sequence
+
+The :keyword:`for` statement is used to iterate over the elements of a sequence
+(such as a string, tuple or list) or other iterable object:
+
+.. productionlist::
+ for_stmt: "for" `target_list` "in" `expression_list` ":" `suite`
+ : ["else" ":" `suite`]
+
+.. index::
+ keyword: in
+ keyword: else
+ pair: target; list
+
+The expression list is evaluated once; it should yield an iterable object. An
+iterator is created for the result of the ``expression_list``. The suite is
+then executed once for each item provided by the iterator, in the order of
+ascending indices. Each item in turn is assigned to the target list using the
+standard rules for assignments, and then the suite is executed. When the items
+are exhausted (which is immediately when the sequence is empty), the suite in
+the :keyword:`else` clause, if present, is executed, and the loop terminates.
+
+.. index::
+ statement: break
+ statement: continue
+
+A :keyword:`break` statement executed in the first suite terminates the loop
+without executing the :keyword:`else` clause's suite. A :keyword:`continue`
+statement executed in the first suite skips the rest of the suite and continues
+with the next item, or with the :keyword:`else` clause if there was no next
+item.
+
+The suite may assign to the variable(s) in the target list; this does not affect
+the next item assigned to it.
+
+.. index::
+ builtin: range
+ pair: Pascal; language
+
+The target list is not deleted when the loop is finished, but if the sequence is
+empty, it will not have been assigned to at all by the loop. Hint: the built-in
+function :func:`range` returns a sequence of integers suitable to emulate the
+effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list
+``[0, 1, 2]``.
+
+.. warning::
+
+ .. index::
+ single: loop; over mutable sequence
+ single: mutable sequence; loop over
+
+ There is a subtlety when the sequence is being modified by the loop (this can
+ only occur for mutable sequences, i.e. lists). An internal counter is used to
+ keep track of which item is used next, and this is incremented on each
+ iteration. When this counter has reached the length of the sequence the loop
+ terminates. This means that if the suite deletes the current (or a previous)
+ item from the sequence, the next item will be skipped (since it gets the index
+ of the current item which has already been treated). Likewise, if the suite
+ inserts an item in the sequence before the current item, the current item will
+ be treated again the next time through the loop. This can lead to nasty bugs
+ that can be avoided by making a temporary copy using a slice of the whole
+ sequence, e.g.,
+
+::
+
+ for x in a[:]:
+ if x < 0: a.remove(x)
+
+
+.. _try:
+
+The :keyword:`try` statement
+============================
+
+.. index:: statement: try
+
+The :keyword:`try` statement specifies exception handlers and/or cleanup code
+for a group of statements:
+
+.. productionlist::
+ try_stmt: try1_stmt | try2_stmt
+ try1_stmt: "try" ":" `suite`
+ : ("except" [`expression` ["," `target`]] ":" `suite`)+
+ : ["else" ":" `suite`]
+ : ["finally" ":" `suite`]
+ try2_stmt: "try" ":" `suite`
+ : "finally" ":" `suite`
+
+.. versionchanged:: 2.5
+ In previous versions of Python, :keyword:`try`...\ :keyword:`except`...\
+ :keyword:`finally` did not work. :keyword:`try`...\ :keyword:`except` had to be
+ nested in :keyword:`try`...\ :keyword:`finally`.
+
+.. index:: keyword: except
+
+The :keyword:`except` clause(s) specify one or more exception handlers. When no
+exception occurs in the :keyword:`try` clause, no exception handler is executed.
+When an exception occurs in the :keyword:`try` suite, a search for an exception
+handler is started. This search inspects the except clauses in turn until one
+is found that matches the exception. An expression-less except clause, if
+present, must be last; it matches any exception. For an except clause with an
+expression, that expression is evaluated, and the clause matches the exception
+if the resulting object is "compatible" with the exception. An object is
+compatible with an exception if it is the class or a base class of the exception
+object or a tuple containing an item compatible with the exception.
+
+If no except clause matches the exception, the search for an exception handler
+continues in the surrounding code and on the invocation stack. [#]_
+
+If the evaluation of an expression in the header of an except clause raises an
+exception, the original search for a handler is canceled and a search starts for
+the new exception in the surrounding code and on the call stack (it is treated
+as if the entire :keyword:`try` statement raised the exception).
+
+When a matching except clause is found, the exception is assigned to the target
+specified in that except clause, if present, and the except clause's suite is
+executed. All except clauses must have an executable block. When the end of
+this block is reached, execution continues normally after the entire try
+statement. (This means that if two nested handlers exist for the same
+exception, and the exception occurs in the try clause of the inner handler, the
+outer handler will not handle the exception.)
+
+.. index::
+ module: sys
+ object: traceback
+
+Before an except clause's suite is executed, details about the exception are
+stored in the :mod:`sys` module and can be access via :func:`sys.exc_info`.
+:func:`sys.exc_info` returns a 3-tuple consisting of: ``exc_type`` receives the
+object identifying the exception; ``exc_value`` receives the exception's
+parameter; ``exc_traceback`` receives a traceback object (see section
+:ref:`types`) identifying the point in the program where the exception
+occurred. :func:`sys.exc_info` values are restored to their previous values
+(before the call) when returning from a function that handled an exception.
+
+.. index::
+ keyword: else
+ statement: return
+ statement: break
+ statement: continue
+
+The optional :keyword:`else` clause is executed if and when control flows off
+the end of the :keyword:`try` clause. [#]_ Exceptions in the :keyword:`else`
+clause are not handled by the preceding :keyword:`except` clauses.
+
+.. index:: keyword: finally
+
+If :keyword:`finally` is present, it specifies a 'cleanup' handler. The
+:keyword:`try` clause is executed, including any :keyword:`except` and
+:keyword:`else` clauses. If an exception occurs in any of the clauses and is
+not handled, the exception is temporarily saved. The :keyword:`finally` clause
+is executed. If there is a saved exception, it is re-raised at the end of the
+:keyword:`finally` clause. If the :keyword:`finally` clause raises another
+exception or executes a :keyword:`return` or :keyword:`break` statement, the
+saved exception is lost. The exception information is not available to the
+program during execution of the :keyword:`finally` clause.
+
+.. index::
+ statement: return
+ statement: break
+ statement: continue
+
+When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is
+executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally`
+statement, the :keyword:`finally` clause is also executed 'on the way out.' A
+:keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The
+reason is a problem with the current implementation --- this restriction may be
+lifted in the future).
+
+Additional information on exceptions can be found in section :ref:`exceptions`,
+and information on using the :keyword:`raise` statement to generate exceptions
+may be found in section :ref:`raise`.
+
+
+.. _with:
+
+The :keyword:`with` statement
+=============================
+
+.. index:: statement: with
+
+.. versionadded:: 2.5
+
+The :keyword:`with` statement is used to wrap the execution of a block with
+methods defined by a context manager (see section :ref:`context-managers`). This
+allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` usage
+patterns to be encapsulated for convenient reuse.
+
+.. productionlist::
+ with_stmt: "with" `expression` ["as" `target`] ":" `suite`
+
+The execution of the :keyword:`with` statement proceeds as follows:
+
+#. The context expression is evaluated to obtain a context manager.
+
+#. The context manager's :meth:`__enter__` method is invoked.
+
+#. If a target was included in the :keyword:`with` statement, the return value
+ from :meth:`__enter__` is assigned to it.
+
+ .. note::
+
+ The :keyword:`with` statement guarantees that if the :meth:`__enter__` method
+ returns without an error, then :meth:`__exit__` will always be called. Thus, if
+ an error occurs during the assignment to the target list, it will be treated the
+ same as an error occurring within the suite would be. See step 5 below.
+
+#. The suite is executed.
+
+#. The context manager's :meth:`__exit__` method is invoked. If an exception
+ caused the suite to be exited, its type, value, and traceback are passed as
+ arguments to :meth:`__exit__`. Otherwise, three :const:`None` arguments are
+ supplied.
+
+ If the suite was exited due to an exception, and the return value from the
+ :meth:`__exit__` method was false, the exception is reraised. If the return
+ value was true, the exception is suppressed, and execution continues with the
+ statement following the :keyword:`with` statement.
+
+ If the suite was exited for any reason other than an exception, the return value
+ from :meth:`__exit__` is ignored, and execution proceeds at the normal location
+ for the kind of exit that was taken.
+
+.. note::
+
+ In Python 2.5, the :keyword:`with` statement is only allowed when the
+ ``with_statement`` feature has been enabled. It will always be enabled in
+ Python 2.6. This ``__future__`` import statement can be used to enable the
+ feature::
+
+ from __future__ import with_statement
+
+
+.. seealso::
+
+ :pep:`0343` - The "with" statement
+ The specification, background, and examples for the Python :keyword:`with`
+ statement.
+
+
+.. _function:
+
+Function definitions
+====================
+
+.. index::
+ pair: function; definition
+ statement: def
+
+.. index::
+ object: user-defined function
+ object: function
+
+A function definition defines a user-defined function object (see section
+:ref:`types`):
+
+.. productionlist::
+ funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`]? ":" `suite`
+ decorators: `decorator`+
+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE
+ dotted_name: `identifier` ("." `identifier`)*
+ parameter_list: (`defparameter` ",")*
+ : ( "*" [`parameter`] ("," `defparameter`)*
+ : [, "**" `parameter`]
+ : | "**" `parameter`
+ : | `defparameter` [","] )
+ parameter: `identifier` [":" `expression`]
+ defparameter: `parameter` ["=" `expression`]
+ funcname: `identifier`
+
+.. index::
+ pair: function; name
+ pair: name; binding
+
+A function definition is an executable statement. Its execution binds the
+function name in the current local namespace to a function object (a wrapper
+around the executable code for the function). This function object contains a
+reference to the current global namespace as the global namespace to be used
+when the function is called.
+
+The function definition does not execute the function body; this gets executed
+only when the function is called.
+
+A function definition may be wrapped by one or more decorator expressions.
+Decorator expressions are evaluated when the function is defined, in the scope
+that contains the function definition. The result must be a callable, which is
+invoked with the function object as the only argument. The returned value is
+bound to the function name instead of the function object. Multiple decorators
+are applied in nested fashion. For example, the following code::
+
+ @f1(arg)
+ @f2
+ def func(): pass
+
+is equivalent to::
+
+ def func(): pass
+ func = f1(arg)(f2(func))
+
+.. index:: triple: default; parameter; value
+
+When one or more parameters have the form *parameter* ``=`` *expression*, the
+function is said to have "default parameter values." For a parameter with a
+default value, the corresponding argument may be omitted from a call, in which
+case the parameter's default value is substituted. If a parameter has a default
+value, all following parameters up until the "``*``" must also have a default
+value --- this is a syntactic restriction that is not expressed by the grammar.
+
+**Default parameter values are evaluated when the function definition is
+executed.** This means that the expression is evaluated once, when the function
+is defined, and that that same "pre-computed" value is used for each call. This
+is especially important to understand when a default parameter is a mutable
+object, such as a list or a dictionary: if the function modifies the object
+(e.g. by appending an item to a list), the default value is in effect modified.
+This is generally not what was intended. A way around this is to use ``None``
+as the default, and explicitly test for it in the body of the function, e.g.::
+
+ def whats_on_the_telly(penguin=None):
+ if penguin is None:
+ penguin = []
+ penguin.append("property of the zoo")
+ return penguin
+
+Function call semantics are described in more detail in section :ref:`calls`. A
+function call always assigns values to all parameters mentioned in the parameter
+list, either from position arguments, from keyword arguments, or from default
+values. If the form "``*identifier``" is present, it is initialized to a tuple
+receiving any excess positional parameters, defaulting to the empty tuple. If
+the form "``**identifier``" is present, it is initialized to a new dictionary
+receiving any excess keyword arguments, defaulting to a new empty dictionary.
+Parameters after "``*``" or "``*identifier``" are keyword-only parameters and
+may only be passed used keyword arguments.
+
+.. index:: pair: function; annotations
+
+Parameters may have annotations of the form "``: expression``" following the
+parameter name. Any parameter may have an annotation even those of the form
+``*identifier`` or ``**identifier``. Functions may have "return" annotation of
+the form "``-> expression``" after the parameter list. These annotations can be
+any valid Python expression and are evaluated when the function definition is
+executed. Annotations may be evaluated in a different order than they appear in
+the source code. The presence of annotations does not change the semantics of a
+function. The annotation values are available as values of a dictionary keyed
+by the parameters' names in the :attr:`__annotations__` attribute of the
+function object.
+
+.. index:: pair: lambda; form
+
+It is also possible to create anonymous functions (functions not bound to a
+name), for immediate use in expressions. This uses lambda forms, described in
+section :ref:`lambda`. Note that the lambda form is merely a shorthand for a
+simplified function definition; a function defined in a ":keyword:`def`"
+statement can be passed around or assigned to another name just like a function
+defined by a lambda form. The ":keyword:`def`" form is actually more powerful
+since it allows the execution of multiple statements and annotations.
+
+**Programmer's note:** Functions are first-class objects. A "``def``" form
+executed inside a function definition defines a local function that can be
+returned or passed around. Free variables used in the nested function can
+access the local variables of the function containing the def. See section
+:ref:`naming` for details.
+
+
+.. _class:
+
+Class definitions
+=================
+
+.. index::
+ pair: class; definition
+ statement: class
+
+.. index:: object: class
+
+A class definition defines a class object (see section :ref:`types`):
+
+.. productionlist::
+ classdef: "class" `classname` [`inheritance`] ":" `suite`
+ inheritance: "(" [`expression_list`] ")"
+ classname: `identifier`
+
+.. index::
+ single: inheritance
+ pair: class; name
+ pair: name; binding
+ pair: execution; frame
+
+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.
+
+**Programmer's note:** Variables defined in the class definition are class
+variables; they are shared by all instances. To define instance variables, they
+must be given a value in the :meth:`__init__` method or in another method. 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 with immutable values can be
+used as defaults for instance variables. For new-style classes, descriptors can
+be used to create instance variables with different implementation details.
+
+.. rubric:: Footnotes
+
+.. [#] The exception is propogated to the invocation stack only if there is no
+ :keyword:`finally` clause that negates the exception.
+
+.. [#] Currently, control "flows off the end" except in the case of an exception or the
+ execution of a :keyword:`return`, :keyword:`continue`, or :keyword:`break`
+ statement.
+
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
new file mode 100644
index 0000000..2f6013e
--- /dev/null
+++ b/Doc/reference/datamodel.rst
@@ -0,0 +1,2118 @@
+
+.. _datamodel:
+
+**********
+Data model
+**********
+
+
+.. _objects:
+
+Objects, values and types
+=========================
+
+.. index::
+ single: object
+ single: data
+
+:dfn:`Objects` are Python's abstraction for data. All data in a Python program
+is represented by objects or by relations between objects. (In a sense, and in
+conformance to Von Neumann's model of a "stored program computer," code is also
+represented by objects.)
+
+.. index::
+ builtin: id
+ builtin: type
+ single: identity of an object
+ single: value of an object
+ single: type of an object
+ single: mutable object
+ single: immutable object
+
+Every object has an identity, a type and a value. An object's *identity* never
+changes once it has been created; you may think of it as the object's address in
+memory. The ':keyword:`is`' operator compares the identity of two objects; the
+:func:`id` function returns an integer representing its identity (currently
+implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_
+An object's type determines the operations that the object supports (e.g., "does
+it have a length?") and also defines the possible values for objects of that
+type. The :func:`type` function returns an object's type (which is an object
+itself). The *value* of some objects can change. Objects whose value can
+change are said to be *mutable*; objects whose value is unchangeable once they
+are created are called *immutable*. (The value of an immutable container object
+that contains a reference to a mutable object can change when the latter's value
+is changed; however the container is still considered immutable, because the
+collection of objects it contains cannot be changed. So, immutability is not
+strictly the same as having an unchangeable value, it is more subtle.) An
+object's mutability is determined by its type; for instance, numbers, strings
+and tuples are immutable, while dictionaries and lists are mutable.
+
+.. index::
+ single: garbage collection
+ single: reference counting
+ single: unreachable object
+
+Objects are never explicitly destroyed; however, when they become unreachable
+they may be garbage-collected. An implementation is allowed to postpone garbage
+collection or omit it altogether --- it is a matter of implementation quality
+how garbage collection is implemented, as long as no objects are collected that
+are still reachable. (Implementation note: the current implementation uses a
+reference-counting scheme with (optional) delayed detection of cyclically linked
+garbage, which collects most objects as soon as they become unreachable, but is
+not guaranteed to collect garbage containing circular references. See the
+documentation of the :mod:`gc` module for information on controlling the
+collection of cyclic garbage.)
+
+Note that the use of the implementation's tracing or debugging facilities may
+keep objects alive that would normally be collectable. Also note that catching
+an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
+objects alive.
+
+Some objects contain references to "external" resources such as open files or
+windows. It is understood that these resources are freed when the object is
+garbage-collected, but since garbage collection is not guaranteed to happen,
+such objects also provide an explicit way to release the external resource,
+usually a :meth:`close` method. Programs are strongly recommended to explicitly
+close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement
+provides a convenient way to do this.
+
+.. index:: single: container
+
+Some objects contain references to other objects; these are called *containers*.
+Examples of containers are tuples, lists and dictionaries. The references are
+part of a container's value. In most cases, when we talk about the value of a
+container, we imply the values, not the identities of the contained objects;
+however, when we talk about the mutability of a container, only the identities
+of the immediately contained objects are implied. So, if an immutable container
+(like a tuple) contains a reference to a mutable object, its value changes if
+that mutable object is changed.
+
+Types affect almost all aspects of object behavior. Even the importance of
+object identity is affected in some sense: for immutable types, operations that
+compute new values may actually return a reference to any existing object with
+the same type and value, while for mutable objects this is not allowed. E.g.,
+after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
+with the value one, depending on the implementation, but after ``c = []; d =
+[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
+created empty lists. (Note that ``c = d = []`` assigns the same object to both
+``c`` and ``d``.)
+
+
+.. _types:
+
+The standard type hierarchy
+===========================
+
+.. index::
+ single: type
+ pair: data; type
+ pair: type; hierarchy
+ pair: extension; module
+ pair: C; language
+
+Below is a list of the types that are built into Python. Extension modules
+(written in C, Java, or other languages, depending on the implementation) can
+define additional types. Future versions of Python may add types to the type
+hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.).
+
+.. index::
+ single: attribute
+ pair: special; attribute
+ triple: generic; special; attribute
+
+Some of the type descriptions below contain a paragraph listing 'special
+attributes.' These are attributes that provide access to the implementation and
+are not intended for general use. Their definition may change in the future.
+
+None
+ .. index:: object: None
+
+ This type has a single value. There is a single object with this value. This
+ object is accessed through the built-in name ``None``. It is used to signify the
+ absence of a value in many situations, e.g., it is returned from functions that
+ don't explicitly return anything. Its truth value is false.
+
+NotImplemented
+ .. index:: object: NotImplemented
+
+ This type has a single value. There is a single object with this value. This
+ object is accessed through the built-in name ``NotImplemented``. Numeric methods
+ and rich comparison methods may return this value if they do not implement the
+ operation for the operands provided. (The interpreter will then try the
+ reflected operation, or some other fallback, depending on the operator.) Its
+ truth value is true.
+
+Ellipsis
+ .. index:: object: Ellipsis
+
+ This type has a single value. There is a single object with this value. This
+ object is accessed through the literal ``...`` or the built-in name
+ ``Ellipsis``. Its truth value is true.
+
+Numbers
+ .. index:: object: numeric
+
+ These are created by numeric literals and returned as results by arithmetic
+ operators and arithmetic built-in functions. Numeric objects are immutable;
+ once created their value never changes. Python numbers are of course strongly
+ related to mathematical numbers, but subject to the limitations of numerical
+ representation in computers.
+
+ Python distinguishes between integers, floating point numbers, and complex
+ numbers:
+
+ Integers
+ .. index:: object: integer
+
+ These represent elements from the mathematical set of integers (positive and
+ negative).
+
+ There are three types of integers:
+
+ Plain integers
+ .. index::
+ object: plain integer
+ single: OverflowError (built-in exception)
+
+ These represent numbers in the range -2147483648 through 2147483647. (The range
+ may be larger on machines with a larger natural word size, but not smaller.)
+ When the result of an operation would fall outside this range, the result is
+ normally returned as a long integer (in some cases, the exception
+ :exc:`OverflowError` is raised instead). For the purpose of shift and mask
+ operations, integers are assumed to have a binary, 2's complement notation using
+ 32 or more bits, and hiding no bits from the user (i.e., all 4294967296
+ different bit patterns correspond to different values).
+
+ Long integers
+ .. index:: object: long integer
+
+ These represent numbers in an unlimited range, subject to available (virtual)
+ memory only. For the purpose of shift and mask operations, a binary
+ representation is assumed, and negative numbers are represented in a variant of
+ 2's complement which gives the illusion of an infinite string of sign bits
+ extending to the left.
+
+ Booleans
+ .. index::
+ object: Boolean
+ single: False
+ single: True
+
+ These represent the truth values False and True. The two objects representing
+ the values False and True are the only Boolean objects. The Boolean type is a
+ subtype of plain integers, and Boolean values behave like the values 0 and 1,
+ respectively, in almost all contexts, the exception being that when converted to
+ a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
+
+ .. index:: pair: integer; representation
+
+ The rules for integer representation are intended to give the most meaningful
+ interpretation of shift and mask operations involving negative integers and the
+ least surprises when switching between the plain and long integer domains. Any
+ operation except left shift, if it yields a result in the plain integer domain
+ without causing overflow, will yield the same result in the long integer domain
+ or when using mixed operands.
+
+ .. % Integers
+
+ Floating point numbers
+ .. index::
+ object: floating point
+ pair: floating point; number
+ pair: C; language
+ pair: Java; language
+
+ These represent machine-level double precision floating point numbers. You are
+ at the mercy of the underlying machine architecture (and C or Java
+ implementation) for the accepted range and handling of overflow. Python does not
+ support single-precision floating point numbers; the savings in processor and
+ memory usage that are usually the reason for using these is dwarfed by the
+ overhead of using objects in Python, so there is no reason to complicate the
+ language with two kinds of floating point numbers.
+
+ Complex numbers
+ .. index::
+ object: complex
+ pair: complex; number
+
+ These represent complex numbers as a pair of machine-level double precision
+ floating point numbers. The same caveats apply as for floating point numbers.
+ The real and imaginary parts of a complex number ``z`` can be retrieved through
+ the read-only attributes ``z.real`` and ``z.imag``.
+
+ .. % Numbers
+
+Sequences
+ .. index::
+ builtin: len
+ object: sequence
+ single: index operation
+ single: item selection
+ single: subscription
+
+ These represent finite ordered sets indexed by non-negative numbers. The
+ built-in function :func:`len` returns the number of items of a sequence. When
+ the length of a sequence is *n*, the index set contains the numbers 0, 1,
+ ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``.
+
+ .. index:: single: slicing
+
+ Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
+ that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a
+ sequence of the same type. This implies that the index set is renumbered so
+ that it starts at 0.
+
+ .. index:: single: extended slicing
+
+ Some sequences also support "extended slicing" with a third "step" parameter:
+ ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
+ ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
+
+ Sequences are distinguished according to their mutability:
+
+ Immutable sequences
+ .. index::
+ object: immutable sequence
+ object: immutable
+
+ An object of an immutable sequence type cannot change once it is created. (If
+ the object contains references to other objects, these other objects may be
+ mutable and may be changed; however, the collection of objects directly
+ referenced by an immutable object cannot change.)
+
+ The following types are immutable sequences:
+
+ Strings
+ .. index::
+ builtin: chr
+ builtin: ord
+ object: string
+ single: character
+ single: byte
+ single: ASCII@ASCII
+
+ The items of a string are characters. There is no separate character type; a
+ character is represented by a string of one item. Characters represent (at
+ least) 8-bit bytes. The built-in functions :func:`chr` and :func:`ord` convert
+ between characters and nonnegative integers representing the byte values. Bytes
+ with the values 0-127 usually represent the corresponding ASCII values, but the
+ interpretation of values is up to the program. The string data type is also
+ used to represent arrays of bytes, e.g., to hold data read from a file.
+
+ .. index::
+ single: ASCII@ASCII
+ single: EBCDIC
+ single: character set
+ pair: string; comparison
+ builtin: chr
+ builtin: ord
+
+ (On systems whose native character set is not ASCII, strings may use EBCDIC in
+ their internal representation, provided the functions :func:`chr` and
+ :func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison
+ preserves the ASCII order. Or perhaps someone can propose a better rule?)
+
+ Unicode
+ .. index::
+ builtin: unichr
+ builtin: ord
+ builtin: unicode
+ object: unicode
+ single: character
+ single: integer
+ single: Unicode
+
+ The items of a Unicode object are Unicode code units. A Unicode code unit is
+ represented by a Unicode object of one item and can hold either a 16-bit or
+ 32-bit value representing a Unicode ordinal (the maximum value for the ordinal
+ is given in ``sys.maxunicode``, and depends on how Python is configured at
+ compile time). Surrogate pairs may be present in the Unicode object, and will
+ be reported as two separate items. The built-in functions :func:`unichr` and
+ :func:`ord` convert between code units and nonnegative integers representing the
+ Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to
+ other encodings are possible through the Unicode method :meth:`encode` and the
+ built-in function :func:`unicode`.
+
+ Tuples
+ .. index::
+ object: tuple
+ pair: singleton; tuple
+ pair: empty; tuple
+
+ The items of a tuple are arbitrary Python objects. Tuples of two or more items
+ are formed by comma-separated lists of expressions. A tuple of one item (a
+ 'singleton') can be formed by affixing a comma to an expression (an expression
+ by itself does not create a tuple, since parentheses must be usable for grouping
+ of expressions). An empty tuple can be formed by an empty pair of parentheses.
+
+ .. % Immutable sequences
+
+ Mutable sequences
+ .. index::
+ object: mutable sequence
+ object: mutable
+ pair: assignment; statement
+ single: delete
+ statement: del
+ single: subscription
+ single: slicing
+
+ Mutable sequences can be changed after they are created. The subscription and
+ slicing notations can be used as the target of assignment and :keyword:`del`
+ (delete) statements.
+
+ There is currently a single intrinsic mutable sequence type:
+
+ Lists
+ .. index:: object: list
+
+ The items of a list are arbitrary Python objects. Lists are formed by placing a
+ comma-separated list of expressions in square brackets. (Note that there are no
+ special cases needed to form lists of length 0 or 1.)
+
+ .. index:: module: array
+
+ The extension module :mod:`array` provides an additional example of a mutable
+ sequence type.
+
+ .. % Mutable sequences
+
+ .. % Sequences
+
+Set types
+ .. index::
+ builtin: len
+ object: set type
+
+ These represent unordered, finite sets of unique, immutable objects. As such,
+ they cannot be indexed by any subscript. However, they can be iterated over, and
+ the built-in function :func:`len` returns the number of items in a set. Common
+ uses for sets are fast membership testing, removing duplicates from a sequence,
+ and computing mathematical operations such as intersection, union, difference,
+ and symmetric difference.
+
+ For set elements, the same immutability rules apply as for dictionary keys. Note
+ that numeric types obey the normal rules for numeric comparison: if two numbers
+ compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
+ set.
+
+ There are currently two intrinsic set types:
+
+ Sets
+ .. index:: object: set
+
+ 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`.
+
+ Frozen sets
+ .. index:: object: frozenset
+
+ These represent an immutable set. They are created by the built-in
+ :func:`frozenset` constructor. As a frozenset is immutable and hashable, it can
+ be used again as an element of another set, or as a dictionary key.
+
+ .. % Set types
+
+Mappings
+ .. index::
+ builtin: len
+ single: subscription
+ object: mapping
+
+ These represent finite sets of objects indexed by arbitrary index sets. The
+ subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
+ ``a``; this can be used in expressions and as the target of assignments or
+ :keyword:`del` statements. The built-in function :func:`len` returns the number
+ of items in a mapping.
+
+ There is currently a single intrinsic mapping type:
+
+ Dictionaries
+ .. index:: object: dictionary
+
+ These represent finite sets of objects indexed by nearly arbitrary values. The
+ only types of values not acceptable as keys are values containing lists or
+ dictionaries or other mutable types that are compared by value rather than by
+ object identity, the reason being that the efficient implementation of
+ dictionaries requires a key's hash value to remain constant. Numeric types used
+ for keys obey the normal rules for numeric comparison: if two numbers compare
+ equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
+ the same dictionary entry.
+
+ Dictionaries are mutable; they can be created by the ``{...}`` notation (see
+ section :ref:`dict`).
+
+ .. index::
+ module: dbm
+ module: gdbm
+ module: bsddb
+
+ The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
+ additional examples of mapping types.
+
+ .. % Mapping types
+
+Callable types
+ .. index::
+ object: callable
+ pair: function; call
+ single: invocation
+ pair: function; argument
+
+ These are the types to which the function call operation (see section
+ :ref:`calls`) can be applied:
+
+ User-defined functions
+ .. index::
+ pair: user-defined; function
+ object: function
+ object: user-defined function
+
+ A user-defined function object is created by a function definition (see
+ section :ref:`function`). It should be called with an argument list
+ containing the same number of items as the function's formal parameter
+ list.
+
+ Special attributes:
+
+ +-------------------------+-------------------------------+-----------+
+ | Attribute | Meaning | |
+ +=========================+===============================+===========+
+ | :attr:`__doc__` | The function's documentation | Writable |
+ | | string, or ``None`` if | |
+ | | unavailable | |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__name__` | The function's name | Writable |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__module__` | The name of the module the | Writable |
+ | | function was defined in, or | |
+ | | ``None`` if unavailable. | |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__defaults__` | A tuple containing default | Writable |
+ | | argument values for those | |
+ | | arguments that have defaults, | |
+ | | or ``None`` if no arguments | |
+ | | have a default value | |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__code__` | The code object representing | Writable |
+ | | the compiled function body. | |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__globals__` | A reference to the dictionary | Read-only |
+ | | that holds the function's | |
+ | | global variables --- the | |
+ | | global namespace of the | |
+ | | module in which the function | |
+ | | was defined. | |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__dict__` | The namespace supporting | Writable |
+ | | arbitrary function | |
+ | | attributes. | |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__closure__` | ``None`` or a tuple of cells | Read-only |
+ | | that contain bindings for the | |
+ | | function's free variables. | |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__annotations__` | A dict containing annotations | Writable |
+ | | of parameters. The keys of | |
+ | | the dict are the parameter | |
+ | | names, or ``'return'`` for | |
+ | | the return annotation, if | |
+ | | provided. | |
+ +-------------------------+-------------------------------+-----------+
+ | :attr:`__kwdefaults__` | A dict containing defaults | Writable |
+ | | for keyword-only parameters. | |
+ +-------------------------+-------------------------------+-----------+
+
+ Most of the attributes labelled "Writable" check the type of the assigned value.
+
+ .. versionchanged:: 2.4
+ ``__name__`` is now writable.
+
+ Function objects also support getting and setting arbitrary attributes, which
+ can be used, for example, to attach metadata to functions. Regular attribute
+ dot-notation is used to get and set such attributes. *Note that the current
+ implementation only supports function attributes on user-defined functions.
+ Function attributes on built-in functions may be supported in the future.*
+
+ 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
+
+ User-defined methods
+ .. index::
+ object: method
+ object: user-defined method
+ pair: user-defined; method
+
+ A user-defined method object combines a class, a class instance (or ``None``)
+ and any callable object (normally a user-defined function).
+
+ Special read-only attributes: :attr:`im_self` is the class instance object,
+ :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.__name__``); :attr:`__module__` is the name of the module the method
+ was defined in, or ``None`` if unavailable.
+
+ .. versionchanged:: 2.2
+ :attr:`im_self` used to refer to the class that defined the method.
+
+ .. index::
+ single: __doc__ (method attribute)
+ single: __name__ (method attribute)
+ single: __module__ (method attribute)
+ single: im_func (method attribute)
+ single: im_self (method attribute)
+
+ Methods also support accessing (but not setting) the arbitrary function
+ attributes on the underlying function object.
+
+ User-defined method objects may be created when getting an attribute of a class
+ (perhaps via an instance of that class), if that attribute is a user-defined
+ function object, an unbound user-defined method object, or a class method
+ object. When the attribute is a user-defined method object, a new method object
+ is only created if the class from which it is being retrieved is the same as, or
+ a derived class of, the class stored in the original method object; otherwise,
+ the original method object is used as it is.
+
+ .. index::
+ single: im_class (method attribute)
+ single: im_func (method attribute)
+ single: im_self (method attribute)
+
+ When a user-defined method object is created by retrieving a user-defined
+ function object from a class, its :attr:`im_self` attribute is ``None``
+ and the method object is said to be unbound. When one is created by
+ retrieving a user-defined function object from a class via one of its
+ instances, its :attr:`im_self` attribute is the instance, and the method
+ object is said to be bound. In either case, the new method's
+ :attr:`im_class` attribute is the class from which the retrieval takes
+ place, and its :attr:`im_func` attribute is the original function object.
+
+ .. index:: single: im_func (method attribute)
+
+ When a user-defined method object is created by retrieving another method object
+ from a class or instance, the behaviour is the same as for a function object,
+ except that the :attr:`im_func` attribute of the new instance is not the
+ original method object but its :attr:`im_func` attribute.
+
+ .. index::
+ single: im_class (method attribute)
+ single: im_func (method attribute)
+ single: im_self (method attribute)
+
+ 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.
+
+ When an unbound user-defined method object is called, the underlying function
+ (:attr:`im_func`) is called, with the restriction that the first argument must
+ be an instance of the proper class (:attr:`im_class`) or of a derived class
+ thereof.
+
+ When a bound user-defined method object is called, the underlying function
+ (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in
+ front of the argument list. For instance, when :class:`C` is a class which
+ contains a definition for a function :meth:`f`, and ``x`` is an instance of
+ :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``.
+
+ When a user-defined method object is derived from a class method object, the
+ "class instance" stored in :attr:`im_self` will actually be the class itself, so
+ that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)``
+ where ``f`` is the underlying function.
+
+ Note that the transformation from function object to (unbound or bound) method
+ object happens each time the attribute is retrieved from the class or instance.
+ In some cases, a fruitful optimization is to assign the attribute to a local
+ variable and call that local variable. Also notice that this transformation only
+ happens for user-defined functions; other callable objects (and all non-callable
+ objects) are retrieved without transformation. It is also important to note
+ that user-defined functions which are attributes of a class instance are not
+ converted to bound methods; this *only* happens when the function is an
+ attribute of the class.
+
+ Generator functions
+ .. index::
+ single: generator; function
+ single: generator; iterator
+
+ A function or method which uses the :keyword:`yield` statement (see section
+ :ref:`yield`) is called a :dfn:`generator
+ 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 using the :keyword:`yield` statement. When the function executes a
+ :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
+ exception is raised and the iterator will have reached the end of the set of
+ values to be returned.
+
+ Built-in functions
+ .. index::
+ object: built-in function
+ object: function
+ pair: C; language
+
+ A built-in function object is a wrapper around a C function. Examples of
+ built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
+ 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
+ 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.
+
+ Built-in methods
+ .. index::
+ object: built-in method
+ object: method
+ pair: built-in; method
+
+ This is really a different disguise of a built-in function, this time containing
+ an object passed to the C function as an implicit extra argument. An example of
+ 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*.
+
+ Class Types
+ Class types, or "new-style classes," are callable. These objects normally act
+ as factories for new instances of themselves, but variations are possible for
+ class types that override :meth:`__new__`. The arguments of the call are passed
+ to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize
+ the new instance.
+
+ Classic Classes
+ .. index::
+ single: __init__() (object method)
+ object: class
+ object: class instance
+ object: instance
+ pair: class object; call
+
+ Class objects are described below. When a class object is called, a new class
+ instance (also described below) is created and returned. This implies a call to
+ the class's :meth:`__init__` method if it has one. Any arguments are passed on
+ to the :meth:`__init__` method. If there is no :meth:`__init__` method, the
+ class must be called without arguments.
+
+ Class instances
+ Class instances are described below. Class instances are callable only when the
+ class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for
+ ``x.__call__(arguments)``.
+
+Modules
+ .. index::
+ statement: import
+ object: module
+
+ Modules are imported by the :keyword:`import` statement (see section
+ :ref:`import`). A module object has a
+ namespace implemented by a dictionary object (this is the dictionary referenced
+ by the __globals__ attribute of functions defined in the module). Attribute
+ references are translated to lookups in this dictionary, e.g., ``m.x`` is
+ equivalent to ``m.__dict__["x"]``. A module object does not contain the code
+ object used to initialize the module (since it isn't needed once the
+ initialization is done).
+
+ .. %
+
+ Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
+ 1`` is equivalent to ``m.__dict__["x"] = 1``.
+
+ .. index:: single: __dict__ (module attribute)
+
+ Special read-only attribute: :attr:`__dict__` is the module's namespace as a
+ dictionary object.
+
+ .. index::
+ single: __name__ (module attribute)
+ single: __doc__ (module attribute)
+ single: __file__ (module attribute)
+ pair: module; namespace
+
+ Predefined (writable) attributes: :attr:`__name__` is the module's name;
+ :attr:`__doc__` is the module's documentation string, or ``None`` if
+ unavailable; :attr:`__file__` is the pathname of the file from which the module
+ was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not
+ present for C modules that are statically linked into the interpreter; for
+ extension modules loaded dynamically from a shared library, it is the pathname
+ of the shared library file.
+
+Classes
+ Class objects are created by class definitions (see section :ref:`class`). A
+ class has a namespace implemented by a dictionary object. Class attribute
+ references are translated to lookups in this dictionary, e.g., ``C.x`` is
+ translated to ``C.__dict__["x"]``. When the attribute name is not found
+ there, the attribute search continues in the base classes. The search is
+ depth-first, left-to-right in the order of occurrence in the base class list.
+
+ .. index::
+ object: class
+ object: class instance
+ object: instance
+ pair: class object; call
+ single: container
+ object: dictionary
+ pair: class; attribute
+
+ When a class attribute reference (for class :class:`C`, say) would yield a
+ user-defined function object or an unbound user-defined method object whose
+ associated class is either :class:`C` or one of its base classes, it is
+ 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
+ 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__`.
+
+ .. index:: triple: class; attribute; assignment
+
+ Class attribute assignments update the class's dictionary, never the dictionary
+ of a base class.
+
+ .. index:: pair: class object; call
+
+ A class object can be called (see above) to yield a class instance (see below).
+
+ .. index::
+ single: __name__ (class attribute)
+ single: __module__ (class attribute)
+ single: __dict__ (class attribute)
+ 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
+ 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.
+
+Class instances
+ .. index::
+ object: class instance
+ object: instance
+ pair: class; instance
+ pair: class instance; attribute
+
+ A class instance is created by calling a class object (see above). A class
+ instance has a namespace implemented as a dictionary which is the first place in
+ which attribute references are searched. When an attribute is not found there,
+ and the instance's class has an attribute by that name, the search continues
+ with the class attributes. If a class attribute is found that is a user-defined
+ function object or an unbound user-defined method object whose associated class
+ is the class (call it :class:`C`) of the instance for which the attribute
+ reference was initiated or one of its bases, it is transformed into a bound
+ user-defined method object whose :attr:`im_class` attribute is :class:`C` and
+ whose :attr:`im_self` attribute is the instance. Static method and class method
+ 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
+ class attribute is found, and the object's class has a :meth:`__getattr__`
+ method, that is called to satisfy the lookup.
+
+ .. index:: triple: class instance; attribute; assignment
+
+ Attribute assignments and deletions update the instance's dictionary, never a
+ class's dictionary. If the class has a :meth:`__setattr__` or
+ :meth:`__delattr__` method, this is called instead of updating the instance
+ dictionary directly.
+
+ .. index::
+ object: numeric
+ object: sequence
+ object: mapping
+
+ Class instances can pretend to be numbers, sequences, or mappings if they have
+ methods with certain special names. See section :ref:`specialnames`.
+
+ .. index::
+ single: __dict__ (instance attribute)
+ single: __class__ (instance attribute)
+
+ Special attributes: :attr:`__dict__` is the attribute dictionary;
+ :attr:`__class__` is the instance's class.
+
+Files
+ .. index::
+ object: file
+ builtin: open
+ single: popen() (in module os)
+ single: makefile() (socket method)
+ single: sys.stdin
+ single: sys.stdout
+ single: sys.stderr
+ single: stdio
+ single: stdin (in module sys)
+ single: stdout (in module sys)
+ single: stderr (in module sys)
+
+ A file object represents an open file. File objects are created by the
+ :func:`open` built-in function, and also by :func:`os.popen`,
+ :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and
+ perhaps by other functions or methods provided by extension modules). The
+ objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to
+ file objects corresponding to the interpreter's standard input, output and
+ error streams. See :ref:`bltin-file-objects` for complete documentation of
+ file objects.
+
+Internal types
+ .. index::
+ single: internal type
+ single: types, internal
+
+ A few types used internally by the interpreter are exposed to the user. Their
+ definitions may change with future versions of the interpreter, but they are
+ mentioned here for completeness.
+
+ Code objects
+ .. index::
+ single: bytecode
+ object: code
+
+ Code objects represent *byte-compiled* executable Python code, or *bytecode*.
+ The difference between a code object and a function object is that the function
+ object contains an explicit reference to the function's globals (the module in
+ which it was defined), while a code object contains no context; also the default
+ argument values are stored in the function object, not in the code object
+ (because they represent values calculated at run-time). Unlike function
+ objects, code objects are immutable and contain no references (directly or
+ indirectly) to mutable objects.
+
+ Special read-only attributes: :attr:`co_name` gives the function name;
+ :attr:`co_argcount` is the number of positional arguments (including arguments
+ with default values); :attr:`co_nlocals` is the number of local variables used
+ by the function (including arguments); :attr:`co_varnames` is a tuple containing
+ the names of the local variables (starting with the argument names);
+ :attr:`co_cellvars` is a tuple containing the names of local variables that are
+ referenced by nested functions; :attr:`co_freevars` is a tuple containing the
+ names of free variables; :attr:`co_code` is a string representing the sequence
+ of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
+ used by the bytecode; :attr:`co_names` is a tuple containing the names used by
+ the bytecode; :attr:`co_filename` is the filename from which the code was
+ compiled; :attr:`co_firstlineno` is the first line number of the function;
+ :attr:`co_lnotab` is a string encoding the mapping from byte code offsets to
+ line numbers (for details see the source code of the interpreter);
+ :attr:`co_stacksize` is the required stack size (including local variables);
+ :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
+
+ The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
+ the function uses the ``*arguments`` syntax to accept an arbitrary number of
+ positional arguments; bit ``0x08`` is set if the function uses the
+ ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
+ if the function is a generator.
+
+ Future feature declarations (``from __future__ import division``) also use bits
+ in :attr:`co_flags` to indicate whether a code object was compiled with a
+ particular feature enabled: bit ``0x2000`` is set if the function was compiled
+ with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
+ versions of Python.
+
+ Other bits in :attr:`co_flags` are reserved for internal use.
+
+ .. index:: single: documentation string
+
+ If a code object represents a function, the first item in :attr:`co_consts` is
+ the documentation string of the function, or ``None`` if undefined.
+
+ Frame objects
+ .. index:: object: frame
+
+ Frame objects represent execution frames. They may occur in traceback objects
+ (see below).
+
+ .. index::
+ single: f_back (frame attribute)
+ single: f_code (frame attribute)
+ single: f_globals (frame attribute)
+ single: f_locals (frame attribute)
+ single: f_lasti (frame attribute)
+ single: f_builtins (frame attribute)
+
+ Special read-only attributes: :attr:`f_back` is to the previous stack frame
+ (towards the caller), or ``None`` if this is the bottom stack frame;
+ :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
+ is the dictionary used to look up local variables; :attr:`f_globals` is used for
+ global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
+ :attr:`f_lasti` gives the precise instruction (this is an index into the
+ bytecode string of the code object).
+
+ .. index::
+ single: f_trace (frame attribute)
+ single: f_exc_type (frame attribute)
+ single: f_exc_value (frame attribute)
+ single: f_exc_traceback (frame attribute)
+ single: f_lineno (frame attribute)
+
+ Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
+ called at the start of each source code line (this is used by the debugger);
+ :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the
+ last exception raised in the parent frame provided another exception was ever
+ raised in the current frame (in all other cases they are None); :attr:`f_lineno`
+ is the current line number of the frame --- writing to this from within a trace
+ function jumps to the given line (only for the bottom-most frame). A debugger
+ can implement a Jump command (aka Set Next Statement) by writing to f_lineno.
+
+ Traceback objects
+ .. index::
+ object: traceback
+ pair: stack; trace
+ pair: exception; handler
+ pair: execution; stack
+ single: exc_info (in module sys)
+ single: exc_traceback (in module sys)
+ single: last_traceback (in module sys)
+ single: sys.exc_info
+ single: sys.last_traceback
+
+ Traceback objects represent a stack trace of an exception. A traceback object
+ is created when an exception occurs. When the search for an exception handler
+ unwinds the execution stack, at each unwound level a traceback object is
+ inserted in front of the current traceback. When an exception handler is
+ entered, the stack trace is made available to the program. (See section
+ :ref:`try`.) It is accessible as the third item of the
+ tuple returned by ``sys.exc_info()``. When the program contains no suitable
+ handler, the stack trace is written (nicely formatted) to the standard error
+ stream; if the interpreter is interactive, it is also made available to the user
+ as ``sys.last_traceback``.
+
+ .. index::
+ single: tb_next (traceback attribute)
+ single: tb_frame (traceback attribute)
+ single: tb_lineno (traceback attribute)
+ single: tb_lasti (traceback attribute)
+ statement: try
+
+ Special read-only attributes: :attr:`tb_next` is the next level in the stack
+ trace (towards the frame where the exception occurred), or ``None`` if there is
+ no next level; :attr:`tb_frame` points to the execution frame of the current
+ level; :attr:`tb_lineno` gives the line number where the exception occurred;
+ :attr:`tb_lasti` indicates the precise instruction. The line number and last
+ instruction in the traceback may differ from the line number of its frame object
+ if the exception occurred in a :keyword:`try` statement with no matching except
+ clause or with a finally clause.
+
+ Slice objects
+ .. index:: builtin: slice
+
+ Slice objects are used to represent slices when *extended slice syntax* is used.
+ This is a slice using two colons, or multiple slices or ellipses separated by
+ commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``. They are
+ also created by the built-in :func:`slice` function.
+
+ .. index::
+ single: start (slice object attribute)
+ single: stop (slice object attribute)
+ 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.
+
+ Slice objects support one method:
+
+
+ .. method:: slice.indices(self, length)
+
+ This method takes a single integer argument *length* and computes information
+ about the extended slice that the slice object would describe if applied to a
+ sequence of *length* items. It returns a tuple of three integers; respectively
+ these are the *start* and *stop* indices and the *step* or stride length of the
+ slice. Missing or out-of-bounds indices are handled in a manner consistent with
+ regular slices.
+
+ .. versionadded:: 2.3
+
+ Static method objects
+ Static method objects provide a way of defeating the transformation of function
+ objects to method objects described above. A static method object is a wrapper
+ around any other object, usually a user-defined method object. When a static
+ method object is retrieved from a class or a class instance, the object actually
+ returned is the wrapped object, which is not subject to any further
+ transformation. Static method objects are not themselves callable, although the
+ objects they wrap usually are. Static method objects are created by the built-in
+ :func:`staticmethod` constructor.
+
+ Class method objects
+ A class method object, like a static method object, is a wrapper around another
+ object that alters the way in which that object is retrieved from classes and
+ class instances. The behaviour of class method objects upon such retrieval is
+ described above, under "User-defined methods". Class method objects are created
+ by the built-in :func:`classmethod` constructor.
+
+ .. % Internal types
+
+.. % Types
+.. % =========================================================================
+
+
+New-style and classic classes
+=============================
+
+Classes and instances come in two flavors: old-style or classic, and new-style.
+
+Up to Python 2.1, old-style classes were the only flavour available to the user.
+The concept of (old-style) class is unrelated to the concept of type: if *x* is
+an instance of an old-style class, then ``x.__class__`` designates the class of
+*x*, but ``type(x)`` is always ``<type 'instance'>``. This reflects the fact
+that all old-style instances, independently of their class, are implemented with
+a single built-in type, called ``instance``.
+
+New-style classes were introduced in Python 2.2 to unify classes and types. A
+new-style class neither more nor less than a user-defined type. If *x* is an
+instance of a new-style class, then ``type(x)`` is the same as ``x.__class__``.
+
+The major motivation for introducing new-style classes is to provide a unified
+object model with a full meta-model. It also has a number of immediate
+benefits, like the ability to subclass most built-in types, or the introduction
+of "descriptors", which enable computed properties.
+
+For compatibility reasons, classes are still old-style by default. New-style
+classes are created by specifying another new-style class (i.e. a type) as a
+parent class, or the "top-level type" :class:`object` if no other parent is
+needed. The behaviour of new-style classes differs from that of old-style
+classes in a number of important details in addition to what :func:`type`
+returns. Some of these changes are fundamental to the new object model, like
+the way special methods are invoked. Others are "fixes" that could not be
+implemented before for compatibility concerns, like the method resolution order
+in case of multiple inheritance.
+
+This manual is not up-to-date with respect to new-style classes. For now,
+please see http://www.python.org/doc/newstyle.html for more information.
+
+.. index::
+ single: class
+ single: class
+ single: class
+
+The plan is to eventually drop old-style classes, leaving only the semantics of
+new-style classes. This change will probably only be feasible in Python 3.0.
+new-style classic old-style
+
+.. % =========================================================================
+
+
+.. _specialnames:
+
+Special method names
+====================
+
+.. index::
+ pair: operator; overloading
+ single: __getitem__() (mapping object method)
+
+A class can implement certain operations that are invoked by special syntax
+(such as arithmetic operations or subscripting and slicing) by defining methods
+with special names. This is Python's approach to :dfn:`operator overloading`,
+allowing classes to define their own behavior with respect to language
+operators. For instance, if a class defines a method named :meth:`__getitem__`,
+and ``x`` is an instance of this class, then ``x[i]`` is equivalent [#]_ to
+``x.__getitem__(i)``. Except where mentioned, attempts to execute an operation
+raise an exception when no appropriate method is defined.
+
+When implementing a class that emulates any built-in type, it is important that
+the emulation only be implemented to the degree that it makes sense for the
+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.)
+
+
+.. _customization:
+
+Basic customization
+-------------------
+
+
+.. method:: object.__new__(cls[, ...])
+
+ Called to create a new instance of class *cls*. :meth:`__new__` is a static
+ method (special-cased so you need not declare it as such) that takes the class
+ of which an instance was requested as its first argument. The remaining
+ arguments are those passed to the object constructor expression (the call to the
+ class). The return value of :meth:`__new__` should be the new object instance
+ (usually an instance of *cls*).
+
+ Typical implementations create a new instance of the class by invoking the
+ superclass's :meth:`__new__` method using ``super(currentclass,
+ cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the
+ newly-created instance as necessary before returning it.
+
+ If :meth:`__new__` returns an instance of *cls*, then the new instance's
+ :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where
+ *self* is the new instance and the remaining arguments are the same as were
+ passed to :meth:`__new__`.
+
+ If :meth:`__new__` does not return an instance of *cls*, then the new instance's
+ :meth:`__init__` method will not be invoked.
+
+ :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
+ int, str, or tuple) to customize instance creation.
+
+
+.. method:: object.__init__(self[, ...])
+
+ .. index:: pair: class; constructor
+
+ Called when the instance is created. The arguments are those passed to the
+ class constructor expression. If a base class has an :meth:`__init__` method,
+ the derived class's :meth:`__init__` method, if any, must explicitly call it to
+ ensure proper initialization of the base class part of the instance; for
+ example: ``BaseClass.__init__(self, [args...])``. As a special constraint on
+ constructors, no value may be returned; doing so will cause a :exc:`TypeError`
+ to be raised at runtime.
+
+
+.. method:: object.__del__(self)
+
+ .. index::
+ single: destructor
+ statement: del
+
+ Called when the instance is about to be destroyed. This is also called a
+ destructor. If a base class has a :meth:`__del__` method, the derived class's
+ :meth:`__del__` method, if any, must explicitly call it to ensure proper
+ deletion of the base class part of the instance. Note that it is possible
+ (though not recommended!) for the :meth:`__del__` method to postpone destruction
+ of the instance by creating a new reference to it. It may then be called at a
+ later time when this new reference is deleted. It is not guaranteed that
+ :meth:`__del__` methods are called for objects that still exist when the
+ interpreter exits.
+
+ .. note::
+
+ ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
+ the reference count for ``x`` by one, and the latter is only called when
+ ``x``'s reference count reaches zero. Some common situations that may
+ prevent the reference count of an object from going to zero include:
+ circular references between objects (e.g., a doubly-linked list or a tree
+ data structure with parent and child pointers); a reference to the object
+ on the stack frame of a function that caught an exception (the traceback
+ stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a
+ reference to the object on the stack frame that raised an unhandled
+ exception in interactive mode (the traceback stored in
+ ``sys.last_traceback`` keeps the stack frame alive). The first situation
+ can only be remedied by explicitly breaking the cycles; the latter two
+ situations can be resolved by storing ``None`` in ``sys.last_traceback``.
+ Circular references which are garbage are detected when the option cycle
+ detector is enabled (it's on by default), but can only be cleaned up if
+ there are no Python- level :meth:`__del__` methods involved. Refer to the
+ documentation for the :mod:`gc` module for more information about how
+ :meth:`__del__` methods are handled by the cycle detector, particularly
+ the description of the ``garbage`` value.
+
+ .. warning::
+
+ Due to the precarious circumstances under which :meth:`__del__` methods are
+ invoked, exceptions that occur during their execution are ignored, and a warning
+ is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in
+ response to a module being deleted (e.g., when execution of the program is
+ done), other globals referenced by the :meth:`__del__` method may already have
+ been deleted. For this reason, :meth:`__del__` methods should do the absolute
+ minimum needed to maintain external invariants. Starting with version 1.5,
+ Python guarantees that globals whose name begins with a single underscore are
+ deleted from their module before other globals are deleted; if no other
+ references to such globals exist, this may help in assuring that imported
+ modules are still available at the time when the :meth:`__del__` method is
+ called.
+
+
+.. method:: object.__repr__(self)
+
+ .. index:: builtin: repr
+
+ Called by the :func:`repr` built-in function and by string conversions (reverse
+ quotes) to compute the "official" string representation of an object. If at all
+ possible, this should look like a valid Python expression that could be used to
+ recreate an object with the same value (given an appropriate environment). If
+ this is not possible, a string of the form ``<...some useful description...>``
+ should be returned. The return value must be a string object. If a class
+ defines :meth:`__repr__` but not :meth:`__str__`, then :meth:`__repr__` is also
+ used when an "informal" string representation of instances of that class is
+ required.
+
+ .. index::
+ pair: string; conversion
+ pair: reverse; quotes
+ pair: backward; quotes
+ single: back-quotes
+
+ This is typically used for debugging, so it is important that the representation
+ is information-rich and unambiguous.
+
+
+.. method:: object.__str__(self)
+
+ .. index::
+ builtin: str
+ statement: print
+
+ Called by the :func:`str` built-in function and by the :keyword:`print`
+ statement to compute the "informal" string representation of an object. This
+ differs from :meth:`__repr__` in that it does not have to be a valid Python
+ expression: a more convenient or concise representation may be used instead.
+ The return value must be a string object.
+
+
+.. method:: object.__lt__(self, other)
+ object.__le__(self, other)
+ object.__eq__(self, other)
+ object.__ne__(self, other)
+ object.__gt__(self, other)
+ object.__ge__(self, other)
+
+ .. versionadded:: 2.1
+
+ These are the so-called "rich comparison" methods, and are called for comparison
+ operators in preference to :meth:`__cmp__` below. The correspondence between
+ operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
+ ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` calls
+ ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
+ ``x.__ge__(y)``.
+
+ A rich comparison method may return the singleton ``NotImplemented`` if it does
+ not implement the operation for a given pair of arguments. By convention,
+ ``False`` and ``True`` are returned for a successful comparison. However, these
+ methods can return any value, so if the comparison operator is used in a Boolean
+ context (e.g., in the condition of an ``if`` statement), Python will call
+ :func:`bool` on the value to determine if the result is true or false.
+
+ There are no implied relationships among the comparison operators. The truth of
+ ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when defining
+ :meth:`__eq__`, one should also define :meth:`__ne__` so that the operators will
+ behave as expected.
+
+ There are no reflected (swapped-argument) versions of these methods (to be used
+ when the left argument does not support the operation but the right argument
+ does); rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
+ :meth:`__le__` and :meth:`__ge__` are each other's reflection, and
+ :meth:`__eq__` and :meth:`__ne__` are their own reflection.
+
+ Arguments to rich comparison methods are never coerced.
+
+
+.. method:: object.__cmp__(self, other)
+
+ .. index::
+ builtin: cmp
+ single: comparisons
+
+ Called by comparison operations if rich comparison (see above) is not defined.
+ Should return a negative integer if ``self < other``, zero if ``self == other``,
+ a positive integer if ``self > other``. If no :meth:`__cmp__`, :meth:`__eq__`
+ or :meth:`__ne__` operation is defined, class instances are compared by object
+ identity ("address"). See also the description of :meth:`__hash__` for some
+ important notes on creating objects which support custom comparison operations
+ and are usable as dictionary keys. (Note: the restriction that exceptions are
+ not propagated by :meth:`__cmp__` has been removed since Python 1.5.)
+
+
+.. method:: object.__rcmp__(self, other)
+
+ .. versionchanged:: 2.1
+ No longer supported.
+
+
+.. method:: object.__hash__(self)
+
+ .. index::
+ object: dictionary
+ builtin: hash
+
+ Called for the key object for dictionary operations, and by the built-in
+ function :func:`hash`. Should return a 32-bit integer usable as a hash value
+ for dictionary operations. The only required property is that objects which
+ compare equal have the same hash value; it is advised to somehow mix together
+ (e.g., using exclusive or) the hash values for the components of the object that
+ also play a part in comparison of objects. If a class does not define a
+ :meth:`__cmp__` method it should not define a :meth:`__hash__` operation either;
+ if it defines :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its
+ instances will not be usable as dictionary keys. If a class defines mutable
+ objects and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
+ implement :meth:`__hash__`, since the dictionary implementation requires that a
+ key's hash value is immutable (if the object's hash value changes, it will be in
+ the wrong hash bucket).
+
+ .. versionchanged:: 2.5
+ :meth:`__hash__` may now also return a long integer object; the 32-bit integer
+ is then derived from the hash of that object.
+
+ .. index:: single: __cmp__() (object method)
+
+
+.. method:: object.__bool__(self)
+
+ .. index:: single: __len__() (mapping object method)
+
+ Called to implement truth value testing, and the built-in operation ``bool()``;
+ should return ``False`` or ``True``. When this method is not defined,
+ :meth:`__len__` is called, if it is defined (see below) and ``True`` is returned
+ when the length is not zero. If a class defines neither :meth:`__len__` nor
+ :meth:`__bool__`, all its instances are considered true.
+
+
+.. method:: object.__unicode__(self)
+
+ .. index:: builtin: unicode
+
+ Called to implement :func:`unicode` builtin; should return a Unicode object.
+ When this method is not defined, string conversion is attempted, and the result
+ of string conversion is converted to Unicode using the system default encoding.
+
+
+.. _attribute-access:
+
+Customizing attribute access
+----------------------------
+
+The following methods can be defined to customize the meaning of attribute
+access (use of, assignment to, or deletion of ``x.name``) for class instances.
+
+
+.. method:: object.__getattr__(self, name)
+
+ Called when an attribute lookup has not found the attribute in the usual places
+ (i.e. it is not an instance attribute nor is it found in the class tree for
+ ``self``). ``name`` is the attribute name. This method should return the
+ (computed) attribute value or raise an :exc:`AttributeError` exception.
+
+ .. index:: single: __setattr__() (object method)
+
+ Note that if the attribute is found through the normal mechanism,
+ :meth:`__getattr__` is not called. (This is an intentional asymmetry between
+ :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
+ reasons and because otherwise :meth:`__setattr__` would have no way to access
+ other attributes of the instance. Note that at least for instance variables,
+ you can fake total control by not inserting any values in the instance attribute
+ dictionary (but instead inserting them in another object). See the
+ :meth:`__getattribute__` method below for a way to actually get total control in
+ new-style classes.
+
+
+.. method:: object.__setattr__(self, name, value)
+
+ Called when an attribute assignment is attempted. This is called instead of the
+ normal mechanism (i.e. store the value in the instance dictionary). *name* is
+ the attribute name, *value* is the value to be assigned to it.
+
+ .. index:: single: __dict__ (instance attribute)
+
+ If :meth:`__setattr__` wants to assign to an instance attribute, it should not
+ simply execute ``self.name = value`` --- this would cause a recursive call to
+ itself. Instead, it should insert the value in the dictionary of instance
+ attributes, e.g., ``self.__dict__[name] = value``. For new-style classes,
+ rather than accessing the instance dictionary, it should call the base class
+ method with the same name, for example, ``object.__setattr__(self, name,
+ value)``.
+
+
+.. method:: object.__delattr__(self, name)
+
+ Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
+ should only be implemented if ``del obj.name`` is meaningful for the object.
+
+
+.. _new-style-attribute-access:
+
+More attribute access for new-style classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following methods only apply to new-style classes.
+
+
+.. method:: object.__getattribute__(self, name)
+
+ Called unconditionally to implement attribute accesses for instances of the
+ class. If the class also defines :meth:`__getattr__`, the latter will not be
+ called unless :meth:`__getattribute__` either calls it explicitly or raises an
+ :exc:`AttributeError`. This method should return the (computed) attribute value
+ or raise an :exc:`AttributeError` exception. In order to avoid infinite
+ recursion in this method, its implementation should always call the base class
+ method with the same name to access any attributes it needs, for example,
+ ``object.__getattribute__(self, name)``.
+
+
+.. _descriptors:
+
+Implementing Descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+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:: object.__get__(self, instance, owner)
+
+ Called to get the attribute of the owner class (class attribute access) or of an
+ instance of that class (instance attribute access). *owner* is always the owner
+ class, while *instance* is the instance that the attribute was accessed through,
+ or ``None`` when the attribute is accessed through the *owner*. This method
+ should return the (computed) attribute value or raise an :exc:`AttributeError`
+ exception.
+
+
+.. method:: object.__set__(self, instance, value)
+
+ Called to set the attribute on an instance *instance* of the owner class to a
+ new value, *value*.
+
+
+.. method:: object.__delete__(self, instance)
+
+ Called to delete the attribute on an instance *instance* of the owner class.
+
+
+.. _descriptor-invocation:
+
+Invoking Descriptors
+^^^^^^^^^^^^^^^^^^^^
+
+In general, a descriptor is an object attribute with "binding behavior", one
+whose attribute access has been overridden by methods in the descriptor
+protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
+those methods are defined for an object, it is said to be a descriptor.
+
+The default behavior for attribute access is to get, set, or delete the
+attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
+starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
+continuing through the base classes of ``type(a)`` excluding metaclasses.
+
+However, if the looked-up value is an object defining one of the descriptor
+methods, then Python may override the default behavior and invoke the descriptor
+method instead. Where this occurs in the precedence chain depends on which
+descriptor methods were defined and how they were called. Note that descriptors
+are only invoked for new style objects or classes (ones that subclass
+:class:`object()` or :class:`type()`).
+
+The starting point for descriptor invocation is a binding, ``a.x``. How the
+arguments are assembled depends on ``a``:
+
+Direct Call
+ The simplest and least common call is when user code directly invokes a
+ descriptor method: ``x.__get__(a)``.
+
+Instance Binding
+ If binding to a new-style object instance, ``a.x`` is transformed into the call:
+ ``type(a).__dict__['x'].__get__(a, type(a))``.
+
+Class Binding
+ If binding to a new-style class, ``A.x`` is transformed into the call:
+ ``A.__dict__['x'].__get__(None, A)``.
+
+Super Binding
+ If ``a`` is an instance of :class:`super`, then the binding ``super(B,
+ 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)``.
+
+For instance bindings, the precedence of descriptor invocation depends on the
+which descriptor methods are defined. Data descriptors define both
+:meth:`__get__` and :meth:`__set__`. Non-data descriptors have just the
+:meth:`__get__` method. Data descriptors always override a redefinition in an
+instance dictionary. In contrast, non-data descriptors can be overridden by
+instances.
+
+Python methods (including :func:`staticmethod` and :func:`classmethod`) are
+implemented as non-data descriptors. Accordingly, instances can redefine and
+override methods. This allows individual instances to acquire behaviors that
+differ from other instances of the same class.
+
+The :func:`property` function is implemented as a data descriptor. Accordingly,
+instances cannot override the behavior of a property.
+
+
+.. _slots:
+
+__slots__
+^^^^^^^^^
+
+By default, instances of both old and new-style classes have a dictionary for
+attribute storage. This wastes space for objects having very few instance
+variables. The space consumption can become acute when creating large numbers
+of instances.
+
+The default can be overridden by defining *__slots__* in a new-style class
+definition. The *__slots__* declaration takes a sequence of instance variables
+and reserves just enough space in each instance to hold a value for each
+variable. Space is saved because *__dict__* is not created for each instance.
+
+
+.. data:: __slots__
+
+ This class variable can be assigned a string, iterable, or sequence of strings
+ with variable names used by instances. If defined in a new-style class,
+ *__slots__* reserves space for the declared variables and prevents the automatic
+ creation of *__dict__* and *__weakref__* for each instance.
+
+ .. versionadded:: 2.2
+
+Notes on using *__slots__*
+
+* Without a *__dict__* variable, instances cannot be assigned new variables not
+ listed in the *__slots__* definition. Attempts to assign to an unlisted
+ variable name raises :exc:`AttributeError`. If dynamic assignment of new
+ variables is desired, then add ``'__dict__'`` to the sequence of strings in the
+ *__slots__* declaration.
+
+ .. versionchanged:: 2.3
+ Previously, adding ``'__dict__'`` to the *__slots__* declaration would not
+ enable the assignment of new attributes not specifically listed in the sequence
+ of instance variable names.
+
+* Without a *__weakref__* variable for each instance, classes defining
+ *__slots__* do not support weak references to its instances. If weak reference
+ support is needed, then add ``'__weakref__'`` to the sequence of strings in the
+ *__slots__* declaration.
+
+ .. versionchanged:: 2.3
+ Previously, adding ``'__weakref__'`` to the *__slots__* declaration would not
+ enable support for weak references.
+
+* *__slots__* are implemented at the class level by creating descriptors
+ (:ref:`descriptors`) for each variable name. As a result, class attributes
+ cannot be used to set default values for instance variables defined by
+ *__slots__*; otherwise, the class attribute would overwrite the descriptor
+ assignment.
+
+* If a class defines a slot also defined in a base class, the instance variable
+ defined by the base class slot is inaccessible (except by retrieving its
+ descriptor directly from the base class). This renders the meaning of the
+ program undefined. In the future, a check may be added to prevent this.
+
+* The action of a *__slots__* declaration is limited to the class where it is
+ defined. As a result, subclasses will have a *__dict__* unless they also define
+ *__slots__*.
+
+* *__slots__* do not work for classes derived from "variable-length" built-in
+ types such as :class:`long`, :class:`str` and :class:`tuple`.
+
+* Any non-string iterable may be assigned to *__slots__*. Mappings may also be
+ used; however, in the future, special meaning may be assigned to the values
+ corresponding to each key.
+
+* *__class__* assignment works only if both classes have the same *__slots__*.
+
+ .. versionchanged:: 2.6
+ Previously, *__class__* assignment raised an error if either new or old class
+ had *__slots__*.
+
+
+.. _metaclasses:
+
+Customizing class creation
+--------------------------
+
+By default, new-style classes are constructed using :func:`type`. A class
+definition is read into a separate namespace and the value of class name is
+bound to the result of ``type(name, bases, dict)``.
+
+When the class definition is read, if *__metaclass__* is defined then the
+callable assigned to it will be called instead of :func:`type`. The allows
+classes or functions to be written which monitor or alter the class creation
+process:
+
+* Modifying the class dictionary prior to the class being created.
+
+* Returning an instance of another class -- essentially performing the role of a
+ factory function.
+
+
+.. data:: __metaclass__
+
+ This variable can be any callable accepting arguments for ``name``, ``bases``,
+ and ``dict``. Upon class creation, the callable is used instead of the built-in
+ :func:`type`.
+
+ .. versionadded:: 2.2
+
+The appropriate metaclass is determined by the following precedence rules:
+
+* If ``dict['__metaclass__']`` exists, it is used.
+
+* Otherwise, if there is at least one base class, its metaclass is used (this
+ looks for a *__class__* attribute first and if not found, uses its type).
+
+* Otherwise, if a global variable named __metaclass__ exists, it is used.
+
+* Otherwise, the old-style, classic metaclass (types.ClassType) is used.
+
+The potential uses for metaclasses are boundless. Some ideas that have been
+explored including logging, interface checking, automatic delegation, automatic
+property creation, proxies, frameworks, and automatic resource
+locking/synchronization.
+
+
+.. _callable-types:
+
+Emulating callable objects
+--------------------------
+
+
+.. method:: object.__call__(self[, args...])
+
+ .. index:: pair: call; instance
+
+ Called when the instance is "called" as a function; if this method is defined,
+ ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
+
+
+.. _sequence-types:
+
+Emulating container types
+-------------------------
+
+The following methods can be defined to implement container objects. Containers
+usually are sequences (such as lists or tuples) or mappings (like dictionaries),
+but can represent other containers as well. The first set of methods is used
+either to emulate a sequence or to emulate a mapping; the difference is that for
+a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
+N`` where *N* is the length of the sequence, or slice objects, which define a
+range of items. (For backwards compatibility, the method :meth:`__getslice__`
+(see below) can also be defined to handle simple, but not extended slices.) It
+is also recommended that mappings provide the methods :meth:`keys`,
+: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
+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
+of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and
+:meth:`keys`. Mutable sequences should provide methods :meth:`append`,
+:meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`,
+:meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list
+objects. Finally, sequence types should implement addition (meaning
+concatenation) and multiplication (meaning repetition) by defining the methods
+:meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`,
+:meth:`__rmul__` and :meth:`__imul__` described below; they should not define
+other numerical operators. It is recommended that both mappings and sequences
+implement the :meth:`__contains__` method to allow efficient use of the ``in``
+operator; for mappings, ``in`` should be equivalent of :meth:`has_key`; for
+sequences, it should search through the values. It is further recommended that
+both mappings and sequences implement the :meth:`__iter__` method to allow
+efficient iteration through the container; for mappings, :meth:`__iter__` should
+be the same as :meth:`iterkeys`; for sequences, it should iterate through the
+values.
+
+
+.. method:: object.__len__(self)
+
+ .. index::
+ builtin: len
+ single: __bool__() (object method)
+
+ Called to implement the built-in function :func:`len`. Should return the length
+ of the object, an integer ``>=`` 0. Also, an object that doesn't define a
+ :meth:`__bool__` method and whose :meth:`__len__` method returns zero is
+ considered to be false in a Boolean context.
+
+
+.. method:: object.__getitem__(self, key)
+
+ .. index:: object: slice
+
+ Called to implement evaluation of ``self[key]``. For sequence types, the
+ accepted keys should be integers and slice objects. Note that the special
+ interpretation of negative indexes (if the class wishes to emulate a sequence
+ type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate
+ type, :exc:`TypeError` may be raised; if of a value outside the set of indexes
+ for the sequence (after any special interpretation of negative values),
+ :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not
+ in the container), :exc:`KeyError` should be raised.
+
+ .. note::
+
+ :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal
+ indexes to allow proper detection of the end of the sequence.
+
+
+.. method:: object.__setitem__(self, key, value)
+
+ Called to implement assignment to ``self[key]``. Same note as for
+ :meth:`__getitem__`. This should only be implemented for mappings if the
+ objects support changes to the values for keys, or if new keys can be added, or
+ for sequences if elements can be replaced. The same exceptions should be raised
+ for improper *key* values as for the :meth:`__getitem__` method.
+
+
+.. method:: object.__delitem__(self, key)
+
+ Called to implement deletion of ``self[key]``. Same note as for
+ :meth:`__getitem__`. This should only be implemented for mappings if the
+ objects support removal of keys, or for sequences if elements can be removed
+ from the sequence. The same exceptions should be raised for improper *key*
+ values as for the :meth:`__getitem__` method.
+
+
+.. method:: object.__iter__(self)
+
+ This method is called when an iterator is required for a container. This method
+ should return a new iterator object that can iterate over all the objects in the
+ container. For mappings, it should iterate over the keys of the container, and
+ should also be made available as the method :meth:`iterkeys`.
+
+ Iterator objects also need to implement this method; they are required to return
+ themselves. For more information on iterator objects, see :ref:`typeiter`.
+
+The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
+implemented as an iteration through a sequence. However, container objects can
+supply the following special method with a more efficient implementation, which
+also does not require the object be a sequence.
+
+
+.. method:: object.__contains__(self, item)
+
+ Called to implement membership test operators. Should return true if *item* is
+ in *self*, false otherwise. For mapping objects, this should consider the keys
+ of the mapping rather than the values or the key-item pairs.
+
+
+.. _sequence-methods:
+
+Additional methods for emulation of sequence types
+--------------------------------------------------
+
+The following optional methods can be defined to further emulate sequence
+objects. Immutable sequences methods should at most only define
+:meth:`__getslice__`; mutable sequences might define all three methods.
+
+
+.. method:: object.__getslice__(self, i, j)
+
+ .. deprecated:: 2.0
+ Support slice objects as parameters to the :meth:`__getitem__` method.
+
+ Called to implement evaluation of ``self[i:j]``. The returned object should be
+ of the same type as *self*. Note that missing *i* or *j* in the slice
+ expression are replaced by zero or ``sys.maxint``, respectively. If negative
+ indexes are used in the slice, the length of the sequence is added to that
+ index. If the instance does not implement the :meth:`__len__` method, an
+ :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this
+ way are not still negative. Indexes which are greater than the length of the
+ sequence are not modified. If no :meth:`__getslice__` is found, a slice object
+ is created instead, and passed to :meth:`__getitem__` instead.
+
+
+.. method:: object.__setslice__(self, i, j, sequence)
+
+ Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as
+ for :meth:`__getslice__`.
+
+ This method is deprecated. If no :meth:`__setslice__` is found, or for extended
+ slicing of the form ``self[i:j:k]``, a slice object is created, and passed to
+ :meth:`__setitem__`, instead of :meth:`__setslice__` being called.
+
+
+.. method:: object.__delslice__(self, i, j)
+
+ Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for
+ :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is
+ found, or for extended slicing of the form ``self[i:j:k]``, a slice object is
+ created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__`
+ being called.
+
+Notice that these methods are only invoked when a single slice with a single
+colon is used, and the slice method is available. For slice operations
+involving extended slice notation, or in absence of the slice methods,
+:meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a
+slice object as argument.
+
+The following example demonstrate how to make your program or module compatible
+with earlier versions of Python (assuming that methods :meth:`__getitem__`,
+:meth:`__setitem__` and :meth:`__delitem__` support slice objects as
+arguments)::
+
+ class MyClass:
+ ...
+ def __getitem__(self, index):
+ ...
+ def __setitem__(self, index, value):
+ ...
+ def __delitem__(self, index):
+ ...
+
+ if sys.version_info < (2, 0):
+ # They won't be defined if version is at least 2.0 final
+
+ def __getslice__(self, i, j):
+ return self[max(0, i):max(0, j):]
+ def __setslice__(self, i, j, seq):
+ self[max(0, i):max(0, j):] = seq
+ def __delslice__(self, i, j):
+ del self[max(0, i):max(0, j):]
+ ...
+
+Note the calls to :func:`max`; these are necessary because of the handling of
+negative indices before the :meth:`__\*slice__` methods are called. When
+negative indexes are used, the :meth:`__\*item__` methods receive them as
+provided, but the :meth:`__\*slice__` methods get a "cooked" form of the index
+values. For each negative index value, the length of the sequence is added to
+the index before calling the method (which may still result in a negative
+index); this is the customary handling of negative indexes by the built-in
+sequence types, and the :meth:`__\*item__` methods are expected to do this as
+well. However, since they should already be doing that, negative indexes cannot
+be passed in; they must be constrained to the bounds of the sequence before
+being passed to the :meth:`__\*item__` methods. Calling ``max(0, i)``
+conveniently returns the proper value.
+
+
+.. _numeric-types:
+
+Emulating numeric types
+-----------------------
+
+The following methods can be defined to emulate numeric objects. Methods
+corresponding to operations that are not supported by the particular kind of
+number implemented (e.g., bitwise operations for non-integral numbers) should be
+left undefined.
+
+
+.. method:: object.__add__(self, other)
+ object.__sub__(self, other)
+ object.__mul__(self, other)
+ object.__floordiv__(self, other)
+ object.__mod__(self, other)
+ object.__divmod__(self, other)
+ object.__pow__(self, other[, modulo])
+ object.__lshift__(self, other)
+ object.__rshift__(self, other)
+ object.__and__(self, other)
+ object.__xor__(self, other)
+ object.__or__(self, other)
+
+ .. index::
+ builtin: divmod
+ builtin: pow
+ builtin: pow
+
+ These methods are called to implement the binary arithmetic operations (``+``,
+ ``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
+ ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression
+ *x*``+``*y*, where *x* is an instance of a class that has an :meth:`__add__`
+ method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the
+ equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
+ related to :meth:`__truediv__` (described below). Note that :meth:`__pow__`
+ should be defined to accept an optional third argument if the ternary version of
+ the built-in :func:`pow` function is to be supported.
+
+ If one of those methods does not support the operation with the supplied
+ arguments, it should return ``NotImplemented``.
+
+
+.. method:: object.__div__(self, other)
+ object.__truediv__(self, other)
+
+ The division operator (``/``) is implemented by these methods. The
+ :meth:`__truediv__` method is used when ``__future__.division`` is in effect,
+ otherwise :meth:`__div__` is used. If only one of these two methods is defined,
+ the object will not support division in the alternate context; :exc:`TypeError`
+ will be raised instead.
+
+
+.. method:: object.__radd__(self, other)
+ object.__rsub__(self, other)
+ object.__rmul__(self, other)
+ object.__rdiv__(self, other)
+ object.__rtruediv__(self, other)
+ object.__rfloordiv__(self, other)
+ object.__rmod__(self, other)
+ object.__rdivmod__(self, other)
+ object.__rpow__(self, other)
+ object.__rlshift__(self, other)
+ object.__rrshift__(self, other)
+ object.__rand__(self, other)
+ object.__rxor__(self, other)
+ object.__ror__(self, other)
+
+ .. index::
+ builtin: divmod
+ builtin: pow
+
+ These methods are called to implement the binary arithmetic operations (``+``,
+ ``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``,
+ ``&``, ``^``, ``|``) with reflected (swapped) operands. These functions are
+ only called if the left operand does not support the corresponding operation and
+ the operands are of different types. [#]_ For instance, to evaluate the
+ expression *x*``-``*y*, where *y* is an instance of a class that has an
+ :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns
+ *NotImplemented*.
+
+ .. index:: builtin: pow
+
+ Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the
+ coercion rules would become too complicated).
+
+ .. note::
+
+ If the right operand's type is a subclass of the left operand's type and that
+ subclass provides the reflected method for the operation, this method will be
+ called before the left operand's non-reflected method. This behavior allows
+ subclasses to override their ancestors' operations.
+
+
+.. method:: object.__iadd__(self, other)
+ object.__isub__(self, other)
+ object.__imul__(self, other)
+ object.__idiv__(self, other)
+ object.__itruediv__(self, other)
+ object.__ifloordiv__(self, other)
+ object.__imod__(self, other)
+ object.__ipow__(self, other[, modulo])
+ object.__ilshift__(self, other)
+ object.__irshift__(self, other)
+ object.__iand__(self, other)
+ object.__ixor__(self, other)
+ object.__ior__(self, other)
+
+ These methods are called to implement the augmented arithmetic operations
+ (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
+ ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation
+ in-place (modifying *self*) and return the result (which could be, but does
+ not have to be, *self*). If a specific method is not defined, the augmented
+ operation falls back to the normal methods. For instance, to evaluate the
+ expression *x*``+=``*y*, where *x* is an instance of a class that has an
+ :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance
+ of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
+ and ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*.
+
+
+.. method:: object.__neg__(self)
+ object.__pos__(self)
+ object.__abs__(self)
+ object.__invert__(self)
+
+ .. index:: builtin: abs
+
+ Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
+ and ``~``).
+
+
+.. method:: object.__complex__(self)
+ object.__int__(self)
+ object.__long__(self)
+ object.__float__(self)
+
+ .. index::
+ builtin: complex
+ builtin: int
+ builtin: long
+ builtin: float
+
+ Called to implement the built-in functions :func:`complex`, :func:`int`,
+ :func:`long`, and :func:`float`. Should return a value of the appropriate type.
+
+
+.. method:: object.__index__(self)
+
+ Called to implement :func:`operator.index`. Also called whenever Python needs
+ an integer object (such as in slicing, or in the built-in :func:`bin`,
+ :func:`hex` and :func:`oct` functions). Must return an integer (int or long).
+
+ .. versionadded:: 2.5
+
+
+.. _context-managers:
+
+With Statement Context Managers
+-------------------------------
+
+.. versionadded:: 2.5
+
+A :dfn:`context manager` is an object that defines the runtime context to be
+established when executing a :keyword:`with` statement. The context manager
+handles the entry into, and the exit from, the desired runtime context for the
+execution of the block of code. Context managers are normally invoked using the
+:keyword:`with` statement (described in section :ref:`with`), but can also be
+used by directly invoking their methods.
+
+.. index::
+ statement: with
+ single: context manager
+
+Typical uses of context managers include saving and restoring various kinds of
+global state, locking and unlocking resources, closing opened files, etc.
+
+For more information on context managers, see :ref:`typecontextmanager`.
+
+
+.. method:: object.__enter__(self)
+
+ Enter the runtime context related to this object. The :keyword:`with` statement
+ will bind this method's return value to the target(s) specified in the
+ :keyword:`as` clause of the statement, if any.
+
+
+.. method:: object.__exit__(self, exc_type, exc_value, traceback)
+
+ Exit the runtime context related to this object. The parameters describe the
+ exception that caused the context to be exited. If the context was exited
+ without an exception, all three arguments will be :const:`None`.
+
+ If an exception is supplied, and the method wishes to suppress the exception
+ (i.e., prevent it from being propagated), it should return a true value.
+ Otherwise, the exception will be processed normally upon exit from this method.
+
+ Note that :meth:`__exit__` methods should not reraise the passed-in exception;
+ this is the caller's responsibility.
+
+
+.. seealso::
+
+ :pep:`0343` - The "with" statement
+ The specification, background, and examples for the Python :keyword:`with`
+ statement.
+
+.. rubric:: Footnotes
+
+.. [#] Since Python 2.2, a gradual merging of types and classes has been started that
+ makes this and a few other assertions made in this manual not 100% accurate and
+ complete: for example, it *is* now possible in some cases to change an object's
+ type, under certain controlled conditions. Until this manual undergoes
+ extensive revision, it must now be taken as authoritative only regarding
+ "classic classes", that are still the default, for compatibility purposes, in
+ Python 2.2 and 2.3. For more information, see
+ http://www.python.org/doc/newstyle.html.
+
+.. [#] This, and other statements, are only roughly true for instances of new-style
+ classes.
+
+.. [#] 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
+ reflected method is not called.
+
diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst
new file mode 100644
index 0000000..27802c8
--- /dev/null
+++ b/Doc/reference/executionmodel.rst
@@ -0,0 +1,232 @@
+
+.. _execmodel:
+
+***************
+Execution model
+***************
+
+.. index:: single: execution model
+
+
+.. _naming:
+
+Naming and binding
+==================
+
+.. index::
+ pair: code; block
+ single: namespace
+ single: scope
+
+.. index::
+ single: name
+ pair: binding; name
+
+:dfn:`Names` refer to objects. Names are introduced by name binding operations.
+Each occurrence of a name in the program text refers to the :dfn:`binding` of
+that name established in the innermost function block containing the use.
+
+.. index:: single: block
+
+A :dfn:`block` is a piece of Python program text that is executed as a unit.
+The following are blocks: a module, a function body, and a class definition.
+Each command typed interactively is a block. A script file (a file given as
+standard input to the interpreter or specified on the interpreter command line
+the first argument) is a code block. A script command (a command specified on
+the interpreter command line with the '**-c**' option) is a code block. The string
+argument passed to the built-in functions :func:`eval` and :func:`exec` is a
+code block. The expression read and evaluated by the built-in function
+:func:`input` is a code block.
+
+.. index:: pair: execution; frame
+
+A code block is executed in an :dfn:`execution frame`. A frame contains some
+administrative information (used for debugging) and determines where and how
+execution continues after the code block's execution has completed.
+
+.. index:: single: scope
+
+A :dfn:`scope` defines the visibility of a name within a block. If a local
+variable is defined in a block, its scope includes that block. If the
+definition occurs in a function block, the scope extends to any blocks contained
+within the defining one, unless a contained block introduces a different binding
+for the name. The scope of names defined in a class block is limited to the
+class block; it does not extend to the code blocks of methods.
+
+.. index:: single: environment
+
+When a name is used in a code block, it is resolved using the nearest enclosing
+scope. The set of all such scopes visible to a code block is called the block's
+:dfn:`environment`.
+
+.. index:: pair: free; variable
+
+If a name is bound in a block, it is a local variable of that block. If a name
+is bound at the module level, it is a global variable. (The variables of the
+module code block are local and global.) If a variable is used in a code block
+but not defined there, it is a :dfn:`free variable`.
+
+.. index::
+ single: NameError (built-in exception)
+ single: UnboundLocalError
+
+When a name is not found at all, a :exc:`NameError` exception is raised. If the
+name refers to a local variable that has not been bound, a
+:exc:`UnboundLocalError` exception is raised. :exc:`UnboundLocalError` is a
+subclass of :exc:`NameError`.
+
+.. index:: statement: from
+
+The following constructs bind names: formal parameters to functions,
+:keyword:`import` statements, class and function definitions (these bind the
+class or function name in the defining block), and targets that are identifiers
+if occurring in an assignment, :keyword:`for` loop header, or in the second
+position of an :keyword:`except` clause header. The :keyword:`import` statement
+of the form "``from ...import *``" binds all names defined in the imported
+module, except those beginning with an underscore. This form may only be used
+at the module level.
+
+A target occurring in a :keyword:`del` statement is also considered bound for
+this purpose (though the actual semantics are to unbind the name). It is
+illegal to unbind a name that is referenced by an enclosing scope; the compiler
+will report a :exc:`SyntaxError`.
+
+Each assignment or import statement occurs within a block defined by a class or
+function definition or at the module level (the top-level code block).
+
+If a name binding operation occurs anywhere within a code block, all uses of the
+name within the block are treated as references to the current block. This can
+lead to errors when a name is used within a block before it is bound. This rule
+is subtle. Python lacks declarations and allows name binding operations to
+occur anywhere within a code block. The local variables of a code block can be
+determined by scanning the entire text of the block for name binding operations.
+
+If the global statement occurs within a block, all uses of the name specified in
+the statement refer to the binding of that name in the top-level namespace.
+Names are resolved in the top-level namespace by searching the global namespace,
+i.e. the namespace of the module containing the code block, and the builtin
+namespace, the namespace of the module :mod:`__builtin__`. The global namespace
+is searched first. If the name is not found there, the builtin namespace is
+searched. The global statement must precede all uses of the name.
+
+.. index:: pair: restricted; execution
+
+The built-in namespace associated with the execution of a code block is actually
+found by looking up the name ``__builtins__`` in its global namespace; this
+should be a dictionary or a module (in the latter case the module's dictionary
+is used). By default, when in the :mod:`__main__` module, ``__builtins__`` is
+the built-in module :mod:`__builtin__` (note: no 's'); when in any other module,
+``__builtins__`` is an alias for the dictionary of the :mod:`__builtin__` module
+itself. ``__builtins__`` can be set to a user-created dictionary to create a
+weak form of restricted execution.
+
+.. note::
+
+ Users should not touch ``__builtins__``; it is strictly an implementation
+ detail. Users wanting to override values in the built-in namespace should
+ :keyword:`import` the :mod:`__builtin__` (no 's') module and modify its
+ attributes appropriately.
+
+.. index:: module: __main__
+
+The namespace for a module is automatically created the first time a module is
+imported. The main module for a script is always called :mod:`__main__`.
+
+The global statement has the same scope as a name binding operation in the same
+block. If the nearest enclosing scope for a free variable contains a global
+statement, the free variable is treated as a global.
+
+A class definition is an executable statement that may use and define names.
+These references follow the normal rules for name resolution. The namespace of
+the class definition becomes the attribute dictionary of the class. Names
+defined at the class scope are not visible in methods.
+
+
+.. _dynamic-features:
+
+Interaction with dynamic features
+---------------------------------
+
+There are several cases where Python statements are illegal when used in
+conjunction with nested scopes that contain free variables.
+
+If a variable is referenced in an enclosing scope, it is illegal to delete the
+name. An error will be reported at compile time.
+
+If the wild card form of import --- ``import *`` --- is used in a function and
+the function contains or is a nested block with free variables, the compiler
+will raise a :exc:`SyntaxError`.
+
+The :func:`eval` and :func:`exec` functions do
+not have access to the full environment for resolving names. Names may be
+resolved in the local and global namespaces of the caller. Free variables are
+not resolved in the nearest enclosing namespace, but in the global namespace.
+[#]_ The :func:`exec` and :func:`eval` functions have optional
+arguments to override the global and local namespace. If only one namespace is
+specified, it is used for both.
+
+
+.. _exceptions:
+
+Exceptions
+==========
+
+.. index:: single: exception
+
+.. index::
+ single: raise an exception
+ single: handle an exception
+ single: exception handler
+ single: errors
+ single: error handling
+
+Exceptions are a means of breaking out of the normal flow of control of a code
+block in order to handle errors or other exceptional conditions. An exception
+is *raised* at the point where the error is detected; it may be *handled* by the
+surrounding code block or by any code block that directly or indirectly invoked
+the code block where the error occurred.
+
+The Python interpreter raises an exception when it detects a run-time error
+(such as division by zero). A Python program can also explicitly raise an
+exception with the :keyword:`raise` statement. Exception handlers are specified
+with the :keyword:`try` ... :keyword:`except` statement. The :keyword:`try` ...
+:keyword:`finally` statement specifies cleanup code which does not handle the
+exception, but is executed whether an exception occurred or not in the preceding
+code.
+
+.. index:: single: termination model
+
+Python uses the "termination" model of error handling: an exception handler can
+find out what happened and continue execution at an outer level, but it cannot
+repair the cause of the error and retry the failing operation (except by
+re-entering the offending piece of code from the top).
+
+.. index:: single: SystemExit (built-in exception)
+
+When an exception is not handled at all, the interpreter terminates execution of
+the program, or returns to its interactive main loop. In either case, it prints
+a stack backtrace, except when the exception is :exc:`SystemExit`.
+
+Exceptions are identified by class instances. The :keyword:`except` clause is
+selected depending on the class of the instance: it must reference the class of
+the instance or a base class thereof. The instance can be received by the
+handler and can carry additional information about the exceptional condition.
+
+Exceptions can also be identified by strings, in which case the
+:keyword:`except` clause is selected by object identity. An arbitrary value can
+be raised along with the identifying string which can be passed to the handler.
+
+.. warning::
+
+ Messages to exceptions are not part of the Python API. Their contents may
+ change from one version of Python to the next without warning and should not be
+ relied on by code which will run under multiple versions of the interpreter.
+
+See also the description of the :keyword:`try` statement in section :ref:`try`
+and :keyword:`raise` statement in section :ref:`raise`.
+
+.. rubric:: Footnotes
+
+.. [#] This limitation occurs because the code that is executed by these operations is
+ not available at the time the module is compiled.
+
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
new file mode 100644
index 0000000..28c1406
--- /dev/null
+++ b/Doc/reference/expressions.rst
@@ -0,0 +1,1283 @@
+
+.. _expressions:
+
+***********
+Expressions
+***********
+
+.. index:: single: expression
+
+This chapter explains the meaning of the elements of expressions in Python.
+
+.. index:: single: BNF
+
+**Syntax Notes:** In this and the following chapters, extended BNF notation will
+be used to describe syntax, not lexical analysis. When (one alternative of) a
+syntax rule has the form
+
+.. productionlist:: *
+ name: `othername`
+
+.. index:: single: syntax
+
+and no semantics are given, the semantics of this form of ``name`` are the same
+as for ``othername``.
+
+
+.. _conversions:
+
+Arithmetic conversions
+======================
+
+.. index:: pair: arithmetic; conversion
+
+.. XXX no coercion rules are documented anymore
+
+When a description of an arithmetic operator below uses the phrase "the numeric
+arguments are converted to a common type," the arguments are coerced using the
+coercion rules. If both arguments are standard
+numeric types, the following coercions are applied:
+
+* If either argument is a complex number, the other is converted to complex;
+
+* otherwise, if either argument is a floating point number, the other is
+ converted to floating point;
+
+* otherwise, if either argument is a long integer, the other is converted to
+ long integer;
+
+* otherwise, both must be plain integers and no conversion is necessary.
+
+Some additional rules apply for certain operators (e.g., a string left argument
+to the '%' operator). Extensions can define their own coercions.
+
+
+.. _atoms:
+
+Atoms
+=====
+
+.. index:: single: atom
+
+Atoms are the most basic elements of expressions. The simplest atoms are
+identifiers or literals. Forms enclosed in reverse quotes or in parentheses,
+brackets or braces are also categorized syntactically as atoms. The syntax for
+atoms is:
+
+.. productionlist::
+ atom: `identifier` | `literal` | `enclosure`
+ enclosure: `parenth_form` | `list_display`
+ : | `generator_expression` | `dict_display`
+ : | `string_conversion` | `yield_atom`
+
+
+.. _atom-identifiers:
+
+Identifiers (Names)
+-------------------
+
+.. index::
+ single: name
+ single: identifier
+
+An identifier occurring as an atom is a name. See section :ref:`identifiers`
+for lexical definition and section :ref:`naming` for documentation of naming and
+binding.
+
+.. index:: exception: NameError
+
+When the name is bound to an object, evaluation of the atom yields that object.
+When a name is not bound, an attempt to evaluate it raises a :exc:`NameError`
+exception.
+
+.. index::
+ pair: name; mangling
+ pair: private; names
+
+**Private name mangling:** When an identifier that textually occurs in a class
+definition begins with two or more underscore characters and does not end in two
+or more underscores, it is considered a :dfn:`private name` of that class.
+Private names are transformed to a longer form before code is generated for
+them. The transformation inserts the class name in front of the name, with
+leading underscores removed, and a single underscore inserted in front of the
+class name. For example, the identifier ``__spam`` occurring in a class named
+``Ham`` will be transformed to ``_Ham__spam``. This transformation is
+independent of the syntactical context in which the identifier is used. If the
+transformed name is extremely long (longer than 255 characters), implementation
+defined truncation may happen. If the class name consists only of underscores,
+no transformation is done.
+
+.. %
+.. %
+
+
+.. _atom-literals:
+
+Literals
+--------
+
+.. index:: single: literal
+
+Python supports string literals and various numeric literals:
+
+.. productionlist::
+ literal: `stringliteral` | `integer` | `longinteger`
+ : | `floatnumber` | `imagnumber`
+
+Evaluation of a literal yields an object of the given type (string, integer,
+long integer, floating point number, complex number) with the given value. The
+value may be approximated in the case of floating point and imaginary (complex)
+literals. See section :ref:`literals` for details.
+
+.. index::
+ triple: immutable; data; type
+ pair: immutable; object
+
+All literals correspond to immutable data types, and hence the object's identity
+is less important than its value. Multiple evaluations of literals with the
+same value (either the same occurrence in the program text or a different
+occurrence) may obtain the same object or a different object with the same
+value.
+
+
+.. _parenthesized:
+
+Parenthesized forms
+-------------------
+
+.. index:: single: parenthesized form
+
+A parenthesized form is an optional expression list enclosed in parentheses:
+
+.. productionlist::
+ parenth_form: "(" [`expression_list`] ")"
+
+A parenthesized expression list yields whatever that expression list yields: if
+the list contains at least one comma, it yields a tuple; otherwise, it yields
+the single expression that makes up the expression list.
+
+.. index:: pair: empty; tuple
+
+An empty pair of parentheses yields an empty tuple object. Since tuples are
+immutable, the rules for literals apply (i.e., two occurrences of the empty
+tuple may or may not yield the same object).
+
+.. index::
+ single: comma
+ pair: tuple; display
+
+Note that tuples are not formed by the parentheses, but rather by use of the
+comma operator. The exception is the empty tuple, for which parentheses *are*
+required --- allowing unparenthesized "nothing" in expressions would cause
+ambiguities and allow common typos to pass uncaught.
+
+
+.. _lists:
+
+List displays
+-------------
+
+.. index::
+ pair: list; display
+ pair: list; comprehensions
+
+A list display is a possibly empty series of expressions enclosed in square
+brackets:
+
+.. productionlist::
+ list_display: "[" [`expression_list` | `list_comprehension`] "]"
+ list_comprehension: `expression` `list_for`
+ list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`]
+ old_expression_list: `old_expression` [("," `old_expression`)+ [","]]
+ list_iter: `list_for` | `list_if`
+ list_if: "if" `old_expression` [`list_iter`]
+
+.. index::
+ pair: list; comprehensions
+ object: list
+ pair: empty; list
+
+A list display yields a new list object. Its contents are specified by
+providing either a list of expressions or a list comprehension. When a
+comma-separated list of expressions is supplied, its elements are evaluated from
+left to right and placed into the list object in that order. When a list
+comprehension is supplied, it consists of a single expression followed by at
+least one :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if`
+clauses. In this case, the elements of the new list are those that would be
+produced by considering each of the :keyword:`for` or :keyword:`if` clauses a
+block, nesting from left to right, and evaluating the expression to produce a
+list element each time the innermost block is reached [#]_.
+
+
+.. _genexpr:
+
+Generator expressions
+---------------------
+
+.. index:: pair: generator; expression
+
+A generator expression is a compact generator notation in parentheses:
+
+.. productionlist::
+ generator_expression: "(" `expression` `genexpr_for` ")"
+ genexpr_for: "for" `target_list` "in" `or_test` [`genexpr_iter`]
+ genexpr_iter: `genexpr_for` | `genexpr_if`
+ genexpr_if: "if" `old_expression` [`genexpr_iter`]
+
+.. index:: object: generator
+
+A generator expression yields a new generator object. It consists of a single
+expression followed by at least one :keyword:`for` clause and zero or more
+:keyword:`for` or :keyword:`if` clauses. The iterating values of the new
+generator are those that would be produced by considering each of the
+:keyword:`for` or :keyword:`if` clauses a block, nesting from left to right, and
+evaluating the expression to yield a value that is reached the innermost block
+for each iteration.
+
+Variables used in the generator expression are evaluated lazily when the
+:meth:`__next__` method is called for generator object (in the same fashion as
+normal generators). However, the leftmost :keyword:`for` clause is immediately
+evaluated so that error produced by it can be seen before any other possible
+error in the code that handles the generator expression. Subsequent
+:keyword:`for` clauses cannot be evaluated immediately since they may depend on
+the previous :keyword:`for` loop. For example: ``(x*y for x in range(10) for y
+in bar(x))``.
+
+The parentheses can be omitted on calls with only one argument. See section
+:ref:`calls` for the detail.
+
+
+.. _dict:
+
+Dictionary displays
+-------------------
+
+.. index:: pair: dictionary; display
+
+.. index::
+ single: key
+ single: datum
+ single: key/datum pair
+
+A dictionary display is a possibly empty series of key/datum pairs enclosed in
+curly braces:
+
+.. productionlist::
+ dict_display: "{" [`key_datum_list`] "}"
+ key_datum_list: `key_datum` ("," `key_datum`)* [","]
+ key_datum: `expression` ":" `expression`
+
+.. index:: object: dictionary
+
+A dictionary display yields a new dictionary object.
+
+The key/datum pairs are evaluated from left to right to define the entries of
+the dictionary: each key object is used as a key into the dictionary to store
+the corresponding datum.
+
+.. index:: pair: immutable; object
+
+Restrictions on the types of the key values are listed earlier in section
+:ref:`types`. (To summarize, the key type should be hashable, which excludes
+all mutable objects.) Clashes between duplicate keys are not detected; the last
+datum (textually rightmost in the display) stored for a given key value
+prevails.
+
+
+.. _yieldexpr:
+
+Yield expressions
+-----------------
+
+.. index::
+ keyword: yield
+ pair: yield; expression
+ pair: generator; function
+
+.. productionlist::
+ yield_atom: "(" `yield_expression` ")"
+ yield_expression: "yield" [`expression_list`]
+
+.. versionadded:: 2.5
+
+The :keyword:`yield` expression is only used when defining a generator function,
+and can only be used in the body of a function definition. Using a
+:keyword:`yield` expression in a function definition is sufficient to cause that
+definition to create a generator function instead of a normal function.
+
+When a generator function is called, it returns an iterator known as a
+generator. That generator then controls the execution of a generator function.
+The execution starts when one of the generator's methods is called. At that
+time, the execution proceeds to the first :keyword:`yield` expression, where it
+is suspended again, returning the value of :token:`expression_list` to
+generator's caller. By suspended we mean that all local state is retained,
+including the current bindings of local variables, the instruction pointer, and
+the internal evaluation stack. When the execution is resumed by calling one of
+the generator's methods, the function can proceed exactly as if the
+:keyword:`yield` expression was just another external call. The value of the
+:keyword:`yield` expression after resuming depends on the method which resumed
+the execution.
+
+.. index:: single: coroutine
+
+All of this makes generator functions quite similar to coroutines; they yield
+multiple times, they have more than one entry point and their execution can be
+suspended. The only difference is that a generator function cannot control
+where should the execution continue after it yields; the control is always
+transfered to the generator's caller.
+
+.. index:: object: generator
+
+The following generator's methods can be used to control the execution of a
+generator function:
+
+.. index:: exception: StopIteration
+
+
+.. method:: generator.next()
+
+ Starts the execution of a generator function or resumes it at the last executed
+ :keyword:`yield` expression. When a generator function is resumed with a
+ :meth:`next` method, the current :keyword:`yield` expression always evaluates to
+ :const:`None`. The execution then continues to the next :keyword:`yield`
+ expression, where the generator is suspended again, and the value of the
+ :token:`expression_list` is returned to :meth:`next`'s caller. If the generator
+ exits without yielding another value, a :exc:`StopIteration` exception is
+ raised.
+
+
+.. method:: generator.send(value)
+
+ Resumes the execution and "sends" a value into the generator function. The
+ ``value`` argument becomes the result of the current :keyword:`yield`
+ expression. The :meth:`send` method returns the next value yielded by the
+ generator, or raises :exc:`StopIteration` if the generator exits without
+ yielding another value. When :meth:`send` is called to start the generator, it
+ must be called with :const:`None` as the argument, because there is no
+ :keyword:`yield` expression that could receieve the value.
+
+
+.. method:: generator.throw(type[, value[, traceback]])
+
+ Raises an exception of type ``type`` at the point where generator was paused,
+ and returns the next value yielded by the generator function. If the generator
+ exits without yielding another value, a :exc:`StopIteration` exception is
+ raised. If the generator function does not catch the passed-in exception, or
+ raises a different exception, then that exception propagates to the caller.
+
+.. index:: exception: GeneratorExit
+
+
+.. method:: generator.close()
+
+ Raises a :exc:`GeneratorExit` at the point where the generator function was
+ paused. If the generator function then raises :exc:`StopIteration` (by exiting
+ normally, or due to already being closed) or :exc:`GeneratorExit` (by not
+ catching the exception), close returns to its caller. If the generator yields a
+ value, a :exc:`RuntimeError` is raised. If the generator raises any other
+ exception, it is propagated to the caller. :meth:`close` does nothing if the
+ generator has already exited due to an exception or normal exit.
+
+Here is a simple example that demonstrates the behavior of generators and
+generator functions::
+
+ >>> def echo(value=None):
+ ... print "Execution starts when 'next()' is called for the first time."
+ ... try:
+ ... while True:
+ ... try:
+ ... value = (yield value)
+ ... except GeneratorExit:
+ ... # never catch GeneratorExit
+ ... raise
+ ... except Exception, e:
+ ... value = e
+ ... finally:
+ ... print "Don't forget to clean up when 'close()' is called."
+ ...
+ >>> generator = echo(1)
+ >>> print generator.next()
+ Execution starts when 'next()' is called for the first time.
+ 1
+ >>> print generator.next()
+ None
+ >>> print generator.send(2)
+ 2
+ >>> generator.throw(TypeError, "spam")
+ TypeError('spam',)
+ >>> generator.close()
+ Don't forget to clean up when 'close()' is called.
+
+
+.. seealso::
+
+ :pep:`0342` - Coroutines via Enhanced Generators
+ The proposal to enhance the API and syntax of generators, making them usable as
+ simple coroutines.
+
+
+.. _primaries:
+
+Primaries
+=========
+
+.. index:: single: primary
+
+Primaries represent the most tightly bound operations of the language. Their
+syntax is:
+
+.. productionlist::
+ primary: `atom` | `attributeref` | `subscription` | `slicing` | `call`
+
+
+.. _attribute-references:
+
+Attribute references
+--------------------
+
+.. index:: pair: attribute; reference
+
+An attribute reference is a primary followed by a period and a name:
+
+.. productionlist::
+ attributeref: `primary` "." `identifier`
+
+.. index::
+ exception: AttributeError
+ object: module
+ object: list
+
+The primary must evaluate to an object of a type that supports attribute
+references, e.g., a module, list, or an instance. This object is then asked to
+produce the attribute whose name is the identifier. If this attribute is not
+available, the exception :exc:`AttributeError` is raised. Otherwise, the type
+and value of the object produced is determined by the object. Multiple
+evaluations of the same attribute reference may yield different objects.
+
+
+.. _subscriptions:
+
+Subscriptions
+-------------
+
+.. index:: single: subscription
+
+.. index::
+ object: sequence
+ object: mapping
+ object: string
+ object: tuple
+ object: list
+ object: dictionary
+ pair: sequence; item
+
+A subscription selects an item of a sequence (string, tuple or list) or mapping
+(dictionary) object:
+
+.. productionlist::
+ subscription: `primary` "[" `expression_list` "]"
+
+The primary must evaluate to an object of a sequence or mapping type.
+
+If the primary is a mapping, the expression list must evaluate to an object
+whose value is one of the keys of the mapping, and the subscription selects the
+value in the mapping that corresponds to that key. (The expression list is a
+tuple except if it has exactly one item.)
+
+If the primary is a sequence, the expression (list) must evaluate to a plain
+integer. If this value is negative, the length of the sequence is added to it
+(so that, e.g., ``x[-1]`` selects the last item of ``x``.) The resulting value
+must be a nonnegative integer less than the number of items in the sequence, and
+the subscription selects the item whose index is that value (counting from
+zero).
+
+.. index::
+ single: character
+ pair: string; item
+
+A string's items are characters. A character is not a separate data type but a
+string of exactly one character.
+
+
+.. _slicings:
+
+Slicings
+--------
+
+.. index::
+ single: slicing
+ single: slice
+
+.. index::
+ object: sequence
+ object: string
+ object: tuple
+ object: list
+
+A slicing selects a range of items in a sequence object (e.g., a string, tuple
+or list). Slicings may be used as expressions or as targets in assignment or
+:keyword:`del` statements. The syntax for a slicing:
+
+.. productionlist::
+ slicing: `simple_slicing` | `extended_slicing`
+ simple_slicing: `primary` "[" `short_slice` "]"
+ extended_slicing: `primary` "[" `slice_list` "]"
+ slice_list: `slice_item` ("," `slice_item`)* [","]
+ slice_item: `expression` | `proper_slice` | `ellipsis`
+ proper_slice: `short_slice` | `long_slice`
+ short_slice: [`lower_bound`] ":" [`upper_bound`]
+ long_slice: `short_slice` ":" [`stride`]
+ lower_bound: `expression`
+ upper_bound: `expression`
+ stride: `expression`
+ ellipsis: "..."
+
+.. index:: pair: extended; slicing
+
+There is ambiguity in the formal syntax here: anything that looks like an
+expression list also looks like a slice list, so any subscription can be
+interpreted as a slicing. Rather than further complicating the syntax, this is
+disambiguated by defining that in this case the interpretation as a subscription
+takes priority over the interpretation as a slicing (this is the case if the
+slice list contains no proper slice nor ellipses). Similarly, when the slice
+list has exactly one short slice and no trailing comma, the interpretation as a
+simple slicing takes priority over that as an extended slicing.
+
+The semantics for a simple slicing are as follows. The primary must evaluate to
+a sequence object. The lower and upper bound expressions, if present, must
+evaluate to plain integers; defaults are zero and the ``sys.maxint``,
+respectively. If either bound is negative, the sequence's length is added to
+it. The slicing now selects all items with index *k* such that ``i <= k < j``
+where *i* and *j* are the specified lower and upper bounds. This may be an
+empty sequence. It is not an error if *i* or *j* lie outside the range of valid
+indexes (such items don't exist so they aren't selected).
+
+.. index::
+ single: start (slice object attribute)
+ single: stop (slice object attribute)
+ single: step (slice object attribute)
+
+The semantics for an extended slicing are as follows. The primary must evaluate
+to a mapping object, and it is indexed with a key that is constructed from the
+slice list, as follows. If the slice list contains at least one comma, the key
+is a tuple containing the conversion of the slice items; otherwise, the
+conversion of the lone slice item is the key. The conversion of a slice item
+that is an expression is that expression. The conversion of a proper slice is a
+slice object (see section :ref:`types`) whose :attr:`start`, :attr:`stop` and
+:attr:`step` attributes are the values of the expressions given as lower bound,
+upper bound and stride, respectively, substituting ``None`` for missing
+expressions.
+
+
+.. _calls:
+
+Calls
+-----
+
+.. index:: single: call
+
+.. index:: object: callable
+
+A call calls a callable object (e.g., a function) with a possibly empty series
+of arguments:
+
+.. productionlist::
+ call: `primary` "(" [`argument_list` [","]
+ : | `expression` `genexpr_for`] ")"
+ argument_list: `positional_arguments` ["," `keyword_arguments`]
+ : ["," "*" `expression`]
+ : ["," "**" `expression`]
+ : | `keyword_arguments` ["," "*" `expression`]
+ : ["," "**" `expression`]
+ : | "*" `expression` ["," "**" `expression`]
+ : | "**" `expression`
+ positional_arguments: `expression` ("," `expression`)*
+ keyword_arguments: `keyword_item` ("," `keyword_item`)*
+ keyword_item: `identifier` "=" `expression`
+
+A trailing comma may be present after the positional and keyword arguments but
+does not affect the semantics.
+
+The primary must evaluate to a callable object (user-defined functions, built-in
+functions, methods of built-in objects, class objects, methods of class
+instances, and certain class instances themselves are callable; extensions may
+define additional callable object types). All argument expressions are
+evaluated before the call is attempted. Please refer to section :ref:`function`
+for the syntax of formal parameter lists.
+
+If keyword arguments are present, they are first converted to positional
+arguments, as follows. First, a list of unfilled slots is created for the
+formal parameters. If there are N positional arguments, they are placed in the
+first N slots. Next, for each keyword argument, the identifier is used to
+determine the corresponding slot (if the identifier is the same as the first
+formal parameter name, the first slot is used, and so on). If the slot is
+already filled, a :exc:`TypeError` exception is raised. Otherwise, the value of
+the argument is placed in the slot, filling it (even if the expression is
+``None``, it fills the slot). When all arguments have been processed, the slots
+that are still unfilled are filled with the corresponding default value from the
+function definition. (Default values are calculated, once, when the function is
+defined; thus, a mutable object such as a list or dictionary used as default
+value will be shared by all calls that don't specify an argument value for the
+corresponding slot; this should usually be avoided.) If there are any unfilled
+slots for which no default value is specified, a :exc:`TypeError` exception is
+raised. Otherwise, the list of filled slots is used as the argument list for
+the call.
+
+If there are more positional arguments than there are formal parameter slots, a
+:exc:`TypeError` exception is raised, unless a formal parameter using the syntax
+``*identifier`` is present; in this case, that formal parameter receives a tuple
+containing the excess positional arguments (or an empty tuple if there were no
+excess positional arguments).
+
+If any keyword argument does not correspond to a formal parameter name, a
+:exc:`TypeError` exception is raised, unless a formal parameter using the syntax
+``**identifier`` is present; in this case, that formal parameter receives a
+dictionary containing the excess keyword arguments (using the keywords as keys
+and the argument values as corresponding values), or a (new) empty dictionary if
+there were no excess keyword arguments.
+
+If the syntax ``*expression`` appears in the function call, ``expression`` must
+evaluate to a sequence. Elements from this sequence are treated as if they were
+additional positional arguments; if there are postional arguments *x1*,...,*xN*
+, and ``expression`` evaluates to a sequence *y1*,...,*yM*, this is equivalent
+to a call with M+N positional arguments *x1*,...,*xN*,*y1*,...,*yM*.
+
+A consequence of this is that although the ``*expression`` syntax appears
+*after* any keyword arguments, it is processed *before* the keyword arguments
+(and the ``**expression`` argument, if any -- see below). So::
+
+ >>> def f(a, b):
+ ... print a, b
+ ...
+ >>> f(b=1, *(2,))
+ 2 1
+ >>> f(a=1, *(2,))
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ TypeError: f() got multiple values for keyword argument 'a'
+ >>> f(1, *(2,))
+ 1 2
+
+It is unusual for both keyword arguments and the ``*expression`` syntax to be
+used in the same call, so in practice this confusion does not arise.
+
+If the syntax ``**expression`` appears in the function call, ``expression`` must
+evaluate to a mapping, the contents of which are treated as additional keyword
+arguments. In the case of a keyword appearing in both ``expression`` and as an
+explicit keyword argument, a :exc:`TypeError` exception is raised.
+
+Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be
+used as positional argument slots or as keyword argument names.
+
+A call always returns some value, possibly ``None``, unless it raises an
+exception. How this value is computed depends on the type of the callable
+object.
+
+If it is---
+
+a user-defined function:
+ .. index::
+ pair: function; call
+ triple: user-defined; function; call
+ object: user-defined function
+ object: function
+
+ The code block for the function is executed, passing it the argument list. The
+ first thing the code block will do is bind the formal parameters to the
+ arguments; this is described in section :ref:`function`. When the code block
+ executes a :keyword:`return` statement, this specifies the return value of the
+ function call.
+
+a built-in function or method:
+ .. index::
+ pair: function; call
+ pair: built-in function; call
+ pair: method; call
+ pair: built-in method; call
+ object: built-in method
+ object: built-in function
+ object: method
+ object: function
+
+ The result is up to the interpreter; see :ref:`built-in-funcs` for the
+ descriptions of built-in functions and methods.
+
+a class object:
+ .. index::
+ object: class
+ pair: class object; call
+
+ A new instance of that class is returned.
+
+a class instance method:
+ .. index::
+ object: class instance
+ object: instance
+ pair: class instance; call
+
+ The corresponding user-defined function is called, with an argument list that is
+ one longer than the argument list of the call: the instance becomes the first
+ argument.
+
+a class instance:
+ .. index::
+ pair: instance; call
+ single: __call__() (object method)
+
+ The class must define a :meth:`__call__` method; the effect is then the same as
+ if that method was called.
+
+
+.. _power:
+
+The power operator
+==================
+
+The power operator binds more tightly than unary operators on its left; it binds
+less tightly than unary operators on its right. The syntax is:
+
+.. productionlist::
+ power: `primary` ["**" `u_expr`]
+
+Thus, in an unparenthesized sequence of power and unary operators, the operators
+are evaluated from right to left (this does not constrain the evaluation order
+for the operands).
+
+The power operator has the same semantics as the built-in :func:`pow` function,
+when called with two arguments: it yields its left argument raised to the power
+of its right argument. The numeric arguments are first converted to a common
+type. The result type is that of the arguments after coercion.
+
+With mixed operand types, the coercion rules for binary arithmetic operators
+apply. For int and long int operands, the result has the same type as the
+operands (after coercion) unless the second argument is negative; in that case,
+all arguments are converted to float and a float result is delivered. For
+example, ``10**2`` returns ``100``, but ``10**-2`` returns ``0.01``. (This last
+feature was added in Python 2.2. In Python 2.1 and before, if both arguments
+were of integer types and the second argument was negative, an exception was
+raised).
+
+Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`.
+Raising a negative number to a fractional power results in a :exc:`ValueError`.
+
+
+.. _unary:
+
+Unary arithmetic operations
+===========================
+
+.. index::
+ triple: unary; arithmetic; operation
+ triple: unary; bit-wise; operation
+
+All unary arithmetic (and bit-wise) operations have the same priority:
+
+.. productionlist::
+ u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr`
+
+.. index::
+ single: negation
+ single: minus
+
+The unary ``-`` (minus) operator yields the negation of its numeric argument.
+
+.. index:: single: plus
+
+The unary ``+`` (plus) operator yields its numeric argument unchanged.
+
+.. index:: single: inversion
+
+The unary ``~`` (invert) operator yields the bit-wise inversion of its plain or
+long integer argument. The bit-wise inversion of ``x`` is defined as
+``-(x+1)``. It only applies to integral numbers.
+
+.. index:: exception: TypeError
+
+In all three cases, if the argument does not have the proper type, a
+:exc:`TypeError` exception is raised.
+
+
+.. _binary:
+
+Binary arithmetic operations
+============================
+
+.. index:: triple: binary; arithmetic; operation
+
+The binary arithmetic operations have the conventional priority levels. Note
+that some of these operations also apply to certain non-numeric types. Apart
+from the power operator, there are only two levels, one for multiplicative
+operators and one for additive operators:
+
+.. productionlist::
+ m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr`
+ : | `m_expr` "%" `u_expr`
+ a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr`
+
+.. index:: single: multiplication
+
+The ``*`` (multiplication) operator yields the product of its arguments. The
+arguments must either both be numbers, or one argument must be an integer (plain
+or long) and the other must be a sequence. In the former case, the numbers are
+converted to a common type and then multiplied together. In the latter case,
+sequence repetition is performed; a negative repetition factor yields an empty
+sequence.
+
+.. index::
+ exception: ZeroDivisionError
+ single: division
+
+The ``/`` (division) and ``//`` (floor division) operators yield the quotient of
+their arguments. The numeric arguments are first converted to a common type.
+Plain or long integer division yields an integer of the same type; the result is
+that of mathematical division with the 'floor' function applied to the result.
+Division by zero raises the :exc:`ZeroDivisionError` exception.
+
+.. index:: single: modulo
+
+The ``%`` (modulo) operator yields the remainder from the division of the first
+argument by the second. The numeric arguments are first converted to a common
+type. A zero right argument raises the :exc:`ZeroDivisionError` exception. The
+arguments may be floating point numbers, e.g., ``3.14%0.7`` equals ``0.34``
+(since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a
+result with the same sign as its second operand (or zero); the absolute value of
+the result is strictly smaller than the absolute value of the second operand
+[#]_.
+
+The integer division and modulo operators are connected by the following
+identity: ``x == (x/y)*y + (x%y)``. Integer division and modulo are also
+connected with the built-in function :func:`divmod`: ``divmod(x, y) == (x/y,
+x%y)``. These identities don't hold for floating point numbers; there similar
+identities hold approximately where ``x/y`` is replaced by ``floor(x/y)`` or
+``floor(x/y) - 1`` [#]_.
+
+In addition to performing the modulo operation on numbers, the ``%`` operator is
+also overloaded by string and unicode objects to perform string formatting (also
+known as interpolation). The syntax for string formatting is described in the
+Python Library Reference, section :ref:`string-formatting`.
+
+The floor division operator, the modulo operator, and the :func:`divmod`
+function are not defined for complex numbers. Instead, convert to a
+floating point number using the :func:`abs` function if appropriate.
+
+.. index:: single: addition
+
+The ``+`` (addition) operator yields the sum of its arguments. The arguments
+must either both be numbers or both sequences of the same type. In the former
+case, the numbers are converted to a common type and then added together. In
+the latter case, the sequences are concatenated.
+
+.. index:: single: subtraction
+
+The ``-`` (subtraction) operator yields the difference of its arguments. The
+numeric arguments are first converted to a common type.
+
+
+.. _shifting:
+
+Shifting operations
+===================
+
+.. index:: pair: shifting; operation
+
+The shifting operations have lower priority than the arithmetic operations:
+
+.. productionlist::
+ shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr`
+
+These operators accept plain or long integers as arguments. The arguments are
+converted to a common type. They shift the first argument to the left or right
+by the number of bits given by the second argument.
+
+.. index:: exception: ValueError
+
+A right shift by *n* bits is defined as division by ``pow(2,n)``. A left shift
+by *n* bits is defined as multiplication with ``pow(2,n)``; for plain integers
+there is no overflow check so in that case the operation drops bits and flips
+the sign if the result is not less than ``pow(2,31)`` in absolute value.
+Negative shift counts raise a :exc:`ValueError` exception.
+
+
+.. _bitwise:
+
+Binary bit-wise operations
+==========================
+
+.. index:: triple: binary; bit-wise; operation
+
+Each of the three bitwise operations has a different priority level:
+
+.. productionlist::
+ and_expr: `shift_expr` | `and_expr` "&" `shift_expr`
+ xor_expr: `and_expr` | `xor_expr` "^" `and_expr`
+ or_expr: `xor_expr` | `or_expr` "|" `xor_expr`
+
+.. index:: pair: bit-wise; and
+
+The ``&`` operator yields the bitwise AND of its arguments, which must be plain
+or long integers. The arguments are converted to a common type.
+
+.. index::
+ pair: bit-wise; xor
+ pair: exclusive; or
+
+The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which
+must be plain or long integers. The arguments are converted to a common type.
+
+.. index::
+ pair: bit-wise; or
+ pair: inclusive; or
+
+The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which
+must be plain or long integers. The arguments are converted to a common type.
+
+
+.. _comparisons:
+
+Comparisons
+===========
+
+.. index:: single: comparison
+
+.. index:: pair: C; language
+
+Unlike C, all comparison operations in Python have the same priority, which is
+lower than that of any arithmetic, shifting or bitwise operation. Also unlike
+C, expressions like ``a < b < c`` have the interpretation that is conventional
+in mathematics:
+
+.. productionlist::
+ comparison: `or_expr` ( `comp_operator` `or_expr` )*
+ comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!="
+ : | "is" ["not"] | ["not"] "in"
+
+Comparisons yield boolean values: ``True`` or ``False``.
+
+.. index:: pair: chaining; comparisons
+
+Comparisons can be chained arbitrarily, e.g., ``x < y <= z`` is equivalent to
+``x < y and y <= z``, except that ``y`` is evaluated only once (but in both
+cases ``z`` is not evaluated at all when ``x < y`` is found to be false).
+
+Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *opa*, *opb*, ...,
+*opy* are comparison operators, then *a opa b opb c* ...*y opy z* is equivalent
+to *a opa b* :keyword:`and` *b opb c* :keyword:`and` ... *y opy z*, except that
+each expression is evaluated at most once.
+
+Note that *a opa b opb c* doesn't imply any kind of comparison between *a* and
+*c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not
+pretty).
+
+The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the
+values of two objects. The objects need not have the same type. If both are
+numbers, they are converted to a common type. Otherwise, objects of different
+types *always* compare unequal, and are ordered consistently but arbitrarily.
+You can control comparison behavior of objects of non-builtin types by defining
+a ``__cmp__`` method or rich comparison methods like ``__gt__``, described in
+section :ref:`specialnames`.
+
+(This unusual definition of comparison was used to simplify the definition of
+operations like sorting and the :keyword:`in` and :keyword:`not in` operators.
+In the future, the comparison rules for objects of different types are likely to
+change.)
+
+Comparison of objects of the same type depends on the type:
+
+* Numbers are compared arithmetically.
+
+* Strings are compared lexicographically using the numeric equivalents (the
+ result of the built-in function :func:`ord`) of their characters. Unicode and
+ 8-bit strings are fully interoperable in this behavior.
+
+* Tuples and lists are compared lexicographically using comparison of
+ corresponding elements. This means that to compare equal, each element must
+ compare equal and the two sequences must be of the same type and have the same
+ length.
+
+ If not equal, the sequences are ordered the same as their first differing
+ elements. For example, ``cmp([1,2,x], [1,2,y])`` returns the same as
+ ``cmp(x,y)``. If the corresponding element does not exist, the shorter sequence
+ is ordered first (for example, ``[1,2] < [1,2,3]``).
+
+* Mappings (dictionaries) compare equal if and only if their sorted (key, value)
+ lists compare equal. [#]_ Outcomes other than equality are resolved
+ consistently, but are not otherwise defined. [#]_
+
+* Most other objects of builtin types compare unequal unless they are the same
+ object; the choice whether one object is considered smaller or larger than
+ another one is made arbitrarily but consistently within one execution of a
+ program.
+
+The operators :keyword:`in` and :keyword:`not in` test for set membership. ``x
+in s`` evaluates to true if *x* is a member of the set *s*, and false otherwise.
+``x not in s`` returns the negation of ``x in s``. The set membership test has
+traditionally been bound to sequences; an object is a member of a set if the set
+is a sequence and contains an element equal to that object. However, it is
+possible for an object to support membership tests without being a sequence. In
+particular, dictionaries support membership testing as a nicer way of spelling
+``key in dict``; other mapping types may follow suit.
+
+For the list and tuple types, ``x in y`` is true if and only if there exists an
+index *i* such that ``x == y[i]`` is true.
+
+For the Unicode and string types, ``x in y`` is true if and only if *x* is a
+substring of *y*. An equivalent test is ``y.find(x) != -1``. Note, *x* and *y*
+need not be the same type; consequently, ``u'ab' in 'abc'`` will return
+``True``. Empty strings are always considered to be a substring of any other
+string, so ``"" in "abc"`` will return ``True``.
+
+.. versionchanged:: 2.3
+ Previously, *x* was required to be a string of length ``1``.
+
+For user-defined classes which define the :meth:`__contains__` method, ``x in
+y`` is true if and only if ``y.__contains__(x)`` is true.
+
+For user-defined classes which do not define :meth:`__contains__` and do define
+:meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative
+integer index *i* such that ``x == y[i]``, and all lower integer indices do not
+raise :exc:`IndexError` exception. (If any other exception is raised, it is as
+if :keyword:`in` raised that exception).
+
+.. index::
+ operator: in
+ operator: not in
+ pair: membership; test
+ object: sequence
+
+The operator :keyword:`not in` is defined to have the inverse true value of
+:keyword:`in`.
+
+.. index::
+ operator: is
+ operator: is not
+ pair: identity; test
+
+The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x
+is y`` is true if and only if *x* and *y* are the same object. ``x is not y``
+yields the inverse truth value.
+
+
+.. _booleans:
+
+Boolean operations
+==================
+
+.. index::
+ pair: Conditional; expression
+ pair: Boolean; operation
+
+Boolean operations have the lowest priority of all Python operations:
+
+.. productionlist::
+ expression: `conditional_expression` | `lambda_form`
+ old_expression: `or_test` | `old_lambda_form`
+ conditional_expression: `or_test` ["if" `or_test` "else" `expression`]
+ or_test: `and_test` | `or_test` "or" `and_test`
+ and_test: `not_test` | `and_test` "and" `not_test`
+ not_test: `comparison` | "not" `not_test`
+
+In the context of Boolean operations, and also when expressions are used by
+control flow statements, the following values are interpreted as false:
+``False``, ``None``, numeric zero of all types, and empty strings and containers
+(including strings, tuples, lists, dictionaries, sets and frozensets). All
+other values are interpreted as true.
+
+.. index:: operator: not
+
+The operator :keyword:`not` yields ``True`` if its argument is false, ``False``
+otherwise.
+
+The expression ``x if C else y`` first evaluates *C* (*not* *x*); if *C* is
+true, *x* is evaluated and its value is returned; otherwise, *y* is evaluated
+and its value is returned.
+
+.. versionadded:: 2.5
+
+.. index:: operator: and
+
+The expression ``x and y`` first evaluates *x*; if *x* is false, its value is
+returned; otherwise, *y* is evaluated and the resulting value is returned.
+
+.. index:: operator: or
+
+The expression ``x or y`` first evaluates *x*; if *x* is true, its value is
+returned; otherwise, *y* is evaluated and the resulting value is returned.
+
+(Note that neither :keyword:`and` nor :keyword:`or` restrict the value and type
+they return to ``False`` and ``True``, but rather return the last evaluated
+argument. This is sometimes useful, e.g., if ``s`` is a string that should be
+replaced by a default value if it is empty, the expression ``s or 'foo'`` yields
+the desired value. Because :keyword:`not` has to invent a value anyway, it does
+not bother to return a value of the same type as its argument, so e.g., ``not
+'foo'`` yields ``False``, not ``''``.)
+
+
+.. _lambdas:
+
+Lambdas
+=======
+
+.. index::
+ pair: lambda; expression
+ pair: lambda; form
+ pair: anonymous; function
+
+.. productionlist::
+ lambda_form: "lambda" [`parameter_list`]: `expression`
+ old_lambda_form: "lambda" [`parameter_list`]: `old_expression`
+
+Lambda forms (lambda expressions) have the same syntactic position as
+expressions. They are a shorthand to create anonymous functions; the expression
+``lambda arguments: expression`` yields a function object. The unnamed object
+behaves like a function object defined with ::
+
+ def name(arguments):
+ return expression
+
+See section :ref:`function` for the syntax of parameter lists. Note that
+functions created with lambda forms cannot contain statements or annotations.
+
+.. _lambda:
+
+
+.. _exprlists:
+
+Expression lists
+================
+
+.. index:: pair: expression; list
+
+.. productionlist::
+ expression_list: `expression` ( "," `expression` )* [","]
+
+.. index:: object: tuple
+
+An expression list containing at least one comma yields a tuple. The length of
+the tuple is the number of expressions in the list. The expressions are
+evaluated from left to right.
+
+.. index:: pair: trailing; comma
+
+The trailing comma is required only to create a single tuple (a.k.a. a
+*singleton*); it is optional in all other cases. A single expression without a
+trailing comma doesn't create a tuple, but rather yields the value of that
+expression. (To create an empty tuple, use an empty pair of parentheses:
+``()``.)
+
+
+.. _evalorder:
+
+Evaluation order
+================
+
+.. index:: pair: evaluation; order
+
+Python evaluates expressions from left to right. Notice that while evaluating an
+assignment, the right-hand side is evaluated before the left-hand side.
+
+In the following lines, expressions will be evaluated in the arithmetic order of
+their suffixes::
+
+ expr1, expr2, expr3, expr4
+ (expr1, expr2, expr3, expr4)
+ {expr1: expr2, expr3: expr4}
+ expr1 + expr2 * (expr3 - expr4)
+ func(expr1, expr2, *expr3, **expr4)
+ expr3, expr4 = expr1, expr2
+
+
+.. _operator-summary:
+
+Summary
+=======
+
+.. index:: pair: operator; precedence
+
+The following table summarizes the operator precedences in Python, from lowest
+precedence (least binding) to highest precedence (most binding). Operators in
+the same box have the same precedence. Unless the syntax is explicitly given,
+operators are binary. Operators in the same box group left to right (except for
+comparisons, including tests, which all have the same precedence and chain from
+left to right --- see section :ref:`comparisons` --- and exponentiation, which
+groups from right to left).
+
++----------------------------------------------+-------------------------------------+
+| Operator | Description |
++==============================================+=====================================+
+| :keyword:`lambda` | Lambda expression |
++----------------------------------------------+-------------------------------------+
+| :keyword:`or` | Boolean OR |
++----------------------------------------------+-------------------------------------+
+| :keyword:`and` | Boolean AND |
++----------------------------------------------+-------------------------------------+
+| :keyword:`not` *x* | Boolean NOT |
++----------------------------------------------+-------------------------------------+
+| :keyword:`in`, :keyword:`not` :keyword:`in` | Membership tests |
++----------------------------------------------+-------------------------------------+
+| :keyword:`is`, :keyword:`is not` | Identity tests |
++----------------------------------------------+-------------------------------------+
+| ``<``, ``<=``, ``>``, ``>=``, ``!=``, ``==`` | Comparisons |
++----------------------------------------------+-------------------------------------+
+| ``|`` | Bitwise OR |
++----------------------------------------------+-------------------------------------+
+| ``^`` | Bitwise XOR |
++----------------------------------------------+-------------------------------------+
+| ``&`` | Bitwise AND |
++----------------------------------------------+-------------------------------------+
+| ``<<``, ``>>`` | Shifts |
++----------------------------------------------+-------------------------------------+
+| ``+``, ``-`` | Addition and subtraction |
++----------------------------------------------+-------------------------------------+
+| ``*``, ``/``, ``%`` | Multiplication, division, remainder |
++----------------------------------------------+-------------------------------------+
+| ``+x``, ``-x`` | Positive, negative |
++----------------------------------------------+-------------------------------------+
+| ``~x`` | Bitwise not |
++----------------------------------------------+-------------------------------------+
+| ``**`` | Exponentiation |
++----------------------------------------------+-------------------------------------+
+| ``x.attribute`` | Attribute reference |
++----------------------------------------------+-------------------------------------+
+| ``x[index]`` | Subscription |
++----------------------------------------------+-------------------------------------+
+| ``x[index:index]`` | Slicing |
++----------------------------------------------+-------------------------------------+
+| ``f(arguments...)`` | Function call |
++----------------------------------------------+-------------------------------------+
+| ``(expressions...)`` | Binding or tuple display |
++----------------------------------------------+-------------------------------------+
+| ``[expressions...]`` | List display |
++----------------------------------------------+-------------------------------------+
+| ``{key:datum...}`` | Dictionary display |
++----------------------------------------------+-------------------------------------+
+
+.. rubric:: Footnotes
+
+.. [#] In Python 2.3, a list comprehension "leaks" the control variables of each
+ ``for`` it contains into the containing scope. However, this behavior is
+ deprecated, and relying on it will not work once this bug is fixed in a future
+ release
+
+.. [#] While ``abs(x%y) < abs(y)`` is true mathematically, for floats it may not be
+ true numerically due to roundoff. For example, and assuming a platform on which
+ a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 %
+ 1e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 +
+ 1e100``, which is numerically exactly equal to ``1e100``. Function :func:`fmod`
+ in the :mod:`math` module returns a result whose sign matches the sign of the
+ first argument instead, and so returns ``-1e-100`` in this case. Which approach
+ is more appropriate depends on the application.
+
+.. [#] If x is very close to an exact integer multiple of y, it's possible for
+ ``floor(x/y)`` to be one larger than ``(x-x%y)/y`` due to rounding. In such
+ cases, Python returns the latter result, in order to preserve that
+ ``divmod(x,y)[0] * y + x % y`` be very close to ``x``.
+
+.. [#] The implementation computes this efficiently, without constructing lists or
+ sorting.
+
+.. [#] Earlier versions of Python used lexicographic comparison of the sorted (key,
+ value) lists, but this was very expensive for the common case of comparing for
+ equality. An even earlier version of Python compared dictionaries by identity
+ only, but this caused surprises because people expected to be able to test a
+ dictionary for emptiness by comparing it to ``{}``.
+
diff --git a/Doc/reference/index.rst b/Doc/reference/index.rst
new file mode 100644
index 0000000..18bf053
--- /dev/null
+++ b/Doc/reference/index.rst
@@ -0,0 +1,30 @@
+.. _reference-index:
+
+#################################
+ The Python language reference
+#################################
+
+:Release: |version|
+:Date: |today|
+
+This reference manual describes the syntax and "core semantics" of the
+language. It is terse, but attempts to be exact and complete. The semantics of
+non-essential built-in object types and of the built-in functions and modules
+are described in :ref:`library-index`. For an informal introduction to the
+language, see :ref:`tutorial-index`. For C or C++ programmers, two additional
+manuals exist: :ref:`extending-index` describes the high-level picture of how to
+write a Python extension module, and the :ref:`c-api-index` describes the
+interfaces available to C/C++ programmers in detail.
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction.rst
+ lexical_analysis.rst
+ datamodel.rst
+ executionmodel.rst
+ expressions.rst
+ simple_stmts.rst
+ compound_stmts.rst
+ toplevel_components.rst
+
diff --git a/Doc/reference/introduction.rst b/Doc/reference/introduction.rst
new file mode 100644
index 0000000..0d53719
--- /dev/null
+++ b/Doc/reference/introduction.rst
@@ -0,0 +1,138 @@
+
+.. _introduction:
+
+************
+Introduction
+************
+
+This reference manual describes the Python programming language. It is not
+intended as a tutorial.
+
+While I am trying to be as precise as possible, I chose to use English rather
+than formal specifications for everything except syntax and lexical analysis.
+This should make the document more understandable to the average reader, but
+will leave room for ambiguities. Consequently, if you were coming from Mars and
+tried to re-implement Python from this document alone, you might have to guess
+things and in fact you would probably end up implementing quite a different
+language. On the other hand, if you are using Python and wonder what the precise
+rules about a particular area of the language are, you should definitely be able
+to find them here. If you would like to see a more formal definition of the
+language, maybe you could volunteer your time --- or invent a cloning machine
+:-).
+
+It is dangerous to add too many implementation details to a language reference
+document --- the implementation may change, and other implementations of the
+same language may work differently. On the other hand, there is currently only
+one Python implementation in widespread use (although alternate implementations
+exist), and its particular quirks are sometimes worth being mentioned,
+especially where the implementation imposes additional limitations. Therefore,
+you'll find short "implementation notes" sprinkled throughout the text.
+
+Every Python implementation comes with a number of built-in and standard
+modules. These are documented in :ref:`library-index`. A few built-in modules
+are mentioned when they interact in a significant way with the language
+definition.
+
+
+.. _implementations:
+
+Alternate Implementations
+=========================
+
+Though there is one Python implementation which is by far the most popular,
+there are some alternate implementations which are of particular interest to
+different audiences.
+
+Known implementations include:
+
+CPython
+ This is the original and most-maintained implementation of Python, written in C.
+ New language features generally appear here first.
+
+Jython
+ Python implemented in Java. This implementation can be used as a scripting
+ language for Java applications, or can be used to create applications using the
+ Java class libraries. It is also often used to create tests for Java libraries.
+ More information can be found at `the Jython website <http://www.jython.org/>`_.
+
+Python for .NET
+ This implementation actually uses the CPython implementation, but is a managed
+ .NET application and makes .NET libraries available. This was created by Brian
+ Lloyd. For more information, see the `Python for .NET home page
+ <http://www.zope.org/Members/Brian/PythonNet>`_.
+
+IronPython
+ An alternate Python for .NET. Unlike Python.NET, this is a complete Python
+ implementation that generates IL, and compiles Python code directly to .NET
+ assemblies. It was created by Jim Hugunin, the original creator of Jython. For
+ more information, see `the IronPython website
+ <http://workspaces.gotdotnet.com/ironpython>`_.
+
+PyPy
+ An implementation of Python written in Python; even the bytecode interpreter is
+ written in Python. This is executed using CPython as the underlying
+ interpreter. One of the goals of the project is to encourage experimentation
+ with the language itself by making it easier to modify the interpreter (since it
+ is written in Python). Additional information is available on `the PyPy
+ project's home page <http://codespeak.net/pypy/>`_.
+
+Each of these implementations varies in some way from the language as documented
+in this manual, or introduces specific information beyond what's covered in the
+standard Python documentation. Please refer to the implementation-specific
+documentation to determine what else you need to know about the specific
+implementation you're using.
+
+
+.. _notation:
+
+Notation
+========
+
+.. index::
+ single: BNF
+ single: grammar
+ single: syntax
+ single: notation
+
+The descriptions of lexical analysis and syntax use a modified BNF grammar
+notation. This uses the following style of definition:
+
+.. productionlist:: *
+ name: `lc_letter` (`lc_letter` | "_")*
+ lc_letter: "a"..."z"
+
+The first line says that a ``name`` is an ``lc_letter`` followed by a sequence
+of zero or more ``lc_letter``\ s and underscores. An ``lc_letter`` in turn is
+any of the single characters ``'a'`` through ``'z'``. (This rule is actually
+adhered to for the names defined in lexical and grammar rules in this document.)
+
+Each rule begins with a name (which is the name defined by the rule) and
+``::=``. A vertical bar (``|``) is used to separate alternatives; it is the
+least binding operator in this notation. A star (``*``) means zero or more
+repetitions of the preceding item; likewise, a plus (``+``) means one or more
+repetitions, and a phrase enclosed in square brackets (``[ ]``) means zero or
+one occurrences (in other words, the enclosed phrase is optional). The ``*``
+and ``+`` operators bind as tightly as possible; parentheses are used for
+grouping. Literal strings are enclosed in quotes. White space is only
+meaningful to separate tokens. Rules are normally contained on a single line;
+rules with many alternatives may be formatted alternatively with each line after
+the first beginning with a vertical bar.
+
+.. index::
+ single: lexical definitions
+ single: ASCII@ASCII
+
+In lexical definitions (as the example above), two more conventions are used:
+Two literal characters separated by three dots mean a choice of any single
+character in the given (inclusive) range of ASCII characters. A phrase between
+angular brackets (``<...>``) gives an informal description of the symbol
+defined; e.g., this could be used to describe the notion of 'control character'
+if needed.
+
+Even though the notation used is almost the same, there is a big difference
+between the meaning of lexical and syntactic definitions: a lexical definition
+operates on the individual characters of the input source, while a syntax
+definition operates on the stream of tokens generated by the lexical analysis.
+All uses of BNF in the next chapter ("Lexical Analysis") are lexical
+definitions; uses in subsequent chapters are syntactic definitions.
+
diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst
new file mode 100644
index 0000000..35e92cf
--- /dev/null
+++ b/Doc/reference/lexical_analysis.rst
@@ -0,0 +1,758 @@
+
+.. _lexical:
+
+****************
+Lexical analysis
+****************
+
+.. index::
+ single: lexical analysis
+ single: parser
+ single: token
+
+A Python program is read by a *parser*. Input to the parser is a stream of
+*tokens*, generated by the *lexical analyzer*. This chapter describes how the
+lexical analyzer breaks a file into tokens.
+
+Python uses the 7-bit ASCII character set for program text.
+
+.. versionadded:: 2.3
+ An encoding declaration can be used to indicate that string literals and
+ comments use an encoding different from ASCII.
+
+For compatibility with older versions, Python only warns if it finds 8-bit
+characters; those warnings should be corrected by either declaring an explicit
+encoding, or using escape sequences if those bytes are binary data, instead of
+characters.
+
+The run-time character set depends on the I/O devices connected to the program
+but is generally a superset of ASCII.
+
+**Future compatibility note:** It may be tempting to assume that the character
+set for 8-bit characters is ISO Latin-1 (an ASCII superset that covers most
+western languages that use the Latin alphabet), but it is possible that in the
+future Unicode text editors will become common. These generally use the UTF-8
+encoding, which is also an ASCII superset, but with very different use for the
+characters with ordinals 128-255. While there is no consensus on this subject
+yet, it is unwise to assume either Latin-1 or UTF-8, even though the current
+implementation appears to favor Latin-1. This applies both to the source
+character set and the run-time character set.
+
+
+.. _line-structure:
+
+Line structure
+==============
+
+.. index:: single: line structure
+
+A Python program is divided into a number of *logical lines*.
+
+
+.. _logical:
+
+Logical lines
+-------------
+
+.. index::
+ single: logical line
+ single: physical line
+ single: line joining
+ single: NEWLINE token
+
+The end of a logical line is represented by the token NEWLINE. Statements
+cannot cross logical line boundaries except where NEWLINE is allowed by the
+syntax (e.g., between statements in compound statements). A logical line is
+constructed from one or more *physical lines* by following the explicit or
+implicit *line joining* rules.
+
+
+.. _physical:
+
+Physical lines
+--------------
+
+A physical line is a sequence of characters terminated by an end-of-line
+sequence. In source files, any of the standard platform line termination
+sequences can be used - the Unix form using ASCII LF (linefeed), the Windows
+form using the ASCII sequence CR LF (return followed by linefeed), or the
+Macintosh form using the ASCII CR (return) character. All of these forms can be
+used equally, regardless of platform.
+
+When embedding Python, source code strings should be passed to Python APIs using
+the standard C conventions for newline characters (the ``\n`` character,
+representing ASCII LF, is the line terminator).
+
+
+.. _comments:
+
+Comments
+--------
+
+.. index::
+ single: comment
+ single: hash character
+
+A comment starts with a hash character (``#``) that is not part of a string
+literal, and ends at the end of the physical line. A comment signifies the end
+of the logical line unless the implicit line joining rules are invoked. Comments
+are ignored by the syntax; they are not tokens.
+
+
+.. _encodings:
+
+Encoding declarations
+---------------------
+
+.. index::
+ single: source character set
+ single: encodings
+
+If a comment in the first or second line of the Python script matches the
+regular expression ``coding[=:]\s*([-\w.]+)``, this comment is processed as an
+encoding declaration; the first group of this expression names the encoding of
+the source code file. The recommended forms of this expression are ::
+
+ # -*- coding: <encoding-name> -*-
+
+which is recognized also by GNU Emacs, and ::
+
+ # vim:fileencoding=<encoding-name>
+
+which is recognized by Bram Moolenaar's VIM. In addition, if the first bytes of
+the file are the UTF-8 byte-order mark (``'\xef\xbb\xbf'``), the declared file
+encoding is UTF-8 (this is supported, among others, by Microsoft's
+:program:`notepad`).
+
+If an encoding is declared, the encoding name must be recognized by Python. The
+encoding is used for all lexical analysis, in particular to find the end of a
+string, and to interpret the contents of Unicode literals. String literals are
+converted to Unicode for syntactical analysis, then converted back to their
+original encoding before interpretation starts. The encoding declaration must
+appear on a line of its own.
+
+.. % XXX there should be a list of supported encodings.
+
+
+.. _explicit-joining:
+
+Explicit line joining
+---------------------
+
+.. index::
+ single: physical line
+ single: line joining
+ single: line continuation
+ single: backslash character
+
+Two or more physical lines may be joined into logical lines using backslash
+characters (``\``), as follows: when a physical line ends in a backslash that is
+not part of a string literal or comment, it is joined with the following forming
+a single logical line, deleting the backslash and the following end-of-line
+character. For example:
+
+.. %
+
+::
+
+ if 1900 < year < 2100 and 1 <= month <= 12 \
+ and 1 <= day <= 31 and 0 <= hour < 24 \
+ and 0 <= minute < 60 and 0 <= second < 60: # Looks like a valid date
+ return 1
+
+A line ending in a backslash cannot carry a comment. A backslash does not
+continue a comment. A backslash does not continue a token except for string
+literals (i.e., tokens other than string literals cannot be split across
+physical lines using a backslash). A backslash is illegal elsewhere on a line
+outside a string literal.
+
+
+.. _implicit-joining:
+
+Implicit line joining
+---------------------
+
+Expressions in parentheses, square brackets or curly braces can be split over
+more than one physical line without using backslashes. For example::
+
+ month_names = ['Januari', 'Februari', 'Maart', # These are the
+ 'April', 'Mei', 'Juni', # Dutch names
+ 'Juli', 'Augustus', 'September', # for the months
+ 'Oktober', 'November', 'December'] # of the year
+
+Implicitly continued lines can carry comments. The indentation of the
+continuation lines is not important. Blank continuation lines are allowed.
+There is no NEWLINE token between implicit continuation lines. Implicitly
+continued lines can also occur within triple-quoted strings (see below); in that
+case they cannot carry comments.
+
+
+.. _blank-lines:
+
+Blank lines
+-----------
+
+.. index:: single: blank line
+
+A logical line that contains only spaces, tabs, formfeeds and possibly a
+comment, is ignored (i.e., no NEWLINE token is generated). During interactive
+input of statements, handling of a blank line may differ depending on the
+implementation of the read-eval-print loop. In the standard implementation, an
+entirely blank logical line (i.e. one containing not even whitespace or a
+comment) terminates a multi-line statement.
+
+
+.. _indentation:
+
+Indentation
+-----------
+
+.. index::
+ single: indentation
+ single: whitespace
+ single: leading whitespace
+ single: space
+ single: tab
+ single: grouping
+ single: statement grouping
+
+Leading whitespace (spaces and tabs) at the beginning of a logical line is used
+to compute the indentation level of the line, which in turn is used to determine
+the grouping of statements.
+
+First, tabs are replaced (from left to right) by one to eight spaces such that
+the total number of characters up to and including the replacement is a multiple
+of eight (this is intended to be the same rule as used by Unix). The total
+number of spaces preceding the first non-blank character then determines the
+line's indentation. Indentation cannot be split over multiple physical lines
+using backslashes; the whitespace up to the first backslash determines the
+indentation.
+
+**Cross-platform compatibility note:** because of the nature of text editors on
+non-UNIX platforms, it is unwise to use a mixture of spaces and tabs for the
+indentation in a single source file. It should also be noted that different
+platforms may explicitly limit the maximum indentation level.
+
+A formfeed character may be present at the start of the line; it will be ignored
+for the indentation calculations above. Formfeed characters occurring elsewhere
+in the leading whitespace have an undefined effect (for instance, they may reset
+the space count to zero).
+
+.. index::
+ single: INDENT token
+ single: DEDENT token
+
+The indentation levels of consecutive lines are used to generate INDENT and
+DEDENT tokens, using a stack, as follows.
+
+Before the first line of the file is read, a single zero is pushed on the stack;
+this will never be popped off again. The numbers pushed on the stack will
+always be strictly increasing from bottom to top. At the beginning of each
+logical line, the line's indentation level is compared to the top of the stack.
+If it is equal, nothing happens. If it is larger, it is pushed on the stack, and
+one INDENT token is generated. If it is smaller, it *must* be one of the
+numbers occurring on the stack; all numbers on the stack that are larger are
+popped off, and for each number popped off a DEDENT token is generated. At the
+end of the file, a DEDENT token is generated for each number remaining on the
+stack that is larger than zero.
+
+Here is an example of a correctly (though confusingly) indented piece of Python
+code::
+
+ def perm(l):
+ # Compute the list of all permutations of l
+ if len(l) <= 1:
+ return [l]
+ r = []
+ for i in range(len(l)):
+ s = l[:i] + l[i+1:]
+ p = perm(s)
+ for x in p:
+ r.append(l[i:i+1] + x)
+ return r
+
+The following example shows various indentation errors::
+
+ def perm(l): # error: first line indented
+ for i in range(len(l)): # error: not indented
+ s = l[:i] + l[i+1:]
+ p = perm(l[:i] + l[i+1:]) # error: unexpected indent
+ for x in p:
+ r.append(l[i:i+1] + x)
+ return r # error: inconsistent dedent
+
+(Actually, the first three errors are detected by the parser; only the last
+error is found by the lexical analyzer --- the indentation of ``return r`` does
+not match a level popped off the stack.)
+
+
+.. _whitespace:
+
+Whitespace between tokens
+-------------------------
+
+Except at the beginning of a logical line or in string literals, the whitespace
+characters space, tab and formfeed can be used interchangeably to separate
+tokens. Whitespace is needed between two tokens only if their concatenation
+could otherwise be interpreted as a different token (e.g., ab is one token, but
+a b is two tokens).
+
+
+.. _other-tokens:
+
+Other tokens
+============
+
+Besides NEWLINE, INDENT and DEDENT, the following categories of tokens exist:
+*identifiers*, *keywords*, *literals*, *operators*, and *delimiters*. Whitespace
+characters (other than line terminators, discussed earlier) are not tokens, but
+serve to delimit tokens. Where ambiguity exists, a token comprises the longest
+possible string that forms a legal token, when read from left to right.
+
+
+.. _identifiers:
+
+Identifiers and keywords
+========================
+
+.. index::
+ single: identifier
+ single: name
+
+Identifiers (also referred to as *names*) are described by the following lexical
+definitions:
+
+.. productionlist::
+ identifier: (`letter`|"_") (`letter` | `digit` | "_")*
+ letter: `lowercase` | `uppercase`
+ lowercase: "a"..."z"
+ uppercase: "A"..."Z"
+ digit: "0"..."9"
+
+Identifiers are unlimited in length. Case is significant.
+
+
+.. _keywords:
+
+Keywords
+--------
+
+.. index::
+ single: keyword
+ single: reserved word
+
+The following identifiers are used as reserved words, or *keywords* of the
+language, and cannot be used as ordinary identifiers. They must be spelled
+exactly as written here::
+
+ and def for is raise
+ as del from lambda return
+ assert elif global not try
+ break else if or while
+ class except import pass with
+ continue finally in print yield
+
+.. versionchanged:: 2.4
+ :const:`None` became a constant and is now recognized by the compiler as a name
+ for the built-in object :const:`None`. Although it is not a keyword, you cannot
+ assign a different object to it.
+
+.. versionchanged:: 2.5
+ Both :keyword:`as` and :keyword:`with` are only recognized when the
+ ``with_statement`` future feature has been enabled. It will always be enabled in
+ Python 2.6. See section :ref:`with` for details. Note that using :keyword:`as`
+ and :keyword:`with` as identifiers will always issue a warning, even when the
+ ``with_statement`` future directive is not in effect.
+
+
+.. _id-classes:
+
+Reserved classes of identifiers
+-------------------------------
+
+Certain classes of identifiers (besides keywords) have special meanings. These
+classes are identified by the patterns of leading and trailing underscore
+characters:
+
+``_*``
+ Not imported by ``from module import *``. The special identifier ``_`` is used
+ in the interactive interpreter to store the result of the last evaluation; it is
+ stored in the :mod:`__builtin__` module. When not in interactive mode, ``_``
+ has no special meaning and is not defined. See section :ref:`import`.
+
+ .. note::
+
+ The name ``_`` is often used in conjunction with internationalization;
+ refer to the documentation for the :mod:`gettext` module for more
+ information on this convention.
+
+``__*__``
+ System-defined names. These names are defined by the interpreter and its
+ implementation (including the standard library); applications should not expect
+ to define additional names using this convention. The set of names of this
+ class defined by Python may be extended in future versions. See section
+ :ref:`specialnames`.
+
+``__*``
+ Class-private names. Names in this category, when used within the context of a
+ class definition, are re-written to use a mangled form to help avoid name
+ clashes between "private" attributes of base and derived classes. See section
+ :ref:`atom-identifiers`.
+
+
+.. _literals:
+
+Literals
+========
+
+.. index::
+ single: literal
+ single: constant
+
+Literals are notations for constant values of some built-in types.
+
+
+.. _strings:
+
+String literals
+---------------
+
+.. index:: single: string literal
+
+String literals are described by the following lexical definitions:
+
+.. index:: single: ASCII@ASCII
+
+.. productionlist::
+ stringliteral: [`stringprefix`](`shortstring` | `longstring`)
+ stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR"
+ shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"'
+ longstring: ""'" `longstringitem`* ""'"
+ : | '"""' `longstringitem`* '"""'
+ shortstringitem: `shortstringchar` | `escapeseq`
+ longstringitem: `longstringchar` | `escapeseq`
+ shortstringchar: <any source character except "\" or newline or the quote>
+ longstringchar: <any source character except "\">
+ escapeseq: "\" <any ASCII character>
+
+One syntactic restriction not indicated by these productions is that whitespace
+is not allowed between the :token:`stringprefix` and the rest of the string
+literal. The source character set is defined by the encoding declaration; it is
+ASCII if no encoding declaration is given in the source file; see section
+:ref:`encodings`.
+
+.. index::
+ single: triple-quoted string
+ single: Unicode Consortium
+ single: string; Unicode
+ single: raw string
+
+In plain English: String literals can be enclosed in matching single quotes
+(``'``) or double quotes (``"``). They can also be enclosed in matching groups
+of three single or double quotes (these are generally referred to as
+*triple-quoted strings*). The backslash (``\``) character is used to escape
+characters that otherwise have a special meaning, such as newline, backslash
+itself, or the quote character. String literals may optionally be prefixed with
+a letter ``'r'`` or ``'R'``; such strings are called :dfn:`raw strings` and use
+different rules for interpreting backslash escape sequences. A prefix of
+``'u'`` or ``'U'`` makes the string a Unicode string. Unicode strings use the
+Unicode character set as defined by the Unicode Consortium and ISO 10646. Some
+additional escape sequences, described below, are available in Unicode strings.
+The two prefix characters may be combined; in this case, ``'u'`` must appear
+before ``'r'``.
+
+In triple-quoted strings, unescaped newlines and quotes are allowed (and are
+retained), except that three unescaped quotes in a row terminate the string. (A
+"quote" is the character used to open the string, i.e. either ``'`` or ``"``.)
+
+.. index::
+ single: physical line
+ single: escape sequence
+ single: Standard C
+ single: C
+
+Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in strings are
+interpreted according to rules similar to those used by Standard C. The
+recognized escape sequences are:
+
++-----------------+---------------------------------+-------+
+| Escape Sequence | Meaning | Notes |
++=================+=================================+=======+
+| ``\newline`` | Ignored | |
++-----------------+---------------------------------+-------+
+| ``\\`` | Backslash (``\``) | |
++-----------------+---------------------------------+-------+
+| ``\'`` | Single quote (``'``) | |
++-----------------+---------------------------------+-------+
+| ``\"`` | Double quote (``"``) | |
++-----------------+---------------------------------+-------+
+| ``\a`` | ASCII Bell (BEL) | |
++-----------------+---------------------------------+-------+
+| ``\b`` | ASCII Backspace (BS) | |
++-----------------+---------------------------------+-------+
+| ``\f`` | ASCII Formfeed (FF) | |
++-----------------+---------------------------------+-------+
+| ``\n`` | ASCII Linefeed (LF) | |
++-----------------+---------------------------------+-------+
+| ``\N{name}`` | Character named *name* in the | |
+| | Unicode database (Unicode only) | |
++-----------------+---------------------------------+-------+
+| ``\r`` | ASCII Carriage Return (CR) | |
++-----------------+---------------------------------+-------+
+| ``\t`` | ASCII Horizontal Tab (TAB) | |
++-----------------+---------------------------------+-------+
+| ``\uxxxx`` | Character with 16-bit hex value | \(1) |
+| | *xxxx* (Unicode only) | |
++-----------------+---------------------------------+-------+
+| ``\Uxxxxxxxx`` | Character with 32-bit hex value | \(2) |
+| | *xxxxxxxx* (Unicode only) | |
++-----------------+---------------------------------+-------+
+| ``\v`` | ASCII Vertical Tab (VT) | |
++-----------------+---------------------------------+-------+
+| ``\ooo`` | Character with octal value | (3,5) |
+| | *ooo* | |
++-----------------+---------------------------------+-------+
+| ``\xhh`` | Character with hex value *hh* | (4,5) |
++-----------------+---------------------------------+-------+
+
+.. index:: single: ASCII@ASCII
+
+Notes:
+
+(1)
+ Individual code units which form parts of a surrogate pair can be encoded using
+ this escape sequence.
+
+(2)
+ Any Unicode character can be encoded this way, but characters outside the Basic
+ Multilingual Plane (BMP) will be encoded using a surrogate pair if Python is
+ compiled to use 16-bit code units (the default). Individual code units which
+ form parts of a surrogate pair can be encoded using this escape sequence.
+
+(3)
+ As in Standard C, up to three octal digits are accepted.
+
+(4)
+ Unlike in Standard C, at most two hex digits are accepted.
+
+(5)
+ In a string literal, hexadecimal and octal escapes denote the byte with the
+ given value; it is not necessary that the byte encodes a character in the source
+ character set. In a Unicode literal, these escapes denote a Unicode character
+ with the given value.
+
+.. index:: single: unrecognized escape sequence
+
+Unlike Standard C, all unrecognized escape sequences are left in the string
+unchanged, i.e., *the backslash is left in the string*. (This behavior is
+useful when debugging: if an escape sequence is mistyped, the resulting output
+is more easily recognized as broken.) It is also important to note that the
+escape sequences marked as "(Unicode only)" in the table above fall into the
+category of unrecognized escapes for non-Unicode string literals.
+
+When an ``'r'`` or ``'R'`` prefix is present, a character following a backslash
+is included in the string without change, and *all backslashes are left in the
+string*. For example, the string literal ``r"\n"`` consists of two characters:
+a backslash and a lowercase ``'n'``. String quotes can be escaped with a
+backslash, but the backslash remains in the string; for example, ``r"\""`` is a
+valid string literal consisting of two characters: a backslash and a double
+quote; ``r"\"`` is not a valid string literal (even a raw string cannot end in
+an odd number of backslashes). Specifically, *a raw string cannot end in a
+single backslash* (since the backslash would escape the following quote
+character). Note also that a single backslash followed by a newline is
+interpreted as those two characters as part of the string, *not* as a line
+continuation.
+
+When an ``'r'`` or ``'R'`` prefix is used in conjunction with a ``'u'`` or
+``'U'`` prefix, then the ``\uXXXX`` and ``\UXXXXXXXX`` escape sequences are
+processed while *all other backslashes are left in the string*. For example,
+the string literal ``ur"\u0062\n"`` consists of three Unicode characters: 'LATIN
+SMALL LETTER B', 'REVERSE SOLIDUS', and 'LATIN SMALL LETTER N'. Backslashes can
+be escaped with a preceding backslash; however, both remain in the string. As a
+result, ``\uXXXX`` escape sequences are only recognized when there are an odd
+number of backslashes.
+
+
+.. _string-catenation:
+
+String literal concatenation
+----------------------------
+
+Multiple adjacent string literals (delimited by whitespace), possibly using
+different quoting conventions, are allowed, and their meaning is the same as
+their concatenation. Thus, ``"hello" 'world'`` is equivalent to
+``"helloworld"``. This feature can be used to reduce the number of backslashes
+needed, to split long strings conveniently across long lines, or even to add
+comments to parts of strings, for example::
+
+ re.compile("[A-Za-z_]" # letter or underscore
+ "[A-Za-z0-9_]*" # letter, digit or underscore
+ )
+
+Note that this feature is defined at the syntactical level, but implemented at
+compile time. The '+' operator must be used to concatenate string expressions
+at run time. Also note that literal concatenation can use different quoting
+styles for each component (even mixing raw strings and triple quoted strings).
+
+
+.. _numbers:
+
+Numeric literals
+----------------
+
+.. index::
+ single: number
+ single: numeric literal
+ single: integer literal
+ single: plain integer literal
+ single: long integer literal
+ single: floating point literal
+ single: hexadecimal literal
+ single: octal literal
+ single: binary literal
+ single: decimal literal
+ single: imaginary literal
+ single: complex; literal
+
+There are four types of numeric literals: plain integers, long integers,
+floating point numbers, and imaginary numbers. There are no complex literals
+(complex numbers can be formed by adding a real number and an imaginary number).
+
+Note that numeric literals do not include a sign; a phrase like ``-1`` is
+actually an expression composed of the unary operator '``-``' and the literal
+``1``.
+
+
+.. _integers:
+
+Integer literals
+----------------
+
+Integer literals are described by the following lexical definitions:
+
+.. productionlist::
+ integer: `decimalinteger` | `octinteger` | `hexinteger`
+ decimalinteger: `nonzerodigit` `digit`* | "0"+
+ octinteger: "0" ("o" | "O") `octdigit`+
+ hexinteger: "0" ("x" | "X") `hexdigit`+
+ bininteger: "0" ("b" | "B") `bindigit`+
+ nonzerodigit: "1"..."9"
+ octdigit: "0"..."7"
+ hexdigit: `digit` | "a"..."f" | "A"..."F"
+ bindigit: "0"..."1"
+
+Plain integer literals that are above the largest representable plain integer
+(e.g., 2147483647 when using 32-bit arithmetic) are accepted as if they were
+long integers instead. [#]_ There is no limit for long integer literals apart
+from what can be stored in available memory.
+
+Note that leading zeros in a non-zero decimal number are not allowed. This is
+for disambiguation with C-style octal literals, which Python used before version
+3.0.
+
+Some examples of integer literals::
+
+ 7 2147483647 0o177 0b100110111
+ 3 79228162514264337593543950336 0o377 0x100000000
+ 79228162514264337593543950336 0xdeadbeef
+
+
+.. _floating:
+
+Floating point literals
+-----------------------
+
+Floating point literals are described by the following lexical definitions:
+
+.. productionlist::
+ floatnumber: `pointfloat` | `exponentfloat`
+ pointfloat: [`intpart`] `fraction` | `intpart` "."
+ exponentfloat: (`intpart` | `pointfloat`) `exponent`
+ intpart: `digit`+
+ fraction: "." `digit`+
+ exponent: ("e" | "E") ["+" | "-"] `digit`+
+
+Note that the integer and exponent parts are always interpreted using radix 10.
+For example, ``077e010`` is legal, and denotes the same number as ``77e10``. The
+allowed range of floating point literals is implementation-dependent. Some
+examples of floating point literals::
+
+ 3.14 10. .001 1e100 3.14e-10 0e0
+
+Note that numeric literals do not include a sign; a phrase like ``-1`` is
+actually an expression composed of the unary operator ``-`` and the literal
+``1``.
+
+
+.. _imaginary:
+
+Imaginary literals
+------------------
+
+Imaginary literals are described by the following lexical definitions:
+
+.. productionlist::
+ imagnumber: (`floatnumber` | `intpart`) ("j" | "J")
+
+An imaginary literal yields a complex number with a real part of 0.0. Complex
+numbers are represented as a pair of floating point numbers and have the same
+restrictions on their range. To create a complex number with a nonzero real
+part, add a floating point number to it, e.g., ``(3+4j)``. Some examples of
+imaginary literals::
+
+ 3.14j 10.j 10j .001j 1e100j 3.14e-10j
+
+
+.. _operators:
+
+Operators
+=========
+
+.. index:: single: operators
+
+The following tokens are operators::
+
+ + - * ** / // %
+ << >> & | ^ ~
+ < > <= >= == !=
+
+
+.. _delimiters:
+
+Delimiters
+==========
+
+.. index:: single: delimiters
+
+The following tokens serve as delimiters in the grammar::
+
+ ( ) [ ] { } @
+ , : . ` = ;
+ += -= *= /= //= %=
+ &= |= ^= >>= <<= **=
+
+The period can also occur in floating-point and imaginary literals. A sequence
+of three periods has a special meaning as an ellipsis in slices. The second half
+of the list, the augmented assignment operators, serve lexically as delimiters,
+but also perform an operation.
+
+The following printing ASCII characters have special meaning as part of other
+tokens or are otherwise significant to the lexical analyzer::
+
+ ' " # \
+
+.. index:: single: ASCII@ASCII
+
+The following printing ASCII characters are not used in Python. Their
+occurrence outside string literals and comments is an unconditional error::
+
+ $ ?
+
+.. rubric:: Footnotes
+
+.. [#] In versions of Python prior to 2.4, octal and hexadecimal literals in the range
+ just above the largest representable plain integer but below the largest
+ unsigned 32-bit number (on a machine using 32-bit arithmetic), 4294967296, were
+ taken as the negative plain integer obtained by subtracting 4294967296 from
+ their unsigned value.
+
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
new file mode 100644
index 0000000..fbc626f
--- /dev/null
+++ b/Doc/reference/simple_stmts.rst
@@ -0,0 +1,825 @@
+
+.. _simple:
+
+*****************
+Simple statements
+*****************
+
+.. index:: pair: simple; statement
+
+Simple statements are comprised within a single logical line. Several simple
+statements may occur on a single line separated by semicolons. The syntax for
+simple statements is:
+
+.. productionlist::
+ simple_stmt: `expression_stmt`
+ : | `assert_stmt`
+ : | `assignment_stmt`
+ : | `augmented_assignment_stmt`
+ : | `pass_stmt`
+ : | `del_stmt`
+ : | `return_stmt`
+ : | `yield_stmt`
+ : | `raise_stmt`
+ : | `break_stmt`
+ : | `continue_stmt`
+ : | `import_stmt`
+ : | `global_stmt`
+
+
+.. _exprstmts:
+
+Expression statements
+=====================
+
+.. index:: pair: expression; statement
+
+Expression statements are used (mostly interactively) to compute and write a
+value, or (usually) to call a procedure (a function that returns no meaningful
+result; in Python, procedures return the value ``None``). Other uses of
+expression statements are allowed and occasionally useful. The syntax for an
+expression statement is:
+
+.. productionlist::
+ expression_stmt: `expression_list`
+
+.. index:: pair: expression; list
+
+An expression statement evaluates the expression list (which may be a single
+expression).
+
+.. index::
+ builtin: repr
+ object: None
+ pair: string; conversion
+ single: output
+ pair: standard; output
+ pair: writing; values
+ pair: procedure; call
+
+In interactive mode, if the value is not ``None``, it is converted to a string
+using the built-in :func:`repr` function and the resulting string is written to
+standard output (see :func:`print`) on a line by itself. (Expression
+statements yielding ``None`` are not written, so that procedure calls do not
+cause any output.)
+
+
+.. _assert:
+
+Assert statements
+=================
+
+.. index::
+ statement: assert
+ pair: debugging; assertions
+
+Assert statements are a convenient way to insert debugging assertions into a
+program:
+
+.. productionlist::
+ assert_stmt: "assert" `expression` ["," `expression`]
+
+The simple form, ``assert expression``, is equivalent to ::
+
+ if __debug__:
+ if not expression: raise AssertionError
+
+The extended form, ``assert expression1, expression2``, is equivalent to ::
+
+ if __debug__:
+ if not expression1: raise AssertionError, expression2
+
+.. index::
+ single: __debug__
+ exception: AssertionError
+
+These equivalences assume that ``__debug__`` and :exc:`AssertionError` refer to
+the built-in variables with those names. In the current implementation, the
+built-in variable ``__debug__`` is ``True`` under normal circumstances,
+``False`` when optimization is requested (command line option -O). The current
+code generator emits no code for an assert statement when optimization is
+requested at compile time. Note that it is unnecessary to include the source
+code for the expression that failed in the error message; it will be displayed
+as part of the stack trace.
+
+Assignments to ``__debug__`` are illegal. The value for the built-in variable
+is determined when the interpreter starts.
+
+
+.. _assignment:
+
+Assignment statements
+=====================
+
+.. index::
+ pair: assignment; statement
+ pair: binding; name
+ pair: rebinding; name
+ object: mutable
+ pair: attribute; assignment
+
+Assignment statements are used to (re)bind names to values and to modify
+attributes or items of mutable objects:
+
+.. productionlist::
+ assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`)
+ target_list: `target` ("," `target`)* [","]
+ target: `identifier`
+ : | "(" `target_list` ")"
+ : | "[" `target_list` "]"
+ : | `attributeref`
+ : | `subscription`
+ : | `slicing`
+
+(See section :ref:`primaries` for the syntax definitions for the last three
+symbols.)
+
+.. index:: pair: expression; list
+
+An assignment statement evaluates the expression list (remember that this can be
+a single expression or a comma-separated list, the latter yielding a tuple) and
+assigns the single resulting object to each of the target lists, from left to
+right.
+
+.. index::
+ single: target
+ pair: target; list
+
+Assignment is defined recursively depending on the form of the target (list).
+When a target is part of a mutable object (an attribute reference, subscription
+or slicing), the mutable object must ultimately perform the assignment and
+decide about its validity, and may raise an exception if the assignment is
+unacceptable. The rules observed by various types and the exceptions raised are
+given with the definition of the object types (see section :ref:`types`).
+
+.. index:: triple: target; list; assignment
+
+Assignment of an object to a target list is recursively defined as follows.
+
+* If the target list is a single target: The object is assigned to that target.
+
+* If the target list is a comma-separated list of targets: The object must be a
+ sequence with the same number of items as there are targets in the target list,
+ and the items are assigned, from left to right, to the corresponding targets.
+ (This rule is relaxed as of Python 1.5; in earlier versions, the object had to
+ be a tuple. Since strings are sequences, an assignment like ``a, b = "xy"`` is
+ now legal as long as the string has the right length.)
+
+Assignment of an object to a single target is recursively defined as follows.
+
+* If the target is an identifier (name):
+
+ .. index:: statement: global
+
+* If the name does not occur in a :keyword:`global` statement in the current
+ code block: the name is bound to the object in the current local namespace.
+
+* Otherwise: the name is bound to the object in the current global namespace.
+
+ .. index:: single: destructor
+
+ The name is rebound if it was already bound. This may cause the reference count
+ for the object previously bound to the name to reach zero, causing the object to
+ be deallocated and its destructor (if it has one) to be called.
+
+ .. % nested
+
+* If the target is a target list enclosed in parentheses or in square brackets:
+ The object must be a sequence with the same number of items as there are targets
+ in the target list, and its items are assigned, from left to right, to the
+ corresponding targets.
+
+ .. index:: pair: attribute; assignment
+
+* If the target is an attribute reference: The primary expression in the
+ reference is evaluated. It should yield an object with assignable attributes;
+ if this is not the case, :exc:`TypeError` is raised. That object is then asked
+ to assign the assigned object to the given attribute; if it cannot perform the
+ assignment, it raises an exception (usually but not necessarily
+ :exc:`AttributeError`).
+
+ .. index::
+ pair: subscription; assignment
+ object: mutable
+
+* If the target is a subscription: The primary expression in the reference is
+ evaluated. It should yield either a mutable sequence object (such as a list) or
+ a mapping object (such as a dictionary). Next, the subscript expression is
+ evaluated.
+
+ .. index::
+ object: sequence
+ object: list
+
+ If the primary is a mutable sequence object (such as a list), the subscript must
+ yield a plain integer. If it is negative, the sequence's length is added to it.
+ The resulting value must be a nonnegative integer less than the sequence's
+ length, and the sequence is asked to assign the assigned object to its item with
+ that index. If the index is out of range, :exc:`IndexError` is raised
+ (assignment to a subscripted sequence cannot add new items to a list).
+
+ .. index::
+ object: mapping
+ object: dictionary
+
+ If the primary is a mapping object (such as a dictionary), the subscript must
+ have a type compatible with the mapping's key type, and the mapping is then
+ asked to create a key/datum pair which maps the subscript to the assigned
+ object. This can either replace an existing key/value pair with the same key
+ value, or insert a new key/value pair (if no key with the same value existed).
+
+ .. index:: pair: slicing; assignment
+
+* If the target is a slicing: The primary expression in the reference is
+ evaluated. It should yield a mutable sequence object (such as a list). The
+ assigned object should be a sequence object of the same type. Next, the lower
+ and upper bound expressions are evaluated, insofar they are present; defaults
+ are zero and the sequence's length. The bounds should evaluate to (small)
+ integers. If either bound is negative, the sequence's length is added to it.
+ The resulting bounds are clipped to lie between zero and the sequence's length,
+ inclusive. Finally, the sequence object is asked to replace the slice with the
+ items of the assigned sequence. The length of the slice may be different from
+ the length of the assigned sequence, thus changing the length of the target
+ sequence, if the object allows it.
+
+(In the current implementation, the syntax for targets is taken to be the same
+as for expressions, and invalid syntax is rejected during the code generation
+phase, causing less detailed error messages.)
+
+WARNING: Although the definition of assignment implies that overlaps between the
+left-hand side and the right-hand side are 'safe' (for example ``a, b = b, a``
+swaps two variables), overlaps *within* the collection of assigned-to variables
+are not safe! For instance, the following program prints ``[0, 2]``::
+
+ x = [0, 1]
+ i = 0
+ i, x[i] = 1, 2
+ print x
+
+
+.. _augassign:
+
+Augmented assignment statements
+-------------------------------
+
+.. index::
+ pair: augmented; assignment
+ single: statement; assignment, augmented
+
+Augmented assignment is the combination, in a single statement, of a binary
+operation and an assignment statement:
+
+.. productionlist::
+ augmented_assignment_stmt: `target` `augop` (`expression_list` | `yield_expression`)
+ augop: "+=" | "-=" | "*=" | "/=" | "%=" | "**="
+ : | ">>=" | "<<=" | "&=" | "^=" | "|="
+
+(See section :ref:`primaries` for the syntax definitions for the last three
+symbols.)
+
+An augmented assignment evaluates the target (which, unlike normal assignment
+statements, cannot be an unpacking) and the expression list, performs the binary
+operation specific to the type of assignment on the two operands, and assigns
+the result to the original target. The target is only evaluated once.
+
+An augmented assignment expression like ``x += 1`` can be rewritten as ``x = x +
+1`` to achieve a similar, but not exactly equal effect. In the augmented
+version, ``x`` is only evaluated once. Also, when possible, the actual operation
+is performed *in-place*, meaning that rather than creating a new object and
+assigning that to the target, the old object is modified instead.
+
+With the exception of assigning to tuples and multiple targets in a single
+statement, the assignment done by augmented assignment statements is handled the
+same way as normal assignments. Similarly, with the exception of the possible
+*in-place* behavior, the binary operation performed by augmented assignment is
+the same as the normal binary operations.
+
+For targets which are attribute references, the initial value is retrieved with
+a :meth:`getattr` and the result is assigned with a :meth:`setattr`. Notice
+that the two methods do not necessarily refer to the same variable. When
+:meth:`getattr` refers to a class variable, :meth:`setattr` still writes to an
+instance variable. For example::
+
+ class A:
+ x = 3 # class variable
+ a = A()
+ a.x += 1 # writes a.x as 4 leaving A.x as 3
+
+
+.. _pass:
+
+The :keyword:`pass` statement
+=============================
+
+.. index:: statement: pass
+
+.. productionlist::
+ pass_stmt: "pass"
+
+.. index:: pair: null; operation
+
+:keyword:`pass` is a null operation --- when it is executed, nothing happens.
+It is useful as a placeholder when a statement is required syntactically, but no
+code needs to be executed, for example::
+
+ def f(arg): pass # a function that does nothing (yet)
+
+ class C: pass # a class with no methods (yet)
+
+
+.. _del:
+
+The :keyword:`del` statement
+============================
+
+.. index:: statement: del
+
+.. productionlist::
+ del_stmt: "del" `target_list`
+
+.. index::
+ pair: deletion; target
+ triple: deletion; target; list
+
+Deletion is recursively defined very similar to the way assignment is defined.
+Rather that spelling it out in full details, here are some hints.
+
+Deletion of a target list recursively deletes each target, from left to right.
+
+.. index::
+ statement: global
+ pair: unbinding; name
+
+Deletion of a name removes the binding of that name from the local or global
+namespace, depending on whether the name occurs in a :keyword:`global` statement
+in the same code block. If the name is unbound, a :exc:`NameError` exception
+will be raised.
+
+.. index:: pair: free; variable
+
+It is illegal to delete a name from the local namespace if it occurs as a free
+variable in a nested block.
+
+.. index:: pair: attribute; deletion
+
+Deletion of attribute references, subscriptions and slicings is passed to the
+primary object involved; deletion of a slicing is in general equivalent to
+assignment of an empty slice of the right type (but even this is determined by
+the sliced object).
+
+
+.. _return:
+
+The :keyword:`return` statement
+===============================
+
+.. index:: statement: return
+
+.. productionlist::
+ return_stmt: "return" [`expression_list`]
+
+.. index::
+ pair: function; definition
+ pair: class; definition
+
+:keyword:`return` may only occur syntactically nested in a function definition,
+not within a nested class definition.
+
+If an expression list is present, it is evaluated, else ``None`` is substituted.
+
+:keyword:`return` leaves the current function call with the expression list (or
+``None``) as return value.
+
+.. index:: keyword: finally
+
+When :keyword:`return` passes control out of a :keyword:`try` statement with a
+:keyword:`finally` clause, that :keyword:`finally` clause is executed before
+really leaving the function.
+
+In a generator function, the :keyword:`return` statement is not allowed to
+include an :token:`expression_list`. In that context, a bare :keyword:`return`
+indicates that the generator is done and will cause :exc:`StopIteration` to be
+raised.
+
+
+.. _yield:
+
+The :keyword:`yield` statement
+==============================
+
+.. index:: statement: yield
+
+.. productionlist::
+ yield_stmt: `yield_expression`
+
+.. index::
+ single: generator; function
+ single: generator; iterator
+ single: function; generator
+ exception: StopIteration
+
+The :keyword:`yield` statement is only used when defining a generator function,
+and is only used in the body of the generator function. Using a :keyword:`yield`
+statement in a function definition is sufficient to cause that definition to
+create a generator function instead of a normal function.
+
+When a generator function is called, it returns an iterator known as a generator
+iterator, or more commonly, a generator. The body of the generator function is
+executed by calling the generator's :meth:`__next__` method repeatedly until it
+raises an exception.
+
+When a :keyword:`yield` statement is executed, the state of the generator is
+frozen and the value of :token:`expression_list` is returned to
+:meth:`__next__`'s caller. By "frozen" we mean that all local state is
+retained, including the current bindings of local variables, the instruction
+pointer, and the internal evaluation stack: enough information is saved so that
+the next time :meth:`__next__` is invoked, the function can proceed exactly as
+if the :keyword:`yield` statement were just another external call.
+
+As of Python version 2.5, the :keyword:`yield` statement is now allowed in the
+:keyword:`try` clause of a :keyword:`try` ... :keyword:`finally` construct. If
+the generator is not resumed before it is finalized (by reaching a zero
+reference count or by being garbage collected), the generator-iterator's
+:meth:`close` method will be called, allowing any pending :keyword:`finally`
+clauses to execute.
+
+.. note::
+
+ In Python 2.2, the :keyword:`yield` statement is only allowed when the
+ ``generators`` feature has been enabled. It will always be enabled in Python
+ 2.3. This ``__future__`` import statement can be used to enable the feature::
+
+ from __future__ import generators
+
+
+.. seealso::
+
+ :pep:`0255` - Simple Generators
+ The proposal for adding generators and the :keyword:`yield` statement to Python.
+
+ :pep:`0342` - Coroutines via Enhanced Generators
+ The proposal that, among other generator enhancements, proposed allowing
+ :keyword:`yield` to appear inside a :keyword:`try` ... :keyword:`finally` block.
+
+
+.. _raise:
+
+The :keyword:`raise` statement
+==============================
+
+.. index:: statement: raise
+
+.. productionlist::
+ raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
+
+.. index::
+ single: exception
+ pair: raising; exception
+
+If no expressions are present, :keyword:`raise` re-raises the last exception
+that was active in the current scope. If no exception is active in the current
+scope, a :exc:`TypeError` exception is raised indicating that this is an error
+(if running under IDLE, a :exc:`Queue.Empty` exception is raised instead).
+
+Otherwise, :keyword:`raise` evaluates the expressions to get three objects,
+using ``None`` as the value of omitted expressions. The first two objects are
+used to determine the *type* and *value* of the exception.
+
+If the first object is an instance, the type of the exception is the class of
+the instance, the instance itself is the value, and the second object must be
+``None``.
+
+If the first object is a class, it becomes the type of the exception. The second
+object is used to determine the exception value: If it is an instance of the
+class, the instance becomes the exception value. If the second object is a
+tuple, it is used as the argument list for the class constructor; if it is
+``None``, an empty argument list is used, and any other object is treated as a
+single argument to the constructor. The instance so created by calling the
+constructor is used as the exception value.
+
+.. index:: object: traceback
+
+If a third object is present and not ``None``, it must be a traceback object
+(see section :ref:`types`), and it is substituted instead of the current
+location as the place where the exception occurred. If the third object is
+present and not a traceback object or ``None``, a :exc:`TypeError` exception is
+raised. The three-expression form of :keyword:`raise` is useful to re-raise an
+exception transparently in an except clause, but :keyword:`raise` with no
+expressions should be preferred if the exception to be re-raised was the most
+recently active exception in the current scope.
+
+Additional information on exceptions can be found in section :ref:`exceptions`,
+and information about handling exceptions is in section :ref:`try`.
+
+
+.. _break:
+
+The :keyword:`break` statement
+==============================
+
+.. index:: statement: break
+
+.. productionlist::
+ break_stmt: "break"
+
+.. index::
+ statement: for
+ statement: while
+ pair: loop; statement
+
+:keyword:`break` may only occur syntactically nested in a :keyword:`for` or
+:keyword:`while` loop, but not nested in a function or class definition within
+that loop.
+
+.. index:: keyword: else
+
+It terminates the nearest enclosing loop, skipping the optional :keyword:`else`
+clause if the loop has one.
+
+.. index:: pair: loop control; target
+
+If a :keyword:`for` loop is terminated by :keyword:`break`, the loop control
+target keeps its current value.
+
+.. index:: keyword: finally
+
+When :keyword:`break` passes control out of a :keyword:`try` statement with a
+:keyword:`finally` clause, that :keyword:`finally` clause is executed before
+really leaving the loop.
+
+
+.. _continue:
+
+The :keyword:`continue` statement
+=================================
+
+.. index:: statement: continue
+
+.. productionlist::
+ continue_stmt: "continue"
+
+.. index::
+ statement: for
+ statement: while
+ pair: loop; statement
+ keyword: finally
+
+:keyword:`continue` may only occur syntactically nested in a :keyword:`for` or
+:keyword:`while` loop, but not nested in a function or class definition or
+:keyword:`finally` statement within that loop. [#]_ It continues with the next
+cycle of the nearest enclosing loop.
+
+
+.. _import:
+
+The :keyword:`import` statement
+===============================
+
+.. index::
+ statement: import
+ single: module; importing
+ pair: name; binding
+ keyword: from
+
+.. productionlist::
+ import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )*
+ : | "from" `relative_module` "import" `identifier` ["as" `name`]
+ : ( "," `identifier` ["as" `name`] )*
+ : | "from" `relative_module` "import" "(" `identifier` ["as" `name`]
+ : ( "," `identifier` ["as" `name`] )* [","] ")"
+ : | "from" `module` "import" "*"
+ module: (`identifier` ".")* `identifier`
+ relative_module: "."* `module` | "."+
+ name: `identifier`
+
+Import statements are executed in two steps: (1) find a module, and initialize
+it if necessary; (2) define a name or names in the local namespace (of the scope
+where the :keyword:`import` statement occurs). The first form (without
+:keyword:`from`) repeats these steps for each identifier in the list. The form
+with :keyword:`from` performs step (1) once, and then performs step (2)
+repeatedly.
+
+In this context, to "initialize" a built-in or extension module means to call an
+initialization function that the module must provide for the purpose (in the
+reference implementation, the function's name is obtained by prepending string
+"init" to the module's name); to "initialize" a Python-coded module means to
+execute the module's body.
+
+.. index::
+ single: modules (in module sys)
+ single: sys.modules
+ pair: module; name
+ pair: built-in; module
+ pair: user-defined; module
+ module: sys
+ pair: filename; extension
+ triple: module; search; path
+
+The system maintains a table of modules that have been or are being initialized,
+indexed by module name. This table is accessible as ``sys.modules``. When a
+module name is found in this table, step (1) is finished. If not, a search for
+a module definition is started. When a module is found, it is loaded. Details
+of the module searching and loading process are implementation and platform
+specific. It generally involves searching for a "built-in" module with the
+given name and then searching a list of locations given as ``sys.path``.
+
+.. index::
+ pair: module; initialization
+ exception: ImportError
+ single: code block
+ exception: SyntaxError
+
+If a built-in module is found, its built-in initialization code is executed and
+step (1) is finished. If no matching file is found, :exc:`ImportError` is
+raised. If a file is found, it is parsed, yielding an executable code block. If
+a syntax error occurs, :exc:`SyntaxError` is raised. Otherwise, an empty module
+of the given name is created and inserted in the module table, and then the code
+block is executed in the context of this module. Exceptions during this
+execution terminate step (1).
+
+When step (1) finishes without raising an exception, step (2) can begin.
+
+The first form of :keyword:`import` statement binds the module name in the local
+namespace to the module object, and then goes on to import the next identifier,
+if any. If the module name is followed by :keyword:`as`, the name following
+:keyword:`as` is used as the local name for the module.
+
+.. index::
+ pair: name; binding
+ exception: ImportError
+
+The :keyword:`from` form does not bind the module name: it goes through the list
+of identifiers, looks each one of them up in the module found in step (1), and
+binds the name in the local namespace to the object thus found. As with the
+first form of :keyword:`import`, an alternate local name can be supplied by
+specifying ":keyword:`as` localname". If a name is not found,
+:exc:`ImportError` is raised. If the list of identifiers is replaced by a star
+(``'*'``), all public names defined in the module are bound in the local
+namespace of the :keyword:`import` statement..
+
+.. index:: single: __all__ (optional module attribute)
+
+The *public names* defined by a module are determined by checking the module's
+namespace for a variable named ``__all__``; if defined, it must be a sequence of
+strings which are names defined or imported by that module. The names given in
+``__all__`` are all considered public and are required to exist. If ``__all__``
+is not defined, the set of public names includes all names found in the module's
+namespace which do not begin with an underscore character (``'_'``).
+``__all__`` should contain the entire public API. It is intended to avoid
+accidentally exporting items that are not part of the API (such as library
+modules which were imported and used within the module).
+
+The :keyword:`from` form with ``*`` may only occur in a module scope. If the
+wild card form of import --- ``import *`` --- is used in a function and the
+function contains or is a nested block with free variables, the compiler will
+raise a :exc:`SyntaxError`.
+
+.. index::
+ keyword: from
+ statement: from
+
+.. index::
+ triple: hierarchical; module; names
+ single: packages
+ single: __init__.py
+
+**Hierarchical module names:** when the module names contains one or more dots,
+the module search path is carried out differently. The sequence of identifiers
+up to the last dot is used to find a "package"; the final identifier is then
+searched inside the package. A package is generally a subdirectory of a
+directory on ``sys.path`` that has a file :file:`__init__.py`. [XXX Can't be
+bothered to spell this out right now; see the URL
+http://www.python.org/doc/essays/packages.html for more details, also about how
+the module search works from inside a package.]
+
+.. %
+
+.. index:: builtin: __import__
+
+The built-in function :func:`__import__` is provided to support applications
+that determine which modules need to be loaded dynamically; refer to
+:ref:`built-in-funcs` for additional information.
+
+
+.. _future:
+
+Future statements
+-----------------
+
+.. index:: pair: future; statement
+
+A :dfn:`future statement` is a directive to the compiler that a particular
+module should be compiled using syntax or semantics that will be available in a
+specified future release of Python. The future statement is intended to ease
+migration to future versions of Python that introduce incompatible changes to
+the language. It allows use of the new features on a per-module basis before
+the release in which the feature becomes standard.
+
+.. productionlist:: *
+ future_statement: "from" "__future__" "import" feature ["as" name]
+ : ("," feature ["as" name])*
+ : | "from" "__future__" "import" "(" feature ["as" name]
+ : ("," feature ["as" name])* [","] ")"
+ feature: identifier
+ name: identifier
+
+A future statement must appear near the top of the module. The only lines that
+can appear before a future statement are:
+
+* the module docstring (if any),
+* comments,
+* blank lines, and
+* other future statements.
+
+The features recognized by Python 2.5 are ``absolute_import``, ``division``,
+``generators``, ``nested_scopes`` and ``with_statement``. ``generators`` and
+``nested_scopes`` are redundant in Python version 2.3 and above because they
+are always enabled.
+
+A future statement is recognized and treated specially at compile time: Changes
+to the semantics of core constructs are often implemented by generating
+different code. It may even be the case that a new feature introduces new
+incompatible syntax (such as a new reserved word), in which case the compiler
+may need to parse the module differently. Such decisions cannot be pushed off
+until runtime.
+
+For any given release, the compiler knows which feature names have been defined,
+and raises a compile-time error if a future statement contains a feature not
+known to it.
+
+The direct runtime semantics are the same as for any import statement: there is
+a standard module :mod:`__future__`, described later, and it will be imported in
+the usual way at the time the future statement is executed.
+
+The interesting runtime semantics depend on the specific feature enabled by the
+future statement.
+
+Note that there is nothing special about the statement::
+
+ import __future__ [as name]
+
+That is not a future statement; it's an ordinary import statement with no
+special semantics or syntax restrictions.
+
+Code compiled by calls to the builtin functions :func:`exec` and :func:`compile`
+that occur in a module :mod:`M` containing a future
+statement will, by default, use the new syntax or semantics associated with the
+future statement. This can, starting with Python 2.2 be controlled by optional
+arguments to :func:`compile` --- see the documentation of that function
+for details.
+
+A future statement typed at an interactive interpreter prompt will take effect
+for the rest of the interpreter session. If an interpreter is started with the
+:option:`-i` option, is passed a script name to execute, and the script includes
+a future statement, it will be in effect in the interactive session started
+after the script is executed.
+
+
+.. _global:
+
+The :keyword:`global` statement
+===============================
+
+.. index:: statement: global
+
+.. productionlist::
+ global_stmt: "global" `identifier` ("," `identifier`)*
+
+.. index:: triple: global; name; binding
+
+The :keyword:`global` statement is a declaration which holds for the entire
+current code block. It means that the listed identifiers are to be interpreted
+as globals. It would be impossible to assign to a global variable without
+:keyword:`global`, although free variables may refer to globals without being
+declared global.
+
+Names listed in a :keyword:`global` statement must not be used in the same code
+block textually preceding that :keyword:`global` statement.
+
+Names listed in a :keyword:`global` statement must not be defined as formal
+parameters or in a :keyword:`for` loop control target, :keyword:`class`
+definition, function definition, or :keyword:`import` statement.
+
+(The current implementation does not enforce the latter two restrictions, but
+programs should not abuse this freedom, as future implementations may enforce
+them or silently change the meaning of the program.)
+
+.. index::
+ builtin: exec
+ builtin: eval
+ builtin: compile
+
+**Programmer's note:** the :keyword:`global` is a directive to the parser. It
+applies only to code parsed at the same time as the :keyword:`global` statement.
+In particular, a :keyword:`global` statement contained in a string or code
+object supplied to the builtin :func:`exec` function does not affect the code
+block *containing* the function call, and code contained in such a string is
+unaffected by :keyword:`global` statements in the code containing the function
+call. The same applies to the :func:`eval` and :func:`compile` functions.
+
+.. rubric:: Footnotes
+
+.. [#] It may occur within an :keyword:`except` or :keyword:`else` clause. The
+ restriction on occurring in the :keyword:`try` clause is implementor's laziness
+ and will eventually be lifted.
+
diff --git a/Doc/reference/toplevel_components.rst b/Doc/reference/toplevel_components.rst
new file mode 100644
index 0000000..2149311
--- /dev/null
+++ b/Doc/reference/toplevel_components.rst
@@ -0,0 +1,123 @@
+
+.. _top-level:
+
+********************
+Top-level components
+********************
+
+.. index:: single: interpreter
+
+The Python interpreter can get its input from a number of sources: from a script
+passed to it as standard input or as program argument, typed in interactively,
+from a module source file, etc. This chapter gives the syntax used in these
+cases.
+
+
+.. _programs:
+
+Complete Python programs
+========================
+
+.. index:: single: program
+
+.. index::
+ module: sys
+ module: __main__
+ module: __builtin__
+
+While a language specification need not prescribe how the language interpreter
+is invoked, it is useful to have a notion of a complete Python program. A
+complete Python program is executed in a minimally initialized environment: all
+built-in and standard modules are available, but none have been initialized,
+except for :mod:`sys` (various system services), :mod:`__builtin__` (built-in
+functions, exceptions and ``None``) and :mod:`__main__`. The latter is used to
+provide the local and global namespace for execution of the complete program.
+
+The syntax for a complete Python program is that for file input, described in
+the next section.
+
+.. index::
+ single: interactive mode
+ module: __main__
+
+The interpreter may also be invoked in interactive mode; in this case, it does
+not read and execute a complete program but reads and executes one statement
+(possibly compound) at a time. The initial environment is identical to that of
+a complete program; each statement is executed in the namespace of
+:mod:`__main__`.
+
+.. index::
+ single: UNIX
+ single: command line
+ single: standard input
+
+Under Unix, a complete program can be passed to the interpreter in three forms:
+with the :option:`-c` *string* command line option, as a file passed as the
+first command line argument, or as standard input. If the file or standard input
+is a tty device, the interpreter enters interactive mode; otherwise, it executes
+the file as a complete program.
+
+
+.. _file-input:
+
+File input
+==========
+
+All input read from non-interactive files has the same form:
+
+.. productionlist::
+ file_input: (NEWLINE | `statement`)*
+
+This syntax is used in the following situations:
+
+* when parsing a complete Python program (from a file or from a string);
+
+* when parsing a module;
+
+* when parsing a string passed to the :func:`exec` function;
+
+
+.. _interactive:
+
+Interactive input
+=================
+
+Input in interactive mode is parsed using the following grammar:
+
+.. productionlist::
+ interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE
+
+Note that a (top-level) compound statement must be followed by a blank line in
+interactive mode; this is needed to help the parser detect the end of the input.
+
+
+.. _expression-input:
+
+Expression input
+================
+
+.. index:: single: input
+
+.. index:: builtin: eval
+
+There are two forms of expression input. Both ignore leading whitespace. The
+string argument to :func:`eval` must have the following form:
+
+.. productionlist::
+ eval_input: `expression_list` NEWLINE*
+
+.. index:: builtin: input
+
+The input line read by :func:`input` must have the following form:
+
+.. productionlist::
+ input_input: `expression_list` NEWLINE
+
+.. index::
+ object: file
+ single: input; raw
+ single: readline() (file method)
+
+Note: to read 'raw' input line without interpretation, you can use the the
+:meth:`readline` method of file objects, including ``sys.stdin``.
+