Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r72319 | georg.brandl | 2009-05-05 10:28:49 +0200 (Di, 05 Mai 2009) | 1 line
#1309567: fix linecache behavior of stripping subdirectories from paths when looking for relative filename matches. Also add a linecache test suite.
........
r72320 | georg.brandl | 2009-05-05 10:30:28 +0200 (Di, 05 Mai 2009) | 1 line
Add a news entry for r72319.
........
r72467 | georg.brandl | 2009-05-08 14:17:34 +0200 (Fr, 08 Mai 2009) | 1 line
Fix name.
........
r72661 | georg.brandl | 2009-05-15 10:03:03 +0200 (Fr, 15 Mai 2009) | 1 line
Fix example output for doctest-like demos.
........
r72675 | georg.brandl | 2009-05-16 13:13:21 +0200 (Sa, 16 Mai 2009) | 1 line
#6034: clarify __reversed__ doc.
........
r72676 | georg.brandl | 2009-05-16 13:14:46 +0200 (Sa, 16 Mai 2009) | 1 line
#6025: fix signature of parse().
........
r72677 | georg.brandl | 2009-05-16 13:18:55 +0200 (Sa, 16 Mai 2009) | 1 line
#6009: undocument default argument of Option as deprecated.
........
r72678 | georg.brandl | 2009-05-16 13:21:29 +0200 (Sa, 16 Mai 2009) | 1 line
#2856: document 2.x os.listdir() behavior for undecodable filenames.
........
r72679 | georg.brandl | 2009-05-16 13:24:41 +0200 (Sa, 16 Mai 2009) | 1 line
Fix about and bugs pages to match real workflow.
........
r72703 | georg.brandl | 2009-05-17 10:10:27 +0200 (So, 17 Mai 2009) | 1 line
part of #4144: fix exception message in console session.
........
r72708 | georg.brandl | 2009-05-17 10:24:29 +0200 (So, 17 Mai 2009) | 1 line
#6017: better document behavior of dictiterators when the dict is changed.
........
r72710 | georg.brandl | 2009-05-17 10:36:04 +0200 (So, 17 Mai 2009) | 1 line
#5942: Copy over flag table from dbm.rst which is clearer.
........
r72712 | georg.brandl | 2009-05-17 10:55:00 +0200 (So, 17 Mai 2009) | 1 line
#5935: mention that BROWSER is looked for in PATH.
........
r72801 | georg.brandl | 2009-05-20 20:31:14 +0200 (Mi, 20 Mai 2009) | 1 line
#6055: refer to "sqlite3" consistently.
........
r72802 | georg.brandl | 2009-05-20 20:35:27 +0200 (Mi, 20 Mai 2009) | 1 line
#6051: refer to email examples for better way to construct email messages.
........
r72820 | georg.brandl | 2009-05-22 09:23:32 +0200 (Fr, 22 Mai 2009) | 1 line
Use raise X(y).
........
r72822 | georg.brandl | 2009-05-22 11:33:25 +0200 (Fr, 22 Mai 2009) | 1 line
#6084: fix example.
........
r72824 | georg.brandl | 2009-05-22 11:43:17 +0200 (Fr, 22 Mai 2009) | 1 line
Fix references to file-related functions and methods (os.* vs file.*).
........
r72826 | georg.brandl | 2009-05-22 11:49:42 +0200 (Fr, 22 Mai 2009) | 1 line
Fix confusing wording.
........
r72827 | georg.brandl | 2009-05-22 11:50:30 +0200 (Fr, 22 Mai 2009) | 1 line
s/use/call/
........
r72828 | georg.brandl | 2009-05-22 11:58:48 +0200 (Fr, 22 Mai 2009) | 1 line
Correction in softspace behavior description.
........
r72830 | georg.brandl | 2009-05-22 12:40:00 +0200 (Fr, 22 Mai 2009) | 1 line
#6086: fix spelling and use a better exception to catch.
........
diff --git a/Doc/library/anydbm.rst b/Doc/library/anydbm.rst
index 36f0a7e..aad1776 100644
--- a/Doc/library/anydbm.rst
+++ b/Doc/library/anydbm.rst
@@ -27,19 +27,33 @@
Open the database file *filename* and return a corresponding object.
- If the database file already exists, the :mod:`whichdb` module is used to
- determine its type and the appropriate module is used; if it does not exist, the
- first module listed above that can be imported is used.
+ If the database file already exists, the :mod:`whichdb` module is used to
+ determine its type and the appropriate module is used; if it does not exist,
+ the first module listed above that can be imported is used.
- The optional *flag* argument can be ``'r'`` to open an existing database for
- reading only, ``'w'`` to open an existing database for reading and writing,
- ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will
- always create a new empty database. If not specified, the default value is
- ``'r'``.
+ The optional *flag* argument must be one of these values:
+
+ +---------+-------------------------------------------+
+ | Value | Meaning |
+ +=========+===========================================+
+ | ``'r'`` | Open existing database for reading only |
+ | | (default) |
+ +---------+-------------------------------------------+
+ | ``'w'`` | Open existing database for reading and |
+ | | writing |
+ +---------+-------------------------------------------+
+ | ``'c'`` | Open database for reading and writing, |
+ | | creating it if it doesn't exist |
+ +---------+-------------------------------------------+
+ | ``'n'`` | Always create a new, empty database, open |
+ | | for reading and writing |
+ +---------+-------------------------------------------+
+
+ If not specified, the default value is ``'r'``.
The optional *mode* argument is the Unix mode of the file, used only when the
- database has to be created. It defaults to octal ``0666`` (and will be modified
- by the prevailing umask).
+ database has to be created. It defaults to octal ``0666`` (and will be
+ modified by the prevailing umask).
.. exception:: error
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index c7c3b00..5da4c9d 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -341,9 +341,9 @@
>>> printf("Hello, %s\n", "World!")
Hello, World!
14
- >>> printf("Hello, %S", u"World!")
+ >>> printf("Hello, %S\n", u"World!")
Hello, World!
- 13
+ 14
>>> printf("%d bottles of beer\n", 42)
42 bottles of beer
19
@@ -358,7 +358,7 @@
that they can be converted to the required C data type::
>>> printf("An int %d, a double %f\n", 1234, c_double(3.14))
- Integer 1234, double 3.1400001049
+ An int 1234, a double 3.140000
31
>>>
@@ -414,9 +414,9 @@
Traceback (most recent call last):
File "<stdin>", line 1, in ?
ArgumentError: argument 2: exceptions.TypeError: wrong type
- >>> printf("%s %d %f", "X", 2, 3)
- X 2 3.00000012
- 12
+ >>> printf("%s %d %f\n", "X", 2, 3)
+ X 2 3.000000
+ 13
>>>
If you have defined your own classes which you pass to function calls, you have
diff --git a/Doc/library/email-examples.rst b/Doc/library/email-examples.rst
index f606f9b..c1b16da 100644
--- a/Doc/library/email-examples.rst
+++ b/Doc/library/email-examples.rst
@@ -1,3 +1,5 @@
+.. _email-examples:
+
:mod:`email`: Examples
----------------------
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index b989e8e..9764eae 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1398,7 +1398,7 @@
>>> zipped
[(1, 4), (2, 5), (3, 6)]
>>> x2, y2 = zip(*zipped)
- >>> x == x2, y == y2
+ >>> x == list(x2) and y == list(y2)
True
.. versionadded:: 2.0
@@ -1468,7 +1468,7 @@
names.
If you simply want to import a module (potentially within a package) by name,
- you can get it from :data:`sys.modules`::
+ you can call :func:`__import__` and then look it up in :data:`sys.modules`::
>>> import sys
>>> name = 'foo.bar.baz'
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index 4ef2ba7..a07a751 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -1077,10 +1077,10 @@
tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the
``options`` object that :mod:`optparse` builds as it parses the command line.
-* ``default`` (deprecated)
+* ``default``
The value to use for this option's destination if the option is not seen on the
- command line. Deprecated; use ``parser.set_defaults()`` instead.
+ command line. See also ``parser.set_defaults()``.
* ``nargs`` (default: 1)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 4d8fc4c..357b37e 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -354,7 +354,7 @@
is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as
the corresponding argument to the built-in :func:`open` function. The exit
status of the command (encoded in the format specified for :func:`wait`) is
- available as the return value of the :meth:`close` method of the file object,
+ available as the return value of the :meth:`~file.close` method of the file object,
except that when the exit status is zero (termination without errors), ``None``
is returned. Availability: Unix, Windows.
@@ -475,9 +475,9 @@
.. note::
This function is intended for low-level I/O and must be applied to a file
- descriptor as returned by :func:`open` or :func:`pipe`. To close a "file
+ descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file
object" returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, use its :meth:`close` method.
+ :func:`fdopen`, use its :meth:`~file.close` method.
.. function:: closerange(fd_low, fd_high)
@@ -604,8 +604,8 @@
.. note::
This function is intended for low-level I/O. For normal usage, use the built-in
- function :func:`open`, which returns a "file object" with :meth:`read` and
- :meth:`write` methods (and many more). To wrap a file descriptor in a "file
+ function :func:`open`, which returns a "file object" with :meth:`~file.read` and
+ :meth:`~file.write` methods (and many more). To wrap a file descriptor in a "file
object", use :func:`fdopen`.
@@ -634,22 +634,22 @@
.. note::
This function is intended for low-level I/O and must be applied to a file
- descriptor as returned by :func:`open` or :func:`pipe`. To read a "file object"
+ descriptor as returned by :func:`os.open` or :func:`pipe`. To read a "file object"
returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`read` or :meth:`readline`
- methods.
+ :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or
+ :meth:`~file.readline` methods.
.. function:: tcgetpgrp(fd)
Return the process group associated with the terminal given by *fd* (an open
- file descriptor as returned by :func:`open`). Availability: Unix.
+ file descriptor as returned by :func:`os.open`). Availability: Unix.
.. function:: tcsetpgrp(fd, pg)
Set the process group associated with the terminal given by *fd* (an open file
- descriptor as returned by :func:`open`) to *pg*. Availability: Unix.
+ descriptor as returned by :func:`os.open`) to *pg*. Availability: Unix.
.. function:: ttyname(fd)
@@ -667,13 +667,13 @@
.. note::
This function is intended for low-level I/O and must be applied to a file
- descriptor as returned by :func:`open` or :func:`pipe`. To write a "file
+ descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
object" returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write`
- method.
+ :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
+ :meth:`~file.write` method.
The following constants are options for the *flags* parameter to the
-:func:`open` function. They can be combined using the bitwise OR operator
+:func:`~os.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.
@@ -752,7 +752,7 @@
.. note::
Using :func:`access` to check if a user is authorized to e.g. open a file before
- actually doing so using :func:`open` creates a security hole, because the user
+ actually doing so using :func:`open` creates a security hole, because the user
might exploit the short time interval between checking and opening the file to
manipulate it.
@@ -929,7 +929,8 @@
.. versionchanged:: 2.3
On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
- a list of Unicode objects.
+ a list of Unicode objects. Undecodable filenames will still be returned as
+ string objects.
.. function:: lstat(path)
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 56cb407..4e18ab1 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -1,4 +1,3 @@
-
:mod:`shelve` --- Python object persistence
===========================================
@@ -40,7 +39,7 @@
entries are written back (there is no way to determine which accessed
entries are mutable, nor which ones were actually mutated).
-Shelve objects support all methods supported by dictionaries. This eases the
+Shelf objects support all methods supported by dictionaries. This eases the
transition from dictionary based scripts to those requiring persistent storage.
One additional method is supported:
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index 8facc9a..4c1c614 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -380,3 +380,8 @@
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
+.. note::
+
+ In general, you will want to use the :mod:`email` package's features to
+ construct an email message, which you can then convert to a string and send
+ via :meth:`sendmail`; see :ref:`email-examples`.
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index d031c90..392a130 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -15,7 +15,7 @@
application using SQLite and then port the code to a larger database such as
PostgreSQL or Oracle.
-pysqlite was written by Gerhard Häring and provides a SQL interface compliant
+sqlite3 was written by Gerhard Häring and provides a SQL interface compliant
with the DB-API 2.0 specification described by :pep:`249`.
To use the module, you must first create a :class:`Connection` object that
@@ -52,8 +52,9 @@
Instead, use the DB-API's parameter substitution. Put ``?`` as a placeholder
wherever you want to use a value, and then provide a tuple of values as the
-second argument to the cursor's :meth:`~Cursor.execute` method. (Other database modules
-may use a different placeholder, such as ``%s`` or ``:1``.) For example::
+second argument to the cursor's :meth:`~Cursor.execute` method. (Other database
+modules may use a different placeholder, such as ``%s`` or ``:1``.) For
+example::
# Never do this -- insecure!
symbol = 'IBM'
@@ -92,11 +93,12 @@
.. seealso::
http://www.pysqlite.org
- The pysqlite web page.
+ The pysqlite web page -- sqlite3 is developed externally under the name
+ "pysqlite".
http://www.sqlite.org
- The SQLite web page; the documentation describes the syntax and the available
- data types for the supported SQL dialect.
+ The SQLite web page; the documentation describes the syntax and the
+ available data types for the supported SQL dialect.
:pep:`249` - Database API Specification 2.0
PEP written by Marc-André Lemburg.
@@ -802,10 +804,10 @@
...``, ``VACUUM``, ``PRAGMA``, the :mod:`sqlite3` module will commit implicitly
before executing that command. There are two reasons for doing that. The first
is that some of these commands don't work within transactions. The other reason
-is that pysqlite needs to keep track of the transaction state (if a transaction
+is that sqlite3 needs to keep track of the transaction state (if a transaction
is active or not).
-You can control which kind of ``BEGIN`` statements pysqlite implicitly executes
+You can control which kind of ``BEGIN`` statements sqlite3 implicitly executes
(or none at all) via the *isolation_level* parameter to the :func:`connect`
call, or via the :attr:`isolation_level` property of connections.
@@ -817,8 +819,8 @@
-Using pysqlite efficiently
---------------------------
+Using :mod:`sqlite3` efficiently
+--------------------------------
Using shortcut methods
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 56b6312..7013f15 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1955,7 +1955,7 @@
note for :meth:`dict.items`.
Using :meth:`iteritems` while adding or deleting entries in the dictionary
- will raise a :exc:`RuntimeError`.
+ may raise a :exc:`RuntimeError` or fail to iterate over all entries.
.. versionadded:: 2.2
@@ -1965,7 +1965,7 @@
:meth:`dict.items`.
Using :meth:`iterkeys` while adding or deleting entries in the dictionary
- will raise a :exc:`RuntimeError`.
+ may raise a :exc:`RuntimeError` or fail to iterate over all entries.
.. versionadded:: 2.2
@@ -1975,7 +1975,8 @@
:meth:`dict.items`.
Using :meth:`itervalues` while adding or deleting entries in the
- dictionary will raise a :exc:`RuntimeError`.
+ dictionary may raise a :exc:`RuntimeError` or fail to iterate over all
+ entries.
.. versionadded:: 2.2
diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
index 56aba5a..fc0a004 100644
--- a/Doc/library/webbrowser.rst
+++ b/Doc/library/webbrowser.rst
@@ -22,7 +22,7 @@
of browsers to try in order. When the value of a list part contains the string
``%s``, then it is interpreted as a literal browser command line to be used
with the argument URL substituted for ``%s``; if the part does not contain
-``%s``, it is simply interpreted as the name of the browser to launch.
+``%s``, it is simply interpreted as the name of the browser to launch. [1]_
For non-Unix platforms, or when a remote browser is available on Unix, the
controlling process will not wait for the user to finish with the browser, but
@@ -201,3 +201,8 @@
.. versionadded:: 2.5
+
+.. rubric:: Footnotes
+
+.. [1] Executables named here without a full path will be searched in the
+ directories given in the :envvar:`PATH` environment variable.
diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst
index b127f04..cb49c02 100644
--- a/Doc/library/xml.dom.minidom.rst
+++ b/Doc/library/xml.dom.minidom.rst
@@ -30,7 +30,7 @@
The :func:`parse` function can take either a filename or an open file object.
-.. function:: parse(filename_or_file, parser)
+.. function:: parse(filename_or_file[, parser[, bufsize]])
Return a :class:`Document` from the given input. *filename_or_file* may be
either a file name, or a file-like object. *parser*, if given, must be a SAX2