clued 0.1.0__tar.gz

clued-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: clued
+Version: 0.1.0
+Summary: Ergonomic error context for Python exceptions, built on PEP 678 add_note()
+Keywords: error,exception,context,debugging,add_note,PEP678
+Author: Connor Wang
+Author-email: Connor Wang <wonnor.pro@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/wonnor-pro/clued
+Project-URL: Repository, https://github.com/wonnor-pro/clued
+Project-URL: Issues, https://github.com/wonnor-pro/clued/issues
+Project-URL: Changelog, https://github.com/wonnor-pro/clued/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Clued
+
+[![CI](https://github.com/wonnor-pro/clued/actions/workflows/ci.yml/badge.svg)](https://github.com/wonnor-pro/clued/actions/workflows/ci.yml)
+
+> Leave clues for your future debugging self.
+
+`clued` attaches structured, human-readable context to exceptions as they propagate — without changing the exception type, wrapping in a new exception, or parsing strings later.
+
+## Install
+
+Install with pip
+
+```bash
+pip install clued
+```
+
+or install with uv
+
+```bash
+uv add clued
+```
+
+Requires Python 3.11+. Zero dependencies.
+
+## The Problem
+
+When an error happens deep in your call stack, you typically get one of two outcomes:
+
+**Option A — bare exception, no context:**
+
+```python
+def process_order(order_id):
+    user = get_user(order_id)   # raises ValueError("invalid id format")
+    charge(user)
+```
+
+```text
+ValueError: invalid id format
+  File "app.py", line 2, in get_user
+```
+
+The traceback tells you *where* it happened, not *why*. You don't know which order, which user, or what the system was trying to do at a higher level.
+
+**Option B — verbose try/except wrapping:**
+
+```python
+def process_order(order_id):
+    try:
+        user = get_user(order_id)
+    except ValueError as e:
+        raise OrderProcessingError(
+            f"failed to process order {order_id}: could not fetch user"
+        ) from e
+```
+
+This works, but it's tedious. Every layer of your call stack needs its own `try/except/raise from` block. Real codebases end up with dozens of custom exception classes and repetitive wrapping code. Most developers just don't bother — and then they're debugging production issues with a `KeyError: 'name'` and no idea which record or request caused it.
+
+**With `clued`:**
+
+```python
+from clued import clue
+
+def process_order(order_id: str, user_id: int) -> None:
+    with clue("processing order", order_id=order_id, user_id=user_id) as ctx:
+        ctx.refine(step="fetch user")
+        user = get_user(order_id)
+
+        ctx.refine(step="charge")
+        charge(user)
+```
+
+```text
+ValueError: invalid id format
+  File "app.py", line 4, in get_user
+- Clue 0: processing order [order_id='BAD', user_id=-1, step='fetch user'] (app.py:8)
+```
+
+Clues nest naturally across call boundaries — each layer adds its own note, inner-to-outer:
+
+```python
+from clued import clue
+
+def process_order(order_id: str, user_id: int) -> None:
+    with clue("processing order", order_id=order_id, user_id=user_id):
+        charge_user(order_id, user_id)
+
+def charge_user(order_id: str, user_id: int) -> None:
+    with clue("charging user", user_id=user_id) as ctx:
+        ctx.refine(step="fetch card")
+        card = get_card(user_id)
+
+        ctx.refine(step="apply charge")
+        apply_charge(card, order_id)
+```
+
+```text
+ValueError: invalid card format
+  File "app.py", line 4, in get_card
+- Clue 0: charging user [user_id=-1, step='fetch card'] (app.py:11)
+- Clue 1: processing order [order_id='BAD', user_id=-1] (app.py:5)
+```
+
+One `with` block. No custom exception class. No `raise from`. The context travels with the exception automatically.
+
+## Quick Start
+
+```python
+from clued import clue, get_clues
+
+with clue("loading config", path=path, env=env) as ctx:
+    ctx.refine(section="database")
+    load_db_config(path)
+```
+
+On any exception raised inside the block, `clued` calls `add_note()` (PEP 678) to attach a formatted string, and stores a structured `ClueRecord` you can query in code:
+
+```python
+except Exception as e:
+    for record in get_clues(e):
+        print(record.msg, dict(record.kv), f"{record.filename}:{record.lineno}")
+```
+
+Nested `with clue(...)` blocks each add their own note — outermost last, so the traceback reads inner-to-outer.
+
+## Features
+
+- **Structured kv** — context stored as typed key-value pairs, not just strings
+- **Source location** — note includes the exact file and line where `clue()` or `refine()` was called
+- **`refine()`** — narrow context in-place as a block progresses (e.g. track loop index, current step)
+- **Async-safe** — uses `ContextVar` for per-task isolation; works with `asyncio.gather` and thread pools
+- **Zero dependencies** — stdlib only
+- **Fully typed** — ships a `py.typed` marker, passes mypy strict and pyright
+
+## API Reference
+
+| Symbol | Description |
+| --- | --- |
+| `clue(msg, **kv)` | Context manager. Attaches context on any exception raised within the block. Yields a `ClueHandle`. |
+| `ClueHandle.refine(msg=None, **kv)` | Update context in-place. `None` values delete a key. |
+| `ClueHandle.reset()` | Restore to original message and clear all kv. |
+| `clue_on_error(msg_template, **kv)` | Decorator. Formats `msg_template` with bound arguments and wraps the call in `clue()`. Works on async functions too. |
+| `ctx(fn, *args, msg, **kv)` | Inline wrapper. Calls `fn(*args)` inside a `clue()` context. |
+| `get_clues(exc)` | Returns `list[ClueRecord]` attached to the exception. |
+| `get_clue_dict(exc)` | Returns a flat merged `dict` of all kv (inner clues override outer). |
+| `current_clues()` | Returns the active `tuple[ClueHandle, ...]` stack for the current context (useful for logging). |
+
+### `ClueRecord`
+
+```python
+@dataclass(frozen=True)
+class ClueRecord:
+    msg: str
+    kv: frozenset[tuple[str, Any]]
+    filename: str
+    lineno: int
+```
+
+## Usage Patterns
+
+### Decorator
+
+```python
+from clued import clue_on_error
+
+@clue_on_error("processing item {item_id}", source="worker")
+def process_item(item_id: str) -> None:
+    ...
+
+@clue_on_error("fetch user {user_id}")
+async def fetch_user(user_id: int) -> dict:
+    ...
+```
+
+### Inline wrapper
+
+```python
+from clued import ctx
+
+result = ctx(load_file, path, msg="loading file", path=path)
+```
+
+### Tracking progress in a loop
+
+```python
+with clue("batch processing", total=len(items)) as ctx:
+    for i, item in enumerate(items):
+        ctx.refine(index=i, item_id=item["id"])
+        process_item(item)
+```
+
+If the batch fails at item 42, the exception note shows exactly which item and index.
+
+### Logging integration
+
+```python
+import logging
+from clued import current_clues
+
+class ClueFilter(logging.Filter):
+    def filter(self, record):
+        for handle in current_clues():
+            record.__dict__.update(handle.kv)
+        return True
+```
+
+## How It Works
+
+`clued` is built on two Python stdlib primitives:
+
+- **PEP 678 `add_note()`** (Python 3.11+) — the standard way to attach strings to exceptions. Tools like pytest, rich, and IPython already render `__notes__`, so you get readable output for free.
+- **`contextvars.ContextVar`** — each asyncio task and thread inherits a copy-on-write context, so nested tasks each carry their own clue stack and cannot interfere with each other.
+
+When an exception exits a `clue` block, two things happen:
+
+1. A formatted string (`- Clue N: msg [k=v] (file:line)`) is appended via `add_note()`, where `N` is the depth index (0 = innermost).
+2. A `ClueRecord` is appended to `exc.__clues__` for structured access.
+
+No monkeypatching. No custom exception base class. No runtime overhead on the happy path.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run mypy src/clued
+uv run ruff check src/ tests/
+```
+
+## License
+
+MIT

clued-0.1.0/README.md

@@ -0,0 +1,231 @@
+# Clued
+
+[![CI](https://github.com/wonnor-pro/clued/actions/workflows/ci.yml/badge.svg)](https://github.com/wonnor-pro/clued/actions/workflows/ci.yml)
+
+> Leave clues for your future debugging self.
+
+`clued` attaches structured, human-readable context to exceptions as they propagate — without changing the exception type, wrapping in a new exception, or parsing strings later.
+
+## Install
+
+Install with pip
+
+```bash
+pip install clued
+```
+
+or install with uv
+
+```bash
+uv add clued
+```
+
+Requires Python 3.11+. Zero dependencies.
+
+## The Problem
+
+When an error happens deep in your call stack, you typically get one of two outcomes:
+
+**Option A — bare exception, no context:**
+
+```python
+def process_order(order_id):
+    user = get_user(order_id)   # raises ValueError("invalid id format")
+    charge(user)
+```
+
+```text
+ValueError: invalid id format
+  File "app.py", line 2, in get_user
+```
+
+The traceback tells you *where* it happened, not *why*. You don't know which order, which user, or what the system was trying to do at a higher level.
+
+**Option B — verbose try/except wrapping:**
+
+```python
+def process_order(order_id):
+    try:
+        user = get_user(order_id)
+    except ValueError as e:
+        raise OrderProcessingError(
+            f"failed to process order {order_id}: could not fetch user"
+        ) from e
+```
+
+This works, but it's tedious. Every layer of your call stack needs its own `try/except/raise from` block. Real codebases end up with dozens of custom exception classes and repetitive wrapping code. Most developers just don't bother — and then they're debugging production issues with a `KeyError: 'name'` and no idea which record or request caused it.
+
+**With `clued`:**
+
+```python
+from clued import clue
+
+def process_order(order_id: str, user_id: int) -> None:
+    with clue("processing order", order_id=order_id, user_id=user_id) as ctx:
+        ctx.refine(step="fetch user")
+        user = get_user(order_id)
+
+        ctx.refine(step="charge")
+        charge(user)
+```
+
+```text
+ValueError: invalid id format
+  File "app.py", line 4, in get_user
+- Clue 0: processing order [order_id='BAD', user_id=-1, step='fetch user'] (app.py:8)
+```
+
+Clues nest naturally across call boundaries — each layer adds its own note, inner-to-outer:
+
+```python
+from clued import clue
+
+def process_order(order_id: str, user_id: int) -> None:
+    with clue("processing order", order_id=order_id, user_id=user_id):
+        charge_user(order_id, user_id)
+
+def charge_user(order_id: str, user_id: int) -> None:
+    with clue("charging user", user_id=user_id) as ctx:
+        ctx.refine(step="fetch card")
+        card = get_card(user_id)
+
+        ctx.refine(step="apply charge")
+        apply_charge(card, order_id)
+```
+
+```text
+ValueError: invalid card format
+  File "app.py", line 4, in get_card
+- Clue 0: charging user [user_id=-1, step='fetch card'] (app.py:11)
+- Clue 1: processing order [order_id='BAD', user_id=-1] (app.py:5)
+```
+
+One `with` block. No custom exception class. No `raise from`. The context travels with the exception automatically.
+
+## Quick Start
+
+```python
+from clued import clue, get_clues
+
+with clue("loading config", path=path, env=env) as ctx:
+    ctx.refine(section="database")
+    load_db_config(path)
+```
+
+On any exception raised inside the block, `clued` calls `add_note()` (PEP 678) to attach a formatted string, and stores a structured `ClueRecord` you can query in code:
+
+```python
+except Exception as e:
+    for record in get_clues(e):
+        print(record.msg, dict(record.kv), f"{record.filename}:{record.lineno}")
+```
+
+Nested `with clue(...)` blocks each add their own note — outermost last, so the traceback reads inner-to-outer.
+
+## Features
+
+- **Structured kv** — context stored as typed key-value pairs, not just strings
+- **Source location** — note includes the exact file and line where `clue()` or `refine()` was called
+- **`refine()`** — narrow context in-place as a block progresses (e.g. track loop index, current step)
+- **Async-safe** — uses `ContextVar` for per-task isolation; works with `asyncio.gather` and thread pools
+- **Zero dependencies** — stdlib only
+- **Fully typed** — ships a `py.typed` marker, passes mypy strict and pyright
+
+## API Reference
+
+| Symbol | Description |
+| --- | --- |
+| `clue(msg, **kv)` | Context manager. Attaches context on any exception raised within the block. Yields a `ClueHandle`. |
+| `ClueHandle.refine(msg=None, **kv)` | Update context in-place. `None` values delete a key. |
+| `ClueHandle.reset()` | Restore to original message and clear all kv. |
+| `clue_on_error(msg_template, **kv)` | Decorator. Formats `msg_template` with bound arguments and wraps the call in `clue()`. Works on async functions too. |
+| `ctx(fn, *args, msg, **kv)` | Inline wrapper. Calls `fn(*args)` inside a `clue()` context. |
+| `get_clues(exc)` | Returns `list[ClueRecord]` attached to the exception. |
+| `get_clue_dict(exc)` | Returns a flat merged `dict` of all kv (inner clues override outer). |
+| `current_clues()` | Returns the active `tuple[ClueHandle, ...]` stack for the current context (useful for logging). |
+
+### `ClueRecord`
+
+```python
+@dataclass(frozen=True)
+class ClueRecord:
+    msg: str
+    kv: frozenset[tuple[str, Any]]
+    filename: str
+    lineno: int
+```
+
+## Usage Patterns
+
+### Decorator
+
+```python
+from clued import clue_on_error
+
+@clue_on_error("processing item {item_id}", source="worker")
+def process_item(item_id: str) -> None:
+    ...
+
+@clue_on_error("fetch user {user_id}")
+async def fetch_user(user_id: int) -> dict:
+    ...
+```
+
+### Inline wrapper
+
+```python
+from clued import ctx
+
+result = ctx(load_file, path, msg="loading file", path=path)
+```
+
+### Tracking progress in a loop
+
+```python
+with clue("batch processing", total=len(items)) as ctx:
+    for i, item in enumerate(items):
+        ctx.refine(index=i, item_id=item["id"])
+        process_item(item)
+```
+
+If the batch fails at item 42, the exception note shows exactly which item and index.
+
+### Logging integration
+
+```python
+import logging
+from clued import current_clues
+
+class ClueFilter(logging.Filter):
+    def filter(self, record):
+        for handle in current_clues():
+            record.__dict__.update(handle.kv)
+        return True
+```
+
+## How It Works
+
+`clued` is built on two Python stdlib primitives:
+
+- **PEP 678 `add_note()`** (Python 3.11+) — the standard way to attach strings to exceptions. Tools like pytest, rich, and IPython already render `__notes__`, so you get readable output for free.
+- **`contextvars.ContextVar`** — each asyncio task and thread inherits a copy-on-write context, so nested tasks each carry their own clue stack and cannot interfere with each other.
+
+When an exception exits a `clue` block, two things happen:
+
+1. A formatted string (`- Clue N: msg [k=v] (file:line)`) is appended via `add_note()`, where `N` is the depth index (0 = innermost).
+2. A `ClueRecord` is appended to `exc.__clues__` for structured access.
+
+No monkeypatching. No custom exception base class. No runtime overhead on the happy path.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run mypy src/clued
+uv run ruff check src/ tests/
+```
+
+## License
+
+MIT

clued-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "clued"
+version = "0.1.0"
+description = "Ergonomic error context for Python exceptions, built on PEP 678 add_note()"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Connor Wang", email = "wonnor.pro@gmail.com" },
+]
+keywords = ["error", "exception", "context", "debugging", "add_note", "PEP678"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Debuggers",
+]
+
+[project.urls]
+Homepage = "https://github.com/wonnor-pro/clued"
+Repository = "https://github.com/wonnor-pro/clued"
+Issues = "https://github.com/wonnor-pro/clued/issues"
+Changelog = "https://github.com/wonnor-pro/clued/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "clued"
+module-root = "src"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "mypy>=1.0",
+    "pyright>=1.1",
+    "ruff>=0.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

clued-0.1.0/src/clued/__init__.py

@@ -0,0 +1,17 @@
+from clued._core import ClueHandle, clue
+from clued._decorator import clue_on_error, clue_on_error_async
+from clued._extract import current_clues, get_clue_dict, get_clues
+from clued._functional import ctx
+from clued._types import ClueRecord
+
+__all__ = [
+    "clue",
+    "ClueHandle",
+    "ClueRecord",
+    "clue_on_error",
+    "clue_on_error_async",
+    "ctx",
+    "get_clues",
+    "get_clue_dict",
+    "current_clues",
+]

clued-0.1.0/src/clued/_core.py

@@ -0,0 +1,97 @@
+import sys
+from collections.abc import Generator, Mapping
+from contextlib import AbstractContextManager, contextmanager
+from contextvars import ContextVar
+from copy import deepcopy
+from typing import Any, NamedTuple, final
+
+from clued._types import ClueRecord
+
+_clue_stack: ContextVar[tuple["ClueHandle", ...]] = ContextVar("clued_stack", default=())
+
+
+@final
+class CodeLocation(NamedTuple):
+    filename: str
+    lineno: int
+
+    @property
+    def code_path(self) -> str:
+        return f"{self.filename}:{self.lineno}"
+
+
+@final
+class ClueHandle:
+    """The object yielded by ``with clue(...) as handle``."""
+
+    __slots__ = ("msg", "kv", "_original_msg", "_loc", "_refine_loc")
+
+    def __init__(self, msg: str, kv: Mapping[str, Any], loc: CodeLocation) -> None:
+        self.msg = msg
+        self.kv: dict[str, Any] = dict(kv)
+        self._original_msg = msg
+        self._loc = loc
+        self._refine_loc: CodeLocation | None = None
+
+    def refine(self, msg: str | None = None, **kv: Any) -> None:
+        """Update context in-place. ``None`` values delete the key."""
+        frame = sys._getframe(1)
+        self._refine_loc = CodeLocation(frame.f_code.co_filename, frame.f_lineno)
+        del frame
+
+        if msg is not None:
+            self.msg = msg
+
+        for k, v in kv.items():
+            if v is None:
+                self.kv.pop(k, None)
+            else:
+                self.kv[k] = v
+
+    def reset(self) -> None:
+        """Restore to original msg, clear all kv, clear _refine_loc."""
+        self.msg = self._original_msg
+        self.kv.clear()
+        self._refine_loc = None
+
+    def _snapshot(self) -> tuple[str, dict[str, Any], CodeLocation]:
+        """Return current (msg, kv copy, loc) for note building."""
+        loc = self._refine_loc if self._refine_loc is not None else self._loc
+        return self.msg, dict(self.kv), loc
+
+
+def _format_note(msg: str, kv: dict[str, Any], loc: CodeLocation, depth: int) -> str:
+    note = f"- Clue {depth}: {msg} [{', '.join(f'{k}={v!r}' for k, v in kv.items())}] ({loc.code_path})"
+    return note
+
+
+def clue(msg: str, **kv: Any) -> AbstractContextManager[ClueHandle]:
+    """Context manager that attaches structured context to any exception raised within this block."""
+    # Capture caller location here — this function is called directly from user code.
+    frame = sys._getframe(1)
+    loc = CodeLocation(frame.f_code.co_filename, frame.f_lineno)
+    del frame
+    return _clue_cm(msg, kv, loc)
+
+
+@contextmanager
+def _clue_cm(msg: str, kv: Mapping[str, Any], loc: CodeLocation) -> Generator[ClueHandle, None, None]:
+    handle = ClueHandle(msg, kv, loc)
+    token = _clue_stack.set(_clue_stack.get() + (handle,))
+    try:
+        yield handle
+    except BaseException as exc_value:
+        snap_msg, snap_kv, snap_loc = handle._snapshot()
+        clues: list[ClueRecord] = exc_value.__dict__.setdefault("__clues__", [])
+        clues.append(
+            ClueRecord(
+                msg=snap_msg,
+                kv=frozenset((k, deepcopy(v)) for k, v in snap_kv.items()),
+                filename=snap_loc.filename,
+                lineno=snap_loc.lineno,
+            )
+        )
+        exc_value.add_note(_format_note(snap_msg, snap_kv, snap_loc, len(clues) - 1))
+        raise
+    finally:
+        _clue_stack.reset(token)

clued-0.1.0/src/clued/_decorator.py

@@ -0,0 +1,49 @@
+import functools
+import inspect
+from collections.abc import Callable, Coroutine
+from typing import Any, TypeVar
+
+from typing_extensions import ParamSpec
+
+from clued._core import clue
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+
+def clue_on_error(msg_template: str, **extra_kv: Any) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator that attaches a formatted clue context on error."""
+
+    def decorator(fn: Callable[P, T]) -> Callable[P, T]:
+        sig = inspect.signature(fn)
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            formatted = msg_template.format(**bound.arguments)
+            with clue(formatted, **extra_kv):
+                return fn(*args, **kwargs)
+
+        return sync_wrapper
+
+    return decorator
+
+
+def clue_on_error_async(
+    msg_template: str, **extra_kv: Any
+) -> Callable[[Callable[P, Coroutine[Any, Any, T]]], Callable[P, Coroutine[Any, Any, T]]]:
+    def decorator(fn: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, Coroutine[Any, Any, T]]:
+        sig = inspect.signature(fn)
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            formatted = msg_template.format(**bound.arguments)
+            with clue(formatted, **extra_kv):
+                return await fn(*args, **kwargs)
+
+        return async_wrapper
+
+    return decorator

clued-0.1.0/src/clued/_extract.py

@@ -0,0 +1,22 @@
+from typing import Any, cast
+
+from clued._core import ClueHandle, _clue_stack
+from clued._types import ClueRecord
+
+
+def get_clues(exc: BaseException) -> list[ClueRecord]:
+    """Return structured clue list from exception."""
+    return cast(list[ClueRecord], getattr(exc, "__clues__", []))
+
+
+def get_clue_dict(exc: BaseException) -> dict[str, Any]:
+    """Return flat merged kv dict. Inner clues override outer."""
+    result: dict[str, Any] = {}
+    for c in reversed(get_clues(exc)):  # outer first, inner overrides
+        result.update(c.kv)
+    return result
+
+
+def current_clues() -> tuple[ClueHandle, ...]:
+    """Return active clue stack from ContextVar. For logging integration."""
+    return _clue_stack.get()

clued-0.1.0/src/clued/_functional.py

@@ -0,0 +1,17 @@
+import inspect
+from typing import Any
+
+from clued._core import clue
+
+
+def ctx(fn: Any, *args: Any, msg: str, **kv: Any) -> Any:
+    """Inline wrapper: call fn(*args) inside a clue context."""
+    if inspect.iscoroutinefunction(fn):
+        return _async_ctx(fn, *args, msg=msg, **kv)
+    with clue(msg, **kv):
+        return fn(*args)
+
+
+async def _async_ctx(fn: Any, *args: Any, msg: str, **kv: Any) -> Any:
+    with clue(msg, **kv):
+        return await fn(*args)

clued-0.1.0/src/clued/_types.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ClueRecord:
+    """A single error context entry."""
+
+    msg: str
+    kv: frozenset[tuple[str, Any]]
+    filename: str
+    lineno: int