Merged revisions 85530,85534,85538,85540-85542 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r85530 | georg.brandl | 2010-10-15 17:32:05 +0200 (Fr, 15 Okt 2010) | 1 line

  Refrain from using inline suites.
........
  r85534 | georg.brandl | 2010-10-15 18:19:43 +0200 (Fr, 15 Okt 2010) | 1 line

  #9801: document how list and dict proxies created by Managers behave w.r.t. mutable items.
........
  r85538 | georg.brandl | 2010-10-15 18:35:46 +0200 (Fr, 15 Okt 2010) | 1 line

  #7303: add documentation for useful pkgutil functions and classes.
........
  r85540 | georg.brandl | 2010-10-15 18:42:37 +0200 (Fr, 15 Okt 2010) | 1 line

  #6798: fix wrong docs for the arguments to several trace events.
........
  r85541 | georg.brandl | 2010-10-15 18:53:24 +0200 (Fr, 15 Okt 2010) | 1 line

  #4968: updates to inspect.is* function docs.
........
  r85542 | georg.brandl | 2010-10-15 19:01:15 +0200 (Fr, 15 Okt 2010) | 1 line

  #7790: move table of struct_time members to the actual description of struct_time.
........
This commit is contained in:
Georg Brandl 2010-11-26 07:34:20 +00:00
parent d8d884947b
commit 78f11edf3f
7 changed files with 247 additions and 88 deletions

View File

@ -925,13 +925,14 @@ in previous versions.
+------------------------------+--------------------------------------+
| :const:`PyTrace_LINE` | Always *NULL*. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_RETURN` | Value being returned to the caller. |
| :const:`PyTrace_RETURN` | Value being returned to the caller, |
| | or *NULL* if caused by an exception. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_C_CALL` | Name of function being called. |
| :const:`PyTrace_C_CALL` | Function object being called. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_C_EXCEPTION` | Always *NULL*. |
| :const:`PyTrace_C_EXCEPTION` | Function object being called. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_C_RETURN` | Always *NULL*. |
| :const:`PyTrace_C_RETURN` | Function object being called. |
+------------------------------+--------------------------------------+

View File

@ -263,17 +263,20 @@ Note:
.. function:: isclass(object)
Return true if the object is a class.
Return true if the object is a class, whether built-in or created in Python
code.
.. function:: ismethod(object)
Return true if the object is a method.
Return true if the object is a bound method written in Python.
.. function:: isfunction(object)
Return true if the object is a Python function or unnamed (:term:`lambda`) function.
Return true if the object is a Python function, which includes functions
created by a :term:`lambda` expression.
.. function:: isgeneratorfunction(object)
@ -281,12 +284,14 @@ Note:
.. versionadded:: 2.6
.. function:: isgenerator(object)
Return true if the object is a generator.
.. versionadded:: 2.6
.. function:: istraceback(object)
Return true if the object is a traceback.
@ -304,13 +309,14 @@ Note:
.. function:: isbuiltin(object)
Return true if the object is a built-in function.
Return true if the object is a built-in function or a bound built-in method.
.. function:: isroutine(object)
Return true if the object is a user-defined or built-in function or method.
.. function:: isabstract(object)
Return true if the object is an abstract base class.
@ -320,8 +326,9 @@ Note:
.. function:: ismethoddescriptor(object)
Return true if the object is a method descriptor, but not if :func:`ismethod`
or :func:`isclass` or :func:`isfunction` are true.
Return true if the object is a method descriptor, but not if
:func:`ismethod`, :func:`isclass`, :func:`isfunction` or :func:`isbuiltin`
are true.
This is new as of Python 2.2, and, for example, is true of
``int.__add__``. An object passing this test has a :attr:`__get__` attribute

View File

@ -1286,6 +1286,24 @@ their parent process exits. The manager classes are defined in the
Create a shared ``list`` object and return a proxy for it.
.. note::
Modifications to mutable values or items in dict and list proxies will not
be propagated through the manager, because the proxy has no way of knowing
when its values or items are modified. To modify such an item, you can
re-assign the modified object to the container proxy::
# create a list proxy and append a mutable object (a dictionary)
lproxy = manager.list()
lproxy.append({})
# now mutate the dictionary
d = lproxy[0]
d['a'] = 1
d['b'] = 2
# at this point, the changes to d are not yet synced, but by
# reassigning the dictionary, the proxy is notified of the change
lproxy[0] = d
Namespace objects
>>>>>>>>>>>>>>>>>

View File

@ -3,62 +3,187 @@
============================================
.. module:: pkgutil
:synopsis: Utilities to support extension of packages.
:synopsis: Utilities for the import system.
This module provides utilities for the import system, in particular package
support.
.. versionadded:: 2.3
This module provides functions to manipulate packages:
.. function:: extend_path(path, name)
Extend the search path for the modules which comprise a package. Intended use is
to place the following code in a package's :file:`__init__.py`::
Extend the search path for the modules which comprise a package. Intended
use is to place the following code in a package's :file:`__init__.py`::
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
This will add to the package's ``__path__`` all subdirectories of directories on
``sys.path`` named after the package. This is useful if one wants to distribute
different parts of a single logical package as multiple directories.
This will add to the package's ``__path__`` all subdirectories of directories
on ``sys.path`` named after the package. This is useful if one wants to
distribute different parts of a single logical package as multiple
directories.
It also looks for :file:`\*.pkg` files beginning where ``*`` matches the *name*
argument. This feature is similar to :file:`\*.pth` files (see the :mod:`site`
module for more information), except that it doesn't special-case lines starting
with ``import``. A :file:`\*.pkg` file is trusted at face value: apart from
checking for duplicates, all entries found in a :file:`\*.pkg` file are added to
the path, regardless of whether they exist on the filesystem. (This is a
feature.)
It also looks for :file:`\*.pkg` files beginning where ``*`` matches the
*name* argument. This feature is similar to :file:`\*.pth` files (see the
:mod:`site` module for more information), except that it doesn't special-case
lines starting with ``import``. A :file:`\*.pkg` file is trusted at face
value: apart from checking for duplicates, all entries found in a
:file:`\*.pkg` file are added to the path, regardless of whether they exist
on the filesystem. (This is a feature.)
If the input path is not a list (as is the case for frozen packages) it is
returned unchanged. The input path is not modified; an extended copy is
returned. Items are only appended to the copy at the end.
It is assumed that ``sys.path`` is a sequence. Items of ``sys.path`` that are
not (Unicode or 8-bit) strings referring to existing directories are ignored.
Unicode items on ``sys.path`` that cause errors when used as filenames may cause
this function to raise an exception (in line with :func:`os.path.isdir`
behavior).
It is assumed that :data:`sys.path` is a sequence. Items of :data:`sys.path`
that are not (Unicode or 8-bit) strings referring to existing directories are
ignored. Unicode items on :data:`sys.path` that cause errors when used as
filenames may cause this function to raise an exception (in line with
:func:`os.path.isdir` behavior).
.. class:: ImpImporter(dirname=None)
:pep:`302` Importer that wraps Python's "classic" import algorithm.
If *dirname* is a string, a :pep:`302` importer is created that searches that
directory. If *dirname* is ``None``, a :pep:`302` importer is created that
searches the current :data:`sys.path`, plus any modules that are frozen or
built-in.
Note that :class:`ImpImporter` does not currently support being used by
placement on :data:`sys.meta_path`.
.. class:: ImpLoader(fullname, file, filename, etc)
:pep:`302` Loader that wraps Python's "classic" import algorithm.
.. function:: find_loader(fullname)
Find a :pep:`302` "loader" object for *fullname*.
If *fullname* contains dots, path must be the containing package's
``__path__``. Returns ``None`` if the module cannot be found or imported.
This function uses :func:`iter_importers`, and is thus subject to the same
limitations regarding platform-specific special import locations such as the
Windows registry.
.. function:: get_importer(path_item)
Retrieve a :pep:`302` importer for the given *path_item*.
The returned importer is cached in :data:`sys.path_importer_cache` if it was
newly created by a path hook.
If there is no importer, a wrapper around the basic import machinery is
returned. This wrapper is never inserted into the importer cache (None is
inserted instead).
The cache (or part of it) can be cleared manually if a rescan of
:data:`sys.path_hooks` is necessary.
.. function:: get_loader(module_or_name)
Get a :pep:`302` "loader" object for *module_or_name*.
If the module or package is accessible via the normal import mechanism, a
wrapper around the relevant part of that machinery is returned. Returns
``None`` if the module cannot be found or imported. If the named module is
not already imported, its containing package (if any) is imported, in order
to establish the package ``__path__``.
This function uses :func:`iter_importers`, and is thus subject to the same
limitations regarding platform-specific special import locations such as the
Windows registry.
.. function:: iter_importers(fullname='')
Yield :pep:`302` importers for the given module name.
If fullname contains a '.', the importers will be for the package containing
fullname, otherwise they will be importers for :data:`sys.meta_path`,
:data:`sys.path`, and Python's "classic" import machinery, in that order. If
the named module is in a package, that package is imported as a side effect
of invoking this function.
Non-:pep:`302` mechanisms (e.g. the Windows registry) used by the standard
import machinery to find files in alternative locations are partially
supported, but are searched *after* :data:`sys.path`. Normally, these
locations are searched *before* :data:`sys.path`, preventing :data:`sys.path`
entries from shadowing them.
For this to cause a visible difference in behaviour, there must be a module
or package name that is accessible via both :data:`sys.path` and one of the
non-:pep:`302` file system mechanisms. In this case, the emulation will find
the former version, while the builtin import mechanism will find the latter.
Items of the following types can be affected by this discrepancy:
``imp.C_EXTENSION``, ``imp.PY_SOURCE``, ``imp.PY_COMPILED``,
``imp.PKG_DIRECTORY``.
.. function:: iter_modules(path=None, prefix='')
Yields ``(module_loader, name, ispkg)`` for all submodules on *path*, or, if
path is ``None``, all top-level modules on ``sys.path``.
*path* should be either ``None`` or a list of paths to look for modules in.
*prefix* is a string to output on the front of every module name on output.
.. function:: walk_packages(path=None, prefix='', onerror=None)
Yields ``(module_loader, name, ispkg)`` for all modules recursively on
*path*, or, if path is ``None``, all accessible modules.
*path* should be either ``None`` or a list of paths to look for modules in.
*prefix* is a string to output on the front of every module name on output.
Note that this function must import all *packages* (*not* all modules!) on
the given *path*, in order to access the ``__path__`` attribute to find
submodules.
*onerror* is a function which gets called with one argument (the name of the
package which was being imported) if any exception occurs while trying to
import a package. If no *onerror* function is supplied, :exc:`ImportError`\s
are caught and ignored, while all other exceptions are propagated,
terminating the search.
Examples::
# list all modules python can access
walk_packages()
# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')
.. function:: get_data(package, resource)
Get a resource from a package.
This is a wrapper for the :pep:`302` loader :func:`get_data` API. The package
argument should be the name of a package, in standard module format
(foo.bar). The resource argument should be in the form of a relative
filename, using ``/`` as the path separator. The parent directory name
This is a wrapper for the :pep:`302` loader :func:`get_data` API. The
*package* argument should be the name of a package, in standard module format
(``foo.bar``). The *resource* argument should be in the form of a relative
filename, using ``/`` as the path separator. The parent directory name
``..`` is not allowed, and nor is a rooted name (starting with a ``/``).
The function returns a binary string that is the contents of the
specified resource.
The function returns a binary string that is the contents of the specified
resource.
For packages located in the filesystem, which have already been imported,
this is the rough equivalent of::
d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()
d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()
If the package cannot be located or loaded, or it uses a :pep:`302` loader
which does not support :func:`get_data`, then None is returned.
which does not support :func:`get_data`, then ``None`` is returned.

View File

@ -874,8 +874,9 @@ always available.
``'return'``
A function (or other code block) is about to return. The local trace
function is called; *arg* is the value that will be returned. The trace
function's return value is ignored.
function is called; *arg* is the value that will be returned, or ``None``
if the event is caused by an exception being raised. The trace function's
return value is ignored.
``'exception'``
An exception has occurred. The local trace function is called; *arg* is a
@ -887,10 +888,10 @@ always available.
a built-in. *arg* is the C function object.
``'c_return'``
A C function has returned. *arg* is ``None``.
A C function has returned. *arg* is the C function object.
``'c_exception'``
A C function has raised an exception. *arg* is ``None``.
A C function has raised an exception. *arg* is the C function object.
Note that as an exception is propagated down the chain of callers, an
``'exception'`` event is generated at each level.

View File

@ -17,21 +17,23 @@ semantics of these functions varies among platforms.
An explanation of some terminology and conventions is in order.
.. index:: single: epoch
.. index:: single: epoch
* The :dfn:`epoch` is the point where the time starts. On January 1st of that
year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is
1970. To find out what the epoch is, look at ``gmtime(0)``.
.. index:: single: Year 2038
.. index:: single: Year 2038
* The functions in this module do not handle dates and times before the epoch or
far in the future. The cut-off point in the future is determined by the C
library; for Unix, it is typically in 2038.
.. index::
single: Year 2000
single: Y2K
.. index::
single: Year 2000
single: Y2K
.. _time-y2kissues:
* **Year 2000 (Y2K) issues**: Python depends on the platform's C library, which
generally doesn't have year 2000 issues, since all dates and times are
@ -48,16 +50,16 @@ An explanation of some terminology and conventions is in order.
Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python
1.5.1 and 1.5.2a1, would add 1900 to year values below 1900.
.. index::
single: UTC
single: Coordinated Universal Time
single: Greenwich Mean Time
.. index::
single: UTC
single: Coordinated Universal Time
single: Greenwich Mean Time
* UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
GMT). The acronym UTC is not a mistake but a compromise between English and
French.
.. index:: single: Daylight Saving Time
.. index:: single: Daylight Saving Time
* DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
hour during part of the year. DST rules are magic (determined by local law) and
@ -82,38 +84,7 @@ An explanation of some terminology and conventions is in order.
values of :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer
attribute names for individual fields.
+-------+-------------------+---------------------------------+
| Index | Attribute | Values |
+=======+===================+=================================+
| 0 | :attr:`tm_year` | (for example, 1993) |
+-------+-------------------+---------------------------------+
| 1 | :attr:`tm_mon` | range [1, 12] |
+-------+-------------------+---------------------------------+
| 2 | :attr:`tm_mday` | range [1, 31] |
+-------+-------------------+---------------------------------+
| 3 | :attr:`tm_hour` | range [0, 23] |
+-------+-------------------+---------------------------------+
| 4 | :attr:`tm_min` | range [0, 59] |
+-------+-------------------+---------------------------------+
| 5 | :attr:`tm_sec` | range [0, 61]; see **(1)** in |
| | | :func:`strftime` description |
+-------+-------------------+---------------------------------+
| 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 |
+-------+-------------------+---------------------------------+
| 7 | :attr:`tm_yday` | range [1, 366] |
+-------+-------------------+---------------------------------+
| 8 | :attr:`tm_isdst` | 0, 1 or -1; see below |
+-------+-------------------+---------------------------------+
Note that unlike the C structure, the month value is a range of [1, 12],
not [0, 11].
A year value will be handled as described under "Year 2000 (Y2K) issues" above.
A ``-1`` argument as the daylight savings flag, passed to :func:`mktime` will
usually result in the correct daylight savings state to be filled in.
When a tuple with an incorrect length is passed to a function expecting a
:class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError`
is raised.
See :class:`struct_time` for a description of these objects.
.. versionchanged:: 2.2
The time value sequence was changed from a tuple to a :class:`struct_time`, with
@ -419,13 +390,48 @@ The module defines the following functions and data items:
documented as supported.
.. data:: struct_time
.. class:: struct_time
The type of the time value sequence returned by :func:`gmtime`,
:func:`localtime`, and :func:`strptime`.
:func:`localtime`, and :func:`strptime`. It is an object with a :term:`named
tuple` interface: values can be accessed by index and by attribute name. The
following values are present:
+-------+-------------------+---------------------------------+
| Index | Attribute | Values |
+=======+===================+=================================+
| 0 | :attr:`tm_year` | (for example, 1993) |
+-------+-------------------+---------------------------------+
| 1 | :attr:`tm_mon` | range [1, 12] |
+-------+-------------------+---------------------------------+
| 2 | :attr:`tm_mday` | range [1, 31] |
+-------+-------------------+---------------------------------+
| 3 | :attr:`tm_hour` | range [0, 23] |
+-------+-------------------+---------------------------------+
| 4 | :attr:`tm_min` | range [0, 59] |
+-------+-------------------+---------------------------------+
| 5 | :attr:`tm_sec` | range [0, 61]; see **(1)** in |
| | | :func:`strftime` description |
+-------+-------------------+---------------------------------+
| 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 |
+-------+-------------------+---------------------------------+
| 7 | :attr:`tm_yday` | range [1, 366] |
+-------+-------------------+---------------------------------+
| 8 | :attr:`tm_isdst` | 0, 1 or -1; see below |
+-------+-------------------+---------------------------------+
.. versionadded:: 2.2
Note that unlike the C structure, the month value is a range of [1, 12], not
[0, 11]. A year value will be handled as described under :ref:`Year 2000
(Y2K) issues <time-y2kissues>` above. A ``-1`` argument as the daylight
savings flag, passed to :func:`mktime` will usually result in the correct
daylight savings state to be filled in.
When a tuple with an incorrect length is passed to a function expecting a
:class:`struct_time`, or having elements of the wrong type, a
:exc:`TypeError` is raised.
.. function:: time()

View File

@ -429,7 +429,8 @@ function like this::
def cheeseshop(kind, *arguments, **keywords):
print "-- Do you have any", kind, "?"
print "-- I'm sorry, we're all out of", kind
for arg in arguments: print arg
for arg in arguments:
print arg
print "-" * 40
keys = sorted(keywords.keys())
for kw in keys: