This file is indexed.

/usr/share/doc/python-logbook-doc/html/libraries.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
<!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>Logbook in Libraries &mdash; 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="Unittesting Support" href="unittesting.html" />
    <link rel="prev" title="Performance Tuning" href="performance.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="unittesting.html" title="Unittesting Support"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="performance.html" title="Performance Tuning"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Logbook 0.6.1-dev</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
          <div class="body">
            
  <div class="section" id="logbook-in-libraries">
<h1>Logbook in Libraries</h1>
<p>Logging becomes more useful the higher the number of components in a
system that are using it.  Logbook itself is not a widely supported
library so far, but a handful of libraries are using the <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>
already which can be redirected to Logbook if necessary.</p>
<p>Logbook itself is easier to support for libraries than logging because it
does away with the central logger registry and can easily be mocked in
case the library is not available.</p>
<div class="section" id="mocking-logbook">
<h2>Mocking Logbook</h2>
<p>If you want to support Logbook in your library but not depend on it you
can copy/paste the following piece of code.  It will attempt to import
logbook and create 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> and if it fails provide a
class that just swallows all calls:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">try</span><span class="p">:</span>
    <span class="kn">from</span> <span class="nn">logbook</span> <span class="kn">import</span> <span class="n">Logger</span>
<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>
    <span class="k">class</span> <span class="nc">Logger</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
        <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="mi">0</span><span class="p">):</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="o">=</span> <span class="n">level</span>
        <span class="n">debug</span> <span class="o">=</span> <span class="n">info</span> <span class="o">=</span> <span class="n">warn</span> <span class="o">=</span> <span class="n">warning</span> <span class="o">=</span> <span class="n">notice</span> <span class="o">=</span> <span class="n">error</span> <span class="o">=</span> <span class="n">exception</span> <span class="o">=</span> \
            <span class="n">critical</span> <span class="o">=</span> <span class="n">log</span> <span class="o">=</span> <span class="k">lambda</span> <span class="o">*</span><span class="n">a</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">:</span> <span class="bp">None</span>

<span class="n">log</span> <span class="o">=</span> <span class="n">Logger</span><span class="p">(</span><span class="s">&#39;My library&#39;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="best-practices">
<h2>Best Practices</h2>
<ul class="simple">
<li>A library that wants to log to the Logbook system should generally be
designed to provide an interface to the record dispatchers it is
using.  That does not have to be a reference to the record dispatcher
itself, it is perfectly fine if there is a toggle to switch it on or
off.</li>
<li>The channel name should be readable and descriptive.</li>
<li>For example, if you are a database library that wants to use the
logging system to log all SQL statements issued in debug mode, you can
enable and disable your record dispatcher based on that debug flag.</li>
<li>Libraries should never set up log setups except temporarily on a
per-thread basis if it never changes the stack for a longer duration
than a function call in a library.  For example, hooking in a null
handler for a call to a noisy function is fine, changing the global
stack in a function and not reverting it at the end of the function is
bad.</li>
</ul>
</div>
<div class="section" id="debug-loggers">
<h2>Debug Loggers</h2>
<p>Sometimes you want to have loggers in place that are only really good for
debugging.  For example you might have a library that does a lot of
server/client communication and for debugging purposes it would be nice if
you can enable/disable that log output as necessary.</p>
<p>In that case it makes sense to create a logger and disable that by default
and give people a way to get hold of the logger to flip the flag.
Additionally you can override the <tt class="xref py py-attr docutils literal"><span class="pre">disabled</span></tt> flag to
automatically set it based on another value:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyLogger</span><span class="p">(</span><span class="n">Logger</span><span class="p">):</span>
    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">disabled</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="ow">not</span> <span class="n">database_connection</span><span class="o">.</span><span class="n">debug</span>
<span class="n">database_connection</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">MyLogger</span><span class="p">(</span><span class="s">&#39;mylibrary.dbconnection&#39;</span><span class="p">)</span>
</pre></div>
</div>
</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="unittesting.html" title="Unittesting Support"
             >next</a> |</li>
        <li class="right" >
          <a href="performance.html" title="Performance Tuning"
             >previous</a> |</li>
        <li><a href="index.html">Logbook 0.6.1-dev</a> &raquo;</li> 
      </ul>
    </div>

  
    <div class="footer">
        &copy; Copyright 2010, Armin Ronacher, Georg Brandl.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b3.
    </div>
  </div>

  </body>
</html>