| Name | emptylog JSON |
| Version |
0.0.8
JSON |
| download |
| home_page | None |
| Summary | Mimicking the logger protocol |
| upload_time | 2024-07-23 21:12:41 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
logging
protocols
loggers mocks
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pepy.tech/project/emptylog)
[](https://pepy.tech/project/emptylog)
[](https://codecov.io/gh/pomponchik/emptylog)
[](https://github.com/boyter/scc/)
[](https://hitsofcode.com/github/pomponchik/emptylog/view?branch=main)
[](https://github.com/pomponchik/emptylog/actions/workflows/tests_and_coverage.yml)
[](https://pypi.python.org/pypi/emptylog)
[](https://badge.fury.io/py/emptylog)
[](http://mypy-lang.org/)
[](https://github.com/astral-sh/ruff)
This library is designed to extend the capabilities of the built-in [`logging`](https://docs.python.org/3/library/logging.html) library.
One of the important problems that it solves is the fact that almost no one tests logging in their programs. Are you sure that your program logs everything you need? Programmers cover with tests what they consider to be the basic logic of the program. Logging problems are usually detected only when something is on fire, and then you realize that there are not enough logs, or the wrong thing is being logged. On the contrary, this library makes logging as much a test-friendly part of your program as regular logic.
Here are some of the features it provides:
- A [universal logger protocol](#universal-logger-protocol) that allows you to replace one logger with another without typing violations. In tests, you can replace the original logger with a [logger that remembers its calls](#memory-logger) to check that logging is correct.
- An [empty logger]((#empty-logger)) that does nothing when you call it. It is useful for writing library functions where the user can pass their logger, but there is no logging by default.
- A [memory logger](#memory-logger) that remembers all the times it was called. To verify that your code is correctly logged in, pass it a memory logger object instead of the default logger, and then check how it was used.
- A [printing logger](#printing-logger) is a "toy version" of a real logger that you can use to visualize all logger calls inside your test.
- All loggers presented in this library can be easily [combined](#summation-of-loggers) using the "+" symbol.
## Table of contents
- [**Installing**](#installing)
- [**Universal Logger Protocol**](#universal-logger-protocol)
- [**Empty Logger**](#empty-logger)
- [**Memory Logger**](#memory-logger)
- [**Printing Logger**](#printing-logger)
- [**Summation of loggers**](#summation-of-loggers)
## Installing
Install it from [Pypi](https://pypi.org/project/emptylog/):
```bash
pip install emptylog
```
You can also quickly try out this and other packages without having to install using [instld](https://github.com/pomponchik/instld).
## Universal Logger Protocol
Easily check whether an object is a logger using the protocol. The protocol contains 6 classic logger methods:
```python
def debug(message: str, *args: Any, **kwargs: Any) -> None: pass
def info(message: str, *args: Any, **kwargs: Any) -> None: pass
def warning(message: str, *args: Any, **kwargs: Any) -> None: pass
def error(message: str, *args: Any, **kwargs: Any) -> None: pass
def exception(message: str, *args: Any, **kwargs: Any) -> None: pass
def critical(message: str, *args: Any, **kwargs: Any) -> None: pass
```
The protocol is verifiable in runtime by the [`isinstance`](https://docs.python.org/3/library/functions.html#isinstance) function. Let's check this on a regular logger from `logging`:
```python
import logging
from emptylog import LoggerProtocol
print(isinstance(logging.getLogger('some_name'), LoggerProtocol))
#> True
```
This also works for third-party loggers with the same signature. Let's try it on [loguru](https://github.com/Delgan/loguru):
```python
from loguru import logger
from emptylog import LoggerProtocol
print(isinstance(logger, LoggerProtocol))
#> True
```
And of course, you can use the protocol for type hints:
```python
def function(logger: LoggerProtocol):
logger.info('There was an earthquake in Japan, check the prices of hard drives!')
```
The protocol can be used for static checks by any tool you prefer, such as [`mypy`](https://github.com/python/mypy).
## Empty Logger
`EmptyLogger` is the simplest implementation of the [logger protocol](#universal-logger-protocol). When calling logging methods from an object of this class, nothing happens. You can use it as a stub, for example, when defining functions:
```python
from emptylog import EmptyLogger, LoggerProtocol
def function(logger: LoggerProtocol = EmptyLogger()):
logger.error('Kittens have spilled milk, you need to pour more.')
```
## Memory Logger
`MemoryLogger` is a special class designed for tests. Its difference from [`EmptyLogger`](#empty-logger) is that it remembers all the times it was called.
The call history is stored in the `data` attribute and sorted by logger method names:
```python
from emptylog import MemoryLogger
logger = MemoryLogger()
logger.error('Joe Biden forgot his name again.')
logger.error('And again.')
logger.info("Joe, remember, you're Joe.")
print(logger.data)
#> LoggerAccumulatedData(debug=[], info=[LoggerCallData(message="Joe, remember, you're Joe.", args=(), kwargs={})], warning=[], error=[LoggerCallData(message='Joe Biden forgot his name again.', args=(), kwargs={}), LoggerCallData(message='And again.', args=(), kwargs={})], exception=[], critical=[])
print(logger.data.info[0].message)
#> Joe, remember, you're Joe.
print(logger.data.error[0].message)
#> Joe Biden forgot his name again.
print(logger.data.info[0].args)
#> ()
print(logger.data.info[0].kwargs)
#> {}
```
You can find out the total number of logs saved by `MemoryLogger` by applying the [`len()`](https://docs.python.org/3/library/functions.html#len) function to the `data` attribute:
```python
logger = MemoryLogger()
logger.warning("Are you ready, kids?")
logger.info("Aye, aye, Captain!")
logger.error("I can't hear you!")
logger.info("Aye, aye, Captain!")
logger.debug("Oh!")
print(len(logger.data))
#> 5
```
## Printing Logger
`PrintingLogger` is the simplest logger designed for printing to the console. You cannot control the format or direction of the output, or send logs to a special microservice that will forward them to a long-term storage with indexing support. No, here you can only get basic output to the console and nothing else. Here is an example:
```python
from emptylog import PrintingLogger
logger = PrintingLogger()
logger.debug("I ate a strange pill found under my grandfather's pillow.")
#> 2024-07-08 20:52:31.342048 | DEBUG | I ate a strange pill found under my grandfather's pillow.
logger.info("Everything seems to be fine.")
#> 2024-07-08 20:52:31.342073 | INFO | Everything seems to be fine.
logger.error("My grandfather beat me up. He seems to be breathing fire.")
#> 2024-07-08 20:52:31.342079 | ERROR | My grandfather beat me up. He seems to be breathing fire.
```
As you can see, 3 things are output to the console: the exact time, the logging level, and the message. The message does not support extrapolation. Also, you won't see any additional arguments here that could have been passed to the method.
> ⚠️ Do not use this logger in production. It is intended solely for the purposes of debugging or testing of software.
If necessary, you can change the behavior of the logger by passing it a callback, which is called for the finished message to print it to the console. Instead of the original function (the usual [`print`](https://docs.python.org/3/library/functions.html#print) function is used under the hood), you can pass something more interesting (the code example uses the [`termcolor`](https://github.com/termcolor/termcolor) library):
```python
from termcolor import colored
def callback(string: str) -> None:
print(colored(string, 'green'), end='')
logger = PrintingLogger(printing_callback=callback)
logger.info('Hello, the colored world!')
#> 2024-07-09 11:20:03.693837 | INFO | Hello, the colored world!
# You can't see it here, but believe me, if you repeat the code at home, the output in the console will be green!
```
## Summation of loggers
All loggers represented in this library can be grouped together. To do this, just use the "+" operator:
```python
from emptylog import PrintingLogger, MemoryLogger
logger = PrintingLogger() + MemoryLogger()
print(logger)
#> LoggersGroup(PrintingLogger(), MemoryLogger())
```
The group object also implements the [logger protocol](#universal-logger-protocol). If you use it as a logger, it will alternately call the appropriate methods from the loggers nested in it:
```python
printing_logger = PrintingLogger()
memory_logger = MemoryLogger()
super_logger = printing_logger + memory_logger
super_logger.info('Together we are a force!')
#> 2024-07-10 16:49:21.247290 | INFO | Together we are a force!
print(memory_logger.data.info[0].message)
#> Together we are a force!
```
You can sum up more than 2 loggers. In this case, the number of nesting levels will not grow:
```python
print(MemoryLogger() + MemoryLogger() + MemoryLogger())
#> LoggersGroup(MemoryLogger(), MemoryLogger(), MemoryLogger())
```
You can also add any loggers from this library with loggers from other libraries, for example from the [standard library](https://docs.python.org/3/library/logging.html) or from [loguru](https://github.com/Delgan/loguru):
```python
import logging
from loguru import logger as loguru_logger
print(MemoryLogger() + loguru_logger + logging.getLogger(__name__))
#> LoggersGroup(MemoryLogger(), <loguru.logger handlers=[(id=0, level=10, sink=<stderr>)]>, <Logger __main__ (WARNING)>)
```
Finally, you can use a group as an iterable object, as well as find out the number of nested loggers in a standard way:
```python
group = PrintingLogger() + MemoryLogger()
print(len(group))
#> 2
print([x for x in group])
#> [PrintingLogger(), MemoryLogger()]
```
Raw data
{
"_id": null,
"home_page": null,
"name": "emptylog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "logging, protocols, loggers mocks",
"author": null,
"author_email": "Evgeniy Blinov <zheni-b@yandex.ru>",
"download_url": "https://files.pythonhosted.org/packages/95/18/db8bba36718352089158dbeccf45d75d0b0d03b8f18971fc0b26b7d94a7b/emptylog-0.0.8.tar.gz",
"platform": null,
"description": "\n\n[](https://pepy.tech/project/emptylog)\n[](https://pepy.tech/project/emptylog)\n[](https://codecov.io/gh/pomponchik/emptylog)\n[](https://github.com/boyter/scc/)\n[](https://hitsofcode.com/github/pomponchik/emptylog/view?branch=main)\n[](https://github.com/pomponchik/emptylog/actions/workflows/tests_and_coverage.yml)\n[](https://pypi.python.org/pypi/emptylog)\n[](https://badge.fury.io/py/emptylog)\n[](http://mypy-lang.org/)\n[](https://github.com/astral-sh/ruff)\n\nThis library is designed to extend the capabilities of the built-in [`logging`](https://docs.python.org/3/library/logging.html) library.\n\nOne of the important problems that it solves is the fact that almost no one tests logging in their programs. Are you sure that your program logs everything you need? Programmers cover with tests what they consider to be the basic logic of the program. Logging problems are usually detected only when something is on fire, and then you realize that there are not enough logs, or the wrong thing is being logged. On the contrary, this library makes logging as much a test-friendly part of your program as regular logic.\n\nHere are some of the features it provides:\n\n- A [universal logger protocol](#universal-logger-protocol) that allows you to replace one logger with another without typing violations. In tests, you can replace the original logger with a [logger that remembers its calls](#memory-logger) to check that logging is correct.\n- An [empty logger]((#empty-logger)) that does nothing when you call it. It is useful for writing library functions where the user can pass their logger, but there is no logging by default.\n- A [memory logger](#memory-logger) that remembers all the times it was called. To verify that your code is correctly logged in, pass it a memory logger object instead of the default logger, and then check how it was used.\n- A [printing logger](#printing-logger) is a \"toy version\" of a real logger that you can use to visualize all logger calls inside your test.\n- All loggers presented in this library can be easily [combined](#summation-of-loggers) using the \"+\" symbol.\n\n\n## Table of contents\n\n- [**Installing**](#installing)\n- [**Universal Logger Protocol**](#universal-logger-protocol)\n- [**Empty Logger**](#empty-logger)\n- [**Memory Logger**](#memory-logger)\n- [**Printing Logger**](#printing-logger)\n- [**Summation of loggers**](#summation-of-loggers)\n\n\n## Installing\n\nInstall it from [Pypi](https://pypi.org/project/emptylog/):\n\n```bash\npip install emptylog\n```\n\nYou can also quickly try out this and other packages without having to install using [instld](https://github.com/pomponchik/instld).\n\n\n## Universal Logger Protocol\n\nEasily check whether an object is a logger using the protocol. The protocol contains 6 classic logger methods:\n\n```python\ndef debug(message: str, *args: Any, **kwargs: Any) -> None: pass\ndef info(message: str, *args: Any, **kwargs: Any) -> None: pass\ndef warning(message: str, *args: Any, **kwargs: Any) -> None: pass\ndef error(message: str, *args: Any, **kwargs: Any) -> None: pass\ndef exception(message: str, *args: Any, **kwargs: Any) -> None: pass\ndef critical(message: str, *args: Any, **kwargs: Any) -> None: pass\n```\n\nThe protocol is verifiable in runtime by the [`isinstance`](https://docs.python.org/3/library/functions.html#isinstance) function. Let's check this on a regular logger from `logging`:\n\n```python\nimport logging\nfrom emptylog import LoggerProtocol\n\nprint(isinstance(logging.getLogger('some_name'), LoggerProtocol))\n#> True\n```\n\nThis also works for third-party loggers with the same signature. Let's try it on [loguru](https://github.com/Delgan/loguru):\n\n```python\nfrom loguru import logger\nfrom emptylog import LoggerProtocol\n\nprint(isinstance(logger, LoggerProtocol))\n#> True\n```\n\nAnd of course, you can use the protocol for type hints:\n\n```python\ndef function(logger: LoggerProtocol):\n logger.info('There was an earthquake in Japan, check the prices of hard drives!')\n```\n\nThe protocol can be used for static checks by any tool you prefer, such as [`mypy`](https://github.com/python/mypy).\n\n\n## Empty Logger\n\n`EmptyLogger` is the simplest implementation of the [logger protocol](#universal-logger-protocol). When calling logging methods from an object of this class, nothing happens. You can use it as a stub, for example, when defining functions:\n\n```python\nfrom emptylog import EmptyLogger, LoggerProtocol\n\ndef function(logger: LoggerProtocol = EmptyLogger()):\n logger.error('Kittens have spilled milk, you need to pour more.')\n```\n\n\n## Memory Logger\n\n`MemoryLogger` is a special class designed for tests. Its difference from [`EmptyLogger`](#empty-logger) is that it remembers all the times it was called.\n\nThe call history is stored in the `data` attribute and sorted by logger method names:\n\n```python\nfrom emptylog import MemoryLogger\n\nlogger = MemoryLogger()\n\nlogger.error('Joe Biden forgot his name again.')\nlogger.error('And again.')\nlogger.info(\"Joe, remember, you're Joe.\")\n\nprint(logger.data)\n#> LoggerAccumulatedData(debug=[], info=[LoggerCallData(message=\"Joe, remember, you're Joe.\", args=(), kwargs={})], warning=[], error=[LoggerCallData(message='Joe Biden forgot his name again.', args=(), kwargs={}), LoggerCallData(message='And again.', args=(), kwargs={})], exception=[], critical=[])\n\nprint(logger.data.info[0].message)\n#> Joe, remember, you're Joe.\nprint(logger.data.error[0].message)\n#> Joe Biden forgot his name again.\nprint(logger.data.info[0].args)\n#> ()\nprint(logger.data.info[0].kwargs)\n#> {}\n```\n\nYou can find out the total number of logs saved by `MemoryLogger` by applying the [`len()`](https://docs.python.org/3/library/functions.html#len) function to the `data` attribute:\n\n```python\nlogger = MemoryLogger()\n\nlogger.warning(\"Are you ready, kids?\")\nlogger.info(\"Aye, aye, Captain!\")\nlogger.error(\"I can't hear you!\")\nlogger.info(\"Aye, aye, Captain!\")\nlogger.debug(\"Oh!\")\n\nprint(len(logger.data))\n#> 5\n```\n\n\n## Printing Logger\n\n`PrintingLogger` is the simplest logger designed for printing to the console. You cannot control the format or direction of the output, or send logs to a special microservice that will forward them to a long-term storage with indexing support. No, here you can only get basic output to the console and nothing else. Here is an example:\n\n```python\nfrom emptylog import PrintingLogger\n\nlogger = PrintingLogger()\n\nlogger.debug(\"I ate a strange pill found under my grandfather's pillow.\")\n#> 2024-07-08 20:52:31.342048 | DEBUG | I ate a strange pill found under my grandfather's pillow.\nlogger.info(\"Everything seems to be fine.\")\n#> 2024-07-08 20:52:31.342073 | INFO | Everything seems to be fine.\nlogger.error(\"My grandfather beat me up. He seems to be breathing fire.\")\n#> 2024-07-08 20:52:31.342079 | ERROR | My grandfather beat me up. He seems to be breathing fire.\n```\n\nAs you can see, 3 things are output to the console: the exact time, the logging level, and the message. The message does not support extrapolation. Also, you won't see any additional arguments here that could have been passed to the method.\n\n> \u26a0\ufe0f Do not use this logger in production. It is intended solely for the purposes of debugging or testing of software.\n\nIf necessary, you can change the behavior of the logger by passing it a callback, which is called for the finished message to print it to the console. Instead of the original function (the usual [`print`](https://docs.python.org/3/library/functions.html#print) function is used under the hood), you can pass something more interesting (the code example uses the [`termcolor`](https://github.com/termcolor/termcolor) library):\n\n```python\nfrom termcolor import colored\n\ndef callback(string: str) -> None:\n print(colored(string, 'green'), end='')\n\nlogger = PrintingLogger(printing_callback=callback)\n\nlogger.info('Hello, the colored world!')\n#> 2024-07-09 11:20:03.693837 | INFO | Hello, the colored world!\n# You can't see it here, but believe me, if you repeat the code at home, the output in the console will be green!\n```\n\n\n## Summation of loggers\n\nAll loggers represented in this library can be grouped together. To do this, just use the \"+\" operator:\n\n```python\nfrom emptylog import PrintingLogger, MemoryLogger\n\nlogger = PrintingLogger() + MemoryLogger()\nprint(logger)\n#> LoggersGroup(PrintingLogger(), MemoryLogger())\n```\n\nThe group object also implements the [logger protocol](#universal-logger-protocol). If you use it as a logger, it will alternately call the appropriate methods from the loggers nested in it:\n\n```python\nprinting_logger = PrintingLogger()\nmemory_logger = MemoryLogger()\n\nsuper_logger = printing_logger + memory_logger\n\nsuper_logger.info('Together we are a force!')\n#> 2024-07-10 16:49:21.247290 | INFO | Together we are a force!\nprint(memory_logger.data.info[0].message)\n#> Together we are a force!\n```\n\nYou can sum up more than 2 loggers. In this case, the number of nesting levels will not grow:\n\n```python\nprint(MemoryLogger() + MemoryLogger() + MemoryLogger())\n#> LoggersGroup(MemoryLogger(), MemoryLogger(), MemoryLogger())\n```\n\nYou can also add any loggers from this library with loggers from other libraries, for example from the [standard library](https://docs.python.org/3/library/logging.html) or from [loguru](https://github.com/Delgan/loguru):\n\n```python\nimport logging\nfrom loguru import logger as loguru_logger\n\nprint(MemoryLogger() + loguru_logger + logging.getLogger(__name__))\n#> LoggersGroup(MemoryLogger(), <loguru.logger handlers=[(id=0, level=10, sink=<stderr>)]>, <Logger __main__ (WARNING)>)\n```\n\nFinally, you can use a group as an iterable object, as well as find out the number of nested loggers in a standard way:\n\n```python\ngroup = PrintingLogger() + MemoryLogger()\n\nprint(len(group))\n#> 2\nprint([x for x in group])\n#> [PrintingLogger(), MemoryLogger()]\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Mimicking the logger protocol",
"version": "0.0.8",
"project_urls": {
"Source": "https://github.com/pomponchik/emptylog",
"Tracker": "https://github.com/pomponchik/emptylog/issues"
},
"split_keywords": [
"logging",
" protocols",
" loggers mocks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9d3f95c17b0ffda763a40ed7bad5e2366de770c5a89f51f08089f7fe7aa08319",
"md5": "b373b9a4d448bdf962c3543443951b67",
"sha256": "c8a2f8a0503acac7fb483d086d10fc04fff700fc537fb9d181601a3cafa816fe"
},
"downloads": -1,
"filename": "emptylog-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b373b9a4d448bdf962c3543443951b67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10066,
"upload_time": "2024-07-23T21:12:39",
"upload_time_iso_8601": "2024-07-23T21:12:39.836153Z",
"url": "https://files.pythonhosted.org/packages/9d/3f/95c17b0ffda763a40ed7bad5e2366de770c5a89f51f08089f7fe7aa08319/emptylog-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9518db8bba36718352089158dbeccf45d75d0b0d03b8f18971fc0b26b7d94a7b",
"md5": "446c05bfcea48a09335044ff1a26bad3",
"sha256": "fc60879c2e954e22e87dd3bdfef0ca833871873f2584d9fc03332a7cee32ada9"
},
"downloads": -1,
"filename": "emptylog-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "446c05bfcea48a09335044ff1a26bad3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15395,
"upload_time": "2024-07-23T21:12:41",
"upload_time_iso_8601": "2024-07-23T21:12:41.078129Z",
"url": "https://files.pythonhosted.org/packages/95/18/db8bba36718352089158dbeccf45d75d0b0d03b8f18971fc0b26b7d94a7b/emptylog-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-23 21:12:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pomponchik",
"github_project": "emptylog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "emptylog"
}
