Logging Utilities

A small Python utility for adding custom logging levels to Python's standard logging module.

add_new_level() registers a level name and numeric value, adds a matching constant to logging, and adds a lowercase logging method to logging.Logger. For example, registering TRACE creates logging.TRACE and allows calls such as logger.trace("message").

Features

• Validates custom level names and numeric values.
• Rejects names, logger methods, and numeric levels that are already in use.
• Uses the standard logger machinery, supporting message arguments and options such as extra, exc_info, stack_info, and stacklevel.
• Includes configure_logging() as a convenience configuration for applications that want a TRACE level and a standard log format.

Requirements

• Python 3.12 or later.

Usage

Register a custom level before using it:

import logging

from logging_config import add_new_level

add_new_level("TRACE", 15)

logging.basicConfig(
    level=logging.TRACE,
    format="%(asctime)s %(levelname)-8s %(name)s: %(message)s",
)

logger = logging.getLogger(__name__)
logger.trace("Reading configuration for %s", "my_app")
logger.info("Application started")

The level name must be a non-empty uppercase string. The level number must be a positive integer (not a Boolean). Registration raises ValueError when the name, corresponding logger method, or numeric level conflicts with an existing logging entry.

Default configuration

Call configure_logging() once during application startup to register TRACE at level 15 and configure basic logging with an INFO threshold:

from logging_config import configure_logging

configure_logging()

The default INFO threshold filters out TRACE messages because TRACE (15) is less severe than INFO (20). To see TRACE messages, configure logging with a threshold of logging.TRACE or another value no greater than 15. configure_logging() registers TRACE each time it is called, so call it only once per process.

Development setup

Create a virtual environment from the repository root. For Windows with Python 3.12:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

The requirements file installs the project's current test and lint tools.

Run tests

python -m pytest

Run the test suite with coverage and print the report:

coverage run -m pytest
coverage report

Run Ruff

Check the source module for lint issues and formatting:

ruff check src/logging_config.py
ruff format --check src/logging_config.py

To apply Ruff's automatic fixes, run ruff check --fix src/logging_config.py, then rerun the tests and checks.

Project layout

logging/
├── .github/workflows/   # GitHub Actions for Ruff, tests/coverage, and PyPI publishing
├── src/
│   └── logging_config.py
├── tests/
│   └── test_logging_config.py
├── LICENSE
├── README.md
├── pyproject.toml       # Project metadata and tool configuration
└── requirements.txt     # Development/test tools

Continuous integration

The GitHub Actions workflows are configured to run Ruff checks and pytest with coverage on pushes and pull requests. A separate workflow builds distributions and attempts to publish them to PyPI when a version tag matching v* is pushed. The PyPI workflow still contains a placeholder project URL and requires project-specific release configuration before publishing.

Packaging status

Ready for packaging using the Github packaging action.

License

This project is licensed under the MIT License. See `[LICENSE] for details.