without-logging 0.0.0__tar.gz → 0.0.2__tar.gz

without_logging-0.0.2/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: without-logging
+Version: 0.0.2
+Summary: A without pipeline for logs: stdlib log records parsed into immutable values, filtered and enriched as processors, drained to a sink.
+Author: Josh Karpel
+Author-email: Josh Karpel <josh.karpel@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Dist: without-core==0.0.2
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# without-logging
+
+A `without` pipeline for logs. Logger calls (yours and every third-party
+library's) ultimately produce a stream of records; this package parses each one
+into an immutable `Record` value, lets you filter and enrich them as ordinary
+processors, and drains the result into a sink you own.
+
+The two stdlib logging pain points it targets: the impenetrable, mutable,
+noun-heavy configuration, and the monolithic handlers that bundle unrelated
+decisions (when to flush, how to rotate, how to format) into one object. Here a
+record is a value, each stage is a `Processor`, and the sink is whatever you
+compose.
+
+```python
+import logging
+
+from without import compose, from_selector, from_sink
+from without_logging import Level, at_least, capture
+
+
+async def write(record):
+    print(f"{record.timestamp:%H:%M:%S} {record.level_name} {record.message}")
+
+
+pipeline = compose(from_selector(at_least(Level.WARNING)), from_sink(write))
+
+async with capture(pipeline):          # attaches to the root logger for the block
+    logging.getLogger("app").warning("disk almost full", extra={"free_pct": 3})
+```
+
+`capture` is the one impure piece: it activates a handler on the root logger,
+turns the pushed records into a `Stream`, and runs your pipeline against them for
+the life of the block. Everything upstream of the sink is pure and testable
+without touching the logging machinery.
+
+To write to a file without paying a thread hop per line, `offload` runs a blocking
+writer on a single dedicated thread, fed by a queue that delivers items in bursts
+(so the writer flushes when it catches up, no flush-frequency knob). Writers are
+named by destination: `to_rotating_file` writes to a file (owning the byte count and
+clock, rotating on any combination of size (`max_bytes`), a relative interval
+(`max_age`), and absolute wall-clock boundaries (`schedule=at_times(...)`)), and
+`to_stream` writes to a caller-owned text stream (`sys.stderr`, a socket) without
+closing it. Both take strings (render a `Record` to text with a `from_map` in front):
+
+```python
+from datetime import timedelta
+
+from without import compose, from_map, from_selector
+from without_logging import Level, at_least, offload, to_rotating_file
+
+writer = to_rotating_file(lambda i, when: directory / f"app.{i}.log", max_bytes=64 << 20, max_age=timedelta(hours=1))
+async with offload(writer) as sink:
+    lines = compose(from_map(render), sink)   # Record -> str -> file
+    async with capture(compose(from_selector(at_least(Level.WARNING)), lines)):
+        ...  # WARNING+ records written off the event loop, rotated by size and time
+```
+
+See the
+[`without-logging` guide](https://without.help/without-logging/)
+(with the [API reference](https://without.help/reference/without_logging/))
+for the design narrative: why stdlib becomes a one-way source, why filtering is
+just the core `from_selector` builder, and where fan-out to multiple sinks slots
+in.

without_logging-0.0.2/README.md

@@ -0,0 +1,63 @@
+# without-logging
+
+A `without` pipeline for logs. Logger calls (yours and every third-party
+library's) ultimately produce a stream of records; this package parses each one
+into an immutable `Record` value, lets you filter and enrich them as ordinary
+processors, and drains the result into a sink you own.
+
+The two stdlib logging pain points it targets: the impenetrable, mutable,
+noun-heavy configuration, and the monolithic handlers that bundle unrelated
+decisions (when to flush, how to rotate, how to format) into one object. Here a
+record is a value, each stage is a `Processor`, and the sink is whatever you
+compose.
+
+```python
+import logging
+
+from without import compose, from_selector, from_sink
+from without_logging import Level, at_least, capture
+
+
+async def write(record):
+    print(f"{record.timestamp:%H:%M:%S} {record.level_name} {record.message}")
+
+
+pipeline = compose(from_selector(at_least(Level.WARNING)), from_sink(write))
+
+async with capture(pipeline):          # attaches to the root logger for the block
+    logging.getLogger("app").warning("disk almost full", extra={"free_pct": 3})
+```
+
+`capture` is the one impure piece: it activates a handler on the root logger,
+turns the pushed records into a `Stream`, and runs your pipeline against them for
+the life of the block. Everything upstream of the sink is pure and testable
+without touching the logging machinery.
+
+To write to a file without paying a thread hop per line, `offload` runs a blocking
+writer on a single dedicated thread, fed by a queue that delivers items in bursts
+(so the writer flushes when it catches up, no flush-frequency knob). Writers are
+named by destination: `to_rotating_file` writes to a file (owning the byte count and
+clock, rotating on any combination of size (`max_bytes`), a relative interval
+(`max_age`), and absolute wall-clock boundaries (`schedule=at_times(...)`)), and
+`to_stream` writes to a caller-owned text stream (`sys.stderr`, a socket) without
+closing it. Both take strings (render a `Record` to text with a `from_map` in front):
+
+```python
+from datetime import timedelta
+
+from without import compose, from_map, from_selector
+from without_logging import Level, at_least, offload, to_rotating_file
+
+writer = to_rotating_file(lambda i, when: directory / f"app.{i}.log", max_bytes=64 << 20, max_age=timedelta(hours=1))
+async with offload(writer) as sink:
+    lines = compose(from_map(render), sink)   # Record -> str -> file
+    async with capture(compose(from_selector(at_least(Level.WARNING)), lines)):
+        ...  # WARNING+ records written off the event loop, rotated by size and time
+```
+
+See the
+[`without-logging` guide](https://without.help/without-logging/)
+(with the [API reference](https://without.help/reference/without_logging/))
+for the design narrative: why stdlib becomes a one-way source, why filtering is
+just the core `from_selector` builder, and where fan-out to multiple sinks slots
+in.

without_logging-0.0.2/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "without-logging"
+version = "0.0.2"
+description = "A without pipeline for logs: stdlib log records parsed into immutable values, filtered and enriched as processors, drained to a sink."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Logging",
+    "Typing :: Typed",
+]
+dependencies = ["without-core==0.0.2"]
+
+[[project.authors]]
+name = "Josh Karpel"
+email = "josh.karpel@gmail.com"
+
+[tool.uv.sources.without-core]
+workspace = true

without_logging-0.0.2/pyproject.toml.orig

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "without-logging"
+version = "0.0.2"
+description = "A without pipeline for logs: stdlib log records parsed into immutable values, filtered and enriched as processors, drained to a sink."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Josh Karpel", email = "josh.karpel@gmail.com" },
+]
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Logging",
+    "Typing :: Typed",
+]
+dependencies = [
+    "without-core==0.0.2",
+]
+
+[tool.uv.sources]
+without-core = { workspace = true }

without_logging-0.0.2/src/without_logging/__init__.py

@@ -0,0 +1,39 @@
+from without_logging.capture import CaptureHandler
+from without_logging.capture import capture
+from without_logging.context import bind
+from without_logging.context import merge_context
+from without_logging.processors import add_fields
+from without_logging.processors import at_least
+from without_logging.record import Level
+from without_logging.record import Record
+from without_logging.record import parse_record
+from without_logging.renderers import exception_to_dict
+from without_logging.renderers import exception_to_text
+from without_logging.renderers import iso_timestamp
+from without_logging.renderers import render_console
+from without_logging.renderers import render_json
+from without_logging.sinks import at_times
+from without_logging.sinks import offload
+from without_logging.sinks import to_rotating_file
+from without_logging.sinks import to_stream
+
+__all__ = [
+    "CaptureHandler",
+    "Level",
+    "Record",
+    "add_fields",
+    "at_least",
+    "at_times",
+    "bind",
+    "capture",
+    "exception_to_dict",
+    "exception_to_text",
+    "iso_timestamp",
+    "merge_context",
+    "offload",
+    "parse_record",
+    "render_console",
+    "render_json",
+    "to_rotating_file",
+    "to_stream",
+]

without_logging-0.0.2/src/without_logging/capture.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from collections.abc import AsyncIterator
+from collections.abc import Callable
+from contextlib import asynccontextmanager
+
+from without.interfaces import Sink
+from without.wiring import stream_from_queue
+
+from without_logging.context import merge_context
+from without_logging.record import Record
+from without_logging.record import parse_record
+
+
+def parse_with_bound_context(log_record: logging.LogRecord) -> Record:
+    """`capture`'s default parser: `parse_record`, then `merge_context` folds in any bound context."""
+    return merge_context(parse_record(log_record))
+
+
+class CaptureHandler(logging.Handler):
+    """
+    A stdlib handler that parses each `LogRecord` and offers it to an asyncio queue.
+
+    This is the one-way bridge at the ingestion edge. Stdlib `logging` is the
+    de-facto narrow waist every third-party library already writes to, so making
+    it a *source* (rather than fighting it) is the whole trick: a pushed
+    `LogRecord` is parsed to a `Record` here and dropped onto the queue that
+    `stream_from_queue` turns into the pull-based stream the pipeline consumes.
+    Control only ever flows outward from stdlib into `without`, never back.
+
+    A log call MAY happen off the event loop thread, so the parsed value is handed
+    to the loop with `call_soon_threadsafe`, which writes the loop's self-pipe to
+    wake it. A log call *on* the loop thread (an async handler logging) does not
+    need that wakeup, so those take the cheaper `call_soon`; the construction thread
+    is the loop thread (`capture` builds this right after `get_running_loop`), so its
+    id captured here identifies loop-thread emits. The queue is bounded, so a burst that
+    outruns the sink is dropped rather than growing memory without limit;
+    `dropped` counts how many so an operator can see it. The overflow policy is a
+    boundary decision the app owns: raise `capacity`, or pass `capacity=None` for
+    an unbounded queue that never drops (at the cost of the bound).
+    """
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        queue: asyncio.Queue[Record],
+        parse: Callable[[logging.LogRecord], Record],
+    ) -> None:
+        super().__init__()
+        self._loop = loop
+        self._loop_thread_id = threading.get_ident()
+        self._queue = queue
+        self._parse = parse
+        self.dropped = 0
+
+    def emit(self, log_record: logging.LogRecord) -> None:
+        record = self._parse(log_record)
+        if threading.get_ident() == self._loop_thread_id:
+            self._loop.call_soon(self._offer, record)
+        else:
+            self._loop.call_soon_threadsafe(self._offer, record)
+
+    def _offer(self, record: Record) -> None:
+        try:
+            self._queue.put_nowait(record)
+        except asyncio.QueueFull, asyncio.QueueShutDown:
+            self.dropped += 1
+
+
+@asynccontextmanager
+async def capture(
+    sink: Sink[Record],
+    *,
+    logger: logging.Logger | None = None,
+    level: int = logging.INFO,
+    capacity: int | None = 1024,
+    parse: Callable[[logging.LogRecord], Record] = parse_with_bound_context,
+) -> AsyncIterator[CaptureHandler]:
+    """
+    Capture stdlib log records into `sink` for the duration of the block.
+
+    The imperative shell of the pipeline, and the only impure piece: it attaches a
+    `CaptureHandler` to `logger` (the root logger by default, so third-party logs
+    are captured too), runs `sink(stream_from_queue(queue))` in a background task,
+    and on exit detaches, flushes pending records, shuts the queue so the stream
+    ends gracefully, and joins the task. `sink` is a fully wired pipeline, e.g.
+    `compose(from_selector(at_least(Level.WARNING)), from_sink(write))`;
+    everything upstream of the queue in it is pure and testable on its own.
+
+    `level` sets the capture threshold. stdlib applies *two* gates: the origin
+    logger's effective level (checked where a record is created, and defaulting to
+    WARNING on the root, which is what usually swallows INFO) and each handler's
+    own level. The logger gate is the load-bearing one: a sub-threshold record is
+    dropped at creation before any handler runs, so setting the handler level
+    alone would capture nothing new. So this temporarily lowers `logger`'s level
+    to `level` (restoring it on exit, scoped to the block) *and* sets the handler
+    to `level`, the latter keeping the threshold exact for records that propagate
+    up from a descendant logger pinned to its own lower level.
+
+    `parse` is the enrichment of the *emit phase*, the first of the pipeline's two
+    phases split by the queue: it turns each `LogRecord` into a `Record`
+    *synchronously* in the handler's `emit`, on the logging call's own task
+    (stdlib's shape), where the *sink phase* (`sink`, async, draining the queue) has
+    not yet begun. It defaults to `parse_with_bound_context` (`parse_record` then
+    `merge_context`), so any fields bound with `bind` are stamped on here, where
+    they are still live (the sink phase has left the caller's context). A custom
+    parser composes `merge_context` the same way, `merge_context(my_parse(log_record))`,
+    to keep binds, or omits it to opt out.
+
+    The handler itself is yielded so a caller can read `handler.dropped` after
+    the block to see how many records overflowed the queue.
+    """
+    target = logger if logger is not None else logging.getLogger()
+    loop = asyncio.get_running_loop()
+    queue: asyncio.Queue[Record] = asyncio.Queue(capacity if capacity is not None else 0)
+    handler = CaptureHandler(loop, queue, parse)
+    handler.setLevel(level)
+
+    async def run_sink() -> None:
+        await sink(stream_from_queue(queue))
+
+    previous_level = target.level
+    target.setLevel(level)
+    target.addHandler(handler)
+    drain = asyncio.create_task(run_sink())
+    try:
+        yield handler
+    finally:
+        target.removeHandler(handler)
+        target.setLevel(previous_level)
+        await asyncio.sleep(0)  # let already-scheduled emits reach the queue before it shuts
+        queue.shutdown()
+        await drain

without_logging-0.0.2/src/without_logging/context.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from collections.abc import Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from types import MappingProxyType
+
+from without_logging.record import Record
+
+_bound: ContextVar[Mapping[str, object]] = ContextVar("without_logging_bound_context", default=MappingProxyType({}))
+
+
+@contextmanager
+def bind(**fields: object) -> Iterator[None]:
+    """
+    Bind `fields` onto every record logged within this block, on this task.
+
+    The call-site half of structured context, the equivalent of structlog's
+    `bind_contextvars`: `with bind(request_id=...)` stamps those fields onto every
+    record logged inside the block. Scoping is explicit and lexical: the fields
+    are in effect for the block and gone after it, leaving no shared place
+    mutated. It writes a task-local `ContextVar`, so concurrent tasks each see
+    only their own binds, and nested binds accumulate (an inner `bind` merges onto
+    the outer and is undone on exit; a key set by both takes the inner value
+    inside the inner block).
+
+    Binding alone does nothing until the `capture` side reads it: pair this with
+    `merge_context`, which merges the bound fields onto each record at the parse
+    edge, where they are still live (the handler's `emit` runs synchronously on
+    the logging call's task). A downstream processor cannot read them, having left
+    the caller's context for the sink task.
+    """
+    merged = MappingProxyType({**_bound.get(), **fields})
+    token = _bound.set(merged)
+    try:
+        yield
+    finally:
+        _bound.reset(token)
+
+
+def merge_context(record: Record) -> Record:
+    """
+    Merge the context bound by `bind` onto a record: the read half of call-site context.
+
+    A `Record -> Record` enrichment, *composed on top of* a parser rather than
+    wrapping it: `capture`'s default parser applies it after `parse_record`, and a
+    custom parser composes it the same way,
+    `merge_context(parse_record(log_record))`. A field the log call set explicitly
+    via `extra=` wins over a bound field of the same name (the more specific
+    value), so `bind` supplies defaults, never overrides a per-call value.
+
+    It reads the task-local `ContextVar` that `bind` writes, so it MUST run at the
+    parse edge, in the handler's `emit` on the caller's task, not as a pipeline
+    `Processor`: the pipeline runs in the sink task, having left that context,
+    where the bind would read as empty.
+    """
+    bound = _bound.get()
+    if not bound:
+        return record
+    return record.with_fields(**{key: value for key, value in bound.items() if key not in record.fields})

without_logging-0.0.2/src/without_logging/processors.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from collections.abc import Callable
+
+from without.interfaces import Processor
+from without.interfaces import from_map
+
+from without_logging.record import Record
+
+
+def at_least(level: int) -> Callable[[Record], Awaitable[bool]]:
+    """
+    A predicate matching records at `level` or more severe: the level threshold.
+
+    Pair it with the core `from_selector` to keep only those records (or
+    `from_filter` to drop them). It is `async` to match the one color of
+    predicate `from_selector`/`from_filter` expect, though the decision itself
+    just compares integers. Because a `Record.level` is a plain `int`, a `Level`
+    member reads naturally as the argument (`at_least(Level.WARNING)`), but any
+    numeric level works.
+    """
+
+    async def is_severe_enough(record: Record) -> bool:
+        return record.level >= level
+
+    return is_severe_enough
+
+
+def add_fields(**fields: object) -> Processor[Record, Record]:
+    """
+    A processor that merges static `fields` onto every record: enrichment.
+
+    Enrichment *is* expressible as a `from_map` (one record in, one enriched
+    record out), so it uses the core builder directly. Enriching from a *shared
+    behavior* (a value the whole pipeline sees the latest of: the current config
+    revision, a sampling rate) is the same shape, reading it via `current()`
+    inside the step. Per-call-site context (a request or trace id, which is
+    task-local) is *not* recoverable here: the pipeline runs in the sink task,
+    having left the caller's context. Bind it at the edge instead with
+    `bind`/`merge_context`, which read it while `emit` is still on the caller's
+    task (see the guide).
+    """
+
+    async def enrich(record: Record) -> Record:
+        return record.with_fields(**fields)
+
+    return from_map(enrich)

without_logging-0.0.2/src/without_logging/record.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass
+from dataclasses import replace
+from datetime import UTC
+from datetime import datetime
+from enum import IntEnum
+from traceback import TracebackException
+from types import MappingProxyType
+
+
+class Level(IntEnum):
+    """
+    The five standard severities as an ordered value, for writing filters.
+
+    Members are the stdlib numeric levels, so a `Record.level` (a plain `int`)
+    can be compared straight against them: `record.level >= Level.WARNING`.
+    Keeping `Record.level` an `int` rather than this enum is deliberate: a
+    third-party library that logs at a non-standard numeric level is carried
+    through as that number, not rejected, so the enum is a vocabulary for
+    predicates rather than a closed set the record must belong to.
+    """
+
+    DEBUG = logging.DEBUG
+    INFO = logging.INFO
+    WARNING = logging.WARNING
+    ERROR = logging.ERROR
+    CRITICAL = logging.CRITICAL
+
+
+# The attributes stdlib's LogRecord factory sets. Anything on a record outside
+# this set arrived via `extra=` (or was set by a filter) and is structured data,
+# so it becomes a Record field. The names here split two ways: the caller-supplied
+# content of the log call (`msg`/`args`, `levelno`, `name`, `exc_info`, `created`)
+# is lifted into typed fields, and the rest is factory-synthesized ambient metadata
+# (source location `pathname`/`lineno`/`funcName`; `thread`/`process`/`taskName`)
+# that is deliberately dropped: it is gated by module flags (`logThreads`,
+# `logProcesses`, `logAsyncioTasks`) and a swappable factory, so it may be `None` or
+# absent, and it exists for stdlib's formatter `%(...)s` placeholders rather than as
+# a stable per-event guarantee. A caller who wants some of it lifts it into `fields`
+# with a custom `parse=` on `capture`.
+RESERVED: frozenset[str] = frozenset(
+    {
+        "name",
+        "msg",
+        "args",
+        "levelname",
+        "levelno",
+        "pathname",
+        "filename",
+        "module",
+        "exc_info",
+        "exc_text",
+        "stack_info",
+        "lineno",
+        "funcName",
+        "created",
+        "msecs",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "processName",
+        "process",
+        "taskName",
+        "message",
+        "asctime",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Record:
+    """
+    One log event as an immutable value, parsed from a stdlib `LogRecord`.
+
+    Where a `LogRecord` is a mutable bag that formatters and filters rewrite in
+    place, a `Record` is a value: it always means the same thing, so it can be
+    filtered, enriched, fanned out, and sunk without any stage disturbing
+    another's copy. Enrichment returns a *new* record (`with_fields`) rather than
+    mutating this one. `fields` is the record's structured data, exposed read-only:
+    *seeded* from the log call's `extra=` at the parse edge, then *grown* by
+    enrichment (`add_fields`, a `bind` merged by `merge_context`, any `with_fields`).
+    It is named for what it holds, not for `extra=` alone, because those later
+    sources write here too. `exception` is a `TracebackException` captured at the
+    ingestion edge (`None` when the event carried none): a *structured* value,
+    not a rendered string, so how the traceback is formatted stays a downstream
+    boundary the app owns (`"".join(exc.format())` for the stdlib text, or walk
+    `exc.stack` for JSON frames), the same way rendering the record itself is.
+    Extracting it drops all references to the live frames, so the record stays a
+    self-contained value with no traceback pinned to it.
+    """
+
+    timestamp: datetime
+    level: int
+    logger: str
+    message: str
+    exception: TracebackException | None
+    fields: Mapping[str, object]
+
+    @property
+    def level_name(self) -> str:
+        return logging.getLevelName(self.level)
+
+    def with_fields(self, **fields: object) -> Record:
+        """Return a copy of this record with `fields` merged onto its own."""
+        return replace(self, fields=MappingProxyType({**self.fields, **fields}))
+
+
+def extract_exception(log_record: logging.LogRecord) -> TracebackException | None:
+    """
+    Capture a `LogRecord`'s exception as a structured value, or `None` when it carries none.
+
+    A live traceback is a *place*, not a value: it pins its frames and their
+    locals in memory, is mutable, and cannot ride the queue to another thread
+    safely (stdlib's own `QueueHandler` flattens it to a string for exactly this
+    reason). So the exception is turned into a value at the ingestion edge, while
+    it is still live, the same way `getMessage()` resolves the message. Unlike the
+    message, which has one sensible rendering, a traceback has many (locals,
+    chaining, style), so this keeps the *structure* rather than pre-rendering:
+    `TracebackException.from_exception` extracts frame summaries and drops all
+    references to the live frames, leaving a value the app can format however it
+    likes downstream (`format` for stdlib text, `stack` for JSON frames).
+    """
+    if log_record.exc_info:
+        _, exc_value, _ = log_record.exc_info
+        if exc_value is not None:
+            return TracebackException.from_exception(exc_value)
+    return None
+
+
+def parse_record(log_record: logging.LogRecord) -> Record:
+    """
+    Parse a mutable stdlib `LogRecord` into an immutable `Record` value.
+
+    The ingestion boundary: this is where a pushed `LogRecord`, from the app's
+    own calls or any third-party library's, becomes the typed value the rest of
+    the pipeline works with. It is a pure function (`LogRecord -> Record`), so the
+    whole translation is testable without touching the logging machinery. The
+    structured `fields` are every attribute on the record outside the standard
+    envelope (`RESERVED`), which is exactly what `logging`'s `extra=` merges in;
+    the message is rendered and any exception is captured as a structured value
+    here (see `extract_exception`) so nothing live is carried past this point.
+    """
+    fields = {key: value for key, value in log_record.__dict__.items() if key not in RESERVED}
+    return Record(
+        timestamp=datetime.fromtimestamp(log_record.created, tz=UTC),
+        level=log_record.levelno,
+        logger=log_record.name,
+        message=log_record.getMessage(),
+        exception=extract_exception(log_record),
+        fields=MappingProxyType(fields),
+    )

without_logging-0.0.2/src/without_logging/renderers.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from datetime import datetime
+from traceback import TracebackException
+
+from without.interfaces import Processor
+from without.interfaces import from_map
+
+from without_logging.record import Record
+
+
+def exception_to_dict(exception: TracebackException) -> dict[str, object]:
+    """
+    Convert a captured `TracebackException` into a JSON-serializable dict: structured traceback.
+
+    Each frame becomes `{file, line, function, code}` (from the extracted
+    `FrameSummary` values, no live frames), and a chained exception is nested under
+    `cause`, following Python's own rule: an explicit `raise ... from` (`__cause__`)
+    takes precedence, else the implicit `__context__` unless it was suppressed. This
+    is the read half `render_json` uses, exposed so a custom JSON renderer can reuse
+    it.
+    """
+    cause: dict[str, object] | None = None
+    if exception.__cause__ is not None:
+        cause = exception_to_dict(exception.__cause__)
+    elif exception.__context__ is not None and not exception.__suppress_context__:
+        cause = exception_to_dict(exception.__context__)
+    result: dict[str, object] = {
+        "type": exception.exc_type_str,
+        "message": "".join(exception.format_exception_only()).strip(),
+        "frames": [
+            {"file": frame.filename, "line": frame.lineno, "function": frame.name, "code": frame.line}
+            for frame in exception.stack
+        ],
+    }
+    if cause is not None:
+        result["cause"] = cause
+    return result
+
+
+def exception_to_text(exception: TracebackException) -> str:
+    """
+    Render a captured `TracebackException` to its full traceback text.
+
+    stdlib's own multi-line rendering (`format`), chained cause/context and all,
+    as a single string. The flat-string alternative to the structured
+    `exception_to_dict` when encoding a record's exception, and what
+    `render_console` uses.
+    """
+    return "".join(exception.format()).rstrip("\n")
+
+
+def iso_timestamp(when: datetime) -> str:
+    """The default timestamp format for the renderers: ISO 8601 (`datetime.isoformat`)."""
+    return when.isoformat()
+
+
+def render_json(
+    *,
+    timestamp: Callable[[datetime], object] = iso_timestamp,
+    exception: Callable[[TracebackException], object] = exception_to_dict,
+) -> Processor[Record, str]:
+    """
+    A `Record -> str` renderer emitting one JSON object per record: structured logging.
+
+    The envelope (`timestamp` ISO-8601, `level`, `logger`, `message`) and every
+    field flat at the top level, so a log aggregator can index them directly; the
+    envelope wins a name clash, so a field cannot shadow `level` or `message`.
+
+    `timestamp` chooses how the time is encoded (default `iso_timestamp`; pass, say,
+    a `lambda when: when.timestamp()` for an epoch number). `exception` chooses how a
+    traceback is encoded: `exception_to_dict` (default, structured frames, stays
+    queryable) or `exception_to_text` (the flat traceback string), or any
+    `TracebackException -> <json value>` of your own. A
+    non-serializable *field* value is coerced with `str` (`default=str`): the log
+    JSON is machine-consumed, so a clean indexable value beats a Python `repr`, and
+    `str` still falls back to the `repr` form for an object without its own
+    `__str__` (`render_console` uses `repr`, matching its human-scanning medium). A
+    stray value therefore never tears down the log pipeline.
+
+    Optional and opt-in: the core ships no mandatory formatter (encoding is the app's
+    boundary), so compose this before a string sink yourself, e.g.
+    `compose(render_json(), offload(to_stream(sys.stdout)))`.
+    """
+
+    async def render(record: Record) -> str:
+        payload: dict[str, object] = {
+            "timestamp": timestamp(record.timestamp),
+            "level": record.level_name,
+            "logger": record.logger,
+            "message": record.message,
+        }
+        for key, value in record.fields.items():
+            payload.setdefault(key, value)
+        if record.exception is not None:
+            payload["exception"] = exception(record.exception)
+        return json.dumps(payload, default=str)
+
+    return from_map(render)
+
+
+def render_console(
+    *,
+    timestamp: Callable[[datetime], str] = iso_timestamp,
+) -> Processor[Record, str]:
+    """
+    A `Record -> str` renderer emitting one human-readable line per record.
+
+    `TIMESTAMP LEVEL logger "message" {key=value, ...}`: the message is quoted and
+    the fields grouped in braces (each value `repr`'d), so the free-text message and
+    the structured fields never blur into each other or the leading metadata. The
+    message is quoted with `json.dumps` and each field value is `repr`'d, so a control
+    character in either (a newline from a decoded request path, say) is escaped rather
+    than forging a new log line. The braces are omitted when there are no
+    fields. An exception is appended as its full traceback text (`exception_to_text`,
+    cause chain and all), indented, on following lines. `timestamp` chooses the time
+    format (default `iso_timestamp`). No coloring: wrap the line, or write your own
+    `from_map(Record -> str)`, if you want ANSI.
+
+    Optional and opt-in, like `render_json`: `compose(render_console(),
+    offload(to_stream(sys.stderr)))`.
+    """
+
+    async def render(record: Record) -> str:
+        quoted = json.dumps(record.message, ensure_ascii=False)  # pragma: no mutate - None acts as False here
+        parts = [
+            timestamp(record.timestamp),
+            record.level_name,
+            record.logger,
+            quoted,
+        ]
+        if record.fields:
+            fields = ", ".join(f"{key}={value!r}" for key, value in record.fields.items())
+            parts.append("{" + fields + "}")
+        summary = " ".join(parts)
+        if record.exception is None:
+            return summary
+        body = "\n".join(f"  {line}" if line else "" for line in exception_to_text(record.exception).splitlines())
+        return f"{summary}\n{body}"
+
+    return from_map(render)

without_logging-0.0.2/src/without_logging/sinks.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import queue
+from collections.abc import AsyncIterator
+from collections.abc import Callable
+from collections.abc import Iterator
+from contextlib import asynccontextmanager
+from datetime import UTC
+from datetime import datetime
+from datetime import time
+from datetime import timedelta
+from datetime import tzinfo
+from pathlib import Path
+from typing import TextIO
+
+from without.interfaces import Sink
+from without.interfaces import Stream
+
+
+@asynccontextmanager
+async def offload[T](work: Callable[[Iterator[list[T]]], None]) -> AsyncIterator[Sink[T]]:
+    """
+    Run a blocking `work` on a dedicated thread, fed by the yielded async `Sink`.
+
+    The point is efficient blocking I/O under heavy logging. An async file library
+    (`aiofiles`, `anyio`) hops to a worker thread *per operation*, so a busy log
+    stream pays that round-trip on every write. Here a single long-lived thread
+    owns the resource and does *all* the I/O: `work` is plain blocking Python that
+    consumes the items, and the yielded `Sink` just drops each onto a thread-safe
+    queue the worker drains. No per-item thread hop, and the "processor body" stays
+    ordinary synchronous code.
+
+    Items arrive in *bursts*: each element of the iterator is everything available
+    on the queue at that instant (at least one item, blocking for the first). A
+    burst boundary is therefore exactly the moment the worker has caught up, which
+    is where a writer flushes: under load bursts are large and flushes are few, and
+    when idle each burst is a single item flushed at once. So durability needs no
+    flush-frequency knob; it falls out of the queue's own backlog.
+
+    Lifecycle is bounded by the `with` block: the thread starts on entry, and on
+    exit the queue is shut down so the worker drains what remains and then ends,
+    and the thread is joined (so a file is closed before the block returns). If
+    `work` raises, that surfaces when the block exits.
+
+    Nest this *outside* the consumer that drives the sink, so the worker outlives
+    the draining. With `capture`, that means `async with offload(...) as writer:`
+    around `async with capture(..., writer):`, not the other way round.
+
+    The queue is unbounded in this first cut: the async side never blocks or drops,
+    at the cost of growing memory if the worker cannot keep up with a sustained
+    burst (a stalled disk). A bounded, drop-counting variant is a deliberate
+    follow-up. The bidirectional case (a full `Processor` bridged onto a thread,
+    with an output queue as well) is intentionally out of scope; this covers the
+    terminal-sink need (writing) without that extra state.
+    """
+    items: queue.Queue[T] = queue.Queue()
+
+    def drain() -> Iterator[list[T]]:
+        while True:
+            try:
+                batch = [items.get()]
+            except queue.ShutDown:
+                return
+            # Take everything queued at this instant into the burst. No Empty to catch and no
+            # get_nowait-in-a-try for control flow: the worker is the queue's *only* consumer, so
+            # qsize() is an exact count of items still present to take (a producer may add more,
+            # which simply waits for the next burst; nobody else removes), and each get succeeds.
+            batch.extend(items.get_nowait() for _ in range(items.qsize()))
+            yield batch
+
+    worker = asyncio.create_task(asyncio.to_thread(work, drain()))
+
+    async def sink(inputs: Stream[T]) -> None:
+        async for item in inputs:
+            items.put_nowait(item)
+
+    try:
+        yield sink
+    finally:
+        items.shutdown()
+        await worker
+
+
+def now_utc() -> datetime:
+    return datetime.now(UTC)
+
+
+def at_times(*times: time, tz: tzinfo = UTC) -> Callable[[datetime], datetime]:
+    """
+    A `schedule` for `to_rotating_file`: the next occurrence of any of these wall-clock times.
+
+    Given a moment, returns the soonest of `times` strictly after it, interpreted in
+    timezone `tz`. So `at_times(time(0, 0))` rotates daily at midnight `tz`, and
+    `at_times(time(0, 0), time(12, 0))` twice a day. The list of times is the
+    recurring cycle of rotation boundaries, resolved to a concrete datetime against
+    the *actual* current time each call, so nothing goes stale and a boundary missed
+    while idle collapses to a single rotation. Strictly-after (not at-or-after) is
+    what lets the writer advance past a boundary it just hit without looping on it.
+    """
+    if not times:
+        raise ValueError("at_times requires at least one time-of-day")
+    ordered = sorted(times)
+
+    def schedule(after: datetime) -> datetime:
+        local = after.astimezone(tz)
+        for moment in ordered:
+            candidate = datetime.combine(local.date(), moment, tzinfo=tz)
+            if candidate > local:
+                return candidate
+        return datetime.combine(local.date() + timedelta(days=1), ordered[0], tzinfo=tz)
+
+    return schedule
+
+
+def to_rotating_file(
+    name: Callable[[int, datetime], Path],
+    *,
+    max_bytes: int | None = None,
+    max_age: timedelta | None = None,
+    schedule: Callable[[datetime], datetime] | None = None,
+    now: Callable[[], datetime] = now_utc,
+) -> Callable[[Iterator[list[str]]], None]:
+    """
+    A blocking worker (for `offload`) that appends lines to a file, rotating by size and/or time.
+
+    Rotation lives in the worker deliberately: it is the one place with all the
+    information to decide, timed with its own writes. Size is a function of the
+    bytes written, so a size limit cannot be an independent, decoupled trigger; the
+    worker keeps an exact byte count (writing UTF-8 bytes directly) rather than
+    polling a lagging on-disk size, and reads the clock the same way. So `max_bytes`
+    (size), `max_age` (elapsed since the file opened, a *relative* interval),
+    `schedule` (the next *absolute* wall-clock boundary, e.g. midnight, via a
+    next-boundary function such as `at_times`), and any combination (rotate on
+    whichever trips first) all work here, which the stdlib's separate size and time
+    handlers cannot do at once. At least one policy is required: with no limit the
+    file would never rotate (an unbounded file), which is not the affordance the
+    name suggests, so that case raises `ValueError` rather than being silently
+    allowed.
+
+    `schedule(t)` returns the next rotation boundary strictly after `t`; the writer
+    samples it at each open and rotates once `now()` reaches it (missed boundaries
+    collapse to one rotation). It is the pure, thread-synchronous form of "a stream
+    of rotation datetimes": the worker already owns the clock, so it generates the
+    stream itself rather than sampling an async one.
+
+    `name` turns a rotation index and the rotation time into a path
+    (`lambda i, when: directory / f"app.{i}.log"`); index 0 is the initial file,
+    appended to if it already exists, and the time is that file's open time drawn
+    from the same injected clock, so timestamped names stay consistent with the
+    rotation decision. `now` is the clock, injected so time-based rotation is
+    deterministic under test. This writes strings
+    (render a `Record` to text in a `from_map` in front), owns the newline framing,
+    and flushes at each burst boundary. The rotation decision is made *before* each
+    write (so a size limit is not overshot, bar a single line larger than
+    `max_bytes`), and it is inlined and short-circuiting: `now()` is read only when a
+    size check has not already forced the rotation and an age limit is set.
+    """
+    if max_bytes is None and max_age is None and schedule is None:
+        raise ValueError("to_rotating_file needs at least one rotation policy: max_bytes, max_age, or schedule")
+
+    def next_boundary(opened: datetime) -> datetime | None:
+        return schedule(opened) if schedule is not None else None
+
+    def work(batches: Iterator[list[str]]) -> None:
+        index = 0
+        opened = now()
+        boundary = next_boundary(opened)
+        file = name(index, opened).open("ab")
+        written = file.seek(0, os.SEEK_END)
+        try:
+            for batch in batches:
+                for line in batch:
+                    data = f"{line}\n".encode()
+                    if written > 0 and (
+                        (max_bytes is not None and written + len(data) > max_bytes)
+                        or (max_age is not None and now() - opened >= max_age)
+                        or (boundary is not None and now() >= boundary)
+                    ):
+                        file.close()
+                        index += 1
+                        opened = now()
+                        boundary = next_boundary(opened)
+                        file = name(index, opened).open("ab")
+                        written = file.seek(0, os.SEEK_END)
+                    written += file.write(data)
+                file.flush()
+        finally:
+            file.close()
+
+    return work
+
+
+def to_stream(stream: TextIO) -> Callable[[Iterator[list[str]]], None]:
+    """
+    A blocking worker (for `offload`) that appends each string as a line to an open text stream.
+
+    The destination-shaped sibling of `to_rotating_file`, for a stream the caller
+    already owns: `sys.stderr`, a socket's text wrapper, an in-memory buffer. It
+    writes strings (render a `Record` to text with a `from_map` in front), owns the
+    newline framing, and flushes at each burst boundary. Unlike `to_rotating_file` it
+    does *not* open or close the stream: the caller's stream outlives this and may be
+    shared, so closing it (`sys.stderr`, say) is not this worker's to do.
+    """
+
+    def work(batches: Iterator[list[str]]) -> None:
+        for batch in batches:
+            for line in batch:
+                stream.write(line)
+                stream.write("\n")
+            stream.flush()
+
+    return work

without_logging-0.0.0/PKG-INFO

@@ -1,5 +0,0 @@
-Metadata-Version: 2.3
-Name: without-logging
-Version: 0.0.0
-Summary: Placeholder reserving the PyPI project name; the first real release supersedes it.
-Requires-Python: >=3.9

without_logging-0.0.0/pyproject.toml

@@ -1,9 +0,0 @@
-[build-system]
-requires = ["uv_build>=0.11,<0.12"]
-build-backend = "uv_build"
-
-[project]
-name = "without-logging"
-version = "0.0.0"
-description = "Placeholder reserving the PyPI project name; the first real release supersedes it."
-requires-python = ">=3.9"