sefkhet 0.1a0__py3-none-any.whl

sefkhet/__init__.py

@@ -0,0 +1,72 @@
+"""
+Complex logging setup made simple.
+
+The `sefkhet` package aims to enable one-step configuration of the
+built-in `logging` package, making complex logging setup easy.
+
+The main utilities are the `record`/`rec` function
+and the `Scribe` class.
+
+Getting started is as easy as importing and calling `record`:
+```
+from sefkhet import record
+
+record("I <3 sefkhet!")
+```
+
+You can also use the `Scribe` class for more fine-grained control:
+```
+import sefkhet
+
+scribe = sefkhet.Scribe(handlers="example.log")
+scribe.log("I <3 sefkhet!")
+```
+"""
+
+# Make top-level utilities available
+from sefkhet._color import ColorFormatter, get_level_color
+from sefkhet._csv import CsvFormatter
+from sefkhet._functional import (
+    add_filters_to_target,
+    add_handlers_to_logger,
+    get_filter,
+    get_formatter,
+    get_handler,
+    get_log_level_map,
+    get_log_levels,
+    get_logger,
+)
+from sefkhet._json import JsonFormatter
+from sefkhet._logfmt import LogfmtFormatter
+from sefkhet._object_oriented import Scribe
+from sefkhet._one_step import configure_default_logger, log, rec, record
+
+# Make version number available
+from sefkhet._version import __version__
+
+
+# Define public API
+__all__ = [  # ruff: ignore[unsorted-dunder-all]
+    # Metadata
+    "__version__",
+    # Classes
+    "ColorFormatter",
+    "CsvFormatter",
+    "JsonFormatter",
+    "LogfmtFormatter",
+    "Scribe",
+    # Functions
+    "add_filters_to_target",
+    "add_handlers_to_logger",
+    "configure_default_logger",
+    "get_filter",
+    "get_formatter",
+    "get_handler",
+    "get_level_color",
+    "get_log_level_map",
+    "get_log_levels",
+    "get_logger",
+    "log",
+    "rec",
+    "record",
+]

sefkhet/_color.py

@@ -0,0 +1,266 @@
+"""Color formatting utilities for `sefkhet`."""
+
+import logging as _logging
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+
+if _TYPE_CHECKING:  # pragma: no cover
+    import logging
+    from collections.abc import Callable, Mapping
+    from typing import Any
+
+    from sefkhet._typing import ColorMode, ColorSpec, FormatStyle
+
+
+# Define ANSI color strings
+_ANSI_RESET = "\033[0m"
+_PINK = "\033[38;5;212m"
+_BLUE = "\033[94m"
+_GREEN = "\033[32m"
+_CYAN = "\033[38;5;123m"
+_YELLOW = "\033[93m"
+_ORANGE = "\033[38;5;214m"
+_RED = "\033[91m"
+_MAGENTA = "\033[35m"
+
+# Define thresholds for the color mappings (The first number
+# for which the number <= threshold is the color that is used)
+_COLOR_THRESHOLDS = {
+    0: _PINK,
+    9: _BLUE,
+    19: _GREEN,
+    29: _CYAN,
+    39: _YELLOW,
+    49: _ORANGE,
+    59: _RED,
+    100: _MAGENTA,
+}
+
+
+# Define width to pad level names to
+_LEVELNAME_WIDTH = 8
+
+
+def _get_display_levelname(levelname: str) -> str:
+    """
+    Returns the name to display in the log for `levelname`.
+
+    Args:
+        levelname (str): Original log level name
+
+    Returns:
+        str: Formatted log level name to display, which is `levelname`
+            left-padded to `_LEVELNAME_WIDTH` characters, with the
+            prefix `"Level "` replaced by `"LEVEL_"` if `levelname`
+            starts with `"Level "` followed by a digit (e.g.,
+            `"Level 1"` becomes `"LEVEL_1"`)
+    """
+    if levelname.startswith("Level ") and levelname[6:].isdigit():
+        levelname = "LEVEL_" + levelname[6:]
+    return levelname.ljust(_LEVELNAME_WIDTH)
+
+
+def get_level_color(level: int) -> str:
+    """
+    Returns the ANSI escape code string for the given integer log level.
+
+    The mapping from level to color is:
+
+    - `<= 0` : pink
+    - `1-9`  : blue
+    - `10-19`: green
+    - `20-29`: cyan
+    - `30-39`: yellow
+    - `40-49`: orange
+    - `50-59`: red
+    - `60-100`: magenta
+    - `> 100`: none
+
+    Args:
+        level (int): Integer log level
+
+    Returns:
+        str: ANSI escape code string for the given level
+    """
+    # The threshold dictionary is ordered from lowest to highest,
+    # so we iterate through until we find level <= threshold
+    for threshold, color in _COLOR_THRESHOLDS.items():
+        if level <= threshold:
+            return color
+    # If no threshold matched, return an empty string
+    return ""
+
+
+def _parse_color_spec(
+    color: "ColorSpec",
+) -> "tuple[ColorMode, Callable[[int], str]]":
+    """
+    Parses a `ColorSpec` into a color mode and a color function.
+
+    Args:
+        color (ColorSpec): Either a bare `ColorMode` string or a
+            tuple of `(ColorMode, colormap)` where `colormap` is a
+            `Callable[[int], str]` or a `Mapping[int, str]`.
+
+    Returns:
+        tuple[ColorMode, Callable[[int], str]]: The color mode and a
+            callable that maps an integer log level to an ANSI color
+            escape code string
+    """
+    from collections.abc import Mapping
+
+    if not isinstance(color, tuple):
+        return color, get_level_color
+    mode, colormap = color
+    if isinstance(colormap, Mapping):
+
+        def _map_fn(level: int) -> str:
+            """
+            Returns the custom ANSI color code escape string for
+            `level` if `level` is in `colormap`; otherwise,
+            returns the default ANSI color code escape string
+            for `level` from `get_level_color`.
+
+            Args:
+                level (int): Integer log level
+
+            Returns:
+                str: ANSI escape code string for the given level
+            """
+            try:
+                return colormap[level]  # pyright: ignore[reportUnknownVariableType]
+            except KeyError:
+                return get_level_color(level)
+
+        return mode, _map_fn
+    return mode, colormap
+
+
+class ColorFormatter(_logging.Formatter):
+    """
+    A `logging.Formatter` subclass that applies ANSI color codes
+    to log output based on the log record's level.
+
+    The scope of colorization is controlled by the `color` mode:
+
+    - `"off"`: no colorization; output is identical to
+      `logging.Formatter`
+    - `"full"`: the entire formatted line is wrapped in color
+    - `"level"`: only the level name is wrapped in color
+    - `"msg"`: only the message is wrapped in color
+    - `"partial"`: everything except the message is colored
+    """
+
+    def __init__(  # ruff: ignore[too-many-arguments]
+        self,
+        fmt: str | None = None,
+        datefmt: str | None = None,
+        style: "FormatStyle" = "%",
+        *,
+        validate: bool = True,
+        defaults: "Mapping[str, Any] | None" = None,
+        color: "ColorSpec",
+    ) -> None:
+        """
+        A `logging.Formatter` subclass that applies ANSI color codes
+        to log output based on the log record's level.
+
+        The scope of colorization is controlled by the `color` mode:
+
+        - `"off"`: no colorization; output is identical to
+        `logging.Formatter`
+        - `"full"`: the entire formatted line is wrapped in color
+        - `"level"`: only the level name is wrapped in color
+        - `"msg"`: only the message is wrapped in color
+        - `"partial"`: everything except the message is colored
+
+        Args:
+            fmt (str | None, default=None): Format string.
+                Defaults to `None`.
+            datefmt (str | None, default=None): Date format string.
+                Defaults to `None`.
+            style (FormatStyle, default="%"): Format style.
+                Defaults to `"%"`.
+            validate (bool, default=True): If `True`, validates the
+                format string. Defaults to `True`.
+            defaults (Mapping[str, Any] | None, default=None):
+                Default values for string interpolation.
+                Defaults to `None`.
+            color (ColorSpec): Color mode controlling the scope of
+                colorization. Either a bare `ColorMode` string
+                (`"off"`, `"full"`, `"level"`, `"msg"`, or
+                `"partial"`) or a tuple of `(ColorMode, colormap)`
+                where `colormap` is a `Callable[[int], str]` or a
+                `Mapping[int, str]` for per-level color overrides.
+        """  # noqa: DOC105
+        super().__init__(
+            fmt=fmt,
+            datefmt=datefmt,
+            style=style,
+            validate=validate,
+            defaults=defaults,
+        )
+        self._color_mode, self._color_fn = _parse_color_spec(color)
+
+    def format(self, record: "logging.LogRecord") -> str:
+        """
+        Formats the log record with ANSI color codes applied
+        according to `self._color_mode`.
+
+        Args:
+            record (logging.LogRecord): Log record to format
+
+        Returns:
+            str: Formatted log record string
+        """
+        color = self._color_fn(record.levelno)
+        reset = _ANSI_RESET
+        orig_levelname = record.levelname
+        display_levelname = _get_display_levelname(orig_levelname)
+
+        if self._color_mode == "off":
+            record.levelname = display_levelname
+            try:
+                return super().format(record)
+            finally:
+                record.levelname = orig_levelname
+
+        if self._color_mode == "full":
+            record.levelname = display_levelname
+            try:
+                return f"{color}{super().format(record)}{reset}"
+            finally:
+                record.levelname = orig_levelname
+
+        if self._color_mode == "level":
+            record.levelname = f"{color}{display_levelname}{reset}"
+            try:
+                return super().format(record)
+            finally:
+                record.levelname = orig_levelname
+
+        if self._color_mode == "msg":
+            orig_msg = record.msg
+            orig_args = record.args
+            record.levelname = display_levelname
+            record.msg = f"{color}{record.getMessage()}{reset}"
+            record.args = None
+            try:
+                return super().format(record)
+            finally:
+                record.msg = orig_msg
+                record.args = orig_args
+                record.levelname = orig_levelname
+
+        # "partial": color everything except the message
+        orig_msg = record.msg
+        orig_args = record.args
+        record.levelname = display_levelname
+        record.msg = f"{reset}{record.getMessage()}{color}"
+        record.args = None
+        try:
+            return f"{color}{super().format(record)}{reset}"
+        finally:
+            record.msg = orig_msg
+            record.args = orig_args
+            record.levelname = orig_levelname

sefkhet/_constants.py

@@ -0,0 +1,85 @@
+"""Defines constants used in `sefkhet`."""
+
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+
+if _TYPE_CHECKING:  # pragma: no cover
+    import logging
+
+
+# Define fields with existing formatter interpolations
+_KNOWN_FIELDS: frozenset[str] = frozenset(
+    {
+        "timestamp",
+        "level",
+        "levelno",
+        "message",
+        "logger",
+        "module",
+        "funcName",
+        "lineno",
+        "pathname",
+    }
+)
+
+# Attributes that are standard on every LogRecord and should
+# not be treated as "extra" fields.
+_STANDARD_RECORD_ATTRS: frozenset[str] = frozenset(
+    {
+        "args",
+        "created",
+        "exc_info",
+        "exc_text",
+        "filename",
+        "funcName",
+        "levelname",
+        "levelno",
+        "lineno",
+        "message",
+        "module",
+        "msecs",
+        "msg",
+        "name",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "stack_info",
+        "taskName",
+        "thread",
+        "threadName",
+    }
+)
+
+
+def _extract_known_field(  # pyright: ignore[reportUnusedFunction]
+    field: str, record: "logging.LogRecord", formatter: "logging.Formatter"
+) -> object:
+    """
+    Extracts a known field value from a `LogRecord`.
+
+    Args:
+        field (str): The field name to extract
+        record (logging.LogRecord): The log record
+        formatter (logging.Formatter): The formatter instance,
+            used for `formatTime`
+
+    Returns:
+        object: The extracted field value
+    """
+    # Handle special time and message cases
+    if field == "timestamp":
+        return formatter.formatTime(record, formatter.datefmt)
+    if field == "message":
+        return record.getMessage()
+    # All remaining known fields are simple record attributes
+    attr_map: dict[str, str] = {
+        "level": "levelname",
+        "levelno": "levelno",
+        "logger": "name",
+        "module": "module",
+        "funcName": "funcName",
+        "lineno": "lineno",
+        "pathname": "pathname",
+    }
+    return getattr(record, attr_map[field])

sefkhet/_csv.py

@@ -0,0 +1,202 @@
+"""CSV formatting utilities for `sefkhet`."""
+
+import logging as _logging
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+
+if _TYPE_CHECKING:  # pragma: no cover
+    import logging
+    from collections.abc import Mapping
+    from typing import Any, Literal
+
+    from sefkhet._typing import CsvSpec, FormatStyle
+
+
+# Define fields to include for a default CSV formatter
+_DEFAULT_CSV_FIELDS: tuple[str, ...] = (
+    "timestamp",
+    "level",
+    "levelno",
+    "message",
+    "logger",
+)
+
+
+def _parse_csv_spec(
+    spec: "Literal[True] | CsvSpec",
+) -> "tuple[tuple[str, ...], str, int, bool]":
+    """
+    Returns the result of parsing a CSV spec
+    into resolved configuration values.
+
+    Args:
+        spec (Literal[True] | CsvSpec): Either `True` for
+            defaults or a `CsvSpec` dict with optional keys
+            `fields`, `delimiter`, `quoting`, and `header`.
+
+    Returns:
+        tuple[tuple[str, ...], str, int, bool]: A tuple of
+            `(fields, delimiter, quoting, header)`
+    """
+    import csv
+
+    # Handle boolean case
+    if isinstance(spec, bool):
+        return _DEFAULT_CSV_FIELDS, ",", csv.QUOTE_MINIMAL, False
+    # Use values from spec if given, otherwise use defaults
+    fields = tuple(spec.get("fields", _DEFAULT_CSV_FIELDS))
+    delimiter = spec.get("delimiter", ",")
+    quoting = spec.get("quoting", csv.QUOTE_MINIMAL)
+    header = spec.get("header", False)
+    return fields, delimiter, quoting, header
+
+
+class CsvFormatter(_logging.Formatter):
+    """
+    A `logging.Formatter` subclass that
+    outputs log records as CSV rows.
+
+    Each log line is a single CSV row with configurable
+    fields. Extra attributes passed via `extra={...}` are
+    automatically included. Exception and stack info are
+    serialised as strings when present.
+    """
+
+    def __init__(  # ruff: ignore[too-many-arguments]
+        self,
+        fmt: str | None = None,
+        datefmt: str | None = None,
+        style: "FormatStyle" = "%",
+        *,
+        validate: bool = True,
+        defaults: "Mapping[str, Any] | None" = None,
+        csv: "Literal[True] | CsvSpec",
+    ) -> None:
+        """
+        A `logging.Formatter` subclass that
+        outputs log records as CSV rows.
+
+        Each log line is a single CSV row with configurable
+        fields. Extra attributes passed via `extra={...}` are
+        automatically included. Exception and stack info are
+        serialised as strings when present.
+
+        Args:
+            fmt (str | None, default=None): Format string (unused
+                in CSV output but accepted for interface
+                compatibility). Defaults to `None`.
+            datefmt (str | None, default=None): Date format string
+                used by `formatTime`. Defaults to `None`.
+            style (FormatStyle, default="%"): Format style.
+                Defaults to `"%"`.
+            validate (bool, default=True): If `True`, validates
+                the format string. Defaults to `True`.
+            defaults (Mapping[str, Any] | None, default=None):
+                Default values for string interpolation.
+                Defaults to `None`.
+            csv (Literal[True] | CsvSpec): CSV configuration.
+                `True` for defaults, or a `CsvSpec` dict with
+                optional keys `fields`, `delimiter`, `quoting`,
+                and `header`.
+        """  # noqa: DOC105
+        super().__init__(
+            fmt=fmt,
+            datefmt=datefmt,
+            style=style,
+            validate=validate,
+            defaults=defaults,
+        )
+
+        # Parse the CSV-specific options
+        (
+            self._csv_fields,
+            self._csv_delimiter,
+            self._csv_quoting,
+            self._csv_header,
+        ) = _parse_csv_spec(csv)
+
+        # Track if the header has been written
+        self._csv_header_written = False
+
+    def format(self, record: "logging.LogRecord") -> str:
+        """
+        Formats the log record as a CSV string.
+
+        Args:
+            record (logging.LogRecord): Log record to format
+
+        Returns:
+            str: CSV-formatted log record string
+        """
+        import csv
+        import io
+
+        from sefkhet._constants import (
+            _KNOWN_FIELDS,
+            _STANDARD_RECORD_ATTRS,
+            _extract_known_field,
+        )
+
+        values: list[str] = []
+
+        # Build values from configured fields
+        for field in self._csv_fields:
+            if field in _KNOWN_FIELDS:
+                val = _extract_known_field(field, record, self)
+            else:
+                val = getattr(record, field, None)
+            values.append(str(val))
+
+        # Handle exc_info
+        if record.exc_info and record.exc_info[0] is not None:
+            values.append(self.formatException(record.exc_info))
+
+        # Handle stack_info
+        if record.stack_info:
+            values.append(self.formatStack(record.stack_info))
+
+        # Append extra fields
+        existing_fields = set(self._csv_fields) | _STANDARD_RECORD_ATTRS
+        existing_fields.add("exc_info")
+        existing_fields.add("stack_info")
+        for k, v in record.__dict__.items():
+            if k not in existing_fields:
+                values.append(str(v))
+
+        # Write CSV row
+        output = io.StringIO()
+        writer = csv.writer(
+            output,
+            delimiter=self._csv_delimiter,
+            quoting=self._csv_quoting,  # type: ignore[arg-type] # pyright: ignore[reportArgumentType]
+        )
+
+        # Prepend header row on first call if requested
+        result_lines: list[str] = []
+        if self._csv_header and not self._csv_header_written:
+            header_fields = list(self._csv_fields)
+            # Add extra column names for exc_info/stack_info
+            if record.exc_info and record.exc_info[0] is not None:
+                header_fields.append("exc_info")
+            if record.stack_info:
+                header_fields.append("stack_info")
+            # Add any extra field columns defined by user
+            extras = [k for k in record.__dict__ if k not in existing_fields]
+            header_fields.extend(extras)
+            # Write header to buffer
+            writer.writerow(header_fields)
+            # Add header to CSV output
+            result_lines.append(output.getvalue().rstrip("\r\n"))
+            # Reset the buffer to beginning to prepare for actual log
+            output.seek(0)
+            output.truncate()
+            # Mark header as written
+            self._csv_header_written = True
+
+        # Write logged values to buffer
+        writer.writerow(values)
+        # Add log row to CSV output
+        result_lines.append(output.getvalue().rstrip("\r\n"))
+
+        # Return CSV output row with possible header above
+        return "\n".join(result_lines)