# YaoLogit
[](https://pypi.org/project/yaologit/)
[](https://opensource.org/licenses/MIT)
YaoLogit is a process-safe logging package built on top of [loguru](https://github.com/Delgan/loguru) that ensures only one logger instance is created per Python process, including subprocesses. It provides a simple, powerful, and thread-safe logging solution for Python applications.
## Features
- **Process-Safe Singleton**: Ensures only one logger instance across all processes and subprocesses
- **Thread-Safe**: Uses loguru's `enqueue` parameter for thread-safe logging
- **Automatic Log Rotation**: Built-in support for time-based and size-based log rotation
- **Log Compression**: Automatic compression of rotated logs
- **Flexible Configuration**: Configure via code, environment variables, or configuration files
- **Multiple Log Levels**: Separate log files for different log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
- **Easy Integration**: Drop-in replacement for standard logging with minimal code changes
- **Cross-Platform**: Works on Windows, Linux, and macOS
## Installation
Install YaoLogit using pip:
```bash
pip install yaologit
```
## Quick Start
### Basic Usage
```python
from yaologit import get_logger
# Get logger instance
logger = get_logger()
# Log messages
logger.info("This is an info message")
logger.debug("This is a debug message")
logger.warning("This is a warning message")
logger.error("This is an error message")
logger.critical("This is a critical message")
```
### Custom Configuration
```python
from yaologit import get_logger
# Configure logger with custom settings
logger = get_logger(
name="myapp",
log_dir="./logs",
verbose=True,
rotation="100 MB",
retention="30 days",
compression="zip"
)
logger.info("Logger configured with custom settings")
```
### Advanced Configuration
```python
from yaologit import YaoLogit, YaoLogitConfig
# Create custom configuration
config = YaoLogitConfig(
name="myapp",
log_dir="./logs",
levels=["INFO", "WARNING", "ERROR"],
separate_by_level=True,
rotation="1 day",
retention="7 days",
compression="gz",
format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | <level>{message}</level>"
)
# Initialize YaoLogit
YaoLogit.configure(config)
logger = YaoLogit.get_logger()
logger.info("Advanced configuration applied")
```
### Environment Variables
YaoLogit can be configured using environment variables:
```bash
export YAOLOGIT_NAME=myapp
export YAOLOGIT_LOG_DIR=/var/log/myapp
export YAOLOGIT_VERBOSE=true
export YAOLOGIT_ROTATION="100 MB"
export YAOLOGIT_RETENTION="30 days"
export YAOLOGIT_LEVELS="INFO,WARNING,ERROR"
```
Then in your code:
```python
from yaologit import YaoLogit, YaoLogitConfig
# Load configuration from environment
config = YaoLogitConfig.from_env()
YaoLogit.configure(config)
logger = YaoLogit.get_logger()
```
### Context Manager
Use context managers for temporary logging contexts:
```python
from yaologit import YaoLogit
YaoLogit.configure()
with YaoLogit.session("data_processing", user_id=12345) as logger:
logger.info("Processing started")
# ... do processing ...
logger.info("Processing completed")
```
### Multiprocessing Example
YaoLogit ensures consistent logging across multiple processes:
```python
import multiprocessing
from yaologit import get_logger
def worker_function(worker_id):
# Each process will use the same logger instance
logger = get_logger("myapp")
logger.info(f"Worker {worker_id} started")
# ... do work ...
logger.info(f"Worker {worker_id} finished")
if __name__ == "__main__":
# Initialize logger in main process
logger = get_logger("myapp", log_dir="./logs")
logger.info("Main process started")
# Create worker processes
processes = []
for i in range(4):
p = multiprocessing.Process(target=worker_function, args=(i,))
p.start()
processes.append(p)
# Wait for all processes to complete
for p in processes:
p.join()
logger.info("All workers completed")
```
## Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `name` | str | "yaologit" | Logger name |
| `log_dir` | str/Path | "./logs" | Directory for log files |
| `verbose` | bool | True | Enable console output |
| `levels` | List[str] | ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | Log levels to handle |
| `separate_by_level` | bool | True | Create separate files for each log level |
| `enqueue` | bool | True | Enable thread-safe logging |
| `rotation` | str | "1 day" | When to rotate log files |
| `retention` | str | "7 days" | How long to keep old logs |
| `compression` | str | "zip" | Compression format for rotated logs |
| `format` | str | (see below) | Log message format |
| `console_output` | bool | True | Enable console output |
| `console_level` | str | "INFO" | Minimum level for console output |
### Default Format
```
<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | <level>{message}</level>
```
## API Reference
### `get_logger(name=None, log_dir=None, verbose=True, **kwargs)`
Get a logger instance with the specified configuration.
**Parameters:**
- `name` (str, optional): Logger name
- `log_dir` (str, optional): Log directory path
- `verbose` (bool): Enable console output
- `**kwargs`: Additional configuration options
**Returns:**
- `loguru.Logger`: Logger instance
### `YaoLogit.configure(config=None, **kwargs)`
Configure the YaoLogit singleton.
**Parameters:**
- `config` (YaoLogitConfig, optional): Configuration object
- `**kwargs`: Configuration options to override
**Returns:**
- `YaoLogit`: YaoLogit instance
### `YaoLogit.get_logger()`
Get the configured logger instance.
**Returns:**
- `loguru.Logger`: Logger instance
**Raises:**
- `LoggerNotInitializedError`: If logger not configured
### `YaoLogit.session(name, **kwargs)`
Create a temporary logging context.
**Parameters:**
- `name` (str): Session name
- `**kwargs`: Additional context data
**Yields:**
- `loguru.Logger`: Contextualized logger
## Development
### Setting up development environment
```bash
# Clone the repository
git clone https://github.com/yourusername/yaologit.git
cd yaologit
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"
```
### Running tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=yaologit
# Run specific test file
pytest tests/test_core.py
```
### Code formatting
```bash
# Format code with black
black yaologit tests
# Check code style
flake8 yaologit tests
# Type checking
mypy yaologit
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built on top of the excellent [loguru](https://github.com/Delgan/loguru) library
- Inspired by the need for process-safe logging in multiprocessing applications
## Changelog
### 0.1.0 (2025-01-11)
- Initial release
- Process-safe singleton implementation
- Thread-safe logging with loguru
- Automatic log rotation and compression
- Flexible configuration system
- Support for multiple log levels
- Environment variable configuration
- Context manager support
Raw data
{
"_id": null,
"home_page": null,
"name": "yaologit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Yaohua Guo <guo.yaohua@foxmail.com>",
"keywords": "logging, loguru, process-safe, multiprocessing, logger",
"author": null,
"author_email": "Yaohua Guo <guo.yaohua@foxmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c9/19/99eaf865ff91bc2a7980af27e3a27b88b5ea5ad2eabbecd166630e5b589c/yaologit-0.2.0.tar.gz",
"platform": null,
"description": "# YaoLogit\r\n\r\n[](https://pypi.org/project/yaologit/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nYaoLogit is a process-safe logging package built on top of [loguru](https://github.com/Delgan/loguru) that ensures only one logger instance is created per Python process, including subprocesses. It provides a simple, powerful, and thread-safe logging solution for Python applications.\r\n\r\n## Features\r\n\r\n- **Process-Safe Singleton**: Ensures only one logger instance across all processes and subprocesses\r\n- **Thread-Safe**: Uses loguru's `enqueue` parameter for thread-safe logging\r\n- **Automatic Log Rotation**: Built-in support for time-based and size-based log rotation\r\n- **Log Compression**: Automatic compression of rotated logs\r\n- **Flexible Configuration**: Configure via code, environment variables, or configuration files\r\n- **Multiple Log Levels**: Separate log files for different log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)\r\n- **Easy Integration**: Drop-in replacement for standard logging with minimal code changes\r\n- **Cross-Platform**: Works on Windows, Linux, and macOS\r\n\r\n## Installation\r\n\r\nInstall YaoLogit using pip:\r\n\r\n```bash\r\npip install yaologit\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom yaologit import get_logger\r\n\r\n# Get logger instance\r\nlogger = get_logger()\r\n\r\n# Log messages\r\nlogger.info(\"This is an info message\")\r\nlogger.debug(\"This is a debug message\")\r\nlogger.warning(\"This is a warning message\")\r\nlogger.error(\"This is an error message\")\r\nlogger.critical(\"This is a critical message\")\r\n```\r\n\r\n### Custom Configuration\r\n\r\n```python\r\nfrom yaologit import get_logger\r\n\r\n# Configure logger with custom settings\r\nlogger = get_logger(\r\n name=\"myapp\",\r\n log_dir=\"./logs\",\r\n verbose=True,\r\n rotation=\"100 MB\",\r\n retention=\"30 days\",\r\n compression=\"zip\"\r\n)\r\n\r\nlogger.info(\"Logger configured with custom settings\")\r\n```\r\n\r\n### Advanced Configuration\r\n\r\n```python\r\nfrom yaologit import YaoLogit, YaoLogitConfig\r\n\r\n# Create custom configuration\r\nconfig = YaoLogitConfig(\r\n name=\"myapp\",\r\n log_dir=\"./logs\",\r\n levels=[\"INFO\", \"WARNING\", \"ERROR\"],\r\n separate_by_level=True,\r\n rotation=\"1 day\",\r\n retention=\"7 days\",\r\n compression=\"gz\",\r\n format=\"<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | <level>{message}</level>\"\r\n)\r\n\r\n# Initialize YaoLogit\r\nYaoLogit.configure(config)\r\nlogger = YaoLogit.get_logger()\r\n\r\nlogger.info(\"Advanced configuration applied\")\r\n```\r\n\r\n### Environment Variables\r\n\r\nYaoLogit can be configured using environment variables:\r\n\r\n```bash\r\nexport YAOLOGIT_NAME=myapp\r\nexport YAOLOGIT_LOG_DIR=/var/log/myapp\r\nexport YAOLOGIT_VERBOSE=true\r\nexport YAOLOGIT_ROTATION=\"100 MB\"\r\nexport YAOLOGIT_RETENTION=\"30 days\"\r\nexport YAOLOGIT_LEVELS=\"INFO,WARNING,ERROR\"\r\n```\r\n\r\nThen in your code:\r\n\r\n```python\r\nfrom yaologit import YaoLogit, YaoLogitConfig\r\n\r\n# Load configuration from environment\r\nconfig = YaoLogitConfig.from_env()\r\nYaoLogit.configure(config)\r\nlogger = YaoLogit.get_logger()\r\n```\r\n\r\n### Context Manager\r\n\r\nUse context managers for temporary logging contexts:\r\n\r\n```python\r\nfrom yaologit import YaoLogit\r\n\r\nYaoLogit.configure()\r\n\r\nwith YaoLogit.session(\"data_processing\", user_id=12345) as logger:\r\n logger.info(\"Processing started\")\r\n # ... do processing ...\r\n logger.info(\"Processing completed\")\r\n```\r\n\r\n### Multiprocessing Example\r\n\r\nYaoLogit ensures consistent logging across multiple processes:\r\n\r\n```python\r\nimport multiprocessing\r\nfrom yaologit import get_logger\r\n\r\ndef worker_function(worker_id):\r\n # Each process will use the same logger instance\r\n logger = get_logger(\"myapp\")\r\n logger.info(f\"Worker {worker_id} started\")\r\n # ... do work ...\r\n logger.info(f\"Worker {worker_id} finished\")\r\n\r\nif __name__ == \"__main__\":\r\n # Initialize logger in main process\r\n logger = get_logger(\"myapp\", log_dir=\"./logs\")\r\n logger.info(\"Main process started\")\r\n \r\n # Create worker processes\r\n processes = []\r\n for i in range(4):\r\n p = multiprocessing.Process(target=worker_function, args=(i,))\r\n p.start()\r\n processes.append(p)\r\n \r\n # Wait for all processes to complete\r\n for p in processes:\r\n p.join()\r\n \r\n logger.info(\"All workers completed\")\r\n```\r\n\r\n## Configuration Options\r\n\r\n| Option | Type | Default | Description |\r\n|--------|------|---------|-------------|\r\n| `name` | str | \"yaologit\" | Logger name |\r\n| `log_dir` | str/Path | \"./logs\" | Directory for log files |\r\n| `verbose` | bool | True | Enable console output |\r\n| `levels` | List[str] | [\"DEBUG\", \"INFO\", \"WARNING\", \"ERROR\", \"CRITICAL\"] | Log levels to handle |\r\n| `separate_by_level` | bool | True | Create separate files for each log level |\r\n| `enqueue` | bool | True | Enable thread-safe logging |\r\n| `rotation` | str | \"1 day\" | When to rotate log files |\r\n| `retention` | str | \"7 days\" | How long to keep old logs |\r\n| `compression` | str | \"zip\" | Compression format for rotated logs |\r\n| `format` | str | (see below) | Log message format |\r\n| `console_output` | bool | True | Enable console output |\r\n| `console_level` | str | \"INFO\" | Minimum level for console output |\r\n\r\n### Default Format\r\n\r\n```\r\n<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | <level>{message}</level>\r\n```\r\n\r\n## API Reference\r\n\r\n### `get_logger(name=None, log_dir=None, verbose=True, **kwargs)`\r\n\r\nGet a logger instance with the specified configuration.\r\n\r\n**Parameters:**\r\n- `name` (str, optional): Logger name\r\n- `log_dir` (str, optional): Log directory path\r\n- `verbose` (bool): Enable console output\r\n- `**kwargs`: Additional configuration options\r\n\r\n**Returns:**\r\n- `loguru.Logger`: Logger instance\r\n\r\n### `YaoLogit.configure(config=None, **kwargs)`\r\n\r\nConfigure the YaoLogit singleton.\r\n\r\n**Parameters:**\r\n- `config` (YaoLogitConfig, optional): Configuration object\r\n- `**kwargs`: Configuration options to override\r\n\r\n**Returns:**\r\n- `YaoLogit`: YaoLogit instance\r\n\r\n### `YaoLogit.get_logger()`\r\n\r\nGet the configured logger instance.\r\n\r\n**Returns:**\r\n- `loguru.Logger`: Logger instance\r\n\r\n**Raises:**\r\n- `LoggerNotInitializedError`: If logger not configured\r\n\r\n### `YaoLogit.session(name, **kwargs)`\r\n\r\nCreate a temporary logging context.\r\n\r\n**Parameters:**\r\n- `name` (str): Session name\r\n- `**kwargs`: Additional context data\r\n\r\n**Yields:**\r\n- `loguru.Logger`: Contextualized logger\r\n\r\n## Development\r\n\r\n### Setting up development environment\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/yourusername/yaologit.git\r\ncd yaologit\r\n\r\n# Create virtual environment\r\npython -m venv venv\r\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\r\n\r\n# Install in development mode\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running tests\r\n\r\n```bash\r\n# Run all tests\r\npytest\r\n\r\n# Run with coverage\r\npytest --cov=yaologit\r\n\r\n# Run specific test file\r\npytest tests/test_core.py\r\n```\r\n\r\n### Code formatting\r\n\r\n```bash\r\n# Format code with black\r\nblack yaologit tests\r\n\r\n# Check code style\r\nflake8 yaologit tests\r\n\r\n# Type checking\r\nmypy yaologit\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\r\n\r\n1. Fork the repository\r\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Acknowledgments\r\n\r\n- Built on top of the excellent [loguru](https://github.com/Delgan/loguru) library\r\n- Inspired by the need for process-safe logging in multiprocessing applications\r\n\r\n## Changelog\r\n\r\n### 0.1.0 (2025-01-11)\r\n- Initial release\r\n- Process-safe singleton implementation\r\n- Thread-safe logging with loguru\r\n- Automatic log rotation and compression\r\n- Flexible configuration system\r\n- Support for multiple log levels\r\n- Environment variable configuration\r\n- Context manager support\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A process-safe logging package based on loguru",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/guoyaohua/YaoLogit#readme",
"Homepage": "https://github.com/guoyaohua/YaoLogit",
"Issues": "https://github.com/guoyaohua/YaoLogit/issues",
"Repository": "https://github.com/guoyaohua/YaoLogit"
},
"split_keywords": [
"logging",
" loguru",
" process-safe",
" multiprocessing",
" logger"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f1d79d9a36033ad9adbdf7cc7639d7f12d5ec3fea1b7d1d43165f487e8caf199",
"md5": "bf758b1a8a5f0747cbe9f96508356112",
"sha256": "3e7a9672ef44ddb7eed1135c3bb38d01437527ba2d52b508c9de076a2ada1740"
},
"downloads": -1,
"filename": "yaologit-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf758b1a8a5f0747cbe9f96508356112",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13313,
"upload_time": "2025-07-29T14:19:54",
"upload_time_iso_8601": "2025-07-29T14:19:54.031783Z",
"url": "https://files.pythonhosted.org/packages/f1/d7/9d9a36033ad9adbdf7cc7639d7f12d5ec3fea1b7d1d43165f487e8caf199/yaologit-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c91999eaf865ff91bc2a7980af27e3a27b88b5ea5ad2eabbecd166630e5b589c",
"md5": "1b4bacfc37e4eee6f9911bfffe151227",
"sha256": "1289e2c4c8d7509933dfcb79f4d096b25ff3f2cb5fc5cc63d2e9247a8b2e7bd0"
},
"downloads": -1,
"filename": "yaologit-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "1b4bacfc37e4eee6f9911bfffe151227",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17845,
"upload_time": "2025-07-29T14:19:55",
"upload_time_iso_8601": "2025-07-29T14:19:55.782819Z",
"url": "https://files.pythonhosted.org/packages/c9/19/99eaf865ff91bc2a7980af27e3a27b88b5ea5ad2eabbecd166630e5b589c/yaologit-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 14:19:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "guoyaohua",
"github_project": "YaoLogit#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "yaologit"
}
JSON
