logging518 0.2.2

Configure Python's native logging module using pyproject.toml

logging518

Configure Python's native logging library using pyproject.toml

About

logging518 is simply a wrapper around the logging module in the standard library. It allows a developer to configure the module within the pyproject.toml config file instead of using an additional .ini or .conf config file as specified when using the fileConfig() method.

Why use pyproject.toml instead of logging.conf?

PEP 518 introduced a new config file, pyproject.toml, for specifying build dependecies. An interesting side effect of this new config file standard is that many tools started allowing developers to configure them using the pyproject.toml file that likely already existed in their project.

Using a single, universal config file helps declutter all of those additional config files for each tool (many those .conf, .ini, .yml, etc. files at the root level) bringing some minimalism back in our lives.

Usage

Under the hood, logging518 parses the pyproject.toml file using the toml library and then passes that output to the dictConfig() method.

Following the spec in PEP 518 pertaining to the tool table, logging518 will recognize all config values associated with the tool.logging518 key.

Any config option specified in the logging configuration dictionary schema is allowed.

Installation

pip install logging518

Example Config

Below is an example pyproject.toml file associated with a project using Poetry.

# pyproject.toml

[tool.poetry]
name = "picklr"
version = "0.1.0"
description = "Turns anything into a pickle"
authors = ["Rick Sanchez <[e-mail]>"]

[tool.poetry.dependencies]
python = "^3.8"

[tool.poetry.dev-dependencies]
pytest = "^5.2"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

# ------------- logging518 configured below -------------

[tool.logging518]
version = 1
disable_existing_loggers = true

[tool.logging518.formatters.standard]
format = "%(asctime)s %(levelname)-8s %(name)-15s %(message)s"

[tool.logging518.handlers.console]
class = "logging.StreamHandler"
formatter = "standard"
level = "ERROR"
stream = "ext://sys.stdout"

[tool.logging518.handlers.file]
class = "logging.FileHandler"
formatter = "standard"
level = "DEBUG"
filename = "picklr.log"
mode = "w"

[tool.logging518.root]
handlers = ["console", "file"]
level = "NOTSET"

The configuration above:

1. Created a formatter called "standard"
2. Created 2 handlers (one for logging to the console and the other for writing to a .log file) that both use the formatter created above
3. Configured the root logger to use both handlers created

When parsed by logging518 the above configuration will turn into the below KV object:

{
    "version": 1,
    "disable_existing_loggers": true,
    "formatters": {
        "standard": {
            "format": "%(asctime)s %(levelname)-8s %(name)-15s %(message)s"
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "standard",
            "level": "ERROR",
            "stream": "ext://sys.stdout",
        },
        "file": {
            "class": "logging.FileHandler",
            "formatter": "standard",
            "level": "DEBUG",
            "filename": "picklr.log",
            "mode": "w",
        },
    },
    "root": {
        "handlers": ["console", "file"], 
        "level": "NOTSET"
    },
}

NOTE: Please see this StackOverflow post for an dictionary example with dictConfig().

Using the logger

To access the root logger:

from logging518 import logger

logger.info("This will be an info message")

The logger object accessed from logging518 is normal a regular Logger object from the logging module meaning all of the methods you would normally use are available to you. Note that this is actually the root logger.

Prefer to use log instead logger when you create a Logger object? The below works too (and is just a copy of the logger object demoed above):

from logging518 import log

log.info("This will be an info message")

To access a logger other than the root, you can use the get_logger method:

from logging518 import get_logger

logger = get_logger("foo")
assert logger.name == "foo"

Debugging your configuration

If you would like to peak under the hood and see the dictionary object passed in to dictConfig() you can import debug_config:

from pprint import pprint
from logging518 import debug_config

pprint(debug_config)