python-traceprint 0.1.2__tar.gz → 0.1.3__tar.gz

{python_traceprint-0.1.2 → python_traceprint-0.1.3}/.gitignore

@@ -6,7 +6,6 @@ __pycache__/
 .ruff_cache/
 .mypy_cache/
 .pyright/
-uv.lock
 
 # Build outputs
 dist/

{python_traceprint-0.1.2 → python_traceprint-0.1.3}/.macrostates/implementation/deliverables.yaml

@@ -3,10 +3,10 @@ deliverables:
   traceprint:
     strategy: independent
     version_scheme: pep440
-    version: 0.1.2
+    version: 0.1.3
     status: released
-    specification: specs-1.0.0
-    implementation: imp-1.0.0
-    release_date: '2026-10-14'
+    specification: specs-1.1.0
+    implementation: imp-1.1.0
+    release_date: '2026-10-25'
     source:
-      tag: v0.1.2
+      tag: v0.1.3

python_traceprint-0.1.3/.macrostates/implementation/release.yaml

@@ -0,0 +1,4 @@
+schema_version: 2
+version: imp-1.1.0
+specification: specs-1.1.0
+release_date: '2026-10-25'

python_traceprint-0.1.3/.macrostates/specs/900_traceprint/001_project.md

@@ -0,0 +1,65 @@
+# Project
+
+Traceprint exists to make ad hoc development output easier to follow without
+requiring a full observability stack.
+
+## Responsibilities
+
+Traceprint should provide:
+
+- formatted text output with timestamp, elapsed time, cumulative time, labels,
+  and nesting depth;
+- optional ANSI colors for terminal use;
+- manual spans for nested operations;
+- a decorator for function-level tracing;
+- Python logging handlers that route logging records through tracer formatting.
+
+## Non-goals
+
+Traceprint is not a replacement for structured logging, distributed tracing,
+metrics, OpenTelemetry, or production observability infrastructure.
+
+Traceprint should not include unrelated project, pipeline, placeholder, or
+filesystem utility functions.
+
+## Identity and supported use
+
+- Distribution: `python-traceprint`; import package: `traceprint`; license: MIT.
+- Python 3.12 or later; no runtime dependencies outside the Python standard library.
+- Public API maturity: alpha. Repository specification versions and library
+  versions are independent; a specification 1.x does not declare the library stable.
+- Supported use is ordinary text streams, development scripts, short-lived CLIs
+  and Python logging. Callers coordinate shared state and own stream/file cleanup.
+
+The library is a synchronous formatter and a partial text-stream adapter. It is
+not a general `TextIOBase` implementation: only `write`, `flush` and the explicitly
+specified tracing operations are required. Do not infer `encoding`, `fileno`,
+`isatty`, binary writes or a `close` operation on `Tracer` from stream interception.
+TTY detection is delegated to the underlying sink during construction/configuration.
+
+## Product structure
+
+The importable package lives under `src/traceprint/`. Its root exports the API
+in [API](002_api.md), `colors.py` supplies color constants/conversion, `tracer.py`
+supplies tracer/context/logging behavior, and an empty `py.typed` marks typing
+support. Private implementation organization may vary while these supported
+interfaces and outputs remain equivalent.
+
+The repository also provides tests, two runnable examples, `hatch_build.py`,
+`pyproject.toml`, MIT licensing, README/contribution/changelog material and Sphinx
+API/usage/release documentation. The latter is a product maintained according to
+this package and the Python-library documentation rules. Build and release
+requirements are owned by [Library versions and releases](007_release.md).
+
+## Shared-state boundaries
+
+A tracer owns its label stack, depth, timing, enabled/locked flags, sink,
+interception captures, attached mirrors and current line state. None of these
+is thread-local, task-local or isolated by `contextvars`. Intercepted stdout and
+stderr share one sink and one context/line state.
+
+Do not promise concurrent-context isolation, asynchronous coroutine/generator
+execution tracing, overlapping tracer installation management or transactional
+configuration. Keep enable/lock settings stable while a context is active and
+balance manual push/pop operations. Unsupported mutation observations belong to
+the [compatibility annex](annex_observed-compatibility.md).

python_traceprint-0.1.3/.macrostates/specs/900_traceprint/002_api.md

@@ -0,0 +1,180 @@
+# API
+
+Traceprint's public API is small and explicit. Signatures below specify argument
+positions, keyword-only parameters and defaults; ordinary Python exceptions are
+used rather than a separate error type. Values must satisfy the annotated text,
+stream and logging contracts; constructors do not perform general type validation.
+
+## Public imports
+
+The root exports exactly these names through `__all__`, in this order:
+
+```text
+DARK_GREY, DEFAULT_COLORS, RESET, LoggerMixin, Tracer,
+TracerFileHandler, TracerHandler, trace, tracer
+```
+
+The color values are owned by [Formatting](003_formatting.md#color-values).
+`Span` and the logger proxy are returned objects, not package-root exports.
+There is no required `traceprint.__version__`; distribution version lookup uses
+`importlib.metadata.version("python-traceprint")`.
+
+## Tracer construction
+
+All constructor arguments are keyword-only:
+
+```python
+Tracer(
+    *,
+    use_colors: bool | None = None,
+    use_tabulation: bool = False,
+    color_scheme: list[str] | None = None,
+    metacolor: str | None = DARK_GREY,
+    print_transitions: bool = False,
+    filter_levels: range | Iterable[int] | Callable[[int], bool] | None = None,
+    start_enabled: bool = True,
+    output_format: str = DEFAULT_OUTPUT_FORMAT,
+    timestamp_format: str = "%Y-%m-%d %H:%M:%S",
+    stream: TextIO | None = None,
+    error_stream: TextIO | None = None,
+    intercept_stdout: bool = False,
+    intercept_stderr: bool = False,
+)
+```
+
+`DEFAULT_OUTPUT_FORMAT` denotes the exact literal specified in
+[Formatting](003_formatting.md#format-fields), not a new root export.
+
+| Option | Meaning |
+| --- | --- |
+| `use_colors` | `None` detects the sink's TTY status; explicit booleans select color output. |
+| `use_tabulation` | Enable four spaces per depth, with placement independent of color output. |
+| `color_scheme` | Ordered ANSI foreground strings; `None` or an empty list selects `DEFAULT_COLORS`. |
+| `metacolor` | Color metadata separately; a falsey value selects whole-line depth coloring. |
+| `print_transitions` | Emit the context entry/exit messages specified in [Contexts](005_contexts.md). |
+| `filter_levels` | Allowed depths or a predicate returning truthy for allowed depths. |
+| `start_enabled` | Initial formatting/depth-tracking state. |
+| `output_format` | Python format string containing the supported fields. |
+| `timestamp_format` | UTC `strftime` format. |
+| `stream` | Output sink, defaulting to current stdout; preserve whether it was explicitly supplied. |
+| `error_stream` | Accepted compatibility parameter; it does not create a separate stderr output route. |
+| `intercept_stdout`, `intercept_stderr` | Explicit construction-time installation requests, both false by default. |
+
+Construction initializes `depth = 0`, `labels = []`, an unlocked state, no active
+interception captures, no attached file mirrors and a fresh line state. Read the
+performance clock once and use that value as both the start and last-format time.
+Resolve colors before optional installation; installation does not redetect TTY
+status or reset timing, labels or line state.
+
+Use the supplied stream when present in ordinary use, otherwise current stdout.
+The alpha's falsey-stream selection nuance is documented in the
+[compatibility annex](annex_observed-compatibility.md#stream-and-installation-edges).
+A supplied nonempty palette and the default palette are shared by reference,
+not copied. Keep a palette nonempty after selection.
+
+## Tracer state and operations
+
+Readable/mutable public configuration attributes are `use_colors`,
+`use_tabulation`, `color_scheme`, `metacolor`, `print_transitions`, `filter_levels`,
+`output_format` and `timestamp_format`. `depth` and `labels` expose current context;
+prefer balanced context operations to direct mutation. `enabled` is read-only.
+Depth and labels are separate mutable values; assigning one does not automatically
+reconcile the other. Configuration changes do not reset clocks or line state.
+
+| Signature | Result and owner |
+| --- | --- |
+| `enabled -> bool` | Current enabled flag. |
+| `install(*, stdout: bool = True, stderr: bool = False) -> None` | Explicit stream capture/replacement; [Interception](004_interception.md#installation). |
+| `uninstall() -> None` | Restore captured streams and clear installation flags. |
+| `enable() -> None`, `disable() -> None` | Set formatting/depth-tracking state without resetting context or clocks. |
+| `lock() -> None`, `unlock() -> None` | Set depth-mutation lock without changing existing context. |
+| `configure(**kwargs) -> None` | Ordered configuration updates described below. |
+| `format(message: str) -> str` | Format without output; advances timing; [Formatting](003_formatting.md). |
+| `write(data: str) -> int` | Immediate fragment output; returns input length; [Interception](004_interception.md#writing-fragments). |
+| `flush() -> None` | Flush the sink and each mirror without ending a line. |
+| `push(label: str | None = None) -> None` | Manual depth entry; [Contexts](005_contexts.md#manual-push-and-pop). |
+| `pop(label: str | None = None) -> None` | Manual depth exit, safe at depth zero. |
+| `span(label: str) -> Span` | Return a synchronous context manager; [Contexts](005_contexts.md#spans). |
+| `add_file_handler(handler: TracerFileHandler) -> None` | Append a mirror in attachment order. |
+| `remove_file_handler(handler: TracerFileHandler) -> None` | Remove its first matching attachment; missing attachment is a no-op. |
+
+There is no return-value aggregation from sink/mirror writes and no implicit
+closing of a sink or attached handlers. See [Logging](006_logging.md) for handler
+ownership and failure behavior.
+
+## Configuration order
+
+Apply one `configure` call in this order:
+
+1. If either interception key is supplied, derive both desired flags. Missing
+   flags retain their current installed state; supplied values use `bool(value)`.
+   Uninstall the current captures, then install the derived combination.
+2. If `use_colors` is supplied, `None` redetects the current sink's TTY status;
+   any other value uses `bool(value)`.
+3. If `color_scheme` is supplied, select the provided sequence or default palette
+   using its truthiness.
+4. Assign remaining keys in caller order when the tracer already has that
+   attribute. Otherwise raise `AttributeError("Tracer has no attribute NAME")`.
+
+This is not a constructor replay. Names such as `stream`, `error_stream` and
+`start_enabled` are not public configuration attributes; use lifecycle methods
+for enabled state and construction for a sink. A read-only attribute assignment
+raises normal `AttributeError`. Earlier updates are retained if a later one
+fails. The permissive alpha handling of private/method attributes is an
+[observation](annex_observed-compatibility.md#configuration-and-mutable-state),
+not an additional supported configuration surface.
+
+## Global tracer
+
+Create one global convenience `tracer` when the runtime module first imports,
+using ordinary constructor defaults. Root imports refer to this same object.
+Import alone must not replace stdout/stderr, open logging files, attach root
+logging handlers or configure the root logger. Environment labels are the only
+specified import-time configuration beyond constructor defaults.
+
+## Environment variables
+
+Read `TRACEPRINT_INITIAL_LABELS` once at import time, defaulting to the empty
+string. Strip the complete value; split it on `/`; strip each component and
+discard empty components. Push each remaining component in order on the global
+tracer. This sets both labels and depth; it does not install the tracer.
+
+For example, `" / job // load / "` produces labels `["job", "load"]` and depth 2.
+Explicit new tracer instances do not read this variable. Later environment edits
+do not mutate the existing global instance. There are no other Traceprint-owned
+environment variables.
+
+## Context and logging interfaces
+
+```python
+trace(_func: Callable[..., Any] | None = None, *,
+      label: str | None = None, force: bool = False,
+      tracer_instance: Tracer | None = None) -> Callable[..., Any]
+
+TracerHandler(level: int = logging.NOTSET, *,
+              tracer_instance: Tracer | None = None)
+
+TracerFileHandler(filename: str | os.PathLike[str], mode: str = "a",
+                  level: int = logging.NOTSET, encoding: str = "utf-8", *,
+                  tracer_instance: Tracer | None = None)
+
+LoggerMixin(*, verbose: bool = True, logging_level: int = logging.INFO,
+            logging_passthrough: bool = False, lazy_init: bool = False)
+```
+
+`trace` supports bare and parameterized decorator forms. Its target selection,
+transitions, result/exception behavior and `force` boundary are owned by
+[Contexts](005_contexts.md#function-decorator).
+
+Both handlers subclass `logging.Handler` and support standard levels, formatters,
+filters and `handle` behavior. They implement `emit(record: logging.LogRecord)
+returning `None`. File handlers additionally expose `write(data: str) -> None`,
+`flush() -> None` and `close() -> None`, and the filename/mode/encoding/tracer/stream
+attributes described in [Logging](006_logging.md#file-handler).
+
+`LoggerMixin.logger` returns a standard logger; `LoggerMixin.log` returns the same
+instance's verbosity-gated proxy. The proxy supports `log(level, msg, *args,
+**kwargs)`, `debug`, `info`, `warning`, `error` and `critical`, all returning `None`.
+No proxy `exception` or `warn` method is required. Use `.logger` for the full
+standard logging interface. Initialization and shared-logger effects are owned
+by [Logging](006_logging.md#logger-mixin).

python_traceprint-0.1.3/.macrostates/specs/900_traceprint/003_formatting.md

@@ -0,0 +1,109 @@
+# Formatting and colors
+
+## Format fields
+
+The exact default output format is:
+
+```text
+[{timestamp}][{cumulative}][{elapsed}][{label_full}] {original_message}
+```
+
+Use Python string formatting with these named values, all strings:
+
+| Field | Value |
+| --- | --- |
+| `timestamp` | Current aware UTC datetime formatted with `timestamp_format`. |
+| `cumulative` | Performance-clock seconds since construction, `f"{seconds:.3f}s"`. |
+| `elapsed` | Seconds since the previous `format` call, `f"+{seconds:.3f}s"`. |
+| `label` | The final label, or empty; append `/>` for regular labeled messages. |
+| `label_full` | The slash-joined label stack, or empty; same regular-message suffix. |
+| `original_message` | The input string without further stripping or interpolation. |
+
+At each `format` call, read the performance clock, compute elapsed from the last
+format time and cumulative from the start time, then set last-format time to the
+new value. Obtain the UTC timestamp separately. Formatting advances timing even
+when called directly, when the tracer is disabled, or when a later formatting
+operation raises. Continuation fragments, blank writes, filtered writes and
+flushes do not call `format` and do not advance timing.
+
+Clocks measure tracer age and gaps between formatted messages, not exclusive
+span duration. Timing text has three fractional digits and an `s` suffix, with
+an explicit `+` before elapsed text. The default timestamp uses
+`%Y-%m-%d %H:%M:%S`; `%z` yields `+0000`.
+
+Compute the raw full label by joining labels with `/` and the short label from
+the final entry. If the full label is nonempty and the message does not start
+with literal `>` or `<`, append `/>` to both values. Otherwise keep them raw.
+This rule examines the first character without stripping leading whitespace;
+it is not a special transition object. Label strings are not escaped.
+
+Custom formats may select, omit, repeat or reorder fields. Preserve message text
+when the format includes `original_message`; do not force it into a format that
+omits it. Unknown fields, incompatible format syntax and invalid timestamp formats
+use the standard formatting/datetime exception behavior; there is no silent fallback.
+For incremental writes, metadata/custom suffixes are applied to the first
+nonblank fragment only; see [Writes](004_interception.md#writing-fragments).
+
+## Color values
+
+`RESET` is `"\x1b[0m"`; `DARK_GREY` is `"\x1b[90m"`. `DEFAULT_COLORS` is an
+ordered mutable list of truecolor foreground sequences generated from:
+
+| Depth modulo 8 | RGB hex | Red, green, blue |
+| --- | --- | --- |
+| 0 | `#52C97F` | 82, 201, 127 |
+| 1 | `#68BCCD` | 104, 188, 205 |
+| 2 | `#7D7FD2` | 125, 127, 210 |
+| 3 | `#C891D8` | 200, 145, 216 |
+| 4 | `#DDA5BE` | 221, 165, 190 |
+| 5 | `#E4C9B9` | 228, 201, 185 |
+| 6 | `#E5EACC` | 229, 234, 204 |
+| 7 | `#E0F2DF` | 224, 242, 223 |
+
+The sequence for channels `r`, `g`, `b` is exactly
+`"\x1b[38;2;{r};{g};{b}m"`, with decimal channel values. Select the current
+line color at index `depth % len(color_scheme)`; custom palettes cycle by their
+own length. No terminal capability negotiation beyond TTY color detection is
+required. A caller can explicitly request ANSI output to a non-TTY sink.
+
+The supporting module `traceprint.colors` also exposes
+`hex_to_ansi(hexstr: str) -> str`, although it is not a root export. For normal
+hex input, remove a single leading `#`, require six remaining characters, parse
+each pair using base-16 integer conversion and generate the sequence above.
+Bad length or pair-conversion failure raises
+`ValueError(f"Expected #RRGGBB color, got {hexstr!r}")`; conversion failure chains
+the original `ValueError`. No additional clamping is performed. Malformed inputs
+accepted by Python's integer parser are discussed in the
+[compatibility annex](annex_observed-compatibility.md#format-and-color-edges).
+
+## Color and indentation composition
+
+After formatting fields into `text`, compute `indent` as four literal spaces
+times depth when tabulation is enabled, otherwise the empty string. Indentation
+must have the same placement whether colors are enabled or disabled.
+
+1. If `metacolor` is falsey, prepend `indent` to the entire `text`. When colors
+   are enabled, surround that complete result with the selected line color and
+   `RESET`; otherwise return it directly.
+2. If `metacolor` is truthy, find the first occurrence of the input message in
+   the formatted `text`. Split into `meta_part` before that occurrence and
+   `message_part` from that occurrence through the end. With colors disabled,
+   return `meta_part + indent + message_part`. With colors enabled, return:
+
+   ```text
+   metacolor + meta_part + RESET + line_color + indent + message_part + RESET
+   ```
+
+3. If the message does not occur in `text`, prepend `indent` to the whole text.
+   With colors enabled use `metacolor + indent + text + RESET`; with colors
+   disabled use `indent + text`.
+
+This describes string concatenation, not literal names in emitted output. Do not
+strip caller-supplied ANSI from console output. An empty `meta_part` still has
+its metadata color/reset framing when colors are enabled. `format` adds no
+newline of its own and does not update the fragment line state.
+
+The first-substring rule is a compatibility detail of the existing formatter;
+it is not a promise of placeholder-aware parsing. See the
+[compatibility annex](annex_observed-compatibility.md#format-and-color-edges)
+when a custom format repeats a message or includes it in metadata.

python_traceprint-0.1.3/.macrostates/specs/900_traceprint/004_interception.md

@@ -0,0 +1,115 @@
+# Interception
+
+Traceprint may replace process streams only when the caller explicitly requests
+that behavior. The same object also works as `print(..., file=target)` or through
+direct `write` calls without installation. Writes have immediate effects; no
+complete-line buffering is permitted merely to join `print` arguments.
+
+## Installation
+
+`install(*, stdout=True, stderr=False)` handles stdout first, then stderr:
+
+- For a requested stream not already intercepted by this tracer, capture its
+  current process object and replace it with the tracer. Mark that stream installed.
+- If stdout is newly installed and no explicit sink was supplied at construction,
+  choose the captured stdout as the sink.
+- If stderr is newly installed, this call's `stdout` argument is false and no
+  explicit sink was supplied, choose the captured stderr as the sink.
+- Otherwise retain the sink. An explicit constructor sink wins in every case.
+
+This makes repeated requests for an already-installed stream idempotent without
+recapturing the tracer itself. A false argument does not uninstall a previously
+installed stream; use `uninstall` or `configure` to remove interception. With
+both streams requested in the same call, both feed the selected stdout sink.
+There is no separate routing through `error_stream`.
+
+`uninstall()` restores each captured stdout/stderr object for which this tracer
+has an active installation flag, then clears both flags and captures. Repeating
+uninstall is a no-op. It does not close/reset the sink, clocks, labels, line state
+or attached file handlers. Install/uninstall do not enable a disabled tracer.
+
+Callers should use `try/finally` to restore streams. Normal single-tracer cleanup
+must restore object identity, not just an equivalent stream. Overlapping tracer
+ownership and external stream replacements are not automatically coordinated;
+see [compatibility](annex_observed-compatibility.md#stream-and-installation-edges).
+
+## Depth filtering
+
+At the point a write chunk or transition is considered, determine whether the
+current depth is allowed:
+
+- `None`: allow every depth.
+- `range`: allow exactly its members.
+- Callable: call it with the current depth and allow a truthy result.
+- Other iterable: allow when membership contains the current depth.
+
+Suppressing output does not suppress context mutation. A disallowed chunk must
+not reach either the sink or mirrors, call `format`, advance timing or alter
+visible line state. Evaluate the write filter once per chunk, including whitespace
+chunks. Context transition operations may also perform their own precheck.
+Exceptions from predicates/membership propagate during direct tracer operations.
+Iterable membership has ordinary Python semantics, including consumption of
+one-shot iterators; prefer a reusable collection for stable membership.
+
+## Writing fragments
+
+`write(data: str)` returns `len(data)` on a successful call, even when all output
+is filtered. It does not return the length of metadata or the underlying sink's
+write result. Preserve message whitespace and original CR/LF endings.
+
+When disabled, write `data` directly to the sink, bypassing formatting, filtering
+and mirrors. For a nonempty input, set line state according to whether it ends
+with CR or LF: an ending resets it; otherwise mark an existing line. An empty
+disabled write still calls the sink but leaves line state unchanged.
+
+When enabled:
+
+1. Split `data` using `str.splitlines(keepends=True)`. An empty input creates no
+   chunks and causes no sink write.
+2. For each allowed chunk, remove only trailing CR/LF characters into an `ending`
+   suffix, leaving `message`. Do not strip other characters from the emitted text.
+3. If `message.strip()` is nonempty and no line has started, call `format(message)`.
+   If a line has started, emit the original message unchanged, or surround it
+   with the current depth color and `RESET` when colors are enabled. Do not
+   repeat metadata or indentation on a continuation.
+4. Write that result plus its ending, then mark the line started. For a whitespace-
+   only chunk, write the original chunk without formatting or starting a new line.
+5. Any nonempty CR/LF ending resets line state after that write.
+
+Every enabled write reaches the sink first, followed by all mirrors in attachment
+order with the same already-formatted text. Do not catch sink/mirror exceptions
+in the tracer, automatically retry, or roll back effects already written. Line
+state changes after the corresponding successful write operation.
+
+Whitespace fragments are immediate too. Leading whitespace supplied separately
+can precede the first metadata prefix; whitespace within a nonblank fragment
+remains part of that formatted message. Blank lines have no metadata. Unicode
+line separators recognized by `splitlines` but not CR/LF remain in their message
+or whitespace chunk and do not reset this CR/LF line state. These unusual cases
+are further illustrated in the [compatibility annex](annex_observed-compatibility.md).
+
+Labels, timing and indentation belong to the first nonblank fragment's metadata.
+Later context/configuration changes do not cause a second prefix before a newline.
+Continuation coloring uses the current palette/depth at that write. A custom
+format suffix follows the first fragment, not the eventual complete line.
+
+## Flush and mirroring lifecycle
+
+`flush()` flushes the sink, then every attached mirror in attachment order,
+regardless of enabled state. It does not output pending text, add a newline,
+reset line state or advance clocks. Exceptions propagate; later mirrors are not
+flushed after an earlier failure.
+
+Attaching a handler appends it without deduplication or opening/closing it.
+Removing a handler removes the first equal attachment if present and otherwise
+does nothing. Attaching the same handler twice yields two mirror writes/flushes;
+ordinary use should attach once. The caller removes and closes owned handlers.
+Handler behavior and ANSI stripping are owned by [Logging](006_logging.md).
+
+## Formatting
+
+Formatted output preserves message text when the configured format contains its
+placeholder. Colors are optional and auto-disabled for non-TTY sinks. Exact
+format fields, colors and indentation rules are in [Formatting](003_formatting.md).
+File output strips terminal escape sequences as specified in [Logging](006_logging.md);
+there is no current option to preserve ANSI in files.

python_traceprint-0.1.3/.macrostates/specs/900_traceprint/005_contexts.md

@@ -0,0 +1,126 @@
+# Contexts and decorators
+
+## Common context rules
+
+Depth starts at zero and labels form a stack in outer-to-inner order. A normal
+entry adds one depth and one label; a normal exit removes one of each. Filtering
+affects output, not this tracking. Locked tracers retain their existing depth and
+labels while still being able to print allowed transitions/messages.
+
+Enable/disable and lock/unlock are setters, not counters or context managers.
+They do not reset labels, clocks, mirrors or line state. Disabled manual operations
+and spans do not track depth. Keep these flags stable inside active spans/decorated
+calls and balance manual operations. Behavior outside those conditions is recorded
+in [compatibility observations](annex_observed-compatibility.md#context-mutation-edges).
+
+Transition strings below are supplied to `write` with a trailing newline and
+are therefore subject to filtering, current line state and ordinary formatting.
+Transition output is optional; no transitions are printed by default.
+
+## Manual push and pop
+
+`push(label=None)`:
+
+1. If disabled, return without any effect.
+2. If unlocked, increment depth and append the supplied truthy label, otherwise
+   append `"level" + str(new_depth)`. Thus `None` and `""` generate `levelN` labels.
+3. If the supplied label itself is truthy, transitions are enabled and the new
+   current depth is allowed, write `"> LABEL\n"`.
+
+Generated labels do not trigger a transition when no truthy label was supplied.
+When locked, an explicitly labeled transition can still be written at the existing
+depth; the label stack is unchanged.
+
+`pop(label=None)`:
+
+1. If disabled, return without any effect.
+2. If unlocked and depth is above zero, decrement depth and remove the final
+   stored label. At depth zero, do not decrement or remove anything.
+3. Select the supplied truthy label, otherwise the removed label. If that selected
+   value is truthy, transitions are enabled and the resulting depth is allowed,
+   write `"< LABEL\n"`.
+
+An explicit pop label names the transition, not a stack entry to search/remove.
+At depth zero or while locked, `pop("name")` may still print an exit transition.
+With no selected label, print nothing. Manual push transitions use the entered
+context; manual pop transitions use the parent context after removal.
+
+## Spans
+
+`span(label)` constructs a synchronous context manager without changing state.
+The returned object exposes its target as `.tracer` and exact label as `.label`.
+Entering returns that context object, so `with target.span("load") as context`
+binds the span, not the tracer.
+
+On entry when enabled:
+
+1. If transitions are enabled and the parent depth is allowed, write `"> LABEL\n"`.
+2. If unlocked, increment depth and append the exact supplied label, including an
+   empty string. Unlike manual `push`, spans do not generate a replacement label.
+
+On exit when enabled:
+
+1. If unlocked, decrement depth and remove the final label.
+2. If transitions are enabled and the resulting parent depth is allowed, write
+   `"< LABEL\n"` on ordinary exit, or
+   `"< LABEL [failed: EXCEPTION_CLASS_NAME]\n"` when exiting with an exception.
+
+Return `None` from exit; do not suppress the body's exception. On normal supported
+use, cleanup restores the prior depth/labels even when the body raises. Disabled
+entry/exit performs no context/transition work; locked entry/exit performs no
+depth mutation. Spans do not install/uninstall streams or flush/close sinks.
+
+## Function decorator
+
+Support all these forms, preserving the function's metadata with `functools.wraps`:
+
+```python
+@trace
+def work(): ...
+
+
+@trace(label="load")
+def load(): ...
+
+
+@trace(tracer_instance=target)
+def run(): ...
+```
+
+Select the supplied tracer or global `tracer` when the decorator is created;
+do not select a new tracer on each call. The optional first positional function
+supports the bare form; when it is `None`, return a decorator awaiting a function.
+A truthy explicit label wins; otherwise use `function.__name__`.
+
+On each wrapped call:
+
+1. If the target is disabled, directly call the function with the original
+   arguments and return its result. No transitions or context mutation occur.
+2. Capture whether the entry depth is filtered. If transitions are enabled and
+   either entry depth is allowed or `force=True`, attempt
+   `"> LABEL()\n"` at the parent depth.
+3. If unlocked, increment depth and append the selected label.
+4. Call the function with unchanged positional/keyword arguments. Return its
+   result unchanged; let its exceptions propagate.
+5. In `finally`, if unlocked, decrement depth and remove the last label. If
+   transitions are enabled and either the captured entry depth was allowed or
+   `force=True`, attempt `"< LABEL()\n"` at the resulting parent depth.
+
+The decorator's exit has no span-style `[failed: ...]` suffix. Capture the entry
+filter decision once for both transition attempts; each actual `write` still
+applies the current depth filter. `force` is not a bypass of write-level filtering.
+That alpha compatibility boundary is discussed in the
+[annex](annex_observed-compatibility.md#transition-filtering).
+
+The wrapper traces synchronous function invocation only. For an async function
+or generator, it surrounds creation of the coroutine/generator object, not later
+execution, awaits or iteration. Do not add special async/generator tracing while
+replicating this library.
+
+## Failure boundaries
+
+Context tracking is not transactional with output. A transition write can fail
+before body execution or during exit, using the direct stream failure behavior.
+Entry/exit may therefore fail independently of the body. Normal exception cleanup
+guarantees assume a writable sink, balanced context and stable enabled/locked state;
+no recovery for externally corrupted stacks or flag changes is required.