Edit File: userdict.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>8.12. UserDict — Class wrapper for dictionary objects — Python v2.6.6 documentation</title> <link rel="stylesheet" href="../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '2.6.6', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python v2.6.6 documentation" href="../_static/opensearch.xml"/> <link rel="author" title="About these documents" href="../about.html" /> <link rel="copyright" title="Copyright" href="../copyright.html" /> <link rel="top" title="Python v2.6.6 documentation" href="../index.html" /> <link rel="up" title="8. Data Types" href="datatypes.html" /> <link rel="next" title="8.15. types — Names for built-in types" href="types.html" /> <link rel="prev" title="8.11. weakref — Weak references" href="weakref.html" /> <link rel="shortcut icon" type="image/png" href="../_static/py.png" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../modindex.html" title="Global Module Index" accesskey="M">modules</a> |</li> <li class="right" > <a href="types.html" title="8.15. types — Names for built-in types" accesskey="N">next</a> |</li> <li class="right" > <a href="weakref.html" title="8.11. weakref — Weak references" accesskey="P">previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="../index.html">Python v2.6.6 documentation</a> »</li> <li><a href="index.html" >The Python Standard Library</a> »</li> <li><a href="datatypes.html" accesskey="U">8. Data Types</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="module-UserDict"> <h1>8.12. <tt class="xref docutils literal"><span class="pre">UserDict</span></tt> — Class wrapper for dictionary objects<a class="headerlink" href="#module-UserDict" title="Permalink to this headline">¶</a></h1> <p>The module defines a mixin, <a title="UserDict.DictMixin" class="reference internal" href="#UserDict.DictMixin"><tt class="xref docutils literal"><span class="pre">DictMixin</span></tt></a>, 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 as the shelve module).</p> <p>This module also defines a class, <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a>, that acts as a wrapper around dictionary objects. The need for this class has been largely supplanted by the ability to subclass directly from <a title="dict" class="reference external" href="stdtypes.html#dict"><tt class="xref docutils literal"><span class="pre">dict</span></tt></a> (a feature that became available starting with Python version 2.2). Prior to the introduction of <a title="dict" class="reference external" href="stdtypes.html#dict"><tt class="xref docutils literal"><span class="pre">dict</span></tt></a>, the <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> class was used to create dictionary-like sub-classes that obtained new behaviors by overriding existing methods or adding new ones.</p> <p>The <tt class="xref docutils literal"><span class="pre">UserDict</span></tt> module defines the <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> class and <a title="UserDict.DictMixin" class="reference internal" href="#UserDict.DictMixin"><tt class="xref docutils literal"><span class="pre">DictMixin</span></tt></a>:</p> <dl class="class"> <dt id="UserDict.UserDict"> <em class="property">class </em><tt class="descclassname">UserDict.</tt><tt class="descname">UserDict</tt><big>(</big><span class="optional">[</span><em>initialdata</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserDict.UserDict" title="Permalink to this definition">¶</a></dt> <dd><p>Class that simulates a dictionary. The instance’s contents are kept in a regular dictionary, which is accessible via the <tt class="xref docutils literal"><span class="pre">data</span></tt> attribute of <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> instances. If <em>initialdata</em> is provided, <tt class="xref docutils literal"><span class="pre">data</span></tt> is initialized with its contents; note that a reference to <em>initialdata</em> will not be kept, allowing it be used for other purposes.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">For backward compatibility, instances of <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> are not iterable.</p> </div> </dd></dl> <dl class="class"> <dt id="UserDict.IterableUserDict"> <em class="property">class </em><tt class="descclassname">UserDict.</tt><tt class="descname">IterableUserDict</tt><big>(</big><span class="optional">[</span><em>initialdata</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserDict.IterableUserDict" title="Permalink to this definition">¶</a></dt> <dd>Subclass of <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> that supports direct iteration (e.g. <tt class="docutils literal"><span class="pre">for</span> <span class="pre">key</span> <span class="pre">in</span> <span class="pre">myDict</span></tt>).</dd></dl> <p>In addition to supporting the methods and operations of mappings (see section <a class="reference external" href="stdtypes.html#typesmapping"><em>Mapping Types — dict</em></a>), <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> and <a title="UserDict.IterableUserDict" class="reference internal" href="#UserDict.IterableUserDict"><tt class="xref docutils literal"><span class="pre">IterableUserDict</span></tt></a> instances provide the following attribute:</p> <dl class="attribute"> <dt id="UserDict.IterableUserDict.data"> <tt class="descclassname">IterableUserDict.</tt><tt class="descname">data</tt><a class="headerlink" href="#UserDict.IterableUserDict.data" title="Permalink to this definition">¶</a></dt> <dd>A real dictionary used to store the contents of the <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> class.</dd></dl> <dl class="class"> <dt id="UserDict.DictMixin"> <em class="property">class </em><tt class="descclassname">UserDict.</tt><tt class="descname">DictMixin</tt><a class="headerlink" href="#UserDict.DictMixin" title="Permalink to this definition">¶</a></dt> <dd><p>Mixin defining all dictionary methods for classes that already have a minimum dictionary interface including <a title="object.__getitem__" class="reference external" href="../reference/datamodel.html#object.__getitem__"><tt class="xref docutils literal"><span class="pre">__getitem__()</span></tt></a>, <a title="object.__setitem__" class="reference external" href="../reference/datamodel.html#object.__setitem__"><tt class="xref docutils literal"><span class="pre">__setitem__()</span></tt></a>, <a title="object.__delitem__" class="reference external" href="../reference/datamodel.html#object.__delitem__"><tt class="xref docutils literal"><span class="pre">__delitem__()</span></tt></a>, and <tt class="xref docutils literal"><span class="pre">keys()</span></tt>.</p> <p>This mixin should be used as a superclass. Adding each of the above methods adds progressively more functionality. For instance, defining all but <a title="object.__delitem__" class="reference external" href="../reference/datamodel.html#object.__delitem__"><tt class="xref docutils literal"><span class="pre">__delitem__()</span></tt></a> will preclude only <tt class="xref docutils literal"><span class="pre">pop()</span></tt> and <tt class="xref docutils literal"><span class="pre">popitem()</span></tt> from the full interface.</p> <p>In addition to the four base methods, progressively more efficiency comes with defining <a title="object.__contains__" class="reference external" href="../reference/datamodel.html#object.__contains__"><tt class="xref docutils literal"><span class="pre">__contains__()</span></tt></a>, <a title="object.__iter__" class="reference external" href="../reference/datamodel.html#object.__iter__"><tt class="xref docutils literal"><span class="pre">__iter__()</span></tt></a>, and <tt class="xref docutils literal"><span class="pre">iteritems()</span></tt>.</p> <p>Since the mixin has no knowledge of the subclass constructor, it does not define <a title="object.__init__" class="reference external" href="../reference/datamodel.html#object.__init__"><tt class="xref docutils literal"><span class="pre">__init__()</span></tt></a> or <tt class="xref docutils literal"><span class="pre">copy()</span></tt>.</p> <p>Starting with Python version 2.6, it is recommended to use <tt class="xref docutils literal"><span class="pre">collections.MutableMapping</span></tt> instead of <a title="UserDict.DictMixin" class="reference internal" href="#UserDict.DictMixin"><tt class="xref docutils literal"><span class="pre">DictMixin</span></tt></a>.</p> </dd></dl> </div> <div class="section" id="module-UserList"> <h1>8.13. <tt class="xref docutils literal"><span class="pre">UserList</span></tt> — Class wrapper for list objects<a class="headerlink" href="#module-UserList" title="Permalink to this headline">¶</a></h1> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">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 <a title="list" class="reference external" href="functions.html#list"><tt class="xref docutils literal"><span class="pre">list</span></tt></a> type.</p> </div> <p>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 and override existing methods or add new ones. In this way one can add new behaviors to lists.</p> <p>The <tt class="xref docutils literal"><span class="pre">UserList</span></tt> module defines the <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> class:</p> <dl class="class"> <dt id="UserList.UserList"> <em class="property">class </em><tt class="descclassname">UserList.</tt><tt class="descname">UserList</tt><big>(</big><span class="optional">[</span><em>list</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserList.UserList" title="Permalink to this definition">¶</a></dt> <dd><p>Class that simulates a list. The instance’s contents are kept in a regular list, which is accessible via the <a title="UserList.UserList.data" class="reference internal" href="#UserList.UserList.data"><tt class="xref docutils literal"><span class="pre">data</span></tt></a> attribute of <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> instances. The instance’s contents are initially set to a copy of <em>list</em>, defaulting to the empty list <tt class="docutils literal"><span class="pre">[]</span></tt>. <em>list</em> can be any iterable, e.g. a real Python list or a <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> object.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">The <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> class has been moved to the <a title="High-performance datatypes" class="reference external" href="collections.html#module-collections"><tt class="xref docutils literal"><span class="pre">collections</span></tt></a> module in Python 3.0. The <a class="reference external" href="../glossary.html#term-to3"><em class="xref">2to3</em></a> tool will automatically adapt imports when converting your sources to 3.0.</p> </div> </dd></dl> <p>In addition to supporting the methods and operations of mutable sequences (see section <a class="reference external" href="stdtypes.html#typesseq"><em>Sequence Types — str, unicode, list, tuple, buffer, xrange</em></a>), <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> instances provide the following attribute:</p> <dl class="attribute"> <dt id="UserList.UserList.data"> <tt class="descclassname">UserList.</tt><tt class="descname">data</tt><a class="headerlink" href="#UserList.UserList.data" title="Permalink to this definition">¶</a></dt> <dd>A real Python list object used to store the contents of the <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> class.</dd></dl> <p><strong>Subclassing requirements:</strong> Subclasses of <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> are expect to offer a constructor which can be called with either no arguments or one argument. List operations which return a new sequence attempt to create an instance of the actual implementation class. To do so, it assumes that the constructor can be called with a single parameter, which is a sequence object used as a data source.</p> <p>If a derived class does not wish to comply with this requirement, all of the special methods supported by this class will need to be overridden; please consult the sources for information about the methods which need to be provided in that case.</p> <p class="versionchanged"> <span class="versionmodified">Changed in version 2.0: </span>Python versions 1.5.2 and 1.6 also required that the constructor be callable with no parameters, and offer a mutable <tt class="xref docutils literal"><span class="pre">data</span></tt> attribute. Earlier versions of Python did not attempt to create instances of the derived class.</p> </div> <div class="section" id="module-UserString"> <h1>8.14. <tt class="xref docutils literal"><span class="pre">UserString</span></tt> — Class wrapper for string objects<a class="headerlink" href="#module-UserString" title="Permalink to this headline">¶</a></h1> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">This <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> class from 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 <a title="str" class="reference external" href="functions.html#str"><tt class="xref docutils literal"><span class="pre">str</span></tt></a> type instead of using <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> (there is no built-in equivalent to <a title="UserString.MutableString" class="reference internal" href="#UserString.MutableString"><tt class="xref docutils literal"><span class="pre">MutableString</span></tt></a>).</p> </div> <p>This module defines a class that acts as a wrapper around string objects. It is a useful base class for your own string-like classes, which can inherit from them and override existing methods or add new ones. In this way one can add new behaviors to strings.</p> <p>It should be noted that these classes are highly inefficient compared to real string or Unicode objects; this is especially the case for <a title="UserString.MutableString" class="reference internal" href="#UserString.MutableString"><tt class="xref docutils literal"><span class="pre">MutableString</span></tt></a>.</p> <p>The <tt class="xref docutils literal"><span class="pre">UserString</span></tt> module defines the following classes:</p> <dl class="class"> <dt id="UserString.UserString"> <em class="property">class </em><tt class="descclassname">UserString.</tt><tt class="descname">UserString</tt><big>(</big><span class="optional">[</span><em>sequence</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserString.UserString" title="Permalink to this definition">¶</a></dt> <dd><p>Class that simulates a string or a Unicode string object. The instance’s content is kept in a regular string or Unicode string object, which is accessible via the <tt class="xref docutils literal"><span class="pre">data</span></tt> attribute of <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> instances. The instance’s contents are initially set to a copy of <em>sequence</em>. <em>sequence</em> can be either a regular Python string or Unicode string, an instance of <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> (or a subclass) or an arbitrary sequence which can be converted into a string using the built-in <a title="str" class="reference external" href="functions.html#str"><tt class="xref docutils literal"><span class="pre">str()</span></tt></a> function.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">The <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> class has been moved to the <a title="High-performance datatypes" class="reference external" href="collections.html#module-collections"><tt class="xref docutils literal"><span class="pre">collections</span></tt></a> module in Python 3.0. The <a class="reference external" href="../glossary.html#term-to3"><em class="xref">2to3</em></a> tool will automatically adapt imports when converting your sources to 3.0.</p> </div> </dd></dl> <dl class="class"> <dt id="UserString.MutableString"> <em class="property">class </em><tt class="descclassname">UserString.</tt><tt class="descname">MutableString</tt><big>(</big><span class="optional">[</span><em>sequence</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserString.MutableString" title="Permalink to this definition">¶</a></dt> <dd><p>This class is derived from the <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> above and redefines strings to be <em>mutable</em>. Mutable strings can’t be used as dictionary keys, because dictionaries require <em>immutable</em> objects as keys. The main intention of this class is to serve as an educational example for inheritance and necessity to remove (override) the <a title="object.__hash__" class="reference external" href="../reference/datamodel.html#object.__hash__"><tt class="xref docutils literal"><span class="pre">__hash__()</span></tt></a> method in order to trap attempts to use a mutable object as dictionary key, which would be otherwise very error prone and hard to track down.</p> <p class="deprecated"> <span class="versionmodified">Deprecated since version 2.6: </span>The <a title="UserString.MutableString" class="reference internal" href="#UserString.MutableString"><tt class="xref docutils literal"><span class="pre">MutableString</span></tt></a> class has been removed in Python 3.0.</p> </dd></dl> <p>In addition to supporting the methods and operations of string and Unicode objects (see section <a class="reference external" href="stdtypes.html#string-methods"><em>String Methods</em></a>), <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> instances provide the following attribute:</p> <dl class="attribute"> <dt id="UserString.MutableString.data"> <tt class="descclassname">MutableString.</tt><tt class="descname">data</tt><a class="headerlink" href="#UserString.MutableString.data" title="Permalink to this definition">¶</a></dt> <dd>A real Python string or Unicode object used to store the content of the <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> class.</dd></dl> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference external" href="#">8.12. <tt class="docutils literal"><span class="pre">UserDict</span></tt> — Class wrapper for dictionary objects</a></li> <li><a class="reference external" href="#module-UserList">8.13. <tt class="docutils literal"><span class="pre">UserList</span></tt> — Class wrapper for list objects</a></li> <li><a class="reference external" href="#module-UserString">8.14. <tt class="docutils literal"><span class="pre">UserString</span></tt> — Class wrapper for string objects</a></li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="weakref.html" title="previous chapter">8.11. <tt class="docutils literal docutils literal"><span class="pre">weakref</span></tt> — Weak references</a></p> <h4>Next topic</h4> <p class="topless"><a href="types.html" title="next chapter">8.15. <tt class="docutils literal docutils literal docutils literal"><span class="pre">types</span></tt> — Names for built-in types</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../bugs.html">Report a Bug</a></li> <li><a href="../_sources/library/userdict.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="../search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="../modindex.html" title="Global Module Index" >modules</a> |</li> <li class="right" > <a href="types.html" title="8.15. types — Names for built-in types" >next</a> |</li> <li class="right" > <a href="weakref.html" title="8.11. weakref — Weak references" >previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="../index.html">Python v2.6.6 documentation</a> »</li> <li><a href="index.html" >The Python Standard Library</a> »</li> <li><a href="datatypes.html" >8. Data Types</a> »</li> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 1990-2011, Python Software Foundation. <br /> The Python Software Foundation is a non-profit corporation. <a href="http://www.python.org/psf/donations/">Please donate.</a> <br /> Last updated on Jul 20, 2011. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.6. </div> </body> </html>
Back to File Manager