gpclog 0.2.0__py3-none-any.whl

gpclog/__init__.py

@@ -0,0 +1,91 @@
+"""gpclog - General Purpose Category Logger.
+
+用于在复杂Python项目里管理分类日志。
+"""
+
+from typing import Optional
+
+from gpconfig import GPConfigFolder, GPConfigManager
+
+from gpclog.config import GPCLoggerConfig
+from gpclog.logger import GPCLogger
+from gpclog.manager import GPCLoggerManager
+
+__version__ = "0.2.0"
+
+# Auto-register config and configurable classes with GPConfigManager
+GPConfigManager.register_config_class(GPCLoggerConfig)
+GPConfigManager.register_configurable_class(GPCLogger)
+
+__all__ = [
+    "get_logger",
+    "set_config_folder",
+    "reset",
+    "GPCLogger",
+    "GPCLoggerConfig",
+]
+
+# Singleton manager instance
+_manager: GPCLoggerManager = GPCLoggerManager()
+
+
+def get_logger(logger_name: str, sn: Optional[int] = None) -> GPCLogger:
+    """Get or create a logger by name.
+
+    This is the primary interface for obtaining loggers. Each unique
+    logger_name creates a separate logger with its own configuration
+    and output file.
+
+    Args:
+        logger_name: Unique name for the logger. This name is used
+            for configuration lookup and (without sn) for the log file name.
+        sn: Optional serial number for multiprocess isolation. When provided,
+            the logger is named "{logger_name}-{sn}" and writes to
+            "{logger_name}-{sn}.log", but still uses the configuration
+            associated with logger_name.
+
+    Returns:
+        GPCLogger instance for the given name.
+
+    Example:
+        >>> db_logger = gpclog.get_logger("database")
+        >>> db_logger.info("Connected to database")
+        >>>
+        >>> # In multiprocess scenario:
+        >>> worker_logger = gpclog.get_logger("worker", sn=process_id)
+        >>> worker_logger.info("Process started")
+    """
+    return _manager.get_logger(logger_name, sn)
+
+
+def set_config_folder(cfg_folder: GPConfigFolder) -> None:
+    """Set the configuration folder for logger configurations.
+
+    After calling this function, logger configurations will be loaded
+    from the specified folder. If a logger's configuration is not found,
+    the default configuration is used.
+
+    Args:
+        cfg_folder: GPConfigFolder instance containing logger
+            configuration files.
+
+    Example:
+        >>> from gpconfig import GPConfigManager, GPConfigFolder
+        >>> manager = GPConfigManager("myapp")
+        >>> folder = GPConfigFolder(manager, "logs")
+        >>> gpclog.set_config_folder(folder)
+    """
+    _manager.set_config_folder(cfg_folder)
+
+
+def reset() -> None:
+    """Reset the logger manager and clear all caches.
+
+    This function is primarily intended for testing purposes to ensure
+    a clean state between tests. It resets the internal state and clears
+    all cached loggers.
+    """
+    global _manager
+    GPCLoggerManager._instance = None
+    GPCLogger.clear_cache()
+    _manager = GPCLoggerManager()

gpclog/config.py

@@ -0,0 +1,55 @@
+# src/gpclog/config.py
+"""GPCLoggerConfig - Configuration class for GPCLogger."""
+
+from typing import ClassVar
+
+from gpconfig import GPConfig
+
+
+class GPCLoggerConfig(GPConfig):
+    """Configuration for GPCLogger.
+
+    Attributes:
+        cfg_class_name: Class identifier for gpconfig auto-detection.
+        configured_class_name: Name of the configurable class (always "GPCLogger").
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        file_format: Format string for file output.
+        console_format: Format string for console output.
+        output_to_stdout: Whether to output to stdout.
+        output_to_stderr: Whether to output to stderr.
+        output_to_file: Whether to output to file.
+        log_path: Log output path (auto, env, home, or absolute path).
+        rotation_enabled: Whether to enable log rotation.
+        rotation_size: Rotation size threshold (e.g., "10 MB").
+        retention_enabled: Whether to enable log retention/deletion.
+        retention_days: Number of days to retain logs.
+    """
+
+    cfg_class_name: ClassVar[str] = "GPCLoggerConfig"
+
+    # Required fields
+    configured_class_name: str = "GPCLogger"
+    level: str = "INFO"
+
+    # Optional fields with defaults
+    file_format: str = (
+        "{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {extra[name]} | {message}"
+    )
+    console_format: str = (
+        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+        "<level>{level: <8}</level> | "
+        "<cyan>{extra[name]}</cyan> | "
+        "<level>{message}</level>"
+    )
+
+    output_to_stdout: bool = True
+    output_to_stderr: bool = False
+    output_to_file: bool = True
+
+    log_path: str = "auto"
+
+    rotation_enabled: bool = False
+    rotation_size: str = "10 MB"
+
+    retention_enabled: bool = False
+    retention_days: int = 7

gpclog/logger.py

@@ -0,0 +1,149 @@
+# src/gpclog/logger.py
+"""GPCLogger - Configurable logger class."""
+
+import sys
+from typing import Any, ClassVar
+
+from gpconfig import GPConfigurable
+from loguru import logger as loguru_logger
+
+from gpclog.config import GPCLoggerConfig
+from gpclog.utils import resolve_log_path
+
+
+class GPCLogger(GPConfigurable):
+    """A configurable logger that wraps loguru.
+
+    This class provides a category-based logger with configuration support
+    through GPCLoggerConfig. Each logger instance writes to its own file
+    and can be configured independently.
+    """
+
+    # Class-level cache for bound loguru loggers to prevent duplicate handlers
+    _bound_loggers: ClassVar[dict[str, Any]] = {}
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        """Clear the bound loggers cache.
+
+        This should be called when the singleton manager is reset to ensure
+        that cached loggers with stale handlers are not reused.
+        """
+        cls._bound_loggers.clear()
+
+    def __init__(self, config: GPCLoggerConfig) -> None:
+        """Initialize the logger with configuration.
+
+        Args:
+            config: GPCLoggerConfig instance containing logger settings.
+        """
+        super().__init__(config)
+        self._name: str = config.name or "default"
+        self._logger = self._create_logger(config)
+
+    @property
+    def name(self) -> str:
+        """Get the logger name."""
+        return self._name
+
+    def _create_logger(self, config: GPCLoggerConfig) -> Any:
+        """Create and configure a loguru logger.
+
+        Uses loguru's filter mechanism to allow multiple GPCLogger instances
+        to coexist and write to different files. Each logger binds its name
+        to the record's extra dict, and handlers use filters to route
+        messages to the appropriate sinks.
+
+        If a logger with the same name has already been bound, returns the
+        cached instance to avoid adding duplicate handlers.
+
+        Args:
+            config: Configuration for the logger.
+
+        Returns:
+            Configured loguru logger instance with bound name.
+        """
+        # Check if a logger with this name already exists in cache
+        if self._name in self._bound_loggers:
+            return self._bound_loggers[self._name]
+
+        # Create a logger filter function that captures the name by value
+        # to avoid closure issues with late binding
+        logger_name = self._name
+
+        def name_filter(record: dict) -> bool:
+            """Filter records by logger name."""
+            return record["extra"].get("name") == logger_name
+
+        # Create a new logger with bound context
+        new_logger = loguru_logger.bind(name=self._name)
+
+        # Add console handler if enabled
+        if config.output_to_stdout:
+            loguru_logger.add(
+                sink=sys.stdout,
+                format=config.console_format,
+                level=config.level,
+                colorize=True,
+                filter=name_filter,
+            )
+
+        # Add stderr handler if enabled
+        if config.output_to_stderr:
+            loguru_logger.add(
+                sink=sys.stderr,
+                format=config.console_format,
+                level=config.level,
+                colorize=True,
+                filter=name_filter,
+            )
+
+        # Add file handler if enabled
+        if config.output_to_file:
+            log_dir = resolve_log_path(config.log_path)
+            log_file = log_dir / f"{self._name}.log"
+
+            # Configure rotation
+            rotation = None
+            if config.rotation_enabled:
+                rotation = config.rotation_size
+
+            # Configure retention
+            retention = None
+            if config.retention_enabled:
+                retention = f"{config.retention_days} days"
+
+            loguru_logger.add(
+                sink=str(log_file),
+                format=config.file_format,
+                level=config.level,
+                rotation=rotation,
+                retention=retention,
+                encoding="utf-8",
+                filter=name_filter,
+            )
+
+        # Cache the bound logger to prevent duplicate handlers
+        self._bound_loggers[self._name] = new_logger
+
+        return new_logger
+
+    def debug(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log a debug message."""
+        self._logger.debug(message, *args, **kwargs)
+
+    def info(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log an info message."""
+        self._logger.info(message, *args, **kwargs)
+
+    def warning(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log a warning message."""
+        self._logger.warning(message, *args, **kwargs)
+
+    def error(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log an error message."""
+        self._logger.error(message, *args, **kwargs)
+
+    def critical(self, message: str, *args: Any, **kwargs: Any) -> None:
+        """Log a critical message."""
+        self._logger.critical(message, *args, **kwargs)

gpclog/manager.py

@@ -0,0 +1,201 @@
+# src/gpclog/manager.py
+"""GPCLoggerManager - Singleton logger manager."""
+
+from typing import ClassVar, Optional
+from loguru import logger as loguru_logger
+
+from gpconfig import GPConfigFolder
+
+from gpclog.config import GPCLoggerConfig
+from gpclog.logger import GPCLogger
+
+
+class GPCLoggerManager:
+    """Singleton manager for GPCLogger instances.
+
+    This class manages all logger instances and provides a central
+    point for configuration management.
+    """
+
+    _instance: ClassVar[Optional["GPCLoggerManager"]] = None
+
+    def __new__(cls) -> "GPCLoggerManager":
+        """Create or return the singleton instance."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialize()
+            loguru_logger.remove()
+            # Clear the bound loggers cache since handlers were removed
+            GPCLogger.clear_cache()
+        return cls._instance
+
+    def _initialize(self) -> None:
+        """Initialize the manager instance."""
+        self._loggers: dict[tuple[str, Optional[int]], GPCLogger] = {}
+        self._config_folder: Optional[GPConfigFolder] = None
+        self._default_config: GPCLoggerConfig = self._create_default_config()
+
+    def _create_default_config(self) -> GPCLoggerConfig:
+        """Create the default configuration.
+
+        Returns:
+            GPCLoggerConfig with default values.
+        """
+        return GPCLoggerConfig(
+            name="default",
+            level="INFO",
+        )
+
+    @property
+    def default_config(self) -> GPCLoggerConfig:
+        """Get the default configuration."""
+        return self._default_config
+
+    @property
+    def config_folder(self) -> Optional[GPConfigFolder]:
+        """Get the config folder."""
+        return self._config_folder
+
+    def set_config_folder(self, cfg_folder: GPConfigFolder) -> None:
+        """Set the configuration folder for logger configs.
+
+        Args:
+            cfg_folder: GPConfigFolder instance containing logger configurations.
+        """
+        self._config_folder = cfg_folder
+
+    def get_logger(self, logger_name: str, sn: Optional[int] = None) -> GPCLogger:
+        """Get or create a logger by name.
+
+        If a logger with the given name and sn already exists, returns the cached
+        instance. Otherwise, creates a new logger with the appropriate
+        configuration.
+
+        Args:
+            logger_name: Unique name for the logger.
+            sn: Optional serial number. When provided, creates a logger named
+                "{logger_name}-{sn}" that uses the same configuration as
+                logger_name. Useful for multiprocess isolation.
+
+        Returns:
+            GPCLogger instance for the given name.
+        """
+        cache_key = (logger_name, sn)
+
+        # Check cache first
+        if cache_key in self._loggers:
+            return self._loggers[cache_key]
+
+        # Get or create configuration using original logger_name
+        config = self._get_config(logger_name)
+
+        # Override name to include sn if provided
+        if sn is not None:
+            config = GPCLoggerConfig(
+                name=f"{logger_name}-{sn}",
+                level=config.level,
+                file_format=config.file_format,
+                console_format=config.console_format,
+                output_to_stdout=config.output_to_stdout,
+                output_to_stderr=config.output_to_stderr,
+                output_to_file=config.output_to_file,
+                log_path=config.log_path,
+                rotation_enabled=config.rotation_enabled,
+                rotation_size=config.rotation_size,
+                retention_enabled=config.retention_enabled,
+                retention_days=config.retention_days,
+            )
+
+        # Create logger
+        logger = GPCLogger(config)
+
+        # Cache and return
+        self._loggers[cache_key] = logger
+        return logger
+
+    def _get_config(self, logger_name: str) -> GPCLoggerConfig:
+        """Get configuration for a logger.
+
+        Tries to load configuration from config folder if set.
+        Falls back to default configuration if not found.
+
+        Args:
+            logger_name: Name of the logger.
+
+        Returns:
+            GPCLoggerConfig for the logger.
+        """
+        # Try to get config from config folder
+        if self._config_folder is not None:
+            try:
+                config = self._config_folder.get_config(logger_name, GPCLoggerConfig)
+                # Merge with defaults for missing fields
+                return self._merge_with_defaults(config)
+            except Exception:
+                # Config not found, try default.yaml
+                try:
+                    default_config = self._config_folder.get_config(
+                        "default", GPCLoggerConfig
+                    )
+                    self._default_config = self._merge_with_defaults(default_config)
+                except Exception:
+                    pass
+
+        # Use default config with the logger name
+        return GPCLoggerConfig(
+            name=logger_name,
+            level=self._default_config.level,
+            file_format=self._default_config.file_format,
+            console_format=self._default_config.console_format,
+            output_to_stdout=self._default_config.output_to_stdout,
+            output_to_stderr=self._default_config.output_to_stderr,
+            output_to_file=self._default_config.output_to_file,
+            log_path=self._default_config.log_path,
+            rotation_enabled=self._default_config.rotation_enabled,
+            rotation_size=self._default_config.rotation_size,
+            retention_enabled=self._default_config.retention_enabled,
+            retention_days=self._default_config.retention_days,
+        )
+
+    def _merge_with_defaults(self, config: GPCLoggerConfig) -> GPCLoggerConfig:
+        """Merge user config with defaults for missing fields.
+
+        Args:
+            config: User-provided configuration.
+
+        Returns:
+            GPCLoggerConfig with all fields filled.
+        """
+        defaults = self._default_config
+        return GPCLoggerConfig(
+            name=config.name,
+            level=config.level if config.level else defaults.level,
+            file_format=config.file_format
+            if config.file_format
+            else defaults.file_format,
+            console_format=config.console_format
+            if config.console_format
+            else defaults.console_format,
+            output_to_stdout=config.output_to_stdout
+            if config.output_to_stdout is not None
+            else defaults.output_to_stdout,
+            output_to_stderr=config.output_to_stderr
+            if config.output_to_stderr is not None
+            else defaults.output_to_stderr,
+            output_to_file=config.output_to_file
+            if config.output_to_file is not None
+            else defaults.output_to_file,
+            log_path=config.log_path if config.log_path else defaults.log_path,
+            rotation_enabled=config.rotation_enabled
+            if config.rotation_enabled is not None
+            else defaults.rotation_enabled,
+            rotation_size=config.rotation_size
+            if config.rotation_size
+            else defaults.rotation_size,
+            retention_enabled=config.retention_enabled
+            if config.retention_enabled is not None
+            else defaults.retention_enabled,
+            retention_days=config.retention_days
+            if config.retention_days is not None
+            else defaults.retention_days,
+        )

gpclog/utils.py

@@ -0,0 +1,60 @@
+"""Utility functions for gpclog."""
+
+import os
+from pathlib import Path
+
+
+def resolve_log_path(log_path: str) -> Path:
+    """Resolve the log output path.
+
+    Args:
+        log_path: Path specification. Can be:
+            - "auto": Auto-detect (GPCLOG_PATH env or home directory)
+            - "env": Use GPCLOG_PATH environment variable
+            - "home": Use user home directory
+            - Absolute path: Use specified path
+
+    Returns:
+        Resolved Path object pointing to the log output directory.
+
+    Raises:
+        ValueError: If path is invalid or cannot be resolved.
+    """
+    base_path: Path
+
+    if log_path == "auto":
+        # Try GPCLOG_PATH first, then fall back to home
+        env_path = os.environ.get("GPCLOG_PATH")
+        if env_path:
+            base_path = Path(env_path)
+        else:
+            base_path = Path.home()
+            # Print message to user
+            print(
+                f"gpclog: Using home directory for logs: {base_path / 'gpclog_output'}"
+            )
+    elif log_path == "env":
+        env_path = os.environ.get("GPCLOG_PATH")
+        if not env_path:
+            raise ValueError("GPCLOG_PATH environment variable is not set")
+        base_path = Path(env_path)
+    elif log_path == "home":
+        base_path = Path.home()
+    else:
+        # Treat as absolute path
+        base_path = Path(log_path)
+
+    # Validate path exists and is a directory
+    if not base_path.exists():
+        raise ValueError(f"Log path does not exist: {base_path}")
+    if not base_path.is_dir():
+        raise ValueError(f"Log path is not a directory: {base_path}")
+
+    # Check if already named gpclog_output
+    if base_path.name == "gpclog_output":
+        return base_path
+
+    # Create gpclog_output subfolder
+    final_path = base_path / "gpclog_output"
+    final_path.mkdir(exist_ok=True)
+    return final_path

gpclog-0.2.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: gpclog
+Version: 0.2.0
+Summary: General Purpose Category Logger - A Python library for managing categorized logs in complex projects.
+Project-URL: Homepage, https://github.com/linnetcodes/gpclog
+Project-URL: Documentation, https://linnetcodes.github.io/gpclog
+Project-URL: Repository, https://github.com/linnetcodes/gpclog
+Project-URL: Issues, https://github.com/linnetcodes/gpclog/issues
+Author-email: Linnet Codes <linnet.codes@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: categorized-logging,gpconfig,logging,loguru,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: gpconfig>=0.3.0
+Requires-Dist: loguru>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gpclog
+
+[简体中文](README.zh-CN.md) | English
+
+General Purpose Category Logger - A Python library for managing categorized logs in complex projects.
+
+## Features
+
+- **Category-based Logging** - Each category has its own configuration and file
+- **Built on loguru** - High-performance, feature-rich logging core
+- **Built on gpconfig** - Type-safe configuration management
+- **Smart Defaults** - Works out of the box with zero configuration
+- **Auto Class Registration** - Automatically registers with GPConfigManager on import
+
+## Installation
+
+```bash
+pip install gpclog
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import gpclog
+
+# Get a category logger (zero configuration)
+logger = gpclog.get_logger("my_category")
+logger.info("Hello, gpclog!")
+# Output to: ~/gpclog_output/my_category.log
+```
+
+### Using Configuration Files
+
+```python
+import gpclog
+from gpconfig import GPConfigManager
+
+# Initialize GPConfigManager (GPCLoggerConfig and GPCLogger are auto-registered)
+manager = GPConfigManager("myapp")
+
+# Method 1: Using gpclog public API
+logs_folder = manager.get_config("logs")
+gpclog.set_config_folder(logs_folder)
+logger = gpclog.get_logger("database")
+
+# Method 2: Using GPConfigManager directly
+logger = manager.get_object("logs.database")
+```
+
+Configuration schema, multiprocess usage, rotation/retention, and API details are documented in `docs/`.
+
+## Documentation
+
+Build and validate the documentation locally:
+
+```bash
+venv/bin/mkdocs build --clean --strict
+```
+
+Preview the documentation locally:
+
+```bash
+venv/bin/mkdocs serve
+```
+
+## API Reference
+
+See:
+
+- [Docs home](docs/index.md)
+- [gpclog module](docs/gpclog.md)
+- [GPCLogger](docs/logger.md)
+- [GPCLoggerConfig](docs/config.md)
+
+## License
+
+MIT

gpclog-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+gpclog/__init__.py,sha256=eHjAjHVU8S5SlI0iEHZMYzlhgH7vUMS8wVvuxvLKO5k,2949
+gpclog/config.py,sha256=s3q3c_NlO-VTkRZ9oPbJ1LtG_1q3RUvgh4jQ0-F3miw,1812
+gpclog/logger.py,sha256=D2L8DgiQCJhu-rL9M4qDRw7hrrrxfUrCWEkXNbm4M54,5045
+gpclog/manager.py,sha256=auCzaYL6W_spAG-OFnN5W01n8rFnx1gVudQiVTyvdGI,7757
+gpclog/utils.py,sha256=26CqwnSZS44go8-O8GlllyrSkW1ZC3tU54jobfpCLkY,1927
+gpclog-0.2.0.dist-info/METADATA,sha256=KH1eIB2bcU4RLb_2QsqK270JHkRcRMoVG2uWIhQ03P4,3287
+gpclog-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gpclog-0.2.0.dist-info/licenses/LICENSE,sha256=iQ52cpW4_bx-09PoR6JiM2vuI_WTgsCBve1G9-ydmgg,1094
+gpclog-0.2.0.dist-info/RECORD,,

gpclog-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gpclog-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linnet Codes <linnet.codes@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.