logging-and-error-handling-kit 0.1.8

Env-aware logging with per-call stdout control and a handy ErrorHandler.

logging-and-error-handling-kit

Env-aware logging with per-call stdout control and rotating file handlers. Designed for services that need clean console logs in dev and quiet consoles in prod—without losing file logs.

Features

• Per-call stdout control: logger.info("...", display_on_stdout=False)
• Env-aware default: console shows logs in local/staging, stays quiet in prod (APP_ENV=prod)
• Rotating files: service.log, errors.log, optional debug.log
• One-liner setup with setup_logger() and get_logger(__name__)
• Compatible with standard logging API; no vendor lock-in.

Install

pip install logging-and-error-handling-kit

Quickstart

from logging_and_error_handling_kit import setup_logger, get_logger

setup_logger()  # once at app startup
log = get_logger(__name__)

log.info("Hello!")                                  # prints in non-prod, always goes to files
log.info("Silent on console", display_on_stdout=False)  # still goes to files
log.error("Oops", display_on_stdout=True)           # force to console (subject to handler level)

## How it decides what hits stdout

* `APP_ENV` controls the **default**:

  * `APP_ENV=prod` → default `display_on_stdout=False`
  * any other (or unset) → default `True`
* You can override per call: `display_on_stdout=True/False`
* Console level via `CONSOLE_LOG_LEVEL` (default `INFO`)

## Environment variables

| Name                           | Default | Purpose                                                 |
| ------------------------------ | ------- | ------------------------------------------------------- |
| `APP_ENV`                      | `local` | Env profile: `local`, `staging`, `prod`…                |
| `CONSOLE_LOG_LEVEL`            | `INFO`  | Console verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `DEBUG`                        | `False` | If `true`, also writes detailed `debug.log`             |
| `LOGS_DIR` *(if you add this)* | `logs`  | Directory for log files                                 |

> Tip: Add a `.env` and use `python-dotenv` (already in dependencies) to load these at startup.

## File outputs (rotating)

* `logs/service.log` → `INFO+`
* `logs/errors.log`  → `ERROR+`
* `logs/debug.log`   → `DEBUG+` (only if `DEBUG=true`)

## API

```python
setup_logger() -> None
    # Initializes handlers/formatters/filters on the root logger.

get_logger(name: str) -> logging.Logger
    # Standard logger retrieval.

clear_logs() -> None
    # Deletes the entire 'logs' directory and its contents.

clear_logs_before(cutoff: str) -> None
    # Purges entries older than cutoff from 'logs/service.log' and 'logs/errors.log'.
    # cutoff accepts 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'.

# Log methods (standard logging API) accept:
logger.info(msg, *args, display_on_stdout: bool = <env default>, **kwargs)
logger.debug(...)
logger.warning(...)
logger.error(...)
logger.critical(...)
logger.exception(msg, *args, display_on_stdout=<env default>, **kwargs)
    # .exception sets exc_info=True automatically

Examples

Service-style bootstrap

import os
from logging_and_error_handling_kit import setup_logger, get_logger
from dotenv import load_dotenv

load_dotenv()        # loads APP_ENV, CONSOLE_LOG_LEVEL, etc.
setup_logger()

log = get_logger("my.service")

log.info("Service starting…")
try:
    1 / 0
except Exception:
    log.exception("Calculation failed", display_on_stdout=True)

Quiet console in prod, verbose locally

# local
export APP_ENV=local
python app.py  # console shows logs

# prod
export APP_ENV=prod
python app.py  # console minimal unless you force display_on_stdout=True

Project structure (suggested)

src/
  logging_and_error_handling_kit/
    __init__.py
    error_handler.py
    logger_config.py
README.md
LICENSE
pyproject.toml

Versioning & releases

1. Bump version in pyproject.toml
2. Build: python -m build
3. Upload: python -m twine upload dist/*
4. Install: pip install logging-and-error-handling-kit

Contributing

Issues and PRs welcome. Please add tests and keep public API stable.

License

MIT – see LICENSE.

---

How to publish the README changes to PyPI

• Edit README.md

• Ensure pyproject.toml has readme = "README.md"

• Rebuild & upload a new version:

  # bump version in pyproject.toml (e.g., 0.1.2)
  python -m build
  python -m twine upload dist/*
  

Maintenance

from logging_and_error_handling_kit import clear_logs, clear_logs_before

# Delete the entire logs directory
clear_logs()

# Purge entries older than the cutoff (keeps newer)
clear_logs_before("2025-10-12")              # date only
clear_logs_before("2025-10-12 09:30:00")     # date and time