From 7f044315f49836fbe472b53e089e733439ca5ece Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Sun, 6 Jan 2008 17:05:40 +0000 Subject: Merged revisions 59774-59783 via svnmerge from 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. ........ --- Doc/ACKS.txt | 1 + Doc/library/csv.rst | 11 +++++++++-- Doc/library/functions.rst | 13 +++++++++---- Doc/library/inspect.rst | 5 +++++ Doc/library/shutil.rst | 19 +++++++++++------- Doc/library/stdtypes.rst | 9 +++++++-- Doc/library/subprocess.rst | 25 ++++++++++++++---------- Doc/library/tempfile.rst | 12 +++++++++++- Doc/library/zipimport.rst | 47 ++++++++++++++++++++++++++++----------------- Doc/reference/datamodel.rst | 14 ++++++++++++++ 10 files changed, 112 insertions(+), 44 deletions(-) (limited to 'Doc') diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index 32943bddd5..7344cf8dac 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -158,6 +158,7 @@ docs@python.org), and we'll be glad to correct the problem. * Jim Roskind * Guido van Rossum * Donald Wallace Rouse II + * Mark Russell * Nick Russo * Chris Ryland * Constantina S. diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 678d4d70a0..56972f4af8 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -211,7 +211,6 @@ The :mod:`csv` module defines the following classes: 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 @@ -224,9 +223,17 @@ The :class:`Sniffer` class provides two methods: 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. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 9463ba76d5..e7add3a38c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -232,6 +232,9 @@ available. They are listed here in alphabetical order. 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]]) @@ -313,7 +316,8 @@ available. They are listed here in alphabetical order. 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) @@ -907,9 +911,10 @@ available. They are listed here in alphabetical order. .. 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]) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 5cdec20bf7..e5008f666d 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -180,6 +180,11 @@ attributes: 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) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 3275179c4e..f80c893180 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -17,16 +17,21 @@ copying and removal. For operations on individual files, see also the :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. @@ -106,13 +111,13 @@ copying and removal. For operations on individual files, see also the 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*). diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 92183a4883..fc96f45ec8 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -314,9 +314,9 @@ numeric operations have a higher priority than comparison operations): +---------------------+---------------------------------+-------+--------------------+ | ``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:: @@ -350,6 +350,11 @@ Notes: (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 diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index d2604738ae..c876efe4f5 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -172,12 +172,14 @@ Instances of the :class:`Popen` class have the following methods: .. 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) @@ -187,20 +189,20 @@ Instances of the :class:`Popen` class have the following methods: *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 @@ -227,9 +229,12 @@ The following attributes are also available: .. 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 diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst index 74c032ff27..e38dbab1cb 100644 --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -34,7 +34,7 @@ The module defines the following user-callable functions: .. 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 @@ -49,6 +49,10 @@ The module defines the following user-callable functions: 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]]]]]]) @@ -59,6 +63,8 @@ The module defines the following user-callable functions: 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]]]]]]) @@ -71,6 +77,10 @@ The module defines the following user-callable functions: 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]]]]) diff --git a/Doc/library/zipimport.rst b/Doc/library/zipimport.rst index 6845bf7a43..ed9c631469 100644 --- a/Doc/library/zipimport.rst +++ b/Doc/library/zipimport.rst @@ -27,21 +27,6 @@ Any files may be present in the ZIP archive, but only files :file:`.py` and 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 `_ @@ -57,18 +42,33 @@ The available attributes of this module are: 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]) @@ -110,11 +110,22 @@ zipimporter Objects :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. :: diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 6acd25a760..9c2d7cd584 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1688,6 +1688,20 @@ container; for mappings, :meth:`__iter__` should be the same as 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 -- cgit v1.2.1