# Python Logger Utility
A simple, powerful Python logging utility that configures the root logger properly. No more complex setup - just call `rootlog_config()` once and use standard `logging.info()` everywhere.
## Why This Logger?
Python's built-in logging is powerful but complex to set up correctly. This utility provides:
- **One function call** to configure both console and file logging
- **Root logger approach** - works seamlessly across all modules
- **Thread-safe** with optional queue-based logging for high performance
- **Automatic file organization** - logs organized by script/app name
- **Color-coded console output** for better debugging
- **Flexible rotation** - time-based or size-based with human-readable units
- **Graceful error handling** - falls back to console if file logging fails
- **Zero migration** - use standard `logging.info()` calls everywhere
## Quick Start
```python
from rootlog import rootlog_config
import logging
# Configure once at application entry point
rootlog_config(app="myapp")
# Use standard logging everywhere
logging.info("This works perfectly!")
logging.error("Errors are automatically colored red")
logging.debug("Debug messages go to file by default")
```
## Installation
```bash
pip install rootlog-config
```
## Features
### Basic Usage
```python
from rootlog import rootlog_config
import logging
# Minimal setup - uses sensible defaults
rootlog_config()
# Logs to both console (colored) and file (rotated)
logging.info("Hello, world!")
```
### Script-based Logging
```python
# Automatically uses script name for log directory
rootlog_config(script=__file__)
# Creates logs in ~/python-log/my_script/YYYYMMDD-HH.log
```
### Custom Configuration
```python
rootlog_config(
app="myapp",
level_c=logging.WARNING, # Console level
level_f=logging.DEBUG, # File level
format_c="%(levelname)s: %(message)s", # Console format
log_c=True, # Enable console logging
log_f=True, # Enable file logging
)
```
### Thread-Safe High Performance
```python
# For applications with many threads logging frequently
rootlog_config(app="highperf", use_queue=True)
# All logging calls are now queued and handled by background thread
logging.info("Thread-safe logging!")
```
### Flexible Rotation
```python
# Size-based rotation
rootlog_config(app="big", rotation="100 MB")
rootlog_config(app="huge", rotation="1 GB")
# Time-based rotation
rootlog_config(app="daily", rotation="1 day")
rootlog_config(app="hourly", rotation="1 hour")
rootlog_config(app="weekly", rotation="1 week")
rootlog_config(app="midnight", rotation="00:00")
```
### Error Resilience
```python
# If file logging fails (permissions, disk full, etc.)
# automatically falls back to console logging with warning
rootlog_config(app="robust")
logging.info("This works even on read-only filesystems!")
```
## How It Works
This utility follows Python logging best practices:
1. **Configure root logger once** at application startup
2. **Use standard logging calls** (`logging.info()`, etc.) everywhere
3. **No logger instances** to pass around or manage
4. **Automatic cleanup** prevents duplicate log messages
5. **Thread-safe by design** with optional queue support
### Multi-Module Usage
```python
# main.py
from rootlog import rootlog_config
import logging
from mymodule import do_something
rootlog_config(app="myapp")
logging.info("Application started")
do_something()
# mymodule.py
import logging
def do_something():
logging.info("This automatically uses the configured logger!")
logging.error("Errors are properly formatted and colored")
```
### Threading Example
```python
import threading
import time
from rootlog import rootlog_config
import logging
rootlog_config(app="threaded", use_queue=True)
def worker(name):
for i in range(5):
logging.info(f"Worker {name}: Processing item {i}")
time.sleep(0.1)
# Start multiple threads - all logging is thread-safe
threads = []
for i in range(3):
t = threading.Thread(target=worker, args=[f"Thread-{i}"])
threads.append(t)
t.start()
for t in threads:
t.join()
```
## Configuration Options
### Parameters
- **script** (str): Path to script file, uses filename for log directory
- **app** (str): Application name for log directory
- **logger_name** (str): Specific logger name (None = root logger)
- **level_c** (int): Console logging level (default: INFO)
- **level_f** (int): File logging level (default: DEBUG)
- **format_c** (str): Console log format
- **format_f** (str): File log format
- **log_c** (bool): Enable console logging (default: True)
- **log_f** (bool): Enable file logging (default: True)
- **rotation** (str|int): Rotation config ("1 day", "100 MB", etc.)
- **use_queue** (bool): Enable queue-based thread-safe logging
### Log File Organization
Logs are automatically organized:
```
~/python-log/ # Default location (set PY_LOG_PATH to override)
├── myapp/ # App-specific directory
│ ├── 20240315-14.log # Hourly rotation (default)
│ ├── 20240315-15.log
│ └── ...
└── myscript/ # Script-based directory
├── 20240315-09.log
└── ...
```
### Environment Variables
- **PY_LOG_PATH**: Override default log directory (default: `~/python-log`)
- **TESTING**: Set to "true" to append "-testing" to log filenames
## Comparison with Popular Libraries
| Feature | This Logger | Loguru | Structlog | Colorlog |
|---------|-------------|--------|-----------|----------|
| Setup Complexity | Low | Lowest | High | Medium |
| Root Logger Config | ✅ | ❌ | ✅ | ✅ |
| File Rotation | ✅ | ✅ | ❌ | ❌ |
| Thread Safety | ✅ | ✅ | ✅ | ✅ |
| Migration Cost | None | Medium | High | Low |
| File Organization | ✅ | ❌ | ❌ | ❌ |
## Requirements
- Python 3.8+
- colorlog >= 6.9.0
## Development
```bash
# Install dependencies
poetry install
# Run tests
poetry run pytest
# Type checking
poetry run mypy .
# Code formatting
pre-commit run --all-files
```
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions welcome! Please read our development guidelines in CLAUDE.md.
## Why Not Just Use Loguru?
Loguru is excellent, but:
- Creates its own logger instance (not root logger compatible)
- Requires migration of existing `logging.info()` calls
- Abstracts away Python logging concepts
- Less educational for learning proper logging patterns
This utility teaches and uses Python logging correctly while providing modern conveniences.
## Philosophy
> Configure once, log everywhere. Keep it simple, keep it standard.
This utility embraces Python's logging design rather than replacing it. Perfect for developers who want proper logging without complexity or vendor lock-in.
Raw data
{
"_id": null,
"home_page": "https://github.com/byte-pipe/simple-logger",
"name": "rootlog-config",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "logging, logger, console, file, rotation, colors, thread-safe, root-logger",
"author": "Python Logger Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/aa/58/c5be586b313f5fcdbbbb156d6063156b8b68f9d228948598031bb0e28336/rootlog_config-0.2.0.tar.gz",
"platform": null,
"description": "# Python Logger Utility\n\nA simple, powerful Python logging utility that configures the root logger properly. No more complex setup - just call `rootlog_config()` once and use standard `logging.info()` everywhere.\n\n## Why This Logger?\n\nPython's built-in logging is powerful but complex to set up correctly. This utility provides:\n\n- **One function call** to configure both console and file logging\n- **Root logger approach** - works seamlessly across all modules\n- **Thread-safe** with optional queue-based logging for high performance\n- **Automatic file organization** - logs organized by script/app name\n- **Color-coded console output** for better debugging\n- **Flexible rotation** - time-based or size-based with human-readable units\n- **Graceful error handling** - falls back to console if file logging fails\n- **Zero migration** - use standard `logging.info()` calls everywhere\n\n## Quick Start\n\n```python\nfrom rootlog import rootlog_config\nimport logging\n\n# Configure once at application entry point\nrootlog_config(app=\"myapp\")\n\n# Use standard logging everywhere\nlogging.info(\"This works perfectly!\")\nlogging.error(\"Errors are automatically colored red\")\nlogging.debug(\"Debug messages go to file by default\")\n```\n\n## Installation\n\n```bash\npip install rootlog-config\n```\n\n## Features\n\n### Basic Usage\n\n```python\nfrom rootlog import rootlog_config\nimport logging\n\n# Minimal setup - uses sensible defaults\nrootlog_config()\n\n# Logs to both console (colored) and file (rotated)\nlogging.info(\"Hello, world!\")\n```\n\n### Script-based Logging\n\n```python\n# Automatically uses script name for log directory\nrootlog_config(script=__file__)\n\n# Creates logs in ~/python-log/my_script/YYYYMMDD-HH.log\n```\n\n### Custom Configuration\n\n```python\nrootlog_config(\n app=\"myapp\",\n level_c=logging.WARNING, # Console level\n level_f=logging.DEBUG, # File level\n format_c=\"%(levelname)s: %(message)s\", # Console format\n log_c=True, # Enable console logging\n log_f=True, # Enable file logging\n)\n```\n\n### Thread-Safe High Performance\n\n```python\n# For applications with many threads logging frequently\nrootlog_config(app=\"highperf\", use_queue=True)\n\n# All logging calls are now queued and handled by background thread\nlogging.info(\"Thread-safe logging!\")\n```\n\n### Flexible Rotation\n\n```python\n# Size-based rotation\nrootlog_config(app=\"big\", rotation=\"100 MB\")\nrootlog_config(app=\"huge\", rotation=\"1 GB\")\n\n# Time-based rotation\nrootlog_config(app=\"daily\", rotation=\"1 day\")\nrootlog_config(app=\"hourly\", rotation=\"1 hour\")\nrootlog_config(app=\"weekly\", rotation=\"1 week\")\nrootlog_config(app=\"midnight\", rotation=\"00:00\")\n```\n\n### Error Resilience\n\n```python\n# If file logging fails (permissions, disk full, etc.)\n# automatically falls back to console logging with warning\nrootlog_config(app=\"robust\")\nlogging.info(\"This works even on read-only filesystems!\")\n```\n\n## How It Works\n\nThis utility follows Python logging best practices:\n\n1. **Configure root logger once** at application startup\n2. **Use standard logging calls** (`logging.info()`, etc.) everywhere\n3. **No logger instances** to pass around or manage\n4. **Automatic cleanup** prevents duplicate log messages\n5. **Thread-safe by design** with optional queue support\n\n### Multi-Module Usage\n\n```python\n# main.py\nfrom rootlog import rootlog_config\nimport logging\nfrom mymodule import do_something\n\nrootlog_config(app=\"myapp\")\nlogging.info(\"Application started\")\ndo_something()\n\n# mymodule.py\nimport logging\n\ndef do_something():\n logging.info(\"This automatically uses the configured logger!\")\n logging.error(\"Errors are properly formatted and colored\")\n```\n\n### Threading Example\n\n```python\nimport threading\nimport time\nfrom rootlog import rootlog_config\nimport logging\n\nrootlog_config(app=\"threaded\", use_queue=True)\n\ndef worker(name):\n for i in range(5):\n logging.info(f\"Worker {name}: Processing item {i}\")\n time.sleep(0.1)\n\n# Start multiple threads - all logging is thread-safe\nthreads = []\nfor i in range(3):\n t = threading.Thread(target=worker, args=[f\"Thread-{i}\"])\n threads.append(t)\n t.start()\n\nfor t in threads:\n t.join()\n```\n\n## Configuration Options\n\n### Parameters\n\n- **script** (str): Path to script file, uses filename for log directory\n- **app** (str): Application name for log directory\n- **logger_name** (str): Specific logger name (None = root logger)\n- **level_c** (int): Console logging level (default: INFO)\n- **level_f** (int): File logging level (default: DEBUG)\n- **format_c** (str): Console log format\n- **format_f** (str): File log format\n- **log_c** (bool): Enable console logging (default: True)\n- **log_f** (bool): Enable file logging (default: True)\n- **rotation** (str|int): Rotation config (\"1 day\", \"100 MB\", etc.)\n- **use_queue** (bool): Enable queue-based thread-safe logging\n\n### Log File Organization\n\nLogs are automatically organized:\n```\n~/python-log/ # Default location (set PY_LOG_PATH to override)\n\u251c\u2500\u2500 myapp/ # App-specific directory\n\u2502 \u251c\u2500\u2500 20240315-14.log # Hourly rotation (default)\n\u2502 \u251c\u2500\u2500 20240315-15.log\n\u2502 \u2514\u2500\u2500 ...\n\u2514\u2500\u2500 myscript/ # Script-based directory\n \u251c\u2500\u2500 20240315-09.log\n \u2514\u2500\u2500 ...\n```\n\n### Environment Variables\n\n- **PY_LOG_PATH**: Override default log directory (default: `~/python-log`)\n- **TESTING**: Set to \"true\" to append \"-testing\" to log filenames\n\n## Comparison with Popular Libraries\n\n| Feature | This Logger | Loguru | Structlog | Colorlog |\n|---------|-------------|--------|-----------|----------|\n| Setup Complexity | Low | Lowest | High | Medium |\n| Root Logger Config | \u2705 | \u274c | \u2705 | \u2705 |\n| File Rotation | \u2705 | \u2705 | \u274c | \u274c |\n| Thread Safety | \u2705 | \u2705 | \u2705 | \u2705 |\n| Migration Cost | None | Medium | High | Low |\n| File Organization | \u2705 | \u274c | \u274c | \u274c |\n\n## Requirements\n\n- Python 3.8+\n- colorlog >= 6.9.0\n\n## Development\n\n```bash\n# Install dependencies\npoetry install\n\n# Run tests\npoetry run pytest\n\n# Type checking\npoetry run mypy .\n\n# Code formatting\npre-commit run --all-files\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions welcome! Please read our development guidelines in CLAUDE.md.\n\n## Why Not Just Use Loguru?\n\nLoguru is excellent, but:\n- Creates its own logger instance (not root logger compatible)\n- Requires migration of existing `logging.info()` calls\n- Abstracts away Python logging concepts\n- Less educational for learning proper logging patterns\n\nThis utility teaches and uses Python logging correctly while providing modern conveniences.\n\n## Philosophy\n\n> Configure once, log everywhere. Keep it simple, keep it standard.\n\nThis utility embraces Python's logging design rather than replacing it. Perfect for developers who want proper logging without complexity or vendor lock-in.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple Python logging utility that configures the root logger properly. One function call for both console and file logging with colors, rotation, and thread safety.",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/byte-pipe/simple-logger#readme",
"Homepage": "https://github.com/byte-pipe/simple-logger",
"Repository": "https://github.com/byte-pipe/simple-logger"
},
"split_keywords": [
"logging",
" logger",
" console",
" file",
" rotation",
" colors",
" thread-safe",
" root-logger"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "69415a1b38f34bf28cd4db5554f3e7566a45a065d18409cd3fc53d1101247968",
"md5": "c9ad9923c55bf273a8f7156980715aaa",
"sha256": "119da7f3fe2ed3fddd6705c0a3c9872e6de10e8b35c4d6f5a2ef521e3495c192"
},
"downloads": -1,
"filename": "rootlog_config-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9ad9923c55bf273a8f7156980715aaa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 7791,
"upload_time": "2025-09-07T06:42:37",
"upload_time_iso_8601": "2025-09-07T06:42:37.826604Z",
"url": "https://files.pythonhosted.org/packages/69/41/5a1b38f34bf28cd4db5554f3e7566a45a065d18409cd3fc53d1101247968/rootlog_config-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa58c5be586b313f5fcdbbbb156d6063156b8b68f9d228948598031bb0e28336",
"md5": "046eb5286e90ff852157e513aa90e8cd",
"sha256": "e3f0806e0dac75661cb4621e191781cfeca301128fd0207bb3fdd5652485e7f3"
},
"downloads": -1,
"filename": "rootlog_config-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "046eb5286e90ff852157e513aa90e8cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 7559,
"upload_time": "2025-09-07T06:42:39",
"upload_time_iso_8601": "2025-09-07T06:42:39.100454Z",
"url": "https://files.pythonhosted.org/packages/aa/58/c5be586b313f5fcdbbbb156d6063156b8b68f9d228948598031bb0e28336/rootlog_config-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 06:42:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "byte-pipe",
"github_project": "simple-logger",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"lcname": "rootlog-config"
}
JSON
