1 

     2 :mod:`UserDict` --- Class wrapper for dictionary objects

     3 ========================================================

     4 

     5 .. module:: UserDict

     6    :synopsis: Class wrapper for dictionary objects.

     7 

     8 

     9 The module defines a mixin,  :class:`DictMixin`, defining all dictionary methods

    10 for classes that already have a minimum mapping interface.  This greatly

    11 simplifies writing classes that need to be substitutable for dictionaries (such

    12 as the shelve module).

    13 

    14 This module also defines a class, :class:`UserDict`, that acts as a wrapper

    15 around dictionary objects.  The need for this class has been largely supplanted

    16 by the ability to subclass directly from :class:`dict` (a feature that became

    17 available starting with Python version 2.2).  Prior to the introduction of

    18 :class:`dict`, the :class:`UserDict` class was used to create dictionary-like

    19 sub-classes that obtained new behaviors by overriding existing methods or adding

    20 new ones.

    21 

    22 The :mod:`UserDict` module defines the :class:`UserDict` class and

    23 :class:`DictMixin`:

    24 

    25 

    26 .. class:: UserDict([initialdata])

    27 

    28    Class that simulates a dictionary.  The instance's contents are kept in a

    29    regular dictionary, which is accessible via the :attr:`data` attribute of

    30    :class:`UserDict` instances.  If *initialdata* is provided, :attr:`data` is

    31    initialized with its contents; note that a reference to *initialdata* will not

    32    be kept, allowing it be used for other purposes.

    33 

    34    .. note::

    35 

    36       For backward compatibility, instances of :class:`UserDict` are not iterable.

    37 

    38 

    39 .. class:: IterableUserDict([initialdata])

    40 

    41    Subclass of :class:`UserDict` that supports direct iteration (e.g.  ``for key in

    42    myDict``).

    43 

    44 In addition to supporting the methods and operations of mappings (see section

    45 :ref:`typesmapping`), :class:`UserDict` and :class:`IterableUserDict` instances

    46 provide the following attribute:

    47 

    48 

    49 .. attribute:: IterableUserDict.data

    50 

    51    A real dictionary used to store the contents of the :class:`UserDict` class.

    52 

    53 

    54 .. class:: DictMixin()

    55 

    56    Mixin defining all dictionary methods for classes that already have a minimum

    57    dictionary interface including :meth:`__getitem__`, :meth:`__setitem__`,

    58    :meth:`__delitem__`, and :meth:`keys`.

    59 

    60    This mixin should be used as a superclass.  Adding each of the above methods

    61    adds progressively more functionality.  For instance, defining all but

    62    :meth:`__delitem__` will preclude only :meth:`pop` and :meth:`popitem` from the

    63    full interface.

    64 

    65    In addition to the four base methods, progressively more efficiency comes with

    66    defining :meth:`__contains__`, :meth:`__iter__`, and :meth:`iteritems`.

    67 

    68    Since the mixin has no knowledge of the subclass constructor, it does not define

    69    :meth:`__init__` or :meth:`copy`.

    70 

    71    Starting with Python version 2.6, it is recommended to use

    72    :class:`collections.MutableMapping` instead of :class:`DictMixin`.

    73 

    74 :mod:`UserList` --- Class wrapper for list objects

    75 ==================================================

    76 

    77 .. module:: UserList

    78    :synopsis: Class wrapper for list objects.

    79 

    80 

    81 .. note::

    82 

    83    This module is available for backward compatibility only.  If you are writing

    84    code that does not need to work with versions of Python earlier than Python 2.2,

    85    please consider subclassing directly from the built-in :class:`list` type.

    86 

    87 This module defines a class that acts as a wrapper around list objects.  It is a

    88 useful base class for your own list-like classes, which can inherit from them

    89 and override existing methods or add new ones.  In this way one can add new

    90 behaviors to lists.

    91 

    92 The :mod:`UserList` module defines the :class:`UserList` class:

    93 

    94 

    95 .. class:: UserList([list])

    96 

    97    Class that simulates a list.  The instance's contents are kept in a regular

    98    list, which is accessible via the :attr:`data` attribute of :class:`UserList`

    99    instances.  The instance's contents are initially set to a copy of *list*,

   100    defaulting to the empty list ``[]``.  *list* can be any iterable, e.g. a

   101    real Python list or a :class:`UserList` object.

   102 

   103    .. note::

   104       The :class:`UserList` class has been moved to the :mod:`collections`

   105       module in Python 3.0. The :term:`2to3` tool will automatically adapt

   106       imports when converting your sources to 3.0.

   107 

   108 

   109 In addition to supporting the methods and operations of mutable sequences (see

   110 section :ref:`typesseq`), :class:`UserList` instances provide the following

   111 attribute:

   112 

   113 

   114 .. attribute:: UserList.data

   115 

   116    A real Python list object used to store the contents of the :class:`UserList`

   117    class.

   118 

   119 **Subclassing requirements:** Subclasses of :class:`UserList` are expect to

   120 offer a constructor which can be called with either no arguments or one

   121 argument.  List operations which return a new sequence attempt to create an

   122 instance of the actual implementation class.  To do so, it assumes that the

   123 constructor can be called with a single parameter, which is a sequence object

   124 used as a data source.

   125 

   126 If a derived class does not wish to comply with this requirement, all of the

   127 special methods supported by this class will need to be overridden; please

   128 consult the sources for information about the methods which need to be provided

   129 in that case.

   130 

   131 .. versionchanged:: 2.0

   132    Python versions 1.5.2 and 1.6 also required that the constructor be callable

   133    with no parameters, and offer a mutable :attr:`data` attribute.  Earlier

   134    versions of Python did not attempt to create instances of the derived class.

   135 

   136 

   137 :mod:`UserString` --- Class wrapper for string objects

   138 ======================================================

   139 

   140 .. module:: UserString

   141    :synopsis: Class wrapper for string objects.

   142 .. moduleauthor:: Peter Funk <pf@artcom-gmbh.de>

   143 .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>

   144 

   145 

   146 .. note::

   147 

   148    This :class:`UserString` class from this module is available for backward

   149    compatibility only.  If you are writing code that does not need to work with

   150    versions of Python earlier than Python 2.2, please consider subclassing directly

   151    from the built-in :class:`str` type instead of using :class:`UserString` (there

   152    is no built-in equivalent to :class:`MutableString`).

   153 

   154 This module defines a class that acts as a wrapper around string objects.  It is

   155 a useful base class for your own string-like classes, which can inherit from

   156 them and override existing methods or add new ones.  In this way one can add new

   157 behaviors to strings.

   158 

   159 It should be noted that these classes are highly inefficient compared to real

   160 string or Unicode objects; this is especially the case for

   161 :class:`MutableString`.

   162 

   163 The :mod:`UserString` module defines the following classes:

   164 

   165 

   166 .. class:: UserString([sequence])

   167 

   168    Class that simulates a string or a Unicode string object.  The instance's

   169    content is kept in a regular string or Unicode string object, which is

   170    accessible via the :attr:`data` attribute of :class:`UserString` instances.  The

   171    instance's contents are initially set to a copy of *sequence*.  *sequence* can

   172    be either a regular Python string or Unicode string, an instance of

   173    :class:`UserString` (or a subclass) or an arbitrary sequence which can be

   174    converted into a string using the built-in :func:`str` function.

   175 

   176    .. note::

   177       The :class:`UserString` class has been moved to the :mod:`collections`

   178       module in Python 3.0. The :term:`2to3` tool will automatically adapt

   179       imports when converting your sources to 3.0.

   180 

   181 

   182 

   183 .. class:: MutableString([sequence])

   184 

   185    This class is derived from the :class:`UserString` above and redefines strings

   186    to be *mutable*.  Mutable strings can't be used as dictionary keys, because

   187    dictionaries require *immutable* objects as keys.  The main intention of this

   188    class is to serve as an educational example for inheritance and necessity to

   189    remove (override) the :meth:`__hash__` method in order to trap attempts to use a

   190    mutable object as dictionary key, which would be otherwise very error prone and

   191    hard to track down.

   192 

   193    .. deprecated:: 2.6

   194       The :class:`MutableString` class has been removed in Python 3.0.

   195 

   196 In addition to supporting the methods and operations of string and Unicode

   197 objects (see section :ref:`string-methods`), :class:`UserString` instances

   198 provide the following attribute:

   199 

   200 

   201 .. attribute:: MutableString.data

   202 

   203    A real Python string or Unicode object used to store the content of the

   204    :class:`UserString` class.

   205