diff --git a/README.md b/README.md index 21ef604..bdbf1de 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,14 @@ -Log formatting with colors! -=========================== +# Log formatting with colors! [![](https://img.shields.io/pypi/v/colorlog.svg)](https://pypi.org/project/colorlog/) [![](https://img.shields.io/pypi/l/colorlog.svg)](https://pypi.org/project/colorlog/) -[![](https://img.shields.io/travis/borntyping/python-colorlog/master.svg)](https://travis-ci.org/borntyping/python-colorlog) Add colours to the output of Python's `logging` module. * [Source on GitHub](https://github.com/borntyping/python-colorlog) * [Packages on PyPI](https://pypi.org/pypi/colorlog/) -Status ------- +## Status colorlog currently requires Python 3.6 or higher. Older versions (below 5.x.x) support Python 2.6 and above. @@ -23,7 +20,7 @@ support Python 2.6 and above. [colorama] is included as a required dependency and initialised when using colorlog on Windows. -This library is almost a decade old and supported a wide set of Python versions +This library is over a decade old and supported a wide set of Python versions for most of its life, which has made it a difficult library to add new features to. colorlog 6 may break backwards compatibility so that newer features can be added more easily, but may still not accept all changes or feature @@ -31,8 +28,7 @@ requests. colorlog 4 might accept essential bugfixes but should not be considered actively maintained and will not accept any major changes or new features. -Installation ------------- +## Installation Install from PyPI with: @@ -40,12 +36,11 @@ Install from PyPI with: pip install colorlog ``` -Several Linux distributions provide official packages ([Debian], [Fedora], +Several Linux distributions provide official packages ([Debian], [Arch], [Fedora], [Gentoo], [OpenSuse] and [Ubuntu]), and others have user provided packages -([Arch AUR], [BSD ports], [Conda]). +([BSD ports], [Conda]). -Usage ------ +## Usage ```python import colorlog @@ -85,13 +80,32 @@ The following escape codes are made available for use in the format string: - `thin`, `thin_{color}`, `fg_thin_{color}`: Thin colors (terminal dependent). - `reset`: Clear all formatting (both foreground and background colors). -The available color names are `black`, `red`, `green`, `yellow`, `blue`, -`purple`, `cyan` and `white`. +The available color names are: -Examples --------- +- `black` +- `red` +- `green` +- `yellow` +- `blue`, +- `purple` +- `cyan` +- `white` -![Example output](doc/example.png) +You can also use "bright" colors. These aren't standard ANSI codes, and +support for these varies wildly across different terminals. + +- `light_black` +- `light_red` +- `light_green` +- `light_yellow` +- `light_blue` +- `light_purple` +- `light_cyan` +- `light_white` + +## Examples + +![Example output](docs/example.png) The following code creates a `ColoredFormatter` for use in a logging setup, using the default values for each argument. @@ -192,21 +206,18 @@ logger.setLevel('TRACE') logger.log(TRACE, 'a message using a custom level') ``` -Tests ------ +## Tests Tests similar to the above examples are found in `tests/test_colorlog.py`. -Status ------- +## Status colorlog is in maintenance mode. I try and ensure bugfixes are published, but compatibility with Python 2.6+ and Python 3+ makes this a difficult codebase to add features to. Any changes that might break backwards compatibility for existing users will not be considered. -Alternatives ------------- +## Alternatives There are some more modern libraries for improving Python logging you may find useful. @@ -214,15 +225,13 @@ find useful. - [structlog] - [jsonlog] -Projects using colorlog ------------------------ +## Projects using colorlog GitHub provides [a list of projects that depend on colorlog][dependents]. Some early adopters included [Errbot], [Pythran], and [zenlog]. -Licence -------- +## Licence Copyright (c) 2012-2021 Sam Clements @@ -248,11 +257,11 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. [addLevelName]: https://docs.python.org/3/library/logging.html#logging.addLevelName [Formatter]: http://docs.python.org/3/library/logging.html#logging.Formatter [tox]: http://tox.readthedocs.org/ -[Arch AUR]: https://aur.archlinux.org/packages/python-colorlog/ +[Arch]: https://archlinux.org/packages/extra/any/python-colorlog/ [BSD ports]: https://www.freshports.org/devel/py-colorlog/ [colorama]: https://pypi.python.org/pypi/colorama [Conda]: https://anaconda.org/conda-forge/colorlog -[Debian]: https://packages.debian.org/buster/python3-colorlog +[Debian]: [https://packages.debian.org/buster/python3-colorlog](https://packages.debian.org/buster/python3-colorlog) [Errbot]: http://errbot.io/ [Fedora]: https://src.fedoraproject.org/rpms/python-colorlog [Gentoo]: https://packages.gentoo.org/packages/dev-python/colorlog diff --git a/colorlog/escape_codes.py b/colorlog/escape_codes.py index f35dfca..185b947 100644 --- a/colorlog/escape_codes.py +++ b/colorlog/escape_codes.py @@ -5,6 +5,7 @@ Uses colorama as an optional dependency to support color on Windows """ + import sys try: diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..ea3476a --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,19 @@ +# Contributing to colorlog + +## New features + +Open a thread in the "[Discussions]" section of the GitHub repository before doing any significant work on a new feature. This library is over a decade old, and my priority in maintaining it is stability rather than features. See the [Status](../README.md#Status]) section of the README file for more information. + +## Bugfixes + +_Please_ provide a simple way to reproduce any bug you encounter when opening an issue. It's very common for bugs to be reported for this library that are actually caused by the calling code or another library being used alongside it. + +## Pull requests + +Open pull requests against the `main` branch. + +Make sure your changes pass the test suite, which runs tests against most recent versions of Python 3 and checks the `black` formatter makes no changes. + * You can run tests locally with `tox` if you have suitable versions of Python 3 installed... + * ...or use the GitHub Actions pipeline which will run automatically once you open a pull request. + +[Discussions]: https://github.com/borntyping/python-colorlog/discussions diff --git a/doc/colors.py b/docs/colors.py similarity index 100% rename from doc/colors.py rename to docs/colors.py diff --git a/doc/custom_level.py b/docs/custom_level.py similarity index 100% rename from doc/custom_level.py rename to docs/custom_level.py diff --git a/doc/example.png b/docs/example.png similarity index 100% rename from doc/example.png rename to docs/example.png diff --git a/doc/example.py b/docs/example.py similarity index 100% rename from doc/example.py rename to docs/example.py diff --git a/doc/yaml_example.py b/docs/yaml_example.py similarity index 100% rename from doc/yaml_example.py rename to docs/yaml_example.py diff --git a/doc/yaml_example.yaml b/docs/yaml_example.yaml similarity index 100% rename from doc/yaml_example.yaml rename to docs/yaml_example.yaml diff --git a/setup.py b/setup.py index 66211da..0635cf0 100644 --- a/setup.py +++ b/setup.py @@ -2,7 +2,7 @@ setup( name="colorlog", - version="6.8.0", + version="6.8.2", description="Add colours to the output of Python's logging module.", long_description=open("README.md").read(), long_description_content_type="text/markdown", diff --git a/tox.ini b/tox.ini index db99cc7..a918a2b 100644 --- a/tox.ini +++ b/tox.ini @@ -7,17 +7,17 @@ commands = pytest -v [testenv:black] deps = black -commands = black --check colorlog doc +commands = black --check --diff colorlog docs skip_install = true [testenv:flake8] deps = flake8 -commands = flake8 colorlog doc +commands = flake8 colorlog docs skip_install = true [testenv:mypy] deps = mypy types-PyYAML -commands = mypy colorlog doc +commands = mypy colorlog docs skip_install = true