| Name | logging-and-error-handling-kit JSON |
| Version |
0.1.13
JSON |
| download |
| home_page | None |
| Summary | Env-aware logging with per-call stdout control and a handy ErrorHandler. |
| upload_time | 2025-10-14 04:49:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| 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.
|
| keywords |
logging
error-handling
dotenv
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.
[](https://pypi.org/project/logging-and-error-handling-kit/)
[](https://pypi.org/project/logging-and-error-handling-kit/)
[](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("service-name")` 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("translation-service") # 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(name: str) -> ServiceLogger
# Initializes handlers/formatters/filters on the root logger and sets global service name.
get_logger(name: str) -> logging.Logger
# Standard logger retrieval.
clear_logs() -> None
# Deletes the entire 'logs' directory.
clear_logs_befor(cutoff_date: str) -> None
# Prunes entries before the given date ('YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS').
# 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/*
```
Raw data
{
"_id": null,
"home_page": null,
"name": "logging-and-error-handling-kit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "logging, error-handling, dotenv",
"author": null,
"author_email": "Omar <onajialhayek@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/48/0d/b0e211ebcfa3679929bf63b8ecf64941127ebe4a02f5a864f3b14d4afb2f/logging_and_error_handling_kit-0.1.13.tar.gz",
"platform": null,
"description": "# logging-and-error-handling-kit\r\n\r\nEnv-aware logging with per-call stdout control and rotating file handlers.\r\nDesigned for services that need clean console logs in dev and quiet consoles in prod\u2014without losing file logs.\r\n\r\n[](https://pypi.org/project/logging-and-error-handling-kit/)\r\n[](https://pypi.org/project/logging-and-error-handling-kit/)\r\n[](LICENSE)\r\n\r\n## Features\r\n\r\n* **Per-call stdout control**: `logger.info(\"...\", display_on_stdout=False)`\r\n* **Env-aware default**: console shows logs in local/staging, stays quiet in prod (`APP_ENV=prod`)\r\n* **Rotating files**: `service.log`, `errors.log`, optional `debug.log`\r\n* **One-liner setup** with `setup_logger(\"service-name\")` and `get_logger(__name__)`\r\n* Compatible with standard `logging` API; no vendor lock-in.\r\n\r\n## Install\r\n\r\n```bash\r\npip install logging-and-error-handling-kit\r\n```\r\n\r\n## Quickstart\r\n\r\n```python\r\nfrom logging_and_error_handling_kit import setup_logger, get_logger\r\n\r\nsetup_logger(\"translation-service\") # once at app startup\r\nlog = get_logger(__name__)\r\n\r\nlog.info(\"Hello!\") # prints in non-prod, always goes to files\r\nlog.info(\"Silent on console\", display_on_stdout=False) # still goes to files\r\nlog.error(\"Oops\", display_on_stdout=True) # force to console (subject to handler level)\r\n```\r\n\r\n## How it decides what hits stdout\r\n\r\n* `APP_ENV` controls the **default**:\r\n\r\n * `APP_ENV=prod` \u2192 default `display_on_stdout=False`\r\n * any other (or unset) \u2192 default `True`\r\n* You can override per call: `display_on_stdout=True/False`\r\n* Console level via `CONSOLE_LOG_LEVEL` (default `INFO`)\r\n\r\n## Environment variables\r\n\r\n| Name | Default | Purpose |\r\n| ------------------------------ | ------- | ------------------------------------------------------- |\r\n| `APP_ENV` | `local` | Env profile: `local`, `staging`, `prod`\u2026 |\r\n| `CONSOLE_LOG_LEVEL` | `INFO` | Console verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |\r\n| `DEBUG` | `False` | If `true`, also writes detailed `debug.log` |\r\n| `LOGS_DIR` *(if you add this)* | `logs` | Directory for log files |\r\n\r\n> Tip: Add a `.env` and use `python-dotenv` (already in dependencies) to load these at startup.\r\n\r\n## File outputs (rotating)\r\n\r\n* `logs/service.log` \u2192 `INFO+`\r\n* `logs/errors.log` \u2192 `ERROR+`\r\n* `logs/debug.log` \u2192 `DEBUG+` (only if `DEBUG=true`)\r\n\r\n## API\r\n\r\n```python\r\nsetup_logger(name: str) -> ServiceLogger\r\n # Initializes handlers/formatters/filters on the root logger and sets global service name.\r\n\r\nget_logger(name: str) -> logging.Logger\r\n # Standard logger retrieval.\r\n\r\nclear_logs() -> None\r\n # Deletes the entire 'logs' directory.\r\n\r\nclear_logs_befor(cutoff_date: str) -> None\r\n # Prunes entries before the given date ('YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS').\r\n# Log methods (standard logging API) accept:\r\nlogger.info(msg, *args, display_on_stdout: bool = <env default>, **kwargs)\r\nlogger.debug(...)\r\nlogger.warning(...)\r\nlogger.error(...)\r\nlogger.critical(...)\r\nlogger.exception(msg, *args, display_on_stdout=<env default>, **kwargs)\r\n # .exception sets exc_info=True automatically\r\n```\r\n\r\n## Examples\r\n\r\n**Service-style bootstrap**\r\n\r\n```python\r\nimport os\r\nfrom logging_and_error_handling_kit import setup_logger, get_logger\r\nfrom dotenv import load_dotenv\r\n\r\nload_dotenv() # loads APP_ENV, CONSOLE_LOG_LEVEL, etc.\r\nsetup_logger()\r\n\r\nlog = get_logger(\"my.service\")\r\n\r\nlog.info(\"Service starting\u2026\")\r\ntry:\r\n 1 / 0\r\nexcept Exception:\r\n log.exception(\"Calculation failed\", display_on_stdout=True)\r\n```\r\n\r\n**Quiet console in prod, verbose locally**\r\n\r\n```bash\r\n# local\r\nexport APP_ENV=local\r\npython app.py # console shows logs\r\n\r\n# prod\r\nexport APP_ENV=prod\r\npython app.py # console minimal unless you force display_on_stdout=True\r\n```\r\n\r\n## Project structure (suggested)\r\n\r\n```\r\nsrc/\r\n logging_and_error_handling_kit/\r\n __init__.py\r\n error_handler.py\r\n logger_config.py\r\nREADME.md\r\nLICENSE\r\npyproject.toml\r\n```\r\n\r\n## Versioning & releases\r\n\r\n1. Bump `version` in `pyproject.toml`\r\n2. Build: `python -m build`\r\n3. Upload: `python -m twine upload dist/*`\r\n4. Install: `pip install logging-and-error-handling-kit`\r\n\r\n## Contributing\r\n\r\nIssues and PRs welcome. Please add tests and keep public API stable.\r\n\r\n## License\r\n\r\nMIT \u2013 see [LICENSE](LICENSE).\r\n\r\n---\r\n\r\n### How to publish the README changes to PyPI\r\n\r\n* Edit `README.md`\r\n* Ensure `pyproject.toml` has `readme = \"README.md\"`\r\n* Rebuild & upload a **new version**:\r\n\r\n ```bash\r\n # bump version in pyproject.toml (e.g., 0.1.2)\r\n python -m build\r\n python -m twine upload dist/*\r\n ```\r\n",
"bugtrack_url": null,
"license": "MIT License\r\n \r\n Copyright (c) 2025 Omar\r\n \r\n Permission is hereby granted, free of charge, to any person obtaining a copy\r\n of this software and associated documentation files (the \"Software\"), to deal\r\n in the Software without restriction, including without limitation the rights\r\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n copies of the Software, and to permit persons to whom the Software is\r\n furnished to do so, subject to the following conditions:\r\n \r\n The above copyright notice and this permission notice shall be included in\r\n all copies or substantial portions of the Software.\r\n \r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\r\n THE SOFTWARE.\r\n ",
"summary": "Env-aware logging with per-call stdout control and a handy ErrorHandler.",
"version": "0.1.13",
"project_urls": {
"Homepage": "https://github.com/osintclaude-wq/logging_and_error_handling_kit",
"Issues": "https://github.com/osintclaude-wq/logging_and_error_handling_kit/issues",
"Repository": "https://github.com/osintclaude-wq/logging_and_error_handling_kit"
},
"split_keywords": [
"logging",
" error-handling",
" dotenv"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "13072a7a6485f3a1fb737a9eb58a15f630b4f4f4a87035f51e0575b4a0e271e3",
"md5": "d64961e4ec1dd355fcbb73e5c18a706d",
"sha256": "0d99858af5f8822abfc99d6015591a1d4acc324ba640396ea332b7fd46a44916"
},
"downloads": -1,
"filename": "logging_and_error_handling_kit-0.1.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d64961e4ec1dd355fcbb73e5c18a706d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9801,
"upload_time": "2025-10-14T04:49:53",
"upload_time_iso_8601": "2025-10-14T04:49:53.254579Z",
"url": "https://files.pythonhosted.org/packages/13/07/2a7a6485f3a1fb737a9eb58a15f630b4f4f4a87035f51e0575b4a0e271e3/logging_and_error_handling_kit-0.1.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "480db0e211ebcfa3679929bf63b8ecf64941127ebe4a02f5a864f3b14d4afb2f",
"md5": "f7242f43cb64202e32a9ceb24273920f",
"sha256": "35a3b17cd8643d8cbd86918ffce2afc9158f76dd88dda91e3d6a67eb488860e0"
},
"downloads": -1,
"filename": "logging_and_error_handling_kit-0.1.13.tar.gz",
"has_sig": false,
"md5_digest": "f7242f43cb64202e32a9ceb24273920f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 11250,
"upload_time": "2025-10-14T04:49:54",
"upload_time_iso_8601": "2025-10-14T04:49:54.437922Z",
"url": "https://files.pythonhosted.org/packages/48/0d/b0e211ebcfa3679929bf63b8ecf64941127ebe4a02f5a864f3b14d4afb2f/logging_and_error_handling_kit-0.1.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 04:49:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "osintclaude-wq",
"github_project": "logging_and_error_handling_kit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "logging-and-error-handling-kit"
}
