diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index e37618ad1a9..02ce783f5b7 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -76,7 +76,10 @@ on a separate line for clarity. The :keyword:`if` statement =========================== -.. index:: statement: if +.. index:: + statement: if + keyword: elif + keyword: else The :keyword:`if` statement is used for conditional execution: @@ -85,10 +88,6 @@ The :keyword:`if` statement is used for conditional execution: : ( "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 @@ -104,6 +103,7 @@ The :keyword:`while` statement .. index:: statement: while pair: loop; statement + keyword: else The :keyword:`while` statement is used for repeated execution as long as an expression is true: @@ -112,8 +112,6 @@ expression is true: 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 @@ -137,8 +135,10 @@ The :keyword:`for` statement .. index:: statement: for pair: loop; statement - -.. index:: object: sequence + keyword: in + keyword: else + pair: target; list + 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: @@ -147,11 +147,6 @@ The :keyword:`for` statement is used to iterate over the elements of a sequence 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 @@ -214,7 +209,10 @@ effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list The :keyword:`try` statement ============================ -.. index:: statement: try +.. index:: + statement: try + keyword: except + keyword: finally The :keyword:`try` statement specifies exception handlers and/or cleanup code for a group of statements: @@ -233,8 +231,6 @@ for a group of statements: :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 @@ -376,12 +372,8 @@ The execution of the :keyword:`with` statement proceeds as follows: .. 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 - + ``with_statement`` feature has been enabled. It is always enabled in + Python 2.6. .. seealso:: @@ -397,10 +389,10 @@ Function definitions ==================== .. index:: - pair: function; definition statement: def - -.. index:: + pair: function; definition + pair: function; name + pair: name; binding object: user-defined function object: function @@ -421,10 +413,6 @@ A function definition defines a user-defined function object (see section parameter: `identifier` | "(" `sublist` ")" 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 @@ -505,10 +493,13 @@ Class definitions ================= .. index:: - pair: class; definition + object: class statement: class - -.. index:: object: class + pair: class; definition + pair: class; name + pair: name; binding + pair: execution; frame + single: inheritance A class definition defines a class object (see section :ref:`types`): @@ -517,12 +508,6 @@ A class definition defines a class object (see section :ref:`types`): 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 @@ -535,13 +520,13 @@ 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 :term:`new-style class`\es, -descriptors can be used to create instance variables with different +variables; they are shared by all instances. To create instance variables, they +can be set in a method with ``self.name = value``. Both class and instance +variables are accessible through the notation "``self.name``", and an instance +variable hides a class variable with the same name when accessed in this way. +Class variables can be used as defaults for instance variables, but using +mutable values there can lead to unexpected results. For :term:`new-style +class`\es, descriptors can be used to create instance variables with different implementation details. .. rubric:: Footnotes @@ -552,4 +537,3 @@ implementation details. .. [#] 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 index 6fc1f8eb44d..7ea6ca757a9 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1097,16 +1097,15 @@ 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. +please see http://www.python.org/doc/newstyle/ for more information. .. index:: - single: class - single: class - single: class + single: class; new-style + single: class; classic + single: class; old-style 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: @@ -2242,7 +2241,7 @@ For more information on context managers, see :ref:`typecontextmanager`. 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. + http://www.python.org/doc/newstyle/. .. [#] This, and other statements, are only roughly true for instances of new-style classes. diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 513543bd70b..07671701146 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -34,7 +34,9 @@ simple statements is: Expression statements ===================== -.. index:: pair: expression; statement +.. index:: + pair: expression; statement + pair: expression; list Expression statements are used (mostly interactively) to compute and write a value, or (usually) to call a procedure (a function that returns no meaningful @@ -45,8 +47,6 @@ 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). @@ -311,13 +311,13 @@ is determined when the interpreter starts. The :keyword:`pass` statement ============================= -.. index:: statement: pass +.. index:: + statement: pass + pair: null; operation .. 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:: @@ -332,15 +332,14 @@ code needs to be executed, for example:: The :keyword:`del` statement ============================ -.. index:: statement: del +.. index:: + statement: del + pair: deletion; target + triple: deletion; target; list .. 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. @@ -399,8 +398,6 @@ functional to write an empty string to standard output for this reason.) .. index:: single: output pair: writing; values - -.. index:: pair: trailing; comma pair: newline; suppression @@ -434,15 +431,14 @@ then ``sys.stdout`` is used as the file for output. The :keyword:`return` statement =============================== -.. index:: statement: return +.. index:: + statement: return + pair: function; definition + pair: class; definition .. 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. @@ -468,17 +464,16 @@ raised. The :keyword:`yield` statement ============================== -.. index:: statement: yield - -.. productionlist:: - yield_stmt: `yield_expression` - .. index:: + statement: yield single: generator; function single: generator; iterator single: function; generator exception: StopIteration +.. productionlist:: + yield_stmt: `yield_expression` + 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 @@ -528,15 +523,14 @@ clauses to execute. The :keyword:`raise` statement ============================== -.. index:: statement: raise +.. index:: + statement: raise + single: exception + pair: raising; exception .. 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 @@ -578,16 +572,15 @@ and information about handling exceptions is in section :ref:`try`. The :keyword:`break` statement ============================== -.. index:: statement: break - -.. productionlist:: - break_stmt: "break" - .. index:: + statement: break statement: for statement: while pair: loop; statement +.. productionlist:: + break_stmt: "break" + :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. @@ -614,17 +607,16 @@ really leaving the loop. The :keyword:`continue` statement ================================= -.. index:: statement: continue - -.. productionlist:: - continue_stmt: "continue" - .. index:: + statement: continue statement: for statement: while pair: loop; statement keyword: finally +.. productionlist:: + continue_stmt: "continue" + :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 @@ -739,8 +731,6 @@ raise a :exc:`SyntaxError`. .. index:: keyword: from statement: from - -.. index:: triple: hierarchical; module; names single: packages single: __init__.py @@ -840,13 +830,13 @@ after the script is executed. The :keyword:`global` statement =============================== -.. index:: statement: global +.. index:: + statement: global + triple: global; name; binding .. 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 @@ -908,7 +898,7 @@ variables. If two expressions are given, they are used for the global and local variables, respectively. If provided, *locals* can be any mapping object. .. versionchanged:: 2.4 - formerly *locals* was required to be a dictionary. + Formerly, *locals* was required to be a dictionary. .. index:: single: __builtins__