Metadata-Version: 2.4
Name: logging-and-error-handling-kit
Version: 0.1.7
Summary: Env-aware logging with per-call stdout control and a handy ErrorHandler.
Author-email: Omar <onajialhayek@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Omar
        
        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://github.com/osintclaude-wq/logging_and_error_handling_kit
Project-URL: Repository, https://github.com/osintclaude-wq/logging_and_error_handling_kit
Project-URL: Issues, https://github.com/osintclaude-wq/logging_and_error_handling_kit/issues
Keywords: logging,error-handling,dotenv
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv<2,>=1.0.0
Dynamic: license-file

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

[![PyPI](https://img.shields.io/pypi/v/logging-and-error-handling-kit.svg)](https://pypi.org/project/logging-and-error-handling-kit/)
[![Python](https://img.shields.io/pypi/pyversions/logging-and-error-handling-kit.svg)](https://pypi.org/project/logging-and-error-handling-kit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

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

```bash
pip install logging-and-error-handling-kit
```

## Quickstart

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

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

```bash
# 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](LICENSE).

---

### How to publish the README changes to PyPI

* Edit `README.md`
* Ensure `pyproject.toml` has `readme = "README.md"`
* Rebuild & upload a **new version**:

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

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