<!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>