File: collections.html

package info (click to toggle)
sqlalchemy 0.9.8%2Bdfsg-0.1
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 23,952 kB
ctags: 24,534
sloc: python: 152,282; ansic: 1,346; makefile: 257; xml: 17
file content (1090 lines) | stat: -rw-r--r-- 101,155 bytes
<!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>
            
    
                Collection Configuration and Techniques
             &mdash;
    SQLAlchemy 0.9 Documentation

        </title>

        
            <!-- begin iterate through SQLA + sphinx environment css_files -->
                <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
                <link rel="stylesheet" href="../_static/docs.css" type="text/css" />
                <link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
                <link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
            <!-- end iterate through SQLA + sphinx environment css_files -->
        

        

    

    <!-- begin layout.mako headers -->

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '../',
          VERSION:     '0.9.8',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>

    <!-- begin iterate through sphinx environment script_files -->
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
    <!-- end iterate through sphinx environment script_files -->

    <script type="text/javascript" src="../_static/detectmobile.js"></script>
    <script type="text/javascript" src="../_static/init.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
        <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="SQLAlchemy 0.9 Documentation" href="../index.html" />
        <link rel="up" title="SQLAlchemy ORM" href="index.html" />
        <link rel="next" title="Mapping Class Inheritance Hierarchies" href="inheritance.html" />
        <link rel="prev" title="Relationship Configuration" href="relationships.html" />
    <!-- end layout.mako headers -->


    </head>
    <body>
        















<div id="docs-container">





<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
    <div id="docs-version-header">
        Release: <span class="version-num">0.9.8</span> | Release Date: October 13, 2014
    </div>

    <h1>SQLAlchemy 0.9 Documentation</h1>

</div>
</div>

<div id="docs-body-container">

    <div id="fixed-sidebar" class="withsidebar">


        <div id="docs-sidebar-popout">
            <h3><a href="../index.html">SQLAlchemy 0.9 Documentation</a></h3>

            <p id="sidebar-paginate">
                    <a href="index.html" title="SQLAlchemy ORM">Up</a> |

                    <a href="relationships.html" title="Relationship Configuration">Prev</a> |
                    <a href="inheritance.html" title="Mapping Class Inheritance Hierarchies">Next</a>
            </p>

            <p id="sidebar-topnav">
                <a href="../index.html">Contents</a> |
                <a href="../genindex.html">Index</a>
            </p>

            <div id="sidebar-search">
                <form class="search" action="../search.html" method="get">
                  <input type="text" name="q" size="12" /> <input type="submit" value="Search" />
                  <input type="hidden" name="check_keywords" value="yes" />
                  <input type="hidden" name="area" value="default" />
                </form>
            </div>

        </div>

        <div id="docs-sidebar">

        <h3><a href="#">            
                Collection Configuration and Techniques
            
        </a></h3>
        <ul>
<li><a class="reference internal" href="#">Collection Configuration and Techniques</a><ul>
<li><a class="reference internal" href="#working-with-large-collections">Working with Large Collections</a><ul>
<li><a class="reference internal" href="#dynamic-relationship-loaders">Dynamic Relationship Loaders</a></li>
<li><a class="reference internal" href="#setting-noload">Setting Noload</a></li>
<li><a class="reference internal" href="#using-passive-deletes">Using Passive Deletes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizing-collection-access">Customizing Collection Access</a><ul>
<li><a class="reference internal" href="#dictionary-collections">Dictionary Collections</a></li>
</ul>
</li>
<li><a class="reference internal" href="#custom-collection-implementations">Custom Collection Implementations</a><ul>
<li><a class="reference internal" href="#annotating-custom-collections-via-decorators">Annotating Custom Collections via Decorators</a></li>
<li><a class="reference internal" href="#custom-dictionary-based-collections">Custom Dictionary-Based Collections</a></li>
<li><a class="reference internal" href="#instrumentation-and-custom-types">Instrumentation and Custom Types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#collection-internals">Collection Internals</a></li>
</ul>
</li>
</ul>




        </div>

    </div>

    

    <div id="docs-body" class="withsidebar" >
        
<div class="section" id="collection-configuration-and-techniques">
<span id="collections-toplevel"></span><h1>Collection Configuration and Techniques<a class="headerlink" href="#collection-configuration-and-techniques" title="Permalink to this headline">¶</a></h1>
<p>The <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a> function defines a linkage between two classes.
When the linkage defines a one-to-many or many-to-many relationship, it&#8217;s
represented as a Python collection when objects are loaded and manipulated.
This section presents additional information about collection configuration
and techniques.</p>
<div class="section" id="working-with-large-collections">
<span id="largecollections"></span><h2>Working with Large Collections<a class="headerlink" href="#working-with-large-collections" title="Permalink to this headline">¶</a></h2>
<p>The default behavior of <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a> is to fully load
the collection of items in, as according to the loading strategy of the
relationship. Additionally, the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> by default only knows how to delete
objects which are actually present within the session. When a parent instance
is marked for deletion and flushed, the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> loads its full list of child
items in so that they may either be deleted as well, or have their foreign key
value set to null; this is to avoid constraint violations. For large
collections of child items, there are several strategies to bypass full
loading of child items both at load time as well as deletion time.</p>
<div class="section" id="dynamic-relationship-loaders">
<span id="dynamic-relationship"></span><h3>Dynamic Relationship Loaders<a class="headerlink" href="#dynamic-relationship-loaders" title="Permalink to this headline">¶</a></h3>
<p>A key feature to enable management of a large collection is the so-called &#8220;dynamic&#8221;
relationship.  This is an optional form of <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a> which
returns a <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> object in place of a collection
when accessed. <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.filter" title="sqlalchemy.orm.query.Query.filter"><tt class="xref py py-func docutils literal"><span class="pre">filter()</span></tt></a> criterion may be
applied as well as limits and offsets, either explicitly or via array slices:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user&#39;</span>

    <span class="n">posts</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="n">Post</span><span class="p">,</span> <span class="n">lazy</span><span class="o">=</span><span class="s">&quot;dynamic&quot;</span><span class="p">)</span>

<span class="n">jack</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>

<span class="c"># filter Jack&#39;s blog posts</span>
<span class="n">posts</span> <span class="o">=</span> <span class="n">jack</span><span class="o">.</span><span class="n">posts</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Post</span><span class="o">.</span><span class="n">headline</span><span class="o">==</span><span class="s">&#39;this is a post&#39;</span><span class="p">)</span>

<span class="c"># apply array slices</span>
<span class="n">posts</span> <span class="o">=</span> <span class="n">jack</span><span class="o">.</span><span class="n">posts</span><span class="p">[</span><span class="mi">5</span><span class="p">:</span><span class="mi">20</span><span class="p">]</span></pre></div>
</div>
<p>The dynamic relationship supports limited write operations, via the
<tt class="docutils literal"><span class="pre">append()</span></tt> and <tt class="docutils literal"><span class="pre">remove()</span></tt> methods:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">oldpost</span> <span class="o">=</span> <span class="n">jack</span><span class="o">.</span><span class="n">posts</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Post</span><span class="o">.</span><span class="n">headline</span><span class="o">==</span><span class="s">&#39;old post&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">one</span><span class="p">()</span>
<span class="n">jack</span><span class="o">.</span><span class="n">posts</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">oldpost</span><span class="p">)</span>

<span class="n">jack</span><span class="o">.</span><span class="n">posts</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Post</span><span class="p">(</span><span class="s">&#39;new post&#39;</span><span class="p">))</span></pre></div>
</div>
<p>Since the read side of the dynamic relationship always queries the
database, changes to the underlying collection will not be visible
until the data has been flushed.  However, as long as &#8220;autoflush&#8221; is
enabled on the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> in use, this will occur
automatically each time the collection is about to emit a
query.</p>
<p>To place a dynamic relationship on a backref, use the <a class="reference internal" href="relationships.html#sqlalchemy.orm.backref" title="sqlalchemy.orm.backref"><tt class="xref py py-func docutils literal"><span class="pre">backref()</span></tt></a>
function in conjunction with <tt class="docutils literal"><span class="pre">lazy='dynamic'</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Post</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__table__</span> <span class="o">=</span> <span class="n">posts_table</span>

    <span class="n">user</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="n">User</span><span class="p">,</span>
                <span class="n">backref</span><span class="o">=</span><span class="n">backref</span><span class="p">(</span><span class="s">&#39;posts&#39;</span><span class="p">,</span> <span class="n">lazy</span><span class="o">=</span><span class="s">&#39;dynamic&#39;</span><span class="p">)</span>
            <span class="p">)</span></pre></div>
</div>
<p>Note that eager/lazy loading options cannot be used in conjunction dynamic relationships at this time.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference internal" href="relationships.html#sqlalchemy.orm.dynamic_loader" title="sqlalchemy.orm.dynamic_loader"><tt class="xref py py-func docutils literal"><span class="pre">dynamic_loader()</span></tt></a> function is essentially the same
as <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a> with the <tt class="docutils literal"><span class="pre">lazy='dynamic'</span></tt> argument specified.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The &#8220;dynamic&#8221; loader applies to <strong>collections only</strong>.   It is not valid
to use &#8220;dynamic&#8221; loaders with many-to-one, one-to-one, or uselist=False
relationships.   Newer versions of SQLAlchemy emit warnings or exceptions
in these cases.</p>
</div>
</div>
<div class="section" id="setting-noload">
<h3>Setting Noload<a class="headerlink" href="#setting-noload" title="Permalink to this headline">¶</a></h3>
<p>A &#8220;noload&#8221; relationship never loads from the database, even when
accessed.   It is configured using <tt class="docutils literal"><span class="pre">lazy='noload'</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;some_table&#39;</span>

    <span class="n">children</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="n">MyOtherClass</span><span class="p">,</span> <span class="n">lazy</span><span class="o">=</span><span class="s">&#39;noload&#39;</span><span class="p">)</span></pre></div>
</div>
<p>Above, the <tt class="docutils literal"><span class="pre">children</span></tt> collection is fully writeable, and changes to it will
be persisted to the database as well as locally available for reading at the
time they are added. However when instances of <tt class="docutils literal"><span class="pre">MyClass</span></tt> are freshly loaded
from the database, the <tt class="docutils literal"><span class="pre">children</span></tt> collection stays empty.</p>
</div>
<div class="section" id="using-passive-deletes">
<span id="passive-deletes"></span><h3>Using Passive Deletes<a class="headerlink" href="#using-passive-deletes" title="Permalink to this headline">¶</a></h3>
<p>Use <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship.params.passive_deletes" title="sqlalchemy.orm.relationship"><tt class="xref py py-paramref docutils literal"><span class="pre">passive_deletes</span></tt></a> to disable child object loading on a DELETE
operation, in conjunction with &#8220;ON DELETE (CASCADE|SET NULL)&#8221; on your database
to automatically cascade deletes to child objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;mytable&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">children</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;MyOtherClass&quot;</span><span class="p">,</span>
                    <span class="n">cascade</span><span class="o">=</span><span class="s">&quot;all, delete-orphan&quot;</span><span class="p">,</span>
                    <span class="n">passive_deletes</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">MyOtherClass</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;myothertable&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">parent_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span>
                <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;mytable.id&#39;</span><span class="p">,</span> <span class="n">ondelete</span><span class="o">=</span><span class="s">&#39;CASCADE&#39;</span><span class="p">)</span>
                    <span class="p">)</span></pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>To use &#8220;ON DELETE CASCADE&#8221;, the underlying database engine must
support foreign keys.</p>
<ul class="last simple">
<li>When using MySQL, an appropriate storage engine must be
selected.  See <a class="reference internal" href="../dialects/mysql.html#mysql-storage-engines"><em>CREATE TABLE arguments including Storage Engines</em></a> for details.</li>
<li>When using SQLite, foreign key support must be enabled explicitly.
See <a class="reference internal" href="../dialects/sqlite.html#sqlite-foreign-keys"><em>Foreign Key Support</em></a> for details.</li>
</ul>
</div>
<p>When <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship.params.passive_deletes" title="sqlalchemy.orm.relationship"><tt class="xref py py-paramref docutils literal"><span class="pre">passive_deletes</span></tt></a> is applied, the <tt class="docutils literal"><span class="pre">children</span></tt> relationship will not be
loaded into memory when an instance of <tt class="docutils literal"><span class="pre">MyClass</span></tt> is marked for deletion. The
<tt class="docutils literal"><span class="pre">cascade=&quot;all,</span> <span class="pre">delete-orphan&quot;</span></tt> <em>will</em> take effect for instances of
<tt class="docutils literal"><span class="pre">MyOtherClass</span></tt> which are currently present in the session; however for
instances of <tt class="docutils literal"><span class="pre">MyOtherClass</span></tt> which are not loaded, SQLAlchemy assumes that
&#8220;ON DELETE CASCADE&#8221; rules will ensure that those rows are deleted by the
database.</p>
</div>
</div>
<div class="section" id="customizing-collection-access">
<span id="custom-collections"></span><h2>Customizing Collection Access<a class="headerlink" href="#customizing-collection-access" title="Permalink to this headline">¶</a></h2>
<p>Mapping a one-to-many or many-to-many relationship results in a collection of
values accessible through an attribute on the parent instance. By default,
this collection is a <tt class="docutils literal"><span class="pre">list</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Parent</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;parent&#39;</span>
    <span class="n">parent_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>

    <span class="n">children</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="n">Child</span><span class="p">)</span>

<span class="n">parent</span> <span class="o">=</span> <span class="n">Parent</span><span class="p">()</span>
<span class="n">parent</span><span class="o">.</span><span class="n">children</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Child</span><span class="p">())</span>
<span class="k">print</span> <span class="n">parent</span><span class="o">.</span><span class="n">children</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span></pre></div>
</div>
<p>Collections are not limited to lists. Sets, mutable sequences and almost any
other Python object that can act as a container can be used in place of the
default list, by specifying the <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship.params.collection_class" title="sqlalchemy.orm.relationship"><tt class="xref py py-paramref docutils literal"><span class="pre">collection_class</span></tt></a> option on
<a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Parent</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;parent&#39;</span>
    <span class="n">parent_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>

    <span class="c"># use a set</span>
    <span class="n">children</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="n">Child</span><span class="p">,</span> <span class="n">collection_class</span><span class="o">=</span><span class="nb">set</span><span class="p">)</span>

<span class="n">parent</span> <span class="o">=</span> <span class="n">Parent</span><span class="p">()</span>
<span class="n">child</span> <span class="o">=</span> <span class="n">Child</span><span class="p">()</span>
<span class="n">parent</span><span class="o">.</span><span class="n">children</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">child</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">parent</span><span class="o">.</span><span class="n">children</span></pre></div>
</div>
<div class="section" id="dictionary-collections">
<h3>Dictionary Collections<a class="headerlink" href="#dictionary-collections" title="Permalink to this headline">¶</a></h3>
<p>A little extra detail is needed when using a dictionary as a collection.
This because objects are always loaded from the database as lists, and a key-generation
strategy must be available to populate the dictionary correctly.  The
<a class="reference internal" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><tt class="xref py py-func docutils literal"><span class="pre">attribute_mapped_collection()</span></tt></a> function is by far the most common way
to achieve a simple dictionary collection.  It produces a dictionary class that will apply a particular attribute
of the mapped class as a key.   Below we map an <tt class="docutils literal"><span class="pre">Item</span></tt> class containing
a dictionary of <tt class="docutils literal"><span class="pre">Note</span></tt> items keyed to the <tt class="docutils literal"><span class="pre">Note.keyword</span></tt> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Column</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">String</span><span class="p">,</span> <span class="n">ForeignKey</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">relationship</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">attribute_mapped_collection</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.ext.declarative</span> <span class="kn">import</span> <span class="n">declarative_base</span>

<span class="n">Base</span> <span class="o">=</span> <span class="n">declarative_base</span><span class="p">()</span>

<span class="k">class</span> <span class="nc">Item</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;item&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">notes</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Note&quot;</span><span class="p">,</span>
                <span class="n">collection_class</span><span class="o">=</span><span class="n">attribute_mapped_collection</span><span class="p">(</span><span class="s">&#39;keyword&#39;</span><span class="p">),</span>
                <span class="n">cascade</span><span class="o">=</span><span class="s">&quot;all, delete-orphan&quot;</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Note</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;note&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">item_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;item.id&#39;</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">)</span>
    <span class="n">text</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">keyword</span><span class="p">,</span> <span class="n">text</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">keyword</span> <span class="o">=</span> <span class="n">keyword</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="n">text</span></pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">Item.notes</span></tt> is then a dictionary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">item</span> <span class="o">=</span> <span class="n">Item</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">item</span><span class="o">.</span><span class="n">notes</span><span class="p">[</span><span class="s">&#39;a&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">Note</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;atext&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">item</span><span class="o">.</span><span class="n">notes</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
<span class="go">{&#39;a&#39;: &lt;__main__.Note object at 0x2eaaf0&gt;}</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><tt class="xref py py-func docutils literal"><span class="pre">attribute_mapped_collection()</span></tt></a> will ensure that
the <tt class="docutils literal"><span class="pre">.keyword</span></tt> attribute of each <tt class="docutils literal"><span class="pre">Note</span></tt> complies with the key in the
dictionary.   Such as, when assigning to <tt class="docutils literal"><span class="pre">Item.notes</span></tt>, the dictionary
key we supply must match that of the actual <tt class="docutils literal"><span class="pre">Note</span></tt> object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">item</span> <span class="o">=</span> <span class="n">Item</span><span class="p">()</span>
<span class="n">item</span><span class="o">.</span><span class="n">notes</span> <span class="o">=</span> <span class="p">{</span>
            <span class="s">&#39;a&#39;</span><span class="p">:</span> <span class="n">Note</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;atext&#39;</span><span class="p">),</span>
            <span class="s">&#39;b&#39;</span><span class="p">:</span> <span class="n">Note</span><span class="p">(</span><span class="s">&#39;b&#39;</span><span class="p">,</span> <span class="s">&#39;btext&#39;</span><span class="p">)</span>
        <span class="p">}</span></pre></div>
</div>
<p>The attribute which <a class="reference internal" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><tt class="xref py py-func docutils literal"><span class="pre">attribute_mapped_collection()</span></tt></a> uses as a key
does not need to be mapped at all!  Using a regular Python <tt class="docutils literal"><span class="pre">&#64;property</span></tt> allows virtually
any detail or combination of details about the object to be used as the key, as
below when we establish it as a tuple of <tt class="docutils literal"><span class="pre">Note.keyword</span></tt> and the first ten letters
of the <tt class="docutils literal"><span class="pre">Note.text</span></tt> field:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Item</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;item&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">notes</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Note&quot;</span><span class="p">,</span>
                <span class="n">collection_class</span><span class="o">=</span><span class="n">attribute_mapped_collection</span><span class="p">(</span><span class="s">&#39;note_key&#39;</span><span class="p">),</span>
                <span class="n">backref</span><span class="o">=</span><span class="s">&quot;item&quot;</span><span class="p">,</span>
                <span class="n">cascade</span><span class="o">=</span><span class="s">&quot;all, delete-orphan&quot;</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Note</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;note&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">item_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;item.id&#39;</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">)</span>
    <span class="n">text</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">note_key</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">keyword</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">text</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">])</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">keyword</span><span class="p">,</span> <span class="n">text</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">keyword</span> <span class="o">=</span> <span class="n">keyword</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="n">text</span></pre></div>
</div>
<p>Above we added a <tt class="docutils literal"><span class="pre">Note.item</span></tt> backref.  Assigning to this reverse relationship, the <tt class="docutils literal"><span class="pre">Note</span></tt>
is added to the <tt class="docutils literal"><span class="pre">Item.notes</span></tt> dictionary and the key is generated for us automatically:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">item</span> <span class="o">=</span> <span class="n">Item</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">n1</span> <span class="o">=</span> <span class="n">Note</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="s">&quot;atext&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">n1</span><span class="o">.</span><span class="n">item</span> <span class="o">=</span> <span class="n">item</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">item</span><span class="o">.</span><span class="n">notes</span>
<span class="go">{(&#39;a&#39;, &#39;atext&#39;): &lt;__main__.Note object at 0x2eaaf0&gt;}</span></pre></div>
</div>
<p>Other built-in dictionary types include <a class="reference internal" href="#sqlalchemy.orm.collections.column_mapped_collection" title="sqlalchemy.orm.collections.column_mapped_collection"><tt class="xref py py-func docutils literal"><span class="pre">column_mapped_collection()</span></tt></a>,
which is almost like <a class="reference internal" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><tt class="xref py py-func docutils literal"><span class="pre">attribute_mapped_collection()</span></tt></a> except given the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
object directly:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">column_mapped_collection</span>

<span class="k">class</span> <span class="nc">Item</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;item&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">notes</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Note&quot;</span><span class="p">,</span>
                <span class="n">collection_class</span><span class="o">=</span><span class="n">column_mapped_collection</span><span class="p">(</span><span class="n">Note</span><span class="o">.</span><span class="n">__table__</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">keyword</span><span class="p">),</span>
                <span class="n">cascade</span><span class="o">=</span><span class="s">&quot;all, delete-orphan&quot;</span><span class="p">)</span></pre></div>
</div>
<p>as well as <a class="reference internal" href="#sqlalchemy.orm.collections.mapped_collection" title="sqlalchemy.orm.collections.mapped_collection"><tt class="xref py py-func docutils literal"><span class="pre">mapped_collection()</span></tt></a> which is passed any callable function.
Note that it&#8217;s usually easier to use <a class="reference internal" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><tt class="xref py py-func docutils literal"><span class="pre">attribute_mapped_collection()</span></tt></a> along
with a <tt class="docutils literal"><span class="pre">&#64;property</span></tt> as mentioned earlier:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">mapped_collection</span>

<span class="k">class</span> <span class="nc">Item</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;item&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">notes</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Note&quot;</span><span class="p">,</span>
                <span class="n">collection_class</span><span class="o">=</span><span class="n">mapped_collection</span><span class="p">(</span><span class="k">lambda</span> <span class="n">note</span><span class="p">:</span> <span class="n">note</span><span class="o">.</span><span class="n">text</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">]),</span>
                <span class="n">cascade</span><span class="o">=</span><span class="s">&quot;all, delete-orphan&quot;</span><span class="p">)</span></pre></div>
</div>
<p>Dictionary mappings are often combined with the &#8220;Association Proxy&#8221; extension to produce
streamlined dictionary views.  See <a class="reference internal" href="extensions/associationproxy.html#proxying-dictionaries"><em>Proxying to Dictionary Based Collections</em></a> and <a class="reference internal" href="extensions/associationproxy.html#composite-association-proxy"><em>Composite Association Proxies</em></a>
for examples.</p>
<dl class="function">
<dt id="sqlalchemy.orm.collections.attribute_mapped_collection">
<tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">attribute_mapped_collection</tt><big>(</big><em>attr_name</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary-based collection type with attribute-based keying.</p>
<p>Returns a <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> factory with a keying based on the
&#8216;attr_name&#8217; attribute of entities in the collection, where <tt class="docutils literal"><span class="pre">attr_name</span></tt>
is the string name of the attribute.</p>
<p>The key value must be immutable for the lifetime of the object.  You
can not, for example, map on foreign key values if those key values will
change during the session, i.e. from None to a database-assigned integer
after a session flush.</p>
</dd></dl>

<dl class="function">
<dt id="sqlalchemy.orm.collections.column_mapped_collection">
<tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">column_mapped_collection</tt><big>(</big><em>mapping_spec</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.column_mapped_collection" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary-based collection type with column-based keying.</p>
<p>Returns a <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> factory with a keying function
generated from mapping_spec, which may be a Column or a sequence
of Columns.</p>
<p>The key value must be immutable for the lifetime of the object.  You
can not, for example, map on foreign key values if those key values will
change during the session, i.e. from None to a database-assigned integer
after a session flush.</p>
</dd></dl>

<dl class="function">
<dt id="sqlalchemy.orm.collections.mapped_collection">
<tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">mapped_collection</tt><big>(</big><em>keyfunc</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.mapped_collection" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary-based collection type with arbitrary keying.</p>
<p>Returns a <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> factory with a keying function
generated from keyfunc, a callable that takes an entity and returns a
key value.</p>
<p>The key value must be immutable for the lifetime of the object.  You
can not, for example, map on foreign key values if those key values will
change during the session, i.e. from None to a database-assigned integer
after a session flush.</p>
</dd></dl>

</div>
</div>
<div class="section" id="custom-collection-implementations">
<h2>Custom Collection Implementations<a class="headerlink" href="#custom-collection-implementations" title="Permalink to this headline">¶</a></h2>
<p>You can use your own types for collections as well.  In simple cases,
inherting from <tt class="docutils literal"><span class="pre">list</span></tt> or <tt class="docutils literal"><span class="pre">set</span></tt>, adding custom behavior, is all that&#8217;s needed.
In other cases, special decorators are needed to tell SQLAlchemy more detail
about how the collection operates.</p>
<div class="topic">
<p class="topic-title first">Do I need a custom collection implementation?</p>
<p>In most cases not at all!   The most common use cases for a &#8220;custom&#8221; collection
is one that validates or marshals incoming values into a new form, such as
a string that becomes a class instance, or one which goes a
step beyond and represents the data internally in some fashion, presenting
a &#8220;view&#8221; of that data on the outside of a different form.</p>
<p>For the first use case, the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.validates" title="sqlalchemy.orm.validates"><tt class="xref py py-func docutils literal"><span class="pre">orm.validates()</span></tt></a> decorator is by far
the simplest way to intercept incoming values in all cases for the purposes
of validation and simple marshaling.  See <a class="reference internal" href="mapper_config.html#simple-validators"><em>Simple Validators</em></a>
for an example of this.</p>
<p>For the second use case, the <a class="reference internal" href="extensions/associationproxy.html"><em>Association Proxy</em></a> extension is a
well-tested, widely used system that provides a read/write &#8220;view&#8221; of a
collection in terms of some attribute present on the target object. As the
target attribute can be a <tt class="docutils literal"><span class="pre">&#64;property</span></tt> that returns virtually anything, a
wide array of &#8220;alternative&#8221; views of a collection can be constructed with
just a few functions. This approach leaves the underlying mapped collection
unaffected and avoids the need to carefully tailor collection behavior on a
method-by-method basis.</p>
<p>Customized collections are useful when the collection needs to
have special behaviors upon access or mutation operations that can&#8217;t
otherwise be modeled externally to the collection.   They can of course
be combined with the above two approaches.</p>
</div>
<p>Collections in SQLAlchemy are transparently <em>instrumented</em>. Instrumentation
means that normal operations on the collection are tracked and result in
changes being written to the database at flush time. Additionally, collection
operations can fire <em>events</em> which indicate some secondary operation must take
place. Examples of a secondary operation include saving the child item in the
parent&#8217;s <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> (i.e. the <tt class="docutils literal"><span class="pre">save-update</span></tt>
cascade), as well as synchronizing the state of a bi-directional relationship
(i.e. a <a class="reference internal" href="relationships.html#sqlalchemy.orm.backref" title="sqlalchemy.orm.backref"><tt class="xref py py-func docutils literal"><span class="pre">backref()</span></tt></a>).</p>
<p>The collections package understands the basic interface of lists, sets and
dicts and will automatically apply instrumentation to those built-in types and
their subclasses. Object-derived types that implement a basic collection
interface are detected and instrumented via duck-typing:</p>
<div class="highlight-python+sql"><div class="highlight"><pre><span class="k">class</span> <span class="nc">ListLike</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">def</span> <span class="nf">append</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">remove</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">extend</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">items</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">items</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="nb">iter</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&#39;foo&#39;</span></pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">append</span></tt>, <tt class="docutils literal"><span class="pre">remove</span></tt>, and <tt class="docutils literal"><span class="pre">extend</span></tt> are known list-like methods, and will
be instrumented automatically. <tt class="docutils literal"><span class="pre">__iter__</span></tt> is not a mutator method and won&#8217;t
be instrumented, and <tt class="docutils literal"><span class="pre">foo</span></tt> won&#8217;t be either.</p>
<p>Duck-typing (i.e. guesswork) isn&#8217;t rock-solid, of course, so you can be
explicit about the interface you are implementing by providing an
<tt class="docutils literal"><span class="pre">__emulates__</span></tt> class attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">SetLike</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="n">__emulates__</span> <span class="o">=</span> <span class="nb">set</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>
    <span class="k">def</span> <span class="nf">append</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">remove</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="nb">iter</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="p">)</span></pre></div>
</div>
<p>This class looks list-like because of <tt class="docutils literal"><span class="pre">append</span></tt>, but <tt class="docutils literal"><span class="pre">__emulates__</span></tt> forces
it to set-like. <tt class="docutils literal"><span class="pre">remove</span></tt> is known to be part of the set interface and will
be instrumented.</p>
<p>But this class won&#8217;t work quite yet: a little glue is needed to adapt it for
use by SQLAlchemy. The ORM needs to know which methods to use to append,
remove and iterate over members of the collection. When using a type like
<tt class="docutils literal"><span class="pre">list</span></tt> or <tt class="docutils literal"><span class="pre">set</span></tt>, the appropriate methods are well-known and used
automatically when present. This set-like class does not provide the expected
<tt class="docutils literal"><span class="pre">add</span></tt> method, so we must supply an explicit mapping for the ORM via a
decorator.</p>
<div class="section" id="annotating-custom-collections-via-decorators">
<h3>Annotating Custom Collections via Decorators<a class="headerlink" href="#annotating-custom-collections-via-decorators" title="Permalink to this headline">¶</a></h3>
<p>Decorators can be used to tag the individual methods the ORM needs to manage
collections. Use them when your class doesn&#8217;t quite meet the regular interface
for its container type, or when you otherwise would like to use a different method to
get the job done.</p>
<div class="highlight-python+sql"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">collection</span>

<span class="k">class</span> <span class="nc">SetLike</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="n">__emulates__</span> <span class="o">=</span> <span class="nb">set</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>

    <span class="nd">@collection.appender</span>
    <span class="k">def</span> <span class="nf">append</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">remove</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="nb">iter</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="p">)</span></pre></div>
</div>
<p>And that&#8217;s all that&#8217;s needed to complete the example. SQLAlchemy will add
instances via the <tt class="docutils literal"><span class="pre">append</span></tt> method. <tt class="docutils literal"><span class="pre">remove</span></tt> and <tt class="docutils literal"><span class="pre">__iter__</span></tt> are the
default methods for sets and will be used for removing and iteration. Default
methods can be changed as well:</p>
<div class="highlight-python+sql"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">collection</span>

<span class="k">class</span> <span class="nc">MyList</span><span class="p">(</span><span class="nb">list</span><span class="p">):</span>
    <span class="nd">@collection.remover</span>
    <span class="k">def</span> <span class="nf">zark</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span>
        <span class="c"># do something special...</span>

    <span class="nd">@collection.iterator</span>
    <span class="k">def</span> <span class="nf">hey_use_this_instead_for_iteration</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c"># ...</span></pre></div>
</div>
<p>There is no requirement to be list-, or set-like at all. Collection classes
can be any shape, so long as they have the append, remove and iterate
interface marked for SQLAlchemy&#8217;s use. Append and remove methods will be
called with a mapped entity as the single argument, and iterator methods are
called with no arguments and must return an iterator.</p>
<dl class="class">
<dt id="sqlalchemy.orm.collections.collection">
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">collection</tt><a class="headerlink" href="#sqlalchemy.orm.collections.collection" title="Permalink to this definition">¶</a></dt>
<dd><p>Decorators for entity collection classes.</p>
<p>The decorators fall into two groups: annotations and interception recipes.</p>
<p>The annotating decorators (appender, remover, iterator, linker, converter,
internally_instrumented) indicate the method&#8217;s purpose and take no
arguments.  They are not written with parens:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.appender</span>
<span class="k">def</span> <span class="nf">append</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">append</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
<p>The recipe decorators all require parens, even those that take no
arguments:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.adds</span><span class="p">(</span><span class="s">&#39;entity&#39;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">insert</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">position</span><span class="p">,</span> <span class="n">entity</span><span class="p">):</span> <span class="o">...</span>

<span class="nd">@collection.removes_return</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">popitem</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.adds">
<em class="property">static </em><tt class="descname">adds</tt><big>(</big><em>arg</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.adds" title="Permalink to this definition">¶</a></dt>
<dd><p>Mark the method as adding an entity to the collection.</p>
<p>Adds &#8220;add to collection&#8221; handling to the method.  The decorator
argument indicates which method argument holds the SQLAlchemy-relevant
value.  Arguments can be specified positionally (i.e. integer) or by
name:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.adds</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">push</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span> <span class="o">...</span>

<span class="nd">@collection.adds</span><span class="p">(</span><span class="s">&#39;entity&#39;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">do_stuff</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">thing</span><span class="p">,</span> <span class="n">entity</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.appender">
<em class="property">static </em><tt class="descname">appender</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.appender" title="Permalink to this definition">¶</a></dt>
<dd><p>Tag the method as the collection appender.</p>
<p>The appender method is called with one positional argument: the value
to append. The method will be automatically decorated with &#8216;adds(1)&#8217;
if not already decorated:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.appender</span>
<span class="k">def</span> <span class="nf">add</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">append</span><span class="p">):</span> <span class="o">...</span>

<span class="c"># or, equivalently</span>
<span class="nd">@collection.appender</span>
<span class="nd">@collection.adds</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">add</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">append</span><span class="p">):</span> <span class="o">...</span>

<span class="c"># for mapping type, an &#39;append&#39; may kick out a previous value</span>
<span class="c"># that occupies that slot.  consider d[&#39;a&#39;] = &#39;foo&#39;- any previous</span>
<span class="c"># value in d[&#39;a&#39;] is discarded.</span>
<span class="nd">@collection.appender</span>
<span class="nd">@collection.replaces</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">add</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">entity</span><span class="p">):</span>
    <span class="n">key</span> <span class="o">=</span> <span class="n">some_key_func</span><span class="p">(</span><span class="n">entity</span><span class="p">)</span>
    <span class="n">previous</span> <span class="o">=</span> <span class="bp">None</span>
    <span class="k">if</span> <span class="n">key</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
        <span class="n">previous</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
    <span class="bp">self</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">entity</span>
    <span class="k">return</span> <span class="n">previous</span></pre></div>
</div>
<p>If the value to append is not allowed in the collection, you may
raise an exception.  Something to remember is that the appender
will be called for each object mapped by a database query.  If the
database contains rows that violate your collection semantics, you
will need to get creative to fix the problem, as access via the
collection will not work.</p>
<p>If the appender method is internally instrumented, you must also
receive the keyword argument &#8216;_sa_initiator&#8217; and ensure its
promulgation to collection events.</p>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.converter">
<em class="property">static </em><tt class="descname">converter</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.converter" title="Permalink to this definition">¶</a></dt>
<dd><p>Tag the method as the collection converter.</p>
<p>This optional method will be called when a collection is being
replaced entirely, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">myobj</span><span class="o">.</span><span class="n">acollection</span> <span class="o">=</span> <span class="p">[</span><span class="n">newvalue1</span><span class="p">,</span> <span class="n">newvalue2</span><span class="p">]</span></pre></div>
</div>
<p>The converter method will receive the object being assigned and should
return an iterable of values suitable for use by the <tt class="docutils literal"><span class="pre">appender</span></tt>
method.  A converter must not assign values or mutate the collection,
its sole job is to adapt the value the user provides into an iterable
of values for the ORM&#8217;s use.</p>
<p>The default converter implementation will use duck-typing to do the
conversion.  A dict-like collection will be convert into an iterable
of dictionary values, and other types will simply be iterated:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.converter</span>
<span class="k">def</span> <span class="nf">convert</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
<p>If the duck-typing of the object does not match the type of this
collection, a TypeError is raised.</p>
<p>Supply an implementation of this method if you want to expand the
range of possible types that can be assigned in bulk or perform
validation on the values about to be assigned.</p>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.internally_instrumented">
<em class="property">static </em><tt class="descname">internally_instrumented</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.internally_instrumented" title="Permalink to this definition">¶</a></dt>
<dd><p>Tag the method as instrumented.</p>
<p>This tag will prevent any decoration from being applied to the
method. Use this if you are orchestrating your own calls to
<a class="reference internal" href="#sqlalchemy.orm.collections.collection_adapter" title="sqlalchemy.orm.collections.collection_adapter"><tt class="xref py py-func docutils literal"><span class="pre">collection_adapter()</span></tt></a> in one of the basic SQLAlchemy
interface methods, or to prevent an automatic ABC method
decoration from wrapping your implementation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># normally an &#39;extend&#39; method on a list-like class would be</span>
<span class="c"># automatically intercepted and re-implemented in terms of</span>
<span class="c"># SQLAlchemy events and append().  your implementation will</span>
<span class="c"># never be called, unless:</span>
<span class="nd">@collection.internally_instrumented</span>
<span class="k">def</span> <span class="nf">extend</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">items</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.iterator">
<em class="property">static </em><tt class="descname">iterator</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.iterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Tag the method as the collection remover.</p>
<p>The iterator method is called with no arguments.  It is expected to
return an iterator over all collection members:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.iterator</span>
<span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.link">
<em class="property">static </em><tt class="descname">link</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.link" title="Permalink to this definition">¶</a></dt>
<dd><p>deprecated; synonym for <a class="reference internal" href="#sqlalchemy.orm.collections.collection.linker" title="sqlalchemy.orm.collections.collection.linker"><tt class="xref py py-meth docutils literal"><span class="pre">collection.linker()</span></tt></a>.</p>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.linker">
<em class="property">static </em><tt class="descname">linker</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.linker" title="Permalink to this definition">¶</a></dt>
<dd><p>Tag the method as a &#8220;linked to attribute&#8221; event handler.</p>
<p>This optional event handler will be called when the collection class
is linked to or unlinked from the InstrumentedAttribute.  It is
invoked immediately after the &#8216;_sa_adapter&#8217; property is set on
the instance.  A single argument is passed: the collection adapter
that has been linked, or None if unlinking.</p>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.remover">
<em class="property">static </em><tt class="descname">remover</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.remover" title="Permalink to this definition">¶</a></dt>
<dd><p>Tag the method as the collection remover.</p>
<p>The remover method is called with one positional argument: the value
to remove. The method will be automatically decorated with
<a class="reference internal" href="#sqlalchemy.orm.collections.collection.removes_return" title="sqlalchemy.orm.collections.collection.removes_return"><tt class="xref py py-meth docutils literal"><span class="pre">removes_return()</span></tt></a> if not already decorated:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.remover</span>
<span class="k">def</span> <span class="nf">zap</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">entity</span><span class="p">):</span> <span class="o">...</span>

<span class="c"># or, equivalently</span>
<span class="nd">@collection.remover</span>
<span class="nd">@collection.removes_return</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">zap</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="p">):</span> <span class="o">...</span></pre></div>
</div>
<p>If the value to remove is not present in the collection, you may
raise an exception or return None to ignore the error.</p>
<p>If the remove method is internally instrumented, you must also
receive the keyword argument &#8216;_sa_initiator&#8217; and ensure its
promulgation to collection events.</p>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.removes">
<em class="property">static </em><tt class="descname">removes</tt><big>(</big><em>arg</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.removes" title="Permalink to this definition">¶</a></dt>
<dd><p>Mark the method as removing an entity in the collection.</p>
<p>Adds &#8220;remove from collection&#8221; handling to the method.  The decorator
argument indicates which method argument holds the SQLAlchemy-relevant
value to be removed. Arguments can be specified positionally (i.e.
integer) or by name:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.removes</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">zap</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
<p>For methods where the value to remove is not known at call-time, use
collection.removes_return.</p>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.removes_return">
<em class="property">static </em><tt class="descname">removes_return</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.removes_return" title="Permalink to this definition">¶</a></dt>
<dd><p>Mark the method as removing an entity in the collection.</p>
<p>Adds &#8220;remove from collection&#8221; handling to the method.  The return
value of the method, if any, is considered the value to remove.  The
method arguments are not inspected:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.removes_return</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">pop</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
<p>For methods where the value to remove is known at call-time, use
collection.remove.</p>
</dd></dl>

<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.replaces">
<em class="property">static </em><tt class="descname">replaces</tt><big>(</big><em>arg</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.replaces" title="Permalink to this definition">¶</a></dt>
<dd><p>Mark the method as replacing an entity in the collection.</p>
<p>Adds &#8220;add to collection&#8221; and &#8220;remove from collection&#8221; handling to
the method.  The decorator argument indicates which method argument
holds the SQLAlchemy-relevant value to be added, and return value, if
any will be considered the value to remove.</p>
<p>Arguments can be specified positionally (i.e. integer) or by name:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.replaces</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">__setitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">index</span><span class="p">,</span> <span class="n">item</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="custom-dictionary-based-collections">
<span id="id1"></span><h3>Custom Dictionary-Based Collections<a class="headerlink" href="#custom-dictionary-based-collections" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> class can be used as
a base class for your custom types or as a mix-in to quickly add <tt class="docutils literal"><span class="pre">dict</span></tt>
collection support to other classes. It uses a keying function to delegate to
<tt class="docutils literal"><span class="pre">__setitem__</span></tt> and <tt class="docutils literal"><span class="pre">__delitem__</span></tt>:</p>
<div class="highlight-python+sql"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.util</span> <span class="kn">import</span> <span class="n">OrderedDict</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">MappedCollection</span>

<span class="k">class</span> <span class="nc">NodeMap</span><span class="p">(</span><span class="n">OrderedDict</span><span class="p">,</span> <span class="n">MappedCollection</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Holds &#39;Node&#39; objects, keyed by the &#39;name&#39; attribute with insert order maintained.&quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
        <span class="n">MappedCollection</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">keyfunc</span><span class="o">=</span><span class="k">lambda</span> <span class="n">node</span><span class="p">:</span> <span class="n">node</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
        <span class="n">OrderedDict</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span></pre></div>
</div>
<p>When subclassing <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a>, user-defined versions
of <tt class="docutils literal"><span class="pre">__setitem__()</span></tt> or <tt class="docutils literal"><span class="pre">__delitem__()</span></tt> should be decorated
with <a class="reference internal" href="#sqlalchemy.orm.collections.collection.internally_instrumented" title="sqlalchemy.orm.collections.collection.internally_instrumented"><tt class="xref py py-meth docutils literal"><span class="pre">collection.internally_instrumented()</span></tt></a>, <strong>if</strong> they call down
to those same methods on <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a>.  This because the methods
on <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> are already instrumented - calling them
from within an already instrumented call can cause events to be fired off
repeatedly, or inappropriately, leading to internal state corruption in
rare cases:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">MappedCollection</span><span class="p">,</span>\
                                    <span class="n">collection</span>

<span class="k">class</span> <span class="nc">MyMappedCollection</span><span class="p">(</span><span class="n">MappedCollection</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Use @internally_instrumented when your methods</span>
<span class="sd">    call down to already-instrumented methods.</span>

<span class="sd">    &quot;&quot;&quot;</span>

    <span class="nd">@collection.internally_instrumented</span>
    <span class="k">def</span> <span class="nf">__setitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">_sa_initiator</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
        <span class="c"># do something with key, value</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">MyMappedCollection</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__setitem__</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">_sa_initiator</span><span class="p">)</span>

    <span class="nd">@collection.internally_instrumented</span>
    <span class="k">def</span> <span class="nf">__delitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">_sa_initiator</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
        <span class="c"># do something with key</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">MyMappedCollection</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__delitem__</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">_sa_initiator</span><span class="p">)</span></pre></div>
</div>
<p>The ORM understands the <tt class="docutils literal"><span class="pre">dict</span></tt> interface just like lists and sets, and will
automatically instrument all dict-like methods if you choose to subclass
<tt class="docutils literal"><span class="pre">dict</span></tt> or provide dict-like collection behavior in a duck-typed class. You
must decorate appender and remover methods, however- there are no compatible
methods in the basic dictionary interface for SQLAlchemy to use by default.
Iteration will go through <tt class="docutils literal"><span class="pre">itervalues()</span></tt> unless otherwise decorated.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Due to a bug in MappedCollection prior to version 0.7.6, this
workaround usually needs to be called before a custom subclass
of <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> which uses <a class="reference internal" href="#sqlalchemy.orm.collections.collection.internally_instrumented" title="sqlalchemy.orm.collections.collection.internally_instrumented"><tt class="xref py py-meth docutils literal"><span class="pre">collection.internally_instrumented()</span></tt></a>
can be used:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">_instrument_class</span><span class="p">,</span> <span class="n">MappedCollection</span>
<span class="n">_instrument_class</span><span class="p">(</span><span class="n">MappedCollection</span><span class="p">)</span></pre></div>
</div>
<p class="last">This will ensure that the <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> has been properly
initialized with custom <tt class="docutils literal"><span class="pre">__setitem__()</span></tt> and <tt class="docutils literal"><span class="pre">__delitem__()</span></tt>
methods before used in a custom subclass.</p>
</div>
<dl class="class">
<dt id="sqlalchemy.orm.collections.MappedCollection">
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">MappedCollection</tt><big>(</big><em>keyfunc</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">__builtin__.dict</span></tt></p>
<p>A basic dictionary-based collection class.</p>
<p>Extends dict with the minimal bag semantics that collection
classes require. <tt class="docutils literal"><span class="pre">set</span></tt> and <tt class="docutils literal"><span class="pre">remove</span></tt> are implemented in terms
of a keying function: any callable that takes an object and
returns an object for use as a dictionary key.</p>
<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.__init__">
<tt class="descname">__init__</tt><big>(</big><em>keyfunc</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new collection with keying provided by keyfunc.</p>
<p>keyfunc may be any callable any callable that takes an object and
returns an object for use as a dictionary key.</p>
<p>The keyfunc will be called every time the ORM needs to add a member by
value-only (such as when loading instances from the database) or
remove a member.  The usual cautions about dictionary keying apply-
<tt class="docutils literal"><span class="pre">keyfunc(object)</span></tt> should return the same output for the life of the
collection.  Keying based on mutable properties can result in
unreachable instances &#8220;lost&#8221; in the collection.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.clear">
<tt class="descname">clear</tt><big>(</big><big>)</big> &rarr; None.  Remove all items from D.<a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.clear" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.pop">
<tt class="descname">pop</tt><big>(</big><em>k</em><span class="optional">[</span>, <em>d</em><span class="optional">]</span><big>)</big> &rarr; v, remove specified key and return the corresponding value.<a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.pop" title="Permalink to this definition">¶</a></dt>
<dd><p>If key is not found, d is returned if given, otherwise KeyError is raised</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.popitem">
<tt class="descname">popitem</tt><big>(</big><big>)</big> &rarr; (k, v), remove and return some (key, value) pair as a<a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.popitem" title="Permalink to this definition">¶</a></dt>
<dd><p>2-tuple; but raise KeyError if D is empty.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.remove">
<tt class="descname">remove</tt><big>(</big><em>value</em>, <em>_sa_initiator=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.remove" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove an item by value, consulting the keyfunc for the key.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.set">
<tt class="descname">set</tt><big>(</big><em>value</em>, <em>_sa_initiator=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.set" title="Permalink to this definition">¶</a></dt>
<dd><p>Add an item by value, consulting the keyfunc for the key.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.setdefault">
<tt class="descname">setdefault</tt><big>(</big><em>k</em><span class="optional">[</span>, <em>d</em><span class="optional">]</span><big>)</big> &rarr; D.get(k,d), also set D[k]=d if k not in D<a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.setdefault" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.update">
<tt class="descname">update</tt><big>(</big><span class="optional">[</span><em>E</em><span class="optional">]</span>, <em>**F</em><big>)</big> &rarr; None.  Update D from dict/iterable E and F.<a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.update" title="Permalink to this definition">¶</a></dt>
<dd><p>If E present and has a .keys() method, does:     for k in E: D[k] = E[k]
If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
In either case, this is followed by: for k in F: D[k] = F[k]</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="instrumentation-and-custom-types">
<h3>Instrumentation and Custom Types<a class="headerlink" href="#instrumentation-and-custom-types" title="Permalink to this headline">¶</a></h3>
<p>Many custom types and existing library classes can be used as a entity
collection type as-is without further ado. However, it is important to note
that the instrumentation process will modify the type, adding decorators
around methods automatically.</p>
<p>The decorations are lightweight and no-op outside of relationships, but they
do add unneeded overhead when triggered elsewhere. When using a library class
as a collection, it can be good practice to use the &#8220;trivial subclass&#8221; trick
to restrict the decorations to just your usage in relationships. For example:</p>
<div class="highlight-python+sql"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyAwesomeList</span><span class="p">(</span><span class="n">some</span><span class="o">.</span><span class="n">great</span><span class="o">.</span><span class="n">library</span><span class="o">.</span><span class="n">AwesomeList</span><span class="p">):</span>
    <span class="k">pass</span>

<span class="c"># ... relationship(..., collection_class=MyAwesomeList)</span></pre></div>
</div>
<p>The ORM uses this approach for built-ins, quietly substituting a trivial
subclass when a <tt class="docutils literal"><span class="pre">list</span></tt>, <tt class="docutils literal"><span class="pre">set</span></tt> or <tt class="docutils literal"><span class="pre">dict</span></tt> is used directly.</p>
</div>
</div>
<div class="section" id="collection-internals">
<h2>Collection Internals<a class="headerlink" href="#collection-internals" title="Permalink to this headline">¶</a></h2>
<p>Various internal methods.</p>
<dl class="function">
<dt id="sqlalchemy.orm.collections.bulk_replace">
<tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">bulk_replace</tt><big>(</big><em>values</em>, <em>existing_adapter</em>, <em>new_adapter</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.bulk_replace" title="Permalink to this definition">¶</a></dt>
<dd><p>Load a new collection, firing events based on prior like membership.</p>
<p>Appends instances in <tt class="docutils literal"><span class="pre">values</span></tt> onto the <tt class="docutils literal"><span class="pre">new_adapter</span></tt>. Events will be
fired for any instance not present in the <tt class="docutils literal"><span class="pre">existing_adapter</span></tt>.  Any
instances in <tt class="docutils literal"><span class="pre">existing_adapter</span></tt> not present in <tt class="docutils literal"><span class="pre">values</span></tt> will have
remove events fired upon them.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.orm.collections.bulk_replace.params.values"></span><strong>values</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.collections.bulk_replace.params.values">¶</a> &#8211; An iterable of collection member instances</li>
<li><span class="target" id="sqlalchemy.orm.collections.bulk_replace.params.existing_adapter"></span><strong>existing_adapter</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.collections.bulk_replace.params.existing_adapter">¶</a> &#8211; A <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><tt class="xref py py-class docutils literal"><span class="pre">CollectionAdapter</span></tt></a> of
instances to be replaced</li>
<li><span class="target" id="sqlalchemy.orm.collections.bulk_replace.params.new_adapter"></span><strong>new_adapter</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.collections.bulk_replace.params.new_adapter">¶</a> &#8211; An empty <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><tt class="xref py py-class docutils literal"><span class="pre">CollectionAdapter</span></tt></a>
to load with <tt class="docutils literal"><span class="pre">values</span></tt></li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="class">
<dt>
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">collection</tt></dt>
<dd><p>Decorators for entity collection classes.</p>
<p>The decorators fall into two groups: annotations and interception recipes.</p>
<p>The annotating decorators (appender, remover, iterator, linker, converter,
internally_instrumented) indicate the method&#8217;s purpose and take no
arguments.  They are not written with parens:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.appender</span>
<span class="k">def</span> <span class="nf">append</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">append</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
<p>The recipe decorators all require parens, even those that take no
arguments:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.adds</span><span class="p">(</span><span class="s">&#39;entity&#39;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">insert</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">position</span><span class="p">,</span> <span class="n">entity</span><span class="p">):</span> <span class="o">...</span>

<span class="nd">@collection.removes_return</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">popitem</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span></pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="sqlalchemy.orm.collections.collection_adapter">
<tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">collection_adapter</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection_adapter" title="Permalink to this definition">¶</a></dt>
<dd><p>Fetch the <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><tt class="xref py py-class docutils literal"><span class="pre">CollectionAdapter</span></tt></a> for a collection.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.orm.collections.CollectionAdapter">
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">CollectionAdapter</tt><big>(</big><em>attr</em>, <em>owner_state</em>, <em>data</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.CollectionAdapter" title="Permalink to this definition">¶</a></dt>
<dd><p>Bridges between the ORM and arbitrary Python collections.</p>
<p>Proxies base-level collection operations (append, remove, iterate)
to the underlying Python collection, and emits add/remove events for
entities entering or leaving the collection.</p>
<p>The ORM uses <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><tt class="xref py py-class docutils literal"><span class="pre">CollectionAdapter</span></tt></a> exclusively for interaction with
entity collections.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.orm.collections.InstrumentedDict">
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">InstrumentedDict</tt><a class="headerlink" href="#sqlalchemy.orm.collections.InstrumentedDict" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">__builtin__.dict</span></tt></p>
<p>An instrumented version of the built-in dict.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.orm.collections.InstrumentedList">
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">InstrumentedList</tt><a class="headerlink" href="#sqlalchemy.orm.collections.InstrumentedList" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">__builtin__.list</span></tt></p>
<p>An instrumented version of the built-in list.</p>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.orm.collections.InstrumentedSet">
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">InstrumentedSet</tt><a class="headerlink" href="#sqlalchemy.orm.collections.InstrumentedSet" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">__builtin__.set</span></tt></p>
<p>An instrumented version of the built-in set.</p>
</dd></dl>

<dl class="function">
<dt id="sqlalchemy.orm.collections.prepare_instrumentation">
<tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">prepare_instrumentation</tt><big>(</big><em>factory</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.prepare_instrumentation" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepare a callable for future use as a collection class factory.</p>
<p>Given a collection class factory (either a type or no-arg callable),
return another factory that will produce compatible instances when
called.</p>
<p>This function is responsible for converting collection_class=list
into the run-time behavior of collection_class=InstrumentedList.</p>
</dd></dl>

</div>
</div>

    </div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
        Previous:
        <a href="relationships.html" title="previous chapter">Relationship Configuration</a>
        Next:
        <a href="inheritance.html" title="next chapter">Mapping Class Inheritance Hierarchies</a>

    <div id="docs-copyright">
        &copy; <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
    </div>
</div>

</div>

        
    </body>
</html>