Metadata-Version: 2.4
Name: Logging-utils-dnc
Version: 0.0.1
Summary: Logging utilities for Python
Author-email: Dave <dave@caracappa.com>
License: The MIT License (MIT)
        Copyright © 2026 Dave Caracappa
        
        Permission is hereby granted, free of charge, to any person obtaining a 
        copy of this software and associated documentation files (the “Software”), 
        to deal in the Software without restriction, including without limitation 
        the rights to use, copy, modify, merge, publish, distribute, sublicense, 
        and/or sell copies of the Software, and to permit persons to whom the 
        Software is furnished to do so, subject to the following conditions:
            
            The above copyright notice and this permission notice shall be 
            included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS 
        OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
        THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
        DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://dncarac.github.io/logging/README.md
Project-URL: Repository, https://github.com/dncarac/logging
Project-URL: Issues, https://github.com/dncarac/logging/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: build>=1.6.1; extra == "dev"
Dynamic: license-file

# 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:

```python
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:

```python
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:

```powershell
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

```powershell
python -m pytest
```

Run the test suite with coverage and print the report:

```powershell
coverage run -m pytest
coverage report
```

### Run Ruff

Check the source module for lint issues and formatting:

```powershell
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

```text
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.
