mirror of https://github.com/python/cpython
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
parent
d8d884947b
commit
78f11edf3f
|
|
@ -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. |
|
||||
+------------------------------+--------------------------------------+
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
>>>>>>>>>>>>>>>>>
|
||||
|
|
|
|||
|
|
@ -3,56 +3,181 @@
|
|||
============================================
|
||||
|
||||
.. 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
|
||||
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::
|
||||
|
|
@ -61,4 +186,4 @@ This module provides functions to manipulate packages:
|
|||
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -33,6 +33,8 @@ An explanation of some terminology and conventions is in order.
|
|||
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
|
||||
represented internally as seconds since the epoch. Functions accepting a
|
||||
|
|
@ -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()
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue