[Python-checkins] r59743 - python/trunk/Doc/reference/compound_stmts.rst python/trunk/Doc/reference/datamodel.rst python/trunk/Doc/reference/simple_stmts.rst
georg.brandl
python-checkins at python.org
Sat Jan 5 20:29:45 CET 2008
Author: georg.brandl
Date: Sat Jan 5 20:29:45 2008
New Revision: 59743
Modified:
python/trunk/Doc/reference/compound_stmts.rst
python/trunk/Doc/reference/datamodel.rst
python/trunk/Doc/reference/simple_stmts.rst
Log:
Simplify index entries; fix #1712.
Modified: python/trunk/Doc/reference/compound_stmts.rst
==============================================================================
--- python/trunk/Doc/reference/compound_stmts.rst (original)
+++ python/trunk/Doc/reference/compound_stmts.rst Sat Jan 5 20:29:45 2008
@@ -76,7 +76,10 @@
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 @@
: ( "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 @@
.. 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 @@
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 @@
.. 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 @@
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 @@
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 @@
: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 @@
.. 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 @@
====================
.. 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 @@
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 @@
=================
.. 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 @@
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 @@
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 @@
.. [#] 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.
-
Modified: python/trunk/Doc/reference/datamodel.rst
==============================================================================
--- python/trunk/Doc/reference/datamodel.rst (original)
+++ python/trunk/Doc/reference/datamodel.rst Sat Jan 5 20:29:45 2008
@@ -1097,16 +1097,15 @@
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 @@
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.
Modified: python/trunk/Doc/reference/simple_stmts.rst
==============================================================================
--- python/trunk/Doc/reference/simple_stmts.rst (original)
+++ python/trunk/Doc/reference/simple_stmts.rst Sat Jan 5 20:29:45 2008
@@ -34,7 +34,9 @@
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 @@
.. 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 @@
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 @@
The :keyword:`del` statement
============================
-.. index:: statement: del
-
-.. productionlist::
- del_stmt: "del" `target_list`
-
.. index::
+ statement: del
pair: deletion; target
triple: deletion; target; list
+.. productionlist::
+ del_stmt: "del" `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 @@
.. index::
single: output
pair: writing; values
-
-.. index::
pair: trailing; comma
pair: newline; suppression
@@ -434,15 +431,14 @@
The :keyword:`return` statement
===============================
-.. index:: statement: return
-
-.. productionlist::
- return_stmt: "return" [`expression_list`]
-
.. index::
+ statement: return
pair: function; definition
pair: class; definition
+.. productionlist::
+ return_stmt: "return" [`expression_list`]
+
:keyword:`return` may only occur syntactically nested in a function definition,
not within a nested class definition.
@@ -468,17 +464,16 @@
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 @@
The :keyword:`raise` statement
==============================
-.. index:: statement: raise
-
-.. productionlist::
- raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
-
.. index::
+ statement: raise
single: exception
pair: raising; exception
+.. productionlist::
+ raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
+
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 @@
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 @@
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 @@
.. index::
keyword: from
statement: from
-
-.. index::
triple: hierarchical; module; names
single: packages
single: __init__.py
@@ -840,13 +830,13 @@
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, 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__
More information about the Python-checkins
mailing list