Merged revisions…

Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r70642 | georg.brandl | 2009-03-28 01:48:48 +0100 (Sa, 28 Mär 2009) | 1 line

  Fix typo.
........
  r70648 | georg.brandl | 2009-03-28 20:10:37 +0100 (Sa, 28 Mär 2009) | 1 line

  #5324: document __subclasses__().
........
  r70656 | georg.brandl | 2009-03-28 20:33:33 +0100 (Sa, 28 Mär 2009) | 2 lines

  Add a script to fixup rst files if the pre-commit hook rejects them.
........
  r70661 | georg.brandl | 2009-03-28 20:57:36 +0100 (Sa, 28 Mär 2009) | 2 lines

  Add section numbering to some of the larger subdocuments.
........
  r70765 | georg.brandl | 2009-03-31 00:09:34 +0200 (Di, 31 Mär 2009) | 1 line

  #5199: make warning about vars() assignment more visible.
........
  r70773 | georg.brandl | 2009-03-31 00:43:00 +0200 (Di, 31 Mär 2009) | 1 line

  #5039: make it clear that the impl. note refers to CPython.
........
  r70789 | georg.brandl | 2009-03-31 03:25:15 +0200 (Di, 31 Mär 2009) | 1 line

  Fix a wrong struct field assignment (docstring as closure).
........
  r70824 | georg.brandl | 2009-03-31 17:43:20 +0200 (Di, 31 Mär 2009) | 1 line

  #5519: remove reference to Kodos, which seems dead.
........
  r70825 | georg.brandl | 2009-03-31 17:46:30 +0200 (Di, 31 Mär 2009) | 1 line

  #5566: fix versionadded from PyLong ssize_t functions.
........
  r70828 | georg.brandl | 2009-03-31 17:50:16 +0200 (Di, 31 Mär 2009) | 1 line

  #5581: fget argument of abstractproperty is optional as well.
........
  r70830 | georg.brandl | 2009-03-31 18:11:45 +0200 (Di, 31 Mär 2009) | 1 line

  #5529: backport new docs of import semantics written by Brett to 2.x.
........
  r70832 | georg.brandl | 2009-03-31 18:31:11 +0200 (Di, 31 Mär 2009) | 1 line

  #1386675: specify WindowsError as the exception, because it has a winerror attribute that EnvironmentError doesnt have.
........
  r70836 | georg.brandl | 2009-03-31 18:50:25 +0200 (Di, 31 Mär 2009) | 1 line

  #5417: replace references to undocumented functions by ones to documented functions.
........
  r70838 | georg.brandl | 2009-03-31 18:54:38 +0200 (Di, 31 Mär 2009) | 1 line

  #992207: document that the parser only accepts \\n newlines.
........
  r70842 | georg.brandl | 2009-03-31 19:13:06 +0200 (Di, 31 Mär 2009) | 1 line

  #970783: document PyObject_Generic[GS]etAttr.
........
  r70851 | georg.brandl | 2009-03-31 20:26:55 +0200 (Di, 31 Mär 2009) | 1 line

  #837577: note cryptic return value of spawn*e on invalid env dicts.
........
  r70855 | georg.brandl | 2009-03-31 20:30:37 +0200 (Di, 31 Mär 2009) | 1 line

  #5245: note that PyRun_SimpleString doesnt return on SystemExit.
........
  r70857 | georg.brandl | 2009-03-31 20:33:10 +0200 (Di, 31 Mär 2009) | 1 line

  #5227: note that Py_Main doesnt return on SystemExit.
........
  r70858 | georg.brandl | 2009-03-31 20:38:56 +0200 (Di, 31 Mär 2009) | 1 line

  #5241: document missing U in regex howto.
........

Doc/c-api/long.rst

@@ -54,7 +54,7 @@ Long Integer Objects
    Return a new :ctype:`PyLongObject` object from a C :ctype:`Py_ssize_t`, or
    *NULL* on failure.
 
-   .. versionadded:: 2.5
+   .. versionadded:: 2.6
 
 
 .. cfunction:: PyObject* PyLong_FromSize_t(size_t v)
@@ -62,7 +62,7 @@ Long Integer Objects
    Return a new :ctype:`PyLongObject` object from a C :ctype:`size_t`, or
    *NULL* on failure.
 
-   .. versionadded:: 2.5
+   .. versionadded:: 2.6
 
 
 .. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
@@ -139,7 +139,7 @@ Long Integer Objects
    *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised
    and ``-1`` will be returned.
 
-   .. versionadded:: 2.5
+   .. versionadded:: 2.6
 
 
 .. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

Doc/c-api/object.rst

@@ -42,6 +42,16 @@ Object Protocol
    expression ``o.attr_name``.
 
 
+.. cfunction:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
+
+   Generic attribute getter function that is meant to be put into a type
+   object's ``tp_getattro`` slot.  It looks for a descriptor in the dictionary
+   of classes in the object's MRO as well as an attribute in the object's
+   :attr:`__dict__` (if present).  As outlined in :ref:`descriptors`, data
+   descriptors take preference over instance attributes, while non-data
+   descriptors don't.  Otherwise, an :exc:`AttributeError` is raised.
+
+
 .. cfunction:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
 
    Set the value of the attribute named *attr_name*, for object *o*, to the value
@@ -56,6 +66,17 @@ Object Protocol
    ``o.attr_name = v``.
 
 
+.. cfunction:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject
+*value)
+
+   Generic attribute setter function that is meant to be put into a type
+   object's ``tp_setattro`` slot.  It looks for a data descriptor in the
+   dictionary of classes in the object's MRO, and if found it takes preference
+   over setting the attribute in the instance dictionary. Otherwise, the
+   attribute is set in the object's :attr:`__dict__` (if present).  Otherwise,
+   an :exc:`AttributeError` is raised and ``-1`` is returned.
+
+
 .. cfunction:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
 
    Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.

Doc/c-api/veryhigh.rst

@@ -36,6 +36,10 @@ the same library that the Python runtime is using.
    interpreter exits due to an exception, or ``2`` if the parameter list does not
    represent a valid Python command line.
 
+   Note that if an otherwise unhandled :exc:`SystemError` is raised, this
+   function will not return ``1``, but exit the process, as long as
+   ``Py_InspectFlag`` is not set.
+
 
 .. cfunction:: int PyRun_AnyFile(FILE *fp, const char *filename)
 
@@ -78,6 +82,10 @@ the same library that the Python runtime is using.
    there was an error, there is no way to get the exception information. For the
    meaning of *flags*, see below.
 
+   Note that if an otherwise unhandled :exc:`SystemError` is raised, this
+   function will not return ``-1``, but exit the process, as long as
+   ``Py_InspectFlag`` is not set.
+
 
 .. cfunction:: int PyRun_SimpleFile(FILE *fp, const char *filename)
 

Doc/distutils/index.rst

@@ -16,6 +16,7 @@ very little overhead for build/release/install mechanics.
 
 .. toctree::
    :maxdepth: 2
+   :numbered:
 
    introduction.rst
    setupscript.rst

Doc/documenting/index.rst

@@ -23,6 +23,7 @@ to write reStructuredText if you're not so inclined; plain text contributions
 are more than welcome as well.
 
 .. toctree::
+   :numbered:
 
    intro.rst
    style.rst

Doc/extending/extending.rst

@@ -465,10 +465,10 @@ reference count of an object and are safe in the presence of *NULL* pointers
 (but note that *temp* will not be  *NULL* in this context).  More info on them
 in section :ref:`refcounts`.
 
-.. index:: single: PyEval_CallObject()
+.. index:: single: PyObject_CallObject()
 
 Later, when it is time to call the function, you call the C function
-:cfunc:`PyEval_CallObject`.  This function has two arguments, both pointers to
+:cfunc:`PyObject_CallObject`.  This function has two arguments, both pointers to
 arbitrary Python objects: the Python function, and the argument list.  The
 argument list must always be a tuple object, whose length is the number of
 arguments.  To call the Python function with no arguments, pass in NULL, or
@@ -484,16 +484,16 @@ or more format codes between parentheses.  For example::
    ...
    /* Time to call the callback */
    arglist = Py_BuildValue("(i)", arg);
-   result = PyEval_CallObject(my_callback, arglist);
+   result = PyObject_CallObject(my_callback, arglist);
    Py_DECREF(arglist);
 
-:cfunc:`PyEval_CallObject` returns a Python object pointer: this is the return
-value of the Python function.  :cfunc:`PyEval_CallObject` is
+:cfunc:`PyObject_CallObject` returns a Python object pointer: this is the return
+value of the Python function.  :cfunc:`PyObject_CallObject` is
 "reference-count-neutral" with respect to its arguments.  In the example a new
 tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\
 -ed immediately after the call.
 
-The return value of :cfunc:`PyEval_CallObject` is "new": either it is a brand
+The return value of :cfunc:`PyObject_CallObject` is "new": either it is a brand
 new object, or it is an existing object whose reference count has been
 incremented.  So, unless you want to save it in a global variable, you should
 somehow :cfunc:`Py_DECREF` the result, even (especially!) if you are not
@@ -501,7 +501,7 @@ interested in its value.
 
 Before you do this, however, it is important to check that the return value
 isn't *NULL*.  If it is, the Python function terminated by raising an exception.
-If the C code that called :cfunc:`PyEval_CallObject` is called from Python, it
+If the C code that called :cfunc:`PyObject_CallObject` is called from Python, it
 should now return an error indication to its Python caller, so the interpreter
 can print a stack trace, or the calling Python code can handle the exception.
 If this is not possible or desirable, the exception should be cleared by calling
@@ -513,7 +513,7 @@ If this is not possible or desirable, the exception should be cleared by calling
    Py_DECREF(result);
 
 Depending on the desired interface to the Python callback function, you may also
-have to provide an argument list to :cfunc:`PyEval_CallObject`.  In some cases
+have to provide an argument list to :cfunc:`PyObject_CallObject`.  In some cases
 the argument list is also provided by the Python program, through the same
 interface that specified the callback function.  It can then be saved and used
 in the same manner as the function object.  In other cases, you may have to
@@ -524,7 +524,7 @@ event code, you might use the following code::
    PyObject *arglist;
    ...
    arglist = Py_BuildValue("(l)", eventcode);
-   result = PyEval_CallObject(my_callback, arglist);
+   result = PyObject_CallObject(my_callback, arglist);
    Py_DECREF(arglist);
    if (result == NULL)
        return NULL; /* Pass error back */
@@ -536,19 +536,20 @@ the error check!  Also note that strictly speaking this code is not complete:
 :cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
 
 You may also call a function with keyword arguments by using
-:cfunc:`PyEval_CallObjectWithKeywords`.  As in the above example, we use
-:cfunc:`Py_BuildValue` to construct the dictionary. ::
+:cfunc:`PyObject_Call`, which supports arguments and keyword arguments.  As in
+the above example, we use :cfunc:`Py_BuildValue` to construct the dictionary. ::
 
    PyObject *dict;
    ...
    dict = Py_BuildValue("{s:i}", "name", val);
-   result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict);
+   result = PyObject_Call(my_callback, NULL, dict);
    Py_DECREF(dict);
    if (result == NULL)
        return NULL; /* Pass error back */
    /* Here maybe use the result */
    Py_DECREF(result);
 
+
 .. _parsetuple:
 
 Extracting Parameters in Extension Functions

Doc/extending/index.rst

@@ -26,6 +26,7 @@ For a detailed description of the whole Python/C API, see the separate
 
 .. toctree::
    :maxdepth: 2
+   :numbered:
 
    extending.rst
    newtypes.rst

Doc/glossary.rst

@@ -185,6 +185,11 @@ Glossary
       A module written in C or C++, using Python's C API to interact with the core and
       with user code.
 
+   finder
+      An object that tries to find the :term:`loader` for a module. It must
+      implement a method named :meth:`find_module`. See :pep:`302` for
+      details.
+
    function
       A series of statements which returns some value to a caller. It can also
       be passed zero or more arguments which may be used in the execution of
@@ -288,6 +293,10 @@ Glossary
       fraction.  Integer division can be forced by using the ``//`` operator
       instead of the ``/`` operator.  See also :term:`__future__`.
 
+   importer
+      An object that both finds and loads a module; both a
+      :term:`finder` and :term:`loader` object.
+
    interactive
       Python has an interactive interpreter which means you can enter
       statements and expressions at the interpreter prompt, immediately
@@ -368,6 +377,11 @@ Glossary
       clause is optional.  If omitted, all elements in ``range(256)`` are
       processed.
 
+   loader
+      An object that loads a module. It must define a method named
+      :meth:`load_module`. A loader is typically returned by a
+      :term:`finder`. See :pep:`302` for details.
+
    mapping
       A container object (such as :class:`dict`) which supports arbitrary key
       lookups using the special method :meth:`__getitem__`.

Doc/howto/regex.rst

@@ -540,6 +540,10 @@ of each one.
 | :const:`VERBOSE`, :const:`X`    | Enable verbose REs, which can be organized |
 |                                 | more cleanly and understandably.           |
 +---------------------------------+--------------------------------------------+
+| :const:`UNICODE`, :const:`U`    | Makes several escapes like ``\w``, ``\b``, |
+|                                 | ``\s`` and ``\d`` dependent on the Unicode |
+|                                 | character database.                        |
++---------------------------------+--------------------------------------------+
 
 
 .. data:: I
@@ -594,6 +598,14 @@ of each one.
    newline; without this flag, ``'.'`` will match anything *except* a newline.
 
 
+.. data:: U
+          UNICODE
+   :index:
+
+   Make ``\w``, ``\W``, ``\b``, ``\B``, ``\d``, ``\D``, ``\s`` and ``\S``
+   dependent on the Unicode character properties database.
+
+
 .. data:: X
           VERBOSE
    :noindex:

Doc/library/_winreg.rst

-
 :mod:`_winreg` -- Windows registry access
 =========================================
 
@@ -47,8 +46,8 @@ This module offers the following functions:
 
    *key* is the predefined handle to connect to.
 
-   The return value is the handle of the opened key. If the function fails, an
-   :exc:`EnvironmentError` exception is  raised.
+   The return value is the handle of the opened key. If the function fails, a
+   :exc:`WindowsError` exception is  raised.
 
 
 .. function:: CreateKey(key, sub_key)
@@ -65,8 +64,8 @@ This module offers the following functions:
 
    If the key already exists, this function opens the existing key.
 
-   The return value is the handle of the opened key. If the function fails, an
-   :exc:`EnvironmentError` exception is  raised.
+   The return value is the handle of the opened key. If the function fails, a
+   :exc:`WindowsError` exception is  raised.
 
 
 .. function:: DeleteKey(key, sub_key)
@@ -82,7 +81,7 @@ This module offers the following functions:
    *This method can not delete keys with subkeys.*
 
    If the method succeeds, the entire key, including all of its values, is removed.
-   If the method fails, an :exc:`EnvironmentError`  exception is raised.
+   If the method fails, a :exc:`WindowsError`  exception is raised.
 
 
 .. function:: DeleteValue(key, value)
@@ -105,7 +104,7 @@ This module offers the following functions:
    *index* is an integer that identifies the index of the key to  retrieve.
 
    The function retrieves the name of one subkey each time it  is called.  It is
-   typically called repeatedly until an  :exc:`EnvironmentError` exception  is
+   typically called repeatedly until a  :exc:`WindowsError` exception  is
    raised, indicating, no more values are available.
 
 
@@ -119,7 +118,7 @@ This module offers the following functions:
    *index* is an integer that identifies the index of the value  to retrieve.
 
    The function retrieves the name of one subkey each time it is  called. It is
-   typically called repeatedly, until an  :exc:`EnvironmentError` exception is
+   typically called repeatedly, until a  :exc:`WindowsError` exception is
    raised, indicating  no more values.
 
    The result is a tuple of 3 items:
@@ -209,7 +208,7 @@ This module offers the following functions:
 
    The result is a new handle to the specified key.
 
-   If the function fails, :exc:`EnvironmentError` is raised.
+   If the function fails, :exc:`WindowsError` is raised.
 
 
 .. function:: OpenKeyEx()

Doc/library/abc.rst

@@ -161,7 +161,7 @@ It also provides the following decorators:
       multiple-inheritance.
 
 
-.. function:: abstractproperty(fget[, fset[, fdel[, doc]]])
+.. function:: abstractproperty([fget[, fset[, fdel[, doc]]]])
 
    A subclass of the built-in :func:`property`, indicating an abstract property.
 
@@ -189,6 +189,7 @@ It also provides the following decorators:
           def setx(self, value): ...
           x = abstractproperty(getx, setx)
 
+
 .. rubric:: Footnotes
 
 .. [#] C++ programmers should note that Python's virtual base class

Doc/library/functions.rst

@@ -1344,7 +1344,11 @@ available.  They are listed here in alphabetical order.
    Without arguments, return a dictionary corresponding to the current local symbol
    table.  With a module, class or class instance object as argument (or anything
    else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
-   to the object's symbol table.  The returned dictionary should not be modified:
+   to the object's symbol table.
+
+   .. warning::
+
+      The returned dictionary should not be modified:
       the effects on the corresponding symbol table are undefined. [#]_
 
 

Doc/library/index.rst

@@ -38,6 +38,7 @@ the `Python Package Index <http://pypi.python.org/pypi>`_.
 
 .. toctree::
    :maxdepth: 2
+   :numbered:
 
    intro.rst
    functions.rst

Doc/library/os.rst

@@ -1751,7 +1751,9 @@ written in Python, such as a mail server's external command delivery program.
    which is used to define the environment variables for the new process (they are
    used instead of the current process' environment); the functions
    :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
-   the new process to inherit the environment of the current process.
+   the new process to inherit the environment of the current process.  Note that
+   keys and values in the *env* dictionary must be strings; invalid keys or
+   values will cause the function to fail, with a return value of ``127``.
 
    As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
    equivalent::

Doc/library/re.rst

@@ -8,12 +8,9 @@
 .. sectionauthor:: Andrew M. Kuchling <amk@amk.ca>
 
 
-
-
 This module provides regular expression matching operations similar to
 those found in Perl. Both patterns and strings to be searched can be
-Unicode strings as well as 8-bit strings.  The :mod:`re` module is
-always available.
+Unicode strings as well as 8-bit strings.
 
 Regular expressions use the backslash character (``'\'``) to indicate
 special forms or to allow special characters to be used without invoking
@@ -43,9 +40,6 @@ fine-tuning parameters.
       second edition of the book no longer covers Python at all, but the first
       edition covered writing good regular expression patterns in great detail.
 
-   `Kodos <http://kodos.sf.net/>`_
-      is a graphical regular expression debugger written in Python.
-
 
 .. _re-syntax:
 

Doc/library/stdtypes.rst

@@ -2652,6 +2652,17 @@ types, where they are relevant.  Some of these are not reported by the
 
    The name of the class or type.
 
+
+.. method:: class.__subclasses__
+
+   :term:`New-style class`\ es keep a list of weak references to their immediate
+   subclasses.  This method returns a list of all those references still alive.
+   Example::
+
+      >>> int.__subclasses__()
+      [<type 'bool'>]
+
+
 .. rubric:: Footnotes
 
 .. [#] Additional information on these special methods may be found in the Python

Doc/library/sys.rst

@@ -535,6 +535,22 @@ always available.
    characters are stored as UCS-2 or UCS-4.
 
 
+.. data:: meta_path
+
+    A list of :term:`finder` objects that have their :meth:`find_module`
+    methods called to see if one of the objects can find the module to be
+    imported. The :meth:`find_module` method is called at least with the
+    absolute name of the module being imported. If the module to be imported is
+    contained in package then the parent package's :attr:`__path__` attribute
+    is passed in as a second argument. The method returns :keyword:`None` if
+    the module cannot be found, else returns a :term:`loader`.
+
+    :data:`sys.meta_path` is searched before any implicit default finders or
+    :data:`sys.path`.
+
+    See :pep:`302` for the original specification.
+
+
 .. data:: modules
 
    .. index:: builtin: reload
@@ -571,6 +587,27 @@ always available.
       :data:`sys.path`.
 
 
+.. data:: path_hooks
+
+    A list of callables that take a path argument to try to create a
+    :term:`finder` for the path. If a finder can be created, it is to be
+    returned by the callable, else raise :exc:`ImportError`.
+
+    Originally specified in :pep:`302`.
+
+
+.. data:: path_importer_cache
+
+    A dictionary acting as a cache for :term:`finder` objects. The keys are
+    paths that have been passed to :data:`sys.path_hooks` and the values are
+    the finders that are found. If a path is a valid file system path but no
+    explicit finder is found on :data:`sys.path_hooks` then :keyword:`None` is
+    stored to represent the implicit default finder should be used. If the path
+    is not an existing path then :class:`imp.NullImporter` is set.
+
+    Originally specified in :pep:`302`.
+
+
 .. data:: platform
 
    This string contains a platform identifier that can be used to append

Doc/reference/datamodel.rst

@@ -56,12 +56,13 @@ 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
+are still reachable.  (Implementation note: CPython currently 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.)
+collection of cyclic garbage.  Other implementations act differently and CPython
+may change.)
 
 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

Doc/reference/index.rst

@@ -18,6 +18,7 @@ interfaces available to C/C++ programmers in detail.
 
 .. toctree::
    :maxdepth: 2
+   :numbered:
 
    introduction.rst
    lexical_analysis.rst

Doc/reference/simple_stmts.rst

@@ -653,48 +653,124 @@ The :keyword:`import` statement
 
 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.
+where the :keyword:`import` statement occurs). The statement comes in two
+forms differing on whether it uses the :keyword:`from` keyword. 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: package
+
+To understand how step (1) occurs, one must first understand how Python handles
+hierarchical naming of modules. To help organize modules and provide a
+hierarchy in naming, Python has a concept of packages. A package can contain
+other packages and modules while modules cannot contain other modules or
+packages. From a file system perspective, packages are directories and modules
+are files. The original `specification for packages
+<http://www.python.org/doc/essays/packages.html>`_ is still available to read,
+although minor details have changed since the writing of that document.
 
 .. 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``.
+Once the name of the module is known (unless otherwise specified, the term
+"module" will refer to both packages and modules), searching
+for the module or package can begin. The first place checked is
+:data:`sys.modules`, the cache of all modules that have been imported
+previously. If the module is found there then it is used in step (2) of import.
+
+.. index::
+    single: sys.meta_path
+    single: finder
+    pair: finder; find_module
+    single: __path__
+
+If the module is not found in the cache, then :data:`sys.meta_path` is searched
+(the specification for :data:`sys.meta_path` can be found in :pep:`302`).
+The object is a list of :term:`finder` objects which are queried in order as to
+whether they know how to load the module by calling their :meth:`find_module`
+method with the name of the module. If the module happens to be contained
+within a package (as denoted by the existence of a dot in the name), then a
+second argument to :meth:`find_module` is given as the value of the
+: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`.
+
+.. index::
+    single: sys.path_hooks
+    single: sys.path_importer_cache
+    single: sys.path
+
+If none of the finders on :data:`sys.meta_path` are able to find the module
+then some implicitly defined finders are queried. Implementations of Python
+vary in what implicit meta path finders are defined. The one they all do
+define, though, is one that handles :data:`sys.path_hooks`,
+:data:`sys.path_importer_cache`, and :data:`sys.path`.
+
+The implicit finder searches for the requested module in the "paths" specified
+in one of two places ("paths" do not have to be file system paths). If the
+module being imported is supposed to be contained within a package then the
+second argument passed to :meth:`find_module`, :attr:`__path__` on the parent
+package, is used as the source of paths. If the module is not contained in a
+package then :data:`sys.path` is used as the source of paths.
+
+Once the source of paths is chosen it is iterated over to find a finder that
+can handle that path. The dict at :data:`sys.path_importer_cache` caches
+finders for paths and is checked for a finder. If the path does not have a
+finder cached then :data:`sys.path_hooks` is searched by calling each object in
+the list with a single argument of the path, returning a finder or raises
+: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
+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.
+
+.. index::
+    single: loader
+    pair: loader; load_module
+    exception: ImportError
+
+If no finder can find the module then :exc:`ImportError` is raised. Otherwise
+some finder returned a loader whose :meth:`load_module` method is called with
+the name of the module to load (see :pep:`302` for the original definition of
+loaders). A loader has several responsibilities to perform on a module it
+loads. First, if the module already exists in :data:`sys.modules` (a
+possibility if the loader is called outside of the import machinery) then it
+is to use that module for initialization and not a new module. But if the
+module does not exist in :data:`sys.modules` then it is to be added to that
+dict before initialization begins. If an error occurs during loading of the
+module and it was added to :data:`sys.modules` it is to be removed from the
+dict. If an error occurs but the module was already in :data:`sys.modules` it
+is left in the dict.
+
+.. index::
+    single: __name__
+    single: __file__
+    single: __path__
+    single: __package__
+    single: __loader__
+
+The loader must set several attributes on the module. :data:`__name__` is to be
+set to the name of the module. :data:`__file__` is to be the "path" to the file
+unless the module is built-in (and thus listed in
+:data:`sys.builtin_module_names`) in which case the attribute is not set.
+If what is being imported is a package then :data:`__path__` is to be set to a
+list of paths to be searched when looking for modules and packages contained
+within the package being imported. :data:`__package__` is optional but should
+be set to the name of package that contains the module or package (the empty
+string is used for module not contained in a package). :data:`__loader__` is
+also optional but should be set to the loader object that is loading the
+module.
 
 .. 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).
+If an error occurs during loading then the loader raises :exc:`ImportError` if
+some other exception is not already being propagated. Otherwise the loader
+returns the module that was loaded and initialized.
 
 When step (1) finishes without raising an exception, step (2) can begin.
 
@@ -734,23 +810,21 @@ function contains or is a nested block with free variables, the compiler will
 raise a :exc:`SyntaxError`.
 
 .. index::
-   keyword: from
-   statement: from
-   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.]
+    single: relative; import
+
+When specifying what module to import you do not have to specify the absolute
+name of the module. When a module or package is contained within another
+package it is possible to make a relative import within the same top package
+without having to mention the package name. By using leading dots in the
+specified module or package after :keyword:`from` you can specify how high to
+traverse up the current package hierarchy without specifying exact names. One
+leading dot means the current package where the module making the import
+exists. Two dots means up one package level. Three dots is up two levels, etc.
+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``.
+The specification for relative imports is contained within :pep:`328`.
+
 
 .. index:: builtin: __import__
 
@@ -892,7 +966,7 @@ The :keyword:`exec` statement
 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
+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
@@ -930,3 +1004,8 @@ built-in function :func:`eval`.  The built-in functions :func:`globals` and
 which may be useful to pass around for use by :keyword:`exec`.
 
 
+.. rubric:: Footnotes
+
+.. [#] 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.

Doc/tutorial/index.rst

@@ -44,6 +44,7 @@ various Python library modules described in the Python Library Reference.
 The :ref:`glossary` is also worth going through.
 
 .. toctree::
+   :numbered:
 
    appetite.rst
    interpreter.rst

Doc/using/index.rst

@@ -11,6 +11,7 @@ interpreter and things that make working with Python easier.
 
 
 .. toctree::
+   :numbered:
 
    cmdline.rst
    unix.rst

Lib/distutils/version.py

@@ -162,7 +162,7 @@ class StrictVersion (Version):
 
 
 # The rules according to Greg Stein:
-# 1) a version number has 1 or more numbers separate by a period or by
+# 1) a version number has 1 or more numbers separated by a period or by
 #    sequences of letters. If only periods, then these are compared
 #    left-to-right to determine an ordering.
 # 2) sequences of letters are part of the tuple for comparison and are

Objects/genobject.c

@@ -306,7 +306,7 @@ PyDoc_STRVAR(gen__name__doc__,
 "Return the name of the generator's associated code object.");
 
 static PyGetSetDef gen_getsetlist[] = {
-	{"__name__", (getter)gen_get_name, NULL, NULL, gen__name__doc__},
+	{"__name__", (getter)gen_get_name, NULL, gen__name__doc__},
 	{NULL}
 };
 

Tools/scripts/reindent-rst.py

+#!/usr/bin/env python
+
+# Make a reST file compliant to our pre-commit hook.
+# Currently just remove trailing whitespace.
+
+from __future__ import with_statement
+import sys, re, shutil
+
+ws_re = re.compile(r'\s+(\r?\n)$')
+
+def main(argv=sys.argv):
+    rv = 0
+    for filename in argv[1:]:
+        try:
+            with open(filename, 'rb') as f:
+                lines = f.readlines()
+            new_lines = [ws_re.sub(r'\1', line) for line in lines]
+            if new_lines != lines:
+                print 'Fixing %s...' % filename
+            shutil.copyfile(filename, filename + '.bak')
+            with open(filename, 'wb') as f:
+                f.writelines(new_lines)
+        except Exception, err:
+            print 'Cannot fix %s: %s' % (filename, err)
+            rv = 1
+    return rv
+
+if __name__ == '__main__':
+    sys.exit(main())