Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74861 | benjamin.peterson | 2009-09-17 05:18:28 +0200 (Do, 17 Sep 2009) | 1 line
pep 8 defaults
........
r74862 | brett.cannon | 2009-09-17 05:24:45 +0200 (Do, 17 Sep 2009) | 1 line
Note in the intro to Extending... that ctypes can be a simpler, more portable solution than custom C code.
........
r74863 | benjamin.peterson | 2009-09-17 05:27:33 +0200 (Do, 17 Sep 2009) | 1 line
rationalize a bit
........
r74876 | georg.brandl | 2009-09-17 18:15:53 +0200 (Do, 17 Sep 2009) | 1 line
#6932: remove paragraph that advises relying on __del__ being called.
........
r74896 | georg.brandl | 2009-09-18 09:22:41 +0200 (Fr, 18 Sep 2009) | 1 line
#6936: for interactive use, quit() is just fine.
........
r74930 | georg.brandl | 2009-09-18 23:21:41 +0200 (Fr, 18 Sep 2009) | 1 line
#6925: rewrite docs for locals() and vars() a bit.
........
r74933 | georg.brandl | 2009-09-18 23:35:59 +0200 (Fr, 18 Sep 2009) | 1 line
#6930: clarify description about byteorder handling in UTF decoder routines.
........
r74952 | georg.brandl | 2009-09-19 12:42:34 +0200 (Sa, 19 Sep 2009) | 1 line
#6946: fix duplicate index entries for datetime classes.
........
r74953 | georg.brandl | 2009-09-19 14:04:16 +0200 (Sa, 19 Sep 2009) | 1 line
Fix references to threading.enumerate().
........
r75015 | georg.brandl | 2009-09-22 12:55:08 +0200 (Di, 22 Sep 2009) | 1 line
Fix encoding name.
........
r75019 | vinay.sajip | 2009-09-22 19:23:41 +0200 (Di, 22 Sep 2009) | 1 line
Fixed a typo, and added sections on optimization and using arbitrary objects as messages.
........
r75260 | andrew.kuchling | 2009-10-05 23:24:20 +0200 (Mo, 05 Okt 2009) | 1 line
Wording fix
........
r75261 | andrew.kuchling | 2009-10-05 23:24:35 +0200 (Mo, 05 Okt 2009) | 1 line
Fix narkup
........
r75262 | andrew.kuchling | 2009-10-05 23:25:03 +0200 (Mo, 05 Okt 2009) | 1 line
Document 'skip' parameter to constructor
........
r75263 | andrew.kuchling | 2009-10-05 23:25:35 +0200 (Mo, 05 Okt 2009) | 1 line
Note side benefit of socket.create_connection()
........
r75265 | andrew.kuchling | 2009-10-06 00:31:11 +0200 (Di, 06 Okt 2009) | 1 line
Reword sentence
........
r75266 | andrew.kuchling | 2009-10-06 00:32:48 +0200 (Di, 06 Okt 2009) | 1 line
Use standard comma punctuation; reword some sentences in the docs
........
r75289 | mark.dickinson | 2009-10-08 22:02:25 +0200 (Do, 08 Okt 2009) | 2 lines
Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
........
diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst
index a74e14d..4ee2f19 100644
--- a/Doc/library/bdb.rst
+++ b/Doc/library/bdb.rst
@@ -62,14 +62,22 @@
* The breakpoint hit count.
-.. class:: Bdb()
+.. class:: Bdb(skip=None)
- The :class:`Bdb` acts as a generic Python debugger base class.
+ The :class:`Bdb` class acts as a generic Python debugger base class.
This class takes care of the details of the trace facility; a derived class
should implement user interaction. The standard debugger class
(:class:`pdb.Pdb`) is an example.
+ The *skip* argument, if given, must be an iterable of glob-style
+ module name patterns. The debugger will not step into frames that
+ originate in a module that matches one of these patterns. Whether a
+ frame is considered to originate in a certain module is determined
+ by the ``__name__`` in the frame globals.
+
+ .. versionadded:: 2.7
+ The *skip* argument.
The following methods of :class:`Bdb` normally don't need to be overridden.
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 4f6ddcf..89d6610 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -958,7 +958,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 5539c5a..7251479 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -65,6 +65,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
@@ -72,6 +73,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).
@@ -80,6 +82,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`,
@@ -87,6 +90,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 ff75510..6892c65 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -637,15 +637,13 @@
.. 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.
+ The contents of this dictionary should not be modified; changes may not
+ affect the values of local and free variables used by the interpreter.
.. function:: long([x[, base]])
@@ -1357,10 +1355,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::
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index fcc5edd..aea9653 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -59,7 +59,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')
@@ -1499,6 +1499,53 @@
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:
diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index cfc219c..72332a6 100644
--- a/Doc/library/pdb.rst
+++ b/Doc/library/pdb.rst
@@ -53,7 +53,16 @@
.. versionadded:: 2.4
Restarting post-mortem behavior added.
-Typical usage to inspect a crashed program is::
+The typical usage to break into the debugger from a running program is to
+insert ::
+
+ import pdb; pdb.set_trace()
+
+at the location you want to break into the debugger. You can then step through
+the code following this statement, and continue running without the debugger using
+the ``c`` command.
+
+The typical usage to inspect a crashed program is::
>>> import pdb
>>> import mymodule
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 503db0f..5d82dc4 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -30,27 +30,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::
@@ -75,11 +87,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/string.rst b/Doc/library/string.rst
index 4678167..5b065b3 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -435,15 +435,33 @@
+---------+----------------------------------------------------------+
| ``'F'`` | Fixed point. Same as ``'f'``. |
+---------+----------------------------------------------------------+
- | ``'g'`` | General format. This prints the number as a fixed-point |
- | | number, unless the number is too large, in which case |
- | | it switches to ``'e'`` exponent notation. Infinity and |
- | | NaN values are formatted as ``inf``, ``-inf`` and |
- | | ``nan``, respectively. |
+ | ``'g'`` | General format. For a given precision ``p >= 1``, |
+ | | this rounds the number to ``p`` significant digits and |
+ | | then formats the result in either fixed-point format |
+ | | or in scientific notation, depending on its magnitude. |
+ | | |
+ | | The precise rules are as follows: suppose that the |
+ | | result formatted with presentation type ``'e'`` and |
+ | | precision ``p-1`` would have exponent ``exp``. Then |
+ | | if ``-4 <= exp < p``, the number is formatted |
+ | | with presentation type ``'f'`` and precision |
+ | | ``p-1-exp``. Otherwise, the number is formatted |
+ | | with presentation type ``'e'`` and precision ``p-1``. |
+ | | In both cases insignificant trailing zeros are removed |
+ | | from the significand, and the decimal point is also |
+ | | removed if there are no remaining digits following it. |
+ | | |
+ | | Postive and negative infinity, positive and negative |
+ | | zero, and nans, are formatted as ``inf``, ``-inf``, |
+ | | ``0``, ``-0`` and ``nan`` respectively, regardless of |
+ | | the precision. |
+ | | |
+ | | A precision of ``0`` is treated as equivalent to a |
+ | | precision of ``1``. |
+---------+----------------------------------------------------------+
| ``'G'`` | General format. Same as ``'g'`` except switches to |
- | | ``'E'`` if the number gets to large. The representations |
- | | of infinity and NaN are uppercased, too. |
+ | | ``'E'`` if the number gets too large. The |
+ | | representations of infinity and NaN are uppercased, too. |
+---------+----------------------------------------------------------+
| ``'n'`` | Number. This is the same as ``'g'``, except that it uses |
| | the current locale setting to insert the appropriate |
diff --git a/Doc/library/termios.rst b/Doc/library/termios.rst
index 4847949..2b1be7b 100644
--- a/Doc/library/termios.rst
+++ b/Doc/library/termios.rst
@@ -90,7 +90,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 412000e..1440215 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -33,7 +33,7 @@
activeCount()
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()
@@ -321,7 +321,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.
.. method:: isDaemon()
setDaemon()