[Python-checkins] r67646 - in python/branches/release30-maint: Doc/documenting/rest.rst Doc/glossary.rst Doc/library/getopt.rst Doc/library/heapq.rst Doc/library/os.rst Doc/library/re.rst Doc/library/shutil.rst Doc/library/subprocess.rst Doc/reference/datamodel.rst Doc/tools/sphinxext/layout.html Doc/tutorial/controlflow.rst Lib/textwrap.py
georg.brandl
python-checkins at python.org
Sun Dec 7 17:02:32 CET 2008
Author: georg.brandl
Date: Sun Dec 7 17:02:32 2008
New Revision: 67646
Log:
Manual merge of r67636 from py3k branch:
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.
.........
Modified:
python/branches/release30-maint/Doc/documenting/rest.rst
python/branches/release30-maint/Doc/glossary.rst
python/branches/release30-maint/Doc/library/getopt.rst
python/branches/release30-maint/Doc/library/heapq.rst
python/branches/release30-maint/Doc/library/os.rst
python/branches/release30-maint/Doc/library/re.rst
python/branches/release30-maint/Doc/library/shutil.rst
python/branches/release30-maint/Doc/library/subprocess.rst
python/branches/release30-maint/Doc/reference/datamodel.rst
python/branches/release30-maint/Doc/tools/sphinxext/layout.html
python/branches/release30-maint/Doc/tutorial/controlflow.rst
python/branches/release30-maint/Lib/textwrap.py
Modified: python/branches/release30-maint/Doc/documenting/rest.rst
==============================================================================
--- python/branches/release30-maint/Doc/documenting/rest.rst (original)
+++ python/branches/release30-maint/Doc/documenting/rest.rst Sun Dec 7 17:02:32 2008
@@ -98,7 +98,7 @@
-----------
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::
Modified: python/branches/release30-maint/Doc/glossary.rst
==============================================================================
--- python/branches/release30-maint/Doc/glossary.rst (original)
+++ python/branches/release30-maint/Doc/glossary.rst Sun Dec 7 17:02:32 2008
@@ -116,7 +116,9 @@
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 <function>` and
+ :ref:`class definitions <class>` for more about decorators.
descriptor
Any object which defines the methods :meth:`__get__`, :meth:`__set__`, or
@@ -479,6 +481,12 @@
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
Modified: python/branches/release30-maint/Doc/library/getopt.rst
==============================================================================
--- python/branches/release30-maint/Doc/library/getopt.rst (original)
+++ python/branches/release30-maint/Doc/library/getopt.rst Sun Dec 7 17:02:32 2008
@@ -63,8 +63,8 @@
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
Modified: python/branches/release30-maint/Doc/library/heapq.rst
==============================================================================
--- python/branches/release30-maint/Doc/library/heapq.rst (original)
+++ python/branches/release30-maint/Doc/library/heapq.rst Sun Dec 7 17:02:32 2008
@@ -86,6 +86,21 @@
>>> 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.
Modified: python/branches/release30-maint/Doc/library/os.rst
==============================================================================
--- python/branches/release30-maint/Doc/library/os.rst (original)
+++ python/branches/release30-maint/Doc/library/os.rst Sun Dec 7 17:02:32 2008
@@ -567,10 +567,11 @@
: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 <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>` on Windows.
.. data:: O_RDONLY
@@ -581,8 +582,7 @@
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 @@
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 @@
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 @@
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
Modified: python/branches/release30-maint/Doc/library/re.rst
==============================================================================
--- python/branches/release30-maint/Doc/library/re.rst (original)
+++ python/branches/release30-maint/Doc/library/re.rst Sun Dec 7 17:02:32 2008
@@ -770,6 +770,11 @@
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<id>)`` to group
Modified: python/branches/release30-maint/Doc/library/shutil.rst
==============================================================================
--- python/branches/release30-maint/Doc/library/shutil.rst (original)
+++ python/branches/release30-maint/Doc/library/shutil.rst Sun Dec 7 17:02:32 2008
@@ -43,7 +43,8 @@
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
Modified: python/branches/release30-maint/Doc/library/subprocess.rst
==============================================================================
--- python/branches/release30-maint/Doc/library/subprocess.rst (original)
+++ python/branches/release30-maint/Doc/library/subprocess.rst Sun Dec 7 17:02:32 2008
@@ -68,13 +68,13 @@
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 @@
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 @@
*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 @@
.. 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 @@
print("Execution failed:", e, file=sys.stderr)
-Replacing os.spawn\*
-^^^^^^^^^^^^^^^^^^^^
+Replacing the os.spawn family
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
P_NOWAIT example::
@@ -402,8 +417,8 @@
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
-Replacing os.popen\*
-^^^^^^^^^^^^^^^^^^^^
+Replacing os.popen
+^^^^^^^^^^^^^^^^^^
::
@@ -416,4 +431,3 @@
pipe = os.popen(cmd, 'w', bufsize)
==>
pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
-
Modified: python/branches/release30-maint/Doc/reference/datamodel.rst
==============================================================================
--- python/branches/release30-maint/Doc/reference/datamodel.rst (original)
+++ python/branches/release30-maint/Doc/reference/datamodel.rst Sun Dec 7 17:02:32 2008
@@ -1009,9 +1009,10 @@
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 @@
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):
Modified: python/branches/release30-maint/Doc/tools/sphinxext/layout.html
==============================================================================
--- python/branches/release30-maint/Doc/tools/sphinxext/layout.html (original)
+++ python/branches/release30-maint/Doc/tools/sphinxext/layout.html Sun Dec 7 17:02:32 2008
@@ -1,4 +1,10 @@
{% extends "!layout.html" %}
{% block rootrellink %}
-<li><img src="{{ pathto('_static/py.png', 1) }}" alt="" style="vertical-align: middle; margin-top: -1px"/></li><li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li>
+ <li><img src="{{ pathto('_static/py.png', 1) }}" alt=""
+ style="vertical-align: middle; margin-top: -1px"/></li>
+ <li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li>
+{% endblock %}
+{% block extrahead %}
+ <link rel="shortcut icon" type="image/png" href="{{ pathto('_static/py.png', 1) }}" />
+{{ super() }}
{% endblock %}
Modified: python/branches/release30-maint/Doc/tutorial/controlflow.rst
==============================================================================
--- python/branches/release30-maint/Doc/tutorial/controlflow.rst (original)
+++ python/branches/release30-maint/Doc/tutorial/controlflow.rst Sun Dec 7 17:02:32 2008
@@ -113,8 +113,8 @@
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 @@
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 @@
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
Modified: python/branches/release30-maint/Lib/textwrap.py
==============================================================================
--- python/branches/release30-maint/Lib/textwrap.py (original)
+++ python/branches/release30-maint/Lib/textwrap.py Sun Dec 7 17:02:32 2008
@@ -9,7 +9,7 @@
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
More information about the Python-checkins
mailing list