Update to 2.7.3

[profile/ivi/python.git] / Doc / library / userdict.rst

diff --git a/Doc/library/userdict.rst b/Doc/library/userdict.rst
index ab9ab04..2e14c12 100644 (file)
--- a/Doc/library/userdict.rst
+++ b/Doc/library/userdict.rst
@@ -1,4 +1,3 @@
-
 :mod:`UserDict` --- Class wrapper for dictionary objects
 ========================================================
 
@@ -6,6 +5,10 @@
    :synopsis: Class wrapper for dictionary objects.
 
 
+**Source code:** :source:`Lib/UserDict.py`
+
+--------------
+
 The module defines a mixin,  :class:`DictMixin`, defining all dictionary methods
 for classes that already have a minimum mapping interface.  This greatly
 simplifies writing classes that need to be substitutable for dictionaries (such
@@ -19,11 +22,6 @@ available starting with Python version 2.2).  Prior to the introduction of
 sub-classes that obtained new behaviors by overriding existing methods or adding
 new ones.
 
-.. seealso::
-
-   Latest version of the `UserDict Python source code
-   <http://svn.python.org/view/python/branches/release27-maint/Lib/UserDict.py?view=markup>`_
-
 The :mod:`UserDict` module defines the :class:`UserDict` class and
 :class:`DictMixin`:
 
@@ -85,9 +83,18 @@ provide the following attribute:
 
 .. note::
 
-   This module is available for backward compatibility only.  If you are writing
-   code that does not need to work with versions of Python earlier than Python 2.2,
-   please consider subclassing directly from the built-in :class:`list` type.
+   When Python 2.2 was released, many of the use cases for this class were
+   subsumed by the ability to subclass :class:`list` directly.  However, a
+   handful of use cases remain.
+
+   This module provides a list-interface around an underlying data store.  By
+   default, that data store is a :class:`list`; however, it can be used to wrap
+   a list-like interface around other objects (such as persistent storage).
+
+   In addition, this class can be mixed-in with built-in classes using multiple
+   inheritance.  This can sometimes be useful.  For example, you can inherit
+   from :class:`UserList` and :class:`str` at the same time.  That would not be
+   possible with both a real :class:`list` and a real :class:`str`.
 
 This module defines a class that acts as a wrapper around list objects.  It is a
 useful base class for your own list-like classes, which can inherit from them