colouredlogs 10.0.1

Installation

The colouredlogs package is available on PyPI which means installation should be as simple as:

$ pip install colouredlogs

There’s actually a multitude of ways to install Python packages (e.g. the per user site-packages directory, virtual environments or just installing system wide) and I have no intention of getting into that discussion here, so if this intimidates you then read up on your options before returning to these instructions ;-).

Usage

Here’s an example of how easy it is to get started:

import colouredlogs, logging

# Create a logger object.
logger = logging.getLogger(__name__)

# By default the install() function installs a handler on the root logger,
# this means that log messages from your code and log messages from the
# libraries that you use will all show up on the terminal.
colouredlogs.install(level='DEBUG')

# If you don't want to see log messages from libraries, you can pass a
# specific logger object to the install() function. In this case only log
# messages originating from that logger will show up on the terminal.
colouredlogs.install(level='DEBUG', logger=logger)

# Some examples.
logger.debug("this is a debugging message")
logger.info("this is an informational message")
logger.warning("this is a warning message")
logger.error("this is an error message")
logger.critical("this is a critical message")

Format of log messages

The ColouredFormatter class supports user defined log formats so you can use any log format you like. The default log format is as follows:

%(asctime)s %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s

This log format results in the following output:

2015-10-23 03:32:22 peter-macbook colouredlogs.demo[30462] DEBUG message with level 'debug'
2015-10-23 03:32:23 peter-macbook colouredlogs.demo[30462] VERBOSE message with level 'verbose'
2015-10-23 03:32:24 peter-macbook colouredlogs.demo[30462] INFO message with level 'info'
...

You can customize the log format and styling using environment variables as well as programmatically, please refer to the online documentation for details.

Changing text styles and colours

The online documentation contains an example of customizing the text styles and colours.

Coloured output from cron

When colouredlogs is used in a cron job, the output that’s e-mailed to you by cron won’t contain any ANSI escape sequences because colouredlogs realizes that it’s not attached to an interactive terminal. If you’d like to have colours e-mailed to you by cron there are two ways to make it happen:

MAILTO="your-email-address@here"
CONTENT_TYPE="text/html"
* * * * * root colouredlogs --to-html your-command

Contact

The latest version of colouredlogs is available on PyPI and GitHub. The online documentation is available on Read The Docs and includes a changelog. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at peter@peterodding.com.

License

This software is licensed under the MIT license.

© 2018 Peter Odding.