Merged revisions 85548,85572-85573,85606,85609-85612,85614-85616 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r85548 | georg.brandl | 2010-10-15 21:46:19 +0200 (Fr, 15 Okt 2010) | 1 line
#10072: assume a bit less knowledge of the FTP protocol in the ftplib docs.
........
r85572 | georg.brandl | 2010-10-16 20:51:05 +0200 (Sa, 16 Okt 2010) | 1 line
#10122: typo fix.
........
r85573 | georg.brandl | 2010-10-16 20:53:08 +0200 (Sa, 16 Okt 2010) | 1 line
#10124: typo fix.
........
r85606 | georg.brandl | 2010-10-17 08:32:59 +0200 (So, 17 Okt 2010) | 1 line
#10058: tweak wording about exception returns.
........
r85609 | georg.brandl | 2010-10-17 11:19:03 +0200 (So, 17 Okt 2010) | 1 line
#8556: use less confusing mapping key in example.
........
r85610 | georg.brandl | 2010-10-17 11:23:05 +0200 (So, 17 Okt 2010) | 1 line
#8686: remove potentially confusing wording that does not add any value.
........
r85611 | georg.brandl | 2010-10-17 11:33:24 +0200 (So, 17 Okt 2010) | 1 line
#8811: small fixes to sqlite3 docs.
........
r85612 | georg.brandl | 2010-10-17 11:37:54 +0200 (So, 17 Okt 2010) | 1 line
#8855: add shelve security warning.
........
r85614 | georg.brandl | 2010-10-17 11:46:11 +0200 (So, 17 Okt 2010) | 1 line
#8968: add actual name of token constants.
........
r85615 | georg.brandl | 2010-10-17 12:05:13 +0200 (So, 17 Okt 2010) | 1 line
#459007: merge info from PC/getpathp.c and using/windows.rst to document the forming of sys.path under Windows.
........
r85616 | georg.brandl | 2010-10-17 12:07:29 +0200 (So, 17 Okt 2010) | 1 line
Fix copy-paste error in example.
........
diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst
index b497e1f..29c3914 100644
--- a/Doc/library/audioop.rst
+++ b/Doc/library/audioop.rst
@@ -236,8 +236,8 @@
def mul_stereo(sample, width, lfactor, rfactor):
lsample = audioop.tomono(sample, width, 1, 0)
rsample = audioop.tomono(sample, width, 0, 1)
- lsample = audioop.mul(sample, width, lfactor)
- rsample = audioop.mul(sample, width, rfactor)
+ lsample = audioop.mul(lsample, width, lfactor)
+ rsample = audioop.mul(rsample, width, rfactor)
lsample = audioop.tostereo(lsample, width, 1, 0)
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index 899d7e5..d51e230 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -528,16 +528,11 @@
Return an upper bound on :meth:`ratio` relatively quickly.
- This isn't defined beyond that it is an upper bound on :meth:`ratio`, and
- is faster to compute.
-
.. method:: real_quick_ratio()
Return an upper bound on :meth:`ratio` very quickly.
- This isn't defined beyond that it is an upper bound on :meth:`ratio`, and
- is faster to compute than either :meth:`ratio` or :meth:`quick_ratio`.
The three methods that return the ratio of matching to total characters can give
different results due to differing levels of approximation, although
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 4b25d85..b6db983 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -91,18 +91,21 @@
.. exception:: error_temp
- Exception raised when an error code in the range 400--499 is received.
+ Exception raised when an error code signifying a temporary error (response
+ codes in the range 400--499) is received.
.. exception:: error_perm
- Exception raised when an error code in the range 500--599 is received.
+ Exception raised when an error code signifying a permanent error (response
+ codes in the range 500--599) is received.
.. exception:: error_proto
- Exception raised when a reply is received from the server that does not
- begin with a digit in the range 1--5.
+ Exception raised when a reply is received from the server that does not fit
+ the response specifications of the File Transfer Protocol, i.e. begin with a
+ digit in the range 1--5.
.. data:: all_errors
@@ -198,9 +201,9 @@
.. method:: FTP.voidcmd(command)
- Send a simple command string to the server and handle the response. Return
- nothing if a response code in the range 200--299 is received. Raise an exception
- otherwise.
+ Send a simple command string to the server and handle the response. Return
+ nothing if a response code corresponding to success (codes in the range
+ 200--299) is received. Raise :exc:`error_reply` otherwise.
.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
@@ -220,9 +223,11 @@
Retrieve a file or directory listing in ASCII transfer mode. *command*
should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
- ``'LIST'``). The *callback* function is called for each line with a
- string argument containing the line with the trailing CRLF stripped.
- The default *callback* prints the line to ``sys.stdout``.
+ ``'LIST'``). ``LIST`` retrieves a list of files and information about those files.
+ ``NLST`` retrieves a list of file names. On some servers, ``MLSD`` retrieves
+ a machine readable list of files and information about those files. The *callback*
+ function is called for each line with a string argument containing the line with
+ the trailing CRLF stripped. The default *callback* prints the line to ``sys.stdout``.
.. method:: FTP.set_pasv(boolean)
@@ -293,10 +298,10 @@
.. method:: FTP.nlst(argument[, ...])
- Return a list of files as returned by the ``NLST`` command. The optional
- *argument* is a directory to list (default is the current server directory).
- Multiple arguments can be used to pass non-standard options to the ``NLST``
- command.
+ Return a list of file names as returned by the ``NLST`` command. The
+ optional *argument* is a directory to list (default is the current server
+ directory). Multiple arguments can be used to pass non-standard options to
+ the ``NLST`` command.
.. method:: FTP.dir(argument[, ...])
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 34e1dbe..4b63c9f 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -514,7 +514,7 @@
.. function:: getattr(object, name[, default])
- Return the value of the named attributed of *object*. *name* must be a string.
+ Return the value of the named attribute of *object*. *name* must be a string.
If the string is the name of one of the object's attributes, the result is the
value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
``x.foobar``. If the named attribute does not exist, *default* is returned if
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 3616724..4f2d94b 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -50,6 +50,11 @@
:meth:`close` explicitly when you don't need it any more, or use a
:keyword:`with` statement with :func:`contextlib.closing`.
+.. warning::
+
+ Because the :mod:`shelve` module is backed by :mod:`pickle`, it is insecure
+ to load a shelf from an untrusted source. Like with pickle, loading a shelf
+ can execute arbitrary code.
Shelf objects support all methods supported by dictionaries. This eases the
transition from dictionary based scripts to those requiring persistent storage.
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index cf2e678..59ed097 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -258,22 +258,21 @@
.. method:: Connection.execute(sql, [parameters])
This is a nonstandard shortcut that creates an intermediate cursor object by
- calling the cursor method, then calls the cursor's
- :meth:`execute<Cursor.execute>` method with the parameters given.
+ calling the cursor method, then calls the cursor's :meth:`execute
+ <Cursor.execute>` method with the parameters given.
.. method:: Connection.executemany(sql, [parameters])
This is a nonstandard shortcut that creates an intermediate cursor object by
- calling the cursor method, then calls the cursor's
- :meth:`executemany<Cursor.executemany>` method with the parameters given.
+ calling the cursor method, then calls the cursor's :meth:`executemany
+ <Cursor.executemany>` method with the parameters given.
.. method:: Connection.executescript(sql_script)
This is a nonstandard shortcut that creates an intermediate cursor object by
- calling the cursor method, then calls the cursor's
- :meth:`executescript<Cursor.executescript>` method with the parameters
- given.
+ calling the cursor method, then calls the cursor's :meth:`executescript
+ <Cursor.executescript>` method with the parameters given.
.. method:: Connection.create_function(name, num_params, func)
@@ -374,7 +373,7 @@
This routine allows/disallows the SQLite engine to load SQLite extensions
from shared libraries. SQLite extensions can define new functions,
- aggregates or whole new virtual table implementations. One well-known
+ aggregates or whole new virtual table implementations. One well-known
extension is the fulltext-search extension distributed with SQLite.
.. literalinclude:: ../includes/sqlite3/load_extension.py
@@ -383,9 +382,9 @@
.. versionadded:: 2.7
- This routine loads a SQLite extension from a shared library. You have to
- enable extension loading with ``enable_load_extension`` before you can use
- this routine.
+ This routine loads a SQLite extension from a shared library. You have to
+ enable extension loading with :meth:`enable_load_extension` before you can
+ use this routine.
.. attribute:: Connection.row_factory
@@ -458,9 +457,9 @@
Cursor Objects
--------------
-A :class:`Cursor` instance has the following attributes and methods:
+.. class:: Cursor
- A SQLite database cursor has the following attributes and methods:
+ A :class:`Cursor` instance has the following attributes and methods.
.. method:: Cursor.execute(sql, [parameters])
@@ -894,4 +893,3 @@
The only exception is calling the :meth:`~Connection.interrupt` method, which
only makes sense to call from a different thread.
-
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 7cb92ee..d99d184 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1356,8 +1356,8 @@
dictionary inserted immediately after the ``'%'`` character. The mapping key
selects the value to be formatted from the mapping. For example:
- >>> print '%(language)s has %(#)03d quote types.' % \
- ... {'language': "Python", "#": 2}
+ >>> print '%(language)s has %(number)03d quote types.' % \
+ ... {"language": "Python", "number": 2}
Python has 002 quote types.
In this case no ``*`` specifiers may occur in a format (since they require a
diff --git a/Doc/library/token.rst b/Doc/library/token.rst
index 5bf0ea8..00972b0 100644
--- a/Doc/library/token.rst
+++ b/Doc/library/token.rst
@@ -13,8 +13,8 @@
the language grammar. The specific numeric values which the names map to may
change between Python versions.
-This module also provides one data object and some functions. The functions
-mirror definitions in the Python C header files.
+The module also provides a mapping from numeric codes to names and some
+functions. The functions mirror definitions in the Python C header files.
.. data:: tok_name
@@ -39,6 +39,65 @@
Return true if *x* is the marker indicating the end of input.
+The token constants are:
+
+.. data:: ENDMARKER
+ NAME
+ NUMBER
+ STRING
+ NEWLINE
+ INDENT
+ DEDENT
+ LPAR
+ RPAR
+ LSQB
+ RSQB
+ COLON
+ COMMA
+ SEMI
+ PLUS
+ MINUS
+ STAR
+ SLASH
+ VBAR
+ AMPER
+ LESS
+ GREATER
+ EQUAL
+ DOT
+ PERCENT
+ BACKQUOTE
+ LBRACE
+ RBRACE
+ EQEQUAL
+ NOTEQUAL
+ LESSEQUAL
+ GREATEREQUAL
+ TILDE
+ CIRCUMFLEX
+ LEFTSHIFT
+ RIGHTSHIFT
+ DOUBLESTAR
+ PLUSEQUAL
+ MINEQUAL
+ STAREQUAL
+ SLASHEQUAL
+ PERCENTEQUAL
+ AMPEREQUAL
+ VBAREQUAL
+ CIRCUMFLEXEQUAL
+ LEFTSHIFTEQUAL
+ RIGHTSHIFTEQUAL
+ DOUBLESTAREQUAL
+ DOUBLESLASH
+ DOUBLESLASHEQUAL
+ AT
+ OP
+ ERRORTOKEN
+ N_TOKENS
+ NT_OFFSET
+
+
.. seealso::
Module :mod:`parser`