comparison env/lib/python3.9/site-packages/coloredlogs-15.0.dist-info/METADATA @ 0:4f3585e2f14b draft default tip

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