/Doc/library/userdict.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 205 lines · 138 code · 67 blank · 0 comment · 0 complexity · 637335c1fd540fe14d40402d6b8fd148 MD5 · raw file

  1. :mod:`UserDict` --- Class wrapper for dictionary objects
  2. ========================================================
  3. .. module:: UserDict
  4. :synopsis: Class wrapper for dictionary objects.
  5. The module defines a mixin, :class:`DictMixin`, defining all dictionary methods
  6. for classes that already have a minimum mapping interface. This greatly
  7. simplifies writing classes that need to be substitutable for dictionaries (such
  8. as the shelve module).
  9. This module also defines a class, :class:`UserDict`, that acts as a wrapper
  10. around dictionary objects. The need for this class has been largely supplanted
  11. by the ability to subclass directly from :class:`dict` (a feature that became
  12. available starting with Python version 2.2). Prior to the introduction of
  13. :class:`dict`, the :class:`UserDict` class was used to create dictionary-like
  14. sub-classes that obtained new behaviors by overriding existing methods or adding
  15. new ones.
  16. The :mod:`UserDict` module defines the :class:`UserDict` class and
  17. :class:`DictMixin`:
  18. .. class:: UserDict([initialdata])
  19. Class that simulates a dictionary. The instance's contents are kept in a
  20. regular dictionary, which is accessible via the :attr:`data` attribute of
  21. :class:`UserDict` instances. If *initialdata* is provided, :attr:`data` is
  22. initialized with its contents; note that a reference to *initialdata* will not
  23. be kept, allowing it be used for other purposes.
  24. .. note::
  25. For backward compatibility, instances of :class:`UserDict` are not iterable.
  26. .. class:: IterableUserDict([initialdata])
  27. Subclass of :class:`UserDict` that supports direct iteration (e.g. ``for key in
  28. myDict``).
  29. In addition to supporting the methods and operations of mappings (see section
  30. :ref:`typesmapping`), :class:`UserDict` and :class:`IterableUserDict` instances
  31. provide the following attribute:
  32. .. attribute:: IterableUserDict.data
  33. A real dictionary used to store the contents of the :class:`UserDict` class.
  34. .. class:: DictMixin()
  35. Mixin defining all dictionary methods for classes that already have a minimum
  36. dictionary interface including :meth:`__getitem__`, :meth:`__setitem__`,
  37. :meth:`__delitem__`, and :meth:`keys`.
  38. This mixin should be used as a superclass. Adding each of the above methods
  39. adds progressively more functionality. For instance, defining all but
  40. :meth:`__delitem__` will preclude only :meth:`pop` and :meth:`popitem` from the
  41. full interface.
  42. In addition to the four base methods, progressively more efficiency comes with
  43. defining :meth:`__contains__`, :meth:`__iter__`, and :meth:`iteritems`.
  44. Since the mixin has no knowledge of the subclass constructor, it does not define
  45. :meth:`__init__` or :meth:`copy`.
  46. Starting with Python version 2.6, it is recommended to use
  47. :class:`collections.MutableMapping` instead of :class:`DictMixin`.
  48. :mod:`UserList` --- Class wrapper for list objects
  49. ==================================================
  50. .. module:: UserList
  51. :synopsis: Class wrapper for list objects.
  52. .. note::
  53. This module is available for backward compatibility only. If you are writing
  54. code that does not need to work with versions of Python earlier than Python 2.2,
  55. please consider subclassing directly from the built-in :class:`list` type.
  56. This module defines a class that acts as a wrapper around list objects. It is a
  57. useful base class for your own list-like classes, which can inherit from them
  58. and override existing methods or add new ones. In this way one can add new
  59. behaviors to lists.
  60. The :mod:`UserList` module defines the :class:`UserList` class:
  61. .. class:: UserList([list])
  62. Class that simulates a list. The instance's contents are kept in a regular
  63. list, which is accessible via the :attr:`data` attribute of :class:`UserList`
  64. instances. The instance's contents are initially set to a copy of *list*,
  65. defaulting to the empty list ``[]``. *list* can be any iterable, e.g. a
  66. real Python list or a :class:`UserList` object.
  67. .. note::
  68. The :class:`UserList` class has been moved to the :mod:`collections`
  69. module in Python 3.0. The :term:`2to3` tool will automatically adapt
  70. imports when converting your sources to 3.0.
  71. In addition to supporting the methods and operations of mutable sequences (see
  72. section :ref:`typesseq`), :class:`UserList` instances provide the following
  73. attribute:
  74. .. attribute:: UserList.data
  75. A real Python list object used to store the contents of the :class:`UserList`
  76. class.
  77. **Subclassing requirements:** Subclasses of :class:`UserList` are expect to
  78. offer a constructor which can be called with either no arguments or one
  79. argument. List operations which return a new sequence attempt to create an
  80. instance of the actual implementation class. To do so, it assumes that the
  81. constructor can be called with a single parameter, which is a sequence object
  82. used as a data source.
  83. If a derived class does not wish to comply with this requirement, all of the
  84. special methods supported by this class will need to be overridden; please
  85. consult the sources for information about the methods which need to be provided
  86. in that case.
  87. .. versionchanged:: 2.0
  88. Python versions 1.5.2 and 1.6 also required that the constructor be callable
  89. with no parameters, and offer a mutable :attr:`data` attribute. Earlier
  90. versions of Python did not attempt to create instances of the derived class.
  91. :mod:`UserString` --- Class wrapper for string objects
  92. ======================================================
  93. .. module:: UserString
  94. :synopsis: Class wrapper for string objects.
  95. .. moduleauthor:: Peter Funk <pf@artcom-gmbh.de>
  96. .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
  97. .. note::
  98. This :class:`UserString` class from this module is available for backward
  99. compatibility only. If you are writing code that does not need to work with
  100. versions of Python earlier than Python 2.2, please consider subclassing directly
  101. from the built-in :class:`str` type instead of using :class:`UserString` (there
  102. is no built-in equivalent to :class:`MutableString`).
  103. This module defines a class that acts as a wrapper around string objects. It is
  104. a useful base class for your own string-like classes, which can inherit from
  105. them and override existing methods or add new ones. In this way one can add new
  106. behaviors to strings.
  107. It should be noted that these classes are highly inefficient compared to real
  108. string or Unicode objects; this is especially the case for
  109. :class:`MutableString`.
  110. The :mod:`UserString` module defines the following classes:
  111. .. class:: UserString([sequence])
  112. Class that simulates a string or a Unicode string object. The instance's
  113. content is kept in a regular string or Unicode string object, which is
  114. accessible via the :attr:`data` attribute of :class:`UserString` instances. The
  115. instance's contents are initially set to a copy of *sequence*. *sequence* can
  116. be either a regular Python string or Unicode string, an instance of
  117. :class:`UserString` (or a subclass) or an arbitrary sequence which can be
  118. converted into a string using the built-in :func:`str` function.
  119. .. note::
  120. The :class:`UserString` class has been moved to the :mod:`collections`
  121. module in Python 3.0. The :term:`2to3` tool will automatically adapt
  122. imports when converting your sources to 3.0.
  123. .. class:: MutableString([sequence])
  124. This class is derived from the :class:`UserString` above and redefines strings
  125. to be *mutable*. Mutable strings can't be used as dictionary keys, because
  126. dictionaries require *immutable* objects as keys. The main intention of this
  127. class is to serve as an educational example for inheritance and necessity to
  128. remove (override) the :meth:`__hash__` method in order to trap attempts to use a
  129. mutable object as dictionary key, which would be otherwise very error prone and
  130. hard to track down.
  131. .. deprecated:: 2.6
  132. The :class:`MutableString` class has been removed in Python 3.0.
  133. In addition to supporting the methods and operations of string and Unicode
  134. objects (see section :ref:`string-methods`), :class:`UserString` instances
  135. provide the following attribute:
  136. .. attribute:: MutableString.data
  137. A real Python string or Unicode object used to store the content of the
  138. :class:`UserString` class.