/usr/share/doc/python-logbook-doc/html/designexplained.html is in python-logbook-doc 0.6.0-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 | <!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>The Design Explained — 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.6.1-dev',
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="Design Principles" href="designdefense.html" />
<link rel="prev" title="Internal API" href="api/internal.html" />
</head>
<body>
<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">
<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="designdefense.html" title="Design Principles"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="api/internal.html" title="Internal API"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Logbook 0.6.1-dev</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="body">
<div class="section" id="the-design-explained">
<h1>The Design Explained</h1>
<p>This part of the documentation explains the design of Logbook in detail.
This is not strictly necessary to make use of Logbook but might be helpful
when writing custom handlers for Logbook or when using it in a more
complex environment.</p>
<div class="section" id="dispatchers-and-channels">
<h2>Dispatchers and Channels</h2>
<p>Logbook does not use traditional loggers, instead a logger is internally
named as <a class="reference internal" href="api/internal.html#logbook.base.RecordDispatcher" title="logbook.base.RecordDispatcher"><tt class="xref py py-class docutils literal"><span class="pre">RecordDispatcher</span></tt></a>. While a logger also has
methods to create new log records, the base class for all record
dispatchers itself only has ways to dispatch <a class="reference internal" href="api/base.html#logbook.LogRecord" title="logbook.LogRecord"><tt class="xref py py-class docutils literal"><span class="pre">LogRecord</span></tt></a>s
to the handlers. A log record itself might have an attribute that points
to the dispatcher that was responsible for dispatching, but it does not
have to be.</p>
<p>If a log record was created from the builtin <a class="reference internal" href="api/base.html#logbook.Logger" title="logbook.Logger"><tt class="xref py py-class docutils literal"><span class="pre">Logger</span></tt></a> it
will have the channel set to the name of the logger. But that itself is
no requirement. The only requirement for the channel is that it’s a
string with some human readable origin information. It could be
<tt class="docutils literal"><span class="pre">'Database'</span></tt> if the database issued the log record, it could be
<tt class="docutils literal"><span class="pre">'Process-4223'</span></tt> if the process with the pid 4223 issued it etc.</p>
<p>For example if you are logging from the <a class="reference internal" href="api/utilities.html#logbook.log" title="logbook.log"><tt class="xref py py-func docutils literal"><span class="pre">logbook.log()</span></tt></a> function they
will have a cannel set, but no dispatcher:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">logbook</span> <span class="kn">import</span> <span class="n">TestHandler</span><span class="p">,</span> <span class="n">warn</span>
<span class="gp">>>> </span><span class="n">handler</span> <span class="o">=</span> <span class="n">TestHandler</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">handler</span><span class="o">.</span><span class="n">push_application</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">warn</span><span class="p">(</span><span class="s">'This is a warning'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">handler</span><span class="o">.</span><span class="n">records</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">channel</span>
<span class="go">'Generic'</span>
<span class="gp">>>> </span><span class="n">handler</span><span class="o">.</span><span class="n">records</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">dispatcher</span> <span class="ow">is</span> <span class="bp">None</span>
<span class="go">True</span>
</pre></div>
</div>
<p>If you are logging from a custom logger, the channel attribute points to
the logger for as long this logger class is not garbage collected:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">logbook</span> <span class="kn">import</span> <span class="n">Logger</span><span class="p">,</span> <span class="n">TestHandler</span>
<span class="gp">>>> </span><span class="n">logger</span> <span class="o">=</span> <span class="n">Logger</span><span class="p">(</span><span class="s">'Console'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">handler</span> <span class="o">=</span> <span class="n">TestHandler</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">handler</span><span class="o">.</span><span class="n">push_application</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">logger</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s">'A warning'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">handler</span><span class="o">.</span><span class="n">records</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">dispatcher</span> <span class="ow">is</span> <span class="n">logger</span>
<span class="go">True</span>
</pre></div>
</div>
<p>You don’t need a record dispatcher to dispatch a log record though. The
default dispatching can be triggered from a function
<a class="reference internal" href="api/internal.html#logbook.base.dispatch_record" title="logbook.base.dispatch_record"><tt class="xref py py-func docutils literal"><span class="pre">dispatch_record()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">logbook</span> <span class="kn">import</span> <span class="n">dispatch_record</span><span class="p">,</span> <span class="n">LogRecord</span><span class="p">,</span> <span class="n">INFO</span>
<span class="gp">>>> </span><span class="n">record</span> <span class="o">=</span> <span class="n">LogRecord</span><span class="p">(</span><span class="s">'My channel'</span><span class="p">,</span> <span class="n">INFO</span><span class="p">,</span> <span class="s">'Hello World!'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">dispatch_record</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>
<span class="go">[2010-09-04 15:56] INFO: My channel: Hello World!</span>
</pre></div>
</div>
<p>It is pretty common for log records to be created without a dispatcher.
Here some common use cases for log records without a dispatcher:</p>
<ul class="simple">
<li>log records that were redirected from a different logging system
such as the standard library’s <a class="reference external" href="/usr/share/doc/python2.7/html/library/logging.html#module-logging" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">logging</span></tt></a> module or the
<a class="reference external" href="/usr/share/doc/python2.7/html/library/warnings.html#module-warnings" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">warnings</span></tt></a> module.</li>
<li>log records that came from different processes and do not have a
dispatcher equivalent in the current process.</li>
<li>log records that came from over the network.</li>
</ul>
</div>
<div class="section" id="the-log-record-container">
<h2>The Log Record Container</h2>
<p>The <a class="reference internal" href="api/base.html#logbook.LogRecord" title="logbook.LogRecord"><tt class="xref py py-class docutils literal"><span class="pre">LogRecord</span></tt></a> class is a simple container that
holds all the information necessary for a log record. Usually they are
created from a <a class="reference internal" href="api/base.html#logbook.Logger" title="logbook.Logger"><tt class="xref py py-class docutils literal"><span class="pre">Logger</span></tt></a> or one of the default log
functions (<a class="reference internal" href="api/utilities.html#logbook.warn" title="logbook.warn"><tt class="xref py py-func docutils literal"><span class="pre">logbook.warn()</span></tt></a> etc.) and immediately dispatched to the
handlers. The logger will apply some additional knowledge to figure out
where the record was created from and if a traceback information should be
attached.</p>
<p>Normally if log records are dispatched they will be closed immediately
after all handlers had their chance to write it down. On closing, the
interpreter frame and traceback object will be removed from the log record
to break up circular dependencies.</p>
<p>Sometimes however it might be necessary to keep log records around for a
longer time. Logbook provides three different ways to accomplish that:</p>
<ol class="arabic simple">
<li>Handlers can set the <a class="reference internal" href="api/base.html#logbook.LogRecord.keep_open" title="logbook.LogRecord.keep_open"><tt class="xref py py-attr docutils literal"><span class="pre">keep_open</span></tt></a> attribute of
a log record to <cite>True</cite> so that the record dispatcher will not close
the object. This is for example used by the
<a class="reference internal" href="api/handlers.html#logbook.TestHandler" title="logbook.TestHandler"><tt class="xref py py-class docutils literal"><span class="pre">TestHandler</span></tt></a> so that unittests can still access
interpreter frames and traceback objects if necessary.</li>
<li>Because some information on the log records depends on the interpreter
frame (such as the location of the log call) it is possible to pull
that related information directly into the log record so that it can
safely be closed without losing that information (see
<a class="reference internal" href="api/base.html#logbook.LogRecord.pull_information" title="logbook.LogRecord.pull_information"><tt class="xref py py-meth docutils literal"><span class="pre">pull_information()</span></tt></a>).</li>
<li>Last but not least, log records can be converted to dictionaries and
recreated from these. It is also possible to make these dictionaries
safe for JSON export which is used by the
<a class="reference internal" href="api/ticketing.html#logbook.ticketing.TicketingHandler" title="logbook.ticketing.TicketingHandler"><tt class="xref py py-class docutils literal"><span class="pre">TicketingHandler</span></tt></a> to store information in a
database or the <tt class="xref py py-class docutils literal"><span class="pre">MultiProcessingHandler</span></tt> to send
information between processes.</li>
</ol>
</div>
</div>
</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="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="designdefense.html" title="Design Principles"
>next</a> |</li>
<li class="right" >
<a href="api/internal.html" title="Internal API"
>previous</a> |</li>
<li><a href="index.html">Logbook 0.6.1-dev</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010, Armin Ronacher, Georg Brandl.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b3.
</div>
</div>
</body>
</html>
|