Changeset 388 for python/vendor/current/Doc/reference

python/vendor/current/Doc/reference/compound_stmts.rst

-              r2
+              r388
 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, a tuple containing an item compatible with the exception, or, in the
+(deprecated) case of string exceptions, is the raised string itself (note that
+the object identities must match, i.e. it must be the same string object, not
+just a string with the same value).
+object, or a tuple containing an item compatible with the exception.
 If no except clause matches the exception, the search for an exception handler
 …
 :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.
+saved exception is discarded::
+    def f():
+        try:
+/0
+        finally:
+            return 42
+    >>> f()
+The exception information is not available to the program during execution of
+the :keyword:`finally` clause.
 .. index::
 …
 .. 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.
+   with_stmt: "with" with_item ("," with_item)* ":" `suite`
+   with_item: `expression` ["as" `target`]
+The execution of the :keyword:`with` statement with one "item" proceeds as follows:
+#. The context expression (the expression given in the :token:`with_item`) is
+   evaluated to obtain a context manager.
+#. The context manager's :meth:`__exit__` is loaded for later use.
 #. The context manager's :meth:`__enter__` method is invoked.
 …
       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.
+      same as an error occurring within the suite would be. See step 6 below.
 #. The suite is executed.
 …
    for the kind of exit that was taken.
+With more than one item, the context managers are processed as if multiple
+:keyword:`with` statements were nested::
+   with A() as a, B() as b:
+       suite
+is equivalent to ::
+   with A() as a:
+       with B() as b:
+           suite
 .. note::
 …
    Python 2.6.
+.. versionchanged:: 2.7
+   Support for multiple context expressions.
 .. seealso::
 …
       statement.
+.. index::
+   single: parameter; function definition
 .. _function:
 …
    dotted_name: `identifier` ("." `identifier`)*
    parameter_list: (`defparameter` ",")*
                  : (  "*" `identifier` [, "**" `identifier`]
+                 : (  "*" `identifier` ["," "**" `identifier`]
                  : | "**" `identifier`
                  : | `defparameter` [","] )
 …
    func = f1(arg)(f2(func))
+.. index:: triple: default; parameter; value
+When one or more top-level 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
+.. index::
+   triple: default; parameter; value
+   single: argument; function definition
+When one or more top-level :term:`parameters <parameter>` have the form
+*parameter* ``=`` *expression*, the function is said to have "default parameter
+values."  For a parameter with a default value, the corresponding
+:term:`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 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 defined, and that the 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
 …
 receiving any excess keyword arguments, defaulting to a new empty dictionary.
 .. index:: pair: lambda; form
+.. index:: pair: lambda; expression
 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
+name), for immediate use in expressions.  This uses lambda expressions, described in
+section :ref:`lambda`.  Note that the lambda expression 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
+defined by a lambda expression.  The ":keyword:`def`" form is actually more powerful
 since it allows the execution of multiple statements.
 …
 .. rubric:: Footnotes
+.. [#] The exception is propagated to the invocation stack only if there is no
+   :keyword:`finally` clause that negates the exception.
+.. [#] The exception is propagated to the invocation stack unless
+   there is a :keyword:`finally` clause which happens to raise another
+   exception. That new exception causes the old one to be lost.
 .. [#] Currently, control "flows off the end" except in the case of an exception or the

python/vendor/current/Doc/reference/datamodel.rst

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

python/vendor/current/Doc/reference/executionmodel.rst

-              r2
+              r388
 .. index:: pair: restricted; execution
 The built-in namespace associated with the execution of a code block is actually
+The builtins 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
 …
    Users should not touch ``__builtins__``; it is strictly an implementation
    detail.  Users wanting to override values in the built-in namespace should
+   detail.  Users wanting to override values in the builtins namespace should
    :keyword:`import` the :mod:`__builtin__` (no 's') module and modify its
    attributes appropriately.
 …
 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.
+The :keyword:`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.

python/vendor/current/Doc/reference/expressions.rst

-              r2
+              r388
    atom: `identifier` | `literal` | `enclosure`
    enclosure: `parenth_form` | `list_display`
             : | `generator_expression` | `dict_display`
+            : | `generator_expression` | `dict_display` | `set_display`
             : | `string_conversion` | `yield_atom`
 …
 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.
+them.  The transformation inserts the class name, with leading underscores
+removed and a single underscore inserted, in front of the 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.
 …
    list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`]
    old_expression_list: `old_expression` [("," `old_expression`)+ [","]]
+   old_expression: `or_test` | `old_lambda_expr`
    list_iter: `list_for` | `list_if`
    list_if: "if" `old_expression` [`list_iter`]
 …
+.. _comprehensions:
+Displays for sets and dictionaries
+----------------------------------
+For constructing a set or a dictionary Python provides special syntax
+called "displays", each of them in two flavors:
+* either the container contents are listed explicitly, or
+* they are computed via a set of looping and filtering instructions, called a
+  :dfn:`comprehension`.
+Common syntax elements for comprehensions are:
+.. productionlist::
+   comprehension: `expression` `comp_for`
+   comp_for: "for" `target_list` "in" `or_test` [`comp_iter`]
+   comp_iter: `comp_for` | `comp_if`
+   comp_if: "if" `expression_nocond` [`comp_iter`]
+The comprehension 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 container 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 an element
+each time the innermost block is reached.
+Note that the comprehension is executed in a separate scope, so names assigned
+to in the target list don't "leak" in the enclosing scope.
 .. _genexpr:
 …
 .. index:: pair: generator; expression
+           object: generator
 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 in a separate
+scope when the :meth:`next` method is called for the generator object (in the
+same fashion as for normal generators).  However, the :keyword:`in` expression
+of the leftmost :keyword:`for` clause is immediately evaluated in the current
+scope so that an error produced by it can be seen before any other possible
+   generator_expression: "(" `expression` `comp_for` ")"
+A generator expression yields a new generator object.  Its syntax is the same as
+for comprehensions, except that it is enclosed in parentheses instead of
+brackets or curly braces.
+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 an error produced by it can be seen before any other possible
 error in the code that handles the generator expression.  Subsequent
 :keyword:`for` and :keyword:`if` 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
+: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:
 …
 .. index:: pair: dictionary; display
+.. index::
+   single: key
+   single: datum
+   single: key/datum pair
+           key, datum, key/datum pair
+           object: dictionary
 A dictionary display is a possibly empty series of key/datum pairs enclosed in
 …
 .. productionlist::
    dict_display: "{" [`key_datum_list`] "}"
+   dict_display: "{" [`key_datum_list` | `dict_comprehension`] "}"
    key_datum_list: `key_datum` ("," `key_datum`)* [","]
    key_datum: `expression` ":" `expression`
+.. index:: object: dictionary
+   dict_comprehension: `expression` ":" `expression` `comp_for`
 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.
+If a comma-separated sequence of key/datum pairs is given, they 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.  This means
+that you can specify the same key multiple times in the key/datum list, and the
+final dictionary's value for that key will be the last one given.
+A dict comprehension, in contrast to list and set comprehensions, needs two
+expressions separated with a colon followed by the usual "for" and "if" clauses.
+When the comprehension is run, the resulting key and value elements are inserted
+in the new dictionary in the order they are produced.
 .. index:: pair: immutable; object
+           hashable
 Restrictions on the types of the key values are listed earlier in section
 …
+.. _set:
+Set displays
+------------
+.. index:: pair: set; display
+           object: set
+A set display is denoted by curly braces and distinguishable from dictionary
+displays by the lack of colons separating keys and values:
+.. productionlist::
+   set_display: "{" (`expression_list` | `comprehension`) "}"
+A set display yields a new mutable set object, the contents being specified by
+either a sequence of expressions or a comprehension.  When a comma-separated
+list of expressions is supplied, its elements are evaluated from left to right
+and added to the set object.  When a comprehension is supplied, the set is
+constructed from the elements resulting from the comprehension.
+An empty set cannot be constructed with ``{}``; this literal constructs an empty
+dictionary.
 .. _string-conversions:
 …
 .. productionlist::
    string_conversion: "'" `expression_list` "'"
+   string_conversion: "`" `expression_list` "`"
 A string conversion evaluates the contained expression list and converts the
 …
 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.
+transferred to the generator's caller.
 .. index:: object: generator
+The following generator's methods can be used to control the execution of a
+generator function:
+Generator-iterator methods
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+This subsection describes the methods of a generator iterator.  They can
+be used to control the execution of a generator function.
+Note that calling any of the generator methods below when the generator
+is already executing raises a :exc:`ValueError` exception.
 .. index:: exception: StopIteration
+.. class:: generator
 …
    raised.
+.. class:: .
 .. method:: generator.send(value)
 …
 that is an expression is that expression.  The conversion of an ellipsis slice
 item is the built-in ``Ellipsis`` object.  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.
+slice object (see section :ref:`types`) whose :attr:`~slice.start`,
+:attr:`~slice.stop` and :attr:`~slice.step` attributes are the values of the
+expressions given as lower bound, upper bound and stride, respectively,
+substituting ``None`` for missing expressions.
+.. index::
+   object: callable
+   single: call
+   single: argument; call semantics
 .. _calls:
 …
 -----
+.. index:: single: call
+.. index:: object: callable
+A call calls a callable object (e.g., a function) with a possibly empty series
+of arguments:
+A call calls a callable object (e.g., a :term:`function`) with a possibly empty
+series of :term:`arguments <argument>`:
 .. productionlist::
 …
 does not affect the semantics.
+.. index::
+   single: parameter; call 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
 …
 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.
+for the syntax of formal :term:`parameter` lists.
 If keyword arguments are present, they are first converted to positional
 …
    do not have names, even if they are 'named' for the purpose of documentation,
    and which therefore cannot be supplied by keyword.  In CPython, this is the
    case for functions implemented in C that use :cfunc:`PyArg_ParseTuple` to
+   case for functions implemented in C that use :c:func:`PyArg_ParseTuple` to
    parse their arguments.
 …
 there were no excess keyword arguments.
+.. index::
+   single: *; in function calls
 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 positional 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*.
+evaluate to an iterable.  Elements from this iterable are treated as if they
+were additional positional arguments; if there are positional 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 may appear
 …
 used in the same call, so in practice this confusion does not arise.
+.. index::
+   single: **; in function calls
 If the syntax ``**expression`` appears in the function call, ``expression`` must
 evaluate to a mapping, the contents of which are treated as additional keyword
 …
 counts raise a :exc:`ValueError` exception.
+.. note::
+   In the current implementation, the right-hand operand is required
+   to be at most :attr:`sys.maxsize`.  If the right-hand operand is larger than
+   :attr:`sys.maxsize` an :exc:`OverflowError` exception is raised.
 .. _bitwise:
 …
 .. _comparisons:
 .. _is:
 .. _isnot:
+.. _is not:
 .. _in:
 .. _notin:
+.. _not in:
 Comparisons
 …
    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`]
+.. productionlist::
    or_test: `and_test` | `or_test` "or" `and_test`
    and_test: `not_test` | `and_test` "and" `not_test`
 …
 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
 …
+Conditional Expressions
+=======================
+.. versionadded:: 2.5
+.. index::
+   pair: conditional; expression
+   pair: ternary; operator
+.. productionlist::
+   conditional_expression: `or_test` ["if" `or_test` "else" `expression`]
+   expression: `conditional_expression` | `lambda_expr`
+Conditional expressions (sometimes called a "ternary operator") have the lowest
+priority of all Python operations.
+The expression ``x if C else y`` first evaluates the condition, *C* (*not* *x*);
+if *C* is true, *x* is evaluated and its value is returned; otherwise, *y* is
+evaluated and its value is returned.
+See :pep:`308` for more details about conditional expressions.
 .. _lambdas:
 .. _lambda:
 …
 .. 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
+   lambda_expr: "lambda" [`parameter_list`]: `expression`
+   old_lambda_expr: "lambda" [`parameter_list`]: `old_expression`
+Lambda expressions (sometimes called lambda forms) 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
 …
 See section :ref:`function` for the syntax of parameter lists.  Note that
 functions created with lambda forms cannot contain statements.
+functions created with lambda expressions cannot contain statements.
 …
 .. _operator-summary:
+Summary
 =======
+Operator precedence
+===================
 .. index:: pair: operator; precedence
 …
 | :keyword:`lambda`                             | Lambda expression                   |
 +-----------------------------------------------+-------------------------------------+
+| :keyword:`if` -- :keyword:`else`              | Conditional expression              |
++-----------------------------------------------+-------------------------------------+
 | :keyword:`or`                                 | Boolean OR                          |
 +-----------------------------------------------+-------------------------------------+
 | :keyword:`and`                                | Boolean AND                         |
 +-----------------------------------------------+-------------------------------------+
 | :keyword:`not` *x*                            | Boolean NOT                         |
 +-----------------------------------------------+-------------------------------------+
 | :keyword:`in`, :keyword:`not` :keyword:`in`,  | Comparisons, including membership   |
 | :keyword:`is`, :keyword:`is not`, ``<``,      | tests and identity tests,           |
+| :keyword:`not` ``x``                          | Boolean NOT                         |
++-----------------------------------------------+-------------------------------------+
+| :keyword:`in`, :keyword:`not in`,             | Comparisons, including membership   |
+| :keyword:`is`, :keyword:`is not`, ``<``,      | tests and identity tests            |
 | ``<=``, ``>``, ``>=``, ``<>``, ``!=``, ``==`` |                                     |
 +-----------------------------------------------+-------------------------------------+
 …
 +-----------------------------------------------+-------------------------------------+
 | ``*``, ``/``, ``//``, ``%``                   | Multiplication, division, remainder |
+|                                               | [#]_                                |
 +-----------------------------------------------+-------------------------------------+
 | ``+x``, ``-x``, ``~x``                        | Positive, negative, bitwise NOT     |
 …
 | ``(expressions...)``,                         | Binding or tuple display,           |
 | ``[expressions...]``,                         | list display,                       |
 | ``{key:datum...}``,                           | dictionary display,                 |
+| ``{key: value...}``,                          | dictionary display,                 |
 | ```expressions...```                          | string conversion                   |
 +-----------------------------------------------+-------------------------------------+
 …
 .. [#] In Python 2.3 and later releases, 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 in Python 3.0
+   behavior is deprecated, and relying on it will not work in Python 3.
 .. [#] While ``abs(x%y) < abs(y)`` is true mathematically, for floats it may not be
 …
    a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 %
 e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 +
 e100``, 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
+e100``, which is numerically exactly equal to ``1e100``.  The function
+   :func:`math.fmod` 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.
 …
    strings ``u"\u00C7"`` and ``u"\u0043\u0327"`` compare differently,
    even though they both represent the same unicode character (LATIN
    CAPTITAL LETTER C WITH CEDILLA). To compare strings in a human
+   CAPITAL LETTER C WITH CEDILLA). To compare strings in a human
    recognizable way, compare using :func:`unicodedata.normalize`.
 …
    methods, or constants.  Check their documentation for more info.
+.. [#] The ``%`` operator is also used for string formatting; the same
+   precedence applies.
 .. [#] The power operator ``**`` binds less tightly than an arithmetic or
    bitwise unary operator on its right, that is, ``2**-1`` is ``0.5``.

python/vendor/current/Doc/reference/index.rst

-              r2
+              r388
   The Python Language Reference
 #################################
-:Release: |version|
-:Date: |today|
 This reference manual describes the syntax and "core semantics" of the

python/vendor/current/Doc/reference/introduction.rst

-              r2
+              r388
    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://www.ironpython.com/>`_.
+   more information, see `the IronPython website <http://www.ironpython.net/>`_.
 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/>`_.
+   An implementation of Python written completely in Python. It supports several
+   advanced features not found in other implementations like stackless support
+   and a Just in Time compiler. 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://pypy.org/>`_.
 Each of these implementations varies in some way from the language as documented

python/vendor/current/Doc/reference/lexical_analysis.rst

-              r2
+              r388
 .. 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.
+   Using :keyword:`as` and :keyword:`with` as identifiers triggers a warning.  To
+   use them as keywords, enable the ``with_statement`` future feature .
+.. versionchanged:: 2.6
+    :keyword:`as` and :keyword:`with` are full keywords.
 …
 ``__*__``
+   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`.
+   System-defined names. These names are defined by the interpreter and its
+   implementation (including the standard library).  Current system names are
+   discussed in the :ref:`specialnames` section and elsewhere.  More will likely
+   be defined in future versions of Python.  *Any* use of ``__*__`` names, in
+   any context, that does not follow explicitly documented use, is subject to
+   breakage without warning.
 ``__*``
 …
    stringliteral: [`stringprefix`](`shortstring` | `longstring`)
    stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR"
+               : | "b" | "B" | "br" | "Br" | "bR" | "BR"
    shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"'
    longstring: "'''" `longstringitem`* "'''"
 …
 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'``.
+A prefix of ``'b'`` or ``'B'`` is ignored in Python 2; it indicates that the
+literal should become a bytes literal in Python 3 (e.g. when code is
+automatically converted with 2to3).  A ``'u'`` or ``'b'`` prefix may be followed
+by an ``'r'`` prefix.
 In triple-quoted strings, unescaped newlines and quotes are allowed (and are
 …
    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.
+   compiled to use 16-bit code units (the default).
 (3)

python/vendor/current/Doc/reference/simple_stmts.rst

-              r2
+              r388
   iterable 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.
 …
 Deletion is recursively defined very similar to the way assignment is defined.
 Rather that spelling it out in full details, here are some hints.
+Rather than spelling it out in full details, here are some hints.
 Deletion of a target list recursively deletes each target, from left to right.
 …
 clauses to execute.
+For full details of :keyword:`yield` semantics, refer to the :ref:`yieldexpr`
+section.
 .. note::
 …
 :attr:`__path__` attribute from the parent package (everything up to the last
 dot in the name of the module being imported). If a finder can find the module
 it returns a :term:`loader` (discussed later) or returns :keyword:`None`.
+it returns a :term:`loader` (discussed later) or returns ``None``.
 .. index::
 …
 :exc:`ImportError`. If a finder is returned then it is cached in
 :data:`sys.path_importer_cache` and then used for that path entry. If no finder
 can be found but the path exists then a value of :keyword:`None` is
+can be found but the path exists then a value of ``None`` is
 stored in :data:`sys.path_importer_cache` to signify that an implicit,
 file-based finder that handles modules stored as individual files should be
 used for that path. If the path does not exist then a finder which always
 returns :keyword:`None` is placed in the cache for the path.
+returns ``None`` is placed in the cache for the path.
 .. index::
 …
 So if you execute ``from . import mod`` from a module in the ``pkg`` package
 then you will end up importing ``pkg.mod``. If you execute ``from ..subpkg2
 imprt mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``.
+import mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``.
 The specification for relative imports is contained within :pep:`328`.
+.. 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.
+:func:`importlib.import_module` is provided to support applications that
+determine which modules need to be loaded dynamically.
 …
 This statement supports dynamic execution of Python code.  The first expression
+should evaluate to either a string, an open file object, or a code object.  If
+it is a string, the string is parsed as a suite of Python statements which is
+then executed (unless a syntax error occurs). [#]_  If it is an open file, the file
+is parsed until EOF and executed.  If it is a code object, it is simply
+executed.  In all cases, the code that's executed is expected to be valid as
+file input (see section :ref:`file-input`).  Be aware that the
+should evaluate to either a Unicode string, a *Latin-1* encoded string, an open
+file object, a code object, or a tuple.  If it is a string, the string is parsed
+as a suite of Python statements which is then executed (unless a syntax error
+occurs). [#]_ If it is an open file, the file is parsed until EOF and executed.
+If it is a code object, it is simply executed.  For the interpretation of a
+tuple, see below.  In all cases, the code that's executed is expected to be
+valid as file input (see section :ref:`file-input`).  Be aware that the
 :keyword:`return` and :keyword:`yield` statements may not be used outside of
 function definitions even within the context of code passed to the
 …
 In all cases, if the optional parts are omitted, the code is executed in the
 current scope.  If only the first expression after :keyword:`in` is specified,
+current scope.  If only the first expression after ``in`` is specified,
 it should be a dictionary, which will be used for both the global and the local
 variables.  If two expressions are given, they are used for the global and local
 variables, respectively. If provided, *locals* can be any mapping object.
+Remember that at module level, globals and locals are the same dictionary. If
+two separate objects are given as *globals* and *locals*, the code will be
+executed as if it were embedded in a class definition.
+The first expression may also be a tuple of length 2 or 3.  In this case, the
+optional parts must be omitted.  The form ``exec(expr, globals)`` is equivalent
+to ``exec expr in globals``, while the form ``exec(expr, globals, locals)`` is
+equivalent to ``exec expr in globals, locals``.  The tuple form of ``exec``
+provides compatibility with Python 3, where ``exec`` is a function rather than
+a statement.
 .. versionchanged:: 2.4
 …
 .. [#] Note that the parser only accepts the Unix-style end of line convention.
        If you are reading the code from a file, make sure to use universal
        newline mode to convert Windows or Mac-style newlines.
+       If you are reading the code from a file, make sure to use
+       :term:`universal newlines` mode to convert Windows or Mac-style newlines.

Context Navigation

Legend:

python/vendor/current/Doc/reference/compound_stmts.rst

python/vendor/current/Doc/reference/datamodel.rst

python/vendor/current/Doc/reference/executionmodel.rst

python/vendor/current/Doc/reference/expressions.rst

python/vendor/current/Doc/reference/index.rst

python/vendor/current/Doc/reference/introduction.rst

python/vendor/current/Doc/reference/lexical_analysis.rst

python/vendor/current/Doc/reference/simple_stmts.rst

Download in other formats: