<!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
—
SQLAlchemy 1.2 Documentation
</title>
<!-- begin iterate through site-imported + 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/changelog.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
<!-- end iterate through site-imported + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<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 1.2 Documentation" href="../index.html" />
<link rel="up" title="Relationship Configuration" href="relationships.html" />
<link rel="next" title="Special Relationship Persistence Patterns" href="relationship_persistence.html" />
<link rel="prev" title="Configuring how Relationship Joins" href="join_conditions.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">1.2.19</span>
| Release Date: April 15, 2019
</div>
<h1>SQLAlchemy 1.2 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 1.2 Documentation</a></h3>
<p id="sidebar-topnav">
<a href="../contents.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<label>
Search terms:
<input type="text" placeholder="search..." name="q" size="12" />
</label>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<div id="sidebar-banner">
</div>
<div id="docs-sidebar-inner">
<h3>
<a href="index.html" title="SQLAlchemy ORM">SQLAlchemy ORM</a>
</h3>
<ul>
<li><span class="link-container"><a class="reference external" href="tutorial.html">Object Relational Tutorial</a></span></li>
<li><span class="link-container"><a class="reference external" href="mapper_config.html">Mapper Configuration</a></span></li>
<li><span class="link-container"><a class="reference external" href="relationships.html">Relationship Configuration</a></span><ul>
<li><span class="link-container"><a class="reference external" href="basic_relationships.html">Basic Relationship Patterns</a></span></li>
<li><span class="link-container"><a class="reference external" href="self_referential.html">Adjacency List Relationships</a></span></li>
<li><span class="link-container"><a class="reference external" href="backref.html">Linking Relationships with Backref</a></span></li>
<li><span class="link-container"><a class="reference external" href="join_conditions.html">Configuring how Relationship Joins</a></span></li>
<li class="selected"><span class="link-container"><strong>Collection Configuration and Techniques</strong><a class="paramlink headerlink reference internal" href="#">¶</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#working-with-large-collections">Working with Large Collections</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dynamic-relationship-loaders">Dynamic Relationship Loaders</a></span></li>
<li><span class="link-container"><a class="reference external" href="#setting-noload-raiseload">Setting Noload, RaiseLoad</a></span></li>
<li><span class="link-container"><a class="reference external" href="#using-passive-deletes">Using Passive Deletes</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#customizing-collection-access">Customizing Collection Access</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dictionary-collections">Dictionary Collections</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#custom-collection-implementations">Custom Collection Implementations</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#annotating-custom-collections-via-decorators">Annotating Custom Collections via Decorators</a></span></li>
<li><span class="link-container"><a class="reference external" href="#custom-dictionary-based-collections">Custom Dictionary-Based Collections</a></span></li>
<li><span class="link-container"><a class="reference external" href="#instrumentation-and-custom-types">Instrumentation and Custom Types</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#collection-internals">Collection Internals</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="relationship_persistence.html">Special Relationship Persistence Patterns</a></span></li>
<li><span class="link-container"><a class="reference external" href="relationship_api.html">Relationships API</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="loading_objects.html">Loading Objects</a></span></li>
<li><span class="link-container"><a class="reference external" href="session.html">Using the Session</a></span></li>
<li><span class="link-container"><a class="reference external" href="extending.html">Events and Internals</a></span></li>
<li><span class="link-container"><a class="reference external" href="extensions/index.html">ORM Extensions</a></span></li>
<li><span class="link-container"><a class="reference external" href="examples.html">ORM Examples</a></span></li>
</ul>
</div>
</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="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a> function defines a linkage between two classes.
When the linkage defines a one-to-many or many-to-many relationship, it’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="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></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_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></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_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></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 “dynamic”
relationship. This is an optional form of <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a> which
returns a <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></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"><code class="xref py py-func docutils literal notranslate"><span class="pre">filter()</span></code></a> criterion may be
applied as well as limits and offsets, either explicitly or via array slices:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'user'</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="s2">"dynamic"</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="c1"># filter Jack'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="s1">'this is a post'</span><span class="p">)</span>
<span class="c1"># 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
<code class="docutils literal notranslate"><span class="pre">append()</span></code> and <code class="docutils literal notranslate"><span class="pre">remove()</span></code> methods:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'old post'</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="s1">'new post'</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 “autoflush” is
enabled on the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></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="relationship_api.html#sqlalchemy.orm.backref" title="sqlalchemy.orm.backref"><code class="xref py py-func docutils literal notranslate"><span class="pre">backref()</span></code></a>
function in conjunction with <code class="docutils literal notranslate"><span class="pre">lazy='dynamic'</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'posts'</span><span class="p">,</span> <span class="n">lazy</span><span class="o">=</span><span class="s1">'dynamic'</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="admonition-title">Note</p>
<p>The <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.dynamic_loader" title="sqlalchemy.orm.dynamic_loader"><code class="xref py py-func docutils literal notranslate"><span class="pre">dynamic_loader()</span></code></a> function is essentially the same
as <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a> with the <code class="docutils literal notranslate"><span class="pre">lazy='dynamic'</span></code> argument specified.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The “dynamic” loader applies to <strong>collections only</strong>. It is not valid
to use “dynamic” 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-raiseload">
<span id="collections-noload-raiseload"></span><h3>Setting Noload, RaiseLoad<a class="headerlink" href="#setting-noload-raiseload" title="Permalink to this headline">¶</a></h3>
<p>A “noload” relationship never loads from the database, even when
accessed. It is configured using <code class="docutils literal notranslate"><span class="pre">lazy='noload'</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'some_table'</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="s1">'noload'</span><span class="p">)</span></pre></div>
</div>
<p>Above, the <code class="docutils literal notranslate"><span class="pre">children</span></code> 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 <code class="docutils literal notranslate"><span class="pre">MyClass</span></code> are freshly loaded
from the database, the <code class="docutils literal notranslate"><span class="pre">children</span></code> collection stays empty. The noload
strategy is also available on a query option basis using the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.noload" title="sqlalchemy.orm.noload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.noload()</span></code></a> loader option.</p>
<p>Alternatively, a “raise”-loaded relationship will raise an
<a class="reference internal" href="../core/exceptions.html#sqlalchemy.exc.InvalidRequestError" title="sqlalchemy.exc.InvalidRequestError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InvalidRequestError</span></code></a> where the attribute would normally
emit a lazy load:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'some_table'</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="s1">'raise'</span><span class="p">)</span></pre></div>
</div>
<p>Above, attribute access on the <code class="docutils literal notranslate"><span class="pre">children</span></code> collection will raise an exception
if it was not previously eagerloaded. This includes read access but for
collections will also affect write access, as collections can’t be mutated
without first loading them. The rationale for this is to ensure that an
application is not emitting any unexpected lazy loads within a certain context.
Rather than having to read through SQL logs to determine that all necessary
attributes were eager loaded, the “raise” strategy will cause unloaded
attributes to raise immediately if accessed. The raise strategy is
also available on a query option basis using the <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.raiseload" title="sqlalchemy.orm.raiseload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.raiseload()</span></code></a>
loader option.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1: </span>added the “raise” loader strategy.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="loading_relationships.html#prevent-lazy-with-raiseload"><span class="std std-ref">Preventing unwanted lazy loads using raiseload</span></a></p>
</div>
</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="relationship_api.html#sqlalchemy.orm.relationship.params.passive_deletes" title="sqlalchemy.orm.relationship"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">passive_deletes</span></code></a> to disable child object loading on a DELETE
operation, in conjunction with “ON DELETE (CASCADE|SET NULL)” on your database
to automatically cascade deletes to child objects:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'mytable'</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="kc">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="s2">"MyOtherClass"</span><span class="p">,</span>
<span class="n">cascade</span><span class="o">=</span><span class="s2">"all, delete-orphan"</span><span class="p">,</span>
<span class="n">passive_deletes</span><span class="o">=</span><span class="kc">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="s1">'myothertable'</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="kc">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="s1">'mytable.id'</span><span class="p">,</span> <span class="n">ondelete</span><span class="o">=</span><span class="s1">'CASCADE'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>To use “ON DELETE CASCADE”, the underlying database engine must
support foreign keys.</p>
<ul class="simple">
<li><p>When using MySQL, an appropriate storage engine must be
selected. See <a class="reference internal" href="../dialects/mysql.html#mysql-storage-engines"><span class="std std-ref">CREATE TABLE arguments including Storage Engines</span></a> for details.</p></li>
<li><p>When using SQLite, foreign key support must be enabled explicitly.
See <a class="reference internal" href="../dialects/sqlite.html#sqlite-foreign-keys"><span class="std std-ref">Foreign Key Support</span></a> for details.</p></li>
</ul>
</div>
<p>When <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship.params.passive_deletes" title="sqlalchemy.orm.relationship"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">passive_deletes</span></code></a> is applied, the <code class="docutils literal notranslate"><span class="pre">children</span></code> relationship will not be
loaded into memory when an instance of <code class="docutils literal notranslate"><span class="pre">MyClass</span></code> is marked for deletion. The
<code class="docutils literal notranslate"><span class="pre">cascade="all,</span> <span class="pre">delete-orphan"</span></code> <em>will</em> take effect for instances of
<code class="docutils literal notranslate"><span class="pre">MyOtherClass</span></code> which are currently present in the session; however for
instances of <code class="docutils literal notranslate"><span class="pre">MyOtherClass</span></code> which are not loaded, SQLAlchemy assumes that
“ON DELETE CASCADE” rules will ensure that those rows are deleted by the
database.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.passive_deletes" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">orm.mapper.passive_deletes</span></code></a> - similar feature on <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><code class="xref py py-func docutils literal notranslate"><span class="pre">mapper()</span></code></a></p>
</div>
</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 <code class="docutils literal notranslate"><span class="pre">list</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'parent'</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="kc">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="nb">print</span><span class="p">(</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="relationship_api.html#sqlalchemy.orm.relationship.params.collection_class" title="sqlalchemy.orm.relationship"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">collection_class</span></code></a> option on
<a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'parent'</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="kc">True</span><span class="p">)</span>
<span class="c1"># 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"><code class="xref py py-func docutils literal notranslate"><span class="pre">attribute_mapped_collection()</span></code></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 <code class="docutils literal notranslate"><span class="pre">Item</span></code> class containing
a dictionary of <code class="docutils literal notranslate"><span class="pre">Note</span></code> items keyed to the <code class="docutils literal notranslate"><span class="pre">Note.keyword</span></code> attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">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="k">import</span> <span class="n">relationship</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="k">import</span> <span class="n">attribute_mapped_collection</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.ext.declarative</span> <span class="k">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="s1">'item'</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="kc">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="s2">"Note"</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="s1">'keyword'</span><span class="p">),</span>
<span class="n">cascade</span><span class="o">=</span><span class="s2">"all, delete-orphan"</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="s1">'note'</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="kc">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="s1">'item.id'</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="kc">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><code class="docutils literal notranslate"><span class="pre">Item.notes</span></code> is then a dictionary:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">item</span> <span class="o">=</span> <span class="n">Item</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">item</span><span class="o">.</span><span class="n">notes</span><span class="p">[</span><span class="s1">'a'</span><span class="p">]</span> <span class="o">=</span> <span class="n">Note</span><span class="p">(</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'atext'</span><span class="p">)</span>
<span class="gp">>>> </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">{'a': <__main__.Note object at 0x2eaaf0>}</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><code class="xref py py-func docutils literal notranslate"><span class="pre">attribute_mapped_collection()</span></code></a> will ensure that
the <code class="docutils literal notranslate"><span class="pre">.keyword</span></code> attribute of each <code class="docutils literal notranslate"><span class="pre">Note</span></code> complies with the key in the
dictionary. Such as, when assigning to <code class="docutils literal notranslate"><span class="pre">Item.notes</span></code>, the dictionary
key we supply must match that of the actual <code class="docutils literal notranslate"><span class="pre">Note</span></code> object:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'a'</span><span class="p">:</span> <span class="n">Note</span><span class="p">(</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'atext'</span><span class="p">),</span>
<span class="s1">'b'</span><span class="p">:</span> <span class="n">Note</span><span class="p">(</span><span class="s1">'b'</span><span class="p">,</span> <span class="s1">'btext'</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"><code class="xref py py-func docutils literal notranslate"><span class="pre">attribute_mapped_collection()</span></code></a> uses as a key
does not need to be mapped at all! Using a regular Python <code class="docutils literal notranslate"><span class="pre">@property</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Note.keyword</span></code> and the first ten letters
of the <code class="docutils literal notranslate"><span class="pre">Note.text</span></code> field:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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="s1">'item'</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="kc">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="s2">"Note"</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="s1">'note_key'</span><span class="p">),</span>
<span class="n">backref</span><span class="o">=</span><span class="s2">"item"</span><span class="p">,</span>
<span class="n">cascade</span><span class="o">=</span><span class="s2">"all, delete-orphan"</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="s1">'note'</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="kc">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="s1">'item.id'</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="kc">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 <code class="docutils literal notranslate"><span class="pre">Note.item</span></code> backref. Assigning to this reverse relationship, the <code class="docutils literal notranslate"><span class="pre">Note</span></code>
is added to the <code class="docutils literal notranslate"><span class="pre">Item.notes</span></code> dictionary and the key is generated for us automatically:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">item</span> <span class="o">=</span> <span class="n">Item</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">n1</span> <span class="o">=</span> <span class="n">Note</span><span class="p">(</span><span class="s2">"a"</span><span class="p">,</span> <span class="s2">"atext"</span><span class="p">)</span>
<span class="gp">>>> </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">>>> </span><span class="n">item</span><span class="o">.</span><span class="n">notes</span>
<span class="go">{('a', 'atext'): <__main__.Note object at 0x2eaaf0>}</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"><code class="xref py py-func docutils literal notranslate"><span class="pre">column_mapped_collection()</span></code></a>,
which is almost like <a class="reference internal" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><code class="xref py py-func docutils literal notranslate"><span class="pre">attribute_mapped_collection()</span></code></a> except given the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a>
object directly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="k">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="s1">'item'</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="kc">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="s2">"Note"</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="s2">"all, delete-orphan"</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"><code class="xref py py-func docutils literal notranslate"><span class="pre">mapped_collection()</span></code></a> which is passed any callable function.
Note that it’s usually easier to use <a class="reference internal" href="#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><code class="xref py py-func docutils literal notranslate"><span class="pre">attribute_mapped_collection()</span></code></a> along
with a <code class="docutils literal notranslate"><span class="pre">@property</span></code> as mentioned earlier:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="k">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="s1">'item'</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="kc">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="s2">"Note"</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="s2">"all, delete-orphan"</span><span class="p">)</span></pre></div>
</div>
<p>Dictionary mappings are often combined with the “Association Proxy” extension to produce
streamlined dictionary views. See <a class="reference internal" href="extensions/associationproxy.html#proxying-dictionaries"><span class="std std-ref">Proxying to Dictionary Based Collections</span></a> and <a class="reference internal" href="extensions/associationproxy.html#composite-association-proxy"><span class="std std-ref">Composite Association Proxies</span></a>
for examples.</p>
<dl class="function">
<dt id="sqlalchemy.orm.collections.attribute_mapped_collection">
<code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">attribute_mapped_collection</code><span class="sig-paren">(</span><em>attr_name</em><span class="sig-paren">)</span><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"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></a> factory with a keying based on the
‘attr_name’ attribute of entities in the collection, where <code class="docutils literal notranslate"><span class="pre">attr_name</span></code>
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">
<code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">column_mapped_collection</code><span class="sig-paren">(</span><em>mapping_spec</em><span class="sig-paren">)</span><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"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></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">
<code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">mapped_collection</code><span class="sig-paren">(</span><em>keyfunc</em><span class="sig-paren">)</span><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"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></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,
inheriting from <code class="docutils literal notranslate"><span class="pre">list</span></code> or <code class="docutils literal notranslate"><span class="pre">set</span></code>, adding custom behavior, is all that’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 “custom” 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 “view” of that data on the outside of a different form.</p>
<p>For the first use case, the <a class="reference internal" href="mapped_attributes.html#sqlalchemy.orm.validates" title="sqlalchemy.orm.validates"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.validates()</span></code></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="mapped_attributes.html#simple-validators"><span class="std std-ref">Simple Validators</span></a>
for an example of this.</p>
<p>For the second use case, the <a class="reference internal" href="extensions/associationproxy.html"><span class="std std-ref">Association Proxy</span></a> extension is a
well-tested, widely used system that provides a read/write “view” of a
collection in terms of some attribute present on the target object. As the
target attribute can be a <code class="docutils literal notranslate"><span class="pre">@property</span></code> that returns virtually anything, a
wide array of “alternative” 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’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’s <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> (i.e. the <code class="docutils literal notranslate"><span class="pre">save-update</span></code>
cascade), as well as synchronizing the state of a bi-directional relationship
(i.e. a <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.backref" title="sqlalchemy.orm.backref"><code class="xref py py-func docutils literal notranslate"><span class="pre">backref()</span></code></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 notranslate"><div class="highlight"><pre><span></span><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="fm">__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="fm">__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="s1">'foo'</span></pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">append</span></code>, <code class="docutils literal notranslate"><span class="pre">remove</span></code>, and <code class="docutils literal notranslate"><span class="pre">extend</span></code> are known list-like methods, and will
be instrumented automatically. <code class="docutils literal notranslate"><span class="pre">__iter__</span></code> is not a mutator method and won’t
be instrumented, and <code class="docutils literal notranslate"><span class="pre">foo</span></code> won’t be either.</p>
<p>Duck-typing (i.e. guesswork) isn’t rock-solid, of course, so you can be
explicit about the interface you are implementing by providing an
<code class="docutils literal notranslate"><span class="pre">__emulates__</span></code> class attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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="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 <code class="docutils literal notranslate"><span class="pre">append</span></code>, but <code class="docutils literal notranslate"><span class="pre">__emulates__</span></code> forces
it to set-like. <code class="docutils literal notranslate"><span class="pre">remove</span></code> is known to be part of the set interface and will
be instrumented.</p>
<p>But this class won’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
<code class="docutils literal notranslate"><span class="pre">list</span></code> or <code class="docutils literal notranslate"><span class="pre">set</span></code>, the appropriate methods are well-known and used
automatically when present. This set-like class does not provide the expected
<code class="docutils literal notranslate"><span class="pre">add</span></code> 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’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 notranslate"><div class="highlight"><pre><span></span><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="fm">__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="fm">__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’s all that’s needed to complete the example. SQLAlchemy will add
instances via the <code class="docutils literal notranslate"><span class="pre">append</span></code> method. <code class="docutils literal notranslate"><span class="pre">remove</span></code> and <code class="docutils literal notranslate"><span class="pre">__iter__</span></code> 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 notranslate"><div class="highlight"><pre><span></span><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="c1"># 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="c1"># ...</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’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><code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">collection</code><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’s purpose and take no
arguments. They are not written with parens:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">adds</span><span class="p">(</span><span class="s1">'entity'</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</span><span class="o">.</span><span class="n">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><code class="descname">adds</code><span class="sig-paren">(</span><em>arg</em><span class="sig-paren">)</span><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 “add to collection” 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-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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</span><span class="o">.</span><span class="n">adds</span><span class="p">(</span><span class="s1">'entity'</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="kc">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><code class="descname">appender</code><span class="sig-paren">(</span><em>fn</em><span class="sig-paren">)</span><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 ‘adds(1)’
if not already decorated:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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="c1"># or, equivalently</span>
<span class="nd">@collection</span><span class="o">.</span><span class="n">appender</span>
<span class="nd">@collection</span><span class="o">.</span><span class="n">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="c1"># for mapping type, an 'append' may kick out a previous value</span>
<span class="c1"># that occupies that slot. consider d['a'] = 'foo'- any previous</span>
<span class="c1"># value in d['a'] is discarded.</span>
<span class="nd">@collection</span><span class="o">.</span><span class="n">appender</span>
<span class="nd">@collection</span><span class="o">.</span><span class="n">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="kc">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 ‘_sa_initiator’ 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><code class="descname">converter</code><span class="sig-paren">(</span><em>fn</em><span class="sig-paren">)</span><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-default notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">appender</span></code>
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’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-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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><code class="descname">internally_instrumented</code><span class="sig-paren">(</span><em>fn</em><span class="sig-paren">)</span><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
<code class="xref py py-func docutils literal notranslate"><span class="pre">collection_adapter()</span></code> in one of the basic SQLAlchemy
interface methods, or to prevent an automatic ABC method
decoration from wrapping your implementation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># normally an 'extend' method on a list-like class would be</span>
<span class="c1"># automatically intercepted and re-implemented in terms of</span>
<span class="c1"># SQLAlchemy events and append(). your implementation will</span>
<span class="c1"># never be called, unless:</span>
<span class="nd">@collection</span><span class="o">.</span><span class="n">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><code class="descname">iterator</code><span class="sig-paren">(</span><em>fn</em><span class="sig-paren">)</span><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-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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><code class="descname">link</code><span class="sig-paren">(</span><em>fn</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.collections.collection.link" title="Permalink to this definition">¶</a></dt>
<dd><p>Synonym for <a class="reference internal" href="#sqlalchemy.orm.collections.collection.linker" title="sqlalchemy.orm.collections.collection.linker"><code class="xref py py-meth docutils literal notranslate"><span class="pre">collection.linker()</span></code></a>.</p>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 1.0: </span>- <a class="reference internal" href="#sqlalchemy.orm.collections.collection.link" title="sqlalchemy.orm.collections.collection.link"><code class="xref py py-meth docutils literal notranslate"><span class="pre">collection.link()</span></code></a> is deprecated and will be
removed in a future release.</p>
</div>
</dd></dl>
<dl class="staticmethod">
<dt id="sqlalchemy.orm.collections.collection.linker">
<em class="property">static </em><code class="descname">linker</code><span class="sig-paren">(</span><em>fn</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.collections.collection.linker" title="Permalink to this definition">¶</a></dt>
<dd><p>Tag the method as a “linked to attribute” event handler.</p>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 1.0: </span>The <a class="reference internal" href="#sqlalchemy.orm.collections.collection.linker" title="sqlalchemy.orm.collections.collection.linker"><code class="xref py py-meth docutils literal notranslate"><span class="pre">collection.linker()</span></code></a> handler is deprecated and will be removed in a future release. Please refer to the <a class="reference internal" href="events.html#sqlalchemy.orm.events.AttributeEvents.init_collection" title="sqlalchemy.orm.events.AttributeEvents.init_collection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">AttributeEvents.init_collection()</span></code></a> and <a class="reference internal" href="events.html#sqlalchemy.orm.events.AttributeEvents.dispose_collection" title="sqlalchemy.orm.events.AttributeEvents.dispose_collection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">AttributeEvents.dispose_collection()</span></code></a> event handlers. </p>
</div>
<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 ‘_sa_adapter’ 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><code class="descname">remover</code><span class="sig-paren">(</span><em>fn</em><span class="sig-paren">)</span><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"><code class="xref py py-meth docutils literal notranslate"><span class="pre">removes_return()</span></code></a> if not already decorated:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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="c1"># or, equivalently</span>
<span class="nd">@collection</span><span class="o">.</span><span class="n">remover</span>
<span class="nd">@collection</span><span class="o">.</span><span class="n">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 ‘_sa_initiator’ 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><code class="descname">removes</code><span class="sig-paren">(</span><em>arg</em><span class="sig-paren">)</span><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 “remove from collection” 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-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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><code class="descname">removes_return</code><span class="sig-paren">(</span><span class="sig-paren">)</span><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 “remove from collection” 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-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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><code class="descname">replaces</code><span class="sig-paren">(</span><em>arg</em><span class="sig-paren">)</span><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 “add to collection” and “remove from collection” 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-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></a> class can be used as
a base class for your custom types or as a mix-in to quickly add <code class="docutils literal notranslate"><span class="pre">dict</span></code>
collection support to other classes. It uses a keying function to delegate to
<code class="docutils literal notranslate"><span class="pre">__setitem__</span></code> and <code class="docutils literal notranslate"><span class="pre">__delitem__</span></code>:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><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">"""Holds 'Node' objects, keyed by the 'name' attribute with insert order maintained."""</span>
<span class="k">def</span> <span class="fm">__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="fm">__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="fm">__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"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></a>, user-defined versions
of <code class="docutils literal notranslate"><span class="pre">__setitem__()</span></code> or <code class="docutils literal notranslate"><span class="pre">__delitem__()</span></code> should be decorated
with <a class="reference internal" href="#sqlalchemy.orm.collections.collection.internally_instrumented" title="sqlalchemy.orm.collections.collection.internally_instrumented"><code class="xref py py-meth docutils literal notranslate"><span class="pre">collection.internally_instrumented()</span></code></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"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></a>. This because the methods
on <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></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-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="k">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">"""Use @internally_instrumented when your methods</span>
<span class="sd"> call down to already-instrumented methods.</span>
<span class="sd"> """</span>
<span class="nd">@collection</span><span class="o">.</span><span class="n">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="kc">None</span><span class="p">):</span>
<span class="c1"># 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="fm">__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</span><span class="o">.</span><span class="n">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="kc">None</span><span class="p">):</span>
<span class="c1"># 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="fm">__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 <code class="docutils literal notranslate"><span class="pre">dict</span></code> interface just like lists and sets, and will
automatically instrument all dict-like methods if you choose to subclass
<code class="docutils literal notranslate"><span class="pre">dict</span></code> 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 <code class="docutils literal notranslate"><span class="pre">itervalues()</span></code> unless otherwise decorated.</p>
<div class="admonition note">
<p class="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"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></a> which uses <a class="reference internal" href="#sqlalchemy.orm.collections.collection.internally_instrumented" title="sqlalchemy.orm.collections.collection.internally_instrumented"><code class="xref py py-meth docutils literal notranslate"><span class="pre">collection.internally_instrumented()</span></code></a>
can be used:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="k">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>This will ensure that the <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><code class="xref py py-class docutils literal notranslate"><span class="pre">MappedCollection</span></code></a> has been properly
initialized with custom <code class="docutils literal notranslate"><span class="pre">__setitem__()</span></code> and <code class="docutils literal notranslate"><span class="pre">__delitem__()</span></code>
methods before used in a custom subclass.</p>
</div>
<dl class="class">
<dt id="sqlalchemy.orm.collections.MappedCollection">
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">MappedCollection</code><span class="sig-paren">(</span><em>keyfunc</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">builtins.dict</span></code></p>
<p>A basic dictionary-based collection class.</p>
<p>Extends dict with the minimal bag semantics that collection
classes require. <code class="docutils literal notranslate"><span class="pre">set</span></code> and <code class="docutils literal notranslate"><span class="pre">remove</span></code> 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__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>keyfunc</em><span class="sig-paren">)</span><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 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-
<code class="docutils literal notranslate"><span class="pre">keyfunc(object)</span></code> should return the same output for the life of the
collection. Keying based on mutable properties can result in
unreachable instances “lost” in the collection.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.clear">
<code class="descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span> → 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">
<code class="descname">pop</code><span class="sig-paren">(</span><em>k</em><span class="optional">[</span>, <em>d</em><span class="optional">]</span><span class="sig-paren">)</span> → 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">
<code class="descname">popitem</code><span class="sig-paren">(</span><span class="sig-paren">)</span> → (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">
<code class="descname">remove</code><span class="sig-paren">(</span><em>value</em>, <em>_sa_initiator=None</em><span class="sig-paren">)</span><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">
<code class="descname">set</code><span class="sig-paren">(</span><em>value</em>, <em>_sa_initiator=None</em><span class="sig-paren">)</span><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">
<code class="descname">setdefault</code><span class="sig-paren">(</span><em>key</em>, <em>default=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.setdefault" title="Permalink to this definition">¶</a></dt>
<dd><p>Insert key with a value of default if key is not in the dictionary.</p>
<p>Return the value for key if key is in the dictionary, else default.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.collections.MappedCollection.update">
<code class="descname">update</code><span class="sig-paren">(</span><span class="optional">[</span><em>E</em>, <span class="optional">]</span><em>**F</em><span class="sig-paren">)</span> → 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 is present and has a .keys() method, then does: for k in E: D[k] = E[k]
If E is present and lacks a .keys() method, then 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 “trivial subclass” trick
to restrict the decorations to just your usage in relationships. For example:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><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="c1"># ... relationship(..., collection_class=MyAwesomeList)</span></pre></div>
</div>
<p>The ORM uses this approach for built-ins, quietly substituting a trivial
subclass when a <code class="docutils literal notranslate"><span class="pre">list</span></code>, <code class="docutils literal notranslate"><span class="pre">set</span></code> or <code class="docutils literal notranslate"><span class="pre">dict</span></code> 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">
<code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">bulk_replace</code><span class="sig-paren">(</span><em>values</em>, <em>existing_adapter</em>, <em>new_adapter</em>, <em>initiator=None</em><span class="sig-paren">)</span><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 <code class="docutils literal notranslate"><span class="pre">values</span></code> onto the <code class="docutils literal notranslate"><span class="pre">new_adapter</span></code>. Events will be
fired for any instance not present in the <code class="docutils literal notranslate"><span class="pre">existing_adapter</span></code>. Any
instances in <code class="docutils literal notranslate"><span class="pre">existing_adapter</span></code> not present in <code class="docutils literal notranslate"><span class="pre">values</span></code> will have
remove events fired upon them.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><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> – An iterable of collection member instances</p></li>
<li><p><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> – A <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">CollectionAdapter</span></code></a> of
instances to be replaced</p></li>
<li><p><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> – An empty <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">CollectionAdapter</span></code></a>
to load with <code class="docutils literal notranslate"><span class="pre">values</span></code></p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="class">
<dt>
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">collection</code></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’s purpose and take no
arguments. They are not written with parens:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">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-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@collection</span><span class="o">.</span><span class="n">adds</span><span class="p">(</span><span class="s1">'entity'</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</span><span class="o">.</span><span class="n">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="data">
<dt id="sqlalchemy.orm.collections.collection_adapter">
<code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">collection_adapter</code><em class="property"> = operator.attrgetter('_sa_adapter')</em><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"><code class="xref py py-class docutils literal notranslate"><span class="pre">CollectionAdapter</span></code></a> for a collection.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.orm.collections.CollectionAdapter">
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">CollectionAdapter</code><span class="sig-paren">(</span><em>attr</em>, <em>owner_state</em>, <em>data</em><span class="sig-paren">)</span><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"><code class="xref py py-class docutils literal notranslate"><span class="pre">CollectionAdapter</span></code></a> exclusively for interaction with
entity collections.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.orm.collections.InstrumentedDict">
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">InstrumentedDict</code><a class="headerlink" href="#sqlalchemy.orm.collections.InstrumentedDict" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">builtins.dict</span></code></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><code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">InstrumentedList</code><a class="headerlink" href="#sqlalchemy.orm.collections.InstrumentedList" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">builtins.list</span></code></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><code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">InstrumentedSet</code><a class="headerlink" href="#sqlalchemy.orm.collections.InstrumentedSet" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">builtins.set</span></code></p>
<p>An instrumented version of the built-in set.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.collections.prepare_instrumentation">
<code class="descclassname">sqlalchemy.orm.collections.</code><code class="descname">prepare_instrumentation</code><span class="sig-paren">(</span><em>factory</em><span class="sig-paren">)</span><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, withsidebar">
Previous:
<a href="join_conditions.html" title="previous chapter">Configuring how Relationship Joins</a>
Next:
<a href="relationship_persistence.html" title="next chapter">Special Relationship Persistence Patterns</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2019, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
</div>
</div>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.2.19',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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>
<script type="text/javascript" src="../_static/language_data.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>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
b0b6ffab06cbeede296e36ce94734bf8
>
files
>
813
