lfp-logging 0.0.3__tar.gz

lfp_logging-0.0.3/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.3
+Name: lfp-logging
+Version: 0.0.3
+Summary: A simple, zero-dependency lazy-initialization logging utility
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# lfp-logging
+
+A simple, zero-dependency logging utility for Python that provides lazy-initialization and automatic configuration.
+
+## Features
+
+- **Zero Dependencies**: Built entirely on the Python standard library.
+- **Lazy Initialization**: Logging is only configured when the first log message is actually handled. It uses a patching mechanism that stays out of the way until a log is emitted.
+- **Automatic Name Discovery**: Automatically determines logger names based on the caller's class, module, or file name.
+- **Smart Default Handlers**:
+  - `INFO` messages are sent to `stderr` (along with all other levels) by default.
+  - Detailed formatting including timestamps, levels, and line numbers.
+- **ANSI Colors**: Automatic color support for terminals, with overrides for popular IDEs (VSCode, PyCharm) and CI environments.
+- **Explicit Override Support**: If you call `logging.basicConfig()` yourself, `lfp-logging` will automatically back off and let your configuration take priority.
+- **Flexible Configuration**: Supports configuration via environment variables.
+- **Multi-platform Support**: Supports macOS (ARM/x64), Linux (ARM/x64), and Windows (x64/ARM).
+
+## Installation
+
+You can install `lfp-logging` directly from GitHub using `pip`:
+
+```bash
+pip install git+https://github.com/regbo/lfp-logging-py.git
+```
+
+Or add it to your `pyproject.toml` dependencies:
+
+```toml
+dependencies = [
+    "lfp_logging @ git+https://github.com/regbo/lfp-logging-py.git"
+]
+```
+
+## Quick Start
+
+```python
+from lfp_logging import logger
+
+# The logger name is automatically discovered as the class name "MyService"
+class MyService:
+    def __init__(self):
+        self.log = logger()
+    
+    def do_something(self):
+        self.log.info("Starting task...")
+        self.log.warning("Something might be wrong.")
+
+# You can specify one or more potential names. 
+# The first valid name (non-empty, not "__main__") will be used.
+log = logger(None, "__main__", "my_app")
+log.info("Hello World!") # Uses "my_app"
+```
+
+## Configuration
+
+The logging level and formats can be controlled using environment variables.
+
+### Environment Variables
+
+- `LOG_LEVEL`: Set the global log level. Accepts names (e.g., `DEBUG`, `INFO`) or numeric values (e.g., `10`, `20`).
+- `LOG_FORMAT`: Custom log format string (standard Python logging format).
+- `LOG_FORMAT_DATE`: Custom date format (default: `%Y-%m-%d %H:%M:%S`).
+- `LOG_FORMAT_COLOR`: Global ANSI color code for all levels.
+- `LOG_FORMAT_COLOR_<LEVEL>`: Level-specific ANSI color code (e.g., `LOG_FORMAT_COLOR_DEBUG`).
+- `LOG_CONFIG_LAZY`: Defer logging configuration until the first log message is emitted (default: `false`). Set to `true`, `1`, `yes`, or `on` to enable.
+
+### System Arguments
+
+The `--log-level` argument is no longer supported directly by the core configuration, but can be implemented by the user by setting the `LOG_LEVEL` environment variable before the first log call.
+
+## Development
+
+This project uses `uv` for dependency management and `pytest` for testing.
+
+### Running Tests
+
+```bash
+uv run pytest
+```

lfp_logging-0.0.3/README.md

@@ -0,0 +1,79 @@
+# lfp-logging
+
+A simple, zero-dependency logging utility for Python that provides lazy-initialization and automatic configuration.
+
+## Features
+
+- **Zero Dependencies**: Built entirely on the Python standard library.
+- **Lazy Initialization**: Logging is only configured when the first log message is actually handled. It uses a patching mechanism that stays out of the way until a log is emitted.
+- **Automatic Name Discovery**: Automatically determines logger names based on the caller's class, module, or file name.
+- **Smart Default Handlers**:
+  - `INFO` messages are sent to `stderr` (along with all other levels) by default.
+  - Detailed formatting including timestamps, levels, and line numbers.
+- **ANSI Colors**: Automatic color support for terminals, with overrides for popular IDEs (VSCode, PyCharm) and CI environments.
+- **Explicit Override Support**: If you call `logging.basicConfig()` yourself, `lfp-logging` will automatically back off and let your configuration take priority.
+- **Flexible Configuration**: Supports configuration via environment variables.
+- **Multi-platform Support**: Supports macOS (ARM/x64), Linux (ARM/x64), and Windows (x64/ARM).
+
+## Installation
+
+You can install `lfp-logging` directly from GitHub using `pip`:
+
+```bash
+pip install git+https://github.com/regbo/lfp-logging-py.git
+```
+
+Or add it to your `pyproject.toml` dependencies:
+
+```toml
+dependencies = [
+    "lfp_logging @ git+https://github.com/regbo/lfp-logging-py.git"
+]
+```
+
+## Quick Start
+
+```python
+from lfp_logging import logger
+
+# The logger name is automatically discovered as the class name "MyService"
+class MyService:
+    def __init__(self):
+        self.log = logger()
+    
+    def do_something(self):
+        self.log.info("Starting task...")
+        self.log.warning("Something might be wrong.")
+
+# You can specify one or more potential names. 
+# The first valid name (non-empty, not "__main__") will be used.
+log = logger(None, "__main__", "my_app")
+log.info("Hello World!") # Uses "my_app"
+```
+
+## Configuration
+
+The logging level and formats can be controlled using environment variables.
+
+### Environment Variables
+
+- `LOG_LEVEL`: Set the global log level. Accepts names (e.g., `DEBUG`, `INFO`) or numeric values (e.g., `10`, `20`).
+- `LOG_FORMAT`: Custom log format string (standard Python logging format).
+- `LOG_FORMAT_DATE`: Custom date format (default: `%Y-%m-%d %H:%M:%S`).
+- `LOG_FORMAT_COLOR`: Global ANSI color code for all levels.
+- `LOG_FORMAT_COLOR_<LEVEL>`: Level-specific ANSI color code (e.g., `LOG_FORMAT_COLOR_DEBUG`).
+- `LOG_CONFIG_LAZY`: Defer logging configuration until the first log message is emitted (default: `false`). Set to `true`, `1`, `yes`, or `on` to enable.
+
+### System Arguments
+
+The `--log-level` argument is no longer supported directly by the core configuration, but can be implemented by the user by setting the `LOG_LEVEL` environment variable before the first log call.
+
+## Development
+
+This project uses `uv` for dependency management and `pytest` for testing.
+
+### Running Tests
+
+```bash
+uv run pytest
+```

lfp_logging-0.0.3/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["uv_build>=0.9"]
+build-backend = "uv_build"
+
+[project]
+name = "lfp-logging"
+version = "0.0.3"
+description = "A simple, zero-dependency lazy-initialization logging utility"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+
+[dependency-groups]
+dev = ["pytest", "ruff", "bumpversion"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I"]
+ignore = []
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "osx-64", "linux-64", "linux-aarch64", "win-64", "win-arm64"]
+
+[tool.pixi.pypi-dependencies]
+lfp-logging = { path = ".", editable = true }
+ 
+[tool.pixi.environments]
+default = { solve-group = "default", features = ["dev"] }
+dev = { features = ["dev"], solve-group = "default" }
+
+
+[tool.pixi.tasks]
+publish = { cmd = "git add . && (git diff --staged --quiet || git commit -m \"pre-release: staging changes\") && bumpversion {{ part }} --message \"{{ message }}\" && git push origin HEAD --tags", args = [{ arg = "part", default = "patch" }, { arg = "message", default = "incrementing version to {new_version}" }] }
+

lfp_logging-0.0.3/src/lfp_logging/config.py

@@ -0,0 +1,148 @@
+import logging
+import os
+from dataclasses import dataclass
+from functools import cache
+from typing import IO, Any, Callable, Optional
+
+from lfp_logging import log_level
+
+"""
+This module manages the logging configuration by reading from environment
+variables. It provides defaults that can be overridden by the user via
+the standard environment variable names.
+
+Configuration is handled via `_Config` objects which lazily parse environment
+values when requested.
+"""
+
+
+@dataclass
+class _Config:
+    """
+    A generic configuration container that maps an environment variable
+    to a parsed value.
+    """
+
+    env_name: str
+    parser: Callable[[Optional[str]], Any]
+
+    def get(self) -> Any:
+        return self.parser(_env_value(self.env_name))
+
+
+LOG_LEVEL = _Config("LOG_LEVEL", lambda v: log_level.get(v, logging.INFO))
+LOG_CONFIG_LAZY = _Config("LOG_CONFIG_LAZY", lambda v: _parse_bool(v))
+LOG_FORMAT = _Config(
+    "LOG_FORMAT",
+    lambda v: v or "%(asctime)s %(levelname)s %(name)s:%(lineno)d %(message)s",
+)
+LOG_FORMAT_DATE = _Config("LOG_FORMAT_DATE", lambda v: v or "%Y-%m-%d %H:%M:%S")
+
+_LOG_FORMAT_COLOR_ENV_NAME = "LOG_FORMAT_COLOR"
+_LOG_LEVEL_COLORS = {
+    "TRACE": "\x1b[90m",
+    log_level.get(logging.DEBUG).name: "\x1b[36m",
+    log_level.get(logging.INFO).name: "\x1b[38;5;244m",
+    log_level.get(logging.WARNING).name: "\x1b[33m",
+    log_level.get(logging.ERROR).name: "\x1b[31m",
+    log_level.get(logging.CRITICAL).name: "\x1b[1;31m",
+}
+
+
+def color(stream: IO, record: logging.LogRecord) -> Optional[str]:
+    """
+    Returns the ANSI color code for a given log record if the stream supports it.
+
+    Color selection order:
+    1. `LOG_FORMAT_COLOR_<LEVEL>` environment variable.
+    2. `LOG_FORMAT_COLOR` environment variable.
+    3. Default level-specific colors.
+    """
+    if not _supports_color(stream):
+        return None
+    level_obj = log_level.get(record, None)
+    if level_obj is None:
+        return None
+    ansi_color = _env_value(_LOG_FORMAT_COLOR_ENV_NAME + "_" + level_obj.name.upper())
+    if ansi_color is None:
+        ansi_color = _env_value(_LOG_FORMAT_COLOR_ENV_NAME)
+    if ansi_color is None:
+        ansi_color = _LOG_LEVEL_COLORS.get(level_obj.name, None)
+    return ansi_color
+
+
+def _supports_color(stream: IO) -> bool:
+    """
+    Determines if the given stream supports ANSI color output.
+    Checks for TTY status, IDE-specific environment variables, and OS capabilities.
+    """
+    isatty = False
+    try:
+        if hasattr(stream, "isatty") and stream.isatty():
+            isatty = True
+    except Exception:
+        pass
+    if not isatty:
+        for k, v in {
+            "TERM_PROGRAM": "vscode",
+            "PYCHARM_HOSTED": "1",
+            "CODESPACES": "true",
+        }.items():
+            if _env_value(k) == v:
+                return True
+
+        return False
+
+    return _os_supports_color()
+
+
+@cache
+def _os_supports_color() -> bool:
+    term = _env_value("TERM")
+    if term is None or term == "dumb":
+        return False
+
+    ci = _env_value("CI")
+    if ci is not None and ci in ("GITHUB_ACTIONS", "GITLAB_CI", "COLORTERM"):
+        return False
+
+    if os.name == "nt":
+        env = os.environ
+        return any(k in env for k in ("WT_SESSION", "ANSICON", "ConEmuANSI", "TERM_PROGRAM"))
+
+    if _env_value("COLORTERM") is not None:
+        return True
+
+    # Known color capable TERM values
+    color_terms = (
+        "xterm",
+        "xterm-color",
+        "xterm-256color",
+        "screen",
+        "screen-256color",
+        "tmux",
+        "tmux-256color",
+        "rxvt-unicode",
+        "rxvt-unicode-256color",
+        "linux",
+    )
+
+    return any(term.startswith(t) for t in color_terms)
+
+
+def _env_value(name: Any) -> Optional[str]:
+    value = os.environ.get(name, None)
+    if value:
+        value = str(value).strip()
+    return value or None
+
+
+def _parse_bool(value: Any, default: Optional[bool] = False) -> Optional[bool]:
+    if value is not None:
+        value = str(value).lower().strip()
+        if value:
+            if value in ("true", "1", "yes", "on"):
+                return True
+            elif value in ("false", "0", "no", "off"):
+                return False
+    return default

lfp_logging-0.0.3/src/lfp_logging/log_level.py

@@ -0,0 +1,63 @@
+import logging
+from typing import Any, Union
+
+"""
+This module provides utilities for parsing and representing logging levels.
+It includes a LogLevel container and a robust parsing function that handles
+integers, strings, and numeric strings with support for defaults.
+"""
+
+_UNSET = object()
+
+
+class LogLevel:
+    """
+    A container for logging level information, mapping a human-readable name
+     to its corresponding integer value.
+    """
+
+    def __init__(self, name: str, level: int) -> None:
+        self.name = name
+        self.level = level
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.name!r}, level={self.level!r})"
+
+    def __str__(self) -> str:
+        return self.name
+
+
+def get(value: Any, default_value: Union[str, int, None] = _UNSET) -> Union[LogLevel, None]:
+    """
+    Converts a given value into a LogLevel object.
+
+    Args:
+        value: The value to convert. Can be an integer, a string name, or
+            a numeric string.
+        default_value: The value to return if parsing fails. If _UNSET (default),
+            raises a ValueError on failure.
+
+    Returns:
+        A LogLevel instance if conversion is successful.
+    """
+    if value is not None:
+        if isinstance(value, logging.LogRecord):
+            return get(value.levelno, default_value)
+        elif isinstance(value, int):
+            level_no = value
+            level_name = logging.getLevelName(level_no)
+            if isinstance(level_name, str) and level_name and not level_name.startswith("Level "):
+                return LogLevel(level_name, level_no)
+        else:
+            if level_name := str(value):
+                level_name = level_name.upper()
+                level_no = logging.getLevelName(level_name)
+                if isinstance(level_no, int):
+                    return LogLevel(level_name, level_no)
+                elif level_name.isdigit():
+                    return get(int(level_name), default_value)
+    if default_value is None:
+        return None
+    elif default_value is _UNSET:
+        raise ValueError(f"{LogLevel.__name__} not found: {value}")
+    return get(default_value)

lfp_logging-0.0.3/src/lfp_logging/logs.py

@@ -0,0 +1,224 @@
+import contextlib
+import inspect
+import logging
+import pathlib
+import sys
+import threading
+import types
+from typing import IO, Any, Callable, Optional
+
+from lfp_logging import config
+
+"""
+This module provides a lazy-initialization logging utility that automatically
+configures logging handlers with ANSI color support.
+
+The core design allows for "zero-config" logging that stays out of the way of
+other configuration attempts. It achieves this by patching loggers on creation:
+1. `logger()` returns a standard `logging.Logger` but patches its `isEnabledFor`
+   method.
+2. The first time a log level check occurs, `logging.basicConfig` is called
+   automatically with a default handler (stderr) and a custom color formatter.
+3. `logging.basicConfig` is also temporarily patched; if the user calls it
+   later, it will remove the default handler to ensure the user's explicit
+   configuration always wins.
+
+It includes functionality for:
+- Automatic logger name discovery from caller frames (classes, modules, filenames).
+- ANSI color support for terminals and IDEs (VSCode, PyCharm, etc.).
+- Transparent lazy initialization that supports multi-threaded environments.
+"""
+
+_HANDLE_PATCH_MARKER = ("_lfp_logging_handle_patch", object())
+_PYTHON_FILE_EXTENSION = ".py"
+
+
+class _InitContext(threading.Event):
+    def __init__(self) -> None:
+        super().__init__()
+        self._lock = threading.Lock()
+
+    def call(self, fn: Callable, *args, set: bool = True) -> bool:
+        if not self.is_set():
+            with self._lock:
+                if not self.is_set():
+                    fn(*args)
+                    if set:
+                        self.set()
+                    return True
+        return False
+
+
+_HANDLE_PATCH_CTX = _InitContext()
+_BASIC_CONFIG_PATCH_CTX = _InitContext()
+_BASIC_CONFIG_UNPATCH_CTX = _InitContext()
+
+
+class _Formatter(logging.Formatter):
+    """
+    Custom logging formatter that adds ANSI color codes to log messages
+    based on the log level and terminal support.
+    """
+
+    def __init__(self, stream: IO):
+        super().__init__(config.LOG_FORMAT.get(), config.LOG_FORMAT_DATE.get())
+        self.stream = stream
+
+    def format(self, record: logging.LogRecord) -> str:
+        message = super().format(record)
+        color = config.color(self.stream, record)
+        if color is None:
+            return message
+        return f"{color}{message}" + "\x1b[0m"
+
+
+def logger(*names: Any) -> logging.Logger:
+    """
+    Returns a standard logging.Logger instance, patched to trigger lazy
+    initialization of the default logging configuration on first use.
+
+    If names are provided, it attempts to use the first valid name. If no name
+    is provided or none are valid, it attempts to automatically determine a
+    suitable name from the caller's stack frame.
+
+    Args:
+        *names: Potential names for the logger. The first valid name found
+            (not None, not "__main__") will be used.
+
+    Returns:
+        A logging.Logger instance patched for lazy initialization.
+    """
+    name: Optional[str] = None
+    if names:
+        for n in names:
+            if name := _logger_name(n):
+                break
+    if not name:
+        current_frame = inspect.currentframe()
+        caller_frame = current_frame.f_back if current_frame else None
+        try:
+            if caller_frame:
+                if (instance := caller_frame.f_locals.get("self", None)) is not None:
+                    with contextlib.suppress(Exception):
+                        name = _logger_name(instance.__class__.__name__)
+                if not name and (cls := caller_frame.f_locals.get("cls", None)) is not None:
+                    with contextlib.suppress(Exception):
+                        name = _logger_name(cls.__name__)
+                if not name and (co_filename := caller_frame.f_code.co_filename) is not None:
+                    name = _logger_name(co_filename)
+        finally:
+            # Clean up frames to avoid reference cycles
+            del current_frame
+            del caller_frame
+        if not name:
+            name = __name__
+    logger_obj = logging.getLogger(name)
+    if config.LOG_CONFIG_LAZY.get():
+        _HANDLE_PATCH_CTX.call(_logger_handle_patch, logger_obj, set=False)
+    else:
+        _BASIC_CONFIG_PATCH_CTX.call(_logging_basic_config_patch)
+    return logger_obj
+
+
+def _logger_handle_patch(logger_obj: logging.Logger):
+    """
+    Patches a logger's isEnabledFor method to trigger basic configuration.
+
+    This is the entry point for the lazy initialization. It marks the logger
+    as patched and replaces its isEnabledFor method with a wrapper that
+    will call _logging_basic_config_patch once.
+    """
+    marker_name, marker_value = _HANDLE_PATCH_MARKER
+    if getattr(logger_obj, marker_name, None) is marker_value:
+        return
+    setattr(logger_obj, marker_name, marker_value)
+
+    _orig_is_enabled_for: Callable = logger_obj.isEnabledFor
+
+    def _is_enabled_for(self: logging.Logger, level) -> bool:
+        _BASIC_CONFIG_PATCH_CTX.call(_logging_basic_config_patch)
+        _HANDLE_PATCH_CTX.set()
+        self.isEnabledFor = _orig_is_enabled_for
+
+        return _orig_is_enabled_for(level)
+
+    logger_obj.isEnabledFor = types.MethodType(_is_enabled_for, logger_obj)
+
+
+def _logging_basic_config_patch():
+    """
+    Initializes default logging handlers and patches logging.basicConfig.
+
+    This function is called exactly once when the first log message (or check)
+    is processed. It sets up stdout/stderr handlers and replaces
+    logging.basicConfig with a wrapper that ensures user-provided configuration
+    can override these defaults.
+    """
+    log_level_no = config.LOG_LEVEL.get().level
+    handler = _create_logging_handler()
+
+    logging.basicConfig(
+        level=log_level_no,
+        handlers=[handler],
+    )
+
+    # ensure that all handlers added
+    if handler not in logging.root.handlers:
+        return
+
+    _orig_basic_config: Callable = logging.basicConfig
+
+    def _basic_config_unpatch():
+        root = logging.root
+        for h in root.handlers[:]:
+            if h is handler:
+                root.removeHandler(h)
+                h.close()
+
+    def _basic_config(**kwargs):
+        _BASIC_CONFIG_UNPATCH_CTX.call(_basic_config_unpatch)
+        logging.basicConfig = _orig_basic_config
+        _orig_basic_config(**kwargs)
+
+    logging.basicConfig = _basic_config
+
+
+def _create_logging_handler() -> logging.Handler:
+    """
+    Creates the default StreamHandler (stderr) with the custom color formatter.
+    """
+    stream = sys.stderr
+    handler = logging.StreamHandler(stream)
+    handler.setFormatter(_Formatter(stream))
+    return handler
+
+
+def _logger_name(value: Any) -> Optional[str]:
+    """
+    Parses and cleans a potential logger name.
+
+    It ignores "__main__", converts file paths ending in ".py" to a
+    "parent.stem" format, and replaces spaces with underscores.
+
+    Args:
+        value: The value to parse as a logger name.
+
+    Returns:
+        A cleaned string name if valid, otherwise None.
+    """
+    if value is None or value == "__main__":
+        return None
+
+    name = str(value) if value else None
+    if not name or name == "__main__":
+        return None
+
+    if name.lower().endswith(_PYTHON_FILE_EXTENSION):
+        with contextlib.suppress(Exception):
+            path = pathlib.Path(name)
+            if path_name := path.stem:
+                if parent_name := path.parent.name if path.parent else None:
+                    path_name = f"{parent_name}.{path_name}"
+                if path_name := "".join(c if c.isalnum() or c == "." else "_" for c in path_name):
+                    return path_name
+    return name