simplibs-logger 0.1.0__py3-none-any.whl

simplibs/logger/SimpleLogger.py

@@ -0,0 +1,347 @@
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+from simplibs.file import EncodingName
+from simplibs.validate import validate_call
+# Inners
+from .annotations import BackupCount, LogStream, MaxBytes
+from .definitions import SUCCESS_LEVEL
+from .levels import resolve_level
+from .lifecycle import close_logger, create_logger
+
+
+class SimpleLogger:
+    """A ready-to-use logger: a configured stdlib `logging.Logger` behind a small calling interface.
+
+    Example:
+        logger = SimpleLogger(name="my_app", file_path="logs/app.log")
+        logger.log_info("Application started")
+        logger("Disk almost full", level="warning")
+        logger.log_exception("Import failed")
+        logger.close()
+
+    It is also a context manager (`with SimpleLogger(...) as logger:`) that
+    closes its handlers on exit.
+    """
+
+    __slots__ = ("_logger", "_enabled", "_default_level")
+
+    # ----------------------------------------------------------------------
+    # Constructor initialization
+    # ----------------------------------------------------------------------
+    @validate_call
+    def __init__(
+        self,
+        *,
+        enabled: bool = True,
+        name: str | None = None,
+        level: int | str | None = None,
+        default_level: int | str | None = None,
+        file_path: str | Path | None = None,
+        encoding: EncodingName = "utf-8",
+        console: bool = True,
+        colored: bool = True,
+        console_level: int | str | None = None,
+        file_level: int | str | None = None,
+        stream: LogStream = None,
+        message_format: str | None = None,
+        date_format: str | None = None,
+        utc: bool = False,
+        max_bytes: MaxBytes = None,
+        backup_count: BackupCount = 3,
+        console_output: str | None = None,
+        file_output: str | None = None,
+        json_default: Callable[[Any], Any] | None = None,
+    ) -> None:
+        """Create the logger and its handlers.
+
+        Args:
+            enabled: If False, nothing is written until `enabled` is set to True.
+            name: The logger's name. `None` for `"simplibs"`.
+            level: The level of the logger, as a number or a name. `None` for INFO.
+            default_level: The level used by `log()` when no `level` is given.
+                `None` takes the value of `level` at creation.
+            file_path: If given, a file handler writes here.
+            encoding: The text encoding of the log file.
+            console: If True (default), a console handler is attached.
+            colored: If True (default), the console colors the level name.
+            console_level: An extra level filter of the console handler.
+            file_level: An extra level filter of the file handler.
+            stream: Where the console writes. `None` for standard error.
+            message_format: The log message format of every text handler.
+            date_format: The strftime format of the timestamp of every text handler.
+            utc: If True, timestamps are in UTC.
+            max_bytes: Rotate the log file at this size. `None` never rotates.
+            backup_count: How many rotated files to keep.
+            console_output: `"text"` (default) or `"json"` for the console.
+            file_output: `"text"` (default) or `"json"` for the file.
+            json_default: For JSON output, turns a value JSON cannot hold
+                into one it can. `None` for the built-in fallback.
+        """
+
+        # 1. Resolve the levels first, so a wrong one fails before any handler exists
+        resolved_level = resolve_level(level)
+        resolved_default = resolved_level if default_level is None else resolve_level(default_level)
+
+        # 2. Build the underlying stdlib logger
+        self._logger = create_logger(
+            name=name,
+            level=resolved_level,
+            file_path=file_path,
+            encoding=encoding,
+            console=console,
+            colored=colored,
+            console_level=console_level,
+            file_level=file_level,
+            stream=stream,
+            message_format=message_format,
+            date_format=date_format,
+            utc=utc,
+            max_bytes=max_bytes,
+            backup_count=backup_count,
+            console_output=console_output,
+            file_output=file_output,
+            json_default=json_default,
+        )
+
+        # 3. Store the switch and the level used by a bare `log(...)`
+        self._enabled = enabled
+        self._default_level = resolved_default
+
+    # ----------------------------------------------------------------------
+    # State
+    # ----------------------------------------------------------------------
+    @property
+    def logger(self) -> logging.Logger:
+        """The underlying stdlib `logging.Logger`, for direct access."""
+        return self._logger
+
+    @property
+    def name(self) -> str:
+        """The name of the logger."""
+        return self._logger.name
+
+    @property
+    def level(self) -> int:
+        """The level of the logger as a number."""
+        return self._logger.level
+
+    @property
+    def enabled(self) -> bool:
+        """The switch: False means nothing is written, whatever the level."""
+        return self._enabled
+
+    @enabled.setter
+    @validate_call
+    def enabled(self, value: bool) -> None:
+        self._enabled = value
+
+    def is_enabled_for(
+        self,
+        level: int | str | None = None,
+    ) -> bool:
+        """Tell whether a record of this level would be written now.
+
+        Args:
+            level: The level to ask about. `None` for `default_level`.
+
+        Returns:
+            True if the logger is enabled and its own level lets the level through.
+        """
+
+        # 1. The switch comes first
+        if not self._enabled:
+            return False
+
+        # 2. Then the level of the logger
+        resolved = self._default_level if level is None else resolve_level(level)
+        return self._logger.isEnabledFor(resolved)
+
+    def set_level(
+        self,
+        level: int | str,
+    ) -> None:
+        """Change the level of the logger.
+
+        Args:
+            level: A positive number or a level name.
+        """
+
+        # 1. Handlers follow the logger unless they were given a level of their own
+        self._logger.setLevel(resolve_level(level))
+
+    # ----------------------------------------------------------------------
+    # Logging - main
+    # ----------------------------------------------------------------------
+    def log(
+        self,
+        message: object,
+        *args: Any,
+        level: int | str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Write a message at `level`, or at `default_level` when none is given.
+
+        Args:
+            message: The message; may contain `%` placeholders filled from `args`.
+            *args: Values for the placeholders, as in `logging`.
+            level: A number or a name that replaces `default_level` for this call.
+            **kwargs: Forwarded to `logging.Logger.log` (`exc_info`, `extra`, ...).
+        """
+
+        # 1. Only an explicit level is validated; the default was validated at creation
+        target_level = self._default_level if level is None else resolve_level(level)
+
+        # 2. Hand over to the one place that writes
+        self._emit(target_level, message, args, kwargs)
+
+    # `logger("text")` is `logger.log("text")`; the same function keeps the call depth equal
+    __call__ = log
+
+    # ----------------------------------------------------------------------
+    # Logging - levels
+    # ----------------------------------------------------------------------
+    def log_debug(self, message: object, *args: Any, **kwargs: Any) -> None:
+        """Log a message with DEBUG severity."""
+        self._emit(logging.DEBUG, message, args, kwargs)
+
+    def log_info(self, message: object, *args: Any, **kwargs: Any) -> None:
+        """Log a message with INFO severity."""
+        self._emit(logging.INFO, message, args, kwargs)
+
+    def log_success(self, message: object, *args: Any, **kwargs: Any) -> None:
+        """Log a message with SUCCESS severity (25, between INFO and WARNING)."""
+        self._emit(SUCCESS_LEVEL, message, args, kwargs)
+
+    def log_warning(self, message: object, *args: Any, **kwargs: Any) -> None:
+        """Log a message with WARNING severity."""
+        self._emit(logging.WARNING, message, args, kwargs)
+
+    def log_error(self, message: object, *args: Any, **kwargs: Any) -> None:
+        """Log a message with ERROR severity."""
+        self._emit(logging.ERROR, message, args, kwargs)
+
+    def log_critical(self, message: object, *args: Any, **kwargs: Any) -> None:
+        """Log a message with CRITICAL severity."""
+        self._emit(logging.CRITICAL, message, args, kwargs)
+
+    def log_exception(self, message: object, *args: Any, **kwargs: Any) -> None:
+        """Log a message with ERROR severity and the current exception's traceback.
+
+        Meant for an `except` block. Pass `exc_info=<exception>` to log one
+        that is not being handled.
+        """
+        kwargs.setdefault("exc_info", True)
+        self._emit(logging.ERROR, message, args, kwargs)
+
+    # ----------------------------------------------------------------------
+    # Lifecycle
+    # ----------------------------------------------------------------------
+    def close(self) -> None:
+        """Close every handler (the log file included) and stop writing.
+
+        The logger can be created again under the same name.
+        """
+
+        # 1. Nothing is written after the handlers are gone
+        self._enabled = False
+
+        # 2. Release the files
+        close_logger(self._logger)
+
+    def __enter__(self) -> "SimpleLogger":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+
+        # 1. Close on the way out; an exception in the block is not suppressed
+        self.close()
+
+    # ----------------------------------------------------------------------
+    # Internal
+    # ----------------------------------------------------------------------
+    def _emit(
+        self,
+        level: int,
+        message: object,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> None:
+        """Write one record. The only place that talks to the stdlib logger."""
+
+        # 1. Skip entirely when switched off
+        if not self._enabled:
+            return
+
+        # 2. Point file, line and function at the caller of the public method:
+        #    caller -> public method -> _emit -> Logger.log, so two frames are ours
+        kwargs["stacklevel"] = kwargs.get("stacklevel", 1) + 2
+
+        # 3. Delegate to the stdlib logger
+        self._logger.log(level, message, *args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"SimpleLogger(name={self.name!r}, level={self.level}, enabled={self._enabled})"
+
+
+_DESIGN_NOTES = """
+# SimpleLogger — A Logger With a Short Way to Use It
+
+## Purpose
+A stdlib logger already configured (console, file, colors, format) and a
+small interface: `log_info("text %s", value)`, `logger("text")`.
+
+## Changes Against the Old Version
+* **`level` is keyword-only.** In `log("user %s", name)`, `name` is a
+  placeholder value, as in `logging`, never the level.
+* **File, line and function are the caller's.** Every public method calls
+  `_emit` directly, and `_emit` adds exactly two frames, so `log`, `log_info`
+  and `__call__` all report the caller and never `SimpleLogger.py`. A
+  `stacklevel` given by the caller still counts from their own call.
+* **`enabled` and `is_enabled_for(level)` are two things.** `enabled` is the
+  switch and reads back what was assigned; "would a record of this level be
+  written?" has a level in it, so it is a method.
+* **JSON output** (`console_output`, `file_output`, `json_default`): a
+  readable console and a JSON file, or JSON on both. Extra fields
+  (`logger.log_info("x", extra={"request_id": 7})`) become keys of the object.
+* **`log_exception`, `log_success`** (the level of the `SUCCESS` style
+  preset), **`close()`**, **`with`**, **`set_level`**, `name`, `level`.
+* **`default_level` starts at `level` when not given.** With `level="warning"`
+  a bare `logger("text")` would otherwise be silently below the logger's
+  level.
+
+## The Hot Path
+`log_*` check one bool and call the stdlib; no validation, because their
+levels are constants. Only an explicit `level=` is validated. `__call__ =
+log` is the same function, so it costs nothing extra and keeps the depth
+that `stacklevel` counts.
+
+## `close()`
+Switches `enabled` off and closes the handlers. Otherwise a late `log_error`
+would reach Python's "last resort" handler and appear on standard error.
+
+## `default_level` Is Fixed at Creation
+`set_level` changes the logger, not the level of a bare `log(...)`. A verbosity
+switch such as `set_level("error")` should quiet bare calls too, not promote
+them to ERROR. Create the logger again to change `default_level`.
+
+## Same Name, Same Logger
+A `SimpleLogger` wraps the logger of the standard registry under its name,
+so a second `SimpleLogger(name="x")` reconfigures the first. Give different
+loggers different names. The default `"simplibs"` is the parent of every
+`simplibs.*` logger and receives what other simplibs libraries log through
+plain `logging`.
+
+## `propagate` Is Not a Parameter
+A `SimpleLogger` owns its handlers, so its records stop there
+(`propagate=False`) and nothing is written twice. `create_logger` has the
+parameter for the rare caller who wants the handlers of a parent as well;
+through a `SimpleLogger` that is `logger.logger.propagate = True`.
+"""

simplibs/logger/__init__.py

@@ -0,0 +1,87 @@
+from .annotations import BackupCount, LogStream, MaxBytes
+from .definitions import (
+    DateFormat,
+    LEVEL_NAMES,
+    LoggerLevel,
+    LoggerName,
+    MessageFormat,
+    OUTPUT_FORMATS,
+    OutputFormat,
+    SUCCESS_LEVEL,
+)
+from .levels import register_success_level, resolve_level
+from .formatting import ColoredFormatter, JsonFormatter, build_formatter
+from .handlers import build_console_handler, build_file_handler
+from .lifecycle import close_logger, create_logger
+from .SimpleLogger import SimpleLogger
+
+__all__ = [
+    # core — the logger itself
+    "SimpleLogger",
+    "create_logger",
+    "close_logger",
+    # handlers — where records go
+    "build_console_handler",
+    "build_file_handler",
+    # formatting — how a record looks
+    "build_formatter",
+    "ColoredFormatter",
+    "JsonFormatter",
+    # levels
+    "resolve_level",
+    "register_success_level",
+    "SUCCESS_LEVEL",
+    "LEVEL_NAMES",
+    # validated atoms
+    "LoggerLevel",
+    "LoggerName",
+    "DateFormat",
+    "MessageFormat",
+    "OutputFormat",
+    "OUTPUT_FORMATS",
+    # annotations
+    "BackupCount",
+    "LogStream",
+    "MaxBytes",
+]
+
+
+_DESIGN_NOTES = """
+# simplibs-logger — Package Root
+
+## Purpose
+A ready-to-use logger with a console, an optional rotating file, colored
+level names, optional JSON output and a short interface:
+
+    from simplibs.logger import SimpleLogger
+
+    logger = SimpleLogger(file_path="logs/app.log")
+    logger.log_info("Application started")
+
+## What the Root Exports
+Everything a caller needs, from one import line: the logger (`SimpleLogger`,
+`create_logger`, `close_logger`), the parts it is built from
+(`build_console_handler`, `build_file_handler`, `build_formatter`,
+`ColoredFormatter`, `JsonFormatter`), the level helpers, the validated atoms and the
+annotations for the caller's own signatures.
+
+## What the Root Deliberately Does NOT Export
+Internals: the `_helpers/` and `_validations/` of each sub-package.
+
+## Layers That Only Look Left
+`definitions` and `annotations` <- `levels` <- `formatting` <- `handlers` <-
+`lifecycle` <- `SimpleLogger`. Each layer imports only from those before it.
+
+## One Error Family
+The library has no exception root of its own. Atoms raise the cards of
+`simplibs-object`, signatures raise those of `simplibs-validate`, and the one
+state of its own (a log file that cannot be opened) is an `AccessError` named
+`LOGGER_FILE_OPEN_FAILED`.
+
+## Dependencies
+`simplibs-exception`, `simplibs-object`, `simplibs-validate`,
+`simplibs-path`, `simplibs-style`, `simplibs-file` (`EncodingName`).
+
+## `__all__`
+Defined here only; the sub-packages export by plain imports.
+"""

simplibs/logger/annotations/BackupCount.py

@@ -0,0 +1,24 @@
+from typing import Annotated
+# Inners
+from ._helpers import is_backup_count
+
+
+BackupCount = Annotated[int, is_backup_count]
+"""How many rotated log files to keep: an integer of at least one. Zero, negatives and `bool` are rejected."""
+
+
+_DESIGN_NOTES = """
+# BackupCount — Rotation Needs at Least One Backup
+
+## Purpose
+The type of `backup_count`. It only has an effect together with `max_bytes`.
+A rejected value is refused by `@validate_call`, with the card of `simplibs-validate`.
+
+## Why `Annotated`
+`Annotated[int, is_backup_count]` is a type an editor and a type checker
+understand: they see a plain `int` and offer its methods and hints, while
+`@validate_call` reads the predicate from the metadata and checks the value.
+`validated_type(int, is_backup_count)` builds the same thing, but as a function
+call — the result is a value, not a type, so editors cannot follow it. It is
+meant for building many such types in bulk, not for a hand-written definition.
+"""

simplibs/logger/annotations/LogStream.py

@@ -0,0 +1,29 @@
+from typing import Annotated
+# Inners
+from ._helpers import is_writable_stream
+
+
+LogStream = Annotated[object | None, is_writable_stream]
+"""A stream the console handler writes to: any object with `write`; `None` for standard error."""
+
+
+_DESIGN_NOTES = """
+# LogStream — Where the Console Handler Writes
+
+## Purpose
+The type of `stream`. `None` is part of the type itself.
+
+## Colors Follow the Style Switch, Not the Stream
+`simplibs-style` decides by its own switch (and by standard output when it
+starts from the environment), not by what this stream is. A program that
+writes logs into a file-like object can pass `colored=False`, or switch
+styles off with `set_styles_enabled(False)`.
+
+## Why `Annotated`
+`Annotated[object | None, is_writable_stream]` is a type an editor and a type checker
+understand: they see the underlying type and offer its methods and hints, while
+`@validate_call` reads the predicate from the metadata and checks the value.
+`validated_type` builds the same thing as a function call — the result is a value,
+not a type, so editors cannot follow it. It is meant for building many such types
+in bulk, not for a hand-written definition.
+"""

simplibs/logger/annotations/MaxBytes.py

@@ -0,0 +1,24 @@
+from typing import Annotated
+# Inners
+from ._helpers import is_max_bytes
+
+
+MaxBytes = Annotated[int | None, is_max_bytes]
+"""The size at which a log file is rotated, in bytes; `None` for a file that is never rotated."""
+
+
+_DESIGN_NOTES = """
+# MaxBytes — A Size, or No Rotation
+
+## Purpose
+The type of `max_bytes`. `None` is part of the type itself, so a signature
+needs no separate `| None` next to a validated type.
+
+## Why `Annotated`
+`Annotated[int | None, is_max_bytes]` is a type an editor and a type checker
+understand: they see the underlying type and offer its methods and hints, while
+`@validate_call` reads the predicate from the metadata and checks the value.
+`validated_type` builds the same thing as a function call — the result is a value,
+not a type, so editors cannot follow it. It is meant for building many such types
+in bulk, not for a hand-written definition.
+"""

simplibs/logger/annotations/__init__.py

@@ -0,0 +1,20 @@
+from .BackupCount import BackupCount
+from .LogStream import LogStream
+from .MaxBytes import MaxBytes
+
+
+_DESIGN_NOTES = """
+# annotations — Shared Types of simplibs-logger
+
+Plain imports, no `__all__` (the package root decides what is public).
+`PathLike` and `EncodingName` are not redefined here: they come from
+`simplibs.path` and `simplibs.file`.
+
+## Internal Components Registry
+
+| Component     | Type           | Description                                               |
+| :------------ | :------------- | :-------------------------------------------------------- |
+| `BackupCount` | Annotated Type | How many rotated files to keep; at least one.             |
+| `LogStream`   | Annotated Type | A stream with `write`, or `None` for standard error.      |
+| `MaxBytes`    | Annotated Type | A size limit in bytes, or `None` for no rotation.         |
+"""

simplibs/logger/annotations/_helpers/__init__.py

@@ -0,0 +1,19 @@
+from .is_backup_count import is_backup_count
+from .is_max_bytes import is_max_bytes
+from .is_writable_stream import is_writable_stream
+
+
+_DESIGN_NOTES = """
+# Logger Annotation Helpers Sub-Package
+
+## Purpose
+The rules behind the validated types of the logger.
+
+## Internal Components Registry
+
+| Component            | Type     | Description                                                   |
+| :------------------- | :------- | :------------------------------------------------------------ |
+| `is_backup_count`    | Function | An `int` of at least one.                                     |
+| `is_max_bytes`       | Function | `None`, or an `int` greater than zero.                        |
+| `is_writable_stream` | Function | `None`, or an object with a callable `write`.                 |
+"""

simplibs/logger/annotations/_helpers/is_backup_count.py

@@ -0,0 +1,25 @@
+def is_backup_count(value: int) -> bool:
+    """Check whether a value is a usable number of rotated log files to keep.
+
+    Args:
+        value: The candidate.
+
+    Returns:
+        True for an `int` of at least one; False for zero, negatives and `bool`.
+    """
+
+    # 1. A real integer (a bool is an int, but never a count)
+    if not isinstance(value, int) or isinstance(value, bool):
+        return False
+
+    # 2. At least one backup, or the file would never rotate
+    return value >= 1
+
+
+_DESIGN_NOTES = """
+# is_backup_count — Why Zero Is Refused
+
+The rule behind `BackupCount`. In the standard `RotatingFileHandler`
+`backupCount=0` switches rotation off, whatever the size limit says. The
+log would grow without bound while the caller believes it is capped.
+"""

simplibs/logger/annotations/_helpers/is_max_bytes.py

@@ -0,0 +1,26 @@
+def is_max_bytes(value: int | None) -> bool:
+    """Check whether a value is a usable size limit of a log file.
+
+    Args:
+        value: The candidate.
+
+    Returns:
+        True for `None` (no limit) or an `int` greater than zero; False for
+        zero, negatives and `bool`.
+    """
+
+    # 1. None means "never rotate"
+    if value is None:
+        return True
+
+    # 2. Otherwise a real, positive integer (a bool is an int, but never a size)
+    return isinstance(value, int) and not isinstance(value, bool) and value > 0
+
+
+_DESIGN_NOTES = """
+# is_max_bytes — "No Limit, or a Positive Size"
+
+The rule behind `MaxBytes`. A limit of zero would be read by the standard
+library as "never rotate", the opposite of what a caller who wrote a limit
+meant, so it is refused at the signature instead.
+"""

simplibs/logger/annotations/_helpers/is_writable_stream.py

@@ -0,0 +1,30 @@
+from typing import Any
+
+
+def is_writable_stream(value: Any) -> bool:
+    """Check whether a value can serve as the stream of a console handler.
+
+    Args:
+        value: The candidate.
+
+    Returns:
+        True for `None` (the default, standard error) or any object with a
+        callable `write`; False otherwise.
+    """
+
+    # 1. None means "use standard error"
+    if value is None:
+        return True
+
+    # 2. Duck typing: wrapped streams (such as colorama's) are not `TextIOBase` subclasses
+    return callable(getattr(value, "write", None))
+
+
+_DESIGN_NOTES = """
+# is_writable_stream — Anything That Can Write
+
+The rule behind `LogStream`. `isinstance(stream, io.TextIOBase)` would refuse
+the stream wrappers that Windows programs often put on `sys.stderr`. What the
+handler needs is `write`, so that is what is checked, at the signature rather
+than in the middle of the first emit.
+"""