prismalog 0.1.0__tar.gz

prismalog-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexey Obukhov
+
+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.

prismalog-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: prismalog
+Version: 0.1.0
+Summary: High-performance colored, multi-process logging library for Python
+Author-email: Alexey Obukhov <alexey.obukhov@hotmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/vertok/prismalog
+Project-URL: Documentation, https://prismalog.readthedocs.io/
+Project-URL: Issues, https://github.com/vertok/prismalog/issues
+Project-URL: Changelog, https://github.com/vertok/prismalog/blob/main/CHANGELOG.md
+Keywords: logging,colored,high-performance,multiprocessing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=6.0.1; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: black>=22.6.0; extra == "dev"
+Requires-Dist: pylint>=2.14.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: isort>=5.10.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"
+Requires-Dist: PyYAML>=6.0.2; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.3.5; extra == "test"
+Requires-Dist: pytest-cov>=3.0.0; extra == "test"
+Requires-Dist: pytest-html>=3.2.0; extra == "test"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
+Requires-Dist: coverage>=7.6.1; extra == "test"
+Requires-Dist: nltk>=3.9.1; extra == "test"
+Requires-Dist: PyYAML>=6.0.2; extra == "test"
+Provides-Extra: doc
+Requires-Dist: sphinx>=4.5.0; extra == "doc"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "doc"
+Requires-Dist: sphinx-autodoc-typehints>=1.18.0; extra == "doc"
+Requires-Dist: sphinx-design>=0.5.0; extra == "doc"
+Provides-Extra: ci
+Requires-Dist: anybadge>=1.10.0; extra == "ci"
+Provides-Extra: all
+Requires-Dist: black>=22.6.0; extra == "all"
+Requires-Dist: pylint>=2.14.0; extra == "all"
+Requires-Dist: mypy>=1.0.0; extra == "all"
+Requires-Dist: isort>=5.10.0; extra == "all"
+Requires-Dist: build>=0.8.0; extra == "all"
+Requires-Dist: twine>=4.0.0; extra == "all"
+Requires-Dist: flake8>=5.0.0; extra == "all"
+Requires-Dist: pre-commit>=3.5.0; extra == "all"
+Requires-Dist: PyYAML>=6.0.2; extra == "all"
+Requires-Dist: pytest>=8.3.5; extra == "all"
+Requires-Dist: pytest-cov>=3.0.0; extra == "all"
+Requires-Dist: pytest-html>=3.2.0; extra == "all"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "all"
+Requires-Dist: coverage>=7.6.1; extra == "all"
+Requires-Dist: nltk>=3.9.1; extra == "all"
+Requires-Dist: sphinx>=4.5.0; extra == "all"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "all"
+Requires-Dist: sphinx-autodoc-typehints>=1.18.0; extra == "all"
+Requires-Dist: sphinx-design>=0.5.0; extra == "all"
+Requires-Dist: anybadge>=1.10.0; extra == "all"
+Dynamic: license-file
+
+# prismalog
+
+A robust, multi-process safe logging system for Python applications that integrates perfectly with the psy-supabase package.
+
+[![PyPI version](https://img.shields.io/pypi/v/prismalog.svg)](https://pypi.org/project/prismalog/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/prismalog.svg)](https://pypi.org/project/prismalog/)
+[![Coverage Python 3.8](https://vertok.github.io/prismalog/badges/coverage-py3.8.svg)](https://vertok.github.io/prismalog/htmlcov/index.html)
+[![Pylint Python 3.8](https://vertok.github.io/prismalog/badges/pylint-py3.8.svg)](https://vertok.github.io/prismalog/reports/html/3.8/reports/pylint/pylint-py3.8.html)
+[![Coverage Python 3.10](https://vertok.github.io/prismalog/badges/coverage-py3.10.svg)](https://vertok.github.io/prismalog/htmlcov/index.html)
+[![Pylint Python 3.10](https://vertok.github.io/prismalog/badges/pylint-py3.10.svg)](https://vertok.github.io/prismalog/reports/html/3.10/reports/pylint/pylint-py3.10.html)
+[![Coverage Python 3.11](https://vertok.github.io/prismalog/badges/coverage-py3.11.svg)](https://vertok.github.io/prismalog/htmlcov/index.html)
+[![Pylint Python 3.11](https://vertok.github.io/prismalog/badges/pylint-py3.11.svg)](https://vertok.github.io/prismalog/reports/html/3.11/reports/pylint/pylint-py3.11.html)
+
+## Features
+
+- ⚛️ Zero-dependency core
+- 🚀 High performance
+- 🎨 Colored console output
+- 📁 Automatic log file rotation
+- 🔄 Multi-process safe logging
+- 🧵 Multithreading-safe logging
+- ⚙️ YAML-based configuration
+- 🔇 Control for verbose third-party libraries
+- 🧪 Testing support
+
+## Performance Characteristics
+
+prismalog was designed for high-performance applications. My testing shows:
+
+- **Overhead per log call**: ~0.15ms (typical)
+- **Memory impact**: Minimal (~0.3MB for 10,000 messages)
+- **Throughput**: Capable of handling 20,000+ messages per second
+- **Multi-process/Multi-threading safety**: No measurable performance penalty compared to single-process
+
+## Performance Notes
+
+While prismalog achieves excellent performance characteristics, it's important to note that the primary bottleneck is filesystem I/O when writing to log files. This limitation is inherent to disk-based logging systems:
+
+- File locking mechanisms required for multi-process safety introduce some overhead
+- Synchronous writes to ensure log integrity can impact throughput during high-volume logging events
+- Storage device speed directly impacts maximum sustainable throughput
+
+For applications with extreme logging requirements, consider:
+- Using an asynchronous logging configuration
+- Implementing log batching for high-volume events
+- Configuring separate log files for different components to distribute I/O load
+
+The current performance metrics were achieved with standard SSD hardware. With specialized I/O optimization or enterprise-grade storage systems, significantly higher throughput is achievable.
+
+## Quick Start
+
+```python
+from prismalog import get_logger, LoggingConfig
+
+# Initialize with configuration file
+LoggingConfig.initialize(config_file="config.yaml")
+
+# Get a logger
+logger = get_logger("my_module")
+logger.info("Application started")
+```
+
+## Command-Line Integration
+
+Any application using prismalog automatically supports these command-line arguments:
+
+```bash
+--log-config PATH          # Path to logging configuration file
+--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                           # Set the default logging level
+--log-dir PATH             # Directory where log files will be stored
+```
+
+## Usage
+
+```python
+from prismalog.log import get_logger, LoggingConfig
+
+# Initialize logging (with command-line support)
+LoggingConfig.initialize(use_cli_args=True)
+
+# Get logger and use it
+logger = get_logger("my_app")
+logger.info("Application started")
+```
+
+## Dependencies
+
+prismalog is designed to work with **zero external dependencies** for core functionality. It relies solely on the Python standard library, making it lightweight and easy to integrate into any project.
+
+### Optional Dependencies
+
+- **YAML Configuration**: If YAML config files needed, install with `pip install prismalog[yaml]`
+- **Development**: For running tests and examples, install with `pip install prismalog[dev]`
+
+### Installation Options
+
+```bash
+# Prepare before installation (recommended)
+python -m venv .venv
+source source .venv/bin/activate
+
+# Basic installation - no external dependencies
+pip install -e .
+
+# With documentation support
+pip install prismalog[doc]
+
+# For development and testing
+pip install prismalog[dev]
+
+# With all optional features
+pip install prismalog[all]

prismalog-0.1.0/README.md

@@ -0,0 +1,113 @@
+# prismalog
+
+A robust, multi-process safe logging system for Python applications that integrates perfectly with the psy-supabase package.
+
+[![PyPI version](https://img.shields.io/pypi/v/prismalog.svg)](https://pypi.org/project/prismalog/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/prismalog.svg)](https://pypi.org/project/prismalog/)
+[![Coverage Python 3.8](https://vertok.github.io/prismalog/badges/coverage-py3.8.svg)](https://vertok.github.io/prismalog/htmlcov/index.html)
+[![Pylint Python 3.8](https://vertok.github.io/prismalog/badges/pylint-py3.8.svg)](https://vertok.github.io/prismalog/reports/html/3.8/reports/pylint/pylint-py3.8.html)
+[![Coverage Python 3.10](https://vertok.github.io/prismalog/badges/coverage-py3.10.svg)](https://vertok.github.io/prismalog/htmlcov/index.html)
+[![Pylint Python 3.10](https://vertok.github.io/prismalog/badges/pylint-py3.10.svg)](https://vertok.github.io/prismalog/reports/html/3.10/reports/pylint/pylint-py3.10.html)
+[![Coverage Python 3.11](https://vertok.github.io/prismalog/badges/coverage-py3.11.svg)](https://vertok.github.io/prismalog/htmlcov/index.html)
+[![Pylint Python 3.11](https://vertok.github.io/prismalog/badges/pylint-py3.11.svg)](https://vertok.github.io/prismalog/reports/html/3.11/reports/pylint/pylint-py3.11.html)
+
+## Features
+
+- ⚛️ Zero-dependency core
+- 🚀 High performance
+- 🎨 Colored console output
+- 📁 Automatic log file rotation
+- 🔄 Multi-process safe logging
+- 🧵 Multithreading-safe logging
+- ⚙️ YAML-based configuration
+- 🔇 Control for verbose third-party libraries
+- 🧪 Testing support
+
+## Performance Characteristics
+
+prismalog was designed for high-performance applications. My testing shows:
+
+- **Overhead per log call**: ~0.15ms (typical)
+- **Memory impact**: Minimal (~0.3MB for 10,000 messages)
+- **Throughput**: Capable of handling 20,000+ messages per second
+- **Multi-process/Multi-threading safety**: No measurable performance penalty compared to single-process
+
+## Performance Notes
+
+While prismalog achieves excellent performance characteristics, it's important to note that the primary bottleneck is filesystem I/O when writing to log files. This limitation is inherent to disk-based logging systems:
+
+- File locking mechanisms required for multi-process safety introduce some overhead
+- Synchronous writes to ensure log integrity can impact throughput during high-volume logging events
+- Storage device speed directly impacts maximum sustainable throughput
+
+For applications with extreme logging requirements, consider:
+- Using an asynchronous logging configuration
+- Implementing log batching for high-volume events
+- Configuring separate log files for different components to distribute I/O load
+
+The current performance metrics were achieved with standard SSD hardware. With specialized I/O optimization or enterprise-grade storage systems, significantly higher throughput is achievable.
+
+## Quick Start
+
+```python
+from prismalog import get_logger, LoggingConfig
+
+# Initialize with configuration file
+LoggingConfig.initialize(config_file="config.yaml")
+
+# Get a logger
+logger = get_logger("my_module")
+logger.info("Application started")
+```
+
+## Command-Line Integration
+
+Any application using prismalog automatically supports these command-line arguments:
+
+```bash
+--log-config PATH          # Path to logging configuration file
+--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                           # Set the default logging level
+--log-dir PATH             # Directory where log files will be stored
+```
+
+## Usage
+
+```python
+from prismalog.log import get_logger, LoggingConfig
+
+# Initialize logging (with command-line support)
+LoggingConfig.initialize(use_cli_args=True)
+
+# Get logger and use it
+logger = get_logger("my_app")
+logger.info("Application started")
+```
+
+## Dependencies
+
+prismalog is designed to work with **zero external dependencies** for core functionality. It relies solely on the Python standard library, making it lightweight and easy to integrate into any project.
+
+### Optional Dependencies
+
+- **YAML Configuration**: If YAML config files needed, install with `pip install prismalog[yaml]`
+- **Development**: For running tests and examples, install with `pip install prismalog[dev]`
+
+### Installation Options
+
+```bash
+# Prepare before installation (recommended)
+python -m venv .venv
+source source .venv/bin/activate
+
+# Basic installation - no external dependencies
+pip install -e .
+
+# With documentation support
+pip install prismalog[doc]
+
+# For development and testing
+pip install prismalog[dev]
+
+# With all optional features
+pip install prismalog[all]

prismalog-0.1.0/prismalog/__init__.py

@@ -0,0 +1,35 @@
+"""
+For more information, see the documentation at:
+https://github.com/vertok/prismalog
+"""
+
+from typing import Optional
+
+from .config import LoggingConfig
+from .log import ColoredFormatter, ColoredLogger, CriticalExitHandler, MultiProcessingLog, get_logger
+
+
+def setup_logging(config_file: Optional[str] = None, use_cli_args: bool = True) -> dict:
+    """
+    Initialize logging with potential command-line arguments.
+
+    Simple helper function that initializes LoggingConfig with both
+    a config file and command-line arguments. This is the most common
+    use case for applications.
+
+    Args:
+        config_file: Optional path to config file
+        use_cli_args: Whether to parse command-line arguments (default: True)
+    """
+    return LoggingConfig.initialize(config_file=config_file, use_cli_args=use_cli_args)
+
+
+__all__ = [
+    "get_logger",
+    "ColoredLogger",
+    "ColoredFormatter",
+    "MultiProcessingLog",
+    "CriticalExitHandler",
+    "LoggingConfig",
+    "setup_logging",
+]

prismalog-0.1.0/prismalog/argparser.py

@@ -0,0 +1,216 @@
+"""
+Standard command-line argument parser for prismalog logging system.
+
+This module provides a standardized way to add prismalog-related
+command line arguments to any application using the package. It enables
+consistent handling of logging configuration options across different
+applications and scripts.
+
+Features:
+---------
+* Standardized logging arguments for all prismalog applications
+* Support for configuration via command line or config file
+* Automatic mapping between CLI args and LoggingConfig settings
+* Integration with Python's argparse module
+* Consistent argument naming conventions
+
+Available Arguments:
+--------------------
+--log-config           Path to a YAML configuration file
+--log-level            Set the default logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+--log-dir              Directory where log files will be stored
+--log-format           Format string for log messages
+--no-color             Disable colored console output
+--disable-rotation     Disable log file rotation
+--exit-on-critical     Exit program on critical errors
+--rotation-size        Log file rotation size in MB
+--backup-count         Number of backup log files to keep
+
+Usage Examples:
+---------------
+1. Basic usage::
+
+    from prismalog.argparser import get_argument_parser, extract_logging_args
+    from prismalog.log import LoggingConfig
+
+    # Create parser with standard logging arguments
+    parser = get_argument_parser(description="My Application")
+
+    # Add your own application-specific arguments
+    parser.add_argument("--my-option", help="Application-specific option")
+
+    # Parse arguments
+    args = parser.parse_args()
+
+    # Extract and apply logging configuration
+    logging_args = extract_logging_args(args)
+    LoggingConfig.from_dict(logging_args)
+
+2. Adding to an existing parser::
+
+    import argparse
+    from prismalog.argparser import add_logging_arguments, extract_logging_args
+
+    # Create your own parser
+    parser = argparse.ArgumentParser(description="My Application")
+    parser.add_argument("--my-option", help="Application-specific option")
+
+    # Add standard logging arguments
+    add_logging_arguments(parser)
+
+    # Parse and extract
+    args = parser.parse_args()
+    logging_args = extract_logging_args(args)
+"""
+
+import argparse
+from typing import Any, Dict, Optional
+
+
+class LoggingArgumentParser:
+    """Helper class for adding standard logging arguments to argparse."""
+
+    @staticmethod
+    def add_arguments(parser: Optional[argparse.ArgumentParser] = None) -> argparse.ArgumentParser:
+        """
+        Add standard prismalog arguments to an existing parser.
+
+        Args:
+            parser: An existing ArgumentParser instance. If None, a new one is created.
+
+        Returns:
+            The ArgumentParser with prismalog arguments added
+        """
+        if parser is None:
+            parser = argparse.ArgumentParser()
+
+        # Config file option
+        parser.add_argument("--log-config", help="Path to a YAML configuration file")
+
+        # Standard logging arguments with case-insensitive level
+        parser.add_argument(
+            "--log-level",
+            choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+            type=str.upper,  # Simply convert to uppercase
+            help="Set the default logging level (case-insensitive)",
+        )
+
+        parser.add_argument("--log-dir", help="Directory where log files will be stored")
+
+        parser.add_argument("--log-format", help="Format string for log messages")
+
+        # Boolean flags
+        parser.add_argument(
+            "--no-color",
+            "--no-colors",
+            dest="colored_console",
+            action="store_false",
+            help="Disable colored console output",
+        )
+
+        parser.add_argument(
+            "--disable-rotation", dest="disable_rotation", action="store_true", help="Disable log file rotation"
+        )
+
+        parser.add_argument(
+            "--exit-on-critical",
+            dest="exit_on_critical",
+            action="store_true",
+            help="Exit the program on critical errors",
+        )
+
+        # Numeric options
+        parser.add_argument("--rotation-size", type=int, dest="rotation_size_mb", help="Log file rotation size in MB")
+
+        parser.add_argument("--backup-count", type=int, help="Number of backup log files to keep")
+
+        return parser
+
+    @staticmethod
+    def create_parser(description: Optional[str] = None) -> argparse.ArgumentParser:
+        """
+        Create a new ArgumentParser with prismalog arguments.
+
+        Args:
+            description: Description for the ArgumentParser
+
+        Returns:
+            A new ArgumentParser with prismalog arguments
+        """
+        parser = argparse.ArgumentParser(description=description)
+        return LoggingArgumentParser.add_arguments(parser)
+
+    @staticmethod
+    def extract_logging_args(args: argparse.Namespace) -> Dict[str, Any]:
+        """
+        Extract logging-related arguments from parsed args.
+
+        Args:
+            args: The parsed args from ArgumentParser.parse_args()
+
+        Returns:
+            Dictionary with only the logging-related arguments
+        """
+        # Define mappings from CLI arg names to config keys
+        key_mappings = {
+            "log_level": "default_level",
+            "log_config": "config_file",
+            "log_dir": "log_dir",
+            "log_format": "log_format",
+            "colored_console": "colored_console",
+            "disable_rotation": "disable_rotation",
+            "exit_on_critical": "exit_on_critical",
+            "rotation_size_mb": "rotation_size_mb",
+            "backup_count": "backup_count",
+        }
+
+        # Convert args to dictionary
+        args_dict = vars(args)
+
+        # Extract and map arguments
+        result = {}
+        for arg_name, value in args_dict.items():
+            if value is not None and arg_name in key_mappings:
+                config_key = key_mappings[arg_name]
+                result[config_key] = value
+
+        return result
+
+
+def get_argument_parser(description: Optional[str] = None) -> argparse.ArgumentParser:
+    """
+    Create a new ArgumentParser with prismalog arguments.
+
+    Args:
+        description: Description for the ArgumentParser
+
+    Returns:
+        A new ArgumentParser with prismalog arguments
+    """
+    return LoggingArgumentParser.create_parser(description)
+
+
+def add_logging_arguments(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
+    """
+    Add standard prismalog arguments to an existing parser.
+
+    Args:
+        parser: An existing ArgumentParser instance
+
+    Returns:
+        The ArgumentParser with prismalog arguments added
+    """
+    return LoggingArgumentParser.add_arguments(parser)
+
+
+def extract_logging_args(args: argparse.Namespace) -> Dict[str, Any]:
+    """
+    Extract logging-related arguments from parsed args.
+
+    Args:
+        args: The parsed args from ArgumentParser.parse_args()
+
+    Returns:
+        Dictionary with only the logging-related arguments
+    """
+    return LoggingArgumentParser.extract_logging_args(args)