amox 0.0.1__py3-none-any.whl

amox/__init__.py

@@ -0,0 +1,17 @@
+"""Amox."""
+
+from amox.formatters import JsonFormatter, LogfmtFormatter, create_formatter
+from amox.logging_ import config, get_logger, setup
+from amox.types_ import FormatterOptions
+
+__all__ = [
+    "FormatterOptions",
+    "JsonFormatter",
+    "LogfmtFormatter",
+    "config",
+    "create_formatter",
+    "get_logger",
+    "setup",
+]
+
+__version__ = "0.0.1"

amox/dictConfig.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "../../schema/dictConfig.schema.json",
+  "disable_existing_loggers": false,
+  "formatters": {
+    "amox": {
+      "()": "amox.create_formatter"
+    }
+  },
+  "handlers": {
+    "amox": {
+      "class": "logging.StreamHandler",
+      "formatter": "amox",
+      "stream": "ext://sys.stderr"
+    },
+    "amox.queue_handler": {
+      "class": "amox.handlers.LiveQueueHandler",
+      "handlers": [
+        "amox"
+      ],
+      "respect_handler_level": true
+    }
+  },
+  "root": {
+    "handlers": [
+      "amox.queue_handler"
+    ],
+    "level": "INFO"
+  },
+  "version": 1
+}

amox/formatters.py

@@ -0,0 +1,383 @@
+"""Schema on read formatters."""
+
+import datetime as dt
+import json
+import logging
+import os
+import re
+import typing as t
+import warnings
+
+from amox.types_ import (
+    FieldRemap,
+    FormatterOptions,
+    IncludeFields,
+    Json,
+    Logfmt,
+    LogFormat,
+    LogRecordAttr,
+)
+
+LOG_FORMAT_ENV = "AMOX_LOG_FORMAT"
+"""
+Convention environment variable name to configure log format.
+"""
+
+DEL_CHAR = 0x7F
+"""
+ASCII DEL character ordinal.
+"""
+
+LOG_RECORD_BUILTIN_ATTRS: set[LogRecordAttr] = set(  # pyright: ignore[reportAssignmentType]
+    logging.makeLogRecord({"message": "", "asctime": ""}).__dict__.keys(),
+)  # ty: ignore[invalid-assignment]
+"""
+`logging.LogRecord` instance attributes to enrich logs.
+
+Note:
+    `message` and `asctime` are seeded, since `makeLogRecord` materializes theme during
+    `Formatter.format()`.
+"""
+
+
+LOG_FORMATS: set[LogFormat] = {
+    "json",
+    "logfmt",
+}
+
+DEFAULT_FORMAT: LogFormat = "logfmt"
+
+DEFAULT_FIELD_REMAP: FieldRemap = {
+    "created": "ts",
+    "levelname": "level",
+    "name": "logger",
+    "msg": "msg",
+    "exc_info": "exception",
+}
+"""
+Default rename convention of `LogRecordAttr`.
+"""
+
+DEFAULT_INCLUDE: tuple[LogRecordAttr, ...] = (
+    "created",
+    "levelname",
+    "name",
+    "msg",
+    "exc_info",
+)
+
+VERBOSE_INCLUDE: tuple[LogRecordAttr, ...] = (
+    *DEFAULT_INCLUDE,
+    "filename",
+    "lineno",
+    "funcName",
+    "threadName",
+    "processName",
+)
+
+ALL_EXCLUDE: set[LogRecordAttr] = {
+    "args",
+    "exc_text",
+    "relativeCreated",
+    "msecs",
+}
+"""
+Always excluded attributes from log record.
+"""
+
+
+class AmoxFormatter(logging.Formatter):
+    """Base formatter with shared field extraction logic."""
+
+    configurable: frozenset[
+        t.Literal[
+            "datefmt",
+            "include",
+            "snake_case",
+            "field_remap",
+        ]
+    ] = frozenset(
+        {
+            "datefmt",
+            "include",
+            "snake_case",
+            "field_remap",
+        },
+    )
+    tz: dt.tzinfo | None = None
+
+    def __init__(  # noqa: PLR0913
+        self,
+        fmt: str | None = None,
+        datefmt: str | None = None,
+        style: t.Literal["%", "{", "$"] = "%",
+        validate: bool = True,  # noqa: FBT001, FBT002
+        *,
+        defaults: dict[str, object] | None = None,
+        include: IncludeFields = "minimal",
+        snake_case: bool = True,
+        field_remap: FieldRemap = DEFAULT_FIELD_REMAP,
+    ) -> None:
+        """
+        Initialize the structured formatter.
+
+        Args:
+            fmt: format string for `logging.Formatter` (e.g. `'%(message)s'`).
+                Included for protocol, not typically used with schema formatters.
+            datefmt: strftime format for `LogRecord.created` timestamp.
+            style: format string style character (`%`, `{`, or `$`).
+            validate: whether to validate the format string.
+            defaults: default values merged into every record's `__dict__`.
+            include: list of attributes of a record to include, or string based
+                convention.
+            snake_case: whether to snake_case the keys from the compiled records.
+                Applies to field_remap values as well.
+            field_remap: mapping to convert attribute keys to a different name
+
+        """
+        super().__init__(
+            fmt=fmt,
+            datefmt=datefmt,
+            style=style,
+            validate=validate,
+            defaults=defaults,
+        )
+        self.snake_case: bool = snake_case
+        self.field_remap: FieldRemap = field_remap
+
+        self.include: tuple[LogRecordAttr, ...] = self.includes(include)
+        self.field_remap_keys: list[LogRecordAttr] = list(field_remap.keys())
+
+    def includes(self, fields: IncludeFields) -> tuple[LogRecordAttr, ...]:
+        """Resolve record attributes to include on the record."""
+        if isinstance(fields, list):
+            return tuple(fields)
+        if fields == "minimal":
+            return DEFAULT_INCLUDE
+        if fields == "verbose":
+            return VERBOSE_INCLUDE
+
+        return tuple(  # "all"
+            LOG_RECORD_BUILTIN_ATTRS - ALL_EXCLUDE,
+        )
+
+    def output_key(self, source: str) -> str:
+        """
+        Resolve the output key name for a `LogRecord` attribute.
+
+        Apply's `field_remap` rename if present, snake cases field if configured.
+        """
+        if source in self.field_remap_keys:
+            source = self.field_remap[source]  # ty: ignore[invalid-argument-type]
+
+        return self.to_snake(source) if self.snake_case else source
+
+    def value_from_record(
+        self,
+        record: logging.LogRecord,
+        source: LogRecordAttr,
+    ) -> str | None:
+        """
+        Extract a value from a `LogRecord`.
+
+        Apply dedicated reader to attributes that are enhanced by standard record
+        formatters or custom.
+        """
+        if source == "msg":
+            return record.getMessage()
+        if source == "created":
+            return self.format_timestamp(record.created)
+
+        if source == "exc_info":
+            return (
+                self.formatException(exc)
+                if (exc := record.exc_info)
+                else record.exc_text
+            )
+        return getattr(record, source, None)
+
+    def compile_record(self, record: logging.LogRecord) -> dict[str, object]:
+        """
+        Build dictionary from a `LogRecord`, ready to deserialize.
+
+        Pre-process a raw log record object with configuration options. Produce
+        a mapping ready for formatting.
+        """
+        payload: dict[str, object] = {}
+
+        for key in self.include:
+            val = self.value_from_record(record, key)
+            if key == "exc_info" and val is None:
+                continue
+            payload[self.output_key(key)] = val
+
+        payload.update(
+            {
+                key: val
+                for key, val in record.__dict__.items()
+                if key not in LOG_RECORD_BUILTIN_ATTRS
+            },
+        )
+
+        return payload
+
+    def format_timestamp(self, created: float) -> str:
+        """
+        Format a unix timestamp using `datefmt`.
+
+        When `tz` is set, formats in that timezone. UTC gets a `Z` suffix.
+        Defaults to local time with ISO 8601 foramt.
+        """
+        timestamp = dt.datetime.fromtimestamp(created, tz=dt.UTC)
+        if self.tz is not None:
+            timestamp = timestamp.astimezone(self.tz)
+        else:
+            timestamp = timestamp.astimezone()
+        if self.datefmt:
+            return timestamp.strftime(self.datefmt)
+        iso = timestamp.isoformat()
+        if self.tz == dt.UTC:
+            return iso.replace("+00:00", "Z")
+        return iso
+
+    @staticmethod
+    def to_snake(camel: str) -> str:
+        """
+        Convert a camelCase string to snake_case.
+
+        Reference:
+            `https://github.com/pydantic/pydantic/blob/main/pydantic/alias_generators.py`
+        """
+        snake = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", camel)
+        snake = re.sub(r"([a-z])([A-Z])", r"\1_\2", snake)
+        snake = re.sub(r"([0-9])([A-Z])", r"\1_\2", snake)
+        snake = re.sub(r"([a-z])([0-9])", r"\1_\2", snake)
+        return snake.replace("-", "_").lower()
+
+
+class LogfmtFormatter(AmoxFormatter):
+    """
+    Formats log records as logfmt key=value pairs.
+
+    Reference:
+        `https://brandur.org/logfmt`
+    """
+
+    @t.override
+    def format(self, record: logging.LogRecord) -> str:
+        payload = self.compile_record(record)
+        return " ".join(
+            f"{key}={self.encode_value(val)}" for key, val in payload.items()
+        )
+
+    def encode_value(self, value: object) -> str:
+        """
+        Encode a value for logfmt output.
+
+        Reference:
+            `https://github.com/go-logfmt/logfmt/blob/master/encode.go`
+        """
+        if value is None:
+            return "null"
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if isinstance(value, (int, float)):
+            return str(value)
+        return self.quote(str(value))
+
+    def quote(self, s: str) -> str:
+        """Apply logfmt quoting rules to a string value."""
+        if not s:
+            return '""'
+        if self.needs_quote(s):
+            escaped = (
+                s.replace("\\", "\\\\")
+                .replace('"', '\\"')
+                .replace("\n", "\\n")
+                .replace("\r", "\\r")
+                .replace("\t", "\\t")
+            )
+            return f'"{escaped}"'
+        return s
+
+    def needs_quote(self, s: str) -> bool:
+        """
+        Whether a logfmt value needs quoting.
+
+        Reference:
+            `https://github.com/go-logfmt/logfmt/blob/master/encode.go`
+        """
+        return any(c <= " " or c in {"=", '"', "\\"} or ord(c) == DEL_CHAR for c in s)
+
+
+class JsonFormatter(AmoxFormatter):
+    """Formats log records as JSON."""
+
+    @t.override
+    def format(self, record: logging.LogRecord) -> str:
+        payload = self.compile_record(record)
+        return json.dumps(payload, default=str)
+
+
+@t.overload
+def create_formatter(
+    log_format: Json,
+    /,
+    **opts: t.Unpack[FormatterOptions],
+) -> JsonFormatter: ...
+
+
+@t.overload
+def create_formatter(
+    log_format: Logfmt | None = None,
+    /,
+    **opts: t.Unpack[FormatterOptions],
+) -> LogfmtFormatter: ...
+
+
+def create_formatter(
+    log_format: LogFormat | None = None,
+    /,
+    **opts: t.Unpack[FormatterOptions],
+) -> JsonFormatter | LogfmtFormatter:
+    """
+    Create a formatter from a format identifier string.
+
+    Resolve the log format and return the corresponding formatter instance.
+    Used as the factory for `dictConfig`'s `()` protocol.
+    """
+    log_format = log_format or resolve_format()
+    tz = opts.get("tz")
+    field_remap: FieldRemap = {
+        **DEFAULT_FIELD_REMAP,
+        **(opts.get("field_remap") or {}),
+    }
+    cls = JsonFormatter if log_format == "json" else LogfmtFormatter
+    formatter = cls(
+        datefmt=opts.get("datefmt"),
+        include=opts.get("include", "minimal"),
+        snake_case=opts.get("snake_case", True),
+        field_remap=field_remap,
+    )
+    formatter.tz = tz
+    return formatter
+
+
+def resolve_format() -> LogFormat:
+    """Resolve log format from  environment variable convention."""
+    env = os.environ.get(LOG_FORMAT_ENV)
+    if env is None:
+        return DEFAULT_FORMAT
+    if env in LOG_FORMATS:
+        return env  # ty: ignore[invalid-return-type]
+
+    warnings.warn(
+        (
+            f"{LOG_FORMAT_ENV}={env!r} is not valid."
+            f" Expected one of: {', '.join(sorted(LOG_FORMATS))}."
+            f" Falling back to {DEFAULT_FORMAT!r}."
+        ),
+        UserWarning,
+        stacklevel=2,
+    )
+    return DEFAULT_FORMAT

amox/handlers.py

@@ -0,0 +1,55 @@
+"""Handlers."""
+
+import atexit
+import logging
+import traceback
+import typing as t
+from logging.handlers import QueueHandler, QueueListener
+
+
+class LiveQueueHandler(QueueHandler):
+    """
+    Queue-based log handler with automatic listener lifecycle.
+
+    The `QueueListener` is started as soon as it is attached and stopped on
+    interpreter shutdown via `atexit`.
+    """
+
+    listener: QueueListener | None = None
+
+    @t.override
+    def __setattr__(self, name: str, value: object) -> None:
+        super().__setattr__(name, value)
+        if name == "listener" and isinstance(value, QueueListener):
+            value.start()
+            _ = atexit.register(self.stop_listener)
+
+    def stop_listener(self) -> None:
+        """
+        Stop the listener if it is still running.
+
+        Guards against double-stop when atexit fires after an explicit `listener.stop()`
+        call.
+        """
+        if (listener := self.listener) is not None and listener._thread is not None:  # noqa: SLF001
+            listener.stop()
+
+    @t.override
+    def prepare(self, record: logging.LogRecord) -> logging.LogRecord:
+        """
+        Preserve `exc_text` for downstream formatters.
+
+        Python 3.12's stdlib `prepare()` embeds the traceback into `record.msg`
+        and clears `exc_text`, making exception info inaccessible to downstream
+        formatters. Format `exc_info` into `exc_text` and only clear the tuple
+        (which holds frame references and is unpicklable).
+
+        Reference:
+            `https://github.com/python/cpython/issues/107801`
+        """
+        if record.exc_info:
+            record.exc_text = "".join(
+                traceback.format_exception(*record.exc_info),
+            ).rstrip("\n")
+        record.exc_info = None
+        return record

amox/logging_.py

@@ -0,0 +1,145 @@
+"""Core logging APIs."""
+
+import copy
+import functools
+import json
+import logging
+import logging.config
+import pathlib
+import types
+import typing as t
+
+from amox.formatters import AmoxFormatter, create_formatter
+from amox.types_ import (
+    DictConfig,
+    FormatterOptions,
+    LogFormat,
+    LoggerConfig,
+    LogLevel,
+    SetupOptions,
+)
+
+LIB = f"{__package__}"
+"""
+Library name, reference for `dictConfig`'s custom objects.
+"""
+
+DEFAULT_EXISTING_LOGGER_LEVEL: LogLevel = "WARNING"
+"""
+Default log level on setup when viewing logs of third party packages.
+"""
+
+
+def setup(**opts: t.Unpack[SetupOptions]) -> None:
+    """
+    Configure the root logger with amox's structured formatters.
+
+    Installs a `StreamHandler` (optionally wrapped in a `QueueHandler`) on the root
+    logger. All loggers in the process inherit the handler and emit structured output.
+
+    The root logger level defaults to `INFO`. When `name` is provided, the named
+    logger is set to `DEBUG`: giving clients full verbosity while third-party libraries
+    stay at `INFO`, overridable via `loggers`.
+    """
+    if has_handler():
+        return
+
+    cfg = config()
+
+    # forward formatter opts into the factory config
+    formatter_cfg: dict[str, object] = cfg["formatters"][LIB]  # ty: ignore[invalid-assignment]  # pyright: ignore[reportAssignmentType, reportTypedDictNotRequiredAccess]
+    for key in set(opts) & AmoxFormatter.configurable:
+        formatter_cfg[key] = opts[key]
+
+    # override format if explicitly passed (bypass env/factory)
+    if fmt := opts.get("format"):
+        formatter_cfg["format"] = fmt
+
+    # tz is non-serializable; use dictConfig's "." protocol for post-construction attr
+    # setting
+    if tz := opts.get("tz"):
+        formatter_cfg["."] = {"tz": tz}
+
+    use_queue = opts.get("queue", True)
+    if not use_queue:
+        _ = cfg["handlers"].pop(f"{LIB}.queue_handler")  # type: ignore[misc]
+        cfg["root"] = {"handlers": [LIB], "level": "INFO"}
+
+    # app namespace: promote to DEBUG while root stays at INFO
+    if name := opts.get("name"):
+        loggers_section: dict[str, LoggerConfig] = cfg.get("loggers", {})  # type: ignore[assignment]
+        loggers_section[name] = {"level": "DEBUG"}
+        cfg["loggers"] = loggers_section
+
+    # logger level overrides
+    loggers_section = cfg.get("loggers", {})  # type: ignore[assignment]
+
+    for entry in opts.get("loggers", []):
+        if isinstance(entry, (str, types.ModuleType)):
+            entry_name = (
+                entry.__name__ if isinstance(entry, types.ModuleType) else entry
+            )
+            loggers_section[entry_name] = {"level": DEFAULT_EXISTING_LOGGER_LEVEL}
+        else:
+            mod = entry["module"]
+            entry_name = mod.__name__ if isinstance(mod, types.ModuleType) else mod
+            loggers_section[entry_name] = {"level": entry["level"]}
+    if loggers_section:
+        cfg["loggers"] = loggers_section
+
+    logging.config.dictConfig(cfg)  # ty: ignore[invalid-argument-type]  # pyright: ignore[reportArgumentType]
+    return
+
+
+def config() -> DictConfig:
+    """Return amox's `dictConfig` mapping."""
+    return copy.deepcopy(read_config())
+
+
+def get_logger(
+    name: str | None = None,
+    *,
+    level: LogLevel | int = logging.DEBUG,
+    log_format: LogFormat | None = None,
+    handlers: list[logging.Handler] | None = None,
+    **opts: t.Unpack[FormatterOptions],
+) -> logging.Logger:
+    """
+    Return a logger with amox's structured formatting attached.
+
+    Creates a `StreamHandler` with a amox formatter on the named logger.
+    """
+    logger = logging.getLogger(name)
+
+    # early exit on scenarios that did a `setup()` call
+    if has_handler():
+        return logger
+
+    # local logger
+    if not logger.handlers:
+        stream = logging.StreamHandler()
+        stream.setFormatter(create_formatter(log_format, **opts))  # ty: ignore[no-matching-overload]
+        logger.addHandler(stream)
+        for h in handlers or []:
+            logger.addHandler(h)
+        logger.setLevel(level)
+
+    return logger
+
+
+def has_handler(name: str = LIB) -> bool:
+    """
+    Whether any handler on the root logger is named after a giving name.
+
+    `dictConfig` sets `handler.name` to the dict key, so handlers installed via
+    `setup()` will have names starting with the package name.
+    """
+    return any(h.name and h.name.startswith(name) for h in logging.getLogger().handlers)
+
+
+@functools.cache
+def read_config() -> DictConfig:
+    """Load and cache the bundled dictConfig JSON file."""
+    config_file = pathlib.Path(__file__).parent / "dictConfig.json"
+    with open(config_file) as f:  # noqa: PTH123
+        return json.load(f)