Merged revisions 75231 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
................
r75231 | benjamin.peterson | 2009-10-04 09:49:41 -0500 (Sun, 04 Oct 2009) | 166 lines
Merged revisions 74779-74786,74793,74795,74811,74860-74861,74863,74876,74886,74896,74901,74903,74908,74912,74930,74933,74943,74946,74952-74955,75015,75019,75032,75068,75076,75095,75098,75102,75129,75139,75230 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74779 | michael.foord | 2009-09-13 11:13:36 -0500 (Sun, 13 Sep 2009) | 1 line
Change to tutorial wording for reading text / binary files on Windows. Issue #6301.
........
r74780 | michael.foord | 2009-09-13 11:40:02 -0500 (Sun, 13 Sep 2009) | 1 line
Objects that compare equal automatically pass or fail assertAlmostEqual and assertNotAlmostEqual tests on unittest.TestCase. Issue 6567.
........
r74781 | michael.foord | 2009-09-13 11:46:19 -0500 (Sun, 13 Sep 2009) | 1 line
Note that sys._getframe is not guaranteed to exist in all implementations of Python, and a corresponding note in inspect.currentframe. Issue 6712.
........
r74782 | michael.foord | 2009-09-13 12:07:46 -0500 (Sun, 13 Sep 2009) | 1 line
Tutorial tweaks. Issue 6849.
........
r74783 | michael.foord | 2009-09-13 12:28:35 -0500 (Sun, 13 Sep 2009) | 1 line
unittest.TestLoader.loadTestsFromName honors the loader suiteClass attribute. Issue 6866.
........
r74784 | georg.brandl | 2009-09-13 13:15:07 -0500 (Sun, 13 Sep 2009) | 1 line
Typo fix.
........
r74785 | michael.foord | 2009-09-13 14:07:03 -0500 (Sun, 13 Sep 2009) | 1 line
Test discovery in unittest will only attempt to import modules that are importable; i.e. their names are valid Python identifiers. If an import fails during discovery this will be recorded as an error and test discovery will continue. Issue 6568.
........
r74786 | michael.foord | 2009-09-13 14:08:18 -0500 (Sun, 13 Sep 2009) | 1 line
Remove an extraneous space in unittest documentation.
........
r74793 | georg.brandl | 2009-09-14 09:50:47 -0500 (Mon, 14 Sep 2009) | 1 line
#6908: fix association of hashlib hash attributes.
........
r74795 | benjamin.peterson | 2009-09-14 22:36:26 -0500 (Mon, 14 Sep 2009) | 1 line
Py_SetPythonHome uses static storage #6913
........
r74811 | georg.brandl | 2009-09-15 15:26:59 -0500 (Tue, 15 Sep 2009) | 1 line
Add Armin Ronacher.
........
r74860 | benjamin.peterson | 2009-09-16 21:46:54 -0500 (Wed, 16 Sep 2009) | 1 line
kill bare except
........
r74861 | benjamin.peterson | 2009-09-16 22:18:28 -0500 (Wed, 16 Sep 2009) | 1 line
pep 8 defaults
........
r74863 | benjamin.peterson | 2009-09-16 22:27:33 -0500 (Wed, 16 Sep 2009) | 1 line
rationalize a bit
........
r74876 | georg.brandl | 2009-09-17 11:15:53 -0500 (Thu, 17 Sep 2009) | 1 line
#6932: remove paragraph that advises relying on __del__ being called.
........
r74886 | benjamin.peterson | 2009-09-17 16:33:46 -0500 (Thu, 17 Sep 2009) | 1 line
use macros
........
r74896 | georg.brandl | 2009-09-18 02:22:41 -0500 (Fri, 18 Sep 2009) | 1 line
#6936: for interactive use, quit() is just fine.
........
r74901 | georg.brandl | 2009-09-18 04:14:52 -0500 (Fri, 18 Sep 2009) | 1 line
#6905: use better exception messages in inspect when the argument is of the wrong type.
........
r74903 | georg.brandl | 2009-09-18 04:18:27 -0500 (Fri, 18 Sep 2009) | 1 line
#6938: "ident" is always a string, so use a format code which works.
........
r74908 | georg.brandl | 2009-09-18 08:57:11 -0500 (Fri, 18 Sep 2009) | 1 line
Use str.format() to fix beginner's mistake with %-style string formatting.
........
r74912 | georg.brandl | 2009-09-18 11:19:56 -0500 (Fri, 18 Sep 2009) | 1 line
Optimize optimization and fix method name in docstring.
........
r74930 | georg.brandl | 2009-09-18 16:21:41 -0500 (Fri, 18 Sep 2009) | 1 line
#6925: rewrite docs for locals() and vars() a bit.
........
r74933 | georg.brandl | 2009-09-18 16:35:59 -0500 (Fri, 18 Sep 2009) | 1 line
#6930: clarify description about byteorder handling in UTF decoder routines.
........
r74943 | georg.brandl | 2009-09-19 02:35:07 -0500 (Sat, 19 Sep 2009) | 1 line
#6944: the argument to PyArg_ParseTuple should be a tuple, otherwise a SystemError is set. Also clean up another usage of PyArg_ParseTuple.
........
r74946 | georg.brandl | 2009-09-19 03:43:16 -0500 (Sat, 19 Sep 2009) | 1 line
Update bug tracker reference.
........
r74952 | georg.brandl | 2009-09-19 05:42:34 -0500 (Sat, 19 Sep 2009) | 1 line
#6946: fix duplicate index entries for datetime classes.
........
r74953 | georg.brandl | 2009-09-19 07:04:16 -0500 (Sat, 19 Sep 2009) | 1 line
Fix references to threading.enumerate().
........
r74954 | georg.brandl | 2009-09-19 08:13:56 -0500 (Sat, 19 Sep 2009) | 1 line
Add Doug.
........
r74955 | georg.brandl | 2009-09-19 08:20:49 -0500 (Sat, 19 Sep 2009) | 1 line
Add Mark Summerfield.
........
r75015 | georg.brandl | 2009-09-22 05:55:08 -0500 (Tue, 22 Sep 2009) | 1 line
Fix encoding name.
........
r75019 | vinay.sajip | 2009-09-22 12:23:41 -0500 (Tue, 22 Sep 2009) | 1 line
Fixed a typo, and added sections on optimization and using arbitrary objects as messages.
........
r75032 | benjamin.peterson | 2009-09-22 17:15:28 -0500 (Tue, 22 Sep 2009) | 1 line
fix typos/rephrase
........
r75068 | benjamin.peterson | 2009-09-25 21:57:59 -0500 (Fri, 25 Sep 2009) | 1 line
comment out ugly xxx
........
r75076 | vinay.sajip | 2009-09-26 09:53:32 -0500 (Sat, 26 Sep 2009) | 1 line
Tidied up name of parameter in StreamHandler
........
r75095 | michael.foord | 2009-09-27 14:15:41 -0500 (Sun, 27 Sep 2009) | 1 line
Test creation moved from TestProgram.parseArgs to TestProgram.createTests exclusively. Issue 6956.
........
r75098 | michael.foord | 2009-09-27 15:08:23 -0500 (Sun, 27 Sep 2009) | 1 line
Documentation improvement for load_tests protocol in unittest. Issue 6515.
........
r75102 | skip.montanaro | 2009-09-27 21:12:27 -0500 (Sun, 27 Sep 2009) | 3 lines
Patch from Thomas Barr so that csv.Sniffer will set doublequote property.
Closes issue 6606.
........
r75129 | vinay.sajip | 2009-09-29 02:08:54 -0500 (Tue, 29 Sep 2009) | 1 line
Issue #7014: logging: Improved IronPython 2.6 compatibility.
........
r75139 | raymond.hettinger | 2009-09-29 13:53:24 -0500 (Tue, 29 Sep 2009) | 3 lines
Issue 7008: Better document str.title and show how to work around the apostrophe problem.
........
r75230 | benjamin.peterson | 2009-10-04 08:38:38 -0500 (Sun, 04 Oct 2009) | 1 line
test logging
........
................
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 6e02063..c3e7407 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -986,7 +986,7 @@
+-----------------+--------------------------------+--------------------------------+
| cp1255 | windows-1255 | Hebrew |
+-----------------+--------------------------------+--------------------------------+
-| cp1256 | windows1256 | Arabic |
+| cp1256 | windows-1256 | Arabic |
+-----------------+--------------------------------+--------------------------------+
| cp1257 | windows-1257 | Baltic languages |
+-----------------+--------------------------------+--------------------------------+
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index df04cf3..c1d3113 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -63,6 +63,7 @@
.. class:: date
+ :noindex:
An idealized naive date, assuming the current Gregorian calendar always was, and
always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and
@@ -70,6 +71,7 @@
.. class:: time
+ :noindex:
An idealized time, independent of any particular day, assuming that every day
has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here).
@@ -78,6 +80,7 @@
.. class:: datetime
+ :noindex:
A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
:attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
@@ -85,6 +88,7 @@
.. class:: timedelta
+ :noindex:
A duration expressing the difference between two :class:`date`, :class:`time`,
or :class:`datetime` instances to microsecond resolution.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 9cd2175..465339a 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -600,16 +600,12 @@
.. function:: locals()
Update and return a dictionary representing the current local symbol table.
+ Free variables are returned by :func:`locals` when it is called in function
+ blocks, but not in class blocks.
.. note::
-
The contents of this dictionary should not be modified; changes may not
- affect the values of local variables used by the interpreter.
-
- Free variables are returned by :func:`locals` when it is called in a function
- block. Modifications of free variables may not affect the values used by the
- interpreter. Free variables are not returned in class blocks.
-
+ affect the values of local and free variables used by the interpreter.
.. function:: map(function, iterable, ...)
@@ -1172,10 +1168,10 @@
.. function:: vars([object])
- Without arguments, return a dictionary corresponding to the current local symbol
- table. With a module, class or class instance object as argument (or anything
- else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
- to the object's symbol table.
+ Without an argument, act like :func:`locals`.
+
+ With a module, class or class instance object as argument (or anything else that
+ has a :attr:`__dict__` attribute), return that attribute.
.. note::
The returned dictionary should not be modified:
diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index f63d957..a776df1 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -86,11 +86,11 @@
returned by the constructors:
-.. data:: digest_size
+.. data:: hash.digest_size
The size of the resulting hash in bytes.
-.. data:: block_size
+.. data:: hash.block_size
The internal block size of the hash algorithm in bytes.
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 03bdf3e..ad88e3d 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -508,6 +508,11 @@
Return the frame object for the caller's stack frame.
+ This function relies on Python stack frame support in the interpreter, which
+ isn't guaranteed to exist in all implementations of Python. If running in
+ an implementation without Python stack frame support this function returns
+ ``None``.
+
.. function:: stack(context=1)
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index bb736af..6ff9b8b 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -57,7 +57,7 @@
import logging
LOG_FILENAME = '/tmp/logging_example.out'
- logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG,)
+ logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG)
logging.debug('This message should go to the log file')
@@ -1447,6 +1447,55 @@
69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
69 myapp.area2 ERROR The five boxing wizards jump quickly.
+Using arbitrary objects as messages
+-----------------------------------
+
+In the preceding sections and examples, it has been assumed that the message
+passed when logging the event is a string. However, this is not the only
+possibility. You can pass an arbitrary object as a message, and its
+:meth:`__str__` method will be called when the logging system needs to convert
+it to a string representation. In fact, if you want to, you can avoid
+computing a string representation altogether - for example, the
+:class:`SocketHandler` emits an event by pickling it and sending it over the
+wire.
+
+Optimization
+------------
+
+Formatting of message arguments is deferred until it cannot be avoided.
+However, computing the arguments passed to the logging method can also be
+expensive, and you may want to avoid doing it if the logger will just throw
+away your event. To decide what to do, you can call the :meth:`isEnabledFor`
+method which takes a level argument and returns true if the event would be
+created by the Logger for that level of call. You can write code like this::
+
+ if logger.isEnabledFor(logging.DEBUG):
+ logger.debug("Message with %s, %s", expensive_func1(),
+ expensive_func2())
+
+so that if the logger's threshold is set above ``DEBUG``, the calls to
+:func:`expensive_func1` and :func:`expensive_func2` are never made.
+
+There are other optimizations which can be made for specific applications which
+need more precise control over what logging information is collected. Here's a
+list of things you can do to avoid processing during logging which you don't
+need:
+
++-----------------------------------------------+----------------------------------------+
+| What you don't want to collect | How to avoid collecting it |
++===============================================+========================================+
+| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
++-----------------------------------------------+----------------------------------------+
+| Threading information. | Set ``logging.logThreads`` to ``0``. |
++-----------------------------------------------+----------------------------------------+
+| Process information. | Set ``logging.logProcesses`` to ``0``. |
++-----------------------------------------------+----------------------------------------+
+
+Also note that the core logging module only includes the basic handlers. If
+you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
+take up any memory.
+
+.. _handler:
Handler Objects
---------------
@@ -1562,9 +1611,9 @@
and :meth:`flush` methods).
-.. class:: StreamHandler(strm=None)
+.. class:: StreamHandler(stream=None)
- Returns a new instance of the :class:`StreamHandler` class. If *strm* is
+ Returns a new instance of the :class:`StreamHandler` class. If *stream* is
specified, the instance will use it for logging output; otherwise, *sys.stderr*
will be used.
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 10242fd..e386290 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -27,27 +27,39 @@
Because of Python semantics, a shelf cannot know when a mutable
persistent-dictionary entry is modified. By default modified objects are
- written only when assigned to the shelf (see :ref:`shelve-example`). If
- the optional *writeback* parameter is set to *True*, all entries accessed
- are cached in memory, and written back at close time; this can make it
- handier to mutate mutable entries in the persistent dictionary, but, if
- many entries are accessed, it can consume vast amounts of memory for the
- cache, and it can make the close operation very slow since all accessed
- entries are written back (there is no way to determine which accessed
- entries are mutable, nor which ones were actually mutated).
+ written only when assigned to the shelf (see :ref:`shelve-example`). If the
+ optional *writeback* parameter is set to *True*, all entries accessed are
+ cached in memory, and written back on :meth:`sync` and :meth:`close`; this
+ can make it handier to mutate mutable entries in the persistent dictionary,
+ but, if many entries are accessed, it can consume vast amounts of memory for
+ the cache, and it can make the close operation very slow since all accessed
+ entries are written back (there is no way to determine which accessed entries
+ are mutable, nor which ones were actually mutated).
+
+ .. note::
+
+ Do not rely on the shelf being closed automatically; always call
+ :meth:`close` explicitly when you don't need it any more, or use a
+ :keyword:`with` statement with :func:`contextlib.closing`.
+
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:
-
+Two additional methods are supported:
.. method:: Shelf.sync()
- Write back all entries in the cache if the shelf was opened with *writeback* set
- to *True*. Also empty the cache and synchronize the persistent dictionary on
- disk, if feasible. This is called automatically when the shelf is closed with
- :meth:`close`.
+ Write back all entries in the cache if the shelf was opened with *writeback*
+ set to :const:`True`. Also empty the cache and synchronize the persistent
+ dictionary on disk, if feasible. This is called automatically when the shelf
+ is closed with :meth:`close`.
+
+.. method:: Shelf.close()
+
+ Synchronize and close the persistent *dict* object. Operations on a closed
+ shelf will fail with a :exc:`ValueError`.
+
.. seealso::
@@ -71,11 +83,6 @@
database should be fairly small, and in rare cases key collisions may cause
the database to refuse updates.
-* Depending on the implementation, closing a persistent dictionary may or may
- not be necessary to flush changes to disk. The :meth:`__del__` method of the
- :class:`Shelf` class calls the :meth:`close` method, so the programmer generally
- need not do this explicitly.
-
* The :mod:`shelve` module does not support *concurrent* read/write access to
shelved objects. (Multiple simultaneous read accesses are safe.) When a
program has a shelf open for writing, no other program should have it open for
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 8f56bb0..3b02f98 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1148,6 +1148,8 @@
>>> titlecase("they're bill's friends.")
"They're Bill's Friends."
+ For 8-bit strings, this method is locale-dependent.
+
.. method:: str.translate(map)
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index e895e4c..b786034 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -337,12 +337,12 @@
does not have to hold true for third-party extensions as it is implementation
specific.
- The *default* argument allows to define a value which will be returned
- if the object type does not provide means to retrieve the size and would
- cause a `TypeError`.
+ If given, *default* will be returned if the object does not provide means to
+ retrieve the size. Otherwise a `TypeError` will be raised.
- :func:`getsizeof` calls the object's __sizeof__ method and adds an additional
- garbage collector overhead if the object is managed by the garbage collector.
+ :func:`getsizeof` calls the object's ``__sizeof__`` method and adds an
+ additional garbage collector overhead if the object is managed by the garbage
+ collector.
.. function:: _getframe([depth])
@@ -352,7 +352,8 @@
that is deeper than the call stack, :exc:`ValueError` is raised. The default
for *depth* is zero, returning the frame at the top of the call stack.
- This function should be used for internal and specialized purposes only.
+ This function should be used for internal and specialized purposes only. It
+ is not guaranteed to exist in all implementations of Python.
.. function:: getprofile()
diff --git a/Doc/library/termios.rst b/Doc/library/termios.rst
index df29496..591850e 100644
--- a/Doc/library/termios.rst
+++ b/Doc/library/termios.rst
@@ -89,7 +89,7 @@
:keyword:`finally` statement to ensure that the old tty attributes are restored
exactly no matter what happens::
- def getpass(prompt = "Password: "):
+ def getpass(prompt="Password: "):
import termios, sys
fd = sys.stdin.fileno()
old = termios.tcgetattr(fd)
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index aa7f46a..f642111 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -23,7 +23,7 @@
.. function:: active_count()
Return the number of :class:`Thread` objects currently alive. The returned
- count is equal to the length of the list returned by :func:`enumerate`.
+ count is equal to the length of the list returned by :func:`.enumerate`.
.. function:: Condition()
@@ -301,7 +301,7 @@
Roughly, a thread is alive from the moment the :meth:`start` method
returns until its :meth:`run` method terminates. The module function
- :func:`enumerate` returns a list of all alive threads.
+ :func:`.enumerate` returns a list of all alive threads.
.. attribute:: daemon