.. stacklogger documentation master file, created by
   sphinx-quickstart on Thu Oct 21 22:28:40 2010.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

:mod:`stacklogger` --- stack-aware logging extension
====================================================

stacklogger provides a stack-aware extension of the standard library's logging
facility. With stacklogger, you can add useful information to your log messages
without changing any library code, adding extra dependencies for your users to
install or decreasing performance.

Installing :mod:`stacklogger`
-----------------------------

.. highlight:: none

You can install the latest stable version of :mod:`stacklogger` using :command:`pip`::
    
    $ pip install stacklogger

Public repositories for the project are hosted at `github`_ and `bitbucket`_, so
you can use either `git`_ or `Mercurial`_ to get a copy of the project's code
and history::
    
    $ hg clone http://bitbucket.org/wcmaier/stacklogger
    $ git clone git://github.com/wcmaier/stacklogger.git

.. _github:     http://github.com/wcmaier/stacklogger
.. _bitbucket:  http://bitbucket.org/wcmaier/stacklogger
.. _git:        http://git-scm.com/
.. _Mercurial:  http://mercurial.selenic.com/

If you notice a problem with :mod:`stacklogger`, please report it using the
github `issue tracker`_ (or, if you have a fix, send a `pull request`_).

.. _issue tracker:  http://github.com/wcmaier/stacklogger/issues
.. _pull request:   http://github.com/wcmaier/stacklogger/pull/new/master

A note about versions
+++++++++++++++++++++

:mod:`stacklogger` is developed along two branches. The first, 'default' (or
'master' in git) contains new features and possible bugs -- this branch is the
active development branch. The second, 'stable', contains releases both major
and minor as well as bugfixes. If you'd like to help improve :mod:`stacklogger`,
take a look at default/master. Otherwise, stick with stable.

Basic Usage
-----------

.. highlight:: python

:mod:`stacklogger` will fit easily into your project if you're already using
the standard :mod:`logging` module. If not, take a look at the `provided`_
`tutorials`_. Once your project is logging correctly, simply replace the usual
:class:`~logging.Logger` class with :class:`~stacklogger.StackLogger`::

    import logging

    from stacklogger import StackLogger

    logging.setLoggerClass(StackLogger)
    logging.basicConfig(
        level=logging.DEBUG,
        format="%(funcName)s %(message)s",
    )

You won't see any difference unless you configure the
:class:`~logging.Formatter` to include the 'funcName' in log messages.
:class:`~stacklogger.StackLogger` inspects the calling stack to discover
useful information that the standard logger doesn't include when it emits log
messages. For example, :class:`~stacklogger.StackLogger` will figure out the
class of a method that calls one of the logging methods. Given the above logging
configuration, consider the following example::

    class Eggs(object):
        
        def scramble(self):
            log = logging.getLogger("breakfast")
            log.debug("scrambling")

    eggs = Eggs()
    eggs.scramble()

.. highlight:: none

The above snippet should produce output like the following::

    Foo.scramble scrambling

Enabling :class:`~stacklogger.StackLogger` shouldn't slow your application
or library down any more than using the default :class:`~logging.Logger`
implementation. Simple tests show essentially no difference in performance
between the two implementations; in fact, :class:`~logging.Logger`
already looks at the interpreter stack each time it's called.
:class:`~stacklogger.StackLogger` is a bit smarter about how it figures out
where a calling function was defined, but it doesn't cost much more than regular
logging.

.. _provided:   http://docs.python.org/library/logging.html#simple-examples
.. _tutorials:  http://docs.python.org/library/logging.html#configuring-logging-for-a-library

Caveat
++++++

:class:`~stacklogger.StackLogger` tries pretty hard to figure out where a caller of a logging
method was defined. It is able to provide much more information than the
standard library :class:`~logging.Logger`, but there are some things that even
:class:`~stacklogger.StackLogger` can't (reasonably) figure out:

 * lambdas will always appear as *<lambda>*;
 * static methods will only show the name of the method -- it's not possible to
   discover the name of the class in which the method was defined.

Other somewhat exotic calling contexts --- like classmethods --- are supported.
See the test suite for more examples.

API
---

.. automodule:: stacklogger
    :members:
    :show-inheritance: