From af265f4977e9bcb66d2c17f8230eb8c9d63505e3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 7 Dec 2008 15:06:20 +0000 Subject: Merged revisions 67531-67532,67538,67553-67554,67556-67557,67571,67574-67575,67579-67580,67591,67597,67608,67631 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67531 | georg.brandl | 2008-12-04 19:54:05 +0100 (Thu, 04 Dec 2008) | 2 lines Add reference to enumerate() to indices example. ........ r67532 | georg.brandl | 2008-12-04 19:59:16 +0100 (Thu, 04 Dec 2008) | 2 lines Add another heapq example. ........ r67538 | georg.brandl | 2008-12-04 22:28:16 +0100 (Thu, 04 Dec 2008) | 2 lines Clarification to avoid confusing output with file descriptors. ........ r67553 | georg.brandl | 2008-12-05 08:49:49 +0100 (Fri, 05 Dec 2008) | 2 lines #4408: document regex.groups. ........ r67554 | georg.brandl | 2008-12-05 08:52:26 +0100 (Fri, 05 Dec 2008) | 2 lines #4409: fix asterisks looking like footnotes. ........ r67556 | georg.brandl | 2008-12-05 09:02:17 +0100 (Fri, 05 Dec 2008) | 2 lines #4441: improve doc for os.open() flags. ........ r67557 | georg.brandl | 2008-12-05 09:06:57 +0100 (Fri, 05 Dec 2008) | 2 lines Add an index entry for "subclassing immutable types". ........ r67571 | georg.brandl | 2008-12-05 10:13:45 +0100 (Fri, 05 Dec 2008) | 2 lines Use markup. ........ r67574 | georg.brandl | 2008-12-05 10:25:32 +0100 (Fri, 05 Dec 2008) | 2 lines #4441 followup: Add link to open() docs for Windows. ........ r67575 | georg.brandl | 2008-12-05 12:34:51 +0100 (Fri, 05 Dec 2008) | 2 lines #4544: add `dedent` to textwrap.__all__. ........ r67579 | georg.brandl | 2008-12-05 16:29:39 +0100 (Fri, 05 Dec 2008) | 2 lines #4517: add "special method" glossary entry and clarify when __getattribute__ is bypassed. ........ r67580 | georg.brandl | 2008-12-05 16:32:29 +0100 (Fri, 05 Dec 2008) | 2 lines #4478: document that copyfile() can raise Error. ........ r67591 | georg.brandl | 2008-12-05 19:00:06 +0100 (Fri, 05 Dec 2008) | 2 lines Followup to #4511: add link from decorator glossary entry to definition. ........ r67597 | georg.brandl | 2008-12-05 20:03:19 +0100 (Fri, 05 Dec 2008) | 2 lines Remove confusing sentence part. ........ r67608 | georg.brandl | 2008-12-06 12:57:12 +0100 (Sat, 06 Dec 2008) | 2 lines Follow-up to #4488: document PIPE and STDOUT properly. ........ r67631 | georg.brandl | 2008-12-07 12:54:07 +0100 (Sun, 07 Dec 2008) | 2 lines Add link to the favicon to the docs. ........ --- Doc/documenting/rest.rst | 2 +- Doc/glossary.rst | 10 +++++++- Doc/library/getopt.rst | 4 ++-- Doc/library/heapq.rst | 15 ++++++++++++ Doc/library/os.rst | 22 ++++++++--------- Doc/library/re.rst | 5 ++++ Doc/library/shutil.rst | 3 ++- Doc/library/subprocess.rst | 52 ++++++++++++++++++++++++++--------------- Doc/reference/datamodel.rst | 5 ++-- Doc/tools/sphinxext/layout.html | 8 ++++++- Doc/tutorial/controlflow.rst | 8 +++++-- Lib/textwrap.py | 2 +- 12 files changed, 94 insertions(+), 42 deletions(-) diff --git a/Doc/documenting/rest.rst b/Doc/documenting/rest.rst index e018373..9b6b89b 100644 --- a/Doc/documenting/rest.rst +++ b/Doc/documenting/rest.rst @@ -98,7 +98,7 @@ Source Code ----------- Literal code blocks are introduced by ending a paragraph with the special marker -``::``. The literal block must be indented, to be able to include blank lines:: +``::``. The literal block must be indented:: This is a normal text paragraph. The next paragraph is a code sample:: diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 6100aff..eb2614f 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -116,7 +116,9 @@ Glossary def f(...): ... - The same concept exists for classes, but is less commonly used there. + The same concept exists for classes, but is less commonly used there. See + the documentation for :ref:`function definitions ` and + :ref:`class definitions ` for more about decorators. descriptor Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or @@ -479,6 +481,12 @@ Glossary when several are given, such as in ``variable_name[1:3:5]``. The bracket (subscript) notation uses :class:`slice` objects internally. + special method + A method that is called implicitly by Python to execute a certain + operation on a type, such as addition. Such methods have names starting + and ending with double underscores. Special methods are documented in + :ref:`specialnames`. + statement A statement is part of a suite (a "block" of code). A statement is either an :term:`expression` or a one of several constructs with a keyword, such diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst index 4bf5bef..94ba90e 100644 --- a/Doc/library/getopt.rst +++ b/Doc/library/getopt.rst @@ -63,8 +63,8 @@ exception: non-option argument is encountered. If the first character of the option string is '+', or if the environment - variable POSIXLY_CORRECT is set, then option processing stops as soon as a - non-option argument is encountered. + variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as + soon as a non-option argument is encountered. .. exception:: GetoptError diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index 8e5ce95..5138c83 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -86,6 +86,21 @@ Example of use: >>> data == ordered True +Using a heap to insert items at the correct place in a priority queue: + + >>> heap = [] + >>> data = [(1, 'J'), (4, 'N'), (3, 'H'), (2, 'O')] + >>> for item in data: + ... heappush(heap, item) + ... + >>> while heap: + ... print(heappop(heap)[1]) + J + O + H + N + + The module also offers three general purpose functions based on heaps. diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 3cc77bc..1c69e25 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -567,10 +567,11 @@ by file descriptors. :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write` method. -The following data items are available for use in constructing the *flags* -parameter to the :func:`open` function. Some items will not be available on all -platforms. For descriptions of their availability and use, consult -:manpage:`open(2)`. +The following constants are options for the *flags* parameter to the +:func:`open` function. They can be combined using the bitwise OR operator +``|``. Some of them are not available on all platforms. For descriptions of +their availability and use, consult the :manpage:`open(2)` manual page on Unix +or `the MSDN ` on Windows. .. data:: O_RDONLY @@ -581,8 +582,7 @@ platforms. For descriptions of their availability and use, consult O_EXCL O_TRUNC - Options for the *flag* argument to the :func:`open` function. These can be - combined using the bitwise OR operator ``|``. Availability: Unix, Windows. + These constants are available on Unix and Windows. .. data:: O_DSYNC @@ -594,8 +594,7 @@ platforms. For descriptions of their availability and use, consult O_SHLOCK O_EXLOCK - More options for the *flag* argument to the :func:`open` function. Availability: - Unix. + These constants are only available on Unix. .. data:: O_BINARY @@ -606,8 +605,7 @@ platforms. For descriptions of their availability and use, consult O_SEQUENTIAL O_TEXT - Options for the *flag* argument to the :func:`open` function. These can be - combined using the bitwise OR operator ``|``. Availability: Windows. + These constants are only available on Windows. .. data:: O_ASYNC @@ -616,8 +614,8 @@ platforms. For descriptions of their availability and use, consult O_NOFOLLOW O_NOATIME - Options for the *flag* argument to the :func:`open` function. These are - GNU extensions and not present if they are not defined by the C library. + These constants are GNU extensions and not present if they are not defined by + the C library. .. data:: SEEK_SET diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 2020577..ce52185 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -770,6 +770,11 @@ attributes: were provided. +.. attribute:: RegexObject.groups + + The number of capturing groups in the pattern. + + .. attribute:: RegexObject.groupindex A dictionary mapping any symbolic group names defined by ``(?P)`` to group diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index c4b97a0..ac52ce4 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -43,7 +43,8 @@ copying and removal. For operations on individual files, see also the Copy the contents (no metadata) of the file named *src* to a file named *dst*. *dst* must be the complete target file name; look at :func:`copy` for a copy that - accepts a target directory path. + accepts a target directory path. If *src* and *dst* are the same files, + :exc:`Error` is raised. 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 diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 68f8bfc..6aff816 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -68,13 +68,13 @@ This module defines one class called :class:`Popen`: specified by the :envvar:`COMSPEC` environment variable. *stdin*, *stdout* and *stderr* specify the executed programs' standard input, - standard output and standard error file handles, respectively. Valid values are - ``PIPE``, an existing file descriptor (a positive integer), an existing file - object, and ``None``. ``PIPE`` indicates that a new pipe to the child should be - created. With ``None``, no redirection will occur; the child's file handles - will be inherited from the parent. Additionally, *stderr* can be ``STDOUT``, - which indicates that the stderr data from the applications should be captured - into the same file handle as for stdout. + standard output and standard error file handles, respectively. Valid values + are :data:`PIPE`, an existing file descriptor (a positive integer), an + existing file object, and ``None``. :data:`PIPE` indicates that a new pipe + to the child should be created. With ``None``, no redirection will occur; + the child's file handles will be inherited from the parent. Additionally, + *stderr* can be :data:`STDOUT`, which indicates that the stderr data from the + applications should be captured into the same file handle as for stdout. If *preexec_fn* is set to a callable object, this object will be called in the child process just before the child is executed. (Unix only) @@ -114,6 +114,20 @@ This module defines one class called :class:`Popen`: of the main window and priority for the new process. (Windows only) +.. data:: PIPE + + Special value that can be used as the *stdin*, *stdout* or *stderr* argument + to :class:`Popen` and indicates that a pipe to the standard stream should be + opened. + + +.. data:: STDOUT + + Special value that can be used as the *stderr* argument to :class:`Popen` and + indicates that standard error should go into the same handle as standard + output. + + Convenience Functions ^^^^^^^^^^^^^^^^^^^^^ @@ -229,7 +243,7 @@ Instances of the :class:`Popen` class have the following methods: *input* argument should be a byte string to be sent to the child process, or ``None``, if no data should be sent to the child. - :meth:`communicate` returns a tuple ``(stdout, stderr)``. + :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``. 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 @@ -277,20 +291,21 @@ The following attributes are also available: .. attribute:: Popen.stdin - If the *stdin* argument is ``PIPE``, this attribute is a file object that - provides input to the child process. Otherwise, it is ``None``. + If the *stdin* argument was :data:`PIPE`, this attribute is a file object + that provides input to the child process. Otherwise, it is ``None``. .. attribute:: Popen.stdout - If the *stdout* argument is ``PIPE``, this attribute is a file object that - provides output from the child process. Otherwise, it is ``None``. + If the *stdout* argument was :data:`PIPE`, this attribute is a file object + that provides output from the child process. Otherwise, it is ``None``. .. attribute:: Popen.stderr - If the *stderr* argument is ``PIPE``, this attribute is file object that - provides error output from the child process. Otherwise, it is ``None``. + If the *stderr* argument was :data:`PIPE`, this attribute is a file object + that provides error output from the child process. Otherwise, it is + ``None``. .. attribute:: Popen.pid @@ -374,8 +389,8 @@ A more realistic example would look like this:: print("Execution failed:", e, file=sys.stderr) -Replacing os.spawn\* -^^^^^^^^^^^^^^^^^^^^ +Replacing the os.spawn family +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ P_NOWAIT example:: @@ -402,8 +417,8 @@ Environment example:: Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"}) -Replacing os.popen\* -^^^^^^^^^^^^^^^^^^^^ +Replacing os.popen +^^^^^^^^^^^^^^^^^^ :: @@ -416,4 +431,3 @@ Replacing os.popen\* pipe = os.popen(cmd, 'w', bufsize) ==> pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin - diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 94bcb1b..3200ed8 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1009,9 +1009,10 @@ of this is the :class:`NodeList` interface in the W3C's Document Object Model.) Basic customization ------------------- - .. method:: object.__new__(cls[, ...]) + .. index:: pair: subclassing; immutable types + Called to create a new instance of class *cls*. :meth:`__new__` is a static method (special-cased so you need not declare it as such) that takes the class of which an instance was requested as its first argument. The remaining @@ -1915,7 +1916,7 @@ the instance when looking up special methods:: True In addition to bypassing any instance attributes in the interest of -correctness, implicit special method lookup may also bypass the +correctness, implicit special method lookup generally also bypasses the :meth:`__getattribute__` method even of the object's metaclass:: >>> class Meta(type): diff --git a/Doc/tools/sphinxext/layout.html b/Doc/tools/sphinxext/layout.html index a6afd15..6029871 100644 --- a/Doc/tools/sphinxext/layout.html +++ b/Doc/tools/sphinxext/layout.html @@ -1,4 +1,10 @@ {% extends "!layout.html" %} {% block rootrellink %} -
  • {{ shorttitle }}{{ reldelim1 }}
    • +
    • +
  • {{ shorttitle }}{{ reldelim1 }}
    • +{% endblock %} +{% block extrahead %} + +{{ super() }} {% endblock %} diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 2a55cf1..000d9cb 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -113,8 +113,8 @@ increment (even negative; sometimes this is called the 'step'):: range(-10, -100, -30) -10, -40, -70 -To iterate over the indices of a sequence, combine :func:`range` and :func:`len` -as follows:: +To iterate over the indices of a sequence, you can combine :func:`range` and +:func:`len` as follows:: >>> a = ['Mary', 'had', 'a', 'little', 'lamb'] >>> for i in range(len(a)): @@ -126,6 +126,9 @@ as follows:: 3 little 4 lamb +In most such cases, however, it is convenient to use the :func:`enumerate` +function, see :ref:`tut-loopidioms`. + A strange thing happens if you just print a range:: >>> print(range(10)) @@ -148,6 +151,7 @@ is another; it creates lists from iterables:: Later we will see more functions that return iterables and take iterables as argument. + .. _tut-break: :keyword:`break` and :keyword:`continue` Statements, and :keyword:`else` Clauses on Loops diff --git a/Lib/textwrap.py b/Lib/textwrap.py index 6a2021d..867b9d9 100644 --- a/Lib/textwrap.py +++ b/Lib/textwrap.py @@ -9,7 +9,7 @@ __revision__ = "$Id$" import string, re -__all__ = ['TextWrapper', 'wrap', 'fill'] +__all__ = ['TextWrapper', 'wrap', 'fill', 'dedent'] # Hardcode the recognized whitespace characters to the US-ASCII # whitespace characters. The main reason for doing this is that in -- cgit v0.12