Metadata-Version: 2.4
Name: elseware-py
Version: 1.0.0
Summary: Reusable, typed logging infrastructure for Python applications.
Project-URL: Homepage, https://github.com/elsewaretechnology/elseware-py
Project-URL: Issues, https://github.com/elsewaretechnology/elseware-py/issues
Project-URL: Repository, https://github.com/elsewaretechnology/elseware-py
Author-email: elseware Technology <elsewaretechnology@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: elseware,json,logging,structured-logging,utilities
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# elseware-py

Reusable, typed logging infrastructure for Python applications from Elseware
Technology. It builds on Python's standard `logging` module and has no runtime
dependencies.

Importing `elseware-py` never configures the root logger. Applications opt in
by calling `configure_logging`; libraries can safely use `get_logger`.

## Installation

```bash
python -m pip install elseware-py
```

## Text Logging

```python
from elseware_py.logging import (
    LogLevel,
    LoggingConfig,
    configure_logging,
    get_logger,
)

configure_logging(
    LoggingConfig(level=LogLevel.INFO),
    namespace="my_application",
)

logger = get_logger("my_application.worker")
logger.info("Worker started", extra={"worker_id": "worker-1"})
```

Text records contain an RFC 3339 UTC timestamp, level, logger name, message,
and sorted contextual fields.

## JSON Logging

```python
from elseware_py.logging import (
    LogFormat,
    LogLevel,
    LoggingConfig,
    configure_logging,
)

configure_logging(
    LoggingConfig(
        level=LogLevel.INFO,
        format=LogFormat.JSON,
    ),
    namespace="my_application",
)
```

JSON output is newline-delimited and always contains `timestamp`, `level`,
`logger`, and `message`. Context, exception details, and source information are
included when available.

## Context and Exceptions

```python
from elseware_py.logging import get_logger, log_context

logger = get_logger("my_application.jobs")

with log_context(request_id="req-123", job="sync"):
    logger.info("Job started")

    try:
        raise RuntimeError("connection failed")
    except RuntimeError:
        logger.exception("Job failed")
```

Nested contexts restore previous values automatically. Values passed through
`extra` override matching context fields for that record.

## Redaction

Structured fields with common secret names such as `password`, `token`,
`authorization`, and `api_key` are replaced with `[REDACTED]`, including
nested mappings.

Redaction applies to structured context only. Secrets embedded inside a log
message cannot be detected safely and must never be included by application
code.

## Development

Create and activate a virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --editable . --group dev
```

On Windows, activate with:

```powershell
.venv\Scripts\activate
```

Run validation:

```bash
ruff check .
ruff format --check .
mypy
pytest --cov --cov-report=term-missing
```

## Build

```bash
python -m build
twine check --strict dist/*
```

The build creates:

```text
dist/elseware_py-<version>-py3-none-any.whl
dist/elseware_py-<version>.tar.gz
```

## Publish to PyPI

Update `__version__` in `src/elseware_py/__about__.py`, run the complete
validation, build clean artifacts, and upload them manually:

```bash
twine upload dist/*
```

PyPI release files are immutable. Increment the version before publishing a
corrected release.

## License

MIT License
