Simple Log
==========
A simple Python module to allow for simple and straightforward logging from your application.
Installation
------------
Install simple log using `pip `_ ::
$ pip install simple_log
Usage
-----
We try and stay true to the name and make using this module as simple as possible. For the simplest case just use
>>> from simple_log import get_log
>>> my_log = get_log()
>>> my_log.info("This is an information message")
2016.11.10 22:21:51 INFO:: This is an information message
>>> my_log.error("This is an error message")
2016.11.10 22:22:12 ERROR:: This is an error message
>>> my_log.warning("This is a warning message")
2016.11.10 23:29:14 WARNING:: This is a warning message
If you want to have multiple logs just pass a name to `get_log`
>>> first_log = get_log("first")
>>> first_log.info("Information message to first log")
2016.11.10 22:27:30 INFO:: Information message to first log
>>> second_log = get_log('two')
>>> second_log.debug("This is a debug message")
2016.11.10 22:28:02 DEBUG:: This is a debug message
By default the logging level is set to `'INFO'` (the standard module defaults to `'WARNING'`). See the
`logging tutorial `_ for information on logging
levels. If you would like to change the logging level, for instance to display 'DEBUG' messages use the `setLevel`
method on your log object
>>> from simple_log import get_log
>>> my_log = get_log('test_log')
>>> my_log.debug('This is the first debug message')
...
>>> my_log.setLevel('test_log', 'DEBUG')
>>> my_log.debug('This is the second debug message')
2016.11.10 22:34:55 DEBUG:: This is the second debug message
If you would like your log messages written to a file as well as the screen use the `add_file` function
>>> from simple_log import get_log, add_file
>>> my_log = get_log('test_log')
>>> my_log.info('This is an information message')
2016.11.12 22:48:10 INFO:: This is an information message
>>> add_file('test_log', 'test_log.log')
>>> my_log.info('This is another information message')
2016.11.12 22:49:30 INFO:: This is another information message
>>> cat test_log.log
2016.11.12 22:49:30 INFO:: This is another information message
the `add_file` function tries to be clever and should work if you pass it either the name of a log that was created
using `get_log` or if you pass in the log object itself.
>>> from simple_log import get_log, add_file
>>> my_log = get_log('test_log')
>>> add_file(my_log, 'test_log.log')
>>> my_log.info('Information message to file')
2016.11.23 19:54:10 INFO:: Information message to file
>>> cat test_log.log
2016.11.23 19:54:10 INFO:: Information message to file
Why?
----
Why should you use `simple_log` and not the Python standard library :py:mod:`logging` module? Because `simple_log` follows one of the most import tenets of The Zen of Python - "Simple is better than complex".
This module allows you to produce resonably formatted log messages from your Python code in the simplest possible way. Import the module, create a log then write messages. To get the same effect with the standard logging modules takes this much boilerplate code::
import logging
MESSAGE_FORMAT = "%(asctime)s %(levelname)s:: %(message)s"
DATE_FORMAT="%Y.%m.%d %T"
logger = logging.getLogger(self.__name__)
logger.setLevel(logging.INFO)
formatter = logging.Formatter(MESSAGE_FORMAT, DATE_FORMAT)
ch = logging.StreamHandler()
ch.setFormatter(formatter)
logger.addHandler(ch)
If `simple_log` does nothing else it stops you repeating that code in every Python script that you write.
Code Structure
--------------
The only dependency for `simple_log` is the Python standard library :py:mod:`logging` module
This package is made up of one Python module called `log_utilities.py` within the `simple_log` module. It has two
functions
.. autofunction:: simple_log.get_log
.. autofunction:: simple_log.add_file