Click-logging
=============
**Simple and beautiful logging for click applications**
[](https://pypi.org/project/click-logging/)
[](https://pypi.org/project/click-logging/)
[](https://github.com/Toilal/click-logging/blob/develop/LICENSE)
[](https://github.com/Toilal/click-logging/actions?query=workflow%3Abuild)
[](https://coveralls.io/github/Toilal/click-logging)
[](https://github.com/relekang/python-semantic-release)
Project sources and documentation are available on [Github](https://github.com/Toilal/click-logging)
Documentation
=============
Getting started
---------------
Assuming you have this Click application:
```python
import click
@click.command()
def cli():
click.echo("Dividing by zero.")
try:
1 / 0
except ZeroDivisionError:
click.echo("ERROR: Failed to divide by zero.")
```
Ignore the application's core functionality for a moment. The much more pressing question here is: How do we add an option to not print anything on success? We could try this:
```python
import click
@click.command()
@click.option('--quiet', default=False, is_flag=True)
def cli(quiet):
if not quiet:
click.echo("Dividing by zero.")
try:
1 / 0
except ZeroDivisionError:
click.echo("ERROR: Failed to divide by zero.")
```
Wrapping if-statements around each `echo`-call is cumbersome though. And with that, we discover logging:
```python
import logging
import click
logger = logging.getLogger(__name__)
# More setup for logging handlers here
@click.command()
@click.option('--quiet', default=False, is_flag=True)
def cli(quiet):
if quiet:
logger.setLevel(logging.ERROR)
else:
logger.setLevel(logging.INFO)
# ...
```
Logging is a better solution, but partly because Python's logging module aims to be so generic, it doesn't come with sensible defaults for CLI applications. At some point you might also want to expose more logging levels through more options, at which point the boilerplate code grows even more.
This is where click-logging comes in:
```python
import logging
import click
import click_logging
logger = logging.getLogger(__name__)
click_logging.basic_config(logger)
@click.command()
@click_logging.simple_verbosity_option(logger)
def cli():
logger.info("Dividing by zero.")
try:
1 / 0
except ZeroDivisionError:
logger.error("Failed to divide by zero.")
```
The output will look like this:
```
Dividing by zero.
error: Failed to divide by zero.
```
The `error:`-prefix will be red, unless the output is piped to another command.
The `simple_verbosity_option` decorator adds a `--verbosity` option that takes a (case-insensitive) value of `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`, and calls `setLevel` on the given logger accordingly.
> **note**
>
> Make sure to define the `simple_verbosity_option` as early as possible. Otherwise logging setup will not be early enough for some of your other eager options.
Customize output
---
You can customize [click styles](https://click.palletsprojects.com/en/7.x/api/#utilities) for each log level with
`style_kwargs` keyword argument of `basic_config` function.
```python
import logging
import click_logging
logger = logging.getLogger(__name__)
style_kwargs = {
'error': dict(fg='red', blink=True),
'exception': dict(fg='red', blink=True),
'critical': dict(fg='red', blink=True)
}
click_logging.basic_config(logger, style_kwargs=style_kwargs)
```
You can customize [click echo](https://click.palletsprojects.com/en/7.x/api/#utilities) for each log level using `echo_kwargs` keyword argument of `basic_config` function.
```python
import logging
import click_logging
logger = logging.getLogger(__name__)
echo_kwargs = {
'error': dict(err=True),
'exception': dict(err=True),
'critical': dict(err=True),
}
click_logging.basic_config(logger, echo_kwargs=True)
```
Fork
====
This is a fork of [click-contrib/click-log](https://github.com/click-contrib/click-log)
Motivations of the fork:
- semantic-release and github actions to merge and release often.
- more configuration options.
License
=======
Licensed under the MIT, see `LICENSE`.
Changelog
=========
<!--next-version-placeholder-->
## v1.0.1 (2021-01-06)
### Fix
* Add missing string interpolation in error message ([`3de6f06`](https://github.com/Toilal/click-logging/commit/3de6f064a8b4b3e11b7b4df9f47c2e5fce33abe1))
* **help:** Add trailing dot to help text ([`1ed426f`](https://github.com/Toilal/click-logging/commit/1ed426f2b128b0d934a59fe6c28e19af6aa0cb46))
### Documentation
* **readme:** Enhance README.md formatting ([`3507ba3`](https://github.com/Toilal/click-logging/commit/3507ba3d39e3318baf9cc9f4fbc65e7a39f8787a))
## v1.0.0 (2021-01-06)
### Feature
* **customize:** Add more customization capabilities in basic_config ([`621c0a2`](https://github.com/Toilal/click-logging/commit/621c0a2b4532f0dacade1e031f0ed5c2174269ae))
### Breaking
* click_log has been renamed to click_logging ([`f4a8ddf`](https://github.com/Toilal/click-logging/commit/f4a8ddf83fa6e1f7197e458662f89c303f5dc606))
Raw data
{
"_id": null,
"home_page": "https://github.com/Toilal/click-logging",
"name": "click-logging",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "R\u00e9mi Alvergnat",
"author_email": "toilal.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/75/5e/f42e093e6723bfe7df0070bbfce023fdf0008e08b4ea3f8756811f4196dd/click-logging-1.0.1.tar.gz",
"platform": "",
"description": "Click-logging\n=============\n\n**Simple and beautiful logging for click applications**\n\n[](https://pypi.org/project/click-logging/)\n[](https://pypi.org/project/click-logging/)\n[](https://github.com/Toilal/click-logging/blob/develop/LICENSE)\n[](https://github.com/Toilal/click-logging/actions?query=workflow%3Abuild)\n[](https://coveralls.io/github/Toilal/click-logging)\n[](https://github.com/relekang/python-semantic-release)\n\nProject sources and documentation are available on [Github](https://github.com/Toilal/click-logging)\n\nDocumentation\n=============\n\nGetting started\n---------------\n\nAssuming you have this Click application:\n\n```python\nimport click\n\n@click.command()\ndef cli():\n click.echo(\"Dividing by zero.\")\n\n try:\n 1 / 0\n except ZeroDivisionError:\n click.echo(\"ERROR: Failed to divide by zero.\")\n```\n\nIgnore the application's core functionality for a moment. The much more pressing question here is: How do we add an option to not print anything on success? We could try this:\n\n```python\nimport click\n\n@click.command()\n@click.option('--quiet', default=False, is_flag=True)\ndef cli(quiet):\n if not quiet:\n click.echo(\"Dividing by zero.\")\n\n try:\n 1 / 0\n except ZeroDivisionError:\n click.echo(\"ERROR: Failed to divide by zero.\")\n```\n\nWrapping if-statements around each `echo`-call is cumbersome though. And with that, we discover logging:\n\n```python\nimport logging\nimport click\n\nlogger = logging.getLogger(__name__)\n# More setup for logging handlers here\n\n@click.command()\n@click.option('--quiet', default=False, is_flag=True)\ndef cli(quiet):\n if quiet:\n logger.setLevel(logging.ERROR)\n else:\n logger.setLevel(logging.INFO)\n # ...\n```\n\nLogging is a better solution, but partly because Python's logging module aims to be so generic, it doesn't come with sensible defaults for CLI applications. At some point you might also want to expose more logging levels through more options, at which point the boilerplate code grows even more.\n\nThis is where click-logging comes in:\n\n```python\nimport logging\nimport click\nimport click_logging\n\nlogger = logging.getLogger(__name__)\nclick_logging.basic_config(logger)\n\n@click.command()\n@click_logging.simple_verbosity_option(logger)\ndef cli():\n logger.info(\"Dividing by zero.\")\n\n try:\n 1 / 0\n except ZeroDivisionError:\n logger.error(\"Failed to divide by zero.\")\n```\n\nThe output will look like this:\n\n```\nDividing by zero.\nerror: Failed to divide by zero.\n```\n\nThe `error:`-prefix will be red, unless the output is piped to another command.\n\nThe `simple_verbosity_option` decorator adds a `--verbosity` option that takes a (case-insensitive) value of `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`, and calls `setLevel` on the given logger accordingly.\n\n> **note**\n>\n> Make sure to define the `simple_verbosity_option` as early as possible. Otherwise logging setup will not be early enough for some of your other eager options.\n\nCustomize output\n---\n\nYou can customize [click styles](https://click.palletsprojects.com/en/7.x/api/#utilities) for each log level with \n`style_kwargs` keyword argument of `basic_config` function.\n\n```python\nimport logging\nimport click_logging\n\nlogger = logging.getLogger(__name__)\nstyle_kwargs = {\n 'error': dict(fg='red', blink=True),\n 'exception': dict(fg='red', blink=True),\n 'critical': dict(fg='red', blink=True)\n}\nclick_logging.basic_config(logger, style_kwargs=style_kwargs)\n```\n\nYou can customize [click echo](https://click.palletsprojects.com/en/7.x/api/#utilities) for each log level using `echo_kwargs` keyword argument of `basic_config` function.\n\n```python\nimport logging\nimport click_logging\n\nlogger = logging.getLogger(__name__)\necho_kwargs = {\n 'error': dict(err=True),\n 'exception': dict(err=True),\n 'critical': dict(err=True),\n}\nclick_logging.basic_config(logger, echo_kwargs=True)\n```\n\nFork\n====\n\nThis is a fork of [click-contrib/click-log](https://github.com/click-contrib/click-log)\n\nMotivations of the fork:\n- semantic-release and github actions to merge and release often.\n- more configuration options.\n\nLicense\n=======\n\nLicensed under the MIT, see `LICENSE`.\n\n\nChangelog\n=========\n\n<!--next-version-placeholder-->\n\n## v1.0.1 (2021-01-06)\n### Fix\n* Add missing string interpolation in error message ([`3de6f06`](https://github.com/Toilal/click-logging/commit/3de6f064a8b4b3e11b7b4df9f47c2e5fce33abe1))\n* **help:** Add trailing dot to help text ([`1ed426f`](https://github.com/Toilal/click-logging/commit/1ed426f2b128b0d934a59fe6c28e19af6aa0cb46))\n\n### Documentation\n* **readme:** Enhance README.md formatting ([`3507ba3`](https://github.com/Toilal/click-logging/commit/3507ba3d39e3318baf9cc9f4fbc65e7a39f8787a))\n\n## v1.0.0 (2021-01-06)\n### Feature\n* **customize:** Add more customization capabilities in basic_config ([`621c0a2`](https://github.com/Toilal/click-logging/commit/621c0a2b4532f0dacade1e031f0ed5c2174269ae))\n\n### Breaking\n* click_log has been renamed to click_logging ([`f4a8ddf`](https://github.com/Toilal/click-logging/commit/f4a8ddf83fa6e1f7197e458662f89c303f5dc606))\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Logging integration for Click",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/Toilal/click-logging"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f38231f403a7b19b8fed3c71011e8065d2dc670e13b2195133da11606d797736",
"md5": "13b67ec8744f4ee28ffe1716c0e56822",
"sha256": "3ce04f9fa93120343f5d727108f2066b59bd9c5aac2d770a02f37c69186dbf23"
},
"downloads": -1,
"filename": "click_logging-1.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "13b67ec8744f4ee28ffe1716c0e56822",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6587,
"upload_time": "2021-01-06T14:02:09",
"upload_time_iso_8601": "2021-01-06T14:02:09.312407Z",
"url": "https://files.pythonhosted.org/packages/f3/82/31f403a7b19b8fed3c71011e8065d2dc670e13b2195133da11606d797736/click_logging-1.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "755ef42e093e6723bfe7df0070bbfce023fdf0008e08b4ea3f8756811f4196dd",
"md5": "65fae3e0a6afb1fbb5deb7caa568510d",
"sha256": "1c3b2835ad4834df7c42e47ac7591866535af499dded3a84403f14411c5041a8"
},
"downloads": -1,
"filename": "click-logging-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "65fae3e0a6afb1fbb5deb7caa568510d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7795,
"upload_time": "2021-01-06T14:02:10",
"upload_time_iso_8601": "2021-01-06T14:02:10.120910Z",
"url": "https://files.pythonhosted.org/packages/75/5e/f42e093e6723bfe7df0070bbfce023fdf0008e08b4ea3f8756811f4196dd/click-logging-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-01-06 14:02:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Toilal",
"github_project": "click-logging",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "click-logging"
}
JSON
