/usr/share/doc/python-logbook-doc/html/stacks.html is in python-logbook-doc 0.12.3-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Stacks in Logbook — Logbook</title>
<link rel="stylesheet" href="_static/sheet.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.12.3',
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="top" title="Logbook" href="index.html" />
<link rel="next" title="Performance Tuning" href="performance.html" />
<link rel="prev" title="Common Logbook Setups" href="setups.html" />
</head>
<body role="document">
<div class="book">
<div class="banner">
<a href="index.html">
<!-- <img src="_static/" alt="Logbook logo"></img> -->
<h1>Logbook </h1>
</a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<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="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="performance.html" title="Performance Tuning"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="setups.html" title="Common Logbook Setups"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Logbook 0.12.3</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="body" role="main">
<div class="section" id="stacks-in-logbook">
<h1>Stacks in Logbook</h1>
<p>Logbook keeps three stacks internally currently:</p>
<ul class="simple">
<li>one for the <a class="reference internal" href="api/handlers.html#logbook.Handler" title="logbook.Handler"><code class="xref py py-class docutils literal"><span class="pre">Handler</span></code></a>s: each handler is handled from
stack top to bottom. When a record was handled it depends on the
<a class="reference internal" href="api/handlers.html#logbook.Handler.bubble" title="logbook.Handler.bubble"><code class="xref py py-attr docutils literal"><span class="pre">bubble</span></code></a> flag of the handler if it should still
be processed by the next handler on the stack.</li>
<li>one for the <a class="reference internal" href="api/base.html#logbook.Processor" title="logbook.Processor"><code class="xref py py-class docutils literal"><span class="pre">Processor</span></code></a>s: each processor in the stack
is applied on a record before the log record is handled by the
handler.</li>
<li>one for the <a class="reference internal" href="api/base.html#logbook.Flags" title="logbook.Flags"><code class="xref py py-class docutils literal"><span class="pre">Flags</span></code></a>: this stack manages simple flags
such as how errors during logging should be processed or if stackframe
introspection should be used etc.</li>
</ul>
<div class="section" id="general-stack-management">
<h2>General Stack Management</h2>
<p>Generally all objects that are management by stacks have a common
interface (<a class="reference internal" href="api/internal.html#logbook.base.StackedObject" title="logbook.base.StackedObject"><code class="xref py py-class docutils literal"><span class="pre">StackedObject</span></code></a>) and can be used in
combination with the <a class="reference internal" href="api/handlers.html#logbook.NestedSetup" title="logbook.NestedSetup"><code class="xref py py-class docutils literal"><span class="pre">NestedSetup</span></code></a> class.</p>
<p>Commonly stacked objects are used with a context manager (<cite>with</cite>
statement):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">context_object</span><span class="o">.</span><span class="n">threadbound</span><span class="p">():</span>
<span class="c"># this is managed for this thread only</span>
<span class="o">...</span>
<span class="k">with</span> <span class="n">context_object</span><span class="o">.</span><span class="n">applicationbound</span><span class="p">():</span>
<span class="c"># this is managed for all applications</span>
<span class="o">...</span>
</pre></div>
</div>
<p>Alternatively you can also use <cite>try</cite>/<cite>finally</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">context_object</span><span class="o">.</span><span class="n">push_thread</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="c"># this is managed for this thread only</span>
<span class="o">...</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">context_object</span><span class="o">.</span><span class="n">pop_thread</span><span class="p">()</span>
<span class="n">context_object</span><span class="o">.</span><span class="n">push_application</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="c"># this is managed for all applications</span>
<span class="o">...</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">context_object</span><span class="o">.</span><span class="n">pop_application</span><span class="p">()</span>
</pre></div>
</div>
<p>It’s very important that you will always pop from the stack again unless
you really want the change to last until the application closes down,
which probably is not the case.</p>
<p>If you want to push and pop multiple stacked objects at the same time, you
can use the <a class="reference internal" href="api/handlers.html#logbook.NestedSetup" title="logbook.NestedSetup"><code class="xref py py-class docutils literal"><span class="pre">NestedSetup</span></code></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span> <span class="o">=</span> <span class="n">NestedSetup</span><span class="p">([</span><span class="n">stacked_object1</span><span class="p">,</span> <span class="n">stacked_object2</span><span class="p">])</span>
<span class="k">with</span> <span class="n">setup</span><span class="o">.</span><span class="n">threadbound</span><span class="p">():</span>
<span class="c"># both objects are now bound to the thread's stack</span>
<span class="o">...</span>
</pre></div>
</div>
<p>Sometimes a stacked object can be passed to one of the functions or
methods in Logbook. If any stacked object can be passed, this is usually
called the <cite>setup</cite>. This is for example the case when you specify a
handler or processor for things like the
<a class="reference internal" href="api/queues.html#logbook.queues.ZeroMQSubscriber" title="logbook.queues.ZeroMQSubscriber"><code class="xref py py-class docutils literal"><span class="pre">ZeroMQSubscriber</span></code></a>.</p>
</div>
<div class="section" id="handlers">
<h2>Handlers</h2>
<p>Handlers use the features of the stack the most because not only do they
stack, but they also specify how stack handling is supposed to work. Each
handler can decide if it wants to process the record, and then it has a
flag (the <a class="reference internal" href="api/handlers.html#logbook.Handler.bubble" title="logbook.Handler.bubble"><code class="xref py py-attr docutils literal"><span class="pre">bubble</span></code></a> flag) which specifies if the
next handler in the chain is supposed to get this record passed to.</p>
<p>If a handler is bubbeling it will give the record to the next handler,
even if it was properly handled. If it’s not, it will stop promoting
handlers further down the chain. Additionally there are so-called
“blackhole” handlers (<a class="reference internal" href="api/handlers.html#logbook.NullHandler" title="logbook.NullHandler"><code class="xref py py-class docutils literal"><span class="pre">NullHandler</span></code></a>) which stop processing
at any case when they are reached. If you push a blackhole handler on top
of an existing infrastructure you can build up a separate one without
performance impact.</p>
</div>
<div class="section" id="processor">
<h2>Processor</h2>
<p>A processor can inject additional information into a log record when the
record is handled. Processors are called once at least one log handler is
interested in handling the record. Before that happens, no processing
takes place.</p>
<p>Here an example processor that injects the current working directory into
the extra attribute of the record:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span>
<span class="k">def</span> <span class="nf">inject_cwd</span><span class="p">(</span><span class="n">record</span><span class="p">):</span>
<span class="n">record</span><span class="o">.</span><span class="n">extra</span><span class="p">[</span><span class="s">'cwd'</span><span class="p">]</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getcwd</span><span class="p">()</span>
<span class="k">with</span> <span class="n">Processor</span><span class="p">(</span><span class="n">inject_cwd</span><span class="p">):</span>
<span class="c"># all logging calls inside this block in this thread will now</span>
<span class="c"># have the current working directory information attached.</span>
<span class="o">...</span>
</pre></div>
</div>
</div>
<div class="section" id="flags">
<h2>Flags</h2>
<p>The last pillar of logbook is the flags stack. This stack can be used to
override settings of the logging system. Currently this can be used to
change the behavior of logbook in case an exception during log handling
happens (for instance if a log record is supposed to be delivered to the
filesystem but it ran out of available space). Additionally there is a
flag that disables frame introspection which can result in a speedup on
JIT compiled Python interpreters.</p>
<p>Here an example of a silenced error reporting:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">Flags</span><span class="p">(</span><span class="n">errors</span><span class="o">=</span><span class="s">'silent'</span><span class="p">):</span>
<span class="c"># errors are now silent for this block</span>
<span class="o">...</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<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="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="performance.html" title="Performance Tuning"
>next</a> |</li>
<li class="right" >
<a href="setups.html" title="Common Logbook Setups"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Logbook 0.12.3</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2010, Armin Ronacher, Georg Brandl.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.3.
</div>
</div>
</body>
</html>
|