← Back to branch summary

~ubuntu-branches/debian/sid/sqlalchemy/sid

« back to all changes in this revision

Viewing changes to doc/orm/events.html

  • Committer: Package Import Robot
  • Author(s): Piotr Ożarowski
  • Date: 2012-01-29 23:29:50 UTC
  • mfrom: (1.4.18)
  • Revision ID: package-import@ubuntu.com-20120129232950-1mw4zn2xy2o51ua5
Tags: 0.7.5-1
* New upstream release
  - minumum required python-sphinx version bumped to 1.1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/orm/events.html
6
6
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7
7
        
8
8
        <title>
 
9
            
 
10
    
9
11
                ORM Events
10
 
             &mdash; SQLAlchemy 0.7 Documentation</title>
 
12
             &mdash; 
 
13
    SQLAlchemy 0.7 Documentation
 
14
 
 
15
        </title>
11
16
        
12
17
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
13
18
    <link rel="stylesheet" href="../_static/docs.css" type="text/css" />
15
20
    <script type="text/javascript">
16
21
      var DOCUMENTATION_OPTIONS = {
17
22
          URL_ROOT:    '../',
18
 
          VERSION:     '0.7.4',
 
23
          VERSION:     '0.7.5',
19
24
          COLLAPSE_MODINDEX: false,
20
25
          FILE_SUFFIX: '.html'
21
26
      };
41
46
 
42
47
 
43
48
 
 
49
 
 
50
 
 
51
 
 
52
 
44
53
<div id="docs-container">
45
54
 
46
55
 
58
67
    </div>
59
68
 
60
69
    <div id="docs-version-header">
61
 
        Release: <span class="version-num">0.7.4</span> | Release Date: December 9, 2011
 
70
        Release: <span class="version-num">0.7.5</span> | Release Date: January 28, 2012
62
71
 
63
72
 
64
73
    </div>
125
134
    <a href="extensions/index.html" title="next chapter">ORM Extensions</a>
126
135
    </p>
127
136
 
 
137
 
128
138
    <h4>Quick Search</h4>
129
139
    <p>
130
140
    <form class="search" action="../search.html" method="get">
180
190
<col class="field-name" />
181
191
<col class="field-body" />
182
192
<tbody valign="top">
183
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
193
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
184
194
<li><strong>active_history=False</strong> &#8211; When True, indicates that the
185
195
&#8220;set&#8221; event would like to receive the &#8220;old&#8221; value being
186
196
replaced unconditionally, even if this requires firing off
214
224
<col class="field-name" />
215
225
<col class="field-body" />
216
226
<tbody valign="top">
217
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
227
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
218
228
<li><strong>target</strong> &#8211; the object instance receiving the event.
219
229
If the listener is registered with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
220
230
be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> object.</li>
227
237
</ul>
228
238
</td>
229
239
</tr>
230
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">if the event was registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>,
 
240
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">if the event was registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>,
231
241
the given value, or a new effective value, should be returned.</p>
232
242
</td>
233
243
</tr>
243
253
<col class="field-name" />
244
254
<col class="field-body" />
245
255
<tbody valign="top">
246
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
256
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
247
257
<li><strong>target</strong> &#8211; the object instance receiving the event.
248
258
If the listener is registered with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
249
259
be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> object.</li>
253
263
</ul>
254
264
</td>
255
265
</tr>
256
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is defined for this event.</p>
 
266
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is defined for this event.</p>
257
267
</td>
258
268
</tr>
259
269
</tbody>
268
278
<col class="field-name" />
269
279
<col class="field-body" />
270
280
<tbody valign="top">
271
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
281
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
272
282
<li><strong>target</strong> &#8211; the object instance receiving the event.
273
283
If the listener is registered with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
274
284
be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> object.</li>
287
297
</ul>
288
298
</td>
289
299
</tr>
290
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">if the event was registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>,
 
300
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">if the event was registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>,
291
301
the given value, or a new effective value, should be returned.</p>
292
302
</td>
293
303
</tr>
349
359
<col class="field-name" />
350
360
<col class="field-body" />
351
361
<tbody valign="top">
352
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
362
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
353
363
<li><strong>propagate=False</strong> &#8211; When True, the event listener should 
354
364
be applied to all inheriting mappers as well as the 
355
365
mapper which is the target of this listener.</li>
402
412
<p>The event is often called for a batch of objects of the
403
413
same class after their DELETE statements have been emitted at
404
414
once in a previous step.</p>
405
 
<p>Handlers should <strong>not</strong> alter mapped attributes on the objects
406
 
just flushed or on other objects of the same class, nor
407
 
should any other ORM-based operation such as <tt class="xref py py-class docutils literal"><span class="pre">Session.add</span></tt>
408
 
take place here.   Attribute changes on objects that were
409
 
already flushed will be discarded, and changes to the flush
410
 
plan will also not take place.  Use <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a>
411
 
to change the flush plan on flush.</p>
 
415
<div class="admonition warning">
 
416
<p class="first admonition-title">Warning</p>
 
417
<p>Mapper-level flush events are designed to operate <strong>on attributes
 
418
local to the immediate object being handled  
 
419
and via SQL operations with the given</strong> <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> <strong>only.</strong>
 
420
Handlers here should <strong>not</strong> make alterations to the state of 
 
421
the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> overall, and in general should not
 
422
affect any <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> -mapped attributes, as 
 
423
session cascade rules will not function properly, nor is it
 
424
always known if the related class has already been handled.  
 
425
Operations that <strong>are not supported in mapper events</strong> include:</p>
 
426
<ul class="simple">
 
427
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a></li>
 
428
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a></li>
 
429
<li>Mapped collection append, add, remove, delete, discard, etc.</li>
 
430
<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal"><span class="pre">someobject.related</span> <span class="pre">=</span> <span class="pre">someotherobject</span></tt></li>
 
431
</ul>
 
432
<p>Operations which manipulate the state of the object
 
433
relative to other objects are better handled:</p>
 
434
<ul class="last simple">
 
435
<li>In the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of the mapped object itself, or another method
 
436
designed to establish some particular state.</li>
 
437
<li>In a <tt class="docutils literal"><span class="pre">&#64;validates</span></tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators"><em>Simple Validators</em></a></li>
 
438
<li>Within the  <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a> event.</li>
 
439
</ul>
 
440
</div>
412
441
<table class="docutils field-list" frame="void" rules="none">
413
442
<col class="field-name" />
414
443
<col class="field-body" />
415
444
<tbody valign="top">
416
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
445
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
417
446
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
418
447
of this event.</li>
419
448
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> being used to 
427
456
</ul>
428
457
</td>
429
458
</tr>
430
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
 
459
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
431
460
</td>
432
461
</tr>
433
462
</tbody>
451
480
which will cause batches of instances to be broken up
452
481
into individual (and more poorly performing)
453
482
event-&gt;persist-&gt;event steps.</p>
454
 
<p>Handlers should <strong>not</strong> alter mapped attributes on the objects
455
 
just flushed or on other objects of the same class, nor
456
 
should any other ORM-based operation such as <tt class="xref py py-class docutils literal"><span class="pre">Session.add</span></tt>
457
 
take place here.   Attribute changes on objects that were
458
 
already flushed will be discarded, and changes to the flush
459
 
plan will also not take place.  Use <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a>
460
 
to change the flush plan on flush.</p>
 
483
<div class="admonition warning">
 
484
<p class="first admonition-title">Warning</p>
 
485
<p>Mapper-level flush events are designed to operate <strong>on attributes
 
486
local to the immediate object being handled  
 
487
and via SQL operations with the given</strong> <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> <strong>only.</strong>
 
488
Handlers here should <strong>not</strong> make alterations to the state of 
 
489
the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> overall, and in general should not
 
490
affect any <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> -mapped attributes, as 
 
491
session cascade rules will not function properly, nor is it
 
492
always known if the related class has already been handled.  
 
493
Operations that <strong>are not supported in mapper events</strong> include:</p>
 
494
<ul class="simple">
 
495
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a></li>
 
496
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a></li>
 
497
<li>Mapped collection append, add, remove, delete, discard, etc.</li>
 
498
<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal"><span class="pre">someobject.related</span> <span class="pre">=</span> <span class="pre">someotherobject</span></tt></li>
 
499
</ul>
 
500
<p>Operations which manipulate the state of the object
 
501
relative to other objects are better handled:</p>
 
502
<ul class="last simple">
 
503
<li>In the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of the mapped object itself, or another method
 
504
designed to establish some particular state.</li>
 
505
<li>In a <tt class="docutils literal"><span class="pre">&#64;validates</span></tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators"><em>Simple Validators</em></a></li>
 
506
<li>Within the  <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a> event.</li>
 
507
</ul>
 
508
</div>
461
509
<table class="docutils field-list" frame="void" rules="none">
462
510
<col class="field-name" />
463
511
<col class="field-body" />
464
512
<tbody valign="top">
465
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
513
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
466
514
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
467
515
of this event.</li>
468
516
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> being used to 
476
524
</ul>
477
525
</td>
478
526
</tr>
479
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
 
527
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
480
528
</td>
481
529
</tr>
482
530
</tbody>
516
564
batches of instances to be broken up into individual
517
565
(and more poorly performing) event-&gt;persist-&gt;event
518
566
steps.</p>
519
 
<p>Handlers should <strong>not</strong> alter mapped attributes on the objects
520
 
just flushed or on other objects of the same class, nor
521
 
should any other ORM-based operation such as <tt class="xref py py-class docutils literal"><span class="pre">Session.add</span></tt>
522
 
take place here.   Attribute changes on objects that were
523
 
already flushed will be discarded, and changes to the flush
524
 
plan will also not take place.  Use <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a>
525
 
to change the flush plan on flush.</p>
 
567
<div class="admonition warning">
 
568
<p class="first admonition-title">Warning</p>
 
569
<p>Mapper-level flush events are designed to operate <strong>on attributes
 
570
local to the immediate object being handled  
 
571
and via SQL operations with the given</strong> <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> <strong>only.</strong>
 
572
Handlers here should <strong>not</strong> make alterations to the state of 
 
573
the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> overall, and in general should not
 
574
affect any <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> -mapped attributes, as 
 
575
session cascade rules will not function properly, nor is it
 
576
always known if the related class has already been handled.  
 
577
Operations that <strong>are not supported in mapper events</strong> include:</p>
 
578
<ul class="simple">
 
579
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a></li>
 
580
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a></li>
 
581
<li>Mapped collection append, add, remove, delete, discard, etc.</li>
 
582
<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal"><span class="pre">someobject.related</span> <span class="pre">=</span> <span class="pre">someotherobject</span></tt></li>
 
583
</ul>
 
584
<p>Operations which manipulate the state of the object
 
585
relative to other objects are better handled:</p>
 
586
<ul class="last simple">
 
587
<li>In the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of the mapped object itself, or another method
 
588
designed to establish some particular state.</li>
 
589
<li>In a <tt class="docutils literal"><span class="pre">&#64;validates</span></tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators"><em>Simple Validators</em></a></li>
 
590
<li>Within the  <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a> event.</li>
 
591
</ul>
 
592
</div>
526
593
<table class="docutils field-list" frame="void" rules="none">
527
594
<col class="field-name" />
528
595
<col class="field-body" />
529
596
<tbody valign="top">
530
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
597
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
531
598
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
532
599
of this event.</li>
533
600
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> being used to 
541
608
</ul>
542
609
</td>
543
610
</tr>
544
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
 
611
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
545
612
</td>
546
613
</tr>
547
614
</tbody>
559
626
<col class="field-name" />
560
627
<col class="field-body" />
561
628
<tbody valign="top">
562
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
629
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
563
630
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
564
631
of this event.</li>
565
632
<li><strong>context</strong> &#8211; the <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal"><span class="pre">QueryContext</span></tt></a>, which includes
579
646
</ul>
580
647
</td>
581
648
</tr>
582
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">If this method is registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>,
 
649
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">If this method is registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>,
583
650
a return value of <tt class="docutils literal"><span class="pre">EXT_STOP</span></tt> will prevent the instance
584
651
from being appended to the given result list, whereas a 
585
652
return value of <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt> will result in the default
601
668
<p>The event is often called for a batch of objects of the
602
669
same class before their DELETE statements are emitted at
603
670
once in a later step.</p>
604
 
<p>Handlers should <strong>not</strong> modify any attributes which are
605
 
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>, nor should they attempt
606
 
to make any modifications to the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> in
607
 
this hook (including <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a>, 
608
 
<a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a>, etc.) - such changes will not
609
 
take effect. For overall changes to the &#8220;flush plan&#8221;,
610
 
use <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a>.</p>
 
671
<div class="admonition warning">
 
672
<p class="first admonition-title">Warning</p>
 
673
<p>Mapper-level flush events are designed to operate <strong>on attributes
 
674
local to the immediate object being handled  
 
675
and via SQL operations with the given</strong> <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> <strong>only.</strong>
 
676
Handlers here should <strong>not</strong> make alterations to the state of 
 
677
the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> overall, and in general should not
 
678
affect any <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> -mapped attributes, as 
 
679
session cascade rules will not function properly, nor is it
 
680
always known if the related class has already been handled.  
 
681
Operations that <strong>are not supported in mapper events</strong> include:</p>
 
682
<ul class="simple">
 
683
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a></li>
 
684
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a></li>
 
685
<li>Mapped collection append, add, remove, delete, discard, etc.</li>
 
686
<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal"><span class="pre">someobject.related</span> <span class="pre">=</span> <span class="pre">someotherobject</span></tt></li>
 
687
</ul>
 
688
<p>Operations which manipulate the state of the object
 
689
relative to other objects are better handled:</p>
 
690
<ul class="last simple">
 
691
<li>In the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of the mapped object itself, or another method
 
692
designed to establish some particular state.</li>
 
693
<li>In a <tt class="docutils literal"><span class="pre">&#64;validates</span></tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators"><em>Simple Validators</em></a></li>
 
694
<li>Within the  <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a> event.</li>
 
695
</ul>
 
696
</div>
611
697
<table class="docutils field-list" frame="void" rules="none">
612
698
<col class="field-name" />
613
699
<col class="field-body" />
614
700
<tbody valign="top">
615
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
701
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
616
702
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
617
703
of this event.</li>
618
704
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> being used to 
626
712
</ul>
627
713
</td>
628
714
</tr>
629
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
 
715
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
630
716
</td>
631
717
</tr>
632
718
</tbody>
650
736
batches of instances to be broken up into individual
651
737
(and more poorly performing) event-&gt;persist-&gt;event
652
738
steps.</p>
653
 
<p>Handlers should <strong>not</strong> modify any attributes which are
654
 
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>, nor should they attempt
655
 
to make any modifications to the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> in
656
 
this hook (including <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a>, 
657
 
<a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a>, etc.) - such changes will not
658
 
take effect. For overall changes to the &#8220;flush plan&#8221;,
659
 
use <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a>.</p>
 
739
<div class="admonition warning">
 
740
<p class="first admonition-title">Warning</p>
 
741
<p>Mapper-level flush events are designed to operate <strong>on attributes
 
742
local to the immediate object being handled  
 
743
and via SQL operations with the given</strong> <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> <strong>only.</strong>
 
744
Handlers here should <strong>not</strong> make alterations to the state of 
 
745
the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> overall, and in general should not
 
746
affect any <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> -mapped attributes, as 
 
747
session cascade rules will not function properly, nor is it
 
748
always known if the related class has already been handled.  
 
749
Operations that <strong>are not supported in mapper events</strong> include:</p>
 
750
<ul class="simple">
 
751
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a></li>
 
752
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a></li>
 
753
<li>Mapped collection append, add, remove, delete, discard, etc.</li>
 
754
<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal"><span class="pre">someobject.related</span> <span class="pre">=</span> <span class="pre">someotherobject</span></tt></li>
 
755
</ul>
 
756
<p>Operations which manipulate the state of the object
 
757
relative to other objects are better handled:</p>
 
758
<ul class="last simple">
 
759
<li>In the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of the mapped object itself, or another method
 
760
designed to establish some particular state.</li>
 
761
<li>In a <tt class="docutils literal"><span class="pre">&#64;validates</span></tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators"><em>Simple Validators</em></a></li>
 
762
<li>Within the  <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a> event.</li>
 
763
</ul>
 
764
</div>
660
765
<table class="docutils field-list" frame="void" rules="none">
661
766
<col class="field-name" />
662
767
<col class="field-body" />
663
768
<tbody valign="top">
664
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
769
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
665
770
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
666
771
of this event.</li>
667
772
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> being used to 
675
780
</ul>
676
781
</td>
677
782
</tr>
678
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
 
783
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
679
784
</td>
680
785
</tr>
681
786
</tbody>
716
821
batches of instances to be broken up into individual
717
822
(and more poorly performing) event-&gt;persist-&gt;event
718
823
steps.</p>
719
 
<p>Handlers should <strong>not</strong> modify any attributes which are
720
 
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>, nor should they attempt
721
 
to make any modifications to the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> in
722
 
this hook (including <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a>, 
723
 
<a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a>, etc.) - such changes will not
724
 
take effect. For overall changes to the &#8220;flush plan&#8221;,
725
 
use <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a>.</p>
 
824
<div class="admonition warning">
 
825
<p class="first admonition-title">Warning</p>
 
826
<p>Mapper-level flush events are designed to operate <strong>on attributes
 
827
local to the immediate object being handled  
 
828
and via SQL operations with the given</strong> <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> <strong>only.</strong>
 
829
Handlers here should <strong>not</strong> make alterations to the state of 
 
830
the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a> overall, and in general should not
 
831
affect any <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> -mapped attributes, as 
 
832
session cascade rules will not function properly, nor is it
 
833
always known if the related class has already been handled.  
 
834
Operations that <strong>are not supported in mapper events</strong> include:</p>
 
835
<ul class="simple">
 
836
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal"><span class="pre">Session.add()</span></tt></a></li>
 
837
<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Session.delete()</span></tt></a></li>
 
838
<li>Mapped collection append, add, remove, delete, discard, etc.</li>
 
839
<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal"><span class="pre">someobject.related</span> <span class="pre">=</span> <span class="pre">someotherobject</span></tt></li>
 
840
</ul>
 
841
<p>Operations which manipulate the state of the object
 
842
relative to other objects are better handled:</p>
 
843
<ul class="last simple">
 
844
<li>In the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of the mapped object itself, or another method
 
845
designed to establish some particular state.</li>
 
846
<li>In a <tt class="docutils literal"><span class="pre">&#64;validates</span></tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators"><em>Simple Validators</em></a></li>
 
847
<li>Within the  <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.before_flush()</span></tt></a> event.</li>
 
848
</ul>
 
849
</div>
726
850
<table class="docutils field-list" frame="void" rules="none">
727
851
<col class="field-name" />
728
852
<col class="field-body" />
729
853
<tbody valign="top">
730
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
854
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
731
855
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
732
856
of this event.</li>
733
857
<li><strong>connection</strong> &#8211; the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> being used to 
741
865
</ul>
742
866
</td>
743
867
</tr>
744
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
 
868
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">No return value is supported by this event.</p>
745
869
</td>
746
870
</tr>
747
871
</tbody>
760
884
<col class="field-name" />
761
885
<col class="field-body" />
762
886
<tbody valign="top">
763
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
887
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
764
888
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
765
889
of this event.</li>
766
890
<li><strong>context</strong> &#8211; the <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal"><span class="pre">QueryContext</span></tt></a>, which includes
773
897
</ul>
774
898
</td>
775
899
</tr>
776
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">When configured with <tt class="docutils literal"><span class="pre">retval=True</span></tt>, the return value
 
900
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">When configured with <tt class="docutils literal"><span class="pre">retval=True</span></tt>, the return value
777
901
should be a newly created instance of the mapped class, 
778
902
or <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt> indicating that default object construction
779
903
should take place.</p>
796
920
<col class="field-name" />
797
921
<col class="field-body" />
798
922
<tbody valign="top">
799
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
923
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
800
924
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
801
925
of this event.</li>
802
926
<li><strong>class_</strong> &#8211; the mapped class.</li>
817
941
<col class="field-name" />
818
942
<col class="field-body" />
819
943
<tbody valign="top">
820
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
944
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
821
945
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
822
946
of this event.</li>
823
947
<li><strong>class_</strong> &#8211; the mapped class.</li>
845
969
<col class="field-name" />
846
970
<col class="field-body" />
847
971
<tbody valign="top">
848
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
972
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
849
973
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
850
974
of this event.</li>
851
975
<li><strong>context</strong> &#8211; the <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal"><span class="pre">QueryContext</span></tt></a>, which includes
861
985
</ul>
862
986
</td>
863
987
</tr>
864
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">When configured with <tt class="docutils literal"><span class="pre">retval=True</span></tt>, a return
 
988
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">When configured with <tt class="docutils literal"><span class="pre">retval=True</span></tt>, a return
865
989
value of <tt class="docutils literal"><span class="pre">EXT_STOP</span></tt> will bypass instance population by
866
990
the mapper. A value of <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt> indicates that
867
991
default instance population should take place.</p>
888
1012
<col class="field-name" />
889
1013
<col class="field-body" />
890
1014
<tbody valign="top">
891
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 
1015
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
892
1016
<li><strong>mapper</strong> &#8211; the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal"><span class="pre">Mapper</span></tt></a> which is the target
893
1017
of this event.</li>
894
1018
<li><strong>context</strong> &#8211; the <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal"><span class="pre">QueryContext</span></tt></a>, which includes
900
1024
</ul>
901
1025
</td>
902
1026
</tr>
903
 
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">When configured with <tt class="docutils literal"><span class="pre">retval=True</span></tt>, the function
 
1027
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">When configured with <tt class="docutils literal"><span class="pre">retval=True</span></tt>, the function
904
1028
should return a dictionary-like row object, or <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt>,
905
1029
indicating the original row should be used.</p>
906
1030
</td>
948
1072
<col class="field-name" />
949
1073
<col class="field-body" />
950
1074
<tbody valign="top">
951
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1075
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
952
1076
<li><strong>propagate=False</strong> &#8211; When True, the event listener should 
953
1077
be applied to all inheriting mappers as well as the 
954
1078
mapper which is the target of this listener.</li>
972
1096
<col class="field-name" />
973
1097
<col class="field-body" />
974
1098
<tbody valign="top">
975
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1099
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
976
1100
<li><strong>target</strong> &#8211; the mapped instance.  If 
977
1101
the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will 
978
1102
instead be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> state-management
1029
1153
<col class="field-name" />
1030
1154
<col class="field-body" />
1031
1155
<tbody valign="top">
1032
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1156
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1033
1157
<li><strong>target</strong> &#8211; the mapped instance.  If 
1034
1158
the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will 
1035
1159
instead be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> state-management
1036
1160
object associated with the instance.</li>
1037
1161
<li><strong>context</strong> &#8211; the <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal"><span class="pre">QueryContext</span></tt></a> corresponding to the
1038
1162
current <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> in progress.  This argument may be
1039
 
<tt class="xref docutils literal"><span class="pre">None</span></tt> if the load does not correspond to a <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a>,
 
1163
<tt class="docutils literal"><span class="pre">None</span></tt> if the load does not correspond to a <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a>,
1040
1164
such as during <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-meth docutils literal"><span class="pre">Session.merge()</span></tt></a>.</li>
1041
1165
</ul>
1042
1166
</td>
1054
1178
<col class="field-name" />
1055
1179
<col class="field-body" />
1056
1180
<tbody valign="top">
1057
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1181
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1058
1182
<li><strong>target</strong> &#8211; the mapped instance.  If 
1059
1183
the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will 
1060
1184
instead be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> state-management
1078
1202
<col class="field-name" />
1079
1203
<col class="field-body" />
1080
1204
<tbody valign="top">
1081
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1205
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1082
1206
<li><strong>target</strong> &#8211; the mapped instance.  If 
1083
1207
the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will 
1084
1208
instead be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> state-management
1105
1229
<col class="field-name" />
1106
1230
<col class="field-body" />
1107
1231
<tbody valign="top">
1108
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>target</strong> &#8211; the mapped instance.  If 
 
1232
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>target</strong> &#8211; the mapped instance.  If 
1109
1233
the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will 
1110
1234
instead be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> state-management
1111
1235
object associated with the instance.</td>
1123
1247
<col class="field-name" />
1124
1248
<col class="field-body" />
1125
1249
<tbody valign="top">
1126
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1250
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1127
1251
<li><strong>target</strong> &#8211; the mapped instance.  If 
1128
1252
the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will 
1129
1253
instead be the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal"><span class="pre">InstanceState</span></tt></a> state-management
1179
1303
<col class="field-name" />
1180
1304
<col class="field-body" />
1181
1305
<tbody valign="top">
1182
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1306
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1183
1307
<li><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</li>
1184
1308
<li><strong>transaction</strong> &#8211; The <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal"><span class="pre">SessionTransaction</span></tt></a>.</li>
1185
1309
<li><strong>connection</strong> &#8211; The <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object 
1200
1324
<col class="field-name" />
1201
1325
<col class="field-body" />
1202
1326
<tbody valign="top">
1203
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1327
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1204
1328
<li><strong>query</strong> &#8211; the <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> object that this update operation was
1205
1329
called upon.</li>
1206
1330
<li><strong>query_context</strong> &#8211; The <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal"><span class="pre">QueryContext</span></tt></a> object, corresponding
1223
1347
<col class="field-name" />
1224
1348
<col class="field-body" />
1225
1349
<tbody valign="top">
1226
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1350
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1227
1351
<li><strong>query</strong> &#8211; the <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> object that this update operation was
1228
1352
called upon.</li>
1229
1353
<li><strong>query_context</strong> &#8211; The <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal"><span class="pre">QueryContext</span></tt></a> object, corresponding
1247
1371
<col class="field-name" />
1248
1372
<col class="field-body" />
1249
1373
<tbody valign="top">
1250
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</td>
 
1374
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</td>
1251
1375
</tr>
1252
1376
</tbody>
1253
1377
</table>
1265
1389
<col class="field-name" />
1266
1390
<col class="field-body" />
1267
1391
<tbody valign="top">
1268
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1392
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1269
1393
<li><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</li>
1270
1394
<li><strong>flush_context</strong> &#8211; Internal <tt class="xref py py-class docutils literal"><span class="pre">UOWTransaction</span></tt> object
1271
1395
which handles the details of the flush.</li>
1289
1413
<col class="field-name" />
1290
1414
<col class="field-body" />
1291
1415
<tbody valign="top">
1292
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1416
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1293
1417
<li><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</li>
1294
1418
<li><strong>flush_context</strong> &#8211; Internal <tt class="xref py py-class docutils literal"><span class="pre">UOWTransaction</span></tt> object
1295
1419
which handles the details of the flush.</li>
1318
1442
<col class="field-name" />
1319
1443
<col class="field-body" />
1320
1444
<tbody valign="top">
1321
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</td>
 
1445
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</td>
1322
1446
</tr>
1323
1447
</tbody>
1324
1448
</table>
1345
1469
<col class="field-name" />
1346
1470
<col class="field-body" />
1347
1471
<tbody valign="top">
1348
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1472
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1349
1473
<li><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</li>
1350
1474
<li><strong>previous_transaction</strong> &#8211; The <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal"><span class="pre">SessionTransaction</span></tt></a> transactional
1351
1475
marker object which was just closed.   The current <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal"><span class="pre">SessionTransaction</span></tt></a>
1369
1493
<col class="field-name" />
1370
1494
<col class="field-body" />
1371
1495
<tbody valign="top">
1372
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</td>
 
1496
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</td>
1373
1497
</tr>
1374
1498
</tbody>
1375
1499
</table>
1383
1507
<col class="field-name" />
1384
1508
<col class="field-body" />
1385
1509
<tbody valign="top">
1386
 
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
 
1510
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1387
1511
<li><strong>session</strong> &#8211; The target <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>.</li>
1388
1512
<li><strong>flush_context</strong> &#8211; Internal <tt class="xref py py-class docutils literal"><span class="pre">UOWTransaction</span></tt> object
1389
1513
which handles the details of the flush.</li>
1390
 
<li><strong>instances</strong> &#8211; Usually <tt class="xref docutils literal"><span class="pre">None</span></tt>, this is the collection of
 
1514
<li><strong>instances</strong> &#8211; Usually <tt class="docutils literal"><span class="pre">None</span></tt>, this is the collection of
1391
1515
objects which can be passed to the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><tt class="xref py py-meth docutils literal"><span class="pre">Session.flush()</span></tt></a> method
1392
1516
(note this usage is deprecated).</li>
1393
1517
</ul>
1544
1668
 
1545
1669
</div>
1546
1670
 
1547
 
 
1548
 
    <div id="docs-bottom-navigation" class="docs-navigation-links">
1549
 
            Previous:
1550
 
            <a href="loading.html" title="previous chapter">Relationship Loading Techniques</a>
1551
 
            Next:
1552
 
            <a href="extensions/index.html" title="next chapter">ORM Extensions</a>
1553
 
 
1554
 
        <div id="docs-copyright">
1555
 
            &copy; <a href="../copyright.html">Copyright</a> 2007-2011, the SQLAlchemy authors and contributors.
1556
 
            Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
1557
 
        </div>
 
1671
<div id="docs-bottom-navigation" class="docs-navigation-links">
 
1672
        Previous:
 
1673
        <a href="loading.html" title="previous chapter">Relationship Loading Techniques</a>
 
1674
        Next:
 
1675
        <a href="extensions/index.html" title="next chapter">ORM Extensions</a>
 
1676
 
 
1677
    <div id="docs-copyright">
 
1678
        &copy; <a href="../copyright.html">Copyright</a> 2007-2012, the SQLAlchemy authors and contributors.
 
1679
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.2.
1558
1680
    </div>
1559
 
 
1560
 
 
1561
 
</div>
1562
 
 
 
1681
</div>
 
1682
 
 
1683
</div>
 
1684
 
 
1685
        
1563
1686
    </body>
1564
1687
</html>
1565
1688
 
1566
1689
 
1567