# Rich UTF-8 Logger
A high-performance, thread-safe logging library built with Python's logging module and enhanced with the Rich library for beautiful console output with full UTF-8 support.
## Features
- **Rich Console Output**: Beautiful, colored logging with the Rich library
- **Thread-Safe Queue Logging**: Asynchronous, non-blocking log processing
- **File Rotation**: Automatic log file rotation with custom naming (e.g., `app_1.log`, `app_2.log`)
- **UTF-8 Support**: Full Unicode and emoji support in log files
- **Configuration Management**: Flexible configuration via `app_config.ini`
- **Windows Optimized**: Special handling for Windows file access issues
- **Multiple Logger Types**: Console-only, file-only, and combined loggers
## Installation
```bash
pip install rich_utf8_logger
```
## Quick Start
```python
from rich_utf8_logger import get_logger
# Create a basic logger
logger = get_logger("my_app")
# Log messages
logger.info("Application started")
logger.warning("This is a warning")
logger.error("An error occurred")
```
## Logger Types
### Basic Logger
```python
from rich_logger import get_logger
logger = get_logger("app_name")
```
### File Logger with Rotation
```python
from rich_utf8_logger import get_logger_with_file_handler
logger = get_logger_with_file_handler("app_name")
```
### Queue Logger (Thread-Safe)
```python
from rich_utf8_logger import get_logger_with_queue
logger = get_logger_with_queue("app_name")
```
### Queue Logger with File Output
```python
from rich_utf8_logger import get_logger_with_queue_and_file
logger = get_logger_with_queue_and_file("app_name")
```
## Configuration
Create `app_config.ini` in your project root:
```ini
[app]
name = my_app
[logging]
level = INFO
format = %%(levelname)s %%(name)s - %%(message)s
console_format = %%(levelname)s %%(message)s
logs_dir = logs
max_bytes = 10485760
backup_count = 5
queue_enabled = true
queue_size = 100
flush_interval = 0.1
```
### Configuration Options
| Option | Description | Default |
|--------|-------------|---------|
| `level` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
| `format` | Log message format for files | `%(levelname)s %(name)s - %(message)s` |
| `console_format` | Log message format for console | `%(levelname)s %(message)s` |
| `logs_dir` | Directory for log files | `logs` |
| `max_bytes` | Maximum log file size before rotation | 1MB (1048576) |
| `backup_count` | Number of backup files to keep | 5 |
| `queue_enabled` | Enable thread-safe queue logging | true |
| `queue_size` | Maximum queue size for log records | 100 |
| `flush_interval` | Queue flush interval in seconds | 0.1 |
## Log Rotation
Log files automatically rotate when they reach the configured size limit. Backup files use sequential naming:
- `app.log` (current log file)
- `app_1.log` (first backup)
- `app_2.log` (second backup)
- `app_3.log` (third backup)
## Thread Safety
The queue-based loggers provide thread-safe logging by:
- Buffering log records in a thread-safe queue
- Processing logs in a dedicated worker thread
- Non-blocking log emission
- Configurable queue size and flush intervals
## Usage Examples
### Basic Application Logging
```python
from rich_utf8_logger import get_logger
logger = get_logger("my_application")
def main():
logger.info("Starting application")
try:
# Your application logic here
logger.info("Application running successfully")
except Exception as e:
logger.error(f"Application error: {e}")
logger.info("Application finished")
if __name__ == "__main__":
main()
```
### Web Application with File Logging
```python
from rich_utf8_logger import get_logger_with_file_handler
import time
logger = get_logger_with_file_handler("web_app")
def handle_request(request_id):
logger.info(f"Processing request {request_id}")
time.sleep(0.1) # Simulate work
logger.info(f"Request {request_id} completed")
# Simulate multiple requests
for i in range(100):
handle_request(i)
```
### High-Performance Logging
```python
from rich_utf8_logger import get_logger_with_queue_and_file
import threading
import time
logger = get_logger_with_queue_and_file("high_perf_app")
def worker(worker_id):
for i in range(1000):
logger.info(f"Worker {worker_id}: Message {i}")
time.sleep(0.001) # Very fast logging
# Start multiple worker threads
threads = []
for i in range(5):
t = threading.Thread(target=worker, args=(i,))
t.start()
threads.append(t)
# Wait for completion
for t in threads:
t.join()
# Clean up
from rich_utf8_logger import cleanup_loggers
cleanup_loggers()
```
## Performance Considerations
- **Queue Size**: Smaller queue sizes (100-1000) provide better real-time logging
- **Flush Interval**: Lower intervals (0.1-0.5s) reduce latency but increase CPU usage
- **File Rotation**: Frequent rotation can impact performance on slower storage
- **Thread Count**: More worker threads increase throughput but also resource usage
## Troubleshooting
### Console Colors Not Working
Ensure your terminal supports ANSI color codes. For Windows, use Windows Terminal or enable ANSI support.
### Log Files Not Rotating
Check that:
- File size exceeds `max_bytes` setting
- `backup_count` is greater than 0
- Application has write permissions to the logs directory
### Queue Full Warnings
Increase `queue_size` or reduce logging frequency if you see "queue is full" warnings.
### File Access Errors on Windows
The library includes special handling for Windows file access issues. If problems persist, ensure no other processes are accessing the log files.
## API Reference
### Functions
- `get_logger(name, level, config_file)` - Basic Rich logger
- `get_logger_with_file_handler(name, level, log_file, config_file)` - Logger with file output
- `get_logger_with_queue(name, level, config_file)` - Thread-safe queue logger
- `get_logger_with_queue_and_file(name, level, log_file, config_file)` - Complete solution
- `cleanup_loggers()` - Clean up all loggers and handlers
### Classes
- `WindowsSafeRotatingFileHandler` - Windows-optimized file rotation
- `ThreadSafeQueueHandler` - Asynchronous log processing
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
Raw data
{
"_id": null,
"home_page": "https://github.com/kpandiyaraj/rich_utf8_logger",
"name": "rich-utf8-logger",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Pandiyaraj Karuppasamy <pandiyarajk@live.com>",
"keywords": "logging, rich, console, utf8, unicode, thread-safe, file-rotation, windows",
"author": "Pandiyaraj Karuppasamy",
"author_email": "Pandiyaraj Karuppasamy <pandiyarajk@live.com>",
"download_url": "https://files.pythonhosted.org/packages/26/a0/a3a162e57feb8455d471f0c85e0a1cc5bf2125a6e240511a72c2fb9c7fbf/rich_utf8_logger-0.0.1.tar.gz",
"platform": null,
"description": "# Rich UTF-8 Logger\r\n\r\nA high-performance, thread-safe logging library built with Python's logging module and enhanced with the Rich library for beautiful console output with full UTF-8 support.\r\n\r\n## Features\r\n\r\n- **Rich Console Output**: Beautiful, colored logging with the Rich library\r\n- **Thread-Safe Queue Logging**: Asynchronous, non-blocking log processing\r\n- **File Rotation**: Automatic log file rotation with custom naming (e.g., `app_1.log`, `app_2.log`)\r\n- **UTF-8 Support**: Full Unicode and emoji support in log files\r\n- **Configuration Management**: Flexible configuration via `app_config.ini`\r\n- **Windows Optimized**: Special handling for Windows file access issues\r\n- **Multiple Logger Types**: Console-only, file-only, and combined loggers\r\n\r\n## Installation\r\n\r\n```bash\r\npip install rich_utf8_logger\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom rich_utf8_logger import get_logger\r\n\r\n# Create a basic logger\r\nlogger = get_logger(\"my_app\")\r\n\r\n# Log messages\r\nlogger.info(\"Application started\")\r\nlogger.warning(\"This is a warning\")\r\nlogger.error(\"An error occurred\")\r\n```\r\n\r\n## Logger Types\r\n\r\n### Basic Logger\r\n```python\r\nfrom rich_logger import get_logger\r\n\r\nlogger = get_logger(\"app_name\")\r\n```\r\n\r\n### File Logger with Rotation\r\n```python\r\nfrom rich_utf8_logger import get_logger_with_file_handler\r\n\r\nlogger = get_logger_with_file_handler(\"app_name\")\r\n```\r\n\r\n### Queue Logger (Thread-Safe)\r\n```python\r\nfrom rich_utf8_logger import get_logger_with_queue\r\n\r\nlogger = get_logger_with_queue(\"app_name\")\r\n```\r\n\r\n### Queue Logger with File Output\r\n```python\r\nfrom rich_utf8_logger import get_logger_with_queue_and_file\r\n\r\nlogger = get_logger_with_queue_and_file(\"app_name\")\r\n```\r\n\r\n## Configuration\r\n\r\nCreate `app_config.ini` in your project root:\r\n\r\n```ini\r\n[app]\r\nname = my_app\r\n\r\n[logging]\r\nlevel = INFO\r\nformat = %%(levelname)s %%(name)s - %%(message)s\r\nconsole_format = %%(levelname)s %%(message)s\r\nlogs_dir = logs\r\nmax_bytes = 10485760\r\nbackup_count = 5\r\nqueue_enabled = true\r\nqueue_size = 100\r\nflush_interval = 0.1\r\n```\r\n\r\n### Configuration Options\r\n\r\n| Option | Description | Default |\r\n|--------|-------------|---------|\r\n| `level` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |\r\n| `format` | Log message format for files | `%(levelname)s %(name)s - %(message)s` |\r\n| `console_format` | Log message format for console | `%(levelname)s %(message)s` |\r\n| `logs_dir` | Directory for log files | `logs` |\r\n| `max_bytes` | Maximum log file size before rotation | 1MB (1048576) |\r\n| `backup_count` | Number of backup files to keep | 5 |\r\n| `queue_enabled` | Enable thread-safe queue logging | true |\r\n| `queue_size` | Maximum queue size for log records | 100 |\r\n| `flush_interval` | Queue flush interval in seconds | 0.1 |\r\n\r\n## Log Rotation\r\n\r\nLog files automatically rotate when they reach the configured size limit. Backup files use sequential naming:\r\n\r\n- `app.log` (current log file)\r\n- `app_1.log` (first backup)\r\n- `app_2.log` (second backup)\r\n- `app_3.log` (third backup)\r\n\r\n## Thread Safety\r\n\r\nThe queue-based loggers provide thread-safe logging by:\r\n\r\n- Buffering log records in a thread-safe queue\r\n- Processing logs in a dedicated worker thread\r\n- Non-blocking log emission\r\n- Configurable queue size and flush intervals\r\n\r\n## Usage Examples\r\n\r\n### Basic Application Logging\r\n```python\r\nfrom rich_utf8_logger import get_logger\r\n\r\nlogger = get_logger(\"my_application\")\r\n\r\ndef main():\r\n logger.info(\"Starting application\")\r\n \r\n try:\r\n # Your application logic here\r\n logger.info(\"Application running successfully\")\r\n except Exception as e:\r\n logger.error(f\"Application error: {e}\")\r\n \r\n logger.info(\"Application finished\")\r\n\r\nif __name__ == \"__main__\":\r\n main()\r\n```\r\n\r\n### Web Application with File Logging\r\n```python\r\nfrom rich_utf8_logger import get_logger_with_file_handler\r\nimport time\r\n\r\nlogger = get_logger_with_file_handler(\"web_app\")\r\n\r\ndef handle_request(request_id):\r\n logger.info(f\"Processing request {request_id}\")\r\n time.sleep(0.1) # Simulate work\r\n logger.info(f\"Request {request_id} completed\")\r\n\r\n# Simulate multiple requests\r\nfor i in range(100):\r\n handle_request(i)\r\n```\r\n\r\n### High-Performance Logging\r\n```python\r\nfrom rich_utf8_logger import get_logger_with_queue_and_file\r\nimport threading\r\nimport time\r\n\r\nlogger = get_logger_with_queue_and_file(\"high_perf_app\")\r\n\r\ndef worker(worker_id):\r\n for i in range(1000):\r\n logger.info(f\"Worker {worker_id}: Message {i}\")\r\n time.sleep(0.001) # Very fast logging\r\n\r\n# Start multiple worker threads\r\nthreads = []\r\nfor i in range(5):\r\n t = threading.Thread(target=worker, args=(i,))\r\n t.start()\r\n threads.append(t)\r\n\r\n# Wait for completion\r\nfor t in threads:\r\n t.join()\r\n\r\n# Clean up\r\nfrom rich_utf8_logger import cleanup_loggers\r\ncleanup_loggers()\r\n```\r\n\r\n## Performance Considerations\r\n\r\n- **Queue Size**: Smaller queue sizes (100-1000) provide better real-time logging\r\n- **Flush Interval**: Lower intervals (0.1-0.5s) reduce latency but increase CPU usage\r\n- **File Rotation**: Frequent rotation can impact performance on slower storage\r\n- **Thread Count**: More worker threads increase throughput but also resource usage\r\n\r\n## Troubleshooting\r\n\r\n### Console Colors Not Working\r\nEnsure your terminal supports ANSI color codes. For Windows, use Windows Terminal or enable ANSI support.\r\n\r\n### Log Files Not Rotating\r\nCheck that:\r\n- File size exceeds `max_bytes` setting\r\n- `backup_count` is greater than 0\r\n- Application has write permissions to the logs directory\r\n\r\n### Queue Full Warnings\r\nIncrease `queue_size` or reduce logging frequency if you see \"queue is full\" warnings.\r\n\r\n### File Access Errors on Windows\r\nThe library includes special handling for Windows file access issues. If problems persist, ensure no other processes are accessing the log files.\r\n\r\n## API Reference\r\n\r\n### Functions\r\n\r\n- `get_logger(name, level, config_file)` - Basic Rich logger\r\n- `get_logger_with_file_handler(name, level, log_file, config_file)` - Logger with file output\r\n- `get_logger_with_queue(name, level, config_file)` - Thread-safe queue logger\r\n- `get_logger_with_queue_and_file(name, level, log_file, config_file)` - Complete solution\r\n- `cleanup_loggers()` - Clean up all loggers and handlers\r\n\r\n### Classes\r\n\r\n- `WindowsSafeRotatingFileHandler` - Windows-optimized file rotation\r\n- `ThreadSafeQueueHandler` - Asynchronous log processing\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests if applicable\r\n5. Submit a pull request\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Changelog\r\n\r\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A high-performance, thread-safe logging library with Rich console output and UTF-8 support",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/kpandiyaraj/rich_utf8_logger/issues",
"Changelog": "https://github.com/kpandiyaraj/rich_utf8_logger/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/kpandiyaraj/rich_utf8_logger#readme",
"Homepage": "https://github.com/kpandiyaraj/rich_utf8_logger",
"Repository": "https://github.com/kpandiyaraj/rich_utf8_logger"
},
"split_keywords": [
"logging",
" rich",
" console",
" utf8",
" unicode",
" thread-safe",
" file-rotation",
" windows"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2abf92db2058d63c7b1ef54157ef5cd99bdef88917b7b02e52c27f93f64a2cea",
"md5": "547309e234f649f8609f42c143df9f34",
"sha256": "c308882cb6e1e24cc20a81721f19e774a83f95223040665f8dc0458c8e38288a"
},
"downloads": -1,
"filename": "rich_utf8_logger-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "547309e234f649f8609f42c143df9f34",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9579,
"upload_time": "2025-08-16T18:31:45",
"upload_time_iso_8601": "2025-08-16T18:31:45.480042Z",
"url": "https://files.pythonhosted.org/packages/2a/bf/92db2058d63c7b1ef54157ef5cd99bdef88917b7b02e52c27f93f64a2cea/rich_utf8_logger-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "26a0a3a162e57feb8455d471f0c85e0a1cc5bf2125a6e240511a72c2fb9c7fbf",
"md5": "626c6c65880b7d4ccd27eecaba9f0403",
"sha256": "2c32f4f3788fc054fe0a85c4d06fa5c3e7bf6db39dc9277b84834fc2d581454f"
},
"downloads": -1,
"filename": "rich_utf8_logger-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "626c6c65880b7d4ccd27eecaba9f0403",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16079,
"upload_time": "2025-08-16T18:31:47",
"upload_time_iso_8601": "2025-08-16T18:31:47.310966Z",
"url": "https://files.pythonhosted.org/packages/26/a0/a3a162e57feb8455d471f0c85e0a1cc5bf2125a6e240511a72c2fb9c7fbf/rich_utf8_logger-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 18:31:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kpandiyaraj",
"github_project": "rich_utf8_logger",
"github_not_found": true,
"lcname": "rich-utf8-logger"
}
JSON
