File: associationproxy.html

package info (click to toggle)
sqlalchemy 0.9.8%2Bdfsg-0.1
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 23,952 kB
ctags: 24,534
sloc: python: 152,282; ansic: 1,346; makefile: 257; xml: 17
file content (856 lines) | stat: -rw-r--r-- 89,960 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        
        <title>
            
    
                Association Proxy
             &mdash;
    SQLAlchemy 0.9 Documentation

        </title>

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

        

    

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

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

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

    <script type="text/javascript" src="../../_static/detectmobile.js"></script>
    <script type="text/javascript" src="../../_static/init.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
        <link rel="copyright" title="Copyright" href="../../copyright.html" />
    <link rel="top" title="SQLAlchemy 0.9 Documentation" href="../../index.html" />
        <link rel="up" title="ORM Extensions" href="index.html" />
        <link rel="next" title="Automap" href="automap.html" />
        <link rel="prev" title="ORM Extensions" href="index.html" />
    <!-- end layout.mako headers -->


    </head>
    <body>
        















<div id="docs-container">





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

    <h1>SQLAlchemy 0.9 Documentation</h1>

</div>
</div>

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

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


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

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

                    <a href="index.html" title="ORM Extensions">Prev</a> |
                    <a href="automap.html" title="Automap">Next</a>
            </p>

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

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

        </div>

        <div id="docs-sidebar">

        <h3><a href="#">            
                Association Proxy
            
        </a></h3>
        <ul>
<li><a class="reference internal" href="#">Association Proxy</a><ul>
<li><a class="reference internal" href="#simplifying-scalar-collections">Simplifying Scalar Collections</a></li>
<li><a class="reference internal" href="#creation-of-new-values">Creation of New Values</a></li>
<li><a class="reference internal" href="#simplifying-association-objects">Simplifying Association Objects</a></li>
<li><a class="reference internal" href="#proxying-to-dictionary-based-collections">Proxying to Dictionary Based Collections</a></li>
<li><a class="reference internal" href="#composite-association-proxies">Composite Association Proxies</a></li>
<li><a class="reference internal" href="#querying-with-association-proxies">Querying with Association Proxies</a></li>
<li><a class="reference internal" href="#api-documentation">API Documentation</a></li>
</ul>
</li>
</ul>




        </div>

    </div>

    

    <div id="docs-body" class="withsidebar" >
        
<div class="section" id="module-sqlalchemy.ext.associationproxy">
<span id="association-proxy"></span><span id="associationproxy-toplevel"></span><h1>Association Proxy<a class="headerlink" href="#module-sqlalchemy.ext.associationproxy" title="Permalink to this headline">¶</a></h1>
<p><tt class="docutils literal"><span class="pre">associationproxy</span></tt> is used to create a read/write view of a
target attribute across a relationship.  It essentially conceals
the usage of a &#8220;middle&#8221; attribute between two endpoints, and
can be used to cherry-pick fields from a collection of
related objects or to reduce the verbosity of using the association
object pattern.   Applied creatively, the association proxy allows
the construction of sophisticated collections and dictionary
views of virtually any geometry, persisted to the database using
standard, transparently configured relational patterns.</p>
<div class="section" id="simplifying-scalar-collections">
<h2>Simplifying Scalar Collections<a class="headerlink" href="#simplifying-scalar-collections" title="Permalink to this headline">¶</a></h2>
<p>Consider a many-to-many mapping between two classes, <tt class="docutils literal"><span class="pre">User</span></tt> and <tt class="docutils literal"><span class="pre">Keyword</span></tt>.
Each <tt class="docutils literal"><span class="pre">User</span></tt> can have any number of <tt class="docutils literal"><span class="pre">Keyword</span></tt> objects, and vice-versa
(the many-to-many pattern is described at <a class="reference internal" href="../relationships.html#relationships-many-to-many"><em>Many To Many</em></a>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Column</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">String</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">,</span> <span class="n">Table</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">relationship</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.ext.declarative</span> <span class="kn">import</span> <span class="n">declarative_base</span>

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

<span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">name</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="mi">64</span><span class="p">))</span>
    <span class="n">kw</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Keyword&quot;</span><span class="p">,</span> <span class="n">secondary</span><span class="o">=</span><span class="k">lambda</span><span class="p">:</span> <span class="n">userkeywords_table</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">name</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

<span class="k">class</span> <span class="nc">Keyword</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;keyword&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="s">&#39;keyword&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">64</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="bp">self</span><span class="o">.</span><span class="n">keyword</span> <span class="o">=</span> <span class="n">keyword</span>

<span class="n">userkeywords_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">&#39;userkeywords&#39;</span><span class="p">,</span> <span class="n">Base</span><span class="o">.</span><span class="n">metadata</span><span class="p">,</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;user_id&#39;</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&quot;user.id&quot;</span><span class="p">),</span>
           <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;keyword_id&#39;</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&quot;keyword.id&quot;</span><span class="p">),</span>
           <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Reading and manipulating the collection of &#8220;keyword&#8221; strings associated
with <tt class="docutils literal"><span class="pre">User</span></tt> requires traversal from each collection element to the <tt class="docutils literal"><span class="pre">.keyword</span></tt>
attribute, which can be awkward:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="s">&#39;jek&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">kw</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Keyword</span><span class="p">(</span><span class="s">&#39;cheese inspector&#39;</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">kw</span><span class="p">)</span>
<span class="go">[&lt;__main__.Keyword object at 0x12bf830&gt;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">kw</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">keyword</span><span class="p">)</span>
<span class="go">cheese inspector</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">([</span><span class="n">keyword</span><span class="o">.</span><span class="n">keyword</span> <span class="k">for</span> <span class="n">keyword</span> <span class="ow">in</span> <span class="n">user</span><span class="o">.</span><span class="n">kw</span><span class="p">])</span>
<span class="go">[&#39;cheese inspector&#39;]</span></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">association_proxy</span></tt> is applied to the <tt class="docutils literal"><span class="pre">User</span></tt> class to produce
a &#8220;view&#8221; of the <tt class="docutils literal"><span class="pre">kw</span></tt> relationship, which only exposes the string
value of <tt class="docutils literal"><span class="pre">.keyword</span></tt> associated with each <tt class="docutils literal"><span class="pre">Keyword</span></tt> object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.ext.associationproxy</span> <span class="kn">import</span> <span class="n">association_proxy</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="s">&#39;user&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">name</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="mi">64</span><span class="p">))</span>
    <span class="n">kw</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Keyword&quot;</span><span class="p">,</span> <span class="n">secondary</span><span class="o">=</span><span class="k">lambda</span><span class="p">:</span> <span class="n">userkeywords_table</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">name</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

    <span class="c"># proxy the &#39;keyword&#39; attribute from the &#39;kw&#39; relationship</span>
    <span class="n">keywords</span> <span class="o">=</span> <span class="n">association_proxy</span><span class="p">(</span><span class="s">&#39;kw&#39;</span><span class="p">,</span> <span class="s">&#39;keyword&#39;</span><span class="p">)</span></pre></div>
</div>
<p>We can now reference the <tt class="docutils literal"><span class="pre">.keywords</span></tt> collection as a listing of strings,
which is both readable and writable.  New <tt class="docutils literal"><span class="pre">Keyword</span></tt> objects are created
for us transparently:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="s">&#39;jek&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">&#39;cheese inspector&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span>
<span class="go">[&#39;cheese inspector&#39;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">&#39;snack ninja&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">kw</span>
<span class="go">[&lt;__main__.Keyword object at 0x12cdd30&gt;, &lt;__main__.Keyword object at 0x12cde30&gt;]</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a> object produced by the <a class="reference internal" href="#sqlalchemy.ext.associationproxy.association_proxy" title="sqlalchemy.ext.associationproxy.association_proxy"><tt class="xref py py-func docutils literal"><span class="pre">association_proxy()</span></tt></a> function
is an instance of a <a class="reference external" href="http://docs.python.org/howto/descriptor.html">Python descriptor</a>.
It is always declared with the user-defined class being mapped, regardless of
whether Declarative or classical mappings via the <a class="reference internal" href="../mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a> function are used.</p>
<p>The proxy functions by operating upon the underlying mapped attribute
or collection in response to operations, and changes made via the proxy are immediately
apparent in the mapped attribute, as well as vice versa.   The underlying
attribute remains fully accessible.</p>
<p>When first accessed, the association proxy performs introspection
operations on the target collection so that its behavior corresponds correctly.
Details such as if the locally proxied attribute is a collection (as is typical)
or a scalar reference, as well as if the collection acts like a set, list,
or dictionary is taken into account, so that the proxy should act just like
the underlying collection or attribute does.</p>
</div>
<div class="section" id="creation-of-new-values">
<h2>Creation of New Values<a class="headerlink" href="#creation-of-new-values" title="Permalink to this headline">¶</a></h2>
<p>When a list append() event (or set add(), dictionary __setitem__(), or scalar
assignment event) is intercepted by the association proxy, it instantiates a
new instance of the &#8220;intermediary&#8221; object using its constructor, passing as a
single argument the given value. In our example above, an operation like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">&#39;cheese inspector&#39;</span><span class="p">)</span></pre></div>
</div>
<p>Is translated by the association proxy into the operation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">user</span><span class="o">.</span><span class="n">kw</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Keyword</span><span class="p">(</span><span class="s">&#39;cheese inspector&#39;</span><span class="p">))</span></pre></div>
</div>
<p>The example works here because we have designed the constructor for <tt class="docutils literal"><span class="pre">Keyword</span></tt>
to accept a single positional argument, <tt class="docutils literal"><span class="pre">keyword</span></tt>.   For those cases where a
single-argument constructor isn&#8217;t feasible, the association proxy&#8217;s creational
behavior can be customized using the <tt class="docutils literal"><span class="pre">creator</span></tt> argument, which references a
callable (i.e. Python function) that will produce a new object instance given the
singular argument.  Below we illustrate this using a lambda as is typical:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="c"># ...</span>

    <span class="c"># use Keyword(keyword=kw) on append() events</span>
    <span class="n">keywords</span> <span class="o">=</span> <span class="n">association_proxy</span><span class="p">(</span><span class="s">&#39;kw&#39;</span><span class="p">,</span> <span class="s">&#39;keyword&#39;</span><span class="p">,</span>
                    <span class="n">creator</span><span class="o">=</span><span class="k">lambda</span> <span class="n">kw</span><span class="p">:</span> <span class="n">Keyword</span><span class="p">(</span><span class="n">keyword</span><span class="o">=</span><span class="n">kw</span><span class="p">))</span></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">creator</span></tt> function accepts a single argument in the case of a list-
or set- based collection, or a scalar attribute.  In the case of a dictionary-based
collection, it accepts two arguments, &#8220;key&#8221; and &#8220;value&#8221;.   An example
of this is below in <a class="reference internal" href="#proxying-dictionaries"><em>Proxying to Dictionary Based Collections</em></a>.</p>
</div>
<div class="section" id="simplifying-association-objects">
<h2>Simplifying Association Objects<a class="headerlink" href="#simplifying-association-objects" title="Permalink to this headline">¶</a></h2>
<p>The &#8220;association object&#8221; pattern is an extended form of a many-to-many
relationship, and is described at <a class="reference internal" href="../relationships.html#association-pattern"><em>Association Object</em></a>. Association
proxies are useful for keeping &#8220;association objects&#8221; out the way during
regular use.</p>
<p>Suppose our <tt class="docutils literal"><span class="pre">userkeywords</span></tt> table above had additional columns
which we&#8217;d like to map explicitly, but in most cases we don&#8217;t
require direct access to these attributes.  Below, we illustrate
a new mapping which introduces the <tt class="docutils literal"><span class="pre">UserKeyword</span></tt> class, which
is mapped to the <tt class="docutils literal"><span class="pre">userkeywords</span></tt> table illustrated earlier.
This class adds an additional column <tt class="docutils literal"><span class="pre">special_key</span></tt>, a value which
we occasionally want to access, but not in the usual case.   We
create an association proxy on the <tt class="docutils literal"><span class="pre">User</span></tt> class called
<tt class="docutils literal"><span class="pre">keywords</span></tt>, which will bridge the gap from the <tt class="docutils literal"><span class="pre">user_keywords</span></tt>
collection of <tt class="docutils literal"><span class="pre">User</span></tt> to the <tt class="docutils literal"><span class="pre">.keyword</span></tt> attribute present on each
<tt class="docutils literal"><span class="pre">UserKeyword</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Column</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">String</span><span class="p">,</span> <span class="n">ForeignKey</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">relationship</span><span class="p">,</span> <span class="n">backref</span>

<span class="kn">from</span> <span class="nn">sqlalchemy.ext.associationproxy</span> <span class="kn">import</span> <span class="n">association_proxy</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.ext.declarative</span> <span class="kn">import</span> <span class="n">declarative_base</span>

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

<span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">name</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="mi">64</span><span class="p">))</span>

    <span class="c"># association proxy of &quot;user_keywords&quot; collection</span>
    <span class="c"># to &quot;keyword&quot; attribute</span>
    <span class="n">keywords</span> <span class="o">=</span> <span class="n">association_proxy</span><span class="p">(</span><span class="s">&#39;user_keywords&#39;</span><span class="p">,</span> <span class="s">&#39;keyword&#39;</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">name</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

<span class="k">class</span> <span class="nc">UserKeyword</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user_keyword&#39;</span>
    <span class="n">user_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;user.id&#39;</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">keyword_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;keyword.id&#39;</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">special_key</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="mi">50</span><span class="p">))</span>

    <span class="c"># bidirectional attribute/collection of &quot;user&quot;/&quot;user_keywords&quot;</span>
    <span class="n">user</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="n">User</span><span class="p">,</span>
                <span class="n">backref</span><span class="o">=</span><span class="n">backref</span><span class="p">(</span><span class="s">&quot;user_keywords&quot;</span><span class="p">,</span>
                                <span class="n">cascade</span><span class="o">=</span><span class="s">&quot;all, delete-orphan&quot;</span><span class="p">)</span>
            <span class="p">)</span>

    <span class="c"># reference to the &quot;Keyword&quot; object</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Keyword&quot;</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="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">special_key</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="n">user</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">special_key</span> <span class="o">=</span> <span class="n">special_key</span>

<span class="k">class</span> <span class="nc">Keyword</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;keyword&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="s">&#39;keyword&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">64</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="bp">self</span><span class="o">.</span><span class="n">keyword</span> <span class="o">=</span> <span class="n">keyword</span>

    <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&#39;Keyword(</span><span class="si">%s</span><span class="s">)&#39;</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">keyword</span><span class="p">)</span></pre></div>
</div>
<p>With the above configuration, we can operate upon the <tt class="docutils literal"><span class="pre">.keywords</span></tt>
collection of each <tt class="docutils literal"><span class="pre">User</span></tt> object, and the usage of <tt class="docutils literal"><span class="pre">UserKeyword</span></tt>
is concealed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="s">&#39;log&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">kw</span> <span class="ow">in</span> <span class="p">(</span><span class="n">Keyword</span><span class="p">(</span><span class="s">&#39;new_from_blammo&#39;</span><span class="p">),</span> <span class="n">Keyword</span><span class="p">(</span><span class="s">&#39;its_big&#39;</span><span class="p">)):</span>
<span class="gp">... </span>    <span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">kw</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="p">)</span>
<span class="go">[Keyword(&#39;new_from_blammo&#39;), Keyword(&#39;its_big&#39;)]</span></pre></div>
</div>
<p>Where above, each <tt class="docutils literal"><span class="pre">.keywords.append()</span></tt> operation is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">user_keywords</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">UserKeyword</span><span class="p">(</span><span class="n">Keyword</span><span class="p">(</span><span class="s">&#39;its_heavy&#39;</span><span class="p">)))</span></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">UserKeyword</span></tt> association object has two attributes here which are populated;
the <tt class="docutils literal"><span class="pre">.keyword</span></tt> attribute is populated directly as a result of passing
the <tt class="docutils literal"><span class="pre">Keyword</span></tt> object as the first argument.   The <tt class="docutils literal"><span class="pre">.user</span></tt> argument is then
assigned as the <tt class="docutils literal"><span class="pre">UserKeyword</span></tt> object is appended to the <tt class="docutils literal"><span class="pre">User.user_keywords</span></tt>
collection, where the bidirectional relationship configured between <tt class="docutils literal"><span class="pre">User.user_keywords</span></tt>
and <tt class="docutils literal"><span class="pre">UserKeyword.user</span></tt> results in a population of the <tt class="docutils literal"><span class="pre">UserKeyword.user</span></tt> attribute.
The <tt class="docutils literal"><span class="pre">special_key</span></tt> argument above is left at its default value of <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
<p>For those cases where we do want <tt class="docutils literal"><span class="pre">special_key</span></tt> to have a value, we
create the <tt class="docutils literal"><span class="pre">UserKeyword</span></tt> object explicitly.  Below we assign all three
attributes, where the assignment of <tt class="docutils literal"><span class="pre">.user</span></tt> has the effect of the <tt class="docutils literal"><span class="pre">UserKeyword</span></tt>
being appended to the <tt class="docutils literal"><span class="pre">User.user_keywords</span></tt> collection:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">UserKeyword</span><span class="p">(</span><span class="n">Keyword</span><span class="p">(</span><span class="s">&#39;its_wood&#39;</span><span class="p">),</span> <span class="n">user</span><span class="p">,</span> <span class="n">special_key</span><span class="o">=</span><span class="s">&#39;my special key&#39;</span><span class="p">)</span></pre></div>
</div>
<p>The association proxy returns to us a collection of <tt class="docutils literal"><span class="pre">Keyword</span></tt> objects represented
by all these operations:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span>
<span class="go">[Keyword(&#39;new_from_blammo&#39;), Keyword(&#39;its_big&#39;), Keyword(&#39;its_heavy&#39;), Keyword(&#39;its_wood&#39;)]</span></pre></div>
</div>
</div>
<div class="section" id="proxying-to-dictionary-based-collections">
<span id="proxying-dictionaries"></span><h2>Proxying to Dictionary Based Collections<a class="headerlink" href="#proxying-to-dictionary-based-collections" title="Permalink to this headline">¶</a></h2>
<p>The association proxy can proxy to dictionary based collections as well.   SQLAlchemy
mappings usually use the <a class="reference internal" href="../collections.html#sqlalchemy.orm.collections.attribute_mapped_collection" title="sqlalchemy.orm.collections.attribute_mapped_collection"><tt class="xref py py-func docutils literal"><span class="pre">attribute_mapped_collection()</span></tt></a> collection type to
create dictionary collections, as well as the extended techniques described in
<a class="reference internal" href="../collections.html#id1"><em>Custom Dictionary-Based Collections</em></a>.</p>
<p>The association proxy adjusts its behavior when it detects the usage of a
dictionary-based collection. When new values are added to the dictionary, the
association proxy instantiates the intermediary object by passing two
arguments to the creation function instead of one, the key and the value. As
always, this creation function defaults to the constructor of the intermediary
class, and can be customized using the <tt class="docutils literal"><span class="pre">creator</span></tt> argument.</p>
<p>Below, we modify our <tt class="docutils literal"><span class="pre">UserKeyword</span></tt> example such that the <tt class="docutils literal"><span class="pre">User.user_keywords</span></tt>
collection will now be mapped using a dictionary, where the <tt class="docutils literal"><span class="pre">UserKeyword.special_key</span></tt>
argument will be used as the key for the dictionary.   We then apply a <tt class="docutils literal"><span class="pre">creator</span></tt>
argument to the <tt class="docutils literal"><span class="pre">User.keywords</span></tt> proxy so that these values are assigned appropriately
when new elements are added to the dictionary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Column</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">String</span><span class="p">,</span> <span class="n">ForeignKey</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">relationship</span><span class="p">,</span> <span class="n">backref</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.ext.associationproxy</span> <span class="kn">import</span> <span class="n">association_proxy</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.ext.declarative</span> <span class="kn">import</span> <span class="n">declarative_base</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">attribute_mapped_collection</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">User</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">name</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="mi">64</span><span class="p">))</span>

    <span class="c"># proxy to &#39;user_keywords&#39;, instantiating UserKeyword</span>
    <span class="c"># assigning the new key to &#39;special_key&#39;, values to</span>
    <span class="c"># &#39;keyword&#39;.</span>
    <span class="n">keywords</span> <span class="o">=</span> <span class="n">association_proxy</span><span class="p">(</span><span class="s">&#39;user_keywords&#39;</span><span class="p">,</span> <span class="s">&#39;keyword&#39;</span><span class="p">,</span>
                    <span class="n">creator</span><span class="o">=</span><span class="k">lambda</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span><span class="p">:</span>
                                <span class="n">UserKeyword</span><span class="p">(</span><span class="n">special_key</span><span class="o">=</span><span class="n">k</span><span class="p">,</span> <span class="n">keyword</span><span class="o">=</span><span class="n">v</span><span class="p">)</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">name</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

<span class="k">class</span> <span class="nc">UserKeyword</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user_keyword&#39;</span>
    <span class="n">user_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;user.id&#39;</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">keyword_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;keyword.id&#39;</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">special_key</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="c"># bidirectional user/user_keywords relationships, mapping</span>
    <span class="c"># user_keywords with a dictionary against &quot;special_key&quot; as key.</span>
    <span class="n">user</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">backref</span><span class="o">=</span><span class="n">backref</span><span class="p">(</span>
                    <span class="s">&quot;user_keywords&quot;</span><span class="p">,</span>
                    <span class="n">collection_class</span><span class="o">=</span><span class="n">attribute_mapped_collection</span><span class="p">(</span><span class="s">&quot;special_key&quot;</span><span class="p">),</span>
                    <span class="n">cascade</span><span class="o">=</span><span class="s">&quot;all, delete-orphan&quot;</span>
                    <span class="p">)</span>
                <span class="p">)</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Keyword&quot;</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Keyword</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;keyword&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="s">&#39;keyword&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">64</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="bp">self</span><span class="o">.</span><span class="n">keyword</span> <span class="o">=</span> <span class="n">keyword</span>

    <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&#39;Keyword(</span><span class="si">%s</span><span class="s">)&#39;</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">keyword</span><span class="p">)</span></pre></div>
</div>
<p>We illustrate the <tt class="docutils literal"><span class="pre">.keywords</span></tt> collection as a dictionary, mapping the
<tt class="docutils literal"><span class="pre">UserKeyword.string_key</span></tt> value to <tt class="docutils literal"><span class="pre">Keyword</span></tt> objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="s">&#39;log&#39;</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="p">[</span><span class="s">&#39;sk1&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">Keyword</span><span class="p">(</span><span class="s">&#39;kw1&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="p">[</span><span class="s">&#39;sk2&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">Keyword</span><span class="p">(</span><span class="s">&#39;kw2&#39;</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="p">)</span>
<span class="go">{&#39;sk1&#39;: Keyword(&#39;kw1&#39;), &#39;sk2&#39;: Keyword(&#39;kw2&#39;)}</span></pre></div>
</div>
</div>
<div class="section" id="composite-association-proxies">
<span id="composite-association-proxy"></span><h2>Composite Association Proxies<a class="headerlink" href="#composite-association-proxies" title="Permalink to this headline">¶</a></h2>
<p>Given our previous examples of proxying from relationship to scalar
attribute, proxying across an association object, and proxying dictionaries,
we can combine all three techniques together to give <tt class="docutils literal"><span class="pre">User</span></tt>
a <tt class="docutils literal"><span class="pre">keywords</span></tt> dictionary that deals strictly with the string value
of <tt class="docutils literal"><span class="pre">special_key</span></tt> mapped to the string <tt class="docutils literal"><span class="pre">keyword</span></tt>.  Both the <tt class="docutils literal"><span class="pre">UserKeyword</span></tt>
and <tt class="docutils literal"><span class="pre">Keyword</span></tt> classes are entirely concealed.  This is achieved by building
an association proxy on <tt class="docutils literal"><span class="pre">User</span></tt> that refers to an association proxy
present on <tt class="docutils literal"><span class="pre">UserKeyword</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Column</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">String</span><span class="p">,</span> <span class="n">ForeignKey</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">relationship</span><span class="p">,</span> <span class="n">backref</span>

<span class="kn">from</span> <span class="nn">sqlalchemy.ext.associationproxy</span> <span class="kn">import</span> <span class="n">association_proxy</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.ext.declarative</span> <span class="kn">import</span> <span class="n">declarative_base</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm.collections</span> <span class="kn">import</span> <span class="n">attribute_mapped_collection</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">User</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">name</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="mi">64</span><span class="p">))</span>

    <span class="c"># the same &#39;user_keywords&#39;-&gt;&#39;keyword&#39; proxy as in</span>
    <span class="c"># the basic dictionary example</span>
    <span class="n">keywords</span> <span class="o">=</span> <span class="n">association_proxy</span><span class="p">(</span>
                <span class="s">&#39;user_keywords&#39;</span><span class="p">,</span>
                <span class="s">&#39;keyword&#39;</span><span class="p">,</span>
                <span class="n">creator</span><span class="o">=</span><span class="k">lambda</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span><span class="p">:</span>
                            <span class="n">UserKeyword</span><span class="p">(</span><span class="n">special_key</span><span class="o">=</span><span class="n">k</span><span class="p">,</span> <span class="n">keyword</span><span class="o">=</span><span class="n">v</span><span class="p">)</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">name</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

<span class="k">class</span> <span class="nc">UserKeyword</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user_keyword&#39;</span>
    <span class="n">user_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;user.id&#39;</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">keyword_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s">&#39;keyword.id&#39;</span><span class="p">),</span>
                                                    <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">special_key</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">user</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">backref</span><span class="o">=</span><span class="n">backref</span><span class="p">(</span>
            <span class="s">&quot;user_keywords&quot;</span><span class="p">,</span>
            <span class="n">collection_class</span><span class="o">=</span><span class="n">attribute_mapped_collection</span><span class="p">(</span><span class="s">&quot;special_key&quot;</span><span class="p">),</span>
            <span class="n">cascade</span><span class="o">=</span><span class="s">&quot;all, delete-orphan&quot;</span>
            <span class="p">)</span>
        <span class="p">)</span>

    <span class="c"># the relationship to Keyword is now called</span>
    <span class="c"># &#39;kw&#39;</span>
    <span class="n">kw</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s">&quot;Keyword&quot;</span><span class="p">)</span>

    <span class="c"># &#39;keyword&#39; is changed to be a proxy to the</span>
    <span class="c"># &#39;keyword&#39; attribute of &#39;Keyword&#39;</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">association_proxy</span><span class="p">(</span><span class="s">&#39;kw&#39;</span><span class="p">,</span> <span class="s">&#39;keyword&#39;</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Keyword</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;keyword&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
    <span class="n">keyword</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="s">&#39;keyword&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">64</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="bp">self</span><span class="o">.</span><span class="n">keyword</span> <span class="o">=</span> <span class="n">keyword</span></pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">User.keywords</span></tt> is now a dictionary of string to string, where
<tt class="docutils literal"><span class="pre">UserKeyword</span></tt> and <tt class="docutils literal"><span class="pre">Keyword</span></tt> objects are created and removed for us
transparently using the association proxy. In the example below, we illustrate
usage of the assignment operator, also appropriately handled by the
association proxy, to apply a dictionary value to the collection at once:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="s">&#39;log&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span> <span class="o">=</span> <span class="p">{</span>
<span class="gp">... </span>    <span class="s">&#39;sk1&#39;</span><span class="p">:</span><span class="s">&#39;kw1&#39;</span><span class="p">,</span>
<span class="gp">... </span>    <span class="s">&#39;sk2&#39;</span><span class="p">:</span><span class="s">&#39;kw2&#39;</span>
<span class="gp">... </span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="p">)</span>
<span class="go">{&#39;sk1&#39;: &#39;kw1&#39;, &#39;sk2&#39;: &#39;kw2&#39;}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="p">[</span><span class="s">&#39;sk3&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s">&#39;kw3&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">del</span> <span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="p">[</span><span class="s">&#39;sk2&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">keywords</span><span class="p">)</span>
<span class="go">{&#39;sk1&#39;: &#39;kw1&#39;, &#39;sk3&#39;: &#39;kw3&#39;}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c"># illustrate un-proxied usage</span>
<span class="gp">... </span><span class="k">print</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">user_keywords</span><span class="p">[</span><span class="s">&#39;sk3&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">kw</span><span class="p">)</span>
<span class="go">&lt;__main__.Keyword object at 0x12ceb90&gt;</span></pre></div>
</div>
<p>One caveat with our example above is that because <tt class="docutils literal"><span class="pre">Keyword</span></tt> objects are created
for each dictionary set operation, the example fails to maintain uniqueness for
the <tt class="docutils literal"><span class="pre">Keyword</span></tt> objects on their string name, which is a typical requirement for
a tagging scenario such as this one.  For this use case the recipe
<a class="reference external" href="http://www.sqlalchemy.org/trac/wiki/UsageRecipes/UniqueObject">UniqueObject</a>, or
a comparable creational strategy, is
recommended, which will apply a &#8220;lookup first, then create&#8221; strategy to the constructor
of the <tt class="docutils literal"><span class="pre">Keyword</span></tt> class, so that an already existing <tt class="docutils literal"><span class="pre">Keyword</span></tt> is returned if the
given name is already present.</p>
</div>
<div class="section" id="querying-with-association-proxies">
<h2>Querying with Association Proxies<a class="headerlink" href="#querying-with-association-proxies" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a> features simple SQL construction capabilities
which relate down to the underlying <a class="reference internal" href="../relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a> in use as well
as the target attribute.  For example, the <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.any" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.any"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.any()</span></tt></a>
and <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.has" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.has"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.has()</span></tt></a> operations are available, and will produce
a &#8220;nested&#8221; EXISTS clause, such as in our basic association object example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</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">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">any</span><span class="p">(</span><span class="n">keyword</span><span class="o">=</span><span class="s">&#39;jek&#39;</span><span class="p">)))</span>
<span class="go">SELECT user.id AS user_id, user.name AS user_name</span>
<span class="go">FROM user</span>
<span class="go">WHERE EXISTS (SELECT 1</span>
<span class="go">FROM user_keyword</span>
<span class="go">WHERE user.id = user_keyword.user_id AND (EXISTS (SELECT 1</span>
<span class="go">FROM keyword</span>
<span class="go">WHERE keyword.id = user_keyword.keyword_id AND keyword.keyword = :keyword_1)))</span></pre></div>
</div>
<p>For a proxy to a scalar attribute, <tt class="docutils literal"><span class="pre">__eq__()</span></tt> is supported:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">UserKeyword</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">UserKeyword</span><span class="o">.</span><span class="n">keyword</span> <span class="o">==</span> <span class="s">&#39;jek&#39;</span><span class="p">))</span>
<span class="go">SELECT user_keyword.*</span>
<span class="go">FROM user_keyword</span>
<span class="go">WHERE EXISTS (SELECT 1</span>
<span class="go">    FROM keyword</span>
<span class="go">    WHERE keyword.id = user_keyword.keyword_id AND keyword.keyword = :keyword_1)</span></pre></div>
</div>
<p>and <tt class="docutils literal"><span class="pre">.contains()</span></tt> is available for a proxy to a scalar collection:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</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">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">contains</span><span class="p">(</span><span class="s">&#39;jek&#39;</span><span class="p">)))</span>
<span class="go">SELECT user.*</span>
<span class="go">FROM user</span>
<span class="go">WHERE EXISTS (SELECT 1</span>
<span class="go">FROM userkeywords, keyword</span>
<span class="go">WHERE user.id = userkeywords.user_id</span>
<span class="go">    AND keyword.id = userkeywords.keyword_id</span>
<span class="go">    AND keyword.keyword = :keyword_1)</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a> can be used with <a class="reference internal" href="../query.html#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><tt class="xref py py-meth docutils literal"><span class="pre">Query.join()</span></tt></a> somewhat manually
using the <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.attr"><tt class="xref py py-attr docutils literal"><span class="pre">attr</span></tt></a> attribute in a star-args context:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">q</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">join</span><span class="p">(</span><span class="o">*</span><span class="n">User</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">attr</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.7.3: </span><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.attr"><tt class="xref py py-attr docutils literal"><span class="pre">attr</span></tt></a> attribute in a star-args context.</p>
</div>
<p><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.attr"><tt class="xref py py-attr docutils literal"><span class="pre">attr</span></tt></a> is composed of <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.local_attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.local_attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.local_attr</span></tt></a> and <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.remote_attr</span></tt></a>,
which are just synonyms for the actual proxied attributes, and can also
be used for querying:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">uka</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">UserKeyword</span><span class="p">)</span>
<span class="n">ka</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">Keyword</span><span class="p">)</span>
<span class="n">q</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">join</span><span class="p">(</span><span class="n">uka</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">local_attr</span><span class="p">)</span><span class="o">.</span>\
        <span class="n">join</span><span class="p">(</span><span class="n">ka</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">keywords</span><span class="o">.</span><span class="n">remote_attr</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.7.3: </span><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.local_attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.local_attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.local_attr</span></tt></a> and <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.remote_attr</span></tt></a>,
synonyms for the actual proxied attributes, and usable for querying.</p>
</div>
</div>
<div class="section" id="api-documentation">
<h2>API Documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="sqlalchemy.ext.associationproxy.association_proxy">
<tt class="descclassname">sqlalchemy.ext.associationproxy.</tt><tt class="descname">association_proxy</tt><big>(</big><em>target_collection</em>, <em>attr</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.ext.associationproxy.association_proxy" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a Python property implementing a view of a target
attribute which references an attribute on members of the
target.</p>
<p>The returned value is an instance of <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a>.</p>
<p>Implements a Python property representing a relationship as a collection
of simpler values, or a scalar value.  The proxied property will mimic
the collection type of the target (list, dict or set), or, in the case of
a one to one relationship, a simple scalar value.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.ext.associationproxy.association_proxy.params.target_collection"></span><strong>target_collection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.association_proxy.params.target_collection">¶</a> &#8211; Name of the attribute we&#8217;ll proxy to.
This attribute is typically mapped by
<a class="reference internal" href="../relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a> to link to a target collection, but
can also be a many-to-one or non-scalar relationship.</li>
<li><span class="target" id="sqlalchemy.ext.associationproxy.association_proxy.params.attr"></span><strong>attr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.association_proxy.params.attr">¶</a> &#8211; <p>Attribute on the associated instance or instances we&#8217;ll
proxy for.</p>
<p>For example, given a target collection of [obj1, obj2], a list created
by this proxy property would look like [getattr(obj1, <em>attr</em>),
getattr(obj2, <em>attr</em>)]</p>
<p>If the relationship is one-to-one or otherwise uselist=False, then
simply: getattr(obj, <em>attr</em>)</p>
</li>
<li><span class="target" id="sqlalchemy.ext.associationproxy.association_proxy.params.creator"></span><strong>creator</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.association_proxy.params.creator">¶</a> &#8211; <p>optional.</p>
<p>When new items are added to this proxied collection, new instances of
the class collected by the target collection will be created.  For list
and set collections, the target class constructor will be called with
the &#8216;value&#8217; for the new instance.  For dict types, two arguments are
passed: key and value.</p>
<p>If you want to construct instances differently, supply a <em>creator</em>
function that takes arguments as above and returns instances.</p>
<p>For scalar relationships, creator() will be called if the target is None.
If the target is present, set operations are proxied to setattr() on the
associated object.</p>
<p>If you have an associated object with multiple attributes, you may set
up multiple association proxies mapping to different attributes.  See
the unit tests for examples, and for examples of how creator() functions
can be used to construct the scalar relationship on-demand in this
situation.</p>
</li>
<li><span class="target" id="sqlalchemy.ext.associationproxy.association_proxy.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.association_proxy.params.**kw">¶</a> &#8211; Passes along any other keyword arguments to
<a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy">
<em class="property">class </em><tt class="descclassname">sqlalchemy.ext.associationproxy.</tt><tt class="descname">AssociationProxy</tt><big>(</big><em>target_collection</em>, <em>attr</em>, <em>creator=None</em>, <em>getset_factory=None</em>, <em>proxy_factory=None</em>, <em>proxy_bulk_set=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.orm.base._InspectionAttr</span></tt></p>
<p>A descriptor that presents a read/write view of an object attribute.</p>
<dl class="method">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.__init__">
<tt class="descname">__init__</tt><big>(</big><em>target_collection</em>, <em>attr</em>, <em>creator=None</em>, <em>getset_factory=None</em>, <em>proxy_factory=None</em>, <em>proxy_bulk_set=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a>.</p>
<p>The <a class="reference internal" href="#sqlalchemy.ext.associationproxy.association_proxy" title="sqlalchemy.ext.associationproxy.association_proxy"><tt class="xref py py-func docutils literal"><span class="pre">association_proxy()</span></tt></a> function is provided as the usual
entrypoint here, though <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a> can be instantiated
and/or subclassed directly.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.ext.associationproxy.AssociationProxy.params.target_collection"></span><strong>target_collection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.params.target_collection">¶</a> &#8211; Name of the collection we&#8217;ll proxy to,
usually created with <a class="reference internal" href="../relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a>.</li>
<li><span class="target" id="sqlalchemy.ext.associationproxy.AssociationProxy.params.attr"></span><strong>attr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.params.attr">¶</a> &#8211; Attribute on the collected instances we&#8217;ll proxy
for.  For example, given a target collection of [obj1, obj2], a
list created by this proxy property would look like
[getattr(obj1, attr), getattr(obj2, attr)]</li>
<li><span class="target" id="sqlalchemy.ext.associationproxy.AssociationProxy.params.creator"></span><strong>creator</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.params.creator">¶</a> &#8211; <p>Optional. When new items are added to this proxied
collection, new instances of the class collected by the target
collection will be created.  For list and set collections, the
target class constructor will be called with the &#8216;value&#8217; for the
new instance.  For dict types, two arguments are passed:
key and value.</p>
<p>If you want to construct instances differently, supply a &#8216;creator&#8217;
function that takes arguments as above and returns instances.</p>
</li>
<li><span class="target" id="sqlalchemy.ext.associationproxy.AssociationProxy.params.getset_factory"></span><strong>getset_factory</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.params.getset_factory">¶</a> &#8211; <p>Optional.  Proxied attribute access is
automatically handled by routines that get and set values based on
the <cite>attr</cite> argument for this proxy.</p>
<p>If you would like to customize this behavior, you may supply a
<cite>getset_factory</cite> callable that produces a tuple of <cite>getter</cite> and
<cite>setter</cite> functions.  The factory is called with two arguments, the
abstract type of the underlying collection and this proxy instance.</p>
</li>
<li><span class="target" id="sqlalchemy.ext.associationproxy.AssociationProxy.params.proxy_factory"></span><strong>proxy_factory</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.params.proxy_factory">¶</a> &#8211; Optional.  The type of collection to emulate is
determined by sniffing the target collection.  If your collection
type can&#8217;t be determined by duck typing or you&#8217;d like to use a
different collection implementation, you may supply a factory
function to produce those collections.  Only applicable to
non-scalar relationships.</li>
<li><span class="target" id="sqlalchemy.ext.associationproxy.AssociationProxy.params.proxy_bulk_set"></span><strong>proxy_bulk_set</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.params.proxy_bulk_set">¶</a> &#8211; Optional, use with proxy_factory.  See
the _set() method for details.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.any">
<tt class="descname">any</tt><big>(</big><em>criterion=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.any" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a proxied &#8216;any&#8217; expression using EXISTS.</p>
<p>This expression will be a composed product
using the <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.any" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.any"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.any()</span></tt></a>
and/or <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.has" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.has"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.has()</span></tt></a>
operators of the underlying proxied attributes.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.attr">
<tt class="descname">attr</tt><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.attr" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a tuple of <tt class="docutils literal"><span class="pre">(local_attr,</span> <span class="pre">remote_attr)</span></tt>.</p>
<p>This attribute is convenient when specifying a join
using <a class="reference internal" href="../query.html#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><tt class="xref py py-meth docutils literal"><span class="pre">Query.join()</span></tt></a> across two relationships:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Parent</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="o">*</span><span class="n">Parent</span><span class="o">.</span><span class="n">proxied</span><span class="o">.</span><span class="n">attr</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.7.3.</span></p>
</div>
<p>See also:</p>
<p><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.local_attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.local_attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.local_attr</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.remote_attr</span></tt></a></p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.contains">
<tt class="descname">contains</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a proxied &#8216;contains&#8217; expression using EXISTS.</p>
<p>This expression will be a composed product
using the <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.any" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.any"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.any()</span></tt></a>
, <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.has" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.has"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.has()</span></tt></a>,
and/or <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.contains" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.contains"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.contains()</span></tt></a>
operators of the underlying proxied attributes.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.extension_type">
<tt class="descname">extension_type</tt><em class="property"> = symbol('ASSOCIATION_PROXY')</em><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.extension_type" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="method">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.has">
<tt class="descname">has</tt><big>(</big><em>criterion=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.has" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a proxied &#8216;has&#8217; expression using EXISTS.</p>
<p>This expression will be a composed product
using the <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.any" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.any"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.any()</span></tt></a>
and/or <a class="reference internal" href="../internals.html#sqlalchemy.orm.properties.RelationshipProperty.Comparator.has" title="sqlalchemy.orm.properties.RelationshipProperty.Comparator.has"><tt class="xref py py-meth docutils literal"><span class="pre">RelationshipProperty.Comparator.has()</span></tt></a>
operators of the underlying proxied attributes.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.is_attribute">
<tt class="descname">is_attribute</tt><em class="property"> = False</em><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.is_attribute" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.local_attr">
<tt class="descname">local_attr</tt><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.local_attr" title="Permalink to this definition">¶</a></dt>
<dd><p>The &#8216;local&#8217; <a class="reference internal" href="../internals.html#sqlalchemy.orm.interfaces.MapperProperty" title="sqlalchemy.orm.interfaces.MapperProperty"><tt class="xref py py-class docutils literal"><span class="pre">MapperProperty</span></tt></a> referenced by this
<a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a>.</p>
<div class="versionadded">
<p><span>New in version 0.7.3.</span></p>
</div>
<p>See also:</p>
<p><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.attr</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.remote_attr</span></tt></a></p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr">
<tt class="descname">remote_attr</tt><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.remote_attr" title="Permalink to this definition">¶</a></dt>
<dd><p>The &#8216;remote&#8217; <a class="reference internal" href="../internals.html#sqlalchemy.orm.interfaces.MapperProperty" title="sqlalchemy.orm.interfaces.MapperProperty"><tt class="xref py py-class docutils literal"><span class="pre">MapperProperty</span></tt></a> referenced by this
<a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a>.</p>
<div class="versionadded">
<p><span>New in version 0.7.3.</span></p>
</div>
<p>See also:</p>
<p><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.attr</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy.local_attr" title="sqlalchemy.ext.associationproxy.AssociationProxy.local_attr"><tt class="xref py py-attr docutils literal"><span class="pre">AssociationProxy.local_attr</span></tt></a></p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.scalar">
<tt class="descname">scalar</tt><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.scalar" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <tt class="docutils literal"><span class="pre">True</span></tt> if this <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a> proxies a scalar
relationship on the local side.</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.ext.associationproxy.AssociationProxy.target_class">
<tt class="descname">target_class</tt><a class="headerlink" href="#sqlalchemy.ext.associationproxy.AssociationProxy.target_class" title="Permalink to this definition">¶</a></dt>
<dd><p>The intermediary class handled by this <a class="reference internal" href="#sqlalchemy.ext.associationproxy.AssociationProxy" title="sqlalchemy.ext.associationproxy.AssociationProxy"><tt class="xref py py-class docutils literal"><span class="pre">AssociationProxy</span></tt></a>.</p>
<p>Intercepted append/set/assignment events will result
in the generation of new instances of this class.</p>
</dd></dl>

</dd></dl>

<dl class="data">
<dt id="sqlalchemy.ext.associationproxy.ASSOCIATION_PROXY">
<tt class="descclassname">sqlalchemy.ext.associationproxy.</tt><tt class="descname">ASSOCIATION_PROXY</tt><em class="property"> = symbol('ASSOCIATION_PROXY')</em><a class="headerlink" href="#sqlalchemy.ext.associationproxy.ASSOCIATION_PROXY" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</div>
</div>

    </div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
        Previous:
        <a href="index.html" title="previous chapter">ORM Extensions</a>
        Next:
        <a href="automap.html" title="next chapter">Automap</a>

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

</div>

        
    </body>
</html>