Welcome to easylogger's documentation!
======================================

Summary
-------

**Easylogger** is a Python package which wraps aspects of original :mod:`logging`
module in simple and Pythonic way. You can use all power of the original package
with the new facilities side-by-side.

The key features of current version of **easylogging** package are:

* Easy to start logging without configuring anything;
* Provided decorator-mode to log every function or method call and its doc-string;
* Imitate and replace stdout and stderr streams in order to redirect :func:`print` messages to required logging handlers;
* Alternative message formatting system (like :func:`print` does);
* And more! See unit-tests for additional code examples;

See examples below for the features description.

.. note:: Python version **2.6** or higher is required to use easylogger package.


Examples
--------

.. topic:: 1. Easy start to use logging facilities: 

 ::
 
    from easylogger import log, info, debug, DEBUG
    log("Hello, World!")
    log.info("This is an information message")
    log.debug("This is a debug message")
    log.error("This is an error message")
    log.critical("This is an critical message")
    info("Hello!")
    debug("Bye")
    log.log(DEBUG, "Generic log method.")


 ::
 
    ... [DEBUG   ] Hello, World!
    ... [INFO    ] This is an information message
    ... [DEBUG   ] This is a debug message
    ... [ERROR   ] This is an error message
    ... [CRITICAL] This is an critical message
    ... [INFO    ] Hello!
    ... [DEBUG   ] Bye!
    ... [DEBUG   ] Generic log method.


.. topic:: 2. Using logger as decorator:

 ::
 
    @log
    def create_human(name, sex, age=26):
        """Create new human with name '{name}' and age {age}."""
        print "Creating new human '{0}-{1}-{2}'.".format(name, sex, age)
    
    class MyExClass(object):
        
        @info
        def print_hi(self, who):
            print "Who?", who
    
    log("Checking decorator-mode.")
    create_human("Ivan", "male")
    MyExClass().print_hi("me")
    
    
 ::

    ... [DEBUG   ] Checking decorator-mode.
    ... [DEBUG   ] Executing function create_human(name='Ivan', sex='male', age=26).
    ... [DOC     ] Create new human with name 'Ivan' and age 26.
    Creating new human 'Ivan-male-26'.
    ... [INFO    ] Executing method MyExClass.print_hi(who='me').
    Who? me    


.. topic:: 3. Imitate and replace `stdout` and `stderr` streams:

 ::
 
    import sys
    from easylogger import log, STDOUT, STDERR
    
    # replace current streams
    sys.stdout = log.get_stream(STDOUT)
    sys.stderr = log.get_stream(STDERR)
    
    print "Hello,", "World!"
    print >> sys.stderr, "Error message!"
    
    # assign original stream values
    sys.stdout = sys.__stdout__
    sys.stderr = sys.__stderr__


 ::
 
    ... [STDOUT  ] Hello, World!
    ... [STDERR  ] Error message!
        
 .. warning:: Keep in mind that if you provide :class:`sys.stdout`  (:class:`sys.stderr`)
        as stream parameter to :class:`logging.StreamHandler` you may get into recursive loop when
        using stream redirection. Always provide :class:`sys.__stdout__` (:class:`sys.__stderr__`)
        when constructing a stream handler to avoid this problem.


.. topic:: 4. Alternative message formatting system:

 ::
 
    from easylogger import log, error, info, LoggingOptions
    
    # new message style
    log("Hello, World!", "test1", "test2")
    component = "brain"
    error("Error occurred in", component, "with code", 123, int)
    log.set_options(new_style_delimiter="_")
    log("brown", "fox", "jumps", "over", "lazy", "dog")
    
    # old message style
    opt = LoggingOptions()
    opt.enable_new_style = False
    log.set_options(opt)
    info("a %s %s", "b", "c")

 ::
 
    ... [DEBUG   ] Hello, World! test1 test2
    ... [ERROR   ] Error occurred in brain with code 123 <type 'int'>
    ... [DEBUG   ] brown_fox_jumps_over_lazy_dog
    ... [INFO    ] a b c 

 .. note:: For more options see :class:`easylogger.LoggingOptions`.

.. topic:: 5. Using original logging features and new ones side-by-side:

    ::
    
        from easylogger import get_logger, INFO
        import logging.config
        
        logging.config.fileConfig("logging.cfg")
        mylog = get_logger("simpleExample", level=INFO)
        mylog.info("Hello!")
        mylog.debug("Hello!")
        mylog.error("Hello!")

    ::

        simpleExample - INFO - Hello!
        simpleExample - ERROR - Hello!    
        

.. note:: A lot of examples can be found in :file:`/tests/basic_tests.py` file.


Easylogger objects
------------------

.. automodule:: easylogger
   :members:
   :undoc-members:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`