From c5f310c827c80ac29a3a883af84d07bef161013e Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Wed, 1 Feb 2012 19:00:09 -0800 Subject: [PATCH] Clarify the note for UserList --- Doc/library/userdict.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/Doc/library/userdict.rst b/Doc/library/userdict.rst index 1c756742cd5..2e14c1204dc 100644 --- a/Doc/library/userdict.rst +++ b/Doc/library/userdict.rst @@ -83,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