michael@0: :mod:`mozlog` --- Easy, configurable and uniform logging
michael@0: ========================================================
michael@0: 
michael@0: Mozlog is a python package intended to simplify and standardize logs
michael@0: in the Mozilla universe. It wraps around python's logging module and
michael@0: adds some additional functionality.
michael@0: 
michael@0: .. note::
michael@0:   For the purposes of logging results and other output from test runs,
michael@0:   :doc:`mozlog.structured<mozlog_structured>` should now be used
michael@0:   instead of this module.
michael@0: 
michael@0: .. automodule:: mozlog
michael@0:     :members: getLogger
michael@0: 
michael@0: .. autoclass:: MozLogger
michael@0:     :members: testStart, testEnd, testPass, testFail, testKnownFail
michael@0: 
michael@0: Examples
michael@0: --------
michael@0: 
michael@0: Log to stdout::
michael@0: 
michael@0:     import mozlog
michael@0:     log = mozlog.getLogger('MODULE_NAME')
michael@0:     log.setLevel(mozlog.INFO)
michael@0:     log.info('This message will be printed to stdout')
michael@0:     log.debug('This won't')
michael@0:     log.testPass('A test has passed')
michael@0:     mozlog.shutdown()
michael@0: 
michael@0: Log to a file::
michael@0: 
michael@0:     import mozlog
michael@0:     log = mozlog.getLogger('MODULE_NAME', handler=mozlog.FileHandler('path/to/log/file'))
michael@0:     log.warning('Careful!')
michael@0:     log.testKnownFail('We know the cause for this failure')
michael@0:     mozlog.shutdown()
michael@0: 
michael@0: Log from an existing object using the LoggingMixin::
michael@0: 
michael@0:     import mozlog
michael@0:     class Loggable(mozlog.LoggingMixin):
michael@0:         """Trivial class inheriting from LoggingMixin"""
michael@0:         def say_hello(self):
michael@0:             self.info("hello")
michael@0: 
michael@0:     loggable = Loggable()
michael@0:     loggable.say_hello()
michael@0: 
michael@0: 
michael@0: .. _logging: http://docs.python.org/library/logging.html