amox 0.0.1__tar.gz

amox-0.0.1/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: amox
+Version: 0.0.1
+Summary: Schema on read based logging
+Keywords: json,logfmt,logging,structured-logging
+Author: Kevin Montoya
+Author-email: Kevin Montoya <me@kmontocam.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Issues, https://github.com/kmontocam/amox/issues
+Project-URL: Repository, https://github.com/kmontocam/amox
+Description-Content-Type: text/markdown
+
+# amox

amox-0.0.1/README.md

@@ -0,0 +1 @@
+# amox

amox-0.0.1/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+authors = [{ name = "Kevin Montoya", email = "me@kmontocam.com" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Logging",
+  "Typing :: Typed",
+]
+dependencies = []
+description = "Schema on read based logging"
+keywords = ["json", "logfmt", "logging", "structured-logging"]
+license = "MIT"
+name = "amox"
+readme = "README.md"
+requires-python = ">=3.12"
+version = "0.0.1"
+
+  [project.urls]
+  Issues     = "https://github.com/kmontocam/amox/issues"
+  Repository = "https://github.com/kmontocam/amox"
+
+[build-system]
+build-backend = "uv_build"
+requires      = ["uv_build>=0.11.14,<0.12.0"]
+
+[dependency-groups]
+dev = [
+  "jsonschema==4.26.0",
+  "mbake==1.4.6",
+  "pre-commit==4.6.0",
+  "pytest==9.0.3",
+  "pyyaml==6.0.3",
+  "ruff==0.15.14",
+  "taplo==0.9.3",
+  "ty==0.0.38",
+  "uvicorn==0.47.0",
+]
+
+[tool.pytest.ini_options]
+addopts = ["-p", "no:logging"]
+markers = [
+  "functional: subprocess-based full API tests",
+  "integration: tests with third-party dependencies",
+]
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length    = 88
+target-version = "py312"
+
+  [tool.ruff.lint]
+  ignore = ["COM812", "D203", "D212"]
+  select = ["ALL"]
+
+    [tool.ruff.lint.per-file-ignores]
+    "tests/**/*.py" = ["FBT001", "S101"]
+
+  [tool.ruff.format]
+  docstring-code-format = true
+  quote-style           = "double"
+
+[tool.pyright]
+reportAny = false

amox-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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