<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
Core Events
—
SQLAlchemy 1.2 Documentation
</title>
<!-- begin iterate through site-imported + sphinx environment css_files -->
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
<link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
<!-- end iterate through site-imported + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="SQLAlchemy 1.2 Documentation" href="../index.html" />
<link rel="up" title="Engine and Connection Use" href="engines_connections.html" />
<link rel="next" title="Core API Basics" href="api_basics.html" />
<link rel="prev" title="Connection Pooling" href="pooling.html" />
<!-- end layout.mako headers -->
</head>
<body>
<div id="docs-container">
<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
<div id="docs-version-header">
Release: <span class="version-num">1.2.19</span>
| Release Date: April 15, 2019
</div>
<h1>SQLAlchemy 1.2 Documentation</h1>
</div>
</div>
<div id="docs-body-container">
<div id="fixed-sidebar" class="withsidebar">
<div id="docs-sidebar-popout">
<h3><a href="../index.html">SQLAlchemy 1.2 Documentation</a></h3>
<p id="sidebar-topnav">
<a href="../contents.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<label>
Search terms:
<input type="text" placeholder="search..." name="q" size="12" />
</label>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<div id="sidebar-banner">
</div>
<div id="docs-sidebar-inner">
<h3>
<a href="index.html" title="SQLAlchemy Core">SQLAlchemy Core</a>
</h3>
<ul>
<li><span class="link-container"><a class="reference external" href="tutorial.html">SQL Expression Language Tutorial</a></span></li>
<li><span class="link-container"><a class="reference external" href="expression_api.html">SQL Statements and Expressions API</a></span></li>
<li><span class="link-container"><a class="reference external" href="schema.html">Schema Definition Language</a></span></li>
<li><span class="link-container"><a class="reference external" href="types.html">Column and Data Types</a></span></li>
<li><span class="link-container"><a class="reference external" href="engines_connections.html">Engine and Connection Use</a></span><ul>
<li><span class="link-container"><a class="reference external" href="engines.html">Engine Configuration</a></span></li>
<li><span class="link-container"><a class="reference external" href="connections.html">Working with Engines and Connections</a></span></li>
<li><span class="link-container"><a class="reference external" href="pooling.html">Connection Pooling</a></span></li>
<li class="selected"><span class="link-container"><strong>Core Events</strong><a class="paramlink headerlink reference internal" href="#">¶</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#connection-pool-events">Connection Pool Events</a></span></li>
<li><span class="link-container"><a class="reference external" href="#sql-execution-and-connection-events">SQL Execution and Connection Events</a></span></li>
<li><span class="link-container"><a class="reference external" href="#schema-events">Schema Events</a></span></li>
</ul>
</li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="api_basics.html">Core API Basics</a></span></li>
</ul>
</div>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="core-events">
<span id="core-event-toplevel"></span><h1>Core Events<a class="headerlink" href="#core-events" title="Permalink to this headline">¶</a></h1>
<p>This section describes the event interfaces provided in
SQLAlchemy Core.
For an introduction to the event listening API, see <a class="reference internal" href="event.html"><span class="std std-ref">Events</span></a>.
ORM events are described in <a class="reference internal" href="../orm/events.html"><span class="std std-ref">ORM Events</span></a>.</p>
<dl class="class">
<dt id="sqlalchemy.event.base.Events">
<em class="property">class </em><code class="descclassname">sqlalchemy.event.base.</code><code class="descname">Events</code><a class="headerlink" href="#sqlalchemy.event.base.Events" title="Permalink to this definition">¶</a></dt>
<dd><p>Define event listening functions for a particular target type.</p>
</dd></dl>
<div class="section" id="connection-pool-events">
<h2>Connection Pool Events<a class="headerlink" href="#connection-pool-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.PoolEvents">
<em class="property">class </em><code class="descclassname">sqlalchemy.events.</code><code class="descname">PoolEvents</code><a class="headerlink" href="#sqlalchemy.events.PoolEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.event.base.Events" title="sqlalchemy.event.base.Events"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.event.base.Events</span></code></a></p>
<p>Available events for <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a>.</p>
<p>The methods here define the name of an event as well
as the names of members that are passed to listener
functions.</p>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="k">def</span> <span class="nf">my_on_checkout</span><span class="p">(</span><span class="n">dbapi_conn</span><span class="p">,</span> <span class="n">connection_rec</span><span class="p">,</span> <span class="n">connection_proxy</span><span class="p">):</span>
<span class="s2">"handle an on checkout event"</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">Pool</span><span class="p">,</span> <span class="s1">'checkout'</span><span class="p">,</span> <span class="n">my_on_checkout</span><span class="p">)</span></pre></div>
</div>
<p>In addition to accepting the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a> class and
<a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a> instances, <a class="reference internal" href="#sqlalchemy.events.PoolEvents" title="sqlalchemy.events.PoolEvents"><code class="xref py py-class docutils literal notranslate"><span class="pre">PoolEvents</span></code></a> also accepts
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> objects and the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> class as
targets, which will be resolved to the <code class="docutils literal notranslate"><span class="pre">.pool</span></code> attribute of the
given engine or the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a> class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql://scott:tiger@localhost/test"</span><span class="p">)</span>
<span class="c1"># will associate with engine.pool</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="s1">'checkout'</span><span class="p">,</span> <span class="n">my_on_checkout</span><span class="p">)</span></pre></div>
</div>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.checkin">
<code class="descname">checkin</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.checkin" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection returns to the pool.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'checkin'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_checkin</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">):</span>
<span class="s2">"listen for the 'checkin' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>Note that the connection may be closed, and may be None if the
connection has been invalidated. <code class="docutils literal notranslate"><span class="pre">checkin</span></code> will not be called
for detached connections. (They do not return to the pool.)</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.checkin.params.dbapi_connection"></span><strong>dbapi_connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkin.params.dbapi_connection">¶</a> – a DBAPI connection.</p></li>
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.checkin.params.connection_record"></span><strong>connection_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkin.params.connection_record">¶</a> – the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionRecord" title="sqlalchemy.pool._ConnectionRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">_ConnectionRecord</span></code></a> managing the
DBAPI connection.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.checkout">
<code class="descname">checkout</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em>, <em>connection_proxy</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.checkout" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection is retrieved from the Pool.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'checkout'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_checkout</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">,</span> <span class="n">connection_proxy</span><span class="p">):</span>
<span class="s2">"listen for the 'checkout' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.checkout.params.dbapi_connection"></span><strong>dbapi_connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkout.params.dbapi_connection">¶</a> – a DBAPI connection.</p></li>
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.checkout.params.connection_record"></span><strong>connection_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkout.params.connection_record">¶</a> – the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionRecord" title="sqlalchemy.pool._ConnectionRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">_ConnectionRecord</span></code></a> managing the
DBAPI connection.</p></li>
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.checkout.params.connection_proxy"></span><strong>connection_proxy</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkout.params.connection_proxy">¶</a> – the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionFairy" title="sqlalchemy.pool._ConnectionFairy"><code class="xref py py-class docutils literal notranslate"><span class="pre">_ConnectionFairy</span></code></a> object which
will proxy the public interface of the DBAPI connection for the
lifespan of the checkout.</p></li>
</ul>
</dd>
</dl>
<p>If you raise a <a class="reference internal" href="exceptions.html#sqlalchemy.exc.DisconnectionError" title="sqlalchemy.exc.DisconnectionError"><code class="xref py py-class docutils literal notranslate"><span class="pre">DisconnectionError</span></code></a>, the current
connection will be disposed and a fresh connection retrieved.
Processing of all checkout listeners will abort and restart
using the new connection.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.engine_connect" title="sqlalchemy.events.ConnectionEvents.engine_connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.engine_connect()</span></code></a> - a similar event
which occurs upon creation of a new <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.close">
<code class="descname">close</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a DBAPI connection is closed.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'close'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_close</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">):</span>
<span class="s2">"listen for the 'close' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>The event is emitted before the close occurs.</p>
<p>The close of a connection can fail; typically this is because
the connection is already closed. If the close operation fails,
the connection is discarded.</p>
<p>The <a class="reference internal" href="#sqlalchemy.events.PoolEvents.close" title="sqlalchemy.events.PoolEvents.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> event corresponds to a connection that’s still
associated with the pool. To intercept close events for detached
connections use <a class="reference internal" href="#sqlalchemy.events.PoolEvents.close_detached" title="sqlalchemy.events.PoolEvents.close_detached"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close_detached()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.close_detached">
<code class="descname">close_detached</code><span class="sig-paren">(</span><em>dbapi_connection</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.close_detached" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a detached DBAPI connection is closed.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'close_detached'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_close_detached</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">):</span>
<span class="s2">"listen for the 'close_detached' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>The event is emitted before the close occurs.</p>
<p>The close of a connection can fail; typically this is because
the connection is already closed. If the close operation fails,
the connection is discarded.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.connect">
<code class="descname">connect</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called at the moment a particular DBAPI connection is first
created for a given <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a>.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'connect'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_connect</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">):</span>
<span class="s2">"listen for the 'connect' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event allows one to capture the point directly after which
the DBAPI module-level <code class="docutils literal notranslate"><span class="pre">.connect()</span></code> method has been used in order
to produce a new DBAPI connection.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.connect.params.dbapi_connection"></span><strong>dbapi_connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.connect.params.dbapi_connection">¶</a> – a DBAPI connection.</p></li>
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.connect.params.connection_record"></span><strong>connection_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.connect.params.connection_record">¶</a> – the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionRecord" title="sqlalchemy.pool._ConnectionRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">_ConnectionRecord</span></code></a> managing the
DBAPI connection.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.detach">
<code class="descname">detach</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.detach" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a DBAPI connection is “detached” from a pool.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'detach'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_detach</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">):</span>
<span class="s2">"listen for the 'detach' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event is emitted after the detach occurs. The connection
is no longer associated with the given connection record.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.first_connect">
<code class="descname">first_connect</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.first_connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called exactly once for the first time a DBAPI connection is
checked out from a particular <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a>.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'first_connect'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_first_connect</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">):</span>
<span class="s2">"listen for the 'first_connect' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>The rationale for <a class="reference internal" href="#sqlalchemy.events.PoolEvents.first_connect" title="sqlalchemy.events.PoolEvents.first_connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.first_connect()</span></code></a> is to determine
information about a particular series of database connections based
on the settings used for all connections. Since a particular
<a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a> refers to a single “creator” function (which in terms
of a <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> refers to the URL and connection options used),
it is typically valid to make observations about a single connection
that can be safely assumed to be valid about all subsequent
connections, such as the database version, the server and client
encoding settings, collation settings, and many others.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.first_connect.params.dbapi_connection"></span><strong>dbapi_connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.first_connect.params.dbapi_connection">¶</a> – a DBAPI connection.</p></li>
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.first_connect.params.connection_record"></span><strong>connection_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.first_connect.params.connection_record">¶</a> – the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionRecord" title="sqlalchemy.pool._ConnectionRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">_ConnectionRecord</span></code></a> managing the
DBAPI connection.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.invalidate">
<code class="descname">invalidate</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em>, <em>exception</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.invalidate" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a DBAPI connection is to be “invalidated”.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'invalidate'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_invalidate</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">,</span> <span class="n">exception</span><span class="p">):</span>
<span class="s2">"listen for the 'invalidate' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event is called any time the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionRecord.invalidate" title="sqlalchemy.pool._ConnectionRecord.invalidate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">_ConnectionRecord.invalidate()</span></code></a>
method is invoked, either from API usage or via “auto-invalidation”,
without the <code class="docutils literal notranslate"><span class="pre">soft</span></code> flag.</p>
<p>The event occurs before a final attempt to call <code class="docutils literal notranslate"><span class="pre">.close()</span></code> on the
connection occurs.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.invalidate.params.dbapi_connection"></span><strong>dbapi_connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.invalidate.params.dbapi_connection">¶</a> – a DBAPI connection.</p></li>
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.invalidate.params.connection_record"></span><strong>connection_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.invalidate.params.connection_record">¶</a> – the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionRecord" title="sqlalchemy.pool._ConnectionRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">_ConnectionRecord</span></code></a> managing the
DBAPI connection.</p></li>
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.invalidate.params.exception"></span><strong>exception</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.invalidate.params.exception">¶</a> – the exception object corresponding to the reason
for this invalidation, if any. May be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
</ul>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.2: </span>Added support for connection invalidation
listening.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="pooling.html#pool-connection-invalidation"><span class="std std-ref">More on Invalidation</span></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.reset">
<code class="descname">reset</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.reset" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before the “reset” action occurs for a pooled connection.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'reset'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_reset</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">):</span>
<span class="s2">"listen for the 'reset' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event represents
when the <code class="docutils literal notranslate"><span class="pre">rollback()</span></code> method is called on the DBAPI connection
before it is returned to the pool. The behavior of “reset” can
be controlled, including disabled, using the <code class="docutils literal notranslate"><span class="pre">reset_on_return</span></code>
pool argument.</p>
<p>The <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.reset()</span></code></a> event is usually followed by the
<a class="reference internal" href="#sqlalchemy.events.PoolEvents.checkin" title="sqlalchemy.events.PoolEvents.checkin"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.checkin()</span></code></a> event is called, except in those
cases where the connection is discarded immediately after reset.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.reset.params.dbapi_connection"></span><strong>dbapi_connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.reset.params.dbapi_connection">¶</a> – a DBAPI connection.</p></li>
<li><p><span class="target" id="sqlalchemy.events.PoolEvents.reset.params.connection_record"></span><strong>connection_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.reset.params.connection_record">¶</a> – the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionRecord" title="sqlalchemy.pool._ConnectionRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">_ConnectionRecord</span></code></a> managing the
DBAPI connection.</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback" title="sqlalchemy.events.ConnectionEvents.rollback"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.rollback()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.commit" title="sqlalchemy.events.ConnectionEvents.commit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.commit()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.soft_invalidate">
<code class="descname">soft_invalidate</code><span class="sig-paren">(</span><em>dbapi_connection</em>, <em>connection_record</em>, <em>exception</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.PoolEvents.soft_invalidate" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a DBAPI connection is to be “soft invalidated”.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngineOrPool</span><span class="p">,</span> <span class="s1">'soft_invalidate'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_soft_invalidate</span><span class="p">(</span><span class="n">dbapi_connection</span><span class="p">,</span> <span class="n">connection_record</span><span class="p">,</span> <span class="n">exception</span><span class="p">):</span>
<span class="s2">"listen for the 'soft_invalidate' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event is called any time the <a class="reference internal" href="pooling.html#sqlalchemy.pool._ConnectionRecord.invalidate" title="sqlalchemy.pool._ConnectionRecord.invalidate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">_ConnectionRecord.invalidate()</span></code></a>
method is invoked with the <code class="docutils literal notranslate"><span class="pre">soft</span></code> flag.</p>
<p>Soft invalidation refers to when the connection record that tracks
this connection will force a reconnect after the current connection
is checked in. It does not actively close the dbapi_connection
at the point at which it is called.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.3.</span></p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="sql-execution-and-connection-events">
<h2>SQL Execution and Connection Events<a class="headerlink" href="#sql-execution-and-connection-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.ConnectionEvents">
<em class="property">class </em><code class="descclassname">sqlalchemy.events.</code><code class="descname">ConnectionEvents</code><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.event.base.Events" title="sqlalchemy.event.base.Events"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.event.base.Events</span></code></a></p>
<p>Available events for <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connectable</span></code></a>, which includes
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> and <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>.</p>
<p>The methods here define the name of an event as well as the names of
members that are passed to listener functions.</p>
<p>An event listener can be associated with any <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connectable</span></code></a>
class or instance, such as an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span><span class="p">,</span> <span class="n">create_engine</span>
<span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span>
<span class="n">executemany</span><span class="p">):</span>
<span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">"Received statement: </span><span class="si">%s</span><span class="s2">"</span><span class="p">,</span> <span class="n">statement</span><span class="p">)</span>
<span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s1">'postgresql://scott:tiger@localhost/test'</span><span class="p">)</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="s2">"before_cursor_execute"</span><span class="p">,</span> <span class="n">before_cursor_execute</span><span class="p">)</span></pre></div>
</div>
<p>or with a specific <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">begin</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="s1">'before_cursor_execute'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span>
<span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
<span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">"Received statement: </span><span class="si">%s</span><span class="s2">"</span><span class="p">,</span> <span class="n">statement</span><span class="p">)</span></pre></div>
</div>
<p>When the methods are called with a <cite>statement</cite> parameter, such as in
<a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute" title="sqlalchemy.events.ConnectionEvents.after_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">after_cursor_execute()</span></code></a>, <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_cursor_execute()</span></code></a> and
<a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error" title="sqlalchemy.events.ConnectionEvents.dbapi_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dbapi_error()</span></code></a>, the statement is the exact SQL string that was
prepared for transmission to the DBAPI <code class="docutils literal notranslate"><span class="pre">cursor</span></code> in the connection’s
<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a>.</p>
<p>The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_execute()</span></code></a> and <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_cursor_execute()</span></code></a>
events can also be established with the <code class="docutils literal notranslate"><span class="pre">retval=True</span></code> flag, which
allows modification of the statement and parameters to be sent
to the database. The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_cursor_execute()</span></code></a> event is
particularly useful here to add ad-hoc string transformations, such
as comments, to all executions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.engine</span> <span class="k">import</span> <span class="n">Engine</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s2">"before_cursor_execute"</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">comment_sql_calls</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span>
<span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
<span class="n">statement</span> <span class="o">=</span> <span class="n">statement</span> <span class="o">+</span> <span class="s2">" -- some comment"</span>
<span class="k">return</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span></pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConnectionEvents</span></code></a> can be established on any
combination of <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>, <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>, as well
as instances of each of those classes. Events across all
four scopes will fire off for a given instance of
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>. However, for performance reasons, the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object determines at instantiation time
whether or not its parent <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> has event listeners
established. Event listeners added to the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>
class or to an instance of <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> <em>after</em> the instantiation
of a dependent <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> instance will usually
<em>not</em> be available on that <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> instance. The newly
added listeners will instead take effect for <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>
instances created subsequent to those event listeners being
established on the parent <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> class or instance.</p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.events.ConnectionEvents.params.retval"></span><strong>retval=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.params.retval">¶</a> – Applies to the <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_execute()</span></code></a> and
<a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_cursor_execute()</span></code></a> events only. When True, the
user-defined event function must have a return value, which
is a tuple of parameters that replace the given statement
and parameters. See those methods for a description of
specific return arguments.</p>
</dd>
</dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.after_cursor_execute">
<code class="descname">after_cursor_execute</code><span class="sig-paren">(</span><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>executemany</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept low-level cursor execute() events after execution.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'after_cursor_execute'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_after_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
<span class="s2">"listen for the 'after_cursor_execute' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'after_cursor_execute'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_after_cursor_execute</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'after_cursor_execute' event"</span>
<span class="n">conn</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'conn'</span><span class="p">]</span>
<span class="n">cursor</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'cursor'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.cursor"></span><strong>cursor</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.cursor">¶</a> – DBAPI cursor object. Will have results pending
if the statement was a SELECT, but these should not be consumed
as they will be needed by the <a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">ResultProxy</span></code></a>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.statement"></span><strong>statement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.statement">¶</a> – string SQL statement, as passed to the DBAPI</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.parameters"></span><strong>parameters</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.parameters">¶</a> – Dictionary, tuple, or list of parameters being
passed to the <code class="docutils literal notranslate"><span class="pre">execute()</span></code> or <code class="docutils literal notranslate"><span class="pre">executemany()</span></code> method of the
DBAPI <code class="docutils literal notranslate"><span class="pre">cursor</span></code>. In some cases may be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExecutionContext</span></code></a> object in use. May
be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.executemany"></span><strong>executemany</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.executemany">¶</a> – boolean, if <code class="docutils literal notranslate"><span class="pre">True</span></code>, this is an <code class="docutils literal notranslate"><span class="pre">executemany()</span></code>
call, if <code class="docutils literal notranslate"><span class="pre">False</span></code>, this is an <code class="docutils literal notranslate"><span class="pre">execute()</span></code> call.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.after_execute">
<code class="descname">after_execute</code><span class="sig-paren">(</span><em>conn</em>, <em>clauseelement</em>, <em>multiparams</em>, <em>params</em>, <em>result</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.after_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept high level execute() events after execute.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'after_execute'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_after_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">clauseelement</span><span class="p">,</span> <span class="n">multiparams</span><span class="p">,</span> <span class="n">params</span><span class="p">,</span> <span class="n">result</span><span class="p">):</span>
<span class="s2">"listen for the 'after_execute' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'after_execute'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_after_execute</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'after_execute' event"</span>
<span class="n">conn</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'conn'</span><span class="p">]</span>
<span class="n">clauseelement</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'clauseelement'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.clauseelement"></span><strong>clauseelement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.clauseelement">¶</a> – SQL expression construct, <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><code class="xref py py-class docutils literal notranslate"><span class="pre">Compiled</span></code></a>
instance, or string statement passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execute()</span></code></a>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.multiparams"></span><strong>multiparams</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.multiparams">¶</a> – Multiple parameter sets, a list of dictionaries.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.params"></span><strong>params</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.params">¶</a> – Single parameter set, a single dictionary.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.result"></span><strong>result</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.result">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">ResultProxy</span></code></a> generated by the execution.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.before_cursor_execute">
<code class="descname">before_cursor_execute</code><span class="sig-paren">(</span><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>executemany</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept low-level cursor execute() events before execution,
receiving the string SQL statement and DBAPI-specific parameter list to
be invoked against a cursor.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'before_cursor_execute'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
<span class="s2">"listen for the 'before_cursor_execute' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'before_cursor_execute'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_before_cursor_execute</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'before_cursor_execute' event"</span>
<span class="n">conn</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'conn'</span><span class="p">]</span>
<span class="n">cursor</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'cursor'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event is a good choice for logging as well as late modifications
to the SQL string. It’s less ideal for parameter modifications except
for those which are specific to a target backend.</p>
<p>This event can be optionally established with the <code class="docutils literal notranslate"><span class="pre">retval=True</span></code>
flag. The <code class="docutils literal notranslate"><span class="pre">statement</span></code> and <code class="docutils literal notranslate"><span class="pre">parameters</span></code> arguments should be
returned as a two-tuple in this case:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s2">"before_cursor_execute"</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span>
<span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
<span class="c1"># do something with statement, parameters</span>
<span class="k">return</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span></pre></div>
</div>
<p>See the example at <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConnectionEvents</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.cursor"></span><strong>cursor</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.cursor">¶</a> – DBAPI cursor object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.statement"></span><strong>statement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.statement">¶</a> – string SQL statement, as to be passed to the DBAPI</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.parameters"></span><strong>parameters</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.parameters">¶</a> – Dictionary, tuple, or list of parameters being
passed to the <code class="docutils literal notranslate"><span class="pre">execute()</span></code> or <code class="docutils literal notranslate"><span class="pre">executemany()</span></code> method of the
DBAPI <code class="docutils literal notranslate"><span class="pre">cursor</span></code>. In some cases may be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExecutionContext</span></code></a> object in use. May
be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.executemany"></span><strong>executemany</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.executemany">¶</a> – boolean, if <code class="docutils literal notranslate"><span class="pre">True</span></code>, this is an <code class="docutils literal notranslate"><span class="pre">executemany()</span></code>
call, if <code class="docutils literal notranslate"><span class="pre">False</span></code>, this is an <code class="docutils literal notranslate"><span class="pre">execute()</span></code> call.</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_execute()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute" title="sqlalchemy.events.ConnectionEvents.after_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">after_cursor_execute()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.before_execute">
<code class="descname">before_execute</code><span class="sig-paren">(</span><em>conn</em>, <em>clauseelement</em>, <em>multiparams</em>, <em>params</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept high level execute() events, receiving uncompiled
SQL constructs and other objects prior to rendering into SQL.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'before_execute'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_before_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">clauseelement</span><span class="p">,</span> <span class="n">multiparams</span><span class="p">,</span> <span class="n">params</span><span class="p">):</span>
<span class="s2">"listen for the 'before_execute' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'before_execute'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_before_execute</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'before_execute' event"</span>
<span class="n">conn</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'conn'</span><span class="p">]</span>
<span class="n">clauseelement</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'clauseelement'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event is good for debugging SQL compilation issues as well
as early manipulation of the parameters being sent to the database,
as the parameter lists will be in a consistent format here.</p>
<p>This event can be optionally established with the <code class="docutils literal notranslate"><span class="pre">retval=True</span></code>
flag. The <code class="docutils literal notranslate"><span class="pre">clauseelement</span></code>, <code class="docutils literal notranslate"><span class="pre">multiparams</span></code>, and <code class="docutils literal notranslate"><span class="pre">params</span></code>
arguments should be returned as a three-tuple in this case:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s2">"before_execute"</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">before_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">clauseelement</span><span class="p">,</span> <span class="n">multiparams</span><span class="p">,</span> <span class="n">params</span><span class="p">):</span>
<span class="c1"># do something with clauseelement, multiparams, params</span>
<span class="k">return</span> <span class="n">clauseelement</span><span class="p">,</span> <span class="n">multiparams</span><span class="p">,</span> <span class="n">params</span></pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_execute.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_execute.params.clauseelement"></span><strong>clauseelement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute.params.clauseelement">¶</a> – SQL expression construct, <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><code class="xref py py-class docutils literal notranslate"><span class="pre">Compiled</span></code></a>
instance, or string statement passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execute()</span></code></a>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_execute.params.multiparams"></span><strong>multiparams</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute.params.multiparams">¶</a> – Multiple parameter sets, a list of dictionaries.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.before_execute.params.params"></span><strong>params</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute.params.params">¶</a> – Single parameter set, a single dictionary.</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_cursor_execute()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.begin">
<code class="descname">begin</code><span class="sig-paren">(</span><em>conn</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.begin" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin() events.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'begin'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_begin</span><span class="p">(</span><span class="n">conn</span><span class="p">):</span>
<span class="s2">"listen for the 'begin' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.events.ConnectionEvents.begin.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.begin.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.begin_twophase">
<code class="descname">begin_twophase</code><span class="sig-paren">(</span><em>conn</em>, <em>xid</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.begin_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin_twophase() events.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'begin_twophase'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_begin_twophase</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">xid</span><span class="p">):</span>
<span class="s2">"listen for the 'begin_twophase' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.begin_twophase.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.begin_twophase.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.begin_twophase.params.xid"></span><strong>xid</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.begin_twophase.params.xid">¶</a> – two-phase XID identifier</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.commit">
<code class="descname">commit</code><span class="sig-paren">(</span><em>conn</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.commit" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit() events, as initiated by a
<a class="reference internal" href="connections.html#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><code class="xref py py-class docutils literal notranslate"><span class="pre">Transaction</span></code></a>.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'commit'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_commit</span><span class="p">(</span><span class="n">conn</span><span class="p">):</span>
<span class="s2">"listen for the 'commit' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>Note that the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a> may also “auto-commit”
a DBAPI connection upon checkin, if the <code class="docutils literal notranslate"><span class="pre">reset_on_return</span></code>
flag is set to the value <code class="docutils literal notranslate"><span class="pre">'commit'</span></code>. To intercept this
commit, use the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.reset()</span></code></a> hook.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.events.ConnectionEvents.commit.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.commit.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.commit_twophase">
<code class="descname">commit_twophase</code><span class="sig-paren">(</span><em>conn</em>, <em>xid</em>, <em>is_prepared</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.commit_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit_twophase() events.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'commit_twophase'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_commit_twophase</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">xid</span><span class="p">,</span> <span class="n">is_prepared</span><span class="p">):</span>
<span class="s2">"listen for the 'commit_twophase' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.commit_twophase.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.commit_twophase.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.commit_twophase.params.xid"></span><strong>xid</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.commit_twophase.params.xid">¶</a> – two-phase XID identifier</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.commit_twophase.params.is_prepared"></span><strong>is_prepared</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.commit_twophase.params.is_prepared">¶</a> – boolean, indicates if
<a class="reference internal" href="connections.html#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.TwoPhaseTransaction.prepare"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TwoPhaseTransaction.prepare()</span></code></a> was called.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.dbapi_error">
<code class="descname">dbapi_error</code><span class="sig-paren">(</span><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>exception</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.dbapi_error" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept a raw DBAPI error.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'dbapi_error'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_dbapi_error</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">exception</span><span class="p">):</span>
<span class="s2">"listen for the 'dbapi_error' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'dbapi_error'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_dbapi_error</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'dbapi_error' event"</span>
<span class="n">conn</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'conn'</span><span class="p">]</span>
<span class="n">cursor</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'cursor'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event is called with the DBAPI exception instance
received from the DBAPI itself, <em>before</em> SQLAlchemy wraps the
exception with it’s own exception wrappers, and before any
other operations are performed on the DBAPI cursor; the
existing transaction remains in effect as well as any state
on the cursor.</p>
<p>The use case here is to inject low-level exception handling
into an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>, typically for logging and
debugging purposes.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Code should <strong>not</strong> modify
any state or throw any exceptions here as this will
interfere with SQLAlchemy’s cleanup and error handling
routines. For exception modification, please refer to the
new <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.handle_error()</span></code></a> event.</p>
</div>
<p>Subsequent to this hook, SQLAlchemy may attempt any
number of operations on the connection/cursor, including
closing the cursor, rolling back of the transaction in the
case of connectionless execution, and disposing of the entire
connection pool if a “disconnect” was detected. The
exception is then wrapped in a SQLAlchemy DBAPI exception
wrapper and re-thrown.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.cursor"></span><strong>cursor</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.cursor">¶</a> – DBAPI cursor object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.statement"></span><strong>statement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.statement">¶</a> – string SQL statement, as passed to the DBAPI</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.parameters"></span><strong>parameters</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.parameters">¶</a> – Dictionary, tuple, or list of parameters being
passed to the <code class="docutils literal notranslate"><span class="pre">execute()</span></code> or <code class="docutils literal notranslate"><span class="pre">executemany()</span></code> method of the
DBAPI <code class="docutils literal notranslate"><span class="pre">cursor</span></code>. In some cases may be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExecutionContext</span></code></a> object in use. May
be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.exception"></span><strong>exception</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.exception">¶</a> – The <strong>unwrapped</strong> exception emitted directly from the
DBAPI. The class here is specific to the DBAPI module in use.</p></li>
</ul>
</dd>
</dl>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 0.9: </span>- The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error" title="sqlalchemy.events.ConnectionEvents.dbapi_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.dbapi_error()</span></code></a>
event is deprecated and will be removed in a future release.
Please refer to the <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.handle_error()</span></code></a>
event.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.engine_connect">
<code class="descname">engine_connect</code><span class="sig-paren">(</span><em>conn</em>, <em>branch</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.engine_connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept the creation of a new <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'engine_connect'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_engine_connect</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">branch</span><span class="p">):</span>
<span class="s2">"listen for the 'engine_connect' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event is called typically as the direct result of calling
the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.connect()</span></code></a> method.</p>
<p>It differs from the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.connect" title="sqlalchemy.events.PoolEvents.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.connect()</span></code></a> method, which
refers to the actual connection to a database at the DBAPI level;
a DBAPI connection may be pooled and reused for many operations.
In contrast, this event refers only to the production of a higher level
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> wrapper around such a DBAPI connection.</p>
<p>It also differs from the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.checkout" title="sqlalchemy.events.PoolEvents.checkout"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.checkout()</span></code></a> event
in that it is specific to the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object, not the
DBAPI connection that <a class="reference internal" href="#sqlalchemy.events.PoolEvents.checkout" title="sqlalchemy.events.PoolEvents.checkout"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.checkout()</span></code></a> deals with, although
this DBAPI connection is available here via the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.connection" title="sqlalchemy.engine.Connection.connection"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Connection.connection</span></code></a> attribute. But note there can in fact
be multiple <a class="reference internal" href="#sqlalchemy.events.PoolEvents.checkout" title="sqlalchemy.events.PoolEvents.checkout"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.checkout()</span></code></a> events within the lifespan
of a single <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object, if that <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>
is invalidated and re-established. There can also be multiple
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> objects generated for the same already-checked-out
DBAPI connection, in the case that a “branch” of a <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>
is produced.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.engine_connect.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.engine_connect.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.engine_connect.params.branch"></span><strong>branch</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.engine_connect.params.branch">¶</a> – if True, this is a “branch” of an existing
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>. A branch is generated within the course
of a statement execution to invoke supplemental statements, most
typically to pre-execute a SELECT of a default value for the purposes
of an INSERT statement.</p></li>
</ul>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="pooling.html#pool-disconnects-pessimistic"><span class="std std-ref">Disconnect Handling - Pessimistic</span></a> - illustrates how to use
<a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.engine_connect" title="sqlalchemy.events.ConnectionEvents.engine_connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.engine_connect()</span></code></a>
to transparently ensure pooled connections are connected to the
database.</p>
<p><a class="reference internal" href="#sqlalchemy.events.PoolEvents.checkout" title="sqlalchemy.events.PoolEvents.checkout"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.checkout()</span></code></a> the lower-level pool checkout event
for an individual DBAPI connection</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.set_connection_execution_options" title="sqlalchemy.events.ConnectionEvents.set_connection_execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.set_connection_execution_options()</span></code></a> - a copy
of a <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> is also made when the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a> method is called.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.engine_disposed">
<code class="descname">engine_disposed</code><span class="sig-paren">(</span><em>engine</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.engine_disposed" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept when the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine.dispose" title="sqlalchemy.engine.Engine.dispose"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.dispose()</span></code></a> method is called.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'engine_disposed'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_engine_disposed</span><span class="p">(</span><span class="n">engine</span><span class="p">):</span>
<span class="s2">"listen for the 'engine_disposed' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>The <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine.dispose" title="sqlalchemy.engine.Engine.dispose"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.dispose()</span></code></a> method instructs the engine to
“dispose” of it’s connection pool (e.g. <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a>), and
replaces it with a new one. Disposing of the old pool has the
effect that existing checked-in connections are closed. The new
pool does not establish any new connections until it is first used.</p>
<p>This event can be used to indicate that resources related to the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> should also be cleaned up, keeping in mind that the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> can still be used for new requests in which case
it re-acquires connection resources.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.5.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.handle_error">
<code class="descname">handle_error</code><span class="sig-paren">(</span><em>exception_context</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept all exceptions processed by the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'handle_error'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_handle_error</span><span class="p">(</span><span class="n">exception_context</span><span class="p">):</span>
<span class="s2">"listen for the 'handle_error' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This includes all exceptions emitted by the DBAPI as well as
within SQLAlchemy’s statement invocation process, including
encoding errors and other statement validation errors. Other areas
in which the event is invoked include transaction begin and end,
result row fetching, cursor creation.</p>
<p>Note that <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">handle_error()</span></code></a> may support new kinds of exceptions
and new calling scenarios at <em>any time</em>. Code which uses this
event must expect new calling patterns to be present in minor
releases.</p>
<p>To support the wide variety of members that correspond to an exception,
as well as to allow extensibility of the event without backwards
incompatibility, the sole argument received is an instance of
<a class="reference internal" href="connections.html#sqlalchemy.engine.ExceptionContext" title="sqlalchemy.engine.ExceptionContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExceptionContext</span></code></a>. This object contains data members
representing detail about the exception.</p>
<p>Use cases supported by this hook include:</p>
<ul class="simple">
<li><p>read-only, low-level exception handling for logging and
debugging purposes</p></li>
<li><p>exception re-writing</p></li>
<li><p>Establishing or disabling whether a connection or the owning
connection pool is invalidated or expired in response to a
specific exception.</p></li>
</ul>
<p>The hook is called while the cursor from the failed operation
(if any) is still open and accessible. Special cleanup operations
can be called on this cursor; SQLAlchemy will attempt to close
this cursor subsequent to this hook being invoked. If the connection
is in “autocommit” mode, the transaction also remains open within
the scope of this hook; the rollback of the per-statement transaction
also occurs after the hook is called.</p>
<p>For the common case of detecting a “disconnect” situation which
is not currently handled by the SQLAlchemy dialect, the
<a class="reference internal" href="connections.html#sqlalchemy.engine.ExceptionContext.is_disconnect" title="sqlalchemy.engine.ExceptionContext.is_disconnect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ExceptionContext.is_disconnect</span></code></a> flag can be set to True which
will cause the exception to be considered as a disconnect situation,
which typically results in the connection pool being invalidated:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s2">"handle_error"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">handle_exception</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">original_exception</span><span class="p">,</span> <span class="n">pyodbc</span><span class="o">.</span><span class="n">Error</span><span class="p">):</span>
<span class="k">for</span> <span class="n">code</span> <span class="ow">in</span> <span class="p">(</span>
<span class="s1">'08S01'</span><span class="p">,</span> <span class="s1">'01002'</span><span class="p">,</span> <span class="s1">'08003'</span><span class="p">,</span>
<span class="s1">'08007'</span><span class="p">,</span> <span class="s1">'08S02'</span><span class="p">,</span> <span class="s1">'08001'</span><span class="p">,</span> <span class="s1">'HYT00'</span><span class="p">,</span> <span class="s1">'HY010'</span><span class="p">):</span>
<span class="k">if</span> <span class="n">code</span> <span class="ow">in</span> <span class="nb">str</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">original_exception</span><span class="p">):</span>
<span class="n">context</span><span class="o">.</span><span class="n">is_disconnect</span> <span class="o">=</span> <span class="kc">True</span></pre></div>
</div>
<p>A handler function has two options for replacing
the SQLAlchemy-constructed exception into one that is user
defined. It can either raise this new exception directly, in
which case all further event listeners are bypassed and the
exception will be raised, after appropriate cleanup as taken
place:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s2">"handle_error"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">handle_exception</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">original_exception</span><span class="p">,</span>
<span class="n">psycopg2</span><span class="o">.</span><span class="n">OperationalError</span><span class="p">)</span> <span class="ow">and</span> \
<span class="s2">"failed"</span> <span class="ow">in</span> <span class="nb">str</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">original_exception</span><span class="p">):</span>
<span class="k">raise</span> <span class="n">MySpecialException</span><span class="p">(</span><span class="s2">"failed operation"</span><span class="p">)</span></pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Because the <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.handle_error()</span></code></a>
event specifically provides for exceptions to be re-thrown as
the ultimate exception raised by the failed statement,
<strong>stack traces will be misleading</strong> if the user-defined event
handler itself fails and throws an unexpected exception;
the stack trace may not illustrate the actual code line that
failed! It is advised to code carefully here and use
logging and/or inline debugging if unexpected exceptions are
occurring.</p>
</div>
<p>Alternatively, a “chained” style of event handling can be
used, by configuring the handler with the <code class="docutils literal notranslate"><span class="pre">retval=True</span></code>
modifier and returning the new exception instance from the
function. In this case, event handling will continue onto the
next handler. The “chained” exception is available using
<a class="reference internal" href="connections.html#sqlalchemy.engine.ExceptionContext.chained_exception" title="sqlalchemy.engine.ExceptionContext.chained_exception"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ExceptionContext.chained_exception</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s2">"handle_error"</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">handle_exception</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="k">if</span> <span class="n">context</span><span class="o">.</span><span class="n">chained_exception</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> \
<span class="s2">"special"</span> <span class="ow">in</span> <span class="n">context</span><span class="o">.</span><span class="n">chained_exception</span><span class="o">.</span><span class="n">message</span><span class="p">:</span>
<span class="k">return</span> <span class="n">MySpecialException</span><span class="p">(</span><span class="s2">"failed"</span><span class="p">,</span>
<span class="n">cause</span><span class="o">=</span><span class="n">context</span><span class="o">.</span><span class="n">chained_exception</span><span class="p">)</span></pre></div>
</div>
<p>Handlers that return <code class="docutils literal notranslate"><span class="pre">None</span></code> may be used within the chain; when
a handler returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, the previous exception instance,
if any, is maintained as the current exception that is passed onto the
next handler.</p>
<p>When a custom exception is raised or returned, SQLAlchemy raises
this new exception as-is, it is not wrapped by any SQLAlchemy
object. If the exception is not a subclass of
<a class="reference internal" href="exceptions.html#sqlalchemy.exc.StatementError" title="sqlalchemy.exc.StatementError"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.exc.StatementError</span></code></a>,
certain features may not be available; currently this includes
the ORM’s feature of adding a detail hint about “autoflush” to
exceptions raised within the autoflush process.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.events.ConnectionEvents.handle_error.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error.params.context">¶</a> – an <a class="reference internal" href="connections.html#sqlalchemy.engine.ExceptionContext" title="sqlalchemy.engine.ExceptionContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExceptionContext</span></code></a> object. See this
class for details on all available members.</p>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.7: </span>Added the
<a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.handle_error()</span></code></a> hook.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.1: </span>The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">handle_error()</span></code></a> event will now
receive all exceptions that inherit from <code class="docutils literal notranslate"><span class="pre">BaseException</span></code>,
including <code class="docutils literal notranslate"><span class="pre">SystemExit</span></code> and <code class="docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code>. The setting for
<a class="reference internal" href="connections.html#sqlalchemy.engine.ExceptionContext.is_disconnect" title="sqlalchemy.engine.ExceptionContext.is_disconnect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ExceptionContext.is_disconnect</span></code></a> is <code class="docutils literal notranslate"><span class="pre">True</span></code> in this case and
the default for
<a class="reference internal" href="connections.html#sqlalchemy.engine.ExceptionContext.invalidate_pool_on_disconnect" title="sqlalchemy.engine.ExceptionContext.invalidate_pool_on_disconnect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ExceptionContext.invalidate_pool_on_disconnect</span></code></a> is
<code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.0.0: </span>The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">handle_error()</span></code></a> event is now
invoked when an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> fails during the initial
call to <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.connect()</span></code></a>, as well as when a
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object encounters an error during a
reconnect operation.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.0.0: </span>The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">handle_error()</span></code></a> event is
not fired off when a dialect makes use of the
<code class="docutils literal notranslate"><span class="pre">skip_user_error_events</span></code> execution option. This is used
by dialects which intend to catch SQLAlchemy-specific exceptions
within specific operations, such as when the MySQL dialect detects
a table not present within the <code class="docutils literal notranslate"><span class="pre">has_table()</span></code> dialect method.
Prior to 1.0.0, code which implements <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.handle_error" title="sqlalchemy.events.ConnectionEvents.handle_error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">handle_error()</span></code></a> needs
to ensure that exceptions thrown in these scenarios are re-raised
without modification.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.prepare_twophase">
<code class="descname">prepare_twophase</code><span class="sig-paren">(</span><em>conn</em>, <em>xid</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.prepare_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept prepare_twophase() events.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'prepare_twophase'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_prepare_twophase</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">xid</span><span class="p">):</span>
<span class="s2">"listen for the 'prepare_twophase' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.prepare_twophase.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.prepare_twophase.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.prepare_twophase.params.xid"></span><strong>xid</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.prepare_twophase.params.xid">¶</a> – two-phase XID identifier</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.release_savepoint">
<code class="descname">release_savepoint</code><span class="sig-paren">(</span><em>conn</em>, <em>name</em>, <em>context</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.release_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept release_savepoint() events.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'release_savepoint'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_release_savepoint</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="s2">"listen for the 'release_savepoint' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.release_savepoint.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.release_savepoint.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.release_savepoint.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.release_savepoint.params.name">¶</a> – specified name used for the savepoint.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.release_savepoint.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.release_savepoint.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExecutionContext</span></code></a> in use. May be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback">
<code class="descname">rollback</code><span class="sig-paren">(</span><em>conn</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback() events, as initiated by a
<a class="reference internal" href="connections.html#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><code class="xref py py-class docutils literal notranslate"><span class="pre">Transaction</span></code></a>.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'rollback'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_rollback</span><span class="p">(</span><span class="n">conn</span><span class="p">):</span>
<span class="s2">"listen for the 'rollback' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>Note that the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pool</span></code></a> also “auto-rolls back”
a DBAPI connection upon checkin, if the <code class="docutils literal notranslate"><span class="pre">reset_on_return</span></code>
flag is set to its default value of <code class="docutils literal notranslate"><span class="pre">'rollback'</span></code>.
To intercept this
rollback, use the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.reset()</span></code></a> hook.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PoolEvents.reset()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback_savepoint">
<code class="descname">rollback_savepoint</code><span class="sig-paren">(</span><em>conn</em>, <em>name</em>, <em>context</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_savepoint() events.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'rollback_savepoint'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_rollback_savepoint</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="s2">"listen for the 'rollback_savepoint' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.name">¶</a> – specified name used for the savepoint.</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExecutionContext</span></code></a> in use. May be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback_twophase">
<code class="descname">rollback_twophase</code><span class="sig-paren">(</span><em>conn</em>, <em>xid</em>, <em>is_prepared</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_twophase() events.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'rollback_twophase'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_rollback_twophase</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">xid</span><span class="p">,</span> <span class="n">is_prepared</span><span class="p">):</span>
<span class="s2">"listen for the 'rollback_twophase' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_twophase.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_twophase.params.xid"></span><strong>xid</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase.params.xid">¶</a> – two-phase XID identifier</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_twophase.params.is_prepared"></span><strong>is_prepared</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase.params.is_prepared">¶</a> – boolean, indicates if
<a class="reference internal" href="connections.html#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.TwoPhaseTransaction.prepare"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TwoPhaseTransaction.prepare()</span></code></a> was called.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.savepoint">
<code class="descname">savepoint</code><span class="sig-paren">(</span><em>conn</em>, <em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept savepoint() events.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'savepoint'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_savepoint</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
<span class="s2">"listen for the 'savepoint' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.savepoint.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.savepoint.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.savepoint.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.savepoint.params.name">¶</a> – specified name used for the savepoint.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.set_connection_execution_options">
<code class="descname">set_connection_execution_options</code><span class="sig-paren">(</span><em>conn</em>, <em>opts</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.set_connection_execution_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept when the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a>
method is called.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'set_connection_execution_options'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_set_connection_execution_options</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">opts</span><span class="p">):</span>
<span class="s2">"listen for the 'set_connection_execution_options' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This method is called after the new <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> has been
produced, with the newly updated execution options collection, but
before the <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> has acted upon any of those new options.</p>
<p>Note that this method is not called when a new <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>
is produced which is inheriting execution options from its parent
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>; to intercept this condition, use the
<a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.engine_connect" title="sqlalchemy.events.ConnectionEvents.engine_connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.engine_connect()</span></code></a> event.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.set_connection_execution_options.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.set_connection_execution_options.params.conn">¶</a> – The newly copied <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.set_connection_execution_options.params.opts"></span><strong>opts</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.set_connection_execution_options.params.opts">¶</a> – dictionary of options that were passed to the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a> method.</p></li>
</ul>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.set_engine_execution_options" title="sqlalchemy.events.ConnectionEvents.set_engine_execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.set_engine_execution_options()</span></code></a> - event
which is called when <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine.execution_options" title="sqlalchemy.engine.Engine.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.execution_options()</span></code></a> is called.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.set_engine_execution_options">
<code class="descname">set_engine_execution_options</code><span class="sig-paren">(</span><em>engine</em>, <em>opts</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.set_engine_execution_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept when the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine.execution_options" title="sqlalchemy.engine.Engine.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.execution_options()</span></code></a>
method is called.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'set_engine_execution_options'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_set_engine_execution_options</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="n">opts</span><span class="p">):</span>
<span class="s2">"listen for the 'set_engine_execution_options' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>The <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine.execution_options" title="sqlalchemy.engine.Engine.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Engine.execution_options()</span></code></a> method produces a shallow
copy of the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> which stores the new options. That new
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> is passed here. A particular application of this
method is to add a <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.engine_connect" title="sqlalchemy.events.ConnectionEvents.engine_connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.engine_connect()</span></code></a> event
handler to the given <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> which will perform some per-
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> task specific to these execution options.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.set_engine_execution_options.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.set_engine_execution_options.params.conn">¶</a> – The newly copied <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> object</p></li>
<li><p><span class="target" id="sqlalchemy.events.ConnectionEvents.set_engine_execution_options.params.opts"></span><strong>opts</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.set_engine_execution_options.params.opts">¶</a> – dictionary of options that were passed to the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a> method.</p></li>
</ul>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.set_connection_execution_options" title="sqlalchemy.events.ConnectionEvents.set_connection_execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.set_connection_execution_options()</span></code></a> - event
which is called when <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a> is
called.</p>
</div>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.events.DialectEvents">
<em class="property">class </em><code class="descclassname">sqlalchemy.events.</code><code class="descname">DialectEvents</code><a class="headerlink" href="#sqlalchemy.events.DialectEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.event.base.Events" title="sqlalchemy.event.base.Events"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.event.base.Events</span></code></a></p>
<p>event interface for execution-replacement functions.</p>
<p>These events allow direct instrumentation and replacement
of key dialect functions which interact with the DBAPI.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><a class="reference internal" href="#sqlalchemy.events.DialectEvents" title="sqlalchemy.events.DialectEvents"><code class="xref py py-class docutils literal notranslate"><span class="pre">DialectEvents</span></code></a> hooks should be considered <strong>semi-public</strong>
and experimental.
These hooks are not for general use and are only for those situations
where intricate re-statement of DBAPI mechanics must be injected onto
an existing dialect. For general-use statement-interception events,
please use the <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConnectionEvents</span></code></a> interface.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.before_cursor_execute()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.before_execute()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute" title="sqlalchemy.events.ConnectionEvents.after_cursor_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.after_cursor_execute()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute" title="sqlalchemy.events.ConnectionEvents.after_execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConnectionEvents.after_execute()</span></code></a></p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.4.</span></p>
</div>
<dl class="method">
<dt id="sqlalchemy.events.DialectEvents.do_connect">
<code class="descname">do_connect</code><span class="sig-paren">(</span><em>dialect</em>, <em>conn_rec</em>, <em>cargs</em>, <em>cparams</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DialectEvents.do_connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Receive connection arguments before a connection is made.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_connect'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_connect</span><span class="p">(</span><span class="n">dialect</span><span class="p">,</span> <span class="n">conn_rec</span><span class="p">,</span> <span class="n">cargs</span><span class="p">,</span> <span class="n">cparams</span><span class="p">):</span>
<span class="s2">"listen for the 'do_connect' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_connect'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_connect</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'do_connect' event"</span>
<span class="n">dialect</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'dialect'</span><span class="p">]</span>
<span class="n">conn_rec</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'conn_rec'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>Return a DBAPI connection to halt further events from invoking;
the returned connection will be used.</p>
<p>Alternatively, the event can manipulate the cargs and/or cparams
collections; cargs will always be a Python list that can be mutated
in-place and cparams a Python dictionary. Return None to
allow control to pass to the next event handler and ultimately
to allow the dialect to connect normally, given the updated
arguments.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.3.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DialectEvents.do_execute">
<code class="descname">do_execute</code><span class="sig-paren">(</span><em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DialectEvents.do_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Receive a cursor to have execute() called.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_execute'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_execute</span><span class="p">(</span><span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="s2">"listen for the 'do_execute' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_execute'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_execute</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'do_execute' event"</span>
<span class="n">cursor</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'cursor'</span><span class="p">]</span>
<span class="n">statement</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'statement'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>Return the value True to halt further events from invoking,
and to indicate that the cursor execution has already taken
place within the event handler.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DialectEvents.do_execute_no_params">
<code class="descname">do_execute_no_params</code><span class="sig-paren">(</span><em>cursor</em>, <em>statement</em>, <em>context</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DialectEvents.do_execute_no_params" title="Permalink to this definition">¶</a></dt>
<dd><p>Receive a cursor to have execute() with no parameters called.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_execute_no_params'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_execute_no_params</span><span class="p">(</span><span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="s2">"listen for the 'do_execute_no_params' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>Return the value True to halt further events from invoking,
and to indicate that the cursor execution has already taken
place within the event handler.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DialectEvents.do_executemany">
<code class="descname">do_executemany</code><span class="sig-paren">(</span><em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DialectEvents.do_executemany" title="Permalink to this definition">¶</a></dt>
<dd><p>Receive a cursor to have executemany() called.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_executemany'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_executemany</span><span class="p">(</span><span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="s2">"listen for the 'do_executemany' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_executemany'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_executemany</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'do_executemany' event"</span>
<span class="n">cursor</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'cursor'</span><span class="p">]</span>
<span class="n">statement</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'statement'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>Return the value True to halt further events from invoking,
and to indicate that the cursor execution has already taken
place within the event handler.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DialectEvents.do_setinputsizes">
<code class="descname">do_setinputsizes</code><span class="sig-paren">(</span><em>inputsizes</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DialectEvents.do_setinputsizes" title="Permalink to this definition">¶</a></dt>
<dd><p>Receive the setinputsizes dictionary for possible modification.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_setinputsizes'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_setinputsizes</span><span class="p">(</span><span class="n">inputsizes</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="s2">"listen for the 'do_setinputsizes' event"</span>
<span class="c1"># ... (event handling logic) ...</span>
<span class="c1"># named argument style (new in 0.9)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeEngine</span><span class="p">,</span> <span class="s1">'do_setinputsizes'</span><span class="p">,</span> <span class="n">named</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_do_setinputsizes</span><span class="p">(</span><span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'do_setinputsizes' event"</span>
<span class="n">inputsizes</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'inputsizes'</span><span class="p">]</span>
<span class="n">cursor</span> <span class="o">=</span> <span class="n">kw</span><span class="p">[</span><span class="s1">'cursor'</span><span class="p">]</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>This event is emitted in the case where the dialect makes use of the
DBAPI <code class="docutils literal notranslate"><span class="pre">cursor.setinputsizes()</span></code> method which passes information about
parameter binding for a particular statement. The given
<code class="docutils literal notranslate"><span class="pre">inputsizes</span></code> dictionary will contain <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BindParameter</span></code></a> objects
as keys, linked to DBAPI-specific type objects as values; for
parameters that are not bound, they are added to the dictionary with
<code class="docutils literal notranslate"><span class="pre">None</span></code> as the value, which means the parameter will not be included
in the ultimate setinputsizes call. The event may be used to inspect
and/or log the datatypes that are being bound, as well as to modify the
dictionary in place. Parameters can be added, modified, or removed
from this dictionary. Callers will typically want to inspect the
<code class="xref py py-attr docutils literal notranslate"><span class="pre">BindParameter.type</span></code> attribute of the given bind objects in
order to make decisions about the DBAPI object.</p>
<p>After the event, the <code class="docutils literal notranslate"><span class="pre">inputsizes</span></code> dictionary is converted into
an appropriate datastructure to be passed to <code class="docutils literal notranslate"><span class="pre">cursor.setinputsizes</span></code>;
either a list for a positional bound parameter execution style,
or a dictionary of string parameter keys to DBAPI type objects for
a named bound parameter execution style.</p>
<p>Most dialects <strong>do not use</strong> this method at all; the only built-in
dialect which uses this hook is the cx_Oracle dialect. The hook here
is made available so as to allow customization of how datatypes are set
up with the cx_Oracle DBAPI.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.9.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../dialects/oracle.html#cx-oracle-setinputsizes"><span class="std std-ref">Fine grained control over cx_Oracle data binding performance with setinputsizes</span></a></p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="schema-events">
<h2>Schema Events<a class="headerlink" href="#schema-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.DDLEvents">
<em class="property">class </em><code class="descclassname">sqlalchemy.events.</code><code class="descname">DDLEvents</code><a class="headerlink" href="#sqlalchemy.events.DDLEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.event.base.Events" title="sqlalchemy.event.base.Events"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.event.base.Events</span></code></a></p>
<p>Define event listeners for schema objects,
that is, <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><code class="xref py py-class docutils literal notranslate"><span class="pre">SchemaItem</span></code></a> and other <a class="reference internal" href="#sqlalchemy.events.SchemaEventTarget" title="sqlalchemy.events.SchemaEventTarget"><code class="xref py py-class docutils literal notranslate"><span class="pre">SchemaEventTarget</span></code></a>
subclasses, including <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetaData</span></code></a>, <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>,
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a>.</p>
<p><a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetaData</span></code></a> and <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> support events
specifically regarding when CREATE and DROP
DDL is emitted to the database.</p>
<p>Attachment events are also provided to customize
behavior whenever a child schema element is associated
with a parent, such as, when a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a> is associated
with its <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>, when a <a class="reference internal" href="constraints.html#sqlalchemy.schema.ForeignKeyConstraint" title="sqlalchemy.schema.ForeignKeyConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">ForeignKeyConstraint</span></code></a>
is associated with a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>, etc.</p>
<p>Example using the <code class="docutils literal notranslate"><span class="pre">after_create</span></code> event:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">Table</span><span class="p">,</span> <span class="n">Column</span><span class="p">,</span> <span class="n">Metadata</span><span class="p">,</span> <span class="n">Integer</span>
<span class="n">m</span> <span class="o">=</span> <span class="n">MetaData</span><span class="p">()</span>
<span class="n">some_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'some_table'</span><span class="p">,</span> <span class="n">m</span><span class="p">,</span> <span class="n">Column</span><span class="p">(</span><span class="s1">'data'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">))</span>
<span class="k">def</span> <span class="nf">after_create</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"ALTER TABLE </span><span class="si">%s</span><span class="s2"> SET name=foo_</span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span>
<span class="p">(</span><span class="n">target</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">target</span><span class="o">.</span><span class="n">name</span><span class="p">))</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">some_table</span><span class="p">,</span> <span class="s2">"after_create"</span><span class="p">,</span> <span class="n">after_create</span><span class="p">)</span></pre></div>
</div>
<p>DDL events integrate closely with the
<a class="reference internal" href="ddl.html#sqlalchemy.schema.DDL" title="sqlalchemy.schema.DDL"><code class="xref py py-class docutils literal notranslate"><span class="pre">DDL</span></code></a> class and the <a class="reference internal" href="ddl.html#sqlalchemy.schema.DDLElement" title="sqlalchemy.schema.DDLElement"><code class="xref py py-class docutils literal notranslate"><span class="pre">DDLElement</span></code></a> hierarchy
of DDL clause constructs, which are themselves appropriate
as listener callables:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">DDL</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
<span class="n">some_table</span><span class="p">,</span>
<span class="s2">"after_create"</span><span class="p">,</span>
<span class="n">DDL</span><span class="p">(</span><span class="s2">"ALTER TABLE </span><span class="si">%(table)s</span><span class="s2"> SET name=foo_</span><span class="si">%(table)s</span><span class="s2">"</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The methods here define the name of an event as well
as the names of members that are passed to listener
functions.</p>
<p>For all <code class="xref py py-class docutils literal notranslate"><span class="pre">DDLEvent</span></code> events, the <code class="docutils literal notranslate"><span class="pre">propagate=True</span></code> keyword argument
will ensure that a given event handler is propagated to copies of the
object, which are made when using the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.tometadata()</span></code></a> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">DDL</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
<span class="n">some_table</span><span class="p">,</span>
<span class="s2">"after_create"</span><span class="p">,</span>
<span class="n">DDL</span><span class="p">(</span><span class="s2">"ALTER TABLE </span><span class="si">%(table)s</span><span class="s2"> SET name=foo_</span><span class="si">%(table)s</span><span class="s2">"</span><span class="p">),</span>
<span class="n">propagate</span><span class="o">=</span><span class="kc">True</span>
<span class="p">)</span>
<span class="n">new_table</span> <span class="o">=</span> <span class="n">some_table</span><span class="o">.</span><span class="n">tometadata</span><span class="p">(</span><span class="n">new_metadata</span><span class="p">)</span></pre></div>
</div>
<p>The above <a class="reference internal" href="ddl.html#sqlalchemy.schema.DDL" title="sqlalchemy.schema.DDL"><code class="xref py py-class docutils literal notranslate"><span class="pre">DDL</span></code></a> object will also be associated with the
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> object represented by <code class="docutils literal notranslate"><span class="pre">new_table</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="event.html"><span class="std std-ref">Events</span></a></p>
<p><a class="reference internal" href="ddl.html#sqlalchemy.schema.DDLElement" title="sqlalchemy.schema.DDLElement"><code class="xref py py-class docutils literal notranslate"><span class="pre">DDLElement</span></code></a></p>
<p><a class="reference internal" href="ddl.html#sqlalchemy.schema.DDL" title="sqlalchemy.schema.DDL"><code class="xref py py-class docutils literal notranslate"><span class="pre">DDL</span></code></a></p>
<p><a class="reference internal" href="ddl.html#schema-ddl-sequences"><span class="std std-ref">Controlling DDL Sequences</span></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_create">
<code class="descname">after_create</code><span class="sig-paren">(</span><em>target</em>, <em>connection</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after CREATE statements are emitted.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeSchemaClassOrObject</span><span class="p">,</span> <span class="s1">'after_create'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_after_create</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'after_create' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.after_create.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_create.params.target">¶</a> – the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetaData</span></code></a> or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>
object which is the target of the event.</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.after_create.params.connection"></span><strong>connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_create.params.connection">¶</a> – the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> where the
CREATE statement or statements have been emitted.</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.after_create.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_create.params.**kw">¶</a> – additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</p></li>
</ul>
</dd>
</dl>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">event.listen()</span></code></a> also accepts the <code class="docutils literal notranslate"><span class="pre">propagate=True</span></code>
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.tometadata()</span></code></a> is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_drop">
<code class="descname">after_drop</code><span class="sig-paren">(</span><em>target</em>, <em>connection</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after DROP statements are emitted.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeSchemaClassOrObject</span><span class="p">,</span> <span class="s1">'after_drop'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_after_drop</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'after_drop' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.after_drop.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_drop.params.target">¶</a> – the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetaData</span></code></a> or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>
object which is the target of the event.</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.after_drop.params.connection"></span><strong>connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_drop.params.connection">¶</a> – the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> where the
DROP statement or statements have been emitted.</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.after_drop.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_drop.params.**kw">¶</a> – additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</p></li>
</ul>
</dd>
</dl>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">event.listen()</span></code></a> also accepts the <code class="docutils literal notranslate"><span class="pre">propagate=True</span></code>
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.tometadata()</span></code></a> is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_parent_attach">
<code class="descname">after_parent_attach</code><span class="sig-paren">(</span><em>target</em>, <em>parent</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_parent_attach" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after a <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><code class="xref py py-class docutils literal notranslate"><span class="pre">SchemaItem</span></code></a> is associated with
a parent <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><code class="xref py py-class docutils literal notranslate"><span class="pre">SchemaItem</span></code></a>.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeSchemaClassOrObject</span><span class="p">,</span> <span class="s1">'after_parent_attach'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_after_parent_attach</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
<span class="s2">"listen for the 'after_parent_attach' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.after_parent_attach.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_parent_attach.params.target">¶</a> – the target object</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.after_parent_attach.params.parent"></span><strong>parent</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_parent_attach.params.parent">¶</a> – the parent to which the target is being attached.</p></li>
</ul>
</dd>
</dl>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">event.listen()</span></code></a> also accepts the <code class="docutils literal notranslate"><span class="pre">propagate=True</span></code>
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.tometadata()</span></code></a> is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_create">
<code class="descname">before_create</code><span class="sig-paren">(</span><em>target</em>, <em>connection</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before CREATE statements are emitted.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeSchemaClassOrObject</span><span class="p">,</span> <span class="s1">'before_create'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_before_create</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'before_create' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.before_create.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_create.params.target">¶</a> – the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetaData</span></code></a> or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>
object which is the target of the event.</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.before_create.params.connection"></span><strong>connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_create.params.connection">¶</a> – the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> where the
CREATE statement or statements will be emitted.</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.before_create.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_create.params.**kw">¶</a> – additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</p></li>
</ul>
</dd>
</dl>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">event.listen()</span></code></a> also accepts the <code class="docutils literal notranslate"><span class="pre">propagate=True</span></code>
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.tometadata()</span></code></a> is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_drop">
<code class="descname">before_drop</code><span class="sig-paren">(</span><em>target</em>, <em>connection</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before DROP statements are emitted.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeSchemaClassOrObject</span><span class="p">,</span> <span class="s1">'before_drop'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_before_drop</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="s2">"listen for the 'before_drop' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.before_drop.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_drop.params.target">¶</a> – the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetaData</span></code></a> or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>
object which is the target of the event.</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.before_drop.params.connection"></span><strong>connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_drop.params.connection">¶</a> – the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> where the
DROP statement or statements will be emitted.</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.before_drop.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_drop.params.**kw">¶</a> – additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</p></li>
</ul>
</dd>
</dl>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">event.listen()</span></code></a> also accepts the <code class="docutils literal notranslate"><span class="pre">propagate=True</span></code>
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.tometadata()</span></code></a> is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_parent_attach">
<code class="descname">before_parent_attach</code><span class="sig-paren">(</span><em>target</em>, <em>parent</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_parent_attach" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before a <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><code class="xref py py-class docutils literal notranslate"><span class="pre">SchemaItem</span></code></a> is associated with
a parent <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><code class="xref py py-class docutils literal notranslate"><span class="pre">SchemaItem</span></code></a>.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeSchemaClassOrObject</span><span class="p">,</span> <span class="s1">'before_parent_attach'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_before_parent_attach</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
<span class="s2">"listen for the 'before_parent_attach' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.before_parent_attach.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_parent_attach.params.target">¶</a> – the target object</p></li>
<li><p><span class="target" id="sqlalchemy.events.DDLEvents.before_parent_attach.params.parent"></span><strong>parent</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_parent_attach.params.parent">¶</a> – the parent to which the target is being attached.</p></li>
</ul>
</dd>
</dl>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">event.listen()</span></code></a> also accepts the <code class="docutils literal notranslate"><span class="pre">propagate=True</span></code>
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.tometadata()</span></code></a> is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.column_reflect">
<code class="descname">column_reflect</code><span class="sig-paren">(</span><em>inspector</em>, <em>table</em>, <em>column_info</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.events.DDLEvents.column_reflect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called for each unit of ‘column info’ retrieved when
a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> is being reflected.</p>
<div class="event-signatures docutils container">
<p>Example argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="c1"># standard decorator style</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">SomeSchemaClassOrObject</span><span class="p">,</span> <span class="s1">'column_reflect'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">receive_column_reflect</span><span class="p">(</span><span class="n">inspector</span><span class="p">,</span> <span class="n">table</span><span class="p">,</span> <span class="n">column_info</span><span class="p">):</span>
<span class="s2">"listen for the 'column_reflect' event"</span>
<span class="c1"># ... (event handling logic) ...</span></pre></div>
</div>
</div>
<p>The dictionary of column information as returned by the
dialect is passed, and can be modified. The dictionary
is that returned in each element of the list returned
by <a class="reference internal" href="reflection.html#sqlalchemy.engine.reflection.Inspector.get_columns" title="sqlalchemy.engine.reflection.Inspector.get_columns"><code class="xref py py-meth docutils literal notranslate"><span class="pre">reflection.Inspector.get_columns()</span></code></a>:</p>
<blockquote>
<div><ul>
<li><p><code class="docutils literal notranslate"><span class="pre">name</span></code> - the column’s name</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">type</span></code> - the type of this column, which should be an instance
of <a class="reference internal" href="type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeEngine</span></code></a></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">nullable</span></code> - boolean flag if the column is NULL or NOT NULL</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">default</span></code> - the column’s server default value. This is
normally specified as a plain string SQL expression, however the
event can pass a <a class="reference internal" href="defaults.html#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><code class="xref py py-class docutils literal notranslate"><span class="pre">FetchedValue</span></code></a>, <a class="reference internal" href="defaults.html#sqlalchemy.schema.DefaultClause" title="sqlalchemy.schema.DefaultClause"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultClause</span></code></a>,
or <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><code class="xref py py-func docutils literal notranslate"><span class="pre">sql.expression.text()</span></code></a> object as well.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.1.6: </span>The <a class="reference internal" href="#sqlalchemy.events.DDLEvents.column_reflect" title="sqlalchemy.events.DDLEvents.column_reflect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">DDLEvents.column_reflect()</span></code></a> event allows a non
string <a class="reference internal" href="defaults.html#sqlalchemy.schema.FetchedValue" title="sqlalchemy.schema.FetchedValue"><code class="xref py py-class docutils literal notranslate"><span class="pre">FetchedValue</span></code></a>,
<a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><code class="xref py py-func docutils literal notranslate"><span class="pre">sql.expression.text()</span></code></a>, or derived object to be
specified as the value of <code class="docutils literal notranslate"><span class="pre">default</span></code> in the column
dictionary.</p>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">attrs</span></code> - dict containing optional column attributes</p></li>
</ul>
</div></blockquote>
<p>The event is called before any action is taken against
this dictionary, and the contents can be modified.
The <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a> specific arguments <code class="docutils literal notranslate"><span class="pre">info</span></code>, <code class="docutils literal notranslate"><span class="pre">key</span></code>,
and <code class="docutils literal notranslate"><span class="pre">quote</span></code> can also be added to the dictionary and
will be passed to the constructor of <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a>.</p>
<p>Note that this event is only meaningful if either
associated with the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> class across the
board, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.schema</span> <span class="k">import</span> <span class="n">Table</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="k">def</span> <span class="nf">listen_for_reflect</span><span class="p">(</span><span class="n">inspector</span><span class="p">,</span> <span class="n">table</span><span class="p">,</span> <span class="n">column_info</span><span class="p">):</span>
<span class="s2">"receive a column_reflect event"</span>
<span class="c1"># ...</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
<span class="n">Table</span><span class="p">,</span>
<span class="s1">'column_reflect'</span><span class="p">,</span>
<span class="n">listen_for_reflect</span><span class="p">)</span></pre></div>
</div>
<p>…or with a specific <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> instance using
the <code class="docutils literal notranslate"><span class="pre">listeners</span></code> argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">listen_for_reflect</span><span class="p">(</span><span class="n">inspector</span><span class="p">,</span> <span class="n">table</span><span class="p">,</span> <span class="n">column_info</span><span class="p">):</span>
<span class="s2">"receive a column_reflect event"</span>
<span class="c1"># ...</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span>
<span class="s1">'sometable'</span><span class="p">,</span>
<span class="n">autoload</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="n">listeners</span><span class="o">=</span><span class="p">[</span>
<span class="p">(</span><span class="s1">'column_reflect'</span><span class="p">,</span> <span class="n">listen_for_reflect</span><span class="p">)</span>
<span class="p">])</span></pre></div>
</div>
<p>This because the reflection process initiated by <code class="docutils literal notranslate"><span class="pre">autoload=True</span></code>
completes within the scope of the constructor for <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>.</p>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">event.listen()</span></code></a> also accepts the <code class="docutils literal notranslate"><span class="pre">propagate=True</span></code>
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.tometadata()</span></code></a> is used.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.events.SchemaEventTarget">
<em class="property">class </em><code class="descclassname">sqlalchemy.events.</code><code class="descname">SchemaEventTarget</code><a class="headerlink" href="#sqlalchemy.events.SchemaEventTarget" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for elements that are the targets of <a class="reference internal" href="#sqlalchemy.events.DDLEvents" title="sqlalchemy.events.DDLEvents"><code class="xref py py-class docutils literal notranslate"><span class="pre">DDLEvents</span></code></a>
events.</p>
<p>This includes <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><code class="xref py py-class docutils literal notranslate"><span class="pre">SchemaItem</span></code></a> as well as <a class="reference internal" href="type_basics.html#sqlalchemy.types.SchemaType" title="sqlalchemy.types.SchemaType"><code class="xref py py-class docutils literal notranslate"><span class="pre">SchemaType</span></code></a>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links, withsidebar">
Previous:
<a href="pooling.html" title="previous chapter">Connection Pooling</a>
Next:
<a href="api_basics.html" title="next chapter">Core API Basics</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2019, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
</div>
</div>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.2.19',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<!-- begin iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<!-- end iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/detectmobile.js"></script>
<script type="text/javascript" src="../_static/init.js"></script>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
b0b6ffab06cbeede296e36ce94734bf8
>
files
>
766
