twisted.python.hook.html [plain text]
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>twisted.python.hook</title>
<link rel="stylesheet" href="epydoc.css" type="text/css"></link>
</head>
<body bgcolor="white" text="black" link="blue" vlink="#204080"
alink="#204080">
<!-- =========== START OF NAVBAR =========== -->
<table class="navbar" border="0" width="100%" cellpadding="0" bgcolor="#a0c0ff" cellspacing="0">
<tr valign="center">
<th class="navbar"> <a class="navbar" href="twisted.html">Home</a> </th>
<th class="navbar"> <a class="navbar" href="trees.html">Trees</a> </th>
<th class="navbar"> <a class="navbar" href="indices.html">Index</a> </th>
<th class="navbar"> <a class="navbar" href="help.html">Help</a> </th>
<th class="navbar" align="right" width="100%">
<table border="0" cellpadding="0" cellspacing="0">
<tr><th class="navbar" align="center">
<p class="nomargin">
<a class="navbar" target="_top" href="http://twistedmatrix.com/">Twisted 1.3.0rc1</a>
</p></th></tr></table>
</th>
</tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
<tr valign="top">
<td width="100%">
<font size="-1"><b class="breadcrumbs">
<a href="twisted.html">Package twisted</a> ::
<a href="twisted.python.html">Package python</a> ::
Module hook
</b></font></br>
</td>
<td><table cellpadding="0" cellspacing="0">
<tr><td align="right"><font size="-2">[<a href="frames.html"target="_top">frames</a> | <a href="twisted.python.hook.html" target="_top">no frames</a>]</font></td></tr>
</table></td>
</tr></table>
<!-- =========== START OF MODULE DESCRIPTION =========== -->
<h2 class="module">Module twisted.python.hook</h2>
<p>I define support for hookable instance methods.</p>
<p>These are methods which you can register pre-call and post-call
external functions to augment their functionality. People familiar with
more esoteric languages may think of these as "method
combinations".</p>
<p>This could be used to add optional preconditions, user-extensible
callbacks (a-la emacs) or a thread-safety mechanism.</p>
The four exported calls are:
<ul>
<li>
<a href="twisted.python.hook.html#addPre"
class="link"><code>addPre</code></a>
</li>
<li>
<a href="twisted.python.hook.html#addPost"
class="link"><code>addPost</code></a>
</li>
<li>
<a href="twisted.python.hook.html#removePre"
class="link"><code>removePre</code></a>
</li>
<li>
<a href="twisted.python.hook.html#removePost"
class="link"><code>removePost</code></a>
</li>
</ul>
<p>All have the signature (class, methodName, callable), and the callable
they take must always have the signature (instance, *args, **kw) unless
the particular signature of the method they hook is known.</p>
Hooks should typically not throw exceptions, however, no effort will
be made by this module to prevent them from doing so. Pre-hooks will
always be called, but post-hooks will only be called if the pre-hooks do
not raise any exceptions (they will still be called if the main method
raises an exception). The return values and exception status of the main
method will be propogated (assuming none of the hooks raise an
exception). Hooks will be executed in the order in which they are
added.
<hr/>
<!-- =========== START OF EXCEPTIONS =========== -->
<table class="summary" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="summary">
<th colspan="2">Exceptions</th></tr>
<tr><td width="15%">
<b><a href="twisted.python.hook.HookError.html"><code>HookError</code></a></b></td>
<td>An error which will fire when an invariant is violated.</td></tr>
</table><br />
<!-- =========== START OF FUNCTION SUMMARY =========== -->
<table class="summary" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="summary">
<th colspan="2">Function Summary</th></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#_addHook" class="summary-sig-name"><code>_addHook</code></a>(<span class=summary-sig-arg>klass</span>,
<span class=summary-sig-arg>name</span>,
<span class=summary-sig-arg>phase</span>,
<span class=summary-sig-arg>func</span>)</span></code>
<br />
(private) adds a hook to a method on a class</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#_dehook" class="summary-sig-name"><code>_dehook</code></a>(<span class=summary-sig-arg>klass</span>,
<span class=summary-sig-arg>name</span>)</span></code>
<br />
(private) causes a certain method name no longer to be hooked on a
class</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#_enhook" class="summary-sig-name"><code>_enhook</code></a>(<span class=summary-sig-arg>klass</span>,
<span class=summary-sig-arg>name</span>)</span></code>
<br />
(private) causes a certain method name to be hooked on a class</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#_removeHook" class="summary-sig-name"><code>_removeHook</code></a>(<span class=summary-sig-arg>klass</span>,
<span class=summary-sig-arg>name</span>,
<span class=summary-sig-arg>phase</span>,
<span class=summary-sig-arg>func</span>)</span></code>
<br />
(private) removes a hook from a method on a class</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#_XXX" class="summary-sig-name"><code>_XXX</code></a>(<span class=summary-sig-arg>k</span>,
<span class=summary-sig-arg>n</span>,
<span class=summary-sig-arg>s</span>)</span></code>
<br />
string manipulation garbage</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#addPost" class="summary-sig-name"><code>addPost</code></a>(<span class=summary-sig-arg>klass</span>,
<span class=summary-sig-arg>name</span>,
<span class=summary-sig-arg>func</span>)</span></code>
<br />
hook.addPost(klass, name, func) -> None</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#addPre" class="summary-sig-name"><code>addPre</code></a>(<span class=summary-sig-arg>klass</span>,
<span class=summary-sig-arg>name</span>,
<span class=summary-sig-arg>func</span>)</span></code>
<br />
hook.addPre(klass, name, func) -> None</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#ORIG" class="summary-sig-name"><code>ORIG</code></a>(<span class=summary-sig-arg>k</span>,
<span class=summary-sig-arg>n</span>)</span></code>
<br />
(private) munging to turn a method name into an `original'
identifier</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#POST" class="summary-sig-name"><code>POST</code></a>(<span class=summary-sig-arg>k</span>,
<span class=summary-sig-arg>n</span>)</span></code>
<br />
(private) munging to turn a method name into a
post-hook-method-name</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#PRE" class="summary-sig-name"><code>PRE</code></a>(<span class=summary-sig-arg>k</span>,
<span class=summary-sig-arg>n</span>)</span></code>
<br />
(private) munging to turn a method name into a
pre-hook-method-name</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#removePost" class="summary-sig-name"><code>removePost</code></a>(<span class=summary-sig-arg>klass</span>,
<span class=summary-sig-arg>name</span>,
<span class=summary-sig-arg>func</span>)</span></code>
<br />
hook.removePre(klass, name, func) -> None</td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"> </font></td>
<td><code><span class="summary-sig"><a href="twisted.python.hook.html#removePre" class="summary-sig-name"><code>removePre</code></a>(<span class=summary-sig-arg>klass</span>,
<span class=summary-sig-arg>name</span>,
<span class=summary-sig-arg>func</span>)</span></code>
<br />
hook.removePre(klass, name, func) -> None</td></tr>
</table><br />
<!-- =========== START OF VARIABLE SUMMARY =========== -->
<table class="summary" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="summary">
<th colspan="2">Variable Summary</th></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"><code>str</code></font></td>
<td><b><a href="twisted.python.hook.html#_ORIG"><code>_ORIG</code></a></b> = <span title="'__hook_orig_%s_%s_%s__'"><code><span class="variable-quote">'</span>__hook_orig_%s_%s_%s__<span class="variable-quote">'</span> </code>
</span></td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"><code>str</code></font></td>
<td><b><a href="twisted.python.hook.html#_POST"><code>_POST</code></a></b> = <span title="'__hook_post_%s_%s_%s__'"><code><span class="variable-quote">'</span>__hook_post_%s_%s_%s__<span class="variable-quote">'</span> </code>
</span></td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"><code>str</code></font></td>
<td><b><a href="twisted.python.hook.html#_PRE"><code>_PRE</code></a></b> = <span title="'__hook_pre_%s_%s_%s__'"><code><span class="variable-quote">'</span>__hook_pre_%s_%s_%s__<span class="variable-quote">'</span> </code>
</span></td></tr>
<tr><td align="right" valign="top" width="15%"><font size="-1"><code>str</code></font></td>
<td><b><a href="twisted.python.hook.html#hooked_func"><code>hooked_func</code></a></b> = <span title="'\n\nimport %(module)s\n\ndef %(name)s(*args, **kw):\n klazz = %(module)s.%(klass)s\n for preMethod in klazz.%(preName)s:\n preMethod(*args, **kw)\n try:\n return klazz.%(originalName)s(*args, **kw)\n finally:\n for postMethod in klazz.%(postName)s:\n postMethod(*args, **kw)\n'"><code><span class="variable-quote">'</span>\n\nimport %(module)s\n\ndef %(name)s(*ar<span class="variable-ellipsis">...</span></code>
</span></td></tr>
</table><br />
<!-- =========== START OF FUNCTION DETAILS =========== -->
<table class="details" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="details">
<th colspan="2">Function Details</th></tr>
</table>
<a name="_addHook"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">_addHook</span>(<span class=sig-arg>klass</span>,
<span class=sig-arg>name</span>,
<span class=sig-arg>phase</span>,
<span class=sig-arg>func</span>)</span>
</h3>
(private) adds a hook to a method on a class
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="_dehook"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">_dehook</span>(<span class=sig-arg>klass</span>,
<span class=sig-arg>name</span>)</span>
</h3>
(private) causes a certain method name no longer to be hooked on a
class
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="_enhook"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">_enhook</span>(<span class=sig-arg>klass</span>,
<span class=sig-arg>name</span>)</span>
</h3>
(private) causes a certain method name to be hooked on a class
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="_removeHook"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">_removeHook</span>(<span class=sig-arg>klass</span>,
<span class=sig-arg>name</span>,
<span class=sig-arg>phase</span>,
<span class=sig-arg>func</span>)</span>
</h3>
(private) removes a hook from a method on a class
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="_XXX"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">_XXX</span>(<span class=sig-arg>k</span>,
<span class=sig-arg>n</span>,
<span class=sig-arg>s</span>)</span>
</h3>
string manipulation garbage
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="addPost"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">addPost</span>(<span class=sig-arg>klass</span>,
<span class=sig-arg>name</span>,
<span class=sig-arg>func</span>)</span>
</h3>
<p>hook.addPost(klass, name, func) -> None</p>
Add a function to be called before the method klass.name is
invoked.
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="addPre"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">addPre</span>(<span class=sig-arg>klass</span>,
<span class=sig-arg>name</span>,
<span class=sig-arg>func</span>)</span>
</h3>
<p>hook.addPre(klass, name, func) -> None</p>
Add a function to be called before the method klass.name is
invoked.
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="ORIG"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">ORIG</span>(<span class=sig-arg>k</span>,
<span class=sig-arg>n</span>)</span>
</h3>
(private) munging to turn a method name into an `original'
identifier
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="POST"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">POST</span>(<span class=sig-arg>k</span>,
<span class=sig-arg>n</span>)</span>
</h3>
(private) munging to turn a method name into a
post-hook-method-name
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="PRE"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">PRE</span>(<span class=sig-arg>k</span>,
<span class=sig-arg>n</span>)</span>
</h3>
(private) munging to turn a method name into a
pre-hook-method-name
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="removePost"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">removePost</span>(<span class=sig-arg>klass</span>,
<span class=sig-arg>name</span>,
<span class=sig-arg>func</span>)</span>
</h3>
<p>hook.removePre(klass, name, func) -> None</p>
Remove a function (previously registered with addPost) so that it is
no longer executed after klass.name.
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<a name="removePre"></a>
<table width="100%" class="func-details" bgcolor="#e0e0e0"><tr><td>
<h3><span class="sig"><span class="sig-name">removePre</span>(<span class=sig-arg>klass</span>,
<span class=sig-arg>name</span>,
<span class=sig-arg>func</span>)</span>
</h3>
<p>hook.removePre(klass, name, func) -> None</p>
Remove a function (previously registered with addPre) so that it is
no longer executed before klass.name.
<dl><dt></dt><dd>
</dd></dl>
</td></tr></table>
<br />
<!-- =========== START OF VARIABLE DETAILS =========== -->
<table class="details" border="1" cellpadding="3" cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="details">
<th colspan="2">Variable Details</th></tr>
</table>
<table width="100%" class="var-details" bgcolor="#e0e0e0"><tr><td>
<a name="_ORIG"></a>
<h3>_ORIG</h3>
<dl>
<dt></dt>
<dd>
<dl>
<dt><b>Type:</b></dt>
<dd>
<code>str</code>
</dd>
<span title="'__hook_orig_%s_%s_%s__'"> <dt><b>Value:</b></dt>
<dd><table><tr><td>
<pre class="variable">
<span class="variable-quote">'</span>__hook_orig_%s_%s_%s__<span class="variable-quote">'</span> </pre>
</td></tr></table></dd>
</span> </dl>
</dd>
</dl></td></tr></table>
<table width="100%" class="var-details" bgcolor="#e0e0e0"><tr><td>
<a name="_POST"></a>
<h3>_POST</h3>
<dl>
<dt></dt>
<dd>
<dl>
<dt><b>Type:</b></dt>
<dd>
<code>str</code>
</dd>
<span title="'__hook_post_%s_%s_%s__'"> <dt><b>Value:</b></dt>
<dd><table><tr><td>
<pre class="variable">
<span class="variable-quote">'</span>__hook_post_%s_%s_%s__<span class="variable-quote">'</span> </pre>
</td></tr></table></dd>
</span> </dl>
</dd>
</dl></td></tr></table>
<table width="100%" class="var-details" bgcolor="#e0e0e0"><tr><td>
<a name="_PRE"></a>
<h3>_PRE</h3>
<dl>
<dt></dt>
<dd>
<dl>
<dt><b>Type:</b></dt>
<dd>
<code>str</code>
</dd>
<span title="'__hook_pre_%s_%s_%s__'"> <dt><b>Value:</b></dt>
<dd><table><tr><td>
<pre class="variable">
<span class="variable-quote">'</span>__hook_pre_%s_%s_%s__<span class="variable-quote">'</span> </pre>
</td></tr></table></dd>
</span> </dl>
</dd>
</dl></td></tr></table>
<table width="100%" class="var-details" bgcolor="#e0e0e0"><tr><td>
<a name="hooked_func"></a>
<h3>hooked_func</h3>
<dl>
<dt></dt>
<dd>
<dl>
<dt><b>Type:</b></dt>
<dd>
<code>str</code>
</dd>
<span title="'\n\nimport %(module)s\n\ndef %(name)s(*args, **kw):\n klazz = %(module)s.%(klass)s\n for preMethod in klazz.%(preName)s:\n preMethod(*args, **kw)\n try:\n return klazz.%(originalName)s(*args, **kw)\n finally:\n for postMethod in klazz.%(postName)s:\n postMethod(*args, **kw)\n'"> <dt><b>Value:</b></dt>
<dd><table><tr><td>
<pre class="variable">
<span class="variable-quote">'''</span>
import %(module)s
def %(name)s(*args, **kw):
klazz = %(module)s.%(klass)s
for preMethod in klazz.%(preName)s:
preMethod(*args, **kw)
<span class="variable-ellipsis">...</span> </pre>
</td></tr></table></dd>
</span> </dl>
</dd>
</dl></td></tr></table>
<br />
<!-- =========== START OF NAVBAR =========== -->
<table class="navbar" border="0" width="100%" cellpadding="0" bgcolor="#a0c0ff" cellspacing="0">
<tr valign="center">
<th class="navbar"> <a class="navbar" href="twisted.html">Home</a> </th>
<th class="navbar"> <a class="navbar" href="trees.html">Trees</a> </th>
<th class="navbar"> <a class="navbar" href="indices.html">Index</a> </th>
<th class="navbar"> <a class="navbar" href="help.html">Help</a> </th>
<th class="navbar" align="right" width="100%">
<table border="0" cellpadding="0" cellspacing="0">
<tr><th class="navbar" align="center">
<p class="nomargin">
<a class="navbar" target="_top" href="http://twistedmatrix.com/">Twisted 1.3.0rc1</a>
</p></th></tr></table>
</th>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left"><font size="-2">Generated by Epydoc 2.0 on Sat May 15 20:08:47 2004</font></td>
<td align="right"><a href="http://epydoc.sourceforge.net"
><font size="-2">http://epydoc.sf.net</font></a></td>
</tr>
</table>
</body>
</html>