<!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" />
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-3052036-8']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<title>API Reference — Twiggy</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.4.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<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>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Twiggy"
href="_static/opensearch.xml"/>
<link rel="top" title="Twiggy" href="index.html" />
<link rel="next" title="Glossary" href="glossary.html" />
<link rel="prev" title="Reference Guide" href="reference_guide.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="glossary.html" title="Glossary"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="reference_guide.html" title="Reference Guide"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Twiggy v0.4.4 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="api-reference">
<h1>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h1>
<div class="section" id="module-twiggy">
<span id="global-objects"></span><h2>Global Objects<a class="headerlink" href="#module-twiggy" title="Permalink to this headline">¶</a></h2>
<dl class="data">
<dt id="twiggy.log">
<tt class="descclassname">twiggy.</tt><tt class="descname">log</tt><a class="headerlink" href="#twiggy.log" title="Permalink to this definition">¶</a></dt>
<dd><p>the magic log object</p>
</dd></dl>
<dl class="data">
<dt id="twiggy.internal_log">
<tt class="descclassname">twiggy.</tt><tt class="descname">internal_log</tt><a class="headerlink" href="#twiggy.internal_log" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#twiggy.logger.InternalLogger" title="twiggy.logger.InternalLogger"><tt class="xref py py-obj docutils literal"><span class="pre">InternalLogger</span></tt></a> for reporting errors within Twiggy itself</p>
</dd></dl>
<dl class="data">
<dt id="twiggy.devel_log">
<tt class="descclassname">twiggy.</tt><tt class="descname">devel_log</tt><a class="headerlink" href="#twiggy.devel_log" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#twiggy.logger.InternalLogger" title="twiggy.logger.InternalLogger"><tt class="xref py py-obj docutils literal"><span class="pre">InternalLogger</span></tt></a> for use by developers writing extensions to Twiggy</p>
</dd></dl>
<dl class="data">
<dt id="twiggy.emitters">
<tt class="descclassname">twiggy.</tt><tt class="descname">emitters</tt><a class="headerlink" href="#twiggy.emitters" title="Permalink to this definition">¶</a></dt>
<dd><p>the global <a class="reference internal" href="#twiggy.filters.Emitter" title="twiggy.filters.Emitter"><tt class="xref py py-class docutils literal"><span class="pre">emitters</span></tt></a> dictionary, tied to the <a class="reference internal" href="#twiggy.log" title="twiggy.log"><tt class="xref py py-data docutils literal"><span class="pre">log</span></tt></a></p>
</dd></dl>
<dl class="function">
<dt id="twiggy.addEmitters">
<tt class="descclassname">twiggy.</tt><tt class="descname">addEmitters</tt><big>(</big><em>*tuples</em><big>)</big><a class="headerlink" href="#twiggy.addEmitters" title="Permalink to this definition">¶</a></dt>
<dd><p>Add multiple emitters.
<tt class="docutils literal"><span class="pre">tuples</span></tt> should be <tt class="docutils literal"><span class="pre">(name_of_emitter,</span> <span class="pre">min_level,</span> <span class="pre">filter,</span> <span class="pre">output)</span></tt>. The last three are passed to <a class="reference internal" href="#twiggy.filters.Emitter" title="twiggy.filters.Emitter"><tt class="xref py py-class docutils literal"><span class="pre">Emitter</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="twiggy.quickSetup">
<tt class="descclassname">twiggy.</tt><tt class="descname">quickSetup</tt><big>(</big><em>min_level=<LogLevel DEBUG></em>, <em>file=None</em>, <em>msg_buffer=0</em><big>)</big><a class="headerlink" href="#twiggy.quickSetup" title="Permalink to this definition">¶</a></dt>
<dd><p>Quickly set up <a class="reference internal" href="#twiggy.emitters" title="twiggy.emitters"><tt class="xref py py-obj docutils literal"><span class="pre">emitters</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>min_level</strong> (<em>LogLevel</em>) – lowest message level to cause output</li>
<li><strong>file</strong> (<em>string</em>) – filename to log to, or <tt class="docutils literal"><span class="pre">sys.stdout</span></tt>, or <tt class="docutils literal"><span class="pre">sys.stderr</span></tt>. <tt class="xref docutils literal"><span class="pre">None</span></tt> means standard error.</li>
<li><strong>msg_buffer</strong> (<em>int</em>) – number of messages to buffer, see <tt class="xref py py-obj docutils literal"><span class="pre">outputs.AsyncOutput.msg_buffer</span></tt></li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
<div class="section" id="module-twiggy.features">
<span id="features"></span><h2>Features<a class="headerlink" href="#module-twiggy.features" title="Permalink to this headline">¶</a></h2>
<p>Optional additions of logging functionality</p>
<div class="section" id="module-twiggy.features.procinfo">
<span id="procinfo"></span><h3>procinfo<a class="headerlink" href="#module-twiggy.features.procinfo" title="Permalink to this headline">¶</a></h3>
<p>Logging feature to add information about process, etc.</p>
<dl class="function">
<dt id="twiggy.features.procinfo.procinfo">
<tt class="descclassname">twiggy.features.procinfo.</tt><tt class="descname">procinfo</tt><big>(</big><em>self</em><big>)</big><a class="headerlink" href="#twiggy.features.procinfo.procinfo" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds the following fields:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Hostname :</th><td class="field-body">current hostname</td>
</tr>
<tr class="field"><th class="field-name">Pid :</th><td class="field-body">current process id</td>
</tr>
<tr class="field"><th class="field-name">Thread :</th><td class="field-body">current thread name</td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
<div class="section" id="module-twiggy.features.socket">
<span id="socket"></span><h3>socket<a class="headerlink" href="#module-twiggy.features.socket" title="Permalink to this headline">¶</a></h3>
<p>Logging feature to add information about a socket</p>
<dl class="function">
<dt id="twiggy.features.socket.socket">
<tt class="descclassname">twiggy.features.socket.</tt><tt class="descname">socket</tt><big>(</big><em>self</em>, <em>s</em><big>)</big><a class="headerlink" href="#twiggy.features.socket.socket" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds the following fields:</p>
<blockquote>
<div><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">ip_addr:</th><td class="field-body">numeric IP address</td>
</tr>
<tr class="field"><th class="field-name">port:</th><td class="field-body">port number</td>
</tr>
<tr class="field"><th class="field-name">host:</th><td class="field-body">peer hostname, as returned by <tt class="xref py py-func docutils literal"><span class="pre">getnameinfo()</span></tt></td>
</tr>
<tr class="field"><th class="field-name">service:</th><td class="field-body">the human readable name of the service on <tt class="docutils literal"><span class="pre">port</span></tt></td>
</tr>
</tbody>
</table>
</div></blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>s</strong> (<em>socket</em>) – the socket to extract information from</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="twiggy.features.socket.socket_minimal">
<tt class="descclassname">twiggy.features.socket.</tt><tt class="descname">socket_minimal</tt><big>(</big><em>self</em>, <em>s</em><big>)</big><a class="headerlink" href="#twiggy.features.socket.socket_minimal" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#twiggy.features.socket.socket" title="twiggy.features.socket.socket"><tt class="xref py py-obj docutils literal"><span class="pre">socket</span></tt></a>, but only log <tt class="docutils literal"><span class="pre">ip_addr</span></tt> and <tt class="docutils literal"><span class="pre">port</span></tt></p>
</dd></dl>
</div>
</div>
<div class="section" id="module-twiggy.filters">
<span id="filters"></span><h2>Filters<a class="headerlink" href="#module-twiggy.filters" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="twiggy.filters.filter">
<tt class="descclassname">twiggy.filters.</tt><tt class="descname">filter</tt><big>(</big><em>msg : Message</em><big>)</big> → bool<a class="headerlink" href="#twiggy.filters.filter" title="Permalink to this definition">¶</a></dt>
<dd><p>A <em>filter</em> is any function that takes a <a class="reference internal" href="#twiggy.message.Message" title="twiggy.message.Message"><tt class="xref py py-class docutils literal"><span class="pre">Message</span></tt></a> and returns True if it should be <a class="reference internal" href="#twiggy.filters.Emitter" title="twiggy.filters.Emitter"><tt class="xref py py-class docutils literal"><span class="pre">emitted</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="twiggy.filters.msgFilter">
<tt class="descclassname">twiggy.filters.</tt><tt class="descname">msgFilter</tt><big>(</big><em>x</em><big>)</big> → filter<a class="headerlink" href="#twiggy.filters.msgFilter" title="Permalink to this definition">¶</a></dt>
<dd><p>create a <a class="reference internal" href="#twiggy.filters.filter" title="twiggy.filters.filter"><tt class="xref py py-obj docutils literal"><span class="pre">filter</span></tt></a> intelligently</p>
<p>You may pass:</p>
<blockquote>
<div><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">None, True:</th><td class="field-body">the filter will always return True</td>
</tr>
<tr class="field"><th class="field-name">False:</th><td class="field-body">the filter will always return False</td>
</tr>
<tr class="field"><th class="field-name">string:</th><td class="field-body">compiled into a regex</td>
</tr>
<tr class="field"><th class="field-name">regex:</th><td class="field-body"><tt class="docutils literal"><span class="pre">match()</span></tt> against the message text</td>
</tr>
<tr class="field"><th class="field-name">callable:</th><td class="field-body">returned as is</td>
</tr>
<tr class="field"><th class="field-name">list:</th><td class="field-body">apply <a class="reference internal" href="#twiggy.filters.msgFilter" title="twiggy.filters.msgFilter"><tt class="xref py py-obj docutils literal"><span class="pre">msgFilter</span></tt></a> to each element, and <tt class="docutils literal"><span class="pre">all()</span></tt> the results</td>
</tr>
</tbody>
</table>
</div></blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Return type:</th><td class="field-body"><a class="reference internal" href="#twiggy.filters.filter" title="twiggy.filters.filter"><tt class="xref py py-obj docutils literal"><span class="pre">filter</span></tt></a> function</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="twiggy.filters.names">
<tt class="descclassname">twiggy.filters.</tt><tt class="descname">names</tt><big>(</big><em>*names</em><big>)</big> → filter<a class="headerlink" href="#twiggy.filters.names" title="Permalink to this definition">¶</a></dt>
<dd><p>create a <a class="reference internal" href="#twiggy.filters.filter" title="twiggy.filters.filter"><tt class="xref py py-obj docutils literal"><span class="pre">filter</span></tt></a>, which gives True if the messsage’s name equals any of those provided</p>
<p><tt class="docutils literal"><span class="pre">names</span></tt> will be stored as an attribute on the filter.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>names</strong> (<em>strings</em>) – names to match</td>
</tr>
<tr class="field"><th class="field-name">Return type:</th><td class="field-body"><a class="reference internal" href="#twiggy.filters.filter" title="twiggy.filters.filter"><tt class="xref py py-obj docutils literal"><span class="pre">filter</span></tt></a> function</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="twiggy.filters.glob_names">
<tt class="descclassname">twiggy.filters.</tt><tt class="descname">glob_names</tt><big>(</big><em>*names</em><big>)</big> → filter<a class="headerlink" href="#twiggy.filters.glob_names" title="Permalink to this definition">¶</a></dt>
<dd><p>create a <a class="reference internal" href="#twiggy.filters.filter" title="twiggy.filters.filter"><tt class="xref py py-obj docutils literal"><span class="pre">filter</span></tt></a>, which gives True if the messsage’s name globs those provided.</p>
<p><tt class="docutils literal"><span class="pre">names</span></tt> will be stored as an attribute on the filter.</p>
<p>This is probably quite a bit slower than <a class="reference internal" href="#twiggy.filters.names" title="twiggy.filters.names"><tt class="xref py py-func docutils literal"><span class="pre">names()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>names</strong> (<em>strings</em>) – glob patterns.</td>
</tr>
<tr class="field"><th class="field-name">Return type:</th><td class="field-body"><a class="reference internal" href="#twiggy.filters.filter" title="twiggy.filters.filter"><tt class="xref py py-obj docutils literal"><span class="pre">filter</span></tt></a> function</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="twiggy.filters.Emitter">
<em class="property">class </em><tt class="descclassname">twiggy.filters.</tt><tt class="descname">Emitter</tt><a class="headerlink" href="#twiggy.filters.Emitter" title="Permalink to this definition">¶</a></dt>
<dd><p>Hold and manage an <a class="reference internal" href="#twiggy.outputs.Output" title="twiggy.outputs.Output"><tt class="xref py py-class docutils literal"><span class="pre">Output</span></tt></a> and associated <a class="reference internal" href="#twiggy.filters.filter" title="twiggy.filters.filter"><tt class="xref py py-func docutils literal"><span class="pre">filter()</span></tt></a></p>
<dl class="attribute">
<dt id="twiggy.filters.Emitter.min_level">
<tt class="descname">min_level</tt><a class="headerlink" href="#twiggy.filters.Emitter.min_level" title="Permalink to this definition">¶</a></dt>
<dd><p>only emit if greater than this <a class="reference internal" href="#twiggy.levels.LogLevel" title="twiggy.levels.LogLevel"><tt class="xref py py-obj docutils literal"><span class="pre">LogLevel</span></tt></a></p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.filters.Emitter.filter">
<tt class="descname">filter</tt><a class="headerlink" href="#twiggy.filters.Emitter.filter" title="Permalink to this definition">¶</a></dt>
<dd><p>arbitrary <a class="reference internal" href="#twiggy.filters.filter" title="twiggy.filters.filter"><tt class="xref py py-func docutils literal"><span class="pre">filter()</span></tt></a> on message contents. Assigning to this attribute is <a class="reference internal" href="#twiggy.filters.msgFilter" title="twiggy.filters.msgFilter"><tt class="xref py py-func docutils literal"><span class="pre">intelligent</span></tt></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.filters.Emitter._output">
<tt class="descname">_output</tt><a class="headerlink" href="#twiggy.filters.Emitter._output" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#twiggy.outputs.Output" title="twiggy.outputs.Output"><tt class="xref py py-obj docutils literal"><span class="pre">Output</span></tt></a> to emit messages to. Do not modify.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="module-twiggy.formats">
<span id="formats"></span><h2>Formats<a class="headerlink" href="#module-twiggy.formats" title="Permalink to this headline">¶</a></h2>
<p id="format-function"><em>Formats</em> are single-argument callables that take a <a class="reference internal" href="#twiggy.message.Message" title="twiggy.message.Message"><tt class="xref py py-obj docutils literal"><span class="pre">Message</span></tt></a> and return an object appropriate for the <a class="reference internal" href="#twiggy.outputs.Output" title="twiggy.outputs.Output"><tt class="xref py py-obj docutils literal"><span class="pre">Output</span></tt></a> they are assigned to.</p>
<dl class="class">
<dt id="twiggy.formats.LineFormat">
<em class="property">class </em><tt class="descclassname">twiggy.formats.</tt><tt class="descname">LineFormat</tt><big>(</big><em>separator=':'</em>, <em>traceback_prefix='\nTRACE'</em>, <em>conversion=line_conversion</em><big>)</big><a class="headerlink" href="#twiggy.formats.LineFormat" title="Permalink to this definition">¶</a></dt>
<dd><dl class="attribute">
<dt id="twiggy.formats.LineFormat.separator">
<tt class="descname">separator</tt><a class="headerlink" href="#twiggy.formats.LineFormat.separator" title="Permalink to this definition">¶</a></dt>
<dd><p>string to separate line parts. Defaults to <tt class="docutils literal"><span class="pre">:</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.formats.LineFormat.traceback_prefix">
<tt class="descname">traceback_prefix</tt><a class="headerlink" href="#twiggy.formats.LineFormat.traceback_prefix" title="Permalink to this definition">¶</a></dt>
<dd><p>string to prepend to traceback lines. Defaults to <tt class="docutils literal"><span class="pre">\nTRACE</span></tt>.</p>
<p id="folding-exceptions">Set to <tt class="docutils literal"><span class="pre">'\\n'</span></tt> (double backslash n) to roll up tracebacks to a single line.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.formats.LineFormat.conversion">
<tt class="descname">conversion</tt><a class="headerlink" href="#twiggy.formats.LineFormat.conversion" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#twiggy.lib.converter.ConversionTable" title="twiggy.lib.converter.ConversionTable"><tt class="xref py py-class docutils literal"><span class="pre">ConversionTable</span></tt></a> used to format <a class="reference internal" href="#twiggy.message.Message.fields" title="twiggy.message.Message.fields"><tt class="xref py py-attr docutils literal"><span class="pre">fields</span></tt></a>. Defaults to <a class="reference internal" href="#twiggy.formats.line_conversion" title="twiggy.formats.line_conversion"><tt class="xref py py-data docutils literal"><span class="pre">line_conversion</span></tt></a></p>
</dd></dl>
<dl class="method">
<dt id="twiggy.formats.LineFormat.format_text">
<tt class="descname">format_text</tt><big>(</big><em>msg</em><big>)</big><a class="headerlink" href="#twiggy.formats.LineFormat.format_text" title="Permalink to this definition">¶</a></dt>
<dd><p>format the text part of a message</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.formats.LineFormat.format_fields">
<tt class="descname">format_fields</tt><big>(</big><em>msg</em><big>)</big><a class="headerlink" href="#twiggy.formats.LineFormat.format_fields" title="Permalink to this definition">¶</a></dt>
<dd><p>format the fields of a message</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.formats.LineFormat.format_traceback">
<tt class="descname">format_traceback</tt><big>(</big><em>msg</em><big>)</big><a class="headerlink" href="#twiggy.formats.LineFormat.format_traceback" title="Permalink to this definition">¶</a></dt>
<dd><p>format the traceback part of a message</p>
</dd></dl>
</dd></dl>
<dl class="data">
<dt id="twiggy.formats.line_conversion">
<tt class="descclassname">twiggy.formats.</tt><tt class="descname">line_conversion</tt><a class="headerlink" href="#twiggy.formats.line_conversion" title="Permalink to this definition">¶</a></dt>
<dd><p>a default line-oriented <a class="reference internal" href="#twiggy.lib.converter.ConversionTable" title="twiggy.lib.converter.ConversionTable"><tt class="xref py py-class docutils literal"><span class="pre">ConversionTable</span></tt></a>. Produces a nice-looking string from <a class="reference internal" href="#twiggy.message.Message.fields" title="twiggy.message.Message.fields"><tt class="xref py py-attr docutils literal"><span class="pre">fields</span></tt></a>.</p>
<p>Fields are separated by a colon (<tt class="docutils literal"><span class="pre">:</span></tt>). Resultant string includes:</p>
<blockquote>
<div><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">time:</th><td class="field-body">in iso8601 format (required)</td>
</tr>
<tr class="field"><th class="field-name">level:</th><td class="field-body">message level (required)</td>
</tr>
<tr class="field"><th class="field-name">name:</th><td class="field-body">logger name</td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>Remaining fields are sorted alphabetically and formatted as <tt class="docutils literal"><span class="pre">key=value</span></tt></p>
</dd></dl>
<dl class="data">
<dt id="twiggy.formats.line_format">
<tt class="descclassname">twiggy.formats.</tt><tt class="descname">line_format</tt><a class="headerlink" href="#twiggy.formats.line_format" title="Permalink to this definition">¶</a></dt>
<dd><p>a default <a class="reference internal" href="#twiggy.formats.LineFormat" title="twiggy.formats.LineFormat"><tt class="xref py py-class docutils literal"><span class="pre">LineFormat</span></tt></a> for output to a file. <a class="reference internal" href="logging.html#sample-file-output"><em>Sample output</em></a>.</p>
<p>Fields are formatted using <a class="reference internal" href="#twiggy.formats.line_conversion" title="twiggy.formats.line_conversion"><tt class="xref py py-data docutils literal"><span class="pre">line_conversion</span></tt></a> and separated from the message <a class="reference internal" href="#twiggy.message.Message.text" title="twiggy.message.Message.text"><tt class="xref py py-attr docutils literal"><span class="pre">text</span></tt></a> by a colon (<tt class="docutils literal"><span class="pre">:</span></tt>). Traceback lines are prefixed by <tt class="docutils literal"><span class="pre">TRACE</span></tt>.</p>
</dd></dl>
<dl class="data">
<dt id="twiggy.formats.shell_conversion">
<tt class="descclassname">twiggy.formats.</tt><tt class="descname">shell_conversion</tt><a class="headerlink" href="#twiggy.formats.shell_conversion" title="Permalink to this definition">¶</a></dt>
<dd><p>a default line-oriented <a class="reference internal" href="#twiggy.lib.converter.ConversionTable" title="twiggy.lib.converter.ConversionTable"><tt class="xref py py-class docutils literal"><span class="pre">ConversionTable</span></tt></a> for use in the shell. Returns the same string as <a class="reference internal" href="#twiggy.formats.line_conversion" title="twiggy.formats.line_conversion"><tt class="xref py py-data docutils literal"><span class="pre">line_conversion</span></tt></a> but drops the <tt class="docutils literal"><span class="pre">time</span></tt> field.</p>
</dd></dl>
<dl class="data">
<dt id="twiggy.formats.shell_format">
<tt class="descclassname">twiggy.formats.</tt><tt class="descname">shell_format</tt><a class="headerlink" href="#twiggy.formats.shell_format" title="Permalink to this definition">¶</a></dt>
<dd><p>a default <a class="reference internal" href="#twiggy.formats.LineFormat" title="twiggy.formats.LineFormat"><tt class="xref py py-class docutils literal"><span class="pre">LineFormat</span></tt></a> for use in the shell. Same as <a class="reference internal" href="#twiggy.formats.line_format" title="twiggy.formats.line_format"><tt class="xref py py-data docutils literal"><span class="pre">line_format</span></tt></a> but uses <a class="reference internal" href="#twiggy.formats.shell_conversion" title="twiggy.formats.shell_conversion"><tt class="xref py py-data docutils literal"><span class="pre">shell_conversion</span></tt></a> for <a class="reference internal" href="#twiggy.message.Message.fields" title="twiggy.message.Message.fields"><tt class="xref py py-attr docutils literal"><span class="pre">fields</span></tt></a>.</p>
</dd></dl>
</div>
<div class="section" id="module-twiggy.levels">
<span id="levels"></span><h2>Levels<a class="headerlink" href="#module-twiggy.levels" title="Permalink to this headline">¶</a></h2>
<p>Levels include (increasing severity): <tt class="docutils literal"><span class="pre">DEBUG</span></tt>, <tt class="docutils literal"><span class="pre">INFO</span></tt>, <tt class="docutils literal"><span class="pre">WARNING</span></tt>, <tt class="docutils literal"><span class="pre">ERROR</span></tt>, <tt class="docutils literal"><span class="pre">CRITICAL</span></tt>, <tt class="docutils literal"><span class="pre">DISABLED</span></tt></p>
<dl class="class">
<dt id="twiggy.levels.LogLevel">
<em class="property">class </em><tt class="descclassname">twiggy.levels.</tt><tt class="descname">LogLevel</tt><big>(</big><em>name</em>, <em>value</em><big>)</big><a class="headerlink" href="#twiggy.levels.LogLevel" title="Permalink to this definition">¶</a></dt>
<dd><p>A log level. Users should <em>not</em> create new instances.</p>
<p>Levels are opaque; they may be compared to each other, but nothing else.</p>
</dd></dl>
<dl class="function">
<dt id="twiggy.levels.name2level">
<tt class="descclassname">twiggy.levels.</tt><tt class="descname">name2level</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#twiggy.levels.name2level" title="Permalink to this definition">¶</a></dt>
<dd><p>return a <a class="reference internal" href="#twiggy.levels.LogLevel" title="twiggy.levels.LogLevel"><tt class="xref py py-obj docutils literal"><span class="pre">LogLevel</span></tt></a> from a case-insensitve string</p>
</dd></dl>
</div>
<div class="section" id="module-twiggy.lib">
<span id="library"></span><h2>Library<a class="headerlink" href="#module-twiggy.lib" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="twiggy.lib.iso8601time">
<tt class="descclassname">twiggy.lib.</tt><tt class="descname">iso8601time</tt><big>(</big><em>gmtime=None</em><big>)</big><a class="headerlink" href="#twiggy.lib.iso8601time" title="Permalink to this definition">¶</a></dt>
<dd><p>convert time to ISO 8601 format - it sucks less!</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>gmtime</strong> (<em>time.struct_time</em>) – time tuple. If None, use <tt class="docutils literal"><span class="pre">time.gmtime()</span></tt> (UTC)</td>
</tr>
</tbody>
</table>
<p>XXX timezone is not supported</p>
</dd></dl>
<dl class="function">
<dt id="twiggy.lib.thread_name">
<tt class="descclassname">twiggy.lib.</tt><tt class="descname">thread_name</tt><big>(</big><big>)</big><a class="headerlink" href="#twiggy.lib.thread_name" title="Permalink to this definition">¶</a></dt>
<dd><p>return the name of the current thread</p>
</dd></dl>
<div class="section" id="module-twiggy.lib.converter">
<span id="converter"></span><h3>Converter<a class="headerlink" href="#module-twiggy.lib.converter" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="twiggy.lib.converter.Converter">
<em class="property">class </em><tt class="descclassname">twiggy.lib.converter.</tt><tt class="descname">Converter</tt><big>(</big><em>key</em>, <em>convertValue</em>, <em>convertItem</em>, <em>required=False</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.Converter" title="Permalink to this definition">¶</a></dt>
<dd><p>Holder for <a class="reference internal" href="#twiggy.lib.converter.ConversionTable" title="twiggy.lib.converter.ConversionTable"><tt class="xref py py-obj docutils literal"><span class="pre">ConversionTable</span></tt></a> items</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Variables:</th><td class="field-body"><ul class="first last simple">
<li><strong>key</strong> – the key to apply the conversion to</li>
<li><strong>convertValue</strong> (<em>function</em>) – one-argument function to convert the value</li>
<li><strong>convertItem</strong> (<em>function</em>) – two-argument function converting the key & converted value</li>
<li><strong>required</strong> (<em>bool</em>) – is the item required to present. Items are optional by default.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="twiggy.lib.converter.ConversionTable">
<em class="property">class </em><tt class="descclassname">twiggy.lib.converter.</tt><tt class="descname">ConversionTable</tt><big>(</big><em>seq</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert data dictionaries using <a class="reference internal" href="#twiggy.lib.converter.Converter" title="twiggy.lib.converter.Converter"><tt class="xref py py-obj docutils literal"><span class="pre">Converters</span></tt></a></p>
<p>For each item in the dictionary to be converted:</p>
<ol class="arabic simple">
<li>Find one or more corresponding converters <tt class="docutils literal"><span class="pre">c</span></tt> by matching key.</li>
<li>Build a list of converted items by calling <tt class="docutils literal"><span class="pre">c.convertItem(item_key,</span> <span class="pre">c.convertValue(item_value))</span></tt>. The list will have items in the same order as converters were supplied.</li>
<li>Dict items for which no converter was found are sorted by key and passed to <a class="reference internal" href="#twiggy.lib.converter.ConversionTable.genericValue" title="twiggy.lib.converter.ConversionTable.genericValue"><tt class="xref py py-obj docutils literal"><span class="pre">genericValue</span></tt></a> / <a class="reference internal" href="#twiggy.lib.converter.ConversionTable.genericItem" title="twiggy.lib.converter.ConversionTable.genericItem"><tt class="xref py py-obj docutils literal"><span class="pre">genericItem</span></tt></a>. These items are appended to the list from step 2.</li>
<li>If any required items are missing, <tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt> is raised.</li>
<li>The resulting list of converted items is passed to <a class="reference internal" href="#twiggy.lib.converter.ConversionTable.aggregate" title="twiggy.lib.converter.ConversionTable.aggregate"><tt class="xref py py-obj docutils literal"><span class="pre">aggregate</span></tt></a>. The value it returns is the result of the conversion.</li>
</ol>
<p>Users may override <a class="reference internal" href="#twiggy.lib.converter.ConversionTable.genericValue" title="twiggy.lib.converter.ConversionTable.genericValue"><tt class="xref py py-obj docutils literal"><span class="pre">genericValue</span></tt></a>/<a class="reference internal" href="#twiggy.lib.converter.ConversionTable.genericItem" title="twiggy.lib.converter.ConversionTable.genericItem"><tt class="xref py py-obj docutils literal"><span class="pre">genericItem</span></tt></a>/<a class="reference internal" href="#twiggy.lib.converter.ConversionTable.aggregate" title="twiggy.lib.converter.ConversionTable.aggregate"><tt class="xref py py-obj docutils literal"><span class="pre">aggregate</span></tt></a> by subclassing or assigning a new function on a ConversionTable instance.</p>
<p>Really, it’s <a class="reference internal" href="reference_guide.html#conversion-table-example"><em>pretty intuitive</em></a>.</p>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.__init__">
<tt class="descname">__init__</tt><big>(</big><em>seq=None</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.__init__" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>seq</strong> – a sequence of Converters</td>
</tr>
</tbody>
</table>
<p>You may also pass 3-or-4 item arg tuples or kwarg dicts (which will be used to create <a class="reference internal" href="#twiggy.lib.converter.Converter" title="twiggy.lib.converter.Converter"><tt class="xref py py-obj docutils literal"><span class="pre">Converters</span></tt></a>)</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.convert">
<tt class="descname">convert</tt><big>(</big><em>d</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.convert" title="Permalink to this definition">¶</a></dt>
<dd><p>do the conversion</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>d</strong> (<em>dict</em>) – the data to convert. Keys should be strings.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.genericValue">
<tt class="descname">genericValue</tt><big>(</big><em>value</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.genericValue" title="Permalink to this definition">¶</a></dt>
<dd><p>convert values for which no specific <a class="reference internal" href="#twiggy.lib.converter.Converter" title="twiggy.lib.converter.Converter"><tt class="xref py py-obj docutils literal"><span class="pre">Converter</span></tt></a> is supplied</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.genericItem">
<tt class="descname">genericItem</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.genericItem" title="Permalink to this definition">¶</a></dt>
<dd><p>convert items for which no specific <a class="reference internal" href="#twiggy.lib.converter.Converter" title="twiggy.lib.converter.Converter"><tt class="xref py py-obj docutils literal"><span class="pre">Converter</span></tt></a> is supplied</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.aggregate">
<tt class="descname">aggregate</tt><big>(</big><em>converteds</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.aggregate" title="Permalink to this definition">¶</a></dt>
<dd><p>aggregate list of converted items. The return value of <a class="reference internal" href="#twiggy.lib.converter.ConversionTable.convert" title="twiggy.lib.converter.ConversionTable.convert"><tt class="xref py py-obj docutils literal"><span class="pre">convert</span></tt></a></p>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.copy">
<tt class="descname">copy</tt><big>(</big><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.copy" title="Permalink to this definition">¶</a></dt>
<dd><p>make an independent copy of this ConversionTable</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.get">
<tt class="descname">get</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.get" title="Permalink to this definition">¶</a></dt>
<dd><p>return the <em>first</em> converter for key</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.getAll">
<tt class="descname">getAll</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.getAll" title="Permalink to this definition">¶</a></dt>
<dd><p>return a list of all converters for key</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.add">
<tt class="descname">add</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.add" title="Permalink to this definition">¶</a></dt>
<dd><p>Append a <a class="reference internal" href="#twiggy.lib.converter.Converter" title="twiggy.lib.converter.Converter"><tt class="xref py py-obj docutils literal"><span class="pre">Converter</span></tt></a>. <tt class="docutils literal"><span class="pre">args</span></tt> & <tt class="docutils literal"><span class="pre">kwargs</span></tt> will be passed through to its constructor</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.lib.converter.ConversionTable.delete">
<tt class="descname">delete</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#twiggy.lib.converter.ConversionTable.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>delete the <em>all</em> of the converters for key</p>
</dd></dl>
</dd></dl>
</div>
</div>
<div class="section" id="logger">
<h2>Logger<a class="headerlink" href="#logger" title="Permalink to this headline">¶</a></h2>
<p>Loggers should not be created directly by users; use the global <a class="reference internal" href="#twiggy.log" title="twiggy.log"><tt class="xref py py-data docutils literal"><span class="pre">log</span></tt></a> instead.</p>
<span class="target" id="module-twiggy.logger"></span><dl class="class">
<dt id="twiggy.logger.BaseLogger">
<em class="property">class </em><tt class="descclassname">twiggy.logger.</tt><tt class="descname">BaseLogger</tt><big>(</big><em>fields=None</em>, <em>options=None</em>, <em>min_level=None</em><big>)</big><a class="headerlink" href="#twiggy.logger.BaseLogger" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for loggers</p>
<dl class="attribute">
<dt id="twiggy.logger.BaseLogger._fields">
<tt class="descname">_fields</tt><a class="headerlink" href="#twiggy.logger.BaseLogger._fields" title="Permalink to this definition">¶</a></dt>
<dd><p>dictionary of bound fields for <a class="reference internal" href="glossary.html#term-structured-logging"><em class="xref std std-term">structured logging</em></a>.
By default, contains a single field <tt class="docutils literal"><span class="pre">time</span></tt> with value <tt class="docutils literal"><span class="pre">time.gmtime()</span></tt>. This function will be called for each message emitted, populating the field with the current <tt class="docutils literal"><span class="pre">time.struct_time</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.logger.BaseLogger._options">
<tt class="descname">_options</tt><a class="headerlink" href="#twiggy.logger.BaseLogger._options" title="Permalink to this definition">¶</a></dt>
<dd><p>dictionary of bound <a class="reference internal" href="#message-options"><em>options</em></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.logger.BaseLogger.min_level">
<tt class="descname">min_level</tt><a class="headerlink" href="#twiggy.logger.BaseLogger.min_level" title="Permalink to this definition">¶</a></dt>
<dd><p>minimum <a class="reference internal" href="#twiggy.levels.LogLevel" title="twiggy.levels.LogLevel"><tt class="xref py py-class docutils literal"><span class="pre">LogLevel</span></tt></a> for which to emit. For optimization purposes only.</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.fields">
<tt class="descname">fields</tt><big>(</big><em>**kwargs</em><big>)</big> → bound Logger<a class="headerlink" href="#twiggy.logger.BaseLogger.fields" title="Permalink to this definition">¶</a></dt>
<dd><p>bind fields for <a class="reference internal" href="glossary.html#term-structured-logging"><em class="xref std std-term">structured logging</em></a>. <tt class="docutils literal"><span class="pre">kwargs</span></tt> are interpreted as names/values of fields.</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.fieldsDict">
<tt class="descname">fieldsDict</tt><big>(</big><em>d</em><big>)</big> → bound Logger<a class="headerlink" href="#twiggy.logger.BaseLogger.fieldsDict" title="Permalink to this definition">¶</a></dt>
<dd><p>bind fields for structured logging. Use this instead of <a class="reference internal" href="#twiggy.logger.BaseLogger.fields" title="twiggy.logger.BaseLogger.fields"><tt class="xref py py-obj docutils literal"><span class="pre">fields</span></tt></a> if you have keys which are not valid Python identifiers.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>d</strong> (<em>dict</em>) – dictionary of fields. Keys should be strings.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.options">
<tt class="descname">options</tt><big>(</big><em>**kwargs</em><big>)</big> → bound Logger<a class="headerlink" href="#twiggy.logger.BaseLogger.options" title="Permalink to this definition">¶</a></dt>
<dd><p>bind <a class="reference internal" href="#message-options"><em>options</em></a> for message creation.</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.trace">
<tt class="descname">trace</tt><big>(</big><em>trace='error'</em><big>)</big> → bound Logger<a class="headerlink" href="#twiggy.logger.BaseLogger.trace" title="Permalink to this definition">¶</a></dt>
<dd><p>convenience method to enable <a class="reference internal" href="#message-options"><em>traceback logging</em></a></p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.name">
<tt class="descname">name</tt><big>(</big><em>name</em><big>)</big> → bound Logger<a class="headerlink" href="#twiggy.logger.BaseLogger.name" title="Permalink to this definition">¶</a></dt>
<dd><p>convenvience method to bind <tt class="docutils literal"><span class="pre">name</span></tt> field</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.struct">
<tt class="descname">struct</tt><big>(</big><em>**kwargs</em><big>)</big> → bound Logger<a class="headerlink" href="#twiggy.logger.BaseLogger.struct" title="Permalink to this definition">¶</a></dt>
<dd><p>convenience method for <a class="reference internal" href="glossary.html#term-structured-logging"><em class="xref std std-term">structured logging</em></a>. Calls <a class="reference internal" href="#twiggy.logger.BaseLogger.fields" title="twiggy.logger.BaseLogger.fields"><tt class="xref py py-meth docutils literal"><span class="pre">fields()</span></tt></a> and emits at <a class="reference internal" href="#twiggy.logger.BaseLogger.info" title="twiggy.logger.BaseLogger.info"><tt class="xref py py-obj docutils literal"><span class="pre">info</span></tt></a></p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.structDict">
<tt class="descname">structDict</tt><big>(</big><em>d</em><big>)</big> → bound Logger<a class="headerlink" href="#twiggy.logger.BaseLogger.structDict" title="Permalink to this definition">¶</a></dt>
<dd><p>convenience method for <a class="reference internal" href="glossary.html#term-structured-logging"><em class="xref std std-term">structured logging</em></a>. Use instead of <a class="reference internal" href="#twiggy.logger.BaseLogger.struct" title="twiggy.logger.BaseLogger.struct"><tt class="xref py py-obj docutils literal"><span class="pre">struct</span></tt></a> if you have keys which are not valid Python identifiers.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>d</strong> (<em>dict</em>) – dictionary of fields. Keys should be strings.</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>The following methods cause messages to be emitted. <tt class="docutils literal"><span class="pre">format_spec</span></tt> is a template string into which <tt class="docutils literal"><span class="pre">args</span></tt> and <tt class="docutils literal"><span class="pre">kwargs</span></tt> will be substitued.</p>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.debug">
<tt class="descname">debug</tt><big>(</big><em>format_spec=''</em>, <em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#twiggy.logger.BaseLogger.debug" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit at <tt class="docutils literal"><span class="pre">DEBUG</span></tt> level</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.info">
<tt class="descname">info</tt><big>(</big><em>format_spec=''</em>, <em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#twiggy.logger.BaseLogger.info" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit at <tt class="docutils literal"><span class="pre">INFO</span></tt> level</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.warning">
<tt class="descname">warning</tt><big>(</big><em>format_spec=''</em>, <em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#twiggy.logger.BaseLogger.warning" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit at <tt class="docutils literal"><span class="pre">WARNING</span></tt> level</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.error">
<tt class="descname">error</tt><big>(</big><em>format_spec=''</em>, <em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#twiggy.logger.BaseLogger.error" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit at <tt class="docutils literal"><span class="pre">ERROR</span></tt> level</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.logger.BaseLogger.critical">
<tt class="descname">critical</tt><big>(</big><em>format_spec=''</em>, <em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#twiggy.logger.BaseLogger.critical" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit at <tt class="docutils literal"><span class="pre">CRITICAL</span></tt> level</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="twiggy.logger.Logger">
<em class="property">class </em><tt class="descclassname">twiggy.logger.</tt><tt class="descname">Logger</tt><big>(</big><em>fields=None</em>, <em>options=None</em>, <em>min_level=None</em><big>)</big><a class="headerlink" href="#twiggy.logger.Logger" title="Permalink to this definition">¶</a></dt>
<dd><p>Logger for end-users. The type of the magic <a class="reference internal" href="#twiggy.log" title="twiggy.log"><tt class="xref py py-data docutils literal"><span class="pre">log</span></tt></a></p>
<dl class="attribute">
<dt id="twiggy.logger.Logger.filter">
<tt class="descname">filter</tt><a class="headerlink" href="#twiggy.logger.Logger.filter" title="Permalink to this definition">¶</a></dt>
<dd><p>Filter on <tt class="docutils literal"><span class="pre">format_spec</span></tt>. For optimization purposes only. Should have the following signature:</p>
<dl class="function">
<dt>
<tt class="descname">func</tt><big>(</big><em>format_spec : string</em><big>)</big> → bool</dt>
<dd><p>Should the message be emitted.</p>
</dd></dl>
</dd></dl>
<dl class="classmethod">
<dt id="twiggy.logger.Logger.addFeature">
<em class="property">classmethod </em><tt class="descname">addFeature</tt><big>(</big><em>func</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#twiggy.logger.Logger.addFeature" title="Permalink to this definition">¶</a></dt>
<dd><p>add a feature to the class</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>func</strong> – the function to add</li>
<li><strong>name</strong> (<em>string</em>) – the name to add it under. If None, use the function’s name.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="classmethod">
<dt id="twiggy.logger.Logger.disableFeature">
<em class="property">classmethod </em><tt class="descname">disableFeature</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#twiggy.logger.Logger.disableFeature" title="Permalink to this definition">¶</a></dt>
<dd><p>disable a feature.</p>
<p>A method will still exist by this name, but it won’t do anything.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>name</strong> (<em>string</em>) – the name of the feature to disable.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="classmethod">
<dt id="twiggy.logger.Logger.delFeature">
<em class="property">classmethod </em><tt class="descname">delFeature</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#twiggy.logger.Logger.delFeature" title="Permalink to this definition">¶</a></dt>
<dd><p>delete a feature entirely</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>name</strong> (<em>string</em>) – the name of the feature to remove</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="twiggy.logger.InternalLogger">
<em class="property">class </em><tt class="descclassname">twiggy.logger.</tt><tt class="descname">InternalLogger</tt><big>(</big><em>output</em>, <em>fields=None</em>, <em>options=None</em>, <em>min_level=None</em><big>)</big><a class="headerlink" href="#twiggy.logger.InternalLogger" title="Permalink to this definition">¶</a></dt>
<dd><p>Special-purpose logger for internal uses. Sends messages directly to output, bypassing <a class="reference internal" href="#twiggy.emitters" title="twiggy.emitters"><tt class="xref py py-data docutils literal"><span class="pre">emitters</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Variables:</th><td class="field-body"><strong>output</strong> (<em>Output</em>) – an output to write to</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="twiggy.logger.emit">
<tt class="descclassname">twiggy.logger.</tt><tt class="descname">emit</tt><big>(</big><em>level</em><big>)</big><a class="headerlink" href="#twiggy.logger.emit" title="Permalink to this definition">¶</a></dt>
<dd><p>a decorator that emits at <a class="reference internal" href="#twiggy.levels.LogLevel" title="twiggy.levels.LogLevel"><tt class="xref py py-obj docutils literal"><span class="pre">level</span></tt></a> after calling the method. The method
should return a <a class="reference internal" href="#twiggy.logger.Logger" title="twiggy.logger.Logger"><tt class="xref py py-obj docutils literal"><span class="pre">Logger</span></tt></a> instance.</p>
<p>For convenience, decorators for the various levels are available as
<tt class="docutils literal"><span class="pre">emit.debug</span></tt>, <tt class="docutils literal"><span class="pre">emit.info</span></tt>, etc..</p>
</dd></dl>
</div>
<div class="section" id="module-twiggy.message">
<span id="message"></span><h2>Message<a class="headerlink" href="#module-twiggy.message" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="twiggy.message.Message">
<em class="property">class </em><tt class="descclassname">twiggy.message.</tt><tt class="descname">Message</tt><big>(</big><em>level</em>, <em>format_spec</em>, <em>fields</em>, <em>options</em>, <em>args</em>, <em>kwargs</em><big>)</big><a class="headerlink" href="#twiggy.message.Message" title="Permalink to this definition">¶</a></dt>
<dd><p>A logging message. Users never create these directly.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.4.1: </span>Pass args/kwargs as list/dict instead of via <tt class="docutils literal"><span class="pre">*</span></tt>/<tt class="docutils literal"><span class="pre">**</span></tt> expansion.</p>
<p id="message-options">The constructor takes a dict of <tt class="docutils literal"><span class="pre">options</span></tt> to control message creation. In addition to <a class="reference internal" href="#twiggy.message.Message.suppress_newlines" title="twiggy.message.Message.suppress_newlines"><tt class="xref py py-attr docutils literal"><span class="pre">suppress_newlines</span></tt></a>, the following options are recognized:</p>
<blockquote>
<div><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">trace:</th><td class="field-body">control traceback inclusion. Either a traceback tuple, or one of the strings <tt class="docutils literal"><span class="pre">always</span></tt>, <tt class="docutils literal"><span class="pre">error</span></tt>, in which case a traceback will be extracted from the current stack frame.</td>
</tr>
<tr class="field"><th class="field-name">style:</th><td class="field-body">the style of template used for <tt class="docutils literal"><span class="pre">format_spec</span></tt>. One of <tt class="docutils literal"><span class="pre">braces</span></tt>, <tt class="docutils literal"><span class="pre">percent</span></tt>, <tt class="docutils literal"><span class="pre">dollar</span></tt>.</td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>Any callables passed in <tt class="docutils literal"><span class="pre">fields</span></tt>, <tt class="docutils literal"><span class="pre">args</span></tt> or <tt class="docutils literal"><span class="pre">kwargs</span></tt> will be called and the returned value used instead. See <a class="reference internal" href="reference_guide.html#dynamic-messages"><em>dynamic messages</em></a>.</p>
<p>All attributes are read-only.</p>
<dl class="attribute">
<dt id="twiggy.message.Message.fields">
<tt class="descname">fields</tt><a class="headerlink" href="#twiggy.message.Message.fields" title="Permalink to this definition">¶</a></dt>
<dd><p>dictionary of <a class="reference internal" href="glossary.html#term-structured-logging"><em class="xref std std-term">structured logging</em></a> fields. Keys are string, values are arbitrary. A <tt class="docutils literal"><span class="pre">level</span></tt> item is required.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.message.Message.suppress_newlines">
<tt class="descname">suppress_newlines</tt><a class="headerlink" href="#twiggy.message.Message.suppress_newlines" title="Permalink to this definition">¶</a></dt>
<dd><p>should newlines be escaped in output. Boolean.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.message.Message.traceback">
<tt class="descname">traceback</tt><a class="headerlink" href="#twiggy.message.Message.traceback" title="Permalink to this definition">¶</a></dt>
<dd><p>a stringified traceback, or None.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.message.Message.text">
<tt class="descname">text</tt><a class="headerlink" href="#twiggy.message.Message.text" title="Permalink to this definition">¶</a></dt>
<dd><p>the human-readable message. Constructed by substituting <tt class="docutils literal"><span class="pre">args</span></tt>/<tt class="docutils literal"><span class="pre">kwargs</span></tt> into <tt class="docutils literal"><span class="pre">format_spec</span></tt>. String.</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.message.Message.__init__">
<tt class="descname">__init__</tt><big>(</big><em>level</em>, <em>format_spec</em>, <em>fields</em>, <em>options</em>, <em>args</em>, <em>kwargs</em><big>)</big><a class="headerlink" href="#twiggy.message.Message.__init__" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>level</strong> (<em>LogLevel</em>) – the level of the message</li>
<li><strong>format_spec</strong> (<em>string</em>) – the human-readable message template. Should match the <tt class="docutils literal"><span class="pre">style</span></tt> in options.</li>
<li><strong>fields</strong> (<em>dict</em>) – dictionary of fields for <a class="reference internal" href="logging.html#structured-logging"><em>structured logging</em></a></li>
<li><strong>args</strong> (<em>tuple</em>) – substitution arguments for <tt class="docutils literal"><span class="pre">format_spec</span></tt>.</li>
<li><strong>kwargs</strong> (<em>dict</em>) – substitution keyword arguments for <tt class="docutils literal"><span class="pre">format_spec</span></tt>.</li>
<li><strong>options</strong> (<em>dict</em>) – a dictionary of <a class="reference internal" href="#message-options"><em>options</em></a> to control message creation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="module-twiggy.outputs">
<span id="outputs"></span><h2>Outputs<a class="headerlink" href="#module-twiggy.outputs" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="twiggy.outputs.Output">
<em class="property">class </em><tt class="descclassname">twiggy.outputs.</tt><tt class="descname">Output</tt><big>(</big><em>format=None</em>, <em>close_atexit=True</em><big>)</big><a class="headerlink" href="#twiggy.outputs.Output" title="Permalink to this definition">¶</a></dt>
<dd><dl class="attribute">
<dt id="twiggy.outputs.Output._format">
<tt class="descname">_format</tt><a class="headerlink" href="#twiggy.outputs.Output._format" title="Permalink to this definition">¶</a></dt>
<dd><p>a <a class="reference internal" href="#format-function"><em>callable</em></a> taking a <a class="reference internal" href="#twiggy.message.Message" title="twiggy.message.Message"><tt class="xref py py-obj docutils literal"><span class="pre">Message</span></tt></a> and formatting it for output. None means return the message unchanged.</p>
</dd></dl>
<dl class="attribute">
<dt id="twiggy.outputs.Output.use_locks">
<tt class="descname">use_locks</tt><a class="headerlink" href="#twiggy.outputs.Output.use_locks" title="Permalink to this definition">¶</a></dt>
<dd><p>Class variable, indicating that locks should be used when running in a synchronous, multithreaded environment. Threadsafe subclasses may disable locking for higher throughput. Defaults to True.</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.outputs.Output.__init__">
<tt class="descname">__init__</tt><big>(</big><em>format=None</em>, <em>close_atexit=True</em><big>)</big><a class="headerlink" href="#twiggy.outputs.Output.__init__" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>format</strong> (<em>format</em>) – the format to use. If None, return the message unchanged.</li>
<li><strong>close_atexit</strong> (<em>bool</em>) – should <a class="reference internal" href="#twiggy.outputs.Output.close" title="twiggy.outputs.Output.close"><tt class="xref py py-meth docutils literal"><span class="pre">close()</span></tt></a> be registered with <tt class="xref py py-mod docutils literal"><span class="pre">atexit</span></tt>. If False, the user is responsible for closing the output.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.1: </span>Add the <tt class="xref py py-obj docutils literal"><span class="pre">close_atexit</span></tt> parameter.</p>
<dl class="method">
<dt id="twiggy.outputs.Output.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#twiggy.outputs.Output.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Finalize the output.</p>
</dd></dl>
<p>The following methods should be implemented by subclasses.</p>
<dl class="method">
<dt id="twiggy.outputs.Output._open">
<tt class="descname">_open</tt><big>(</big><big>)</big><a class="headerlink" href="#twiggy.outputs.Output._open" title="Permalink to this definition">¶</a></dt>
<dd><p>Acquire any resources needed for writing (files, sockets, etc.)</p>
</dd></dl>
<dl class="method">
<dt id="twiggy.outputs.Output._close">
<tt class="descname">_close</tt><big>(</big><big>)</big><a class="headerlink" href="#twiggy.outputs.Output._close" title="Permalink to this definition">¶</a></dt>
<dd><p>Release any resources acquired in <a class="reference internal" href="#twiggy.outputs.Output._open" title="twiggy.outputs.Output._open"><tt class="xref py py-obj docutils literal"><span class="pre">_open</span></tt></a></p>
</dd></dl>
<dl class="method">
<dt id="twiggy.outputs.Output._write">
<tt class="descname">_write</tt><big>(</big><em>x</em><big>)</big><a class="headerlink" href="#twiggy.outputs.Output._write" title="Permalink to this definition">¶</a></dt>
<dd><p>Do the work of writing</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>x</strong> – an implementation-dependent object to be written.</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="twiggy.outputs.AsyncOutput">
<em class="property">class </em><tt class="descclassname">twiggy.outputs.</tt><tt class="descname">AsyncOutput</tt><big>(</big><em>msg_buffer=0</em><big>)</big><a class="headerlink" href="#twiggy.outputs.AsyncOutput" title="Permalink to this definition">¶</a></dt>
<dd><p>An <a class="reference internal" href="#twiggy.outputs.Output" title="twiggy.outputs.Output"><tt class="xref py py-obj docutils literal"><span class="pre">Output</span></tt></a> with support for <a class="reference internal" href="glossary.html#term-asynchronous-logging"><em class="xref std std-term">asynchronous logging</em></a>.</p>
<p>Inheriting from this class transparently adds support for asynchronous logging using the multiprocessing module. This is off by default, as it can cause log messages to be dropped.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>msg_buffer</strong> (<em>int</em>) – number of messages to buffer in memory when using asynchronous logging. <tt class="docutils literal"><span class="pre">0</span></tt> turns asynchronous output off, a negative integer means an unlimited buffer, a positive integer is the size of the buffer.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="twiggy.outputs.FileOutput">
<em class="property">class </em><tt class="descclassname">twiggy.outputs.</tt><tt class="descname">FileOutput</tt><big>(</big><em>name</em>, <em>format</em>, <em>mode='a'</em>, <em>buffering=1</em>, <em>msg_buffer=0</em>, <em>close_atexit=True</em><big>)</big><a class="headerlink" href="#twiggy.outputs.FileOutput" title="Permalink to this definition">¶</a></dt>
<dd><p>Output messages to a file</p>
<p><tt class="docutils literal"><span class="pre">name</span></tt>, <tt class="docutils literal"><span class="pre">mode</span></tt>, <tt class="docutils literal"><span class="pre">buffering</span></tt> are passed to <tt class="xref py py-func docutils literal"><span class="pre">open()</span></tt></p>
</dd></dl>
<dl class="class">
<dt id="twiggy.outputs.StreamOutput">
<em class="property">class </em><tt class="descclassname">twiggy.outputs.</tt><tt class="descname">StreamOutput</tt><big>(</big><em>format</em>, <em>stream=sys.stderr</em><big>)</big><a class="headerlink" href="#twiggy.outputs.StreamOutput" title="Permalink to this definition">¶</a></dt>
<dd><p>Output to an externally-managed stream.</p>
<p>The stream will be written to, but otherwise left alone (i.e., it will <em>not</em> be closed).</p>
</dd></dl>
<dl class="class">
<dt id="twiggy.outputs.NullOutput">
<em class="property">class </em><tt class="descclassname">twiggy.outputs.</tt><tt class="descname">NullOutput</tt><big>(</big><em>format=None</em>, <em>close_atexit=True</em><big>)</big><a class="headerlink" href="#twiggy.outputs.NullOutput" title="Permalink to this definition">¶</a></dt>
<dd><p>An output that just discards its messages</p>
</dd></dl>
<dl class="class">
<dt id="twiggy.outputs.ListOutput">
<em class="property">class </em><tt class="descclassname">twiggy.outputs.</tt><tt class="descname">ListOutput</tt><big>(</big><em>format=None</em>, <em>close_atexit=True</em><big>)</big><a class="headerlink" href="#twiggy.outputs.ListOutput" title="Permalink to this definition">¶</a></dt>
<dd><p>an output that stuffs messages in a list</p>
<p>Useful for unittesting.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Variables:</th><td class="field-body"><strong>messages</strong> (<em>list</em>) – messages that have been emitted</td>
</tr>
</tbody>
</table>
</dd></dl>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.4.1: </span>Replace <tt class="xref py py-obj docutils literal"><span class="pre">DequeOutput</span></tt> with more useful <a class="reference internal" href="#twiggy.outputs.ListOutput" title="twiggy.outputs.ListOutput"><tt class="xref py py-obj docutils literal"><span class="pre">ListOutput</span></tt></a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/twig_sidebar.jpg" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">API Reference</a><ul>
<li><a class="reference internal" href="#module-twiggy">Global Objects</a></li>
<li><a class="reference internal" href="#module-twiggy.features">Features</a><ul>
<li><a class="reference internal" href="#module-twiggy.features.procinfo">procinfo</a></li>
<li><a class="reference internal" href="#module-twiggy.features.socket">socket</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-twiggy.filters">Filters</a></li>
<li><a class="reference internal" href="#module-twiggy.formats">Formats</a></li>
<li><a class="reference internal" href="#module-twiggy.levels">Levels</a></li>
<li><a class="reference internal" href="#module-twiggy.lib">Library</a><ul>
<li><a class="reference internal" href="#module-twiggy.lib.converter">Converter</a></li>
</ul>
</li>
<li><a class="reference internal" href="#logger">Logger</a></li>
<li><a class="reference internal" href="#module-twiggy.message">Message</a></li>
<li><a class="reference internal" href="#module-twiggy.outputs">Outputs</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="reference_guide.html"
title="previous chapter">Reference Guide</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="glossary.html"
title="next chapter">Glossary</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/api.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="glossary.html" title="Glossary"
>next</a> |</li>
<li class="right" >
<a href="reference_guide.html" title="Reference Guide"
>previous</a> |</li>
<li><a href="index.html">Twiggy v0.4.4 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010, <a href="http://i.wearpants.org">Peter Fein</a>.
Last updated on Jul 10, 2012.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
