~ubuntu-branches/debian/sid/sqlalchemy/sid : contents of doc/orm/events.html at revision 29

~ubuntu-branches/debian/sid/sqlalchemy/sid : (revision 29)

1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	2	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	3
	4	<html>
	5	<head>
	6	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	7
	8	<title>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	9
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	10
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	11	ORM Events
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	12	—
	13	SQLAlchemy 0.7 Documentation
	14
	15	</title>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	16
	17	<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
	18	<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
	19
	20	<script type="text/javascript">
	21	var DOCUMENTATION_OPTIONS = {
	22	URL_ROOT: '../',
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	23	VERSION: '0.7.5',
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	24	COLLAPSE_MODINDEX: false,
	25	FILE_SUFFIX: '.html'
	26	};
	27	</script>
	28	<script type="text/javascript" src="../_static/jquery.js"></script>
	29	<script type="text/javascript" src="../_static/underscore.js"></script>
	30	<script type="text/javascript" src="../_static/doctools.js"></script>
	31	<script type="text/javascript" src="../_static/init.js"></script>
	32	<link rel="index" title="Index" href="../genindex.html" />
	33	<link rel="search" title="Search" href="../search.html" />
	34	<link rel="copyright" title="Copyright" href="../copyright.html" />
1.4.15 by Piotr Ożarowski Import upstream version 0.7.2	35	<link rel="top" title="SQLAlchemy 0.7 Documentation" href="../index.html" />
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	36	<link rel="up" title="SQLAlchemy ORM" href="index.html" />
	37	<link rel="next" title="ORM Extensions" href="extensions/index.html" />
	38	<link rel="prev" title="Relationship Loading Techniques" href="loading.html" />
	39
	40	</head>
	41	<body>
	42
	43
	44
	45
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	46
	47
	48
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	49
	50
	51
	52
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	53	<div id="docs-container">
	54
	55
	56
	57	<div id="docs-header">
	58	<h1>SQLAlchemy 0.7 Documentation</h1>
	59
	60	<div id="docs-search">
	61	Search:
	62	<form class="search" action="../search.html" method="get">
	63	<input type="text" name="q" size="18" /> <input type="submit" value="Search" />
	64	<input type="hidden" name="check_keywords" value="yes" />
	65	<input type="hidden" name="area" value="default" />
	66	</form>
	67	</div>
	68
	69	<div id="docs-version-header">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	70	Release: <span class="version-num">0.7.5</span> \| Release Date: January 28, 2012
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	71
	72
	73	</div>
	74
	75	</div>
	76
	77	<div id="docs-top-navigation">
	78	<div id="docs-top-page-control" class="docs-navigation-links">
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	79	<ul>
	80	<li>Prev:
	81	<a href="loading.html" title="previous chapter">Relationship Loading Techniques</a>
	82	</li>
	83	<li>Next:
	84	<a href="extensions/index.html" title="next chapter">ORM Extensions</a>
	85	</li>
	86
	87	<li>
	88	<a href="../contents.html">Table of Contents</a> \|
	89	<a href="../genindex.html">Index</a>
	90	\| <a href="../_sources/orm/events.txt">view source
	91	</li>
	92	</ul>
	93	</div>
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	94
	95	<div id="docs-navigation-banner">
	96	<a href="../index.html">SQLAlchemy 0.7 Documentation</a>
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	97	» <a href="index.html" title="SQLAlchemy ORM">SQLAlchemy ORM</a>
	98	»
	99	ORM Events
	100
	101
	102	<h2>
	103
	104	ORM Events
	105
	106	</h2>
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	107	</div>
	108
	109	</div>
	110
	111	<div id="docs-body-container">
	112
	113	<div id="docs-sidebar">
	114	<h3><a href="../index.html">Table of Contents</a></h3>
	115	<ul>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	116	<li><a class="reference internal" href="#">ORM Events</a><ul>
	117	<li><a class="reference internal" href="#attribute-events">Attribute Events</a></li>
	118	<li><a class="reference internal" href="#mapper-events">Mapper Events</a></li>
	119	<li><a class="reference internal" href="#instance-events">Instance Events</a></li>
	120	<li><a class="reference internal" href="#session-events">Session Events</a></li>
	121	<li><a class="reference internal" href="#instrumentation-events">Instrumentation Events</a></li>
	122	<li><a class="reference internal" href="#alternate-class-instrumentation">Alternate Class Instrumentation</a></li>
	123	</ul>
	124	</li>
	125	</ul>
	126
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	127
	128	<h4>Previous Topic</h4>
	129	<p>
	130	<a href="loading.html" title="previous chapter">Relationship Loading Techniques</a>
	131	</p>
	132	<h4>Next Topic</h4>
	133	<p>
	134	<a href="extensions/index.html" title="next chapter">ORM Extensions</a>
	135	</p>
	136
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	137
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	138	<h4>Quick Search</h4>
	139	<p>
	140	<form class="search" action="../search.html" method="get">
	141	<input type="text" name="q" size="18" /> <input type="submit" value="Search" />
	142	<input type="hidden" name="check_keywords" value="yes" />
	143	<input type="hidden" name="area" value="default" />
	144	</form>
	145	</p>
	146
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	147	</div>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	148
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	149	<div id="docs-body" class="withsidebar" >
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	150
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	151	<div class="section" id="orm-events">
	152	<span id="orm-event-toplevel"></span><h1>ORM Events<a class="headerlink" href="#orm-events" title="Permalink to this headline">¶</a></h1>
	153	<p>The ORM includes a wide variety of hooks available for subscription. The event
	154	system in 0.7 is all new and supercedes the previous system of “extension” classes.
	155	For an introduction to the event API, see <a class="reference internal" href="../core/event.html"><em>Events</em></a>. Non-ORM events
	156	such as those regarding connections and low-level statement execution are described in
	157	<a class="reference internal" href="../core/events.html"><em>Core Events</em></a>.</p>
	158	<div class="section" id="attribute-events">
	159	<h2>Attribute Events<a class="headerlink" href="#attribute-events" title="Permalink to this headline">¶</a></h2>
	160	<dl class="class">
	161	<dt id="sqlalchemy.orm.events.AttributeEvents">
	162	<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.events.</tt><tt class="descname">AttributeEvents</tt><a class="headerlink" href="#sqlalchemy.orm.events.AttributeEvents" title="Permalink to this definition">¶</a></dt>
	163	<dd><p>Define events for object attributes.</p>
	164	<p>These are typically defined on the class-bound descriptor for the
	165	target class.</p>
	166	<p>e.g.:</p>
	167	<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
	168
	169	<span class="k">def</span> <span class="nf">my_append_listener</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">initiator</span><span class="p">):</span>
	170	<span class="k">print</span> <span class="s">"received append event for target: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">target</span>
	171
	172	<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">MyClass</span><span class="o">.</span><span class="n">collection</span><span class="p">,</span> <span class="s">'append'</span><span class="p">,</span> <span class="n">my_append_listener</span><span class="p">)</span></pre></div>
	173	</div>
	174	<p>Listeners have the option to return a possibly modified version
	175	of the value, when the <tt class="docutils literal"><span class="pre">retval=True</span></tt> flag is passed
	176	to <a class="reference internal" href="../core/event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">listen()</span></tt></a>:</p>
	177	<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">validate_phone</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">oldvalue</span><span class="p">,</span> <span class="n">initiator</span><span class="p">):</span>
	178	<span class="s">"Strip non-numeric characters from a phone number"</span>
	179
	180	<span class="k">return</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s">r'(?![0-9])'</span><span class="p">,</span> <span class="s">''</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
	181
	182	<span class="c"># setup listener on UserContact.phone attribute, instructing</span>
	183	<span class="c"># it to use the return value</span>
	184	<span class="n">listen</span><span class="p">(</span><span class="n">UserContact</span><span class="o">.</span><span class="n">phone</span><span class="p">,</span> <span class="s">'set'</span><span class="p">,</span> <span class="n">validate_phone</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span></pre></div>
	185	</div>
	186	<p>A validation function like the above can also raise an exception
	187	such as <tt class="xref py py-class docutils literal"><span class="pre">ValueError</span></tt> to halt the operation.</p>
	188	<p>Several modifiers are available to the <a class="reference internal" href="../core/event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">listen()</span></tt></a> function.</p>
	189	<table class="docutils field-list" frame="void" rules="none">
	190	<col class="field-name" />
	191	<col class="field-body" />
	192	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	193	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	194	<li><strong>active_history=False</strong> – When True, indicates that the
	195	“set” event would like to receive the “old” value being
	196	replaced unconditionally, even if this requires firing off
	197	database loads. Note that <tt class="docutils literal"><span class="pre">active_history</span></tt> can also be
	198	set directly via <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal"><span class="pre">column_property()</span></tt></a> and
	199	<a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a>.</li>
	200	<li><strong>propagate=False</strong> – When True, the listener function will
	201	be established not just for the class attribute given, but
	202	for attributes of the same name on all current subclasses
	203	of that class, as well as all future subclasses of that
	204	class, using an additional listener that listens for
	205	instrumentation events.</li>
	206	<li><strong>raw=False</strong> – When True, the “target” argument to the
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	207	event will 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> management
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	208	object, rather than the mapped instance itself.</li>
	209	<li><strong>retval=False</strong> – when True, the user-defined event
	210	listening must return the “value” argument from the
	211	function. This gives the listening function the opportunity
	212	to change the value that is ultimately used for a “set”
	213	or “append” event.</li>
	214	</ul>
	215	</td>
	216	</tr>
	217	</tbody>
	218	</table>
	219	<dl class="method">
	220	<dt id="sqlalchemy.orm.events.AttributeEvents.append">
	221	<tt class="descname">append</tt><big>(</big><em>target</em>, <em>value</em>, <em>initiator</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.AttributeEvents.append" title="Permalink to this definition">¶</a></dt>
	222	<dd><p>Receive a collection append event.</p>
	223	<table class="docutils field-list" frame="void" rules="none">
	224	<col class="field-name" />
	225	<col class="field-body" />
	226	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	227	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	228	<li><strong>target</strong> – the object instance receiving the event.
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	229	If the listener is registered with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	231	<li><strong>value</strong> – the value being appended. If this listener
	232	is registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>, the listener
	233	function must return this value, or a new value which
	234	replaces it.</li>
	235	<li><strong>initiator</strong> – the attribute implementation object
	236	which initiated this event.</li>
	237	</ul>
	238	</td>
	239	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>,
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	241	the given value, or a new effective value, should be returned.</p>
	242	</td>
	243	</tr>
	244	</tbody>
	245	</table>
	246	</dd></dl>
	247
	248	<dl class="method">
	249	<dt id="sqlalchemy.orm.events.AttributeEvents.remove">
	250	<tt class="descname">remove</tt><big>(</big><em>target</em>, <em>value</em>, <em>initiator</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.AttributeEvents.remove" title="Permalink to this definition">¶</a></dt>
	251	<dd><p>Receive a collection remove event.</p>
	252	<table class="docutils field-list" frame="void" rules="none">
	253	<col class="field-name" />
	254	<col class="field-body" />
	255	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	256	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	257	<li><strong>target</strong> – the object instance receiving the event.
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	258	If the listener is registered with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	260	<li><strong>value</strong> – the value being removed.</li>
	261	<li><strong>initiator</strong> – the attribute implementation object
	262	which initiated this event.</li>
	263	</ul>
	264	</td>
	265	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	267	</td>
	268	</tr>
	269	</tbody>
	270	</table>
	271	</dd></dl>
	272
	273	<dl class="method">
	274	<dt id="sqlalchemy.orm.events.AttributeEvents.set">
	275	<tt class="descname">set</tt><big>(</big><em>target</em>, <em>value</em>, <em>oldvalue</em>, <em>initiator</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.AttributeEvents.set" title="Permalink to this definition">¶</a></dt>
	276	<dd><p>Receive a scalar set event.</p>
	277	<table class="docutils field-list" frame="void" rules="none">
	278	<col class="field-name" />
	279	<col class="field-body" />
	280	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	281	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	282	<li><strong>target</strong> – the object instance receiving the event.
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	283	If the listener is registered with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	285	<li><strong>value</strong> – the value being set. If this listener
	286	is registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>, the listener
	287	function must return this value, or a new value which
	288	replaces it.</li>
	289	<li><strong>oldvalue</strong> – the previous value being replaced. This
	290	may also be the symbol <tt class="docutils literal"><span class="pre">NEVER_SET</span></tt> or <tt class="docutils literal"><span class="pre">NO_VALUE</span></tt>.
	291	If the listener is registered with <tt class="docutils literal"><span class="pre">active_history=True</span></tt>,
	292	the previous value of the attribute will be loaded from
	293	the database if the existing value is currently unloaded
	294	or expired.</li>
	295	<li><strong>initiator</strong> – the attribute implementation object
	296	which initiated this event.</li>
	297	</ul>
	298	</td>
	299	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>,
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	301	the given value, or a new effective value, should be returned.</p>
	302	</td>
	303	</tr>
	304	</tbody>
	305	</table>
	306	</dd></dl>
	307
	308	</dd></dl>
	309
	310	</div>
	311	<div class="section" id="mapper-events">
	312	<h2>Mapper Events<a class="headerlink" href="#mapper-events" title="Permalink to this headline">¶</a></h2>
	313	<dl class="class">
	314	<dt id="sqlalchemy.orm.events.MapperEvents">
	315	<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.events.</tt><tt class="descname">MapperEvents</tt><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents" title="Permalink to this definition">¶</a></dt>
	316	<dd><p>Define events specific to mappings.</p>
	317	<p>e.g.:</p>
	318	<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
	319
	320	<span class="k">def</span> <span class="nf">my_before_insert_listener</span><span class="p">(</span><span class="n">mapper</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="n">target</span><span class="p">):</span>
	321	<span class="c"># execute a stored procedure upon INSERT,</span>
	322	<span class="c"># apply the value to the row to be inserted</span>
	323	<span class="n">target</span><span class="o">.</span><span class="n">calculated_value</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">scalar</span><span class="p">(</span>
	324	<span class="s">"select my_special_function(</span><span class="si">%d</span><span class="s">)"</span>
	325	<span class="o">%</span> <span class="n">target</span><span class="o">.</span><span class="n">special_number</span><span class="p">)</span>
	326
	327	<span class="c"># associate the listener function with SomeMappedClass,</span>
	328	<span class="c"># to execute during the "before_insert" hook</span>
	329	<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">SomeMappedClass</span><span class="p">,</span> <span class="s">'before_insert'</span><span class="p">,</span> <span class="n">my_before_insert_listener</span><span class="p">)</span></pre></div>
	330	</div>
	331	<p>Available targets include mapped classes, instances of
	332	<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> (i.e. returned by <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a>,
	333	<a class="reference internal" href="mapper_config.html#sqlalchemy.orm.class_mapper" title="sqlalchemy.orm.class_mapper"><tt class="xref py py-func docutils literal"><span class="pre">class_mapper()</span></tt></a> and similar), as well as the
	334	<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> class and <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a> function itself
	335	for global event reception:</p>
	336	<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">mapper</span>
	337
	338	<span class="k">def</span> <span class="nf">some_listener</span><span class="p">(</span><span class="n">mapper</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="n">target</span><span class="p">):</span>
	339	<span class="n">log</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s">"Instance </span><span class="si">%s</span><span class="s"> being inserted"</span> <span class="o">%</span> <span class="n">target</span><span class="p">)</span>
	340
	341	<span class="c"># attach to all mappers</span>
	342	<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">mapper</span><span class="p">,</span> <span class="s">'before_insert'</span><span class="p">,</span> <span class="n">some_listener</span><span class="p">)</span></pre></div>
	343	</div>
	344	<p>Mapper events provide hooks into critical sections of the
	345	mapper, including those related to object instrumentation,
	346	object loading, and object persistence. In particular, the
	347	persistence methods <a class="reference internal" href="#sqlalchemy.orm.events.MapperEvents.before_insert" title="sqlalchemy.orm.events.MapperEvents.before_insert"><tt class="xref py py-meth docutils literal"><span class="pre">before_insert()</span></tt></a>,
	348	and <a class="reference internal" href="#sqlalchemy.orm.events.MapperEvents.before_update" title="sqlalchemy.orm.events.MapperEvents.before_update"><tt class="xref py py-meth docutils literal"><span class="pre">before_update()</span></tt></a> are popular
	349	places to augment the state being persisted - however, these
	350	methods operate with several significant restrictions. The
	351	user is encouraged to evaluate the
	352	<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> and
	353	<a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_flush" title="sqlalchemy.orm.events.SessionEvents.after_flush"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.after_flush()</span></tt></a> methods as more
	354	flexible and user-friendly hooks in which to apply
	355	additional database state during a flush.</p>
	356	<p>When using <a class="reference internal" href="#sqlalchemy.orm.events.MapperEvents" title="sqlalchemy.orm.events.MapperEvents"><tt class="xref py py-class docutils literal"><span class="pre">MapperEvents</span></tt></a>, several modifiers are
	357	available to the <a class="reference internal" href="../core/event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">event.listen()</span></tt></a> function.</p>
	358	<table class="docutils field-list" frame="void" rules="none">
	359	<col class="field-name" />
	360	<col class="field-body" />
	361	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	362	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	363	<li><strong>propagate=False</strong> – When True, the event listener should
	364	be applied to all inheriting mappers as well as the
	365	mapper which is the target of this listener.</li>
	366	<li><strong>raw=False</strong> – When True, the “target” argument passed
	367	to applicable event listener functions will be the
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	368	instance’s <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> management
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	369	object, rather than the mapped instance itself.</li>
	370	<li><strong>retval=False</strong> – <p>when True, the user-defined event function
	371	must have a return value, the purpose of which is either to
	372	control subsequent event propagation, or to otherwise alter
	373	the operation in progress by the mapper. Possible return
	374	values are:</p>
	375	<ul>
	376	<li><tt class="docutils literal"><span class="pre">sqlalchemy.orm.interfaces.EXT_CONTINUE</span></tt> - continue event
	377	processing normally.</li>
	378	<li><tt class="docutils literal"><span class="pre">sqlalchemy.orm.interfaces.EXT_STOP</span></tt> - cancel all subsequent
	379	event handlers in the chain.</li>
	380	<li>other values - the return value specified by specific listeners,
	381	such as <a class="reference internal" href="#sqlalchemy.orm.events.MapperEvents.translate_row" title="sqlalchemy.orm.events.MapperEvents.translate_row"><tt class="xref py py-meth docutils literal"><span class="pre">translate_row()</span></tt></a> or
	382	<a class="reference internal" href="#sqlalchemy.orm.events.MapperEvents.create_instance" title="sqlalchemy.orm.events.MapperEvents.create_instance"><tt class="xref py py-meth docutils literal"><span class="pre">create_instance()</span></tt></a>.</li>
	383	</ul>
	384	</li>
	385	</ul>
	386	</td>
	387	</tr>
	388	</tbody>
	389	</table>
	390	<dl class="method">
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	391	<dt id="sqlalchemy.orm.events.MapperEvents.after_configured">
	392	<tt class="descname">after_configured</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.after_configured" title="Permalink to this definition">¶</a></dt>
	393	<dd><p>Called after a series of mappers have been configured.</p>
	394	<p>This corresponds to the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.configure_mappers" title="sqlalchemy.orm.configure_mappers"><tt class="xref py py-func docutils literal"><span class="pre">orm.configure_mappers()</span></tt></a> call, which
	395	note is usually called automatically as mappings are first
	396	used.</p>
	397	<p>Theoretically this event is called once per
	398	application, but is actually called any time new mappers
	399	have been affected by a <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.configure_mappers" title="sqlalchemy.orm.configure_mappers"><tt class="xref py py-func docutils literal"><span class="pre">orm.configure_mappers()</span></tt></a> call. If new mappings
	400	are constructed after existing ones have already been used,
	401	this event can be called again.</p>
	402	</dd></dl>
	403
	404	<dl class="method">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	405	<dt id="sqlalchemy.orm.events.MapperEvents.after_delete">
	406	<tt class="descname">after_delete</tt><big>(</big><em>mapper</em>, <em>connection</em>, <em>target</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.after_delete" title="Permalink to this definition">¶</a></dt>
	407	<dd><p>Receive an object instance after a DELETE statement
	408	has been emitted corresponding to that instance.</p>
	409	<p>This event is used to emit additional SQL statements on
	410	the given connection as well as to perform application
	411	specific bookkeeping related to a deletion event.</p>
	412	<p>The event is often called for a batch of objects of the
	413	same class after their DELETE statements have been emitted at
	414	once in a previous step.</p>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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">@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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	441	<table class="docutils field-list" frame="void" rules="none">
	442	<col class="field-name" />
	443	<col class="field-body" />
	444	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	445	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	446	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	447	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	448	<li><strong>connection</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	449	emit DELETE statements for this instance. This
	450	provides a handle into the current transaction on the
	451	target database specific to this instance.</li>
	452	<li><strong>target</strong> – the mapped instance being deleted. If
	453	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	454	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	455	object associated with the instance.</li>
	456	</ul>
	457	</td>
	458	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	460	</td>
	461	</tr>
	462	</tbody>
	463	</table>
	464	</dd></dl>
	465
	466	<dl class="method">
	467	<dt id="sqlalchemy.orm.events.MapperEvents.after_insert">
	468	<tt class="descname">after_insert</tt><big>(</big><em>mapper</em>, <em>connection</em>, <em>target</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.after_insert" title="Permalink to this definition">¶</a></dt>
	469	<dd><p>Receive an object instance after an INSERT statement
	470	is emitted corresponding to that instance.</p>
	471	<p>This event is used to modify in-Python-only
	472	state on the instance after an INSERT occurs, as well
	473	as to emit additional SQL statements on the given
	474	connection.</p>
	475	<p>The event is often called for a batch of objects of the
	476	same class after their INSERT statements have been
	477	emitted at once in a previous step. In the extremely
	478	rare case that this is not desirable, the
	479	<a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a> can be configured with <tt class="docutils literal"><span class="pre">batch=False</span></tt>,
	480	which will cause batches of instances to be broken up
	481	into individual (and more poorly performing)
	482	event->persist->event steps.</p>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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">@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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	509	<table class="docutils field-list" frame="void" rules="none">
	510	<col class="field-name" />
	511	<col class="field-body" />
	512	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	513	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	514	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	515	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	516	<li><strong>connection</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	517	emit INSERT statements for this instance. This
	518	provides a handle into the current transaction on the
	519	target database specific to this instance.</li>
	520	<li><strong>target</strong> – the mapped instance being persisted. If
	521	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	522	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	523	object associated with the instance.</li>
	524	</ul>
	525	</td>
	526	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	528	</td>
	529	</tr>
	530	</tbody>
	531	</table>
	532	</dd></dl>
	533
	534	<dl class="method">
	535	<dt id="sqlalchemy.orm.events.MapperEvents.after_update">
	536	<tt class="descname">after_update</tt><big>(</big><em>mapper</em>, <em>connection</em>, <em>target</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.after_update" title="Permalink to this definition">¶</a></dt>
	537	<dd><p>Receive an object instance after an UPDATE statement
	538	is emitted corresponding to that instance.</p>
	539	<p>This event is used to modify in-Python-only
	540	state on the instance after an UPDATE occurs, as well
	541	as to emit additional SQL statements on the given
	542	connection.</p>
	543	<p>This method is called for all instances that are
	544	marked as “dirty”, <em>even those which have no net changes
	545	to their column-based attributes</em>, and for which
	546	no UPDATE statement has proceeded. An object is marked
	547	as dirty when any of its column-based attributes have a
	548	“set attribute” operation called or when any of its
	549	collections are modified. If, at update time, no
	550	column-based attributes have any net changes, no UPDATE
	551	statement will be issued. This means that an instance
	552	being sent to <a class="reference internal" href="#sqlalchemy.orm.events.MapperEvents.after_update" title="sqlalchemy.orm.events.MapperEvents.after_update"><tt class="xref py py-meth docutils literal"><span class="pre">after_update()</span></tt></a> is
	553	<em>not</em> a guarantee that an UPDATE statement has been
	554	issued.</p>
	555	<p>To detect if the column-based attributes on the object have net
	556	changes, and therefore resulted in an UPDATE statement, use
	557	<tt class="docutils literal"><span class="pre">object_session(instance).is_modified(instance,</span>
	558	<span class="pre">include_collections=False)</span></tt>.</p>
	559	<p>The event is often called for a batch of objects of the
	560	same class after their UPDATE statements have been emitted at
	561	once in a previous step. In the extremely rare case that
	562	this is not desirable, the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a> can be
	563	configured with <tt class="docutils literal"><span class="pre">batch=False</span></tt>, which will cause
	564	batches of instances to be broken up into individual
	565	(and more poorly performing) event->persist->event
	566	steps.</p>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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">@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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	593	<table class="docutils field-list" frame="void" rules="none">
	594	<col class="field-name" />
	595	<col class="field-body" />
	596	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	597	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	598	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	599	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	600	<li><strong>connection</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	601	emit UPDATE statements for this instance. This
	602	provides a handle into the current transaction on the
	603	target database specific to this instance.</li>
	604	<li><strong>target</strong> – the mapped instance being persisted. If
	605	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	606	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	607	object associated with the instance.</li>
	608	</ul>
	609	</td>
	610	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	612	</td>
	613	</tr>
	614	</tbody>
	615	</table>
	616	</dd></dl>
	617
	618	<dl class="method">
	619	<dt id="sqlalchemy.orm.events.MapperEvents.append_result">
	620	<tt class="descname">append_result</tt><big>(</big><em>mapper</em>, <em>context</em>, <em>row</em>, <em>target</em>, <em>result</em>, <em>**flags</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.append_result" title="Permalink to this definition">¶</a></dt>
	621	<dd><p>Receive an object instance before that instance is appended
	622	to a result list.</p>
	623	<p>This is a rarely used hook which can be used to alter
	624	the construction of a result list returned by <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>.</p>
	625	<table class="docutils field-list" frame="void" rules="none">
	626	<col class="field-name" />
	627	<col class="field-body" />
	628	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	629	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	630	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	631	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	632	<li><strong>context</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	633	a handle to the 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 as well
	634	as additional state information.</li>
	635	<li><strong>row</strong> – the result row being handled. This may be
	636	an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal"><span class="pre">RowProxy</span></tt></a> or may be a dictionary containing
	637	<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> objects as keys.</li>
	638	<li><strong>target</strong> – the mapped instance being populated. If
	639	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	640	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	641	object associated with the instance.</li>
	642	<li><strong>result</strong> – a list-like object where results are being
	643	appended.</li>
	644	<li><strong>**flags</strong> – Additional state information about the
	645	current handling of the row.</li>
	646	</ul>
	647	</td>
	648	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>,
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	650	a return value of <tt class="docutils literal"><span class="pre">EXT_STOP</span></tt> will prevent the instance
	651	from being appended to the given result list, whereas a
	652	return value of <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt> will result in the default
	653	behavior of appending the value to the result list.</p>
	654	</td>
	655	</tr>
	656	</tbody>
	657	</table>
	658	</dd></dl>
	659
	660	<dl class="method">
	661	<dt id="sqlalchemy.orm.events.MapperEvents.before_delete">
	662	<tt class="descname">before_delete</tt><big>(</big><em>mapper</em>, <em>connection</em>, <em>target</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.before_delete" title="Permalink to this definition">¶</a></dt>
	663	<dd><p>Receive an object instance before a DELETE statement
	664	is emitted corresponding to that instance.</p>
	665	<p>This event is used to emit additional SQL statements on
	666	the given connection as well as to perform application
	667	specific bookkeeping related to a deletion event.</p>
	668	<p>The event is often called for a batch of objects of the
	669	same class before their DELETE statements are emitted at
	670	once in a later step.</p>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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">@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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	697	<table class="docutils field-list" frame="void" rules="none">
	698	<col class="field-name" />
	699	<col class="field-body" />
	700	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	701	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	702	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	703	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	704	<li><strong>connection</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	705	emit DELETE statements for this instance. This
	706	provides a handle into the current transaction on the
	707	target database specific to this instance.</li>
	708	<li><strong>target</strong> – the mapped instance being deleted. If
	709	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	710	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	711	object associated with the instance.</li>
	712	</ul>
	713	</td>
	714	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	716	</td>
	717	</tr>
	718	</tbody>
	719	</table>
	720	</dd></dl>
	721
	722	<dl class="method">
	723	<dt id="sqlalchemy.orm.events.MapperEvents.before_insert">
	724	<tt class="descname">before_insert</tt><big>(</big><em>mapper</em>, <em>connection</em>, <em>target</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.before_insert" title="Permalink to this definition">¶</a></dt>
	725	<dd><p>Receive an object instance before an INSERT statement
	726	is emitted corresponding to that instance.</p>
	727	<p>This event is used to modify local, non-object related
	728	attributes on the instance before an INSERT occurs, as well
	729	as to emit additional SQL statements on the given
	730	connection.</p>
	731	<p>The event is often called for a batch of objects of the
	732	same class before their INSERT statements are emitted at
	733	once in a later step. In the extremely rare case that
	734	this is not desirable, the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a> can be
	735	configured with <tt class="docutils literal"><span class="pre">batch=False</span></tt>, which will cause
	736	batches of instances to be broken up into individual
	737	(and more poorly performing) event->persist->event
	738	steps.</p>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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">@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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	765	<table class="docutils field-list" frame="void" rules="none">
	766	<col class="field-name" />
	767	<col class="field-body" />
	768	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	769	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	770	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	771	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	772	<li><strong>connection</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	773	emit INSERT statements for this instance. This
	774	provides a handle into the current transaction on the
	775	target database specific to this instance.</li>
	776	<li><strong>target</strong> – the mapped instance being persisted. If
	777	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	778	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	779	object associated with the instance.</li>
	780	</ul>
	781	</td>
	782	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	784	</td>
	785	</tr>
	786	</tbody>
	787	</table>
	788	</dd></dl>
	789
	790	<dl class="method">
	791	<dt id="sqlalchemy.orm.events.MapperEvents.before_update">
	792	<tt class="descname">before_update</tt><big>(</big><em>mapper</em>, <em>connection</em>, <em>target</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.before_update" title="Permalink to this definition">¶</a></dt>
	793	<dd><p>Receive an object instance before an UPDATE statement
	794	is emitted corresponding to that instance.</p>
	795	<p>This event is used to modify local, non-object related
	796	attributes on the instance before an UPDATE occurs, as well
	797	as to emit additional SQL statements on the given
	798	connection.</p>
	799	<p>This method is called for all instances that are
	800	marked as “dirty”, <em>even those which have no net changes
	801	to their column-based attributes</em>. An object is marked
	802	as dirty when any of its column-based attributes have a
	803	“set attribute” operation called or when any of its
	804	collections are modified. If, at update time, no
	805	column-based attributes have any net changes, no UPDATE
	806	statement will be issued. This means that an instance
	807	being sent to <a class="reference internal" href="#sqlalchemy.orm.events.MapperEvents.before_update" title="sqlalchemy.orm.events.MapperEvents.before_update"><tt class="xref py py-meth docutils literal"><span class="pre">before_update()</span></tt></a> is
	808	<em>not</em> a guarantee that an UPDATE statement will be
	809	issued, although you can affect the outcome here by
	810	modifying attributes so that a net change in value does
	811	exist.</p>
	812	<p>To detect if the column-based attributes on the object have net
	813	changes, and will therefore generate an UPDATE statement, use
	814	<tt class="docutils literal"><span class="pre">object_session(instance).is_modified(instance,</span>
	815	<span class="pre">include_collections=False)</span></tt>.</p>
	816	<p>The event is often called for a batch of objects of the
	817	same class before their UPDATE statements are emitted at
	818	once in a later step. In the extremely rare case that
	819	this is not desirable, the <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a> can be
	820	configured with <tt class="docutils literal"><span class="pre">batch=False</span></tt>, which will cause
	821	batches of instances to be broken up into individual
	822	(and more poorly performing) event->persist->event
	823	steps.</p>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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">@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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	850	<table class="docutils field-list" frame="void" rules="none">
	851	<col class="field-name" />
	852	<col class="field-body" />
	853	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	854	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	855	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	856	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	857	<li><strong>connection</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	858	emit UPDATE statements for this instance. This
	859	provides a handle into the current transaction on the
	860	target database specific to this instance.</li>
	861	<li><strong>target</strong> – the mapped instance being persisted. If
	862	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	863	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	864	object associated with the instance.</li>
	865	</ul>
	866	</td>
	867	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	869	</td>
	870	</tr>
	871	</tbody>
	872	</table>
	873	</dd></dl>
	874
	875	<dl class="method">
	876	<dt id="sqlalchemy.orm.events.MapperEvents.create_instance">
	877	<tt class="descname">create_instance</tt><big>(</big><em>mapper</em>, <em>context</em>, <em>row</em>, <em>class_</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.create_instance" title="Permalink to this definition">¶</a></dt>
	878	<dd><p>Receive a row when a new object instance is about to be
	879	created from that row.</p>
	880	<p>The method can choose to create the instance itself, or it can return
	881	EXT_CONTINUE to indicate normal object creation should take place.
	882	This listener is typically registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>.</p>
	883	<table class="docutils field-list" frame="void" rules="none">
	884	<col class="field-name" />
	885	<col class="field-body" />
	886	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	887	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	888	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	889	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	890	<li><strong>context</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	891	a handle to the 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 as well
	892	as additional state information.</li>
	893	<li><strong>row</strong> – the result row being handled. This may be
	894	an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal"><span class="pre">RowProxy</span></tt></a> or may be a dictionary containing
	895	<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> objects as keys.</li>
	896	<li><strong>class_</strong> – the mapped class.</li>
	897	</ul>
	898	</td>
	899	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	901	should be a newly created instance of the mapped class,
	902	or <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt> indicating that default object construction
	903	should take place.</p>
	904	</td>
	905	</tr>
	906	</tbody>
	907	</table>
	908	</dd></dl>
	909
	910	<dl class="method">
	911	<dt id="sqlalchemy.orm.events.MapperEvents.instrument_class">
	912	<tt class="descname">instrument_class</tt><big>(</big><em>mapper</em>, <em>class_</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.instrument_class" title="Permalink to this definition">¶</a></dt>
	913	<dd><p>Receive a class when the mapper is first constructed,
	914	before instrumentation is applied to the mapped class.</p>
	915	<p>This event is the earliest phase of mapper construction.
	916	Most attributes of the mapper are not yet initialized.</p>
	917	<p>This listener can generally only be applied to 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>
	918	class overall.</p>
	919	<table class="docutils field-list" frame="void" rules="none">
	920	<col class="field-name" />
	921	<col class="field-body" />
	922	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	923	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	924	<li><strong>mapper</strong> – 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
	925	of this event.</li>
	926	<li><strong>class_</strong> – the mapped class.</li>
	927	</ul>
	928	</td>
	929	</tr>
	930	</tbody>
	931	</table>
	932	</dd></dl>
	933
	934	<dl class="method">
	935	<dt id="sqlalchemy.orm.events.MapperEvents.mapper_configured">
	936	<tt class="descname">mapper_configured</tt><big>(</big><em>mapper</em>, <em>class_</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.mapper_configured" title="Permalink to this definition">¶</a></dt>
	937	<dd><p>Called when the mapper for the class is fully configured.</p>
	938	<p>This event is the latest phase of mapper construction.
	939	The mapper should be in its final state.</p>
	940	<table class="docutils field-list" frame="void" rules="none">
	941	<col class="field-name" />
	942	<col class="field-body" />
	943	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	944	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	945	<li><strong>mapper</strong> – 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
	946	of this event.</li>
	947	<li><strong>class_</strong> – the mapped class.</li>
	948	</ul>
	949	</td>
	950	</tr>
	951	</tbody>
	952	</table>
	953	</dd></dl>
	954
	955	<dl class="method">
	956	<dt id="sqlalchemy.orm.events.MapperEvents.populate_instance">
	957	<tt class="descname">populate_instance</tt><big>(</big><em>mapper</em>, <em>context</em>, <em>row</em>, <em>target</em>, <em>**flags</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.populate_instance" title="Permalink to this definition">¶</a></dt>
	958	<dd><p>Receive an instance before that instance has
	959	its attributes populated.</p>
	960	<p>This usually corresponds to a newly loaded instance but may
	961	also correspond to an already-loaded instance which has
	962	unloaded attributes to be populated. The method may be called
	963	many times for a single instance, as multiple result rows are
	964	used to populate eagerly loaded collections.</p>
	965	<p>Most usages of this hook are obsolete. For a
	966	generic “object has been newly created from a row” hook, use
	967	<a class="reference internal" href="#sqlalchemy.orm.events.InstanceEvents.load" title="sqlalchemy.orm.events.InstanceEvents.load"><tt class="xref py py-meth docutils literal"><span class="pre">InstanceEvents.load()</span></tt></a>.</p>
	968	<table class="docutils field-list" frame="void" rules="none">
	969	<col class="field-name" />
	970	<col class="field-body" />
	971	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	972	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	973	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	974	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	975	<li><strong>context</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	976	a handle to the 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 as well
	977	as additional state information.</li>
	978	<li><strong>row</strong> – the result row being handled. This may be
	979	an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal"><span class="pre">RowProxy</span></tt></a> or may be a dictionary containing
	980	<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> objects as keys.</li>
	981	<li><strong>target</strong> – the mapped instance. If
	982	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	983	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	984	object associated with the instance.</li>
	985	</ul>
	986	</td>
	987	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	989	value of <tt class="docutils literal"><span class="pre">EXT_STOP</span></tt> will bypass instance population by
	990	the mapper. A value of <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt> indicates that
	991	default instance population should take place.</p>
	992	</td>
	993	</tr>
	994	</tbody>
	995	</table>
	996	</dd></dl>
	997
	998	<dl class="method">
	999	<dt id="sqlalchemy.orm.events.MapperEvents.translate_row">
	1000	<tt class="descname">translate_row</tt><big>(</big><em>mapper</em>, <em>context</em>, <em>row</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.translate_row" title="Permalink to this definition">¶</a></dt>
	1001	<dd><p>Perform pre-processing on the given result row and return a
	1002	new row instance.</p>
	1003	<p>This listener is typically registered with <tt class="docutils literal"><span class="pre">retval=True</span></tt>.
	1004	It is called when the mapper first receives a row, before
	1005	the object identity or the instance itself has been derived
	1006	from that row. The given row may or may not be a
	1007	<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal"><span class="pre">RowProxy</span></tt></a> object - it will always be a dictionary-like
	1008	object which contains mapped columns as keys. The
	1009	returned object should also be a dictionary-like object
	1010	which recognizes mapped columns as keys.</p>
	1011	<table class="docutils field-list" frame="void" rules="none">
	1012	<col class="field-name" />
	1013	<col class="field-body" />
	1014	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1015	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1016	<li><strong>mapper</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1017	of this event.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	1018	<li><strong>context</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1019	a handle to the 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 as well
	1020	as additional state information.</li>
	1021	<li><strong>row</strong> – the result row being handled. This may be
	1022	an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal"><span class="pre">RowProxy</span></tt></a> or may be a dictionary containing
	1023	<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> objects as keys.</li>
	1024	</ul>
	1025	</td>
	1026	</tr>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1028	should return a dictionary-like row object, or <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt>,
	1029	indicating the original row should be used.</p>
	1030	</td>
	1031	</tr>
	1032	</tbody>
	1033	</table>
	1034	</dd></dl>
	1035
	1036	</dd></dl>
	1037
	1038	</div>
	1039	<div class="section" id="instance-events">
	1040	<h2>Instance Events<a class="headerlink" href="#instance-events" title="Permalink to this headline">¶</a></h2>
	1041	<dl class="class">
	1042	<dt id="sqlalchemy.orm.events.InstanceEvents">
	1043	<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.events.</tt><tt class="descname">InstanceEvents</tt><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents" title="Permalink to this definition">¶</a></dt>
	1044	<dd><p>Define events specific to object lifecycle.</p>
	1045	<p>e.g.:</p>
	1046	<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
	1047
	1048	<span class="k">def</span> <span class="nf">my_load_listener</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
	1049	<span class="k">print</span> <span class="s">"on load!"</span>
	1050
	1051	<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">SomeMappedClass</span><span class="p">,</span> <span class="s">'load'</span><span class="p">,</span> <span class="n">my_load_listener</span><span class="p">)</span></pre></div>
	1052	</div>
	1053	<p>Available targets include mapped classes, instances of
	1054	<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> (i.e. returned by <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a>,
	1055	<a class="reference internal" href="mapper_config.html#sqlalchemy.orm.class_mapper" title="sqlalchemy.orm.class_mapper"><tt class="xref py py-func docutils literal"><span class="pre">class_mapper()</span></tt></a> and similar), as well as the
	1056	<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> class and <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a> function itself
	1057	for global event reception:</p>
	1058	<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">mapper</span>
	1059
	1060	<span class="k">def</span> <span class="nf">some_listener</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
	1061	<span class="n">log</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s">"Instance </span><span class="si">%s</span><span class="s"> being loaded"</span> <span class="o">%</span> <span class="n">target</span><span class="p">)</span>
	1062
	1063	<span class="c"># attach to all mappers</span>
	1064	<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">mapper</span><span class="p">,</span> <span class="s">'load'</span><span class="p">,</span> <span class="n">some_listener</span><span class="p">)</span></pre></div>
	1065	</div>
	1066	<p>Instance events are closely related to mapper events, but
	1067	are more specific to the instance and its instrumentation,
	1068	rather than its system of persistence.</p>
	1069	<p>When using <a class="reference internal" href="#sqlalchemy.orm.events.InstanceEvents" title="sqlalchemy.orm.events.InstanceEvents"><tt class="xref py py-class docutils literal"><span class="pre">InstanceEvents</span></tt></a>, several modifiers are
	1070	available to the <a class="reference internal" href="../core/event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">event.listen()</span></tt></a> function.</p>
	1071	<table class="docutils field-list" frame="void" rules="none">
	1072	<col class="field-name" />
	1073	<col class="field-body" />
	1074	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1075	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1076	<li><strong>propagate=False</strong> – When True, the event listener should
	1077	be applied to all inheriting mappers as well as the
	1078	mapper which is the target of this listener.</li>
	1079	<li><strong>raw=False</strong> – When True, the “target” argument passed
	1080	to applicable event listener functions will be the
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	1081	instance’s <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> management
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1082	object, rather than the mapped instance itself.</li>
	1083	</ul>
	1084	</td>
	1085	</tr>
	1086	</tbody>
	1087	</table>
	1088	<dl class="method">
	1089	<dt id="sqlalchemy.orm.events.InstanceEvents.expire">
	1090	<tt class="descname">expire</tt><big>(</big><em>target</em>, <em>attrs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.expire" title="Permalink to this definition">¶</a></dt>
	1091	<dd><p>Receive an object instance after its attributes or some subset
	1092	have been expired.</p>
	1093	<p>‘keys’ is a list of attribute names. If None, the entire
	1094	state was expired.</p>
	1095	<table class="docutils field-list" frame="void" rules="none">
	1096	<col class="field-name" />
	1097	<col class="field-body" />
	1098	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1099	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1100	<li><strong>target</strong> – the mapped instance. If
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1101	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1103	object associated with the instance.</li>
	1104	<li><strong>attrs</strong> – iterable collection of attribute
	1105	names which were expired, or None if all attributes were
	1106	expired.</li>
	1107	</ul>
	1108	</td>
	1109	</tr>
	1110	</tbody>
	1111	</table>
	1112	</dd></dl>
	1113
	1114	<dl class="method">
	1115	<dt id="sqlalchemy.orm.events.InstanceEvents.first_init">
	1116	<tt class="descname">first_init</tt><big>(</big><em>manager</em>, <em>cls</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.first_init" title="Permalink to this definition">¶</a></dt>
	1117	<dd><p>Called when the first instance of a particular mapping is called.</p>
	1118	</dd></dl>
	1119
	1120	<dl class="method">
	1121	<dt id="sqlalchemy.orm.events.InstanceEvents.init">
	1122	<tt class="descname">init</tt><big>(</big><em>target</em>, <em>args</em>, <em>kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.init" title="Permalink to this definition">¶</a></dt>
	1123	<dd><p>Receive an instance when it’s constructor is called.</p>
	1124	<p>This method is only called during a userland construction of
	1125	an object. It is not called when an object is loaded from the
	1126	database.</p>
	1127	</dd></dl>
	1128
	1129	<dl class="method">
	1130	<dt id="sqlalchemy.orm.events.InstanceEvents.init_failure">
	1131	<tt class="descname">init_failure</tt><big>(</big><em>target</em>, <em>args</em>, <em>kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.init_failure" title="Permalink to this definition">¶</a></dt>
	1132	<dd><p>Receive an instance when it’s constructor has been called,
	1133	and raised an exception.</p>
	1134	<p>This method is only called during a userland construction of
	1135	an object. It is not called when an object is loaded from the
	1136	database.</p>
	1137	</dd></dl>
	1138
	1139	<dl class="method">
	1140	<dt id="sqlalchemy.orm.events.InstanceEvents.load">
	1141	<tt class="descname">load</tt><big>(</big><em>target</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.load" title="Permalink to this definition">¶</a></dt>
	1142	<dd><p>Receive an object instance after it has been created via
	1143	<tt class="docutils literal"><span class="pre">__new__</span></tt>, and after initial attribute population has
	1144	occurred.</p>
	1145	<p>This typically occurs when the instance is created based on
	1146	incoming result rows, and is only called once for that
	1147	instance’s lifetime.</p>
	1148	<p>Note that during a result-row load, this method is called upon
	1149	the first row received for this instance. Note that some
	1150	attributes and collections may or may not be loaded or even
	1151	initialized, depending on what’s present in the result rows.</p>
	1152	<table class="docutils field-list" frame="void" rules="none">
	1153	<col class="field-name" />
	1154	<col class="field-body" />
	1155	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1156	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1157	<li><strong>target</strong> – the mapped instance. If
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1158	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1160	object associated with the instance.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	1161	<li><strong>context</strong> – 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
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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>,
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1165	</ul>
	1166	</td>
	1167	</tr>
	1168	</tbody>
	1169	</table>
	1170	</dd></dl>
	1171
	1172	<dl class="method">
	1173	<dt id="sqlalchemy.orm.events.InstanceEvents.pickle">
	1174	<tt class="descname">pickle</tt><big>(</big><em>target</em>, <em>state_dict</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.pickle" title="Permalink to this definition">¶</a></dt>
	1175	<dd><p>Receive an object instance when its associated state is
	1176	being pickled.</p>
	1177	<table class="docutils field-list" frame="void" rules="none">
	1178	<col class="field-name" />
	1179	<col class="field-body" />
	1180	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1181	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1182	<li><strong>target</strong> – the mapped instance. If
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1183	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1185	object associated with the instance.</li>
	1186	<li><strong>state_dict</strong> – the dictionary returned by
	1187	<tt class="xref py py-class docutils literal"><span class="pre">InstanceState.__getstate__</span></tt>, containing the state
	1188	to be pickled.</li>
	1189	</ul>
	1190	</td>
	1191	</tr>
	1192	</tbody>
	1193	</table>
	1194	</dd></dl>
	1195
	1196	<dl class="method">
	1197	<dt id="sqlalchemy.orm.events.InstanceEvents.refresh">
	1198	<tt class="descname">refresh</tt><big>(</big><em>target</em>, <em>context</em>, <em>attrs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.refresh" title="Permalink to this definition">¶</a></dt>
	1199	<dd><p>Receive an object instance after one or more attributes have
	1200	been refreshed from a query.</p>
	1201	<table class="docutils field-list" frame="void" rules="none">
	1202	<col class="field-name" />
	1203	<col class="field-body" />
	1204	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1205	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1206	<li><strong>target</strong> – the mapped instance. If
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1207	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1209	object associated with the instance.</li>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	1210	<li><strong>context</strong> – 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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1211	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.</li>
	1212	<li><strong>attrs</strong> – iterable collection of attribute names which
	1213	were populated, or None if all column-mapped, non-deferred
	1214	attributes were populated.</li>
	1215	</ul>
	1216	</td>
	1217	</tr>
	1218	</tbody>
	1219	</table>
	1220	</dd></dl>
	1221
	1222	<dl class="method">
	1223	<dt id="sqlalchemy.orm.events.InstanceEvents.resurrect">
	1224	<tt class="descname">resurrect</tt><big>(</big><em>target</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.resurrect" title="Permalink to this definition">¶</a></dt>
	1225	<dd><p>Receive an object instance as it is ‘resurrected’ from
	1226	garbage collection, which occurs when a “dirty” state falls
	1227	out of scope.</p>
	1228	<table class="docutils field-list" frame="void" rules="none">
	1229	<col class="field-name" />
	1230	<col class="field-body" />
	1231	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1232	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>target</strong> – the mapped instance. If
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1233	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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
1.6.5 by Piotr Ożarowski Import upstream version 0.7.1	1235	object associated with the instance.</td>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1236	</tr>
	1237	</tbody>
	1238	</table>
	1239	</dd></dl>
	1240
	1241	<dl class="method">
	1242	<dt id="sqlalchemy.orm.events.InstanceEvents.unpickle">
	1243	<tt class="descname">unpickle</tt><big>(</big><em>target</em>, <em>state_dict</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstanceEvents.unpickle" title="Permalink to this definition">¶</a></dt>
	1244	<dd><p>Receive an object instance after it’s associated state has
	1245	been unpickled.</p>
	1246	<table class="docutils field-list" frame="void" rules="none">
	1247	<col class="field-name" />
	1248	<col class="field-body" />
	1249	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1250	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1251	<li><strong>target</strong> – the mapped instance. If
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1252	the event is configured with <tt class="docutils literal"><span class="pre">raw=True</span></tt>, this will
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	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
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1254	object associated with the instance.</li>
	1255	<li><strong>state_dict</strong> – the dictionary sent to
	1256	<tt class="xref py py-class docutils literal"><span class="pre">InstanceState.__setstate__</span></tt>, containing the state
	1257	dictionary which was pickled.</li>
	1258	</ul>
	1259	</td>
	1260	</tr>
	1261	</tbody>
	1262	</table>
	1263	</dd></dl>
	1264
	1265	</dd></dl>
	1266
	1267	</div>
	1268	<div class="section" id="session-events">
	1269	<h2>Session Events<a class="headerlink" href="#session-events" title="Permalink to this headline">¶</a></h2>
	1270	<dl class="class">
	1271	<dt id="sqlalchemy.orm.events.SessionEvents">
	1272	<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.events.</tt><tt class="descname">SessionEvents</tt><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents" title="Permalink to this definition">¶</a></dt>
	1273	<dd><p>Define events specific to <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> lifecycle.</p>
	1274	<p>e.g.:</p>
	1275	<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
	1276	<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">sessionmaker</span>
	1277
	1278	<span class="k">def</span> <span class="nf">my_before_commit</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
	1279	<span class="k">print</span> <span class="s">"before commit!"</span>
	1280
	1281	<span class="n">Session</span> <span class="o">=</span> <span class="n">sessionmaker</span><span class="p">()</span>
	1282
	1283	<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">Session</span><span class="p">,</span> <span class="s">"before_commit"</span><span class="p">,</span> <span class="n">my_before_commit</span><span class="p">)</span></pre></div>
	1284	</div>
	1285	<p>The <a class="reference internal" href="../core/event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">listen()</span></tt></a> function will accept
	1286	<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> objects as well as the return result
	1287	of <a class="reference internal" href="session.html#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal"><span class="pre">sessionmaker()</span></tt></a> and <a class="reference internal" href="session.html#sqlalchemy.orm.scoped_session" title="sqlalchemy.orm.scoped_session"><tt class="xref py py-func docutils literal"><span class="pre">scoped_session()</span></tt></a>.</p>
	1288	<p>Additionally, it accepts 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> class which
	1289	will apply listeners to all <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> instances
	1290	globally.</p>
	1291	<dl class="method">
	1292	<dt id="sqlalchemy.orm.events.SessionEvents.after_attach">
	1293	<tt class="descname">after_attach</tt><big>(</big><em>session</em>, <em>instance</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_attach" title="Permalink to this definition">¶</a></dt>
	1294	<dd><p>Execute after an instance is attached to a session.</p>
	1295	<p>This is called after an add, delete or merge.</p>
	1296	</dd></dl>
	1297
	1298	<dl class="method">
	1299	<dt id="sqlalchemy.orm.events.SessionEvents.after_begin">
	1300	<tt class="descname">after_begin</tt><big>(</big><em>session</em>, <em>transaction</em>, <em>connection</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_begin" title="Permalink to this definition">¶</a></dt>
	1301	<dd><p>Execute after a transaction is begun on a connection</p>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1302	<table class="docutils field-list" frame="void" rules="none">
	1303	<col class="field-name" />
	1304	<col class="field-body" />
	1305	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1306	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1307	<li><strong>session</strong> – 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>
	1308	<li><strong>transaction</strong> – 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>
	1309	<li><strong>connection</strong> – 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
	1310	which will be used for SQL statements.</li>
	1311	</ul>
	1312	</td>
	1313	</tr>
	1314	</tbody>
	1315	</table>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1316	</dd></dl>
	1317
	1318	<dl class="method">
	1319	<dt id="sqlalchemy.orm.events.SessionEvents.after_bulk_delete">
	1320	<tt class="descname">after_bulk_delete</tt><big>(</big><em>session</em>, <em>query</em>, <em>query_context</em>, <em>result</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_bulk_delete" title="Permalink to this definition">¶</a></dt>
	1321	<dd><p>Execute after a bulk delete operation to the session.</p>
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	1322	<p>This is called as a result of the <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.delete" title="sqlalchemy.orm.query.Query.delete"><tt class="xref py py-meth docutils literal"><span class="pre">Query.delete()</span></tt></a> method.</p>
	1323	<table class="docutils field-list" frame="void" rules="none">
	1324	<col class="field-name" />
	1325	<col class="field-body" />
	1326	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1327	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	1328	<li><strong>query</strong> – 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
	1329	called upon.</li>
	1330	<li><strong>query_context</strong> – 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
	1331	to the invocation of an ORM query.</li>
	1332	<li><strong>result</strong> – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a> returned as a result of the
	1333	bulk DELETE operation.</li>
	1334	</ul>
	1335	</td>
	1336	</tr>
	1337	</tbody>
	1338	</table>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1339	</dd></dl>
	1340
	1341	<dl class="method">
	1342	<dt id="sqlalchemy.orm.events.SessionEvents.after_bulk_update">
	1343	<tt class="descname">after_bulk_update</tt><big>(</big><em>session</em>, <em>query</em>, <em>query_context</em>, <em>result</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_bulk_update" title="Permalink to this definition">¶</a></dt>
	1344	<dd><p>Execute after a bulk update operation to the session.</p>
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	1345	<p>This is called as a result of the <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.update" title="sqlalchemy.orm.query.Query.update"><tt class="xref py py-meth docutils literal"><span class="pre">Query.update()</span></tt></a> method.</p>
	1346	<table class="docutils field-list" frame="void" rules="none">
	1347	<col class="field-name" />
	1348	<col class="field-body" />
	1349	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1350	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	1351	<li><strong>query</strong> – 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
	1352	called upon.</li>
	1353	<li><strong>query_context</strong> – 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
	1354	to the invocation of an ORM query.</li>
	1355	<li><strong>result</strong> – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a> returned as a result of the
	1356	bulk UPDATE operation.</li>
	1357	</ul>
	1358	</td>
	1359	</tr>
	1360	</tbody>
	1361	</table>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1362	</dd></dl>
	1363
	1364	<dl class="method">
	1365	<dt id="sqlalchemy.orm.events.SessionEvents.after_commit">
	1366	<tt class="descname">after_commit</tt><big>(</big><em>session</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_commit" title="Permalink to this definition">¶</a></dt>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	1367	<dd><p>Execute after a commit has occurred.</p>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1368	<p>Note that this may not be per-flush if a longer running
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1369	transaction is ongoing.</p>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1370	<table class="docutils field-list" frame="void" rules="none">
	1371	<col class="field-name" />
	1372	<col class="field-body" />
	1373	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1374	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> – 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>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1375	</tr>
	1376	</tbody>
	1377	</table>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1378	</dd></dl>
	1379
	1380	<dl class="method">
	1381	<dt id="sqlalchemy.orm.events.SessionEvents.after_flush">
	1382	<tt class="descname">after_flush</tt><big>(</big><em>session</em>, <em>flush_context</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_flush" title="Permalink to this definition">¶</a></dt>
	1383	<dd><p>Execute after flush has completed, but before commit has been
	1384	called.</p>
	1385	<p>Note that the session’s state is still in pre-flush, i.e. ‘new’,
	1386	‘dirty’, and ‘deleted’ lists still show pre-flush state as well
	1387	as the history settings on instance attributes.</p>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1388	<table class="docutils field-list" frame="void" rules="none">
	1389	<col class="field-name" />
	1390	<col class="field-body" />
	1391	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1392	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1393	<li><strong>session</strong> – 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>
	1394	<li><strong>flush_context</strong> – Internal <tt class="xref py py-class docutils literal"><span class="pre">UOWTransaction</span></tt> object
	1395	which handles the details of the flush.</li>
	1396	</ul>
	1397	</td>
	1398	</tr>
	1399	</tbody>
	1400	</table>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1401	</dd></dl>
	1402
	1403	<dl class="method">
	1404	<dt id="sqlalchemy.orm.events.SessionEvents.after_flush_postexec">
	1405	<tt class="descname">after_flush_postexec</tt><big>(</big><em>session</em>, <em>flush_context</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_flush_postexec" title="Permalink to this definition">¶</a></dt>
	1406	<dd><p>Execute after flush has completed, and after the post-exec
	1407	state occurs.</p>
	1408	<p>This will be when the ‘new’, ‘dirty’, and ‘deleted’ lists are in
	1409	their final state. An actual commit() may or may not have
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	1410	occurred, depending on whether or not the flush started its own
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1411	transaction or participated in a larger transaction.</p>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1412	<table class="docutils field-list" frame="void" rules="none">
	1413	<col class="field-name" />
	1414	<col class="field-body" />
	1415	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1416	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1417	<li><strong>session</strong> – 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>
	1418	<li><strong>flush_context</strong> – Internal <tt class="xref py py-class docutils literal"><span class="pre">UOWTransaction</span></tt> object
	1419	which handles the details of the flush.</li>
	1420	</ul>
	1421	</td>
	1422	</tr>
	1423	</tbody>
	1424	</table>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1425	</dd></dl>
	1426
	1427	<dl class="method">
	1428	<dt id="sqlalchemy.orm.events.SessionEvents.after_rollback">
	1429	<tt class="descname">after_rollback</tt><big>(</big><em>session</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_rollback" title="Permalink to this definition">¶</a></dt>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1430	<dd><p>Execute after a real DBAPI rollback has occurred.</p>
	1431	<p>Note that this event only fires when the <em>actual</em> rollback against
	1432	the database occurs - it does <em>not</em> fire each time the
	1433	<a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-meth docutils literal"><span class="pre">Session.rollback()</span></tt></a> method is called, if the underlying
	1434	DBAPI transaction has already been rolled back. In many
	1435	cases, 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> will not be in
	1436	an “active” state during this event, as the current
	1437	transaction is not valid. To acquire a <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>
	1438	which is active after the outermost rollback has proceeded,
	1439	use the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_soft_rollback" title="sqlalchemy.orm.events.SessionEvents.after_soft_rollback"><tt class="xref py py-meth docutils literal"><span class="pre">SessionEvents.after_soft_rollback()</span></tt></a> event, checking the
	1440	<a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.is_active" title="sqlalchemy.orm.session.Session.is_active"><tt class="xref py py-attr docutils literal"><span class="pre">Session.is_active</span></tt></a> flag.</p>
	1441	<table class="docutils field-list" frame="void" rules="none">
	1442	<col class="field-name" />
	1443	<col class="field-body" />
	1444	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1445	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> – 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>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1446	</tr>
	1447	</tbody>
	1448	</table>
	1449	</dd></dl>
	1450
	1451	<dl class="method">
	1452	<dt id="sqlalchemy.orm.events.SessionEvents.after_soft_rollback">
	1453	<tt class="descname">after_soft_rollback</tt><big>(</big><em>session</em>, <em>previous_transaction</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_soft_rollback" title="Permalink to this definition">¶</a></dt>
	1454	<dd><p>Execute after any rollback has occurred, including “soft”
	1455	rollbacks that don’t actually emit at the DBAPI level.</p>
	1456	<p>This corresponds to both nested and outer rollbacks, i.e.
	1457	the innermost rollback that calls the DBAPI’s
	1458	rollback() method, as well as the enclosing rollback
	1459	calls that only pop themselves from the transaction stack.</p>
	1460	<p>The given <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> can be used to invoke SQL and
	1461	<a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><tt class="xref py py-meth docutils literal"><span class="pre">Session.query()</span></tt></a> operations after an outermost rollback
	1462	by first checking the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.is_active" title="sqlalchemy.orm.session.Session.is_active"><tt class="xref py py-attr docutils literal"><span class="pre">Session.is_active</span></tt></a> flag:</p>
	1463	<div class="highlight-python"><div class="highlight"><pre><span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">Session</span><span class="p">,</span> <span class="s">"after_soft_rollback"</span><span class="p">)</span>
	1464	<span class="k">def</span> <span class="nf">do_something</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">previous_transaction</span><span class="p">):</span>
	1465	<span class="k">if</span> <span class="n">session</span><span class="o">.</span><span class="n">is_active</span><span class="p">:</span>
	1466	<span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">"select * from some_table"</span><span class="p">)</span></pre></div>
	1467	</div>
	1468	<table class="docutils field-list" frame="void" rules="none">
	1469	<col class="field-name" />
	1470	<col class="field-body" />
	1471	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1472	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1473	<li><strong>session</strong> – 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>
	1474	<li><strong>previous_transaction</strong> – 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
	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>
	1476	for the given <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> is available via the
	1477	<a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.transaction" title="sqlalchemy.orm.session.Session.transaction"><tt class="xref py py-attr docutils literal"><span class="pre">Session.transaction</span></tt></a> attribute.</li>
	1478	</ul>
	1479	</td>
	1480	</tr>
	1481	</tbody>
	1482	</table>
	1483	<p>New in 0.7.3.</p>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1484	</dd></dl>
	1485
	1486	<dl class="method">
	1487	<dt id="sqlalchemy.orm.events.SessionEvents.before_commit">
	1488	<tt class="descname">before_commit</tt><big>(</big><em>session</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.before_commit" title="Permalink to this definition">¶</a></dt>
	1489	<dd><p>Execute before commit is called.</p>
	1490	<p>Note that this may not be per-flush if a longer running
	1491	transaction is ongoing.</p>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1492	<table class="docutils field-list" frame="void" rules="none">
	1493	<col class="field-name" />
	1494	<col class="field-body" />
	1495	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1496	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>session</strong> – 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>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1497	</tr>
	1498	</tbody>
	1499	</table>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1500	</dd></dl>
	1501
	1502	<dl class="method">
	1503	<dt id="sqlalchemy.orm.events.SessionEvents.before_flush">
	1504	<tt class="descname">before_flush</tt><big>(</big><em>session</em>, <em>flush_context</em>, <em>instances</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="Permalink to this definition">¶</a></dt>
	1505	<dd><p>Execute before flush process has started.</p>
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1506	<table class="docutils field-list" frame="void" rules="none">
	1507	<col class="field-name" />
	1508	<col class="field-body" />
	1509	<tbody valign="top">
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1510	<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	1511	<li><strong>session</strong> – 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>
	1512	<li><strong>flush_context</strong> – Internal <tt class="xref py py-class docutils literal"><span class="pre">UOWTransaction</span></tt> object
	1513	which handles the details of the flush.</li>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1514	<li><strong>instances</strong> – Usually <tt class="docutils literal"><span class="pre">None</span></tt>, this is the collection of
1.4.16 by Piotr Ożarowski Import upstream version 0.7.3	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
	1516	(note this usage is deprecated).</li>
	1517	</ul>
	1518	</td>
	1519	</tr>
	1520	</tbody>
	1521	</table>
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1522	</dd></dl>
	1523
	1524	</dd></dl>
	1525
	1526	</div>
	1527	<div class="section" id="instrumentation-events">
	1528	<h2>Instrumentation Events<a class="headerlink" href="#instrumentation-events" title="Permalink to this headline">¶</a></h2>
	1529	<dl class="class">
	1530	<dt id="sqlalchemy.orm.events.InstrumentationEvents">
	1531	<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.events.</tt><tt class="descname">InstrumentationEvents</tt><a class="headerlink" href="#sqlalchemy.orm.events.InstrumentationEvents" title="Permalink to this definition">¶</a></dt>
	1532	<dd><p>Events related to class instrumentation events.</p>
	1533	<p>The listeners here support being established against
	1534	any new style class, that is any object that is a subclass
	1535	of ‘type’. Events will then be fired off for events
	1536	against that class as well as all subclasses.
	1537	‘type’ itself is also accepted as a target
	1538	in which case the events fire for all classes.</p>
	1539	<dl class="method">
	1540	<dt id="sqlalchemy.orm.events.InstrumentationEvents.attribute_instrument">
	1541	<tt class="descname">attribute_instrument</tt><big>(</big><em>cls</em>, <em>key</em>, <em>inst</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstrumentationEvents.attribute_instrument" title="Permalink to this definition">¶</a></dt>
	1542	<dd><p>Called when an attribute is instrumented.</p>
	1543	</dd></dl>
	1544
	1545	<dl class="method">
	1546	<dt id="sqlalchemy.orm.events.InstrumentationEvents.class_instrument">
	1547	<tt class="descname">class_instrument</tt><big>(</big><em>cls</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstrumentationEvents.class_instrument" title="Permalink to this definition">¶</a></dt>
	1548	<dd><p>Called after the given class is instrumented.</p>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	1549	<p>To get at the <a class="reference internal" href="internals.html#sqlalchemy.orm.instrumentation.ClassManager" title="sqlalchemy.orm.instrumentation.ClassManager"><tt class="xref py py-class docutils literal"><span class="pre">ClassManager</span></tt></a>, use
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1550	<a class="reference internal" href="session.html#sqlalchemy.orm.attributes.manager_of_class" title="sqlalchemy.orm.attributes.manager_of_class"><tt class="xref py py-func docutils literal"><span class="pre">manager_of_class()</span></tt></a>.</p>
	1551	</dd></dl>
	1552
	1553	<dl class="method">
	1554	<dt id="sqlalchemy.orm.events.InstrumentationEvents.class_uninstrument">
	1555	<tt class="descname">class_uninstrument</tt><big>(</big><em>cls</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstrumentationEvents.class_uninstrument" title="Permalink to this definition">¶</a></dt>
	1556	<dd><p>Called before the given class is uninstrumented.</p>
1.6.2 by Piotr Ożarowski Import upstream version 0.7~b3	1557	<p>To get at the <a class="reference internal" href="internals.html#sqlalchemy.orm.instrumentation.ClassManager" title="sqlalchemy.orm.instrumentation.ClassManager"><tt class="xref py py-class docutils literal"><span class="pre">ClassManager</span></tt></a>, use
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1558	<a class="reference internal" href="session.html#sqlalchemy.orm.attributes.manager_of_class" title="sqlalchemy.orm.attributes.manager_of_class"><tt class="xref py py-func docutils literal"><span class="pre">manager_of_class()</span></tt></a>.</p>
	1559	</dd></dl>
	1560
	1561	</dd></dl>
	1562
	1563	</div>
	1564	<div class="section" id="alternate-class-instrumentation">
	1565	<h2>Alternate Class Instrumentation<a class="headerlink" href="#alternate-class-instrumentation" title="Permalink to this headline">¶</a></h2>
	1566	<dl class="class">
	1567	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager">
	1568	<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.interfaces.</tt><tt class="descname">InstrumentationManager</tt><big>(</big><em>class_</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager" title="Permalink to this definition">¶</a></dt>
	1569	<dd><p>User-defined class instrumentation extension.</p>
	1570	<p><a class="reference internal" href="#sqlalchemy.orm.interfaces.InstrumentationManager" title="sqlalchemy.orm.interfaces.InstrumentationManager"><tt class="xref py py-class docutils literal"><span class="pre">InstrumentationManager</span></tt></a> can be subclassed in order
	1571	to change
	1572	how class instrumentation proceeds. This class exists for
	1573	the purposes of integration with other object management
	1574	frameworks which would like to entirely modify the
	1575	instrumentation methodology of the ORM, and is not intended
	1576	for regular usage. For interception of class instrumentation
	1577	events, see <a class="reference internal" href="#sqlalchemy.orm.events.InstrumentationEvents" title="sqlalchemy.orm.events.InstrumentationEvents"><tt class="xref py py-class docutils literal"><span class="pre">InstrumentationEvents</span></tt></a>.</p>
	1578	<p>For an example of <a class="reference internal" href="#sqlalchemy.orm.interfaces.InstrumentationManager" title="sqlalchemy.orm.interfaces.InstrumentationManager"><tt class="xref py py-class docutils literal"><span class="pre">InstrumentationManager</span></tt></a>, see the
	1579	example <a class="reference internal" href="examples.html#examples-instrumentation"><em>Attribute Instrumentation</em></a>.</p>
	1580	<p>The API for this class should be considered as semi-stable,
	1581	and may change slightly with new releases.</p>
	1582	<dl class="method">
	1583	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.dict_getter">
	1584	<tt class="descname">dict_getter</tt><big>(</big><em>class_</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.dict_getter" title="Permalink to this definition">¶</a></dt>
	1585	<dd></dd></dl>
	1586
	1587	<dl class="method">
	1588	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.dispose">
	1589	<tt class="descname">dispose</tt><big>(</big><em>class_</em>, <em>manager</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.dispose" title="Permalink to this definition">¶</a></dt>
	1590	<dd></dd></dl>
	1591
	1592	<dl class="method">
	1593	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.get_instance_dict">
	1594	<tt class="descname">get_instance_dict</tt><big>(</big><em>class_</em>, <em>instance</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.get_instance_dict" title="Permalink to this definition">¶</a></dt>
	1595	<dd></dd></dl>
	1596
	1597	<dl class="method">
	1598	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.initialize_instance_dict">
	1599	<tt class="descname">initialize_instance_dict</tt><big>(</big><em>class_</em>, <em>instance</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.initialize_instance_dict" title="Permalink to this definition">¶</a></dt>
	1600	<dd></dd></dl>
	1601
	1602	<dl class="method">
	1603	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.install_descriptor">
	1604	<tt class="descname">install_descriptor</tt><big>(</big><em>class_</em>, <em>key</em>, <em>inst</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.install_descriptor" title="Permalink to this definition">¶</a></dt>
	1605	<dd></dd></dl>
	1606
	1607	<dl class="method">
	1608	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.install_member">
	1609	<tt class="descname">install_member</tt><big>(</big><em>class_</em>, <em>key</em>, <em>implementation</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.install_member" title="Permalink to this definition">¶</a></dt>
	1610	<dd></dd></dl>
	1611
	1612	<dl class="method">
	1613	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.install_state">
	1614	<tt class="descname">install_state</tt><big>(</big><em>class_</em>, <em>instance</em>, <em>state</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.install_state" title="Permalink to this definition">¶</a></dt>
	1615	<dd></dd></dl>
	1616
	1617	<dl class="method">
	1618	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.instrument_attribute">
	1619	<tt class="descname">instrument_attribute</tt><big>(</big><em>class_</em>, <em>key</em>, <em>inst</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.instrument_attribute" title="Permalink to this definition">¶</a></dt>
	1620	<dd></dd></dl>
	1621
1622	<dl class="method">
1623	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.instrument_collection_class">
1624	<tt class="descname">instrument_collection_class</tt><big>(</big><em>class_</em>, <em>key</em>, <em>collection_class</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.instrument_collection_class" title="Permalink to this definition">¶</a></dt>
1625	<dd></dd></dl>
1626
1627	<dl class="method">
1628	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.manage">
1629	<tt class="descname">manage</tt><big>(</big><em>class_</em>, <em>manager</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.manage" title="Permalink to this definition">¶</a></dt>
1630	<dd></dd></dl>
1631
1632	<dl class="method">
1633	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.manager_getter">
1634	<tt class="descname">manager_getter</tt><big>(</big><em>class_</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.manager_getter" title="Permalink to this definition">¶</a></dt>
1635	<dd></dd></dl>
1636
1637	<dl class="method">
1638	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.post_configure_attribute">
1639	<tt class="descname">post_configure_attribute</tt><big>(</big><em>class_</em>, <em>key</em>, <em>inst</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.post_configure_attribute" title="Permalink to this definition">¶</a></dt>
1640	<dd></dd></dl>
1641
1642	<dl class="method">
1643	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.remove_state">
1644	<tt class="descname">remove_state</tt><big>(</big><em>class_</em>, <em>instance</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.remove_state" title="Permalink to this definition">¶</a></dt>
1645	<dd></dd></dl>
1646
1647	<dl class="method">
1648	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.state_getter">
1649	<tt class="descname">state_getter</tt><big>(</big><em>class_</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.state_getter" title="Permalink to this definition">¶</a></dt>
1650	<dd></dd></dl>
1651
1652	<dl class="method">
1653	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.uninstall_descriptor">
1654	<tt class="descname">uninstall_descriptor</tt><big>(</big><em>class_</em>, <em>key</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.uninstall_descriptor" title="Permalink to this definition">¶</a></dt>
1655	<dd></dd></dl>
1656
1657	<dl class="method">
1658	<dt id="sqlalchemy.orm.interfaces.InstrumentationManager.uninstall_member">
1659	<tt class="descname">uninstall_member</tt><big>(</big><em>class_</em>, <em>key</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.uninstall_member" title="Permalink to this definition">¶</a></dt>
1660	<dd></dd></dl>
1661
1662	</dd></dl>
1663
1664	</div>
1665	</div>
1666
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	1667	</div>
1.4.17 by Piotr Ożarowski Import upstream version 0.7.4	1668
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	1669	</div>
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	1670
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	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	© <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.
1.6.3 by Piotr Ożarowski Import upstream version 0.7~b4	1680	</div>
1.4.18 by Piotr Ożarowski Import upstream version 0.7.5	1681	</div>
	1682
	1683	</div>
	1684
	1685
1.6.1 by Piotr Ożarowski Import upstream version 0.7~b1	1686	</body>
	1687	</html>
	1688
	1689