log-foundry 0.10.2.dev127__tar.gz → 0.10.2.dev128__tar.gz

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev128}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev127
+Version: 0.10.2.dev128
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -347,7 +347,7 @@ lands can arrive at a sink whose close has already run, and nothing owes that si
 
 ### `@trace`
 
-Decorate any **synchronous** function. Usable bare or with arguments:
+Decorate a function, sync or async. Usable bare or with arguments:
 
 ```python
 @lf.trace                                  # span name = func.__qualname__
@@ -363,7 +363,10 @@ def process(): ...
 
 `@trace` refuses at decoration what it cannot trace, with a `TypeError` naming the function:
 a `@classmethod` or `@staticmethod` written *below* it (put them above), a bare string
-(`@trace("checkout")` meant `@trace(name="checkout")`), and anything not callable.
+(`@trace("checkout")` meant `@trace(name="checkout")`), anything not callable, and a
+**generator function** (sync or async, including one behind `@contextmanager`, `@lru_cache` or
+any `functools.wraps` wrapper) — its body runs after the wrapper has returned, so the span would
+close before it started. Trace the consumer instead: the function that iterates it.
 
 The **outermost** decorated call starts a new trace; every nested decorated call becomes a
 child span within it. On an exception, the decorator records `status="error"` plus an `error`

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev128}/README.md

@@ -296,7 +296,7 @@ lands can arrive at a sink whose close has already run, and nothing owes that si
 
 ### `@trace`
 
-Decorate any **synchronous** function. Usable bare or with arguments:
+Decorate a function, sync or async. Usable bare or with arguments:
 
 ```python
 @lf.trace                                  # span name = func.__qualname__
@@ -312,7 +312,10 @@ def process(): ...
 
 `@trace` refuses at decoration what it cannot trace, with a `TypeError` naming the function:
 a `@classmethod` or `@staticmethod` written *below* it (put them above), a bare string
-(`@trace("checkout")` meant `@trace(name="checkout")`), and anything not callable.
+(`@trace("checkout")` meant `@trace(name="checkout")`), anything not callable, and a
+**generator function** (sync or async, including one behind `@contextmanager`, `@lru_cache` or
+any `functools.wraps` wrapper) — its body runs after the wrapper has returned, so the span would
+close before it started. Trace the consumer instead: the function that iterates it.
 
 The **outermost** decorated call starts a new trace; every nested decorated call becomes a
 child span within it. On an exception, the decorator records `status="error"` plus an `error`

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev128}/pyproject.toml

@@ -74,7 +74,7 @@ keywords = [
 # vulnerability-reporting channel. The repository is still named `log-forge` — the ORIGINAL name,
 # which PyPI rejected for the distribution — so these URLs deliberately do not match the package
 # name. See the note on `name` above before "correcting" them.
-version = "0.10.2.dev127"
+version = "0.10.2.dev128"
 
 [project.urls]
 Homepage = "https://github.com/agriffi10/log-forge"

{log_foundry-0.10.2.dev127 → log_foundry-0.10.2.dev128}/src/log_foundry/decorator.py

@@ -639,6 +639,21 @@ def _refuse_unusable(fn: object) -> None:
     ``self`` to a function declared without one. A ``str`` is the slip ``@trace("checkout")``,
     which meant ``name=``. Anything else that is not callable is refused by type.
 
+    A generator function or an async generator function is refused too (SPEC-055 FR-003): its
+    body runs after the wrapper has returned the generator object, so the span would open and
+    close before a single line of it ran, and every event the body logged would be an orphan on
+    a fresh trace — measured, ``['span.start', 'span.end']`` before the first ``next()``. The
+    check is the code flags, on ``fn``, on whatever ``fn`` advertises through ``__wrapped__``
+    — so ``@trace`` above ``@contextmanager``, ``@lru_cache`` or any ``functools.wraps`` wrapper
+    of a generator is refused too, each measured recording the same orphaned ``inside`` event —
+    and on the type's ``__call__`` for a callable instance; all of them see through a
+    ``functools.partial``. A plain function that merely *returns* a generator object without
+    advertising it is indistinguishable here and is not detected, which is a stated limit
+    rather than a gap to close at call time, where invariant 13 does not refuse. Wrapping the
+    iteration instead — a span per generator, pushed around every resumption — was considered
+    and deferred: a refusal can be lifted into a wrap later without breaking anyone, while a
+    wrap shipped first freezes its semantics at 1.0.
+
     Args:
       fn: Whatever was handed to the decorator.
 
@@ -646,8 +661,8 @@ def _refuse_unusable(fn: object) -> None:
       None.
 
     Raises:
-      TypeError: If ``fn`` is a ``classmethod`` or ``staticmethod`` object, a ``str``, or not
-        callable at all.
+      TypeError: If ``fn`` is a ``classmethod`` or ``staticmethod`` object, a ``str``, not
+        callable at all, or a generator function or async generator function.
       Exception: Whatever the callable's own attribute access raises — a ``__class__`` property,
         say — at decoration, in the caller's frame, which is invariant 13's moment.
     """
@@ -664,6 +679,61 @@ def _refuse_unusable(fn: object) -> None:
         )
     if not callable(fn):
         raise TypeError(f"@trace needs a callable, got {type(fn).__name__}")
+    if _is_generator_function(fn):
+        raise TypeError(
+            f"@trace cannot trace the iteration of the generator function {_span_name(fn)}: its "
+            f"body runs after the wrapper has returned, so the span would close before it "
+            f"starts. Trace the consumer instead: the function that iterates it"
+        )
+
+
+def _is_generator_function(fn: object) -> bool:
+    """Reports whether a callable's body is a generator or async generator (SPEC-055 FR-003).
+
+    The same shape as :func:`_is_async`: the code flags of ``fn`` itself, which see through a
+    ``functools.partial``; then of whatever ``fn`` advertises through ``__wrapped__``, which is
+    how ``@contextmanager``, ``@lru_cache`` and every ``functools.wraps`` wrapper point back at
+    the generator they wrap; and for anything that is not a plain function the type's
+    ``__call__`` as well, so a callable instance whose ``__call__`` yields is caught too. The
+    unwrap is guarded because :func:`inspect.unwrap` raises ``ValueError`` on a ``__wrapped__``
+    cycle, and a cycle is not a generator.
+
+    Args:
+      fn: The callable being decorated.
+
+    Returns:
+      Whether ``fn`` would return a generator or async generator object when called.
+
+    Raises:
+      Exception: Whatever the callable's own ``__class__``, ``__call__`` or ``__wrapped__``
+        lookup raises, at decoration, in the caller's frame.
+    """
+    if _yields(fn):
+        return True
+    try:
+        target = inspect.unwrap(cast("Callable[..., Any]", fn))
+    except ValueError:
+        target = fn
+    if target is not fn and _yields(target):
+        return True
+    if inspect.isfunction(fn):
+        return False
+    return _yields(type(fn).__call__)
+
+
+def _yields(fn: object) -> bool:
+    """Reads a callable's code flags for a generator or async generator body.
+
+    Args:
+      fn: The callable to inspect.
+
+    Returns:
+      Whether its body is a generator or an async generator.
+
+    Raises:
+      None.
+    """
+    return inspect.isgeneratorfunction(fn) or inspect.isasyncgenfunction(fn)
 
 
 def _span_name(fn: object) -> str:
@@ -749,8 +819,10 @@ def trace(
 
     Raises:
       TypeError: At decoration, for a ``classmethod`` or ``staticmethod`` object (the decorators
-        are in the wrong order), a ``str`` (``name=`` was meant), anything not callable, or a
-        ``name=`` that is not a ``str`` (SPEC-055 FR-002, invariant 13).
+        are in the wrong order), a ``str`` (``name=`` was meant), anything not callable, a
+        ``name=`` that is not a ``str`` (SPEC-055 FR-002), or a generator function, whose
+        iteration cannot be traced by a wrapper around the call (SPEC-055 FR-003) — invariant
+        13.
     """
     span_defaults = None if defaults is None else dict(defaults)