async-safe-logger 0.1.3__tar.gz

async_safe_logger-0.1.3/PKG-INFO

@@ -0,0 +1,583 @@
+Metadata-Version: 2.3
+Name: async-safe-logger
+Version: 0.1.3
+Summary: A simple and secure logging library for async operations
+Author: ZHUZIOK
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Async Safe Logger
+
+[中文文档](README_zh-CN.md)
+
+A simple, thread-safe, and asyncio-friendly logging wrapper built on top of Python's standard `logging` module.
+
+`AsyncSafeLogger` moves log formatting, file I/O, log rotation, retention cleanup, and console output to a dedicated background thread using `QueueHandler` and `QueueListener`.
+
+Your application code continues to use Python's standard logging API:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+logger.info("Hello, world!")
+```
+
+No `await` is required for normal logging calls.
+
+---
+
+## Features
+
+* **Built on Python's standard `logging` module**
+* **Asyncio-friendly** — logging calls do not perform file or console I/O on the event-loop thread
+* **Thread-safe** — safe to use from multiple threads and coroutines
+* **Background logging** — formatting and output are handled by a dedicated `QueueListener` thread
+* **Automatic log rotation** — rotate log files when they reach the configured size
+* **Log retention cleanup** — automatically remove expired log files
+* **Console and file output** — independently configurable
+* **Multiple independent logger instances** — no required global mutable state
+* **Synchronous and asynchronous lifecycle APIs**
+* **Context manager support**
+* **Zero runtime dependencies** — only Python's standard library is required
+
+---
+
+## Requirements
+
+* Python **3.13+**
+
+The library currently has no third-party runtime dependencies.
+
+---
+
+## Installation
+
+### Using pip
+
+```bash
+pip install async-safe-logger
+```
+
+### Using uv
+
+If you use [uv](https://docs.astral.sh/uv/), add the package to your project with:
+
+```bash
+uv add async-safe-logger
+```
+
+Or install it directly into the current environment:
+
+```bash
+uv pip install async-safe-logger
+```
+
+---
+
+# Quick Start
+
+The simplest usage is to configure the logger and continue using Python's standard `logging` API.
+
+```python
+import logging
+
+from async_safe_logger import setup_logging, stop_logging
+
+setup_logging()
+
+logger = logging.getLogger(__name__)
+
+logger.info("Hello, world!")
+logger.warning("Something may be wrong.")
+logger.error("Something went wrong.")
+
+stop_logging()
+```
+
+By default, logs are:
+
+* written to `logs/app.log`
+* printed to stdout
+* rotated when the file reaches 2 MB
+* retained according to the configured retention policy
+
+---
+
+# Asyncio Usage
+
+`AsyncSafeLogger` is designed for applications using `asyncio`.
+
+Normal logging calls remain synchronous from the caller's perspective:
+
+```python
+import asyncio
+import logging
+
+from async_safe_logger import setup_logging, stop_logging_async
+
+
+async def main():
+    setup_logging()
+
+    logger = logging.getLogger(__name__)
+
+    logger.info("Running inside asyncio")
+    logger.warning("This logging call does not write directly to disk.")
+
+    try:
+        ...
+    finally:
+        await stop_logging_async()
+
+
+asyncio.run(main())
+```
+
+### Why `stop_logging_async()`?
+
+Stopping a `QueueListener` may wait for its background thread to finish processing queued log records.
+
+The synchronous:
+
+```python
+stop_logging()
+```
+
+may therefore block while the listener shuts down.
+
+When running inside an asyncio event loop, prefer:
+
+```python
+await stop_logging_async()
+```
+
+This moves the potentially blocking shutdown operation to a worker thread.
+
+---
+
+# How It Works
+
+The library uses Python's standard `QueueHandler` and `QueueListener`.
+
+The normal logging path looks approximately like this:
+
+```text
+Application
+    │
+    │ logger.info(...)
+    ▼
+logging.Logger
+    │
+    ▼
+QueueHandler
+    │
+    │ put LogRecord into memory queue
+    ▼
+queue.Queue
+    │
+    ▼
+QueueListener
+    │
+    │ background thread
+    ▼
+┌───────────────┬────────────────┐
+│ FileHandler   │ ConsoleHandler │
+└───────────────┴────────────────┘
+    │                    │
+    ▼                    ▼
+ app.log              stdout
+```
+
+The important point is that the application thread or asyncio event-loop thread does not directly perform:
+
+* file writes
+* console writes
+* log rotation
+* expired-log cleanup
+
+Those operations are handled by the background listener thread.
+
+This keeps the normal logging path lightweight and avoids performing blocking output operations directly from an asyncio event loop.
+
+---
+
+# Configuration
+
+The default logger can be configured through `setup_logging()`.
+
+For example:
+
+```python
+from async_safe_logger import setup_logging
+
+setup_logging(
+    log_dir="logs",
+    log_filename="app.log",
+    level=logging.INFO,
+    max_bytes=2 * 1024 * 1024,
+    backup_count=20,
+    retention_days=5,
+    file=True,
+    console=True,
+)
+```
+
+## Configuration Options
+
+| Parameter        |               Default | Description                                     |
+| ---------------- | --------------------: | ----------------------------------------------- |
+| `log_dir`        |              `"logs"` | Directory used for log files                    |
+| `log_filename`   |           `"app.log"` | Log file name                                   |
+| `level`          |        `logging.INFO` | Minimum logging level                           |
+| `max_bytes`      |                `2 MB` | Maximum size of a log file before rotation      |
+| `backup_count`   |                  `20` | Number of rotated log files to keep             |
+| `retention_days` |                   `5` | Delete log files older than this number of days |
+| `file`           |                `True` | Enable file logging                             |
+| `console`        |                `True` | Enable console logging                          |
+| `fmt`            |             See below | Log message format                              |
+| `datefmt`        | `"%Y-%m-%d %H:%M:%S"` | Timestamp format                                |
+
+Default format:
+
+```text
+%(asctime)s | %(levelname)-8s | %(name)s:%(funcName)s:%(lineno)d - %(message)s
+```
+
+For example:
+
+```text
+2026-09-06 20:30:15 | INFO     | myapp.main:main:42 - Server started
+```
+
+---
+
+# File and Console Output
+
+File and console logging can be independently enabled.
+
+### File only
+
+```python
+AsyncSafeLogger(
+    file=True,
+    console=False,
+)
+```
+
+### Console only
+
+```python
+AsyncSafeLogger(
+    file=False,
+    console=True,
+)
+```
+
+### File and console
+
+```python
+AsyncSafeLogger(
+    file=True,
+    console=True,
+)
+```
+
+This is also the default configuration.
+
+For safety, the following configuration is rejected:
+
+```python
+AsyncSafeLogger(
+    file=False,
+    console=False,
+)
+```
+
+It raises `ValueError` instead of silently discarding all log messages.
+
+---
+
+# Multiple Independent Logger Systems
+
+You can create multiple `AsyncSafeLogger` instances when different subsystems need different configurations.
+
+For example:
+
+```python
+import logging
+
+from async_safe_logger import AsyncSafeLogger
+
+
+business_logger = AsyncSafeLogger(
+    log_dir="logs/business",
+    log_filename="business.log",
+    level=logging.INFO,
+)
+
+debug_logger = AsyncSafeLogger(
+    log_dir="logs/debug",
+    log_filename="debug.log",
+    level=logging.DEBUG,
+)
+
+business_logger.setup()
+debug_logger.setup()
+
+logging.getLogger("business").info("Business event")
+logging.getLogger("debug").debug("Debug information")
+
+# ...
+
+business_logger.stop()
+debug_logger.stop()
+```
+
+Each instance owns its own queue, listener, and handlers.
+
+---
+
+# Context Manager
+
+`AsyncSafeLogger` supports both synchronous and asynchronous context managers.
+
+## Synchronous
+
+```python
+import logging
+
+from async_safe_logger import AsyncSafeLogger
+
+
+with AsyncSafeLogger() as logger:
+    logging.info("Inside the context manager")
+```
+
+The logger is automatically stopped when leaving the `with` block.
+
+## Asynchronous
+
+```python
+import logging
+
+from async_safe_logger import AsyncSafeLogger
+
+
+async with AsyncSafeLogger() as logger:
+    logging.info("Inside the async context manager")
+```
+
+When leaving the `async with` block, the logger is shut down asynchronously.
+
+This is the recommended pattern when the surrounding application is already asynchronous.
+
+---
+
+# Standard Logging Compatibility
+
+The main goal of this library is to keep application code compatible with Python's standard logging API.
+
+You can continue to use:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+logger.debug("Debug message")
+logger.info("Information")
+logger.warning("Warning")
+logger.error("Error")
+logger.critical("Critical error")
+```
+
+There is no need to replace your application's logging calls with a custom API such as:
+
+```python
+await logger.info(...)
+```
+
+Instead, logging remains familiar:
+
+```python
+logger.info(...)
+```
+
+while the output pipeline is handled asynchronously in the background.
+
+---
+
+# Log Rotation and Retention
+
+The file handler combines size-based rotation with automatic retention cleanup.
+
+For example:
+
+```python
+AsyncSafeLogger(
+    log_dir="logs",
+    log_filename="app.log",
+    max_bytes=2 * 1024 * 1024,
+    backup_count=20,
+    retention_days=5,
+)
+```
+
+When `app.log` reaches the configured size, it is rotated according to `RotatingFileHandler`.
+
+After rotation, log files older than the configured retention period are removed.
+
+---
+
+# Graceful Shutdown
+
+It is important to stop the logger before the application exits so that queued log records have an opportunity to be processed.
+
+For synchronous applications:
+
+```python
+stop_logging()
+```
+
+For asyncio applications:
+
+```python
+await stop_logging_async()
+```
+
+A typical asyncio application should use:
+
+```python
+async def main():
+    setup_logging()
+
+    try:
+        ...
+    finally:
+        await stop_logging_async()
+```
+
+This is especially important for applications that produce logs immediately before shutdown.
+
+---
+
+# Design Goals
+
+The project intentionally focuses on a small set of goals:
+
+### 1. Keep the standard logging API
+
+No custom logging syntax is required.
+
+```python
+logger.info("hello")
+```
+
+remains the primary interface.
+
+### 2. Keep blocking output away from the event loop
+
+The application produces a `LogRecord`, which is placed into an in-memory queue.
+
+The listener thread performs the actual output work.
+
+### 3. Minimize runtime dependencies
+
+The current implementation uses only Python's standard library.
+
+### 4. Support both synchronous and asynchronous applications
+
+The same logger can be used by:
+
+* normal synchronous applications
+* asyncio applications
+* applications using both threads and asyncio
+
+### 5. Keep the implementation simple
+
+The library intentionally builds on well-tested components already provided by Python:
+
+* `logging`
+* `QueueHandler`
+* `QueueListener`
+* `RotatingFileHandler`
+* `queue.Queue`
+* `threading`
+
+Rather than implementing a completely new logging framework.
+
+---
+
+# Important Notes
+
+## Logging is not completely "non-blocking"
+
+`AsyncSafeLogger` moves output operations away from the calling thread, but the initial logging operation still performs normal Python logging work and enqueues a `LogRecord`.
+
+Therefore, it should be understood as:
+
+> **asyncio-friendly / async-safe logging output**
+
+rather than a mathematically guaranteed zero-cost or lock-free logging implementation.
+
+## Queue Backpressure
+
+The internal queue is currently unbounded.
+
+This means normal logging calls do not wait for the background listener to consume records.
+
+However, an application that continuously produces logs significantly faster than the output destination can consume them may accumulate an increasing number of `LogRecord` objects in memory.
+
+For high-volume logging workloads, monitor queue growth and application memory usage.
+
+## Shutdown
+
+Always stop the logger during application shutdown:
+
+```python
+await stop_logging_async()
+```
+
+for asyncio applications, or:
+
+```python
+stop_logging()
+```
+
+for synchronous applications.
+
+---
+
+# Project Status
+
+This project is currently in an early development stage.
+
+API design and implementation details may change before the `1.0.0` release.
+
+The current version is:
+
+```text
+0.1.0
+```
+
+---
+
+# License
+
+MIT License.
+
+See [`LICENSE`](LICENSE) for details.

async_safe_logger-0.1.3/README.md

@@ -0,0 +1,563 @@
+# Async Safe Logger
+
+[中文文档](README_zh-CN.md)
+
+A simple, thread-safe, and asyncio-friendly logging wrapper built on top of Python's standard `logging` module.
+
+`AsyncSafeLogger` moves log formatting, file I/O, log rotation, retention cleanup, and console output to a dedicated background thread using `QueueHandler` and `QueueListener`.
+
+Your application code continues to use Python's standard logging API:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+logger.info("Hello, world!")
+```
+
+No `await` is required for normal logging calls.
+
+---
+
+## Features
+
+* **Built on Python's standard `logging` module**
+* **Asyncio-friendly** — logging calls do not perform file or console I/O on the event-loop thread
+* **Thread-safe** — safe to use from multiple threads and coroutines
+* **Background logging** — formatting and output are handled by a dedicated `QueueListener` thread
+* **Automatic log rotation** — rotate log files when they reach the configured size
+* **Log retention cleanup** — automatically remove expired log files
+* **Console and file output** — independently configurable
+* **Multiple independent logger instances** — no required global mutable state
+* **Synchronous and asynchronous lifecycle APIs**
+* **Context manager support**
+* **Zero runtime dependencies** — only Python's standard library is required
+
+---
+
+## Requirements
+
+* Python **3.13+**
+
+The library currently has no third-party runtime dependencies.
+
+---
+
+## Installation
+
+### Using pip
+
+```bash
+pip install async-safe-logger
+```
+
+### Using uv
+
+If you use [uv](https://docs.astral.sh/uv/), add the package to your project with:
+
+```bash
+uv add async-safe-logger
+```
+
+Or install it directly into the current environment:
+
+```bash
+uv pip install async-safe-logger
+```
+
+---
+
+# Quick Start
+
+The simplest usage is to configure the logger and continue using Python's standard `logging` API.
+
+```python
+import logging
+
+from async_safe_logger import setup_logging, stop_logging
+
+setup_logging()
+
+logger = logging.getLogger(__name__)
+
+logger.info("Hello, world!")
+logger.warning("Something may be wrong.")
+logger.error("Something went wrong.")
+
+stop_logging()
+```
+
+By default, logs are:
+
+* written to `logs/app.log`
+* printed to stdout
+* rotated when the file reaches 2 MB
+* retained according to the configured retention policy
+
+---
+
+# Asyncio Usage
+
+`AsyncSafeLogger` is designed for applications using `asyncio`.
+
+Normal logging calls remain synchronous from the caller's perspective:
+
+```python
+import asyncio
+import logging
+
+from async_safe_logger import setup_logging, stop_logging_async
+
+
+async def main():
+    setup_logging()
+
+    logger = logging.getLogger(__name__)
+
+    logger.info("Running inside asyncio")
+    logger.warning("This logging call does not write directly to disk.")
+
+    try:
+        ...
+    finally:
+        await stop_logging_async()
+
+
+asyncio.run(main())
+```
+
+### Why `stop_logging_async()`?
+
+Stopping a `QueueListener` may wait for its background thread to finish processing queued log records.
+
+The synchronous:
+
+```python
+stop_logging()
+```
+
+may therefore block while the listener shuts down.
+
+When running inside an asyncio event loop, prefer:
+
+```python
+await stop_logging_async()
+```
+
+This moves the potentially blocking shutdown operation to a worker thread.
+
+---
+
+# How It Works
+
+The library uses Python's standard `QueueHandler` and `QueueListener`.
+
+The normal logging path looks approximately like this:
+
+```text
+Application
+    │
+    │ logger.info(...)
+    ▼
+logging.Logger
+    │
+    ▼
+QueueHandler
+    │
+    │ put LogRecord into memory queue
+    ▼
+queue.Queue
+    │
+    ▼
+QueueListener
+    │
+    │ background thread
+    ▼
+┌───────────────┬────────────────┐
+│ FileHandler   │ ConsoleHandler │
+└───────────────┴────────────────┘
+    │                    │
+    ▼                    ▼
+ app.log              stdout
+```
+
+The important point is that the application thread or asyncio event-loop thread does not directly perform:
+
+* file writes
+* console writes
+* log rotation
+* expired-log cleanup
+
+Those operations are handled by the background listener thread.
+
+This keeps the normal logging path lightweight and avoids performing blocking output operations directly from an asyncio event loop.
+
+---
+
+# Configuration
+
+The default logger can be configured through `setup_logging()`.
+
+For example:
+
+```python
+from async_safe_logger import setup_logging
+
+setup_logging(
+    log_dir="logs",
+    log_filename="app.log",
+    level=logging.INFO,
+    max_bytes=2 * 1024 * 1024,
+    backup_count=20,
+    retention_days=5,
+    file=True,
+    console=True,
+)
+```
+
+## Configuration Options
+
+| Parameter        |               Default | Description                                     |
+| ---------------- | --------------------: | ----------------------------------------------- |
+| `log_dir`        |              `"logs"` | Directory used for log files                    |
+| `log_filename`   |           `"app.log"` | Log file name                                   |
+| `level`          |        `logging.INFO` | Minimum logging level                           |
+| `max_bytes`      |                `2 MB` | Maximum size of a log file before rotation      |
+| `backup_count`   |                  `20` | Number of rotated log files to keep             |
+| `retention_days` |                   `5` | Delete log files older than this number of days |
+| `file`           |                `True` | Enable file logging                             |
+| `console`        |                `True` | Enable console logging                          |
+| `fmt`            |             See below | Log message format                              |
+| `datefmt`        | `"%Y-%m-%d %H:%M:%S"` | Timestamp format                                |
+
+Default format:
+
+```text
+%(asctime)s | %(levelname)-8s | %(name)s:%(funcName)s:%(lineno)d - %(message)s
+```
+
+For example:
+
+```text
+2026-09-06 20:30:15 | INFO     | myapp.main:main:42 - Server started
+```
+
+---
+
+# File and Console Output
+
+File and console logging can be independently enabled.
+
+### File only
+
+```python
+AsyncSafeLogger(
+    file=True,
+    console=False,
+)
+```
+
+### Console only
+
+```python
+AsyncSafeLogger(
+    file=False,
+    console=True,
+)
+```
+
+### File and console
+
+```python
+AsyncSafeLogger(
+    file=True,
+    console=True,
+)
+```
+
+This is also the default configuration.
+
+For safety, the following configuration is rejected:
+
+```python
+AsyncSafeLogger(
+    file=False,
+    console=False,
+)
+```
+
+It raises `ValueError` instead of silently discarding all log messages.
+
+---
+
+# Multiple Independent Logger Systems
+
+You can create multiple `AsyncSafeLogger` instances when different subsystems need different configurations.
+
+For example:
+
+```python
+import logging
+
+from async_safe_logger import AsyncSafeLogger
+
+
+business_logger = AsyncSafeLogger(
+    log_dir="logs/business",
+    log_filename="business.log",
+    level=logging.INFO,
+)
+
+debug_logger = AsyncSafeLogger(
+    log_dir="logs/debug",
+    log_filename="debug.log",
+    level=logging.DEBUG,
+)
+
+business_logger.setup()
+debug_logger.setup()
+
+logging.getLogger("business").info("Business event")
+logging.getLogger("debug").debug("Debug information")
+
+# ...
+
+business_logger.stop()
+debug_logger.stop()
+```
+
+Each instance owns its own queue, listener, and handlers.
+
+---
+
+# Context Manager
+
+`AsyncSafeLogger` supports both synchronous and asynchronous context managers.
+
+## Synchronous
+
+```python
+import logging
+
+from async_safe_logger import AsyncSafeLogger
+
+
+with AsyncSafeLogger() as logger:
+    logging.info("Inside the context manager")
+```
+
+The logger is automatically stopped when leaving the `with` block.
+
+## Asynchronous
+
+```python
+import logging
+
+from async_safe_logger import AsyncSafeLogger
+
+
+async with AsyncSafeLogger() as logger:
+    logging.info("Inside the async context manager")
+```
+
+When leaving the `async with` block, the logger is shut down asynchronously.
+
+This is the recommended pattern when the surrounding application is already asynchronous.
+
+---
+
+# Standard Logging Compatibility
+
+The main goal of this library is to keep application code compatible with Python's standard logging API.
+
+You can continue to use:
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+logger.debug("Debug message")
+logger.info("Information")
+logger.warning("Warning")
+logger.error("Error")
+logger.critical("Critical error")
+```
+
+There is no need to replace your application's logging calls with a custom API such as:
+
+```python
+await logger.info(...)
+```
+
+Instead, logging remains familiar:
+
+```python
+logger.info(...)
+```
+
+while the output pipeline is handled asynchronously in the background.
+
+---
+
+# Log Rotation and Retention
+
+The file handler combines size-based rotation with automatic retention cleanup.
+
+For example:
+
+```python
+AsyncSafeLogger(
+    log_dir="logs",
+    log_filename="app.log",
+    max_bytes=2 * 1024 * 1024,
+    backup_count=20,
+    retention_days=5,
+)
+```
+
+When `app.log` reaches the configured size, it is rotated according to `RotatingFileHandler`.
+
+After rotation, log files older than the configured retention period are removed.
+
+---
+
+# Graceful Shutdown
+
+It is important to stop the logger before the application exits so that queued log records have an opportunity to be processed.
+
+For synchronous applications:
+
+```python
+stop_logging()
+```
+
+For asyncio applications:
+
+```python
+await stop_logging_async()
+```
+
+A typical asyncio application should use:
+
+```python
+async def main():
+    setup_logging()
+
+    try:
+        ...
+    finally:
+        await stop_logging_async()
+```
+
+This is especially important for applications that produce logs immediately before shutdown.
+
+---
+
+# Design Goals
+
+The project intentionally focuses on a small set of goals:
+
+### 1. Keep the standard logging API
+
+No custom logging syntax is required.
+
+```python
+logger.info("hello")
+```
+
+remains the primary interface.
+
+### 2. Keep blocking output away from the event loop
+
+The application produces a `LogRecord`, which is placed into an in-memory queue.
+
+The listener thread performs the actual output work.
+
+### 3. Minimize runtime dependencies
+
+The current implementation uses only Python's standard library.
+
+### 4. Support both synchronous and asynchronous applications
+
+The same logger can be used by:
+
+* normal synchronous applications
+* asyncio applications
+* applications using both threads and asyncio
+
+### 5. Keep the implementation simple
+
+The library intentionally builds on well-tested components already provided by Python:
+
+* `logging`
+* `QueueHandler`
+* `QueueListener`
+* `RotatingFileHandler`
+* `queue.Queue`
+* `threading`
+
+Rather than implementing a completely new logging framework.
+
+---
+
+# Important Notes
+
+## Logging is not completely "non-blocking"
+
+`AsyncSafeLogger` moves output operations away from the calling thread, but the initial logging operation still performs normal Python logging work and enqueues a `LogRecord`.
+
+Therefore, it should be understood as:
+
+> **asyncio-friendly / async-safe logging output**
+
+rather than a mathematically guaranteed zero-cost or lock-free logging implementation.
+
+## Queue Backpressure
+
+The internal queue is currently unbounded.
+
+This means normal logging calls do not wait for the background listener to consume records.
+
+However, an application that continuously produces logs significantly faster than the output destination can consume them may accumulate an increasing number of `LogRecord` objects in memory.
+
+For high-volume logging workloads, monitor queue growth and application memory usage.
+
+## Shutdown
+
+Always stop the logger during application shutdown:
+
+```python
+await stop_logging_async()
+```
+
+for asyncio applications, or:
+
+```python
+stop_logging()
+```
+
+for synchronous applications.
+
+---
+
+# Project Status
+
+This project is currently in an early development stage.
+
+API design and implementation details may change before the `1.0.0` release.
+
+The current version is:
+
+```text
+0.1.0
+```
+
+---
+
+# License
+
+MIT License.
+
+See [`LICENSE`](LICENSE) for details.

async_safe_logger-0.1.3/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "async-safe-logger"
+version = "0.1.3"
+description = "A simple and secure logging library for async operations"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Logging",
+]
+
+[[project.authors]]
+name = "ZHUZIOK"
+
+[build-system]
+requires = ["uv_build>=0.11.0"]
+build-backend = "uv_build"

async_safe_logger-0.1.3/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "async-safe-logger"
+version = "0.1.3"
+description = "A simple and secure logging library for async operations"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+
+authors = [
+    { name = "ZHUZIOK" }
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Logging",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.0"]
+build-backend = "uv_build"

async_safe_logger-0.1.3/src/async_safe_logger/__init__.py

@@ -0,0 +1,5 @@
+from .logger import AsyncSafeLogger
+
+__all__ = [
+    "AsyncSafeLogger",
+]

async_safe_logger-0.1.3/src/async_safe_logger/logger.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import queue
+import sys
+import threading
+from datetime import datetime, timedelta
+from logging.handlers import QueueHandler, QueueListener, RotatingFileHandler
+from pathlib import Path
+from typing import Optional, Union
+
+
+class _DailyCleanupRotatingFileHandler(RotatingFileHandler):
+    __slots__ = (
+        "retention_days",
+        "_log_dir",
+        "_log_stem",
+    )
+
+    def __init__(self, *args, retention_days: int = 5, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.retention_days = retention_days
+        base_path = Path(self.baseFilename)
+        self._log_dir = base_path.parent
+        self._log_stem = base_path.name
+
+    def doRollover(self) -> None:
+        super().doRollover()
+        self._cleanup_old_logs()
+
+    def _cleanup_old_logs(self) -> None:
+        expire_time = datetime.now() - timedelta(days=self.retention_days)
+        for path in self._log_dir.glob(f"{self._log_stem}*"):
+            try:
+                mtime = datetime.fromtimestamp(path.stat().st_mtime)
+                if mtime < expire_time:
+                    path.unlink()
+            except OSError:
+                pass
+
+
+class AsyncSafeLogger:
+
+    __slots__ = (
+        "log_dir",
+        "log_file",
+        "level",
+        "max_bytes",
+        "backup_count",
+        "retention_days",
+        "file",
+        "console",
+        "fmt",
+        "datefmt",
+        "_queue",
+        "_listener",
+        "_queue_handler",
+        "_lock",
+    )
+
+    def __init__(
+        self,
+        log_dir: Union[str, Path] = "logs",
+        log_filename: str = "app.log",
+        level: int = logging.INFO,
+        max_bytes: int = 2 * 1024 * 1024,  # 2 MB
+        backup_count: int = 20,
+        retention_days: int = 5,
+        file: bool = True,
+        console: bool = True,
+        fmt: str = "%(asctime)s | %(levelname)-8s | %(name)s:%(funcName)s:%(lineno)d - %(message)s",
+        datefmt: str = "%Y-%m-%d %H:%M:%S",
+    ) -> None:
+        if not file and not console:
+            raise ValueError("The values of 'file' and 'console' cannot both be False; otherwise, the logs will be silently discarded.")
+
+        self.log_dir = Path(log_dir)
+        self.log_file = self.log_dir / log_filename
+        self.level = level
+        self.max_bytes = max_bytes
+        self.backup_count = backup_count
+        self.retention_days = retention_days
+        self.file = file
+        self.console = console
+        self.fmt = fmt
+        self.datefmt = datefmt
+
+        self._queue: "queue.Queue[logging.LogRecord]" = queue.Queue()
+
+        self._listener: Optional[QueueListener] = None
+        self._queue_handler: Optional[QueueHandler] = None
+        self._lock = threading.Lock()
+
+    def setup(self) -> None:
+        with self._lock:
+            if self._listener is not None:
+                return
+
+            formatter = logging.Formatter(fmt=self.fmt, datefmt=self.datefmt)
+
+            handlers: list[logging.Handler] = []
+
+            if self.file:
+                self.log_dir.mkdir(parents=True, exist_ok=True)
+
+                file_handler = _DailyCleanupRotatingFileHandler(
+                    filename=str(self.log_file),
+                    maxBytes=self.max_bytes,
+                    backupCount=self.backup_count,
+                    encoding="utf-8",
+                    retention_days=self.retention_days,
+                )
+                file_handler.setLevel(self.level)
+                file_handler.setFormatter(formatter)
+                handlers.append(file_handler)
+
+            if self.console:
+                console_handler: logging.StreamHandler = logging.StreamHandler(sys.stdout)
+                console_handler.setLevel(self.level)
+                console_handler.setFormatter(formatter)
+                handlers.append(console_handler)
+
+            # QueueHandler:业务线程/协程只把 LogRecord 丢进内存队列
+            self._queue_handler = QueueHandler(self._queue)
+
+            root_logger = logging.getLogger()
+            root_logger.setLevel(self.level)
+            root_logger.addHandler(self._queue_handler)
+
+            # QueueListener:独立后台线程,真正做格式化 + 落盘 + 打印
+            self._listener = QueueListener(
+                self._queue,
+                *handlers,
+                respect_handler_level=True,
+            )
+            self._listener.start()
+
+    async def setup_async(self) -> None:
+        await asyncio.to_thread(self.setup)
+
+    def stop(self) -> None:
+        with self._lock:
+            if self._listener is None:
+                return
+
+            root_logger = logging.getLogger()
+            if self._queue_handler is not None:
+                root_logger.removeHandler(self._queue_handler)
+
+            self._listener.stop()
+            self._listener = None
+            self._queue_handler = None
+
+    async def stop_async(self) -> None:
+        await asyncio.to_thread(self.stop)
+
+    def __enter__(self) -> "AsyncSafeLogger":
+        self.setup()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.stop()
+
+    async def __aenter__(self) -> "AsyncSafeLogger":
+        await self.setup_async()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.stop_async()