svn+ssh://pythondev@svn.python.org/python/trunk
........
r59774 | georg.brandl | 2008-01-06 16:41:50 +0100 (Sun, 06 Jan 2008) | 2 lines
#1501: document that 0**0 == 1.
........
r59775 | georg.brandl | 2008-01-06 16:48:20 +0100 (Sun, 06 Jan 2008) | 2 lines
#759525: document that dir() doesn't return metaclass attrs when given a class as arg.
........
r59776 | georg.brandl | 2008-01-06 16:55:26 +0100 (Sun, 06 Jan 2008) | 2 lines
#
1615275: clarify return object types of different tempfile factories.
........
r59777 | georg.brandl | 2008-01-06 17:01:26 +0100 (Sun, 06 Jan 2008) | 2 lines
#
1727024: document that Popen.returncode is set by Popen.poll/wait.
........
r59778 | georg.brandl | 2008-01-06 17:04:56 +0100 (Sun, 06 Jan 2008) | 2 lines
#
1686390: add example for csv.Sniffer use.
........
r59779 | georg.brandl | 2008-01-06 17:12:39 +0100 (Sun, 06 Jan 2008) | 2 lines
#
1559684: document that shutil.copy* doesn't copy all metadata on Posix and Windows too.
........
r59780 | georg.brandl | 2008-01-06 17:17:56 +0100 (Sun, 06 Jan 2008) | 2 lines
#1582: document __reversed__, patch by Mark Russell.
........
r59781 | georg.brandl | 2008-01-06 17:22:56 +0100 (Sun, 06 Jan 2008) | 2 lines
#1499: Document compile() exceptions.
........
r59782 | georg.brandl | 2008-01-06 17:49:50 +0100 (Sun, 06 Jan 2008) | 2 lines
#1325: Add docs and tests for zipimporter.archive and zipimporter.prefix.
........
* Jim Roskind
* Guido van Rossum
* Donald Wallace Rouse II
+ * Mark Russell
* Nick Russo
* Chris Ryland
* Constantina S.
The :class:`Sniffer` class provides two methods:
-
.. method:: Sniffer.sniff(sample[, delimiters=None])
Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the
Analyze the sample text (presumed to be in CSV format) and return :const:`True`
if the first row appears to be a series of column headers.
-The :mod:`csv` module defines the following constants:
+An example for :class:`Sniffer` use::
+
+ csvfile = open("example.csv")
+ dialect = csv.Sniffer().sniff(csvfile.read(1024))
+ csvfile.seek(0)
+ reader = csv.reader(csvfile, dialect)
+ # ... process CSV file contents here ...
+The :mod:`csv` module defines the following constants:
+
.. data:: QUOTE_ALL
Instructs :class:`writer` objects to quote all fields.
can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
instance in the :mod:`__future__` module.
+ This function raises :exc:`SyntaxError` if the compiled source is invalid,
+ and :exc:`TypeError` if the source contains null bytes.
+
.. function:: complex([real[, imag]])
Because :func:`dir` is supplied primarily as a convenience for use at an
interactive prompt, it tries to supply an interesting set of names more than it
tries to supply a rigorously or consistently defined set of names, and its
- detailed behavior may change across releases.
+ detailed behavior may change across releases. For example, metaclass attributes
+ are not in the result list when the argument is a class.
.. function:: divmod(a, b)
.. function:: reversed(seq)
- Return a reverse :term:`iterator`. *seq* must be an object which supports
- the sequence protocol (the :meth:`__len__` method and the :meth:`__getitem__`
- method with integer arguments starting at ``0``).
+ Return a reverse :term:`iterator`. *seq* must be an object which has
+ a :meth:`__reversed__` method or supports the sequence protocol (the
+ :meth:`__len__` method and the :meth:`__getitem__` method with integer
+ arguments starting at ``0``).
.. function:: round(x[, n])
name. If the optional *predicate* argument is supplied, only members for which
the predicate returns a true value are included.
+ .. note::
+
+ :func:`getmembers` does not return metaclass attributes when the argument
+ is a class (this behavior is inherited from the :func:`dir` function).
+
.. function:: getmoduleinfo(path)
:mod:`os` module.
.. warning::
+
+ Even the higher-level file copying functions (:func:`copy`, :func:`copy2`)
+ can't copy all file metadata.
- On MacOS, the resource fork and other metadata are not used. For file copies,
- this means that resources will be lost and file type and creator codes will
- not be correct.
+ On POSIX platforms, this means that file owner and group are lost as well
+ as ACLs. On MacOS, the resource fork and other metadata are not used.
+ This means that resources will be lost and file type and creator codes will
+ not be correct. On Windows, file owners, ACLs and alternate data streams
+ are not copied.
.. function:: copyfile(src, dst)
- Copy the contents of the file named *src* to a file named *dst*. The
- destination location must be writable; otherwise, an :exc:`IOError` exception
+ Copy the contents (no metadata) of the file named *src* to a file named *dst*.
+ The destination location must be writable; otherwise, an :exc:`IOError` exception
will be raised. If *dst* already exists, it will be replaced. Special files
such as character or block devices and pipes cannot be copied with this
function. *src* and *dst* are path names given as strings.
Recursively move a file or directory to another location.
- If the destination is on our current filesystem, then simply use rename.
+ If the destination is on the current filesystem, then simply use rename.
Otherwise, copy src to the dst and then remove src.
.. exception:: Error
- This exception collects exceptions that raised during a mult-file operation. For
+ This exception collects exceptions that raised during a multi-file operation. For
:func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
*dstname*, *exception*).
+---------------------+---------------------------------+-------+--------------------+
| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | \(2) | :func:`divmod` |
+---------------------+---------------------------------+-------+--------------------+
-| ``pow(x, y)`` | *x* to the power *y* | | :func:`pow` |
+| ``pow(x, y)`` | *x* to the power *y* | (7) | :func:`pow` |
+---------------------+---------------------------------+-------+--------------------+
-| ``x ** y`` | *x* to the power *y* | | |
+| ``x ** y`` | *x* to the power *y* | (7) | |
+---------------------+---------------------------------+-------+--------------------+
.. index::
(6)
float also accepts the strings "nan" and "inf" with an optional prefix "+"
or "-" for Not a Number (NaN) and positive or negative infinity.
+
+(7)
+ Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for
+ programming languages.
+
All :class:`numbers.Real` types (:class:`int` and
.. method:: Popen.poll()
- Check if child process has terminated. Returns returncode attribute.
+ Check if child process has terminated. Set and return :attr:`returncode`
+ attribute.
.. method:: Popen.wait()
- Wait for child process to terminate. Returns returncode attribute.
+ Wait for child process to terminate. Set and return :attr:`returncode`
+ attribute.
.. method:: Popen.communicate(input=None)
*input* argument should be a string to be sent to the child process, or
``None``, if no data should be sent to the child.
- communicate() returns a tuple (stdout, stderr).
+ :meth:`communicate` returns a tuple ``(stdout, stderr)``.
Note that if you want to send data to the process's stdin, you need to create
the Popen object with ``stdin=PIPE``. Similarly, to get anything other than
``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
``stderr=PIPE`` too.
-.. note::
+ .. note::
- The data read is buffered in memory, so do not use this method if the data size
- is large or unlimited.
+ The data read is buffered in memory, so do not use this method if the data
+ size is large or unlimited.
-The following attributes are also available:
+The following attributes are also available:
.. attribute:: Popen.stdin
.. attribute:: Popen.returncode
- The child return code. A ``None`` value indicates that the process hasn't
- terminated yet. A negative value -N indicates that the child was terminated by
- signal N (Unix only).
+ The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
+ by :meth:`communicate`). A ``None`` value indicates that the process
+ hasn't terminated yet.
+
+ A negative value ``-N`` indicates that the child was terminated by signal
+ ``N`` (Unix only).
Replacing Older Functions with the subprocess Module
.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]])
- Return a file (or file-like) object that can be used as a temporary storage
+ Return a file-like object that can be used as a temporary storage
area. The file is created using :func:`mkstemp`. It will be destroyed as soon
as it is closed (including an implicit close when the object is garbage
collected). Under Unix, the directory entry for the file is removed immediately
The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`.
+ The returned object is a true file object on POSIX platforms. On other
+ platforms, it is a file-like object whose :attr:`file` attribute is the
+ underlying true file object.
+
.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir[, delete]]]]]])
the file a second time, while the named temporary file is still open, varies
across platforms (it can be so used on Unix; it cannot on Windows NT or later).
If *delete* is true (the default), the file is deleted as soon as it is closed.
+ The returned object is always a file-like object whose :attr:`file` attribute
+ is the underlying true file object.
.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]])
The resulting file has one additional method, :func:`rollover`, which causes the
file to roll over to an on-disk file regardless of its size.
+ The returned object is a file-like object whose :attr:`_file` attribute
+ is either a :class:`StringIO` object or a true file object, depending on
+ whether :func:`rollover` has been called.
+
.. function:: mkstemp([suffix[, prefix[, dir[, text]]]])
corresponding :file:`.pyc` or :file:`.pyo` file, meaning that if a ZIP archive
doesn't contain :file:`.pyc` files, importing may be rather slow.
-The available attributes of this module are:
-
-
-.. exception:: ZipImportError
-
- Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
- so it can be caught as :exc:`ImportError`, too.
-
-
-.. class:: zipimporter
-
- The class for importing ZIP files. See section :ref:`zipimporter-objects`
- for constructor details.
-
-
.. seealso::
`PKZIP Application Note <http://www.pkware.com/business_and_developers/developer/appnote/>`_
The PEP to add the import hooks that help this module work.
+This module defines an exception:
+
+.. exception:: ZipImportError
+
+ Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
+ so it can be caught as :exc:`ImportError`, too.
+
+
.. _zipimporter-objects:
zipimporter Objects
-------------------
+:class:`zipimporter` is the class for importing ZIP files.
.. class:: zipimporter(archivepath)
- Create a new zipimporter instance. *archivepath* must be a path to a zipfile.
+ Create a new zipimporter instance. *archivepath* must be a path to a ZIP file.
:exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
archive.
+ *archivepath* can also contain a path within the ZIP file -- the importer
+ object will then look under that path instead of the ZIP file root. For
+ example, an *archivepath* of :file:`foo/bar.zip/lib` will look for modules
+ in the :file:`lib` directory inside the ZIP file :file:`foo/bar.zip`
+ (provided that it exists).
+
.. method:: zipimporter.find_module(fullname[, path])
:exc:`ZipImportError` if it wasn't found.
-Examples
---------
+.. attribute:: zipimporter.archive
+
+ The file name of the importer's associated ZIP file.
+
+
+.. attribute:: zipimporter.prefix
+
+ The path within the ZIP file where modules are searched; see
+ :class:`zipimporter` for details.
+
.. _zipimport-examples:
+Examples
+--------
+
Here is an example that imports a module from a ZIP archive - note that the
:mod:`zipimport` module is not explicitly used. ::
Iterator objects also need to implement this method; they are required to return
themselves. For more information on iterator objects, see :ref:`typeiter`.
+
+.. method:: object.__reversed__(self)
+
+ Called (if present) by the :func:`reversed` builtin to implement
+ reverse iteration. It should return a new iterator object that iterates
+ over all the objects in the container in reverse order.
+
+ If the :meth:`__reversed__` method is not provided, the
+ :func:`reversed` builtin will fall back to using the sequence protocol
+ (:meth:`__len__` and :meth:`__getitem__`). Objects should normally
+ only provide :meth:`__reversed__` if they do not support the sequence
+ protocol and an efficient implementation of reverse iteration is possible.
+
+
The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
implemented as an iteration through a sequence. However, container objects can
supply the following special method with a more efficient implementation, which
mod = __import__(module_path_to_dotted_name(mod_name))
self.assertEquals(zi.get_source(TESTPACK), None)
self.assertEquals(zi.get_source(mod_name), None)
+
+ # test prefix and archivepath members
+ zi2 = zipimport.zipimporter(TEMP_ZIP + os.sep + TESTPACK)
+ self.assertEquals(zi2.archive, TEMP_ZIP)
+ self.assertEquals(zi2.prefix, TESTPACK + os.sep)
finally:
z.close()
os.remove(TEMP_ZIP)
projects / python / commitdiff