1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
orderinglist
— SQLAlchemy 0.6.3 Documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/docs.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '0.6.3',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<script type="text/javascript" src="../../_static/init.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="top" title="SQLAlchemy 0.6.3 Documentation" href="../../index.html" />
<link rel="up" title="sqlalchemy.ext" href="index.html" />
<link rel="next" title="serializer" href="serializer.html" />
<link rel="prev" title="associationproxy" href="associationproxy.html" />
</head>
<body>
<h1>SQLAlchemy 0.6.3 Documentation</h1>
<div id="search">
Search:
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" size="18" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<div class="versionheader">
Version: <span class="versionnum">0.6.3</span> Last Updated: 07/15/2010 12:35:47
</div>
<div class="clearboth"></div>
<div class="topnav">
<div id="pagecontrol">
<a href="../index.html">API Reference</a>
|
<a href="../../genindex.html">Index</a>
<div class="sourcelink">(<a href="../../_sources/reference/ext/orderinglist.txt">view source)</div>
</div>
<div class="navbanner">
<a class="totoc" href="../../index.html">Table of Contents</a>
» <a href="../index.html" title="API Reference">API Reference</a>
» <a href="index.html" title="sqlalchemy.ext">sqlalchemy.ext</a>
»
orderinglist
<div class="prevnext">
Previous:
<a href="associationproxy.html" title="previous chapter">associationproxy</a>
Next:
<a href="serializer.html" title="next chapter">serializer</a>
</div>
<h2>
orderinglist
</h2>
</div>
<ul>
<li><a class="reference internal" href="#">orderinglist</a><ul>
<li><a class="reference internal" href="#api-reference">API Reference</a></li>
</ul>
</li>
</ul>
<div class="clearboth"></div>
</div>
<div class="document">
<div class="body">
<div class="section" id="module-sqlalchemy.ext.orderinglist">
<span id="orderinglist"></span><h1>orderinglist<a class="headerlink" href="#module-sqlalchemy.ext.orderinglist" title="Permalink to this headline">¶</a></h1>
<p>A custom list that manages index/position information for its children.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">author:</th><td class="field-body">Jason Kirtland</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">orderinglist</span></tt> is a helper for mutable ordered relationships. It will intercept
list operations performed on a relationship collection and automatically
synchronize changes in list position with an attribute on the related objects.
(See <a class="reference internal" href="../../mappers.html#advdatamapping-entitycollections"><em>Alternate Collection Implementations</em></a> for more information on the general pattern.)</p>
<p>Example: Two tables that store slides in a presentation. Each slide
has a number of bullet points, displayed in order by the ‘position’
column on the bullets table. These bullets can be inserted and re-ordered
by your end users, and you need to update the ‘position’ column of all
affected rows when changes are made.</p>
<div class="highlight-python+sql"><div class="highlight"><pre><span class="n">slides_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'Slides'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'id'</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">Column</span><span class="p">(</span><span class="s">'name'</span><span class="p">,</span> <span class="n">String</span><span class="p">))</span>
<span class="n">bullets_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'Bullets'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'id'</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">Column</span><span class="p">(</span><span class="s">'slide_id'</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">'Slides.id'</span><span class="p">)),</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'position'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s">'text'</span><span class="p">,</span> <span class="n">String</span><span class="p">))</span>
<span class="k">class</span> <span class="nc">Slide</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">Bullet</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">pass</span>
<span class="n">mapper</span><span class="p">(</span><span class="n">Slide</span><span class="p">,</span> <span class="n">slides_table</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="p">{</span>
<span class="s">'bullets'</span><span class="p">:</span> <span class="n">relationship</span><span class="p">(</span><span class="n">Bullet</span><span class="p">,</span> <span class="n">order_by</span><span class="o">=</span><span class="p">[</span><span class="n">bullets_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">position</span><span class="p">])</span>
<span class="p">})</span>
<span class="n">mapper</span><span class="p">(</span><span class="n">Bullet</span><span class="p">,</span> <span class="n">bullets_table</span><span class="p">)</span></pre></div>
</div>
<p>The standard relationship mapping will produce a list-like attribute on each Slide
containing all related Bullets, but coping with changes in ordering is totally
your responsibility. If you insert a Bullet into that list, there is no
magic- it won’t have a position attribute unless you assign it it one, and
you’ll need to manually renumber all the subsequent Bullets in the list to
accommodate the insert.</p>
<p>An <tt class="docutils literal"><span class="pre">orderinglist</span></tt> can automate this and manage the ‘position’ attribute on all
related bullets for you.</p>
<div class="highlight-python+sql"><div class="highlight"><pre><span class="n">mapper</span><span class="p">(</span><span class="n">Slide</span><span class="p">,</span> <span class="n">slides_table</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="p">{</span>
<span class="s">'bullets'</span><span class="p">:</span> <span class="n">relationship</span><span class="p">(</span><span class="n">Bullet</span><span class="p">,</span>
<span class="n">collection_class</span><span class="o">=</span><span class="n">ordering_list</span><span class="p">(</span><span class="s">'position'</span><span class="p">),</span>
<span class="n">order_by</span><span class="o">=</span><span class="p">[</span><span class="n">bullets_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">position</span><span class="p">])</span>
<span class="p">})</span>
<span class="n">mapper</span><span class="p">(</span><span class="n">Bullet</span><span class="p">,</span> <span class="n">bullets_table</span><span class="p">)</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">Slide</span><span class="p">()</span>
<span class="n">s</span><span class="o">.</span><span class="n">bullets</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Bullet</span><span class="p">())</span>
<span class="n">s</span><span class="o">.</span><span class="n">bullets</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Bullet</span><span class="p">())</span>
<span class="n">s</span><span class="o">.</span><span class="n">bullets</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">position</span>
<span class="o">>>></span> <span class="mi">1</span>
<span class="n">s</span><span class="o">.</span><span class="n">bullets</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">Bullet</span><span class="p">())</span>
<span class="n">s</span><span class="o">.</span><span class="n">bullets</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">.</span><span class="n">position</span>
<span class="o">>>></span> <span class="mi">2</span></pre></div>
</div>
<p>Use the <tt class="docutils literal"><span class="pre">ordering_list</span></tt> function to set up the <tt class="docutils literal"><span class="pre">collection_class</span></tt> on relationships
(as in the mapper example above). This implementation depends on the list
starting in the proper order, so be SURE to put an order_by on your relationship.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last"><tt class="docutils literal"><span class="pre">ordering_list</span></tt> only provides limited functionality when a primary
key column or unique column is the target of the sort. Since changing the order of
entries often means that two rows must trade values, this is not possible when
the value is constrained by a primary key or unique constraint, since one of the rows
would temporarily have to point to a third available value so that the other row
could take its old value. <tt class="docutils literal"><span class="pre">ordering_list</span></tt> doesn’t do any of this for you,
nor does SQLAlchemy itself.</p>
</div>
<p><tt class="docutils literal"><span class="pre">ordering_list</span></tt> takes the name of the related object’s ordering attribute as
an argument. By default, the zero-based integer index of the object’s
position in the <tt class="docutils literal"><span class="pre">ordering_list</span></tt> is synchronized with the ordering attribute:
index 0 will get position 0, index 1 position 1, etc. To start numbering at 1
or some other integer, provide <tt class="docutils literal"><span class="pre">count_from=1</span></tt>.</p>
<p>Ordering values are not limited to incrementing integers. Almost any scheme
can implemented by supplying a custom <tt class="docutils literal"><span class="pre">ordering_func</span></tt> that maps a Python list
index to any value you require.</p>
<div class="section" id="api-reference">
<h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="sqlalchemy.ext.orderinglist.ordering_list">
<tt class="descclassname">sqlalchemy.ext.orderinglist.</tt><tt class="descname">ordering_list</tt><big>(</big><em>attr</em>, <em>count_from=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.ext.orderinglist.ordering_list" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares an OrderingList factory for use in mapper definitions.</p>
<p>Returns an object suitable for use as an argument to a Mapper relationship’s
<tt class="docutils literal"><span class="pre">collection_class</span></tt> option. Arguments are:</p>
<dl class="docutils">
<dt>attr</dt>
<dd>Name of the mapped attribute to use for storage and retrieval of
ordering information</dd>
<dt>count_from (optional)</dt>
<dd>Set up an integer-based ordering, starting at <tt class="docutils literal"><span class="pre">count_from</span></tt>. For
example, <tt class="docutils literal"><span class="pre">ordering_list('pos',</span> <span class="pre">count_from=1)</span></tt> would create a 1-based
list in SQL, storing the value in the ‘pos’ column. Ignored if
<tt class="docutils literal"><span class="pre">ordering_func</span></tt> is supplied.</dd>
</dl>
<p>Passes along any keyword arguments to <tt class="docutils literal"><span class="pre">OrderingList</span></tt> constructor.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="bottomnav">
<div class="prevnext">
Previous:
<a href="associationproxy.html" title="previous chapter">associationproxy</a>
Next:
<a href="serializer.html" title="next chapter">serializer</a>
</div>
<div class="doc_copyright">
© Copyright 2007, 2008, 2009, 2010, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0b2+.
</div>
</div>
</body>
</html>
|
