← Back to branch summary

~ubuntu-branches/debian/jessie/sqlalchemy/jessie

« back to all changes in this revision

Viewing changes to doc/orm/collections.html

  • Committer: Package Import Robot
  • Author(s): Piotr Ożarowski, Jakub Wilk, Piotr Ożarowski
  • Date: 2013-07-06 20:53:52 UTC
  • mfrom: (1.4.23) (16.1.17 experimental)
  • Revision ID: package-import@ubuntu.com-20130706205352-ryppl1eto3illd79
Tags: 0.8.2-1
[ Jakub Wilk ]
* Use canonical URIs for Vcs-* fields.

[ Piotr Ożarowski ]
* New upstream release
* Upload to unstable
* Build depend on python3-all instead of -dev, extensions are not built for
  Python 3.X 

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/orm/collections.html
10
10
    
11
11
                Collection Configuration and Techniques
12
12
             — 
13
 
    SQLAlchemy 0.7 Documentation
 
13
    SQLAlchemy 0.8 Documentation
14
14
 
15
15
        </title>
16
16
        
20
20
    <script type="text/javascript">
21
21
      var DOCUMENTATION_OPTIONS = {
22
22
          URL_ROOT:    '../',
23
 
          VERSION:     '0.7.9',
 
23
          VERSION:     '0.8.2',
24
24
          COLLAPSE_MODINDEX: false,
25
25
          FILE_SUFFIX: '.html'
26
26
      };
32
32
    <link rel="index" title="Index" href="../genindex.html" />
33
33
    <link rel="search" title="Search" href="../search.html" />
34
34
        <link rel="copyright" title="Copyright" href="../copyright.html" />
35
 
    <link rel="top" title="SQLAlchemy 0.7 Documentation" href="../index.html" />
 
35
    <link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
36
36
        <link rel="up" title="SQLAlchemy ORM" href="index.html" />
37
37
        <link rel="next" title="Mapping Class Inheritance Hierarchies" href="inheritance.html" />
38
38
        <link rel="prev" title="Relationship Configuration" href="relationships.html" />
55
55
 
56
56
 
57
57
<div id="docs-header">
58
 
    <h1>SQLAlchemy 0.7 Documentation</h1>
 
58
    <h1>SQLAlchemy 0.8 Documentation</h1>
59
59
 
60
60
    <div id="docs-search">
61
61
    Search:
67
67
    </div>
68
68
 
69
69
    <div id="docs-version-header">
70
 
        Release: <span class="version-num">0.7.9</span> | Release Date: October 1, 2012
 
70
        Release: <span class="version-num">0.8.2</span> | Release Date: July 3, 2013
71
71
 
72
72
 
73
73
    </div>
93
93
    </div>
94
94
 
95
95
    <div id="docs-navigation-banner">
96
 
        <a href="../index.html">SQLAlchemy 0.7 Documentation</a>
 
96
        <a href="../index.html">SQLAlchemy 0.8 Documentation</a>
97
97
                » <a href="index.html" title="SQLAlchemy ORM">SQLAlchemy ORM</a>
98
98
        » 
99
99
                Collection Configuration and Techniques
447
447
<dt id="sqlalchemy.orm.collections.column_mapped_collection">
448
448
<tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">column_mapped_collection</tt><big>(</big><em>mapping_spec</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.column_mapped_collection" title="Permalink to this definition">¶</a></dt>
449
449
<dd><p>A dictionary-based collection type with column-based keying.</p>
450
 
<p>Returns a <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> factory with a keying function generated
451
 
from mapping_spec, which may be a Column or a sequence of Columns.</p>
 
450
<p>Returns a <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> factory with a keying function
 
451
generated from mapping_spec, which may be a Column or a sequence
 
452
of Columns.</p>
452
453
<p>The key value must be immutable for the lifetime of the object.  You
453
454
can not, for example, map on foreign key values if those key values will
454
455
change during the session, i.e. from None to a database-assigned integer
459
460
<dt id="sqlalchemy.orm.collections.mapped_collection">
460
461
<tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">mapped_collection</tt><big>(</big><em>keyfunc</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.mapped_collection" title="Permalink to this definition">¶</a></dt>
461
462
<dd><p>A dictionary-based collection type with arbitrary keying.</p>
462
 
<p>Returns a <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> factory with a keying function generated
463
 
from keyfunc, a callable that takes an entity and returns a key value.</p>
 
463
<p>Returns a <a class="reference internal" href="#sqlalchemy.orm.collections.MappedCollection" title="sqlalchemy.orm.collections.MappedCollection"><tt class="xref py py-class docutils literal"><span class="pre">MappedCollection</span></tt></a> factory with a keying function
 
464
generated from keyfunc, a callable that takes an entity and returns a
 
465
key value.</p>
464
466
<p>The key value must be immutable for the lifetime of the object.  You
465
467
can not, for example, map on foreign key values if those key values will
466
468
change during the session, i.e. from None to a database-assigned integer
602
604
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">collection</tt><a class="headerlink" href="#sqlalchemy.orm.collections.collection" title="Permalink to this definition">¶</a></dt>
603
605
<dd><p>Decorators for entity collection classes.</p>
604
606
<p>The decorators fall into two groups: annotations and interception recipes.</p>
605
 
<p>The annotating decorators (appender, remover, iterator,
606
 
internally_instrumented, link) indicate the method&#8217;s purpose and take no
 
607
<p>The annotating decorators (appender, remover, iterator, linker, converter,
 
608
internally_instrumented) indicate the method&#8217;s purpose and take no
607
609
arguments.  They are not written with parens:</p>
608
610
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.appender</span>
609
611
<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>
701
703
<dt id="sqlalchemy.orm.collections.collection.internally_instrumented">
702
704
<em class="property">static </em><tt class="descname">internally_instrumented</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.internally_instrumented" title="Permalink to this definition">¶</a></dt>
703
705
<dd><p>Tag the method as instrumented.</p>
704
 
<p>This tag will prevent any decoration from being applied to the method.
705
 
Use this if you are orchestrating your own calls to <a class="reference internal" href="#sqlalchemy.orm.collections.collection_adapter" title="sqlalchemy.orm.collections.collection_adapter"><tt class="xref py py-func docutils literal"><span class="pre">collection_adapter()</span></tt></a>
706
 
in one of the basic SQLAlchemy interface methods, or to prevent
707
 
an automatic ABC method decoration from wrapping your implementation:</p>
 
706
<p>This tag will prevent any decoration from being applied to the
 
707
method. Use this if you are orchestrating your own calls to
 
708
<a class="reference internal" href="#sqlalchemy.orm.collections.collection_adapter" title="sqlalchemy.orm.collections.collection_adapter"><tt class="xref py py-func docutils literal"><span class="pre">collection_adapter()</span></tt></a> in one of the basic SQLAlchemy
 
709
interface methods, or to prevent an automatic ABC method
 
710
decoration from wrapping your implementation:</p>
708
711
<div class="highlight-python"><div class="highlight"><pre><span class="c"># normally an &#39;extend&#39; method on a list-like class would be</span>
709
712
<span class="c"># automatically intercepted and re-implemented in terms of</span>
710
713
<span class="c"># SQLAlchemy events and append().  your implementation will</span>
728
731
<dl class="staticmethod">
729
732
<dt id="sqlalchemy.orm.collections.collection.link">
730
733
<em class="property">static </em><tt class="descname">link</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.link" title="Permalink to this definition">¶</a></dt>
731
 
<dd><p>Tag the method as a the &#8220;linked to attribute&#8221; event handler.</p>
 
734
<dd><p>deprecated; synonym for <a class="reference internal" href="#sqlalchemy.orm.collections.collection.linker" title="sqlalchemy.orm.collections.collection.linker"><tt class="xref py py-meth docutils literal"><span class="pre">collection.linker()</span></tt></a>.</p>
 
735
</dd></dl>
 
736
 
 
737
<dl class="staticmethod">
 
738
<dt id="sqlalchemy.orm.collections.collection.linker">
 
739
<em class="property">static </em><tt class="descname">linker</tt><big>(</big><em>fn</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.collection.linker" title="Permalink to this definition">¶</a></dt>
 
740
<dd><p>Tag the method as a &#8220;linked to attribute&#8221; event handler.</p>
732
741
<p>This optional event handler will be called when the collection class
733
742
is linked to or unlinked from the InstrumentedAttribute.  It is
734
743
invoked immediately after the &#8216;_sa_adapter&#8217; property is set on
870
879
<dt id="sqlalchemy.orm.collections.MappedCollection">
871
880
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">MappedCollection</tt><big>(</big><em>keyfunc</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection" title="Permalink to this definition">¶</a></dt>
872
881
<dd><p>A basic dictionary-based collection class.</p>
873
 
<p>Extends dict with the minimal bag semantics that collection classes require.
874
 
<tt class="docutils literal"><span class="pre">set</span></tt> and <tt class="docutils literal"><span class="pre">remove</span></tt> are implemented in terms of a keying function: any
875
 
callable that takes an object and returns an object for use as a dictionary
876
 
key.</p>
 
882
<p>Extends dict with the minimal bag semantics that collection
 
883
classes require. <tt class="docutils literal"><span class="pre">set</span></tt> and <tt class="docutils literal"><span class="pre">remove</span></tt> are implemented in terms
 
884
of a keying function: any callable that takes an object and
 
885
returns an object for use as a dictionary key.</p>
877
886
<dl class="method">
878
887
<dt id="sqlalchemy.orm.collections.MappedCollection.__init__">
879
888
<tt class="descname">__init__</tt><big>(</big><em>keyfunc</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.__init__" title="Permalink to this definition">¶</a></dt>
924
933
 
925
934
<dl class="method">
926
935
<dt id="sqlalchemy.orm.collections.MappedCollection.update">
927
 
<tt class="descname">update</tt><big>(</big><em>E</em>, <em>**F</em><big>)</big> &rarr; None.  Update D from dict/iterable E and F.<a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.update" title="Permalink to this definition">¶</a></dt>
928
 
<dd><p>If E has a .keys() method, does:     for k in E: D[k] = E[k]
929
 
If E lacks .keys() method, does:     for (k, v) in E: D[k] = v
 
936
<tt class="descname">update</tt><big>(</big><span class="optional">[</span><em>E</em><span class="optional">]</span>, <em>**F</em><big>)</big> &rarr; None.  Update D from dict/iterable E and F.<a class="headerlink" href="#sqlalchemy.orm.collections.MappedCollection.update" title="Permalink to this definition">¶</a></dt>
 
937
<dd><p>If E present and has a .keys() method, does:     for k in E: D[k] = E[k]
 
938
If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
930
939
In either case, this is followed by: for k in F: D[k] = F[k]</p>
931
940
</dd></dl>
932
941
 
969
978
<tbody valign="top">
970
979
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
971
980
<li><strong>values</strong> &#8211; An iterable of collection member instances</li>
972
 
<li><strong>existing_adapter</strong> &#8211; A <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><tt class="xref py py-class docutils literal"><span class="pre">CollectionAdapter</span></tt></a> of instances to be replaced</li>
973
 
<li><strong>new_adapter</strong> &#8211; An empty <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><tt class="xref py py-class docutils literal"><span class="pre">CollectionAdapter</span></tt></a> to load with <tt class="docutils literal"><span class="pre">values</span></tt></li>
 
981
<li><strong>existing_adapter</strong> &#8211; A <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><tt class="xref py py-class docutils literal"><span class="pre">CollectionAdapter</span></tt></a> of
 
982
instances to be replaced</li>
 
983
<li><strong>new_adapter</strong> &#8211; An empty <a class="reference internal" href="#sqlalchemy.orm.collections.CollectionAdapter" title="sqlalchemy.orm.collections.CollectionAdapter"><tt class="xref py py-class docutils literal"><span class="pre">CollectionAdapter</span></tt></a>
 
984
to load with <tt class="docutils literal"><span class="pre">values</span></tt></li>
974
985
</ul>
975
986
</td>
976
987
</tr>
983
994
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.collections.</tt><tt class="descname">collection</tt></dt>
984
995
<dd><p>Decorators for entity collection classes.</p>
985
996
<p>The decorators fall into two groups: annotations and interception recipes.</p>
986
 
<p>The annotating decorators (appender, remover, iterator,
987
 
internally_instrumented, link) indicate the method&#8217;s purpose and take no
 
997
<p>The annotating decorators (appender, remover, iterator, linker, converter,
 
998
internally_instrumented) indicate the method&#8217;s purpose and take no
988
999
arguments.  They are not written with parens:</p>
989
1000
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@collection.appender</span>
990
1001
<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>
1061
1072
        <a href="inheritance.html" title="next chapter">Mapping Class Inheritance Hierarchies</a>
1062
1073
 
1063
1074
    <div id="docs-copyright">
1064
 
        &copy; <a href="../copyright.html">Copyright</a> 2007-2012, the SQLAlchemy authors and contributors.
 
1075
        &copy; <a href="../copyright.html">Copyright</a> 2007-2013, the SQLAlchemy authors and contributors.
1065
1076
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
1066
1077
    </div>
1067
1078
</div>