python
diff --git a/‎Doc/library/collections.rst
Lines changed: 18 additions & 20 deletions b/‎Doc/library/collections.rst
Lines changed: 18 additions & 20 deletions
diff --git a/‎Doc/library/logging.rst
Lines changed: 46 additions & 0 deletions b/‎Doc/library/logging.rst
Lines changed: 46 additions & 0 deletions
diff --git a/‎Doc/library/stdtypes.rst
Lines changed: 2 additions & 1 deletion b/‎Doc/library/stdtypes.rst
Lines changed: 2 additions & 1 deletion
diff --git a/‎Doc/library/sys.rst
Lines changed: 11 additions & 0 deletions b/‎Doc/library/sys.rst
Lines changed: 11 additions & 0 deletions
diff --git a/‎Doc/library/urllib.rst
Lines changed: 65 additions & 73 deletions b/‎Doc/library/urllib.rst
Lines changed: 65 additions & 73 deletions
@@ -382,7 +382,7 @@ Setting the :attr:`default_factory` to :class:`set` makes the
 .. _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 @@ they add the ability to access fields by name instead of position index.
 
    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 @@ by the :mod:`csv` or :mod:`sqlite3` modules::
 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 @@ three additional methods and one attribute.
       >>> 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 @@ three additional methods and one attribute.
       >>> 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 @@ three additional methods and one attribute.
       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 @@ three additional methods and one attribute.
       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 @@ a fixed-width print format::
         @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)
+
+    >>> for p in Point(3,4), Point(14,5), Point(9./7,6):
+            print p
 
-    >>> 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)
+    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 @@ faster versions that bypass error-checking and localize variable access::
         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)
 
@@ -1118,6 +1118,52 @@ This example uses console and file handlers, but you can use any number and
 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
 
@@ -435,8 +435,9 @@ the iteration methods.
 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
 
@@ -438,6 +438,17 @@ always available.
    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
 
@@ -1,4 +1,3 @@
-
 :mod:`urllib` --- Open arbitrary resources by URL
 =================================================
 
@@ -17,8 +16,8 @@ built-in function :func:`open`, but accepts Universal Resource Locators (URLs)
 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 @@ It defines the following public functions:
    :func:`urlretrieve`.
 
 
+Utility functions
+-----------------
+
 .. function:: quote(string[, safe])
 
    Replace special characters in *string* using the ``%xx`` escape. Letters,
@@ -235,6 +237,9 @@ It defines the following public functions:
    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 @@ It defines the following public functions:
    :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 @@ It defines the following public functions:
       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 @@ It defines the following public functions:
    *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 @@ Restrictions:
   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