Merged revisions 59822-59841 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59822 | georg.brandl | 2008-01-07 17:43:47 +0100 (Mon, 07 Jan 2008) | 2 lines
Restore "somenamedtuple" as the "class" for named tuple attrs.
........
r59824 | georg.brandl | 2008-01-07 18:09:35 +0100 (Mon, 07 Jan 2008) | 2 lines
Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode.
........
r59827 | georg.brandl | 2008-01-07 18:25:53 +0100 (Mon, 07 Jan 2008) | 2 lines
patch #1668: clarify envvar docs; rename THREADDEBUG to PYTHONTHREADDEBUG.
........
r59830 | georg.brandl | 2008-01-07 19:16:36 +0100 (Mon, 07 Jan 2008) | 2 lines
Make Python compile with --disable-unicode.
........
r59831 | georg.brandl | 2008-01-07 19:23:27 +0100 (Mon, 07 Jan 2008) | 2 lines
Restructure urllib doc structure.
........
r59833 | georg.brandl | 2008-01-07 19:41:34 +0100 (Mon, 07 Jan 2008) | 2 lines
Fix #define ordering.
........
r59834 | georg.brandl | 2008-01-07 19:47:44 +0100 (Mon, 07 Jan 2008) | 2 lines
#467924, patch by Alan McIntyre: Add ZipFile.extract and ZipFile.extractall.
........
r59835 | raymond.hettinger | 2008-01-07 19:52:19 +0100 (Mon, 07 Jan 2008) | 1 line
Fix inconsistent title levels -- it made the whole doc build crash horribly.
........
r59836 | georg.brandl | 2008-01-07 19:57:03 +0100 (Mon, 07 Jan 2008) | 2 lines
Fix two further doc build warnings.
........
r59837 | georg.brandl | 2008-01-07 20:17:10 +0100 (Mon, 07 Jan 2008) | 2 lines
Clarify metaclass docs and add example.
........
r59838 | vinay.sajip | 2008-01-07 20:40:10 +0100 (Mon, 07 Jan 2008) | 1 line
Added section about adding contextual information to log output.
........
r59839 | christian.heimes | 2008-01-07 20:58:41 +0100 (Mon, 07 Jan 2008) | 1 line
Fixed indention problem that caused the second TIPC test to run on systems without TIPC
........
r59840 | raymond.hettinger | 2008-01-07 21:07:38 +0100 (Mon, 07 Jan 2008) | 1 line
Cleanup named tuple subclassing example.
........
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index cb3a029..2b8e279 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -382,7 +382,7 @@
.. _named-tuple-factory:
:func:`namedtuple` Factory Function for Tuples with Named Fields
------------------------------------------------------------------
+----------------------------------------------------------------
Named tuples assign meaning to each position in a tuple and allow for more readable,
self-documenting code. They can be used wherever regular tuples are used, and
@@ -398,7 +398,7 @@
The *fieldnames* are a single string with each fieldname separated by whitespace
and/or commas (for example 'x y' or 'x, y'). Alternatively, the *fieldnames*
- can be specified as a list of strings (such as ['x', 'y']).
+ can be specified with a sequence of strings (such as ['x', 'y']).
Any valid Python identifier may be used for a fieldname except for names
starting with an underscore. Valid identifiers consist of letters, digits,
@@ -479,7 +479,7 @@
In addition to the methods inherited from tuples, named tuples support
three additional methods and one attribute.
-.. method:: namedtuple._make(iterable)
+.. method:: somenamedtuple._make(iterable)
Class method that makes a new instance from an existing sequence or iterable.
@@ -489,7 +489,7 @@
>>> Point._make(t)
Point(x=11, y=22)
-.. method:: namedtuple._asdict()
+.. method:: somenamedtuple._asdict()
Return a new dict which maps field names to their corresponding values:
@@ -498,7 +498,7 @@
>>> p._asdict()
{'x': 11, 'y': 22}
-.. method:: namedtuple._replace(kwargs)
+.. method:: somenamedtuple._replace(kwargs)
Return a new instance of the named tuple replacing specified fields with new values:
@@ -509,9 +509,9 @@
Point(x=33, y=22)
>>> for partnum, record in inventory.items():
- ... inventory[partnum] = record._replace(price=newprices[partnum], updated=time.now())
+ inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
-.. attribute:: namedtuple._fields
+.. attribute:: somenamedtuple._fields
Tuple of strings listing the field names. This is useful for introspection
and for creating new named tuple types from existing named tuples.
@@ -527,9 +527,7 @@
Pixel(x=11, y=22, red=128, green=255, blue=0)'
To retrieve a field whose name is stored in a string, use the :func:`getattr`
-function:
-
-::
+function::
>>> getattr(p, 'x')
11
@@ -548,13 +546,15 @@
@property
def hypot(self):
return (self.x ** 2 + self.y ** 2) ** 0.5
- def __repr__(self):
- return 'Point(x=%.3f, y=%.3f, hypot=%.3f)' % (self.x, self.y, self.hypot)
+ def __str__(self):
+ return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, self.hypot)
- >>> print Point(3, 4),'\n', Point(2, 5), '\n', Point(9./7, 6)
- Point(x=3.000, y=4.000, hypot=5.000)
- Point(x=2.000, y=5.000, hypot=5.385)
- Point(x=1.286, y=6.000, hypot=6.136)
+ >>> for p in Point(3,4), Point(14,5), Point(9./7,6):
+ print p
+
+ Point: x= 3.000 y= 4.000 hypot= 5.000
+ Point: x=14.000 y= 5.000 hypot=14.866
+ Point: x= 1.286 y= 6.000 hypot= 6.136
Another use for subclassing is to replace performance critcal methods with
faster versions that bypass error-checking and localize variable access::
@@ -564,10 +564,8 @@
def _replace(self, _map=map, **kwds):
return self._make(_map(kwds.pop, ('x', 'y'), self))
-Default values can be implemented by starting with a prototype instance
-and customizing it with :meth:`_replace`:
-
-::
+Default values can be implemented by using :meth:`_replace`:: to
+customize a prototype instance::
>>> Account = namedtuple('Account', 'owner balance transaction_count')
>>> model_account = Account('<owner name>', 0.0, 0)
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index bf6ad71..af8c867 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1118,6 +1118,52 @@
combination of handlers you choose.
+.. _context-info:
+
+Adding contextual information to your logging output
+----------------------------------------------------
+
+Sometimes you want logging output to contain contextual information in
+addition to the parameters passed to the logging call. For example, in a
+networked application, it may be desirable to log client-specific information
+in the log (e.g. remote client's username, or IP address). Although you could
+use the *extra* parameter to achieve this, it's not always convenient to pass
+the information in this way. While it might be tempting to create
+:class:`Logger` instances on a per-connection basis, this is not a good idea
+because these instances are not garbage collected. While this is not a problem
+in practice, when the number of :class:`Logger` instances is dependent on the
+level of granularity you want to use in logging an application, it could
+be hard to manage if the number of :class:`Logger` instances becomes
+effectively unbounded.
+
+There are a number of other ways you can pass contextual information to be
+output along with logging event information.
+
+* Use an adapter class which has access to the contextual information and
+ which defines methods :meth:`debug`, :meth:`info` etc. with the same
+ signatures as used by :class:`Logger`. You instantiate the adapter with a
+ name, which will be used to create an underlying :class:`Logger` with that
+ name. In each adpater method, the passed-in message is modified to include
+ whatever contextual information you want.
+
+* Use something other than a string to pass the message. Although normally
+ the first argument to a logger method such as :meth:`debug`, :meth:`info`
+ etc. is usually a string, it can in fact be any object. This object is the
+ argument to a :func:`str()` call which is made, in
+ :meth:`LogRecord.getMessage`, to obtain the actual message string. You can
+ use this behavior to pass an instance which may be initialized with a
+ logging message, which redefines :meth:__str__ to return a modified version
+ of that message with the contextual information added.
+
+* Use a specialized :class:`Formatter` subclass to add additional information
+ to the formatted output. The subclass could, for instance, merge some thread
+ local contextual information (or contextual information obtained in some
+ other way) with the output generated by the base :class:`Formatter`.
+
+In each of these three approaches, thread locals can sometimes be a useful way
+of passing contextual information without undue coupling between different
+parts of your code.
+
.. _network-logging:
Sending and receiving logging events across a network
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 4a1d566..22ca0f0 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -435,8 +435,9 @@
One method needs to be defined for container objects to provide iteration
support:
+.. XXX duplicated in reference/datamodel!
-.. method:: object.__iter__()
+.. method:: container.__iter__()
Return an iterator object. The object is required to support the iterator
protocol described below. If a container supports different types of
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 4182a0b..85c592e 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -438,6 +438,17 @@
implement a dynamic prompt.
+.. data:: dont_write_bytecode
+
+ If this is true, Python won't try to write ``.pyc`` or ``.pyo`` files on the
+ import of source modules. This value is initially set to ``True`` or ``False``
+ depending on the ``-B`` command line option and the ``PYTHONDONTWRITEBYTECODE``
+ environment variable, but you can set it yourself to control bytecode file
+ generation.
+
+ .. versionadded:: 2.6
+
+
.. function:: setcheckinterval(interval)
Set the interpreter's "check interval". This integer value determines how often
diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst
index 77eb632..4b86e88 100644
--- a/Doc/library/urllib.rst
+++ b/Doc/library/urllib.rst
@@ -1,4 +1,3 @@
-
:mod:`urllib` --- Open arbitrary resources by URL
=================================================
@@ -17,8 +16,8 @@
instead of filenames. Some restrictions apply --- it can only open URLs for
reading, and no seek operations are available.
-It defines the following public functions:
-
+High-level interface
+--------------------
.. function:: urlopen(url[, data[, proxies]])
@@ -174,6 +173,9 @@
:func:`urlretrieve`.
+Utility functions
+-----------------
+
.. function:: quote(string[, safe])
Replace special characters in *string* using the ``%xx`` escape. Letters,
@@ -235,6 +237,9 @@
to decode *path*.
+URL Opener objects
+------------------
+
.. class:: URLopener([proxies[, **x509]])
Base class for opening and reading URLs. Unless you need to support opening
@@ -260,6 +265,48 @@
:class:`URLopener` objects will raise an :exc:`IOError` exception if the server
returns an error code.
+ .. method:: open(fullurl[, data])
+
+ Open *fullurl* using the appropriate protocol. This method sets up cache and
+ proxy information, then calls the appropriate open method with its input
+ arguments. If the scheme is not recognized, :meth:`open_unknown` is called.
+ The *data* argument has the same meaning as the *data* argument of
+ :func:`urlopen`.
+
+
+ .. method:: open_unknown(fullurl[, data])
+
+ Overridable interface to open unknown URL types.
+
+
+ .. method:: retrieve(url[, filename[, reporthook[, data]]])
+
+ Retrieves the contents of *url* and places it in *filename*. The return value
+ is a tuple consisting of a local filename and either a
+ :class:`mimetools.Message` object containing the response headers (for remote
+ URLs) or ``None`` (for local URLs). The caller must then open and read the
+ contents of *filename*. If *filename* is not given and the URL refers to a
+ local file, the input filename is returned. If the URL is non-local and
+ *filename* is not given, the filename is the output of :func:`tempfile.mktemp`
+ with a suffix that matches the suffix of the last path component of the input
+ URL. If *reporthook* is given, it must be a function accepting three numeric
+ parameters. It will be called after each chunk of data is read from the
+ network. *reporthook* is ignored for local URLs.
+
+ If the *url* uses the :file:`http:` scheme identifier, the optional *data*
+ argument may be given to specify a ``POST`` request (normally the request type
+ is ``GET``). The *data* argument must in standard
+ :mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
+ function below.
+
+
+ .. attribute:: version
+
+ Variable that specifies the user agent of the opener object. To get
+ :mod:`urllib` to tell servers that it is a particular user agent, set this in a
+ subclass as a class variable or in the constructor before calling the base
+ constructor.
+
.. class:: FancyURLopener(...)
@@ -289,6 +336,18 @@
users for the required information on the controlling terminal. A subclass may
override this method to support more appropriate behavior if needed.
+ The :class:`FancyURLopener` class offers one additional method that should be
+ overloaded to provide the appropriate behavior:
+
+ .. method:: prompt_user_passwd(host, realm)
+
+ Return information needed to authenticate the user at the given host in the
+ specified security realm. The return value should be a tuple, ``(user,
+ password)``, which can be used for basic authentication.
+
+ The implementation prompts for this information on the terminal; an application
+ should override this method to use an appropriate interaction model in the local
+ environment.
.. exception:: ContentTooShortError(msg[, content])
@@ -297,7 +356,9 @@
*Content-Length* header). The :attr:`content` attribute stores the downloaded
(and supposedly truncated) data.
-Restrictions:
+
+:mod:`urllib` Restrictions
+--------------------------
.. index::
pair: HTTP; protocol
@@ -358,75 +419,6 @@
module :mod:`urlparse`.
-.. _urlopener-objs:
-
-URLopener Objects
------------------
-
-.. sectionauthor:: Skip Montanaro <skip@pobox.com>
-
-
-:class:`URLopener` and :class:`FancyURLopener` objects have the following
-attributes.
-
-
-.. method:: URLopener.open(fullurl[, data])
-
- Open *fullurl* using the appropriate protocol. This method sets up cache and
- proxy information, then calls the appropriate open method with its input
- arguments. If the scheme is not recognized, :meth:`open_unknown` is called.
- The *data* argument has the same meaning as the *data* argument of
- :func:`urlopen`.
-
-
-.. method:: URLopener.open_unknown(fullurl[, data])
-
- Overridable interface to open unknown URL types.
-
-
-.. method:: URLopener.retrieve(url[, filename[, reporthook[, data]]])
-
- Retrieves the contents of *url* and places it in *filename*. The return value
- is a tuple consisting of a local filename and either a
- :class:`mimetools.Message` object containing the response headers (for remote
- URLs) or ``None`` (for local URLs). The caller must then open and read the
- contents of *filename*. If *filename* is not given and the URL refers to a
- local file, the input filename is returned. If the URL is non-local and
- *filename* is not given, the filename is the output of :func:`tempfile.mktemp`
- with a suffix that matches the suffix of the last path component of the input
- URL. If *reporthook* is given, it must be a function accepting three numeric
- parameters. It will be called after each chunk of data is read from the
- network. *reporthook* is ignored for local URLs.
-
- If the *url* uses the :file:`http:` scheme identifier, the optional *data*
- argument may be given to specify a ``POST`` request (normally the request type
- is ``GET``). The *data* argument must in standard
- :mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
- function below.
-
-
-.. attribute:: URLopener.version
-
- Variable that specifies the user agent of the opener object. To get
- :mod:`urllib` to tell servers that it is a particular user agent, set this in a
- subclass as a class variable or in the constructor before calling the base
- constructor.
-
-The :class:`FancyURLopener` class offers one additional method that should be
-overloaded to provide the appropriate behavior:
-
-
-.. method:: FancyURLopener.prompt_user_passwd(host, realm)
-
- Return information needed to authenticate the user at the given host in the
- specified security realm. The return value should be a tuple, ``(user,
- password)``, which can be used for basic authentication.
-
- The implementation prompts for this information on the terminal; an application
- should override this method to use an appropriate interaction model in the local
- environment.
-
-
.. _urllib-examples:
Examples
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 7515440..f647bca 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -173,6 +173,27 @@
operate independently of the ZipFile.
+.. method:: ZipFile.extract(member[, path[, pwd]])
+
+ Extract a member from the archive to the current working directory, using its
+ full name. Its file information is extracted as accurately as possible.
+ *path* specifies a different directory to extract to. *member* can be a
+ filename or a :class:`ZipInfo` object. *pwd* is the password used for
+ encrypted files.
+
+ .. versionadded:: 2.6
+
+
+.. method:: ZipFile.extractall([path[, members[, pwd]]])
+
+ Extract all members from the archive to the current working directory. *path*
+ specifies a different directory to extract to. *members* is optional and must
+ be a subset of the list returned by :meth:`namelist`. *pwd* is the password
+ used for encrypted files.
+
+ .. versionadded:: 2.6
+
+
.. method:: ZipFile.printdir()
Print a table of contents for the archive to ``sys.stdout``.
@@ -237,6 +258,13 @@
created with mode ``'r'`` will raise a :exc:`RuntimeError`. Calling
:meth:`writestr` on a closed ZipFile will raise a :exc:`RuntimeError`.
+ .. note::
+
+ When passing a :class:`ZipInfo` instance as the *zinfo_or_acrname* parameter,
+ the compression method used will be that specified in the *compress_type*
+ member of the given :class:`ZipInfo` instance. By default, the
+ :class:`ZipInfo` constructor sets this member to :const:`ZIP_STORED`.
+
The following data attribute is also available: