File: //usr/share/doc/python-sqlalchemy-0.9.8/doc/core/interfaces.html
<!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>
Deprecated Event Interfaces
—
SQLAlchemy 0.9 Documentation
</title>
<!-- begin iterate through SQLA + 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/sphinx_paramlinks.css" type="text/css" />
<link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
<!-- end iterate through SQLA + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.9.8',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</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>
<!-- 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>
<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 0.9 Documentation" href="../index.html" />
<link rel="up" title="SQLAlchemy Core" href="index.html" />
<link rel="next" title="Core Exceptions" href="exceptions.html" />
<link rel="prev" title="Expression Serializer Extension" href="serializer.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">0.9.8</span> | Release Date: October 13, 2014
</div>
<h1>SQLAlchemy 0.9 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 0.9 Documentation</a></h3>
<p id="sidebar-paginate">
<a href="index.html" title="SQLAlchemy Core">Up</a> |
<a href="serializer.html" title="Expression Serializer Extension">Prev</a> |
<a href="exceptions.html" title="Core Exceptions">Next</a>
</p>
<p id="sidebar-topnav">
<a href="../index.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="12" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<h3><a href="#">
Deprecated Event Interfaces
</a></h3>
<ul>
<li><a class="reference internal" href="#">Deprecated Event Interfaces</a><ul>
<li><a class="reference internal" href="#execution-connection-and-cursor-events">Execution, Connection and Cursor Events</a></li>
<li><a class="reference internal" href="#connection-pool-events">Connection Pool Events</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="module-sqlalchemy.interfaces">
<span id="deprecated-event-interfaces"></span><span id="dep-interfaces-core-toplevel"></span><h1>Deprecated Event Interfaces<a class="headerlink" href="#module-sqlalchemy.interfaces" title="Permalink to this headline">¶</a></h1>
<p>This section describes the class-based core event interface introduced in
SQLAlchemy 0.5. The ORM analogue is described at <a class="reference internal" href="../orm/deprecated.html"><em>Deprecated ORM Event Interfaces</em></a>.</p>
<div class="deprecated">
<p><span>Deprecated since version 0.7: </span>The new event system described in <a class="reference internal" href="event.html"><em>Events</em></a> replaces
the extension/proxy/listener system, providing a consistent interface
to all events without the need for subclassing.</p>
</div>
<div class="section" id="execution-connection-and-cursor-events">
<h2>Execution, Connection and Cursor Events<a class="headerlink" href="#execution-connection-and-cursor-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.interfaces.ConnectionProxy">
<em class="property">class </em><tt class="descclassname">sqlalchemy.interfaces.</tt><tt class="descname">ConnectionProxy</tt><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy" title="Permalink to this definition">¶</a></dt>
<dd><p>Allows interception of statement execution by Connections.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.interfaces.ConnectionProxy" title="sqlalchemy.interfaces.ConnectionProxy"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionProxy</span></tt></a> is deprecated. Please
refer to <a class="reference internal" href="events.html#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionEvents</span></tt></a>.</p>
</div>
<p>Either or both of the <tt class="docutils literal"><span class="pre">execute()</span></tt> and <tt class="docutils literal"><span class="pre">cursor_execute()</span></tt>
may be implemented to intercept compiled statement and
cursor level executions, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyProxy</span><span class="p">(</span><span class="n">ConnectionProxy</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">execute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">conn</span><span class="p">,</span> <span class="n">execute</span><span class="p">,</span> <span class="n">clauseelement</span><span class="p">,</span>
<span class="o">*</span><span class="n">multiparams</span><span class="p">,</span> <span class="o">**</span><span class="n">params</span><span class="p">):</span>
<span class="k">print</span> <span class="s">"compiled statement:"</span><span class="p">,</span> <span class="n">clauseelement</span>
<span class="k">return</span> <span class="n">execute</span><span class="p">(</span><span class="n">clauseelement</span><span class="p">,</span> <span class="o">*</span><span class="n">multiparams</span><span class="p">,</span> <span class="o">**</span><span class="n">params</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">cursor_execute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">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="n">executemany</span><span class="p">):</span>
<span class="k">print</span> <span class="s">"raw statement:"</span><span class="p">,</span> <span class="n">statement</span>
<span class="k">return</span> <span class="n">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></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">execute</span></tt> argument is a function that will fulfill the default
execution behavior for the operation. The signature illustrated
in the example should be used.</p>
<p>The proxy is installed into an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> via
the <tt class="docutils literal"><span class="pre">proxy</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">e</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">'someurl://'</span><span class="p">,</span> <span class="n">proxy</span><span class="o">=</span><span class="n">MyProxy</span><span class="p">())</span></pre></div>
</div>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.begin">
<tt class="descname">begin</tt><big>(</big><em>conn</em>, <em>begin</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.begin" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.begin_twophase">
<tt class="descname">begin_twophase</tt><big>(</big><em>conn</em>, <em>begin_twophase</em>, <em>xid</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.begin_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin_twophase() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.commit">
<tt class="descname">commit</tt><big>(</big><em>conn</em>, <em>commit</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.commit" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.commit_twophase">
<tt class="descname">commit_twophase</tt><big>(</big><em>conn</em>, <em>commit_twophase</em>, <em>xid</em>, <em>is_prepared</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.commit_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit_twophase() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.cursor_execute">
<tt class="descname">cursor_execute</tt><big>(</big><em>execute</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>executemany</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.cursor_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept low-level cursor execute() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.execute">
<tt class="descname">execute</tt><big>(</big><em>conn</em>, <em>execute</em>, <em>clauseelement</em>, <em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept high level execute() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.prepare_twophase">
<tt class="descname">prepare_twophase</tt><big>(</big><em>conn</em>, <em>prepare_twophase</em>, <em>xid</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.prepare_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept prepare_twophase() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.release_savepoint">
<tt class="descname">release_savepoint</tt><big>(</big><em>conn</em>, <em>release_savepoint</em>, <em>name</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.release_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept release_savepoint() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.rollback">
<tt class="descname">rollback</tt><big>(</big><em>conn</em>, <em>rollback</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.rollback" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.rollback_savepoint">
<tt class="descname">rollback_savepoint</tt><big>(</big><em>conn</em>, <em>rollback_savepoint</em>, <em>name</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.rollback_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_savepoint() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.rollback_twophase">
<tt class="descname">rollback_twophase</tt><big>(</big><em>conn</em>, <em>rollback_twophase</em>, <em>xid</em>, <em>is_prepared</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.rollback_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_twophase() events.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.ConnectionProxy.savepoint">
<tt class="descname">savepoint</tt><big>(</big><em>conn</em>, <em>savepoint</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.ConnectionProxy.savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept savepoint() events.</p>
</dd></dl>
</dd></dl>
</div>
<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.interfaces.PoolListener">
<em class="property">class </em><tt class="descclassname">sqlalchemy.interfaces.</tt><tt class="descname">PoolListener</tt><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener" title="Permalink to this definition">¶</a></dt>
<dd><p>Hooks into the lifecycle of connections in a <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.interfaces.PoolListener" title="sqlalchemy.interfaces.PoolListener"><tt class="xref py py-class docutils literal"><span class="pre">PoolListener</span></tt></a> is deprecated. Please
refer to <a class="reference internal" href="events.html#sqlalchemy.events.PoolEvents" title="sqlalchemy.events.PoolEvents"><tt class="xref py py-class docutils literal"><span class="pre">PoolEvents</span></tt></a>.</p>
</div>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyListener</span><span class="p">(</span><span class="n">PoolListener</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">connect</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dbapi_con</span><span class="p">,</span> <span class="n">con_record</span><span class="p">):</span>
<span class="sd">'''perform connect operations'''</span>
<span class="c"># etc.</span>
<span class="c"># create a new pool with a listener</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">QueuePool</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">listeners</span><span class="o">=</span><span class="p">[</span><span class="n">MyListener</span><span class="p">()])</span>
<span class="c"># add a listener after the fact</span>
<span class="n">p</span><span class="o">.</span><span class="n">add_listener</span><span class="p">(</span><span class="n">MyListener</span><span class="p">())</span>
<span class="c"># usage with create_engine()</span>
<span class="n">e</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">"url://"</span><span class="p">,</span> <span class="n">listeners</span><span class="o">=</span><span class="p">[</span><span class="n">MyListener</span><span class="p">()])</span></pre></div>
</div>
<p>All of the standard connection <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> types can
accept event listeners for key connection lifecycle events:
creation, pool check-out and check-in. There are no events fired
when a connection closes.</p>
<p>For any given DB-API connection, there will be one <tt class="docutils literal"><span class="pre">connect</span></tt>
event, <cite>n</cite> number of <tt class="docutils literal"><span class="pre">checkout</span></tt> events, and either <cite>n</cite> or <cite>n - 1</cite>
<tt class="docutils literal"><span class="pre">checkin</span></tt> events. (If a <tt class="docutils literal"><span class="pre">Connection</span></tt> is detached from its
pool via the <tt class="docutils literal"><span class="pre">detach()</span></tt> method, it won’t be checked back in.)</p>
<p>These are low-level events for low-level objects: raw Python
DB-API connections, without the conveniences of the SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper, <tt class="docutils literal"><span class="pre">Dialect</span></tt> services or <tt class="docutils literal"><span class="pre">ClauseElement</span></tt>
execution. If you execute SQL through the connection, explicitly
closing all cursors and other resources is recommended.</p>
<p>Events also receive a <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt>, a long-lived internal
<tt class="docutils literal"><span class="pre">Pool</span></tt> object that basically represents a “slot” in the
connection pool. <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> objects have one public
attribute of note: <tt class="docutils literal"><span class="pre">info</span></tt>, a dictionary whose contents are
scoped to the lifetime of the DB-API connection managed by the
record. You can use this shared storage area however you like.</p>
<p>There is no need to subclass <tt class="docutils literal"><span class="pre">PoolListener</span></tt> to handle events.
Any class that implements one or more of these methods can be used
as a pool listener. The <tt class="docutils literal"><span class="pre">Pool</span></tt> will inspect the methods
provided by a listener object and add the listener to one or more
internal event queues based on its capabilities. In terms of
efficiency and function call overhead, you’re much better off only
providing implementations for the hooks you’ll be using.</p>
<dl class="method">
<dt id="sqlalchemy.interfaces.PoolListener.checkin">
<tt class="descname">checkin</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener.checkin" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection returns to the pool.</p>
<p>Note that the connection may be closed, and may be None if the
connection has been invalidated. <tt class="docutils literal"><span class="pre">checkin</span></tt> will not be called
for detached connections. (They do not return to the pool.)</p>
<dl class="docutils">
<dt>dbapi_con</dt>
<dd>A raw DB-API connection</dd>
<dt>con_record</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.PoolListener.checkout">
<tt class="descname">checkout</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em>, <em>con_proxy</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener.checkout" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection is retrieved from the Pool.</p>
<dl class="docutils">
<dt>dbapi_con</dt>
<dd>A raw DB-API connection</dd>
<dt>con_record</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</dd>
<dt>con_proxy</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionFairy</span></tt> which manages the connection for the span of
the current checkout.</dd>
</dl>
<p>If you raise an <tt class="docutils literal"><span class="pre">exc.DisconnectionError</span></tt>, 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>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.PoolListener.connect">
<tt class="descname">connect</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called once for each new DB-API connection or Pool’s <tt class="docutils literal"><span class="pre">creator()</span></tt>.</p>
<dl class="docutils">
<dt>dbapi_con</dt>
<dd>A newly connected raw DB-API connection (not a SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper).</dd>
<dt>con_record</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.interfaces.PoolListener.first_connect">
<tt class="descname">first_connect</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.interfaces.PoolListener.first_connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called exactly once for the first DB-API connection.</p>
<dl class="docutils">
<dt>dbapi_con</dt>
<dd>A newly connected raw DB-API connection (not a SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper).</dd>
<dt>con_record</dt>
<dd>The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</dd>
</dl>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links">
Previous:
<a href="serializer.html" title="previous chapter">Expression Serializer Extension</a>
Next:
<a href="exceptions.html" title="next chapter">Core Exceptions</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
</div>
</div>
</div>
</body>
</html>