# uvulog
A simple logger for console and file logging, with colored output and log rotation.
<span> </span>
## Features
- **Colored terminal output**: ANSI color support, log levels highlighted.
- **File log rotation**: Automatic log file splitting, with cache and size/line limits.
- **Extensible render blocks**: Pluggable blocks for time, process ID, counters, source file, line number, etc.
- **Process safety**: Safe writing in multi-process/multi-threaded environments, with file locking.
- **High performance**: Memory buffering, batch writes, optimized for low overhead.
- **User-friendly API**: Easy integration, shortcut methods (`info`, `debug`, `error`, etc.).
## Quick Start
```python
from uvulog import Logger, Styled, Styles
logger = Logger()
logger.info(Styled("Hello uvulog!", Styles.GREEN, Styles.BOLD))
logger.error(Styled("Something went wrong!", Styles.RED, Styles.UNDERLINE))
```
## Log Levels
- TRACE
- DEBUG
- INFO
- NOTICE
- WARNING
- ERROR
- CRITICAL
Each level supports custom styles and formatting.
## File Log Rotation
- Automatically splits log files by size or line count
- Supports line caching to reduce disk IO
- Safe file locking to prevent concurrent write conflicts
**There is no config to directly enable/disable rotation. To enable this feature, you should add `{rotate_count}`, `{date}` or other enabled keys in blocks to `file`.`save_config`.`file_name_fmt`**
## Render Block Examples
- Timestamp `[2025-09-17 12:00:00]`
- Log level `INFO`
- Main message content
- Process ID, counter, source file, line number, etc.
---
## Installation
```bash
pip install uvulog
```
---
## Configuration Guide
You can fully customize uvulog using a configuration dictionary when creating a `Logger` instance.
Below is a detailed example and explanation of each option:
```python
from uvulog import Logger, Levels
custom_config = {
"logger_name": "myapp",
"console": {
"enabled": True, # Enable console output
"colored": True, # Use ANSI colors in terminal
"level": Levels.DEBUG, # Minimum log level for console
"text_fmt": "{time}{level}{main}\n", # Output format
"blocks_config": { # Customize render blocks
"time": {
"args": [
["[", 90], # Bright black
["{}", 97], # Bright white
["]", 90]
],
"kwargs": {
"time_format": "%H:%M:%S"
}
},
"level": {
"args": [["{}"]],
"kwargs": {
"levels": {
Levels.INFO: [[" I ", 37]], # White
Levels.ERROR: [[" E ", 41, 30]] # Red background, black text
}
}
},
"main": {
"args": [["{}"]],
"kwargs": {
"levels": {
Levels.INFO: [["{}", 37]],
Levels.ERROR: [["{}", 91]] # Bright red
}
}
}
}
},
"file": {
"enabled": True, # Enable file logging
"colored": False, # No ANSI colors in file
"save_config": {
"root_dir": "logs", # Log directory
"file_name_fmt": "myapp.log", # Log file name
"cache_lines": 100, # Buffer lines before writing
"max_lines": 10000, # Max lines per file
"max_size": 10 * 1024 * 1024 # Max size per file (bytes)
},
"level": Levels.INFO, # Minimum log level for file
"text_fmt": "{time}{level}{main}\n",
"blocks_config": None # Use default if None
}
}
logger = Logger(config=custom_config)
```
### Configuration Options
- **logger_name**: Name of the logger, used in output.
- **console.enabled**: Enable/disable console output.
- **console.colored**: Use colored output in terminal.
- **console.level**: Minimum log level for console output.
- **console.text_fmt**: Format string for each log line.
- **console.blocks_config**: Dict to customize each block (time, level, main, etc.).
- **file.enabled**: Enable/disable file logging.
- **file.colored**: Use colored output in log files.
- **file.save_config.root_dir**: Directory to save log files.
- **file.save_config.file_name_fmt**: Log file name format.
- **file.save_config.cache_lines**: Number of lines to buffer before writing.
- **file.save_config.max_lines**: Maximum lines per log file.
- **file.save_config.max_size**: Maximum size per log file (in bytes).
- **file.level**: Minimum log level for file output.
- **file.text_fmt**: Format string for file log lines.
- **file.blocks_config**: Dict to customize blocks for file output.
You can override any block (such as time, level, main) with your own style and format.
---
## Use Cases
- Suitable for AI, data science, web backend, CLI tools, and all Python projects
- Supports multi-process/multi-threaded environments
- Compatible with Linux, Mac, and Windows
---
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/lupnis/uvulog",
"name": "uvulog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": null,
"keywords": "logger, logging, console, file, colored, log rotation",
"author": "Lupnis J H",
"author_email": "Lupnis J H <lupnisj@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/35/bc3a57f2fdb1c8ebc072f0b7ecaa3b8523e2bf98ee5c48590c4de178db82/uvulog-1.0.4.tar.gz",
"platform": null,
"description": "# uvulog\n\nA simple logger for console and file logging, with colored output and log rotation.\n\n\n<span> </span>\n\n\n## Features\n\n- **Colored terminal output**: ANSI color support, log levels highlighted.\n- **File log rotation**: Automatic log file splitting, with cache and size/line limits.\n- **Extensible render blocks**: Pluggable blocks for time, process ID, counters, source file, line number, etc.\n- **Process safety**: Safe writing in multi-process/multi-threaded environments, with file locking.\n- **High performance**: Memory buffering, batch writes, optimized for low overhead.\n- **User-friendly API**: Easy integration, shortcut methods (`info`, `debug`, `error`, etc.).\n\n## Quick Start\n\n```python\nfrom uvulog import Logger, Styled, Styles\n\nlogger = Logger()\nlogger.info(Styled(\"Hello uvulog!\", Styles.GREEN, Styles.BOLD))\nlogger.error(Styled(\"Something went wrong!\", Styles.RED, Styles.UNDERLINE))\n```\n\n## Log Levels\n\n- TRACE\n- DEBUG\n- INFO\n- NOTICE\n- WARNING\n- ERROR\n- CRITICAL\n\nEach level supports custom styles and formatting.\n\n## File Log Rotation\n\n- Automatically splits log files by size or line count\n- Supports line caching to reduce disk IO\n- Safe file locking to prevent concurrent write conflicts\n\n**There is no config to directly enable/disable rotation. To enable this feature, you should add `{rotate_count}`, `{date}` or other enabled keys in blocks to `file`.`save_config`.`file_name_fmt`**\n\n## Render Block Examples\n\n- Timestamp `[2025-09-17 12:00:00]`\n- Log level `INFO`\n- Main message content\n- Process ID, counter, source file, line number, etc.\n\n---\n\n## Installation\n\n```bash\npip install uvulog\n```\n\n---\n\n## Configuration Guide\n\nYou can fully customize uvulog using a configuration dictionary when creating a `Logger` instance. \nBelow is a detailed example and explanation of each option:\n\n```python\nfrom uvulog import Logger, Levels\n\ncustom_config = {\n \"logger_name\": \"myapp\",\n \"console\": {\n \"enabled\": True, # Enable console output\n \"colored\": True, # Use ANSI colors in terminal\n \"level\": Levels.DEBUG, # Minimum log level for console\n \"text_fmt\": \"{time}{level}{main}\\n\", # Output format\n \"blocks_config\": { # Customize render blocks\n \"time\": {\n \"args\": [\n [\"[\", 90], # Bright black\n [\"{}\", 97], # Bright white\n [\"]\", 90]\n ],\n \"kwargs\": {\n \"time_format\": \"%H:%M:%S\"\n }\n },\n \"level\": {\n \"args\": [[\"{}\"]],\n \"kwargs\": {\n \"levels\": {\n Levels.INFO: [[\" I \", 37]], # White\n Levels.ERROR: [[\" E \", 41, 30]] # Red background, black text\n }\n }\n },\n \"main\": {\n \"args\": [[\"{}\"]],\n \"kwargs\": {\n \"levels\": {\n Levels.INFO: [[\"{}\", 37]],\n Levels.ERROR: [[\"{}\", 91]] # Bright red\n }\n }\n }\n }\n },\n \"file\": {\n \"enabled\": True, # Enable file logging\n \"colored\": False, # No ANSI colors in file\n \"save_config\": {\n \"root_dir\": \"logs\", # Log directory\n \"file_name_fmt\": \"myapp.log\", # Log file name\n \"cache_lines\": 100, # Buffer lines before writing\n \"max_lines\": 10000, # Max lines per file\n \"max_size\": 10 * 1024 * 1024 # Max size per file (bytes)\n },\n \"level\": Levels.INFO, # Minimum log level for file\n \"text_fmt\": \"{time}{level}{main}\\n\",\n \"blocks_config\": None # Use default if None\n }\n}\n\nlogger = Logger(config=custom_config)\n```\n\n### Configuration Options\n\n- **logger_name**: Name of the logger, used in output.\n- **console.enabled**: Enable/disable console output.\n- **console.colored**: Use colored output in terminal.\n- **console.level**: Minimum log level for console output.\n- **console.text_fmt**: Format string for each log line.\n- **console.blocks_config**: Dict to customize each block (time, level, main, etc.).\n- **file.enabled**: Enable/disable file logging.\n- **file.colored**: Use colored output in log files.\n- **file.save_config.root_dir**: Directory to save log files.\n- **file.save_config.file_name_fmt**: Log file name format.\n- **file.save_config.cache_lines**: Number of lines to buffer before writing.\n- **file.save_config.max_lines**: Maximum lines per log file.\n- **file.save_config.max_size**: Maximum size per log file (in bytes).\n- **file.level**: Minimum log level for file output.\n- **file.text_fmt**: Format string for file log lines.\n- **file.blocks_config**: Dict to customize blocks for file output.\n\nYou can override any block (such as time, level, main) with your own style and format.\n\n---\n\n## Use Cases\n\n- Suitable for AI, data science, web backend, CLI tools, and all Python projects\n- Supports multi-process/multi-threaded environments\n- Compatible with Linux, Mac, and Windows\n\n---\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple logger for console and file logging, with colored output and log rotation.",
"version": "1.0.4",
"project_urls": {
"Homepage": "https://github.com/lupnis/uvulog"
},
"split_keywords": [
"logger",
" logging",
" console",
" file",
" colored",
" log rotation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f4fc7c3bd9f88cef1d436f79b52bbb44fd8d766c88d567e2964b18037b03a058",
"md5": "c149303c081d65c1ebd5fd0f64883ad9",
"sha256": "7bdbb01efbf5e1ff8cdd3f53f2063dcbc48178302d7099cc01b6cadd7010b6d9"
},
"downloads": -1,
"filename": "uvulog-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c149303c081d65c1ebd5fd0f64883ad9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 12226,
"upload_time": "2025-09-17T11:24:26",
"upload_time_iso_8601": "2025-09-17T11:24:26.975504Z",
"url": "https://files.pythonhosted.org/packages/f4/fc/7c3bd9f88cef1d436f79b52bbb44fd8d766c88d567e2964b18037b03a058/uvulog-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0e35bc3a57f2fdb1c8ebc072f0b7ecaa3b8523e2bf98ee5c48590c4de178db82",
"md5": "0c1f1eeafe2f488f1f3e71cd73064f79",
"sha256": "1faeed741ab00935674aee5540deab778dcaa4114197ac073318a958feb1864b"
},
"downloads": -1,
"filename": "uvulog-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "0c1f1eeafe2f488f1f3e71cd73064f79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 15090,
"upload_time": "2025-09-17T11:24:28",
"upload_time_iso_8601": "2025-09-17T11:24:28.478981Z",
"url": "https://files.pythonhosted.org/packages/0e/35/bc3a57f2fdb1c8ebc072f0b7ecaa3b8523e2bf98ee5c48590c4de178db82/uvulog-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-17 11:24:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lupnis",
"github_project": "uvulog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "uvulog"
}
JSON
