1coloredlogs: Colored terminal output for Python's logging module 2================================================================ 3 4.. image:: https://travis-ci.org/xolox/python-coloredlogs.svg?branch=master 5 :target: https://travis-ci.org/xolox/python-coloredlogs 6 7.. image:: https://coveralls.io/repos/github/xolox/python-coloredlogs/badge.svg?branch=master 8 :target: https://coveralls.io/github/xolox/python-coloredlogs?branch=master 9 10The `coloredlogs` package enables colored terminal output for Python's logging_ 11module. The ColoredFormatter_ class inherits from `logging.Formatter`_ and uses 12`ANSI escape sequences`_ to render your logging messages in color. It uses only 13standard colors so it should work on any UNIX terminal. It's currently tested 14on Python 2.7, 3.5+ and PyPy (2 and 3). On Windows `coloredlogs` automatically 15tries to enable native ANSI support (on up-to-date Windows 10 installations) 16and falls back on using colorama_ (if installed). Here is a screen shot of the 17demo that is printed when the command ``coloredlogs --demo`` is executed: 18 19.. image:: https://coloredlogs.readthedocs.io/en/latest/_images/defaults.png 20 21Note that the screenshot above includes custom logging levels defined by my 22verboselogs_ package: if you install both `coloredlogs` and `verboselogs` it 23will Just Work (`verboselogs` is of course not required to use 24`coloredlogs`). 25 26.. contents:: 27 :local: 28 29Installation 30------------ 31 32The `coloredlogs` package is available on PyPI_ which means installation should 33be as simple as: 34 35.. code-block:: console 36 37 $ pip install coloredlogs 38 39There's actually a multitude of ways to install Python packages (e.g. the `per 40user site-packages directory`_, `virtual environments`_ or just installing 41system wide) and I have no intention of getting into that discussion here, so 42if this intimidates you then read up on your options before returning to these 43instructions ��. 44 45Optional dependencies 46~~~~~~~~~~~~~~~~~~~~~ 47 48Native ANSI support on Windows requires an up-to-date Windows 10 installation. 49If this is not working for you then consider installing the colorama_ package: 50 51.. code-block:: console 52 53 $ pip install colorama 54 55Once colorama_ is installed it will be used automatically. 56 57Usage 58----- 59 60Here's an example of how easy it is to get started: 61 62.. code-block:: python 63 64 import coloredlogs, logging 65 66 # Create a logger object. 67 logger = logging.getLogger(__name__) 68 69 # By default the install() function installs a handler on the root logger, 70 # this means that log messages from your code and log messages from the 71 # libraries that you use will all show up on the terminal. 72 coloredlogs.install(level='DEBUG') 73 74 # If you don't want to see log messages from libraries, you can pass a 75 # specific logger object to the install() function. In this case only log 76 # messages originating from that logger will show up on the terminal. 77 coloredlogs.install(level='DEBUG', logger=logger) 78 79 # Some examples. 80 logger.debug("this is a debugging message") 81 logger.info("this is an informational message") 82 logger.warning("this is a warning message") 83 logger.error("this is an error message") 84 logger.critical("this is a critical message") 85 86Format of log messages 87---------------------- 88 89The ColoredFormatter_ class supports user defined log formats so you can use 90any log format you like. The default log format is as follows:: 91 92 %(asctime)s %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s 93 94This log format results in the following output:: 95 96 2015-10-23 03:32:22 peter-macbook coloredlogs.demo[30462] DEBUG message with level 'debug' 97 2015-10-23 03:32:23 peter-macbook coloredlogs.demo[30462] VERBOSE message with level 'verbose' 98 2015-10-23 03:32:24 peter-macbook coloredlogs.demo[30462] INFO message with level 'info' 99 ... 100 101You can customize the log format and styling using environment variables as 102well as programmatically, please refer to the `online documentation`_ for 103details. 104 105Enabling millisecond precision 106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 107 108If you're switching from `logging.basicConfig()`_ to `coloredlogs.install()`_ 109you may notice that timestamps no longer include milliseconds. This is because 110coloredlogs doesn't output milliseconds in timestamps unless you explicitly 111tell it to. There are three ways to do that: 112 1131. The easy way is to pass the `milliseconds` argument to `coloredlogs.install()`_:: 114 115 coloredlogs.install(milliseconds=True) 116 117 This became supported in `release 7.1`_ (due to `#16`_). 118 1192. Alternatively you can change the log format `to include 'msecs'`_:: 120 121 %(asctime)s,%(msecs)03d %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s 122 123 Here's what the call to `coloredlogs.install()`_ would then look like:: 124 125 coloredlogs.install(fmt='%(asctime)s,%(msecs)03d %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s') 126 127 Customizing the log format also enables you to change the delimiter that 128 separates seconds from milliseconds (the comma above). This became possible 129 in `release 3.0`_ which added support for user defined log formats. 130 1313. If the use of ``%(msecs)d`` isn't flexible enough you can instead add ``%f`` 132 to the date/time format, it will be replaced by the value of ``%(msecs)03d``. 133 Support for the ``%f`` directive was added to `release 9.3`_ (due to `#45`_). 134 135Custom logging fields 136~~~~~~~~~~~~~~~~~~~~~ 137 138The following custom log format fields are supported: 139 140- ``%(hostname)s`` provides the hostname of the local system. 141- ``%(programname)s`` provides the name of the currently running program. 142- ``%(username)s`` provides the username of the currently logged in user. 143 144When `coloredlogs.install()`_ detects that any of these fields are used in the 145format string the applicable logging.Filter_ subclasses are automatically 146registered to populate the relevant log record fields. 147 148Changing text styles and colors 149------------------------------- 150 151The online documentation contains `an example of customizing the text styles and 152colors <https://coloredlogs.readthedocs.io/en/latest/api.html#changing-the-colors-styles>`_. 153 154Colored output from cron 155------------------------ 156 157When `coloredlogs` is used in a cron_ job, the output that's e-mailed to you by 158cron won't contain any ANSI escape sequences because `coloredlogs` realizes 159that it's not attached to an interactive terminal. If you'd like to have colors 160e-mailed to you by cron there are two ways to make it happen: 161 162.. contents:: 163 :local: 164 165Modifying your crontab 166~~~~~~~~~~~~~~~~~~~~~~ 167 168Here's an example of a minimal crontab:: 169 170 MAILTO="your-email-address@here" 171 CONTENT_TYPE="text/html" 172 * * * * * root coloredlogs --to-html your-command 173 174The ``coloredlogs`` program is installed when you install the `coloredlogs` 175Python package. When you execute ``coloredlogs --to-html your-command`` it runs 176``your-command`` under the external program ``script`` (you need to have this 177installed). This makes ``your-command`` think that it's attached to an 178interactive terminal which means it will output ANSI escape sequences which 179will then be converted to HTML by the ``coloredlogs`` program. Yes, this is a 180bit convoluted, but it works great :-) 181 182Modifying your Python code 183~~~~~~~~~~~~~~~~~~~~~~~~~~ 184 185The ColoredCronMailer_ class provides a context manager that automatically 186enables HTML output when the ``$CONTENT_TYPE`` variable has been correctly set 187in the crontab. 188 189This requires my capturer_ package which you can install using ``pip install 190'coloredlogs[cron]'``. The ``[cron]`` extra will pull in capturer_ 2.4 or newer 191which is required to capture the output while silencing it - otherwise you'd 192get duplicate output in the emails sent by ``cron``. 193 194The context manager can also be used to retroactively silence output that has 195already been produced, this can be useful to avoid spammy cron jobs that have 196nothing useful to do but still email their output to the system administrator 197every few minutes :-). 198 199Contact 200------- 201 202The latest version of `coloredlogs` is available on PyPI_ and GitHub_. The 203`online documentation`_ is available on Read The Docs and includes a 204changelog_. For bug reports please create an issue on GitHub_. If you have 205questions, suggestions, etc. feel free to send me an e-mail at 206`peter@peterodding.com`_. 207 208License 209------- 210 211This software is licensed under the `MIT license`_. 212 213© 2020 Peter Odding. 214 215 216.. External references: 217.. _#16: https://github.com/xolox/python-coloredlogs/issues/16 218.. _#45: https://github.com/xolox/python-coloredlogs/issues/45 219.. _ANSI escape sequences: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors 220.. _capturer: https://pypi.org/project/capturer 221.. _changelog: https://coloredlogs.readthedocs.org/en/latest/changelog.html 222.. _colorama: https://pypi.org/project/colorama 223.. _ColoredCronMailer: https://coloredlogs.readthedocs.io/en/latest/api.html#coloredlogs.converter.ColoredCronMailer 224.. _ColoredFormatter: https://coloredlogs.readthedocs.io/en/latest/api.html#coloredlogs.ColoredFormatter 225.. _coloredlogs.install(): https://coloredlogs.readthedocs.io/en/latest/api.html#coloredlogs.install 226.. _cron: https://en.wikipedia.org/wiki/Cron 227.. _GitHub: https://github.com/xolox/python-coloredlogs 228.. _logging.basicConfig(): https://docs.python.org/2/library/logging.html#logging.basicConfig 229.. _logging.Filter: https://docs.python.org/3/library/logging.html#filter-objects 230.. _logging.Formatter: https://docs.python.org/2/library/logging.html#logging.Formatter 231.. _logging: https://docs.python.org/2/library/logging.html 232.. _MIT license: https://en.wikipedia.org/wiki/MIT_License 233.. _online documentation: https://coloredlogs.readthedocs.io/ 234.. _per user site-packages directory: https://www.python.org/dev/peps/pep-0370/ 235.. _peter@peterodding.com: peter@peterodding.com 236.. _PyPI: https://pypi.org/project/coloredlogs 237.. _release 3.0: https://coloredlogs.readthedocs.io/en/latest/changelog.html#release-3-0-2015-10-23 238.. _release 7.1: https://coloredlogs.readthedocs.io/en/latest/changelog.html#release-7-1-2017-07-15 239.. _release 9.3: https://coloredlogs.readthedocs.io/en/latest/changelog.html#release-9-3-2018-04-29 240.. _to include 'msecs': https://stackoverflow.com/questions/6290739/python-logging-use-milliseconds-in-time-format 241.. _verboselogs: https://pypi.org/project/verboselogs 242.. _virtual environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/ 243
