Skip to content

Add firstresult=True and wrapper=True support to AHook async dispatch - #258

Open
schuyler wants to merge 6 commits into
nextline-dev:mainfrom
schuyler:main
Open

schuyler wants to merge 6 commits into
nextline-dev:mainfrom
schuyler:main

Conversation

@schuyler

@schuyler schuyler commented Apr 30, 2026 •

Copy link
Copy Markdown

Summary

Two related additions to AHook async dispatch, building on each other:

1. firstresult=True support

AHook.__getattr__ crashes on any async hook with firstresult=True — _multicall returns a single coroutine, and asyncio.gather(*coro) raises TypeError. This adds _call_firstresult() to bypass _multicall and drive dispatch manually: iterate reversed(hookimpls), await each sequentially, return the first non-None result.

9 tests in tests/wrap/test_ahook_firstresult.py.

2. wrapper=True support

Adds _async_multicall() to handle wrapper=True hookimpls — sync generator wrappers that form middleware chains around async non-wrappers. Wrappers yield once, receive the aggregate result (or exception) via send/throw, and return a (possibly modified) result via StopIteration.value. This matches pluggy's protocol exactly.

AHook.__getattr__ now has three dispatch paths:

  • Wrappers present → _async_multicall (handles both firstresult modes)
  • No wrappers + firstresult=True → _call_firstresult
  • No wrappers + firstresult=False → hook() + asyncio.gather() (unchanged)

17 tests in tests/wrap/test_ahook_wrapper.py.

Test plan

  • All 26 new tests pass (tests/wrap/)
  • Existing apluggy tests unaffected
  • No wrappers present → existing dispatch paths unchanged (regression tests included)

@schuyler
schuyler requested a review from TaiSakuma as a code owner April 30, 2026 21:07
apluggy's AHook dispatched all hooks through pluggy's _multicall, which
returns a single coroutine (not a list) for firstresult=True hooks.
asyncio.gather(*coro) then crashes with TypeError.

Add _call_firstresult() that bypasses _multicall: detects firstresult via
hook.spec.opts, iterates reversed(hook.get_hookimpls()) to match pluggy's
execution order (tryfirst → plain → trylast), awaits each sequentially,
and stops on the first non-None result. The firstresult=False path is
unchanged.
Add _async_multicall to drive sync-generator wrappers around async
non-wrapper hookimpls. Wrappers yield once and receive the aggregate
result (or exception) via send/throw, matching pluggy's protocol.

AHook.__getattr__ now routes through _async_multicall when any wrapper
hookimpl is present, preserving the existing gather and firstresult
fast paths for the common no-wrapper case.
@schuyler schuyler changed the title Fix AHook async dispatch for firstresult=True hooks Add firstresult=True and wrapper=True support to AHook async dispatch Apr 30, 2026
schuyler and others added 4 commits November 19, 2026 13:13
Fixes #4.

## Problem

A call through `pm.ahook` that omits an argument an implementation needs
raised a bare `KeyError: 'channel'` on the firstresult path and on the
wrapper path (`_async_multicall`). The plain broadcast path goes through
pluggy's `HookCaller.__call__`, which warns and then raises
`HookCallError: hook call must provide argument 'channel'`.

## Change

- `_impl_kwargs` in `src/apluggy/wrap/ext.py` replaces the two unchecked
`caller_kwargs[k]` lookups. On a missing argument it raises
`HookCallError("hook call must provide argument '<name>'")`, naming the
first missing argument in `argnames` order, as pluggy's `_multicall`
does.
- `hook._verify_all_args_are_provided(kwargs)` is now called on the two
branches that bypass `HookCaller.__call__` (wrapper and firstresult), so
the missing-argument `UserWarning` matches the plain path.
- The plain broadcast branch, `With` and `AWith` are untouched.

## Behaviour changes to be aware of

- The error fires only when an implementation actually needs the missing
argument, same as pluggy. It is not a spec-level check.
- A call that works today but omits a spec argument that no
implementation uses now emits a `UserWarning` on the firstresult and
wrapper paths. Under `-W error` or pytest `filterwarnings=error`, such a
call now raises.
- A spec-less hook with a `wrapper=True` implementation and a missing
argument now raises `HookCallError` instead of `KeyError`, with no
warning. This matches what spec-less plain broadcast hooks already do.
- The fix calls pluggy's private `_verify_all_args_are_provided`. It
exists in pluggy 1.3.0, 1.6.0 and 1.7.0. The CI `latest` and `min` jobs
would catch a rename.

## Testing

`tests/wrap/test_ahook_missing_args.py` adds 6 tests: firstresult,
wrapper firstresult, wrapper broadcast, spec-less wrapper, and two cases
for an omitted spec argument that no implementation needs (firstresult
and wrapper).

- Full suite: 54 passed on pluggy 1.7.0, and also on 1.3.0 in a separate
environment.
- `ruff check` is clean. mypy reports the same 3 errors as before this
change.
- `tests/stack/test_exc.py::test_eq` (a hypothesis health check) failed
once in three runs on an unmodified checkout as well, so it is not
caused by this change.

## Not addressed

- Positional calls on the firstresult and wrapper paths silently drop
the positional arguments: tracked in #6.
- Old-style `hookwrapper=True` implementations with a missing argument
get `NotImplementedError` or `HookCallError` depending on implementation
order. This is unchanged in kind from before this PR.

🤖 Generated with [Claude Code](https://claude.ai/code)

https://claude.ai/code/session_01VJHmNJh9yvuLCo6GzHbTZC

Co-authored-by: Claude <noreply@anthropic.com>
…d broadcasts (#7)

corvidae's kernel needs every implementation of a broadcast hook to run
to completion, with each outcome attributed to its plugin, so it can
make observe hooks fail soft (schuyler/corvidae#1094). `pm.ahook` can't
provide that: the first exception escapes while the siblings keep
running unobserved. This PR adds a `return_exceptions=True` mode to
`AHook`, exposed as `pm.ahook_isolated`. It returns `(plugin_name,
pluggy.Result)` pairs in hook order and takes an optional
per-implementation timeout. `pm.ahook` is unchanged apart from #1's
patch, cherry-picked here, which stops a wrapper from serializing a
broadcast.

<details><summary>Agent details (Claude Code)</summary>

### Requirements (schuyler/corvidae#1095, owner rulings recorded there,
2026-11-19)

1. `AHook(pm, return_exceptions=True, timeout=None)` returns
`list[tuple[str, pluggy.Result]]` in hook order. `pm.ahook_isolated =
AHook(self, return_exceptions=True)`; `pm.ahook` stays `AHook(self)`.
2. Every implementation runs concurrently and to completion. Attribution
comes from the implementations dispatched, not list position, so `None`
results keep their pair.
3. A `BaseException` that isn't an `Exception` propagates once every
sibling has finished, the first in hook order. That includes
`KeyboardInterrupt` and `SystemExit`, with or without a timeout.
4. `timeout=` applies per implementation. An overrunning implementation
is cancelled, and its `Result` holds `asyncio.TimeoutError`. `timeout`
without `return_exceptions=True` raises `ValueError`.
5. A `firstresult=True` hook, or one with a
`wrapper=True`/`hookwrapper=True` implementation, is refused with
`HookCallError` naming the hook (and the wrapper's plugin) and pointing
at `pm.ahook`, before anything runs.
6. Keyword arguments only. A missing argument raises `HookCallError`
before anything runs (it reuses #5's `_impl_kwargs`).
7. A sync implementation's `Result` holds a `TypeError`.
8. #1's patch (`f739ea0`) lands with its tests. #3 is closed, not
landed.
9. The README documents the mode and plain `pm.ahook`'s limit.

### Design notes

- `asyncio`'s task step re-raises `KeyboardInterrupt`/`SystemExit`
straight out of the loop instead of handing them to `gather`. So the
innermost coroutine, the one that calls and awaits the implementation,
boxes them as `_Escaped`. Before 3.12, and for `timeout <= 0` on any
version, `wait_for` runs its argument in a Task of its own, which is why
the box has to sit inside `wait_for`.
- The settings are stored as `_return_exceptions`/`_timeout`, so they
can't shadow a hook of the same name.
- Like the firstresult and wrapper paths, the isolated path skips
pluggy's `_hookexec`, so tracing doesn't see these calls. The docstring
says so.

### Tests and checks

- `tests/wrap/test_ahook_isolated.py`: 14 tests, one per acceptance
criterion of requirements 1–7. All failed before the implementation
(missing attribute / constructor argument).
- **Mutation evidence** (the Red-gate reviewer ran 13 deliberately wrong
implementations):
  - Sequential awaits → `test_impls_run_concurrently` red.
- No boxing → both KI tests red at the "sibling finished" assertion, on
3.10/3.11/3.13.
- Boxing outside `wait_for` → the KI+timeout test red on 3.10/3.11
(green on 3.12+, where `wait_for` makes no Task; the CI matrix covers
it).
  - Zipping `hook()` results by position → 4 red.
  - Dropping `None` → the None test red.
  - Storage order → 5 red.
  - No refusals → 3 red.
  - Lazy kwargs → the missing-argument test red.
  - No `wait_for` → the timeout test red.
- **Full suite:** 74 passed on Python 3.10, 3.11 and 3.13.
`tests/stack/test_exc.py::test_eq` is a known-flaky hypothesis health
check that also fails intermittently on an unmodified checkout (noted in
#5). The README is doctested.
- **ruff:** clean on the changed files.
- **mypy:** 4 errors against 3 on `main`. The new one is the same `await
hook_impl.function(...)` "object is not awaitable" pattern as the
existing line 145.

### Review (Rule of Two, cold subagent reviewers)

- **Design:** 3 rounds.
  - Round 1: KI/SystemExit escape `gather`.
  - Round 2: the same class recurred on the timeout path on 3.10/3.11.
- A meta-review diagnosed the remedy as one layer too high, not a flawed
design. Round 3 passed.
- **Red:** passed (mutation-checked, as above).
- **Green + docs:** passed. One cosmetic README precision fix was
applied.
- **Skipped findings:**
  - `timeout <= 0` (the implementation never runs; out of scope).
  - `copy.copy` of an `AHook` recursing (edge).
- The missing-argument message, inherited from #5, doesn't name the
hook.
- #1's patch builds coroutines inside the gather argument list, so a
sync non-wrapper under a wrapper misbehaves. corvidae#1096 refuses sync
implementations at startup.

### Merge

The owner invoked an away-from-keyboard run that authorizes merging once
checks pass. After merge, #1 is closed as landed here.

</details>

---
_Generated by [Claude Code](https://claude.ai/code)_

---------

Co-authored-by: Claude <noreply@anthropic.com>
Closes #8. corvidae makes observe hooks fail soft by registration-time wrapping (schuyler/corvidae#1111); #7's concurrent gather for wrapped broadcasts stays. Merged with the owner's permission (live session, 2026-11-20); apluggy CI is broken, so the local suite (60 passed) stands in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJHmNL31sBmLviAVvf1hBt
…10)

A broadcast that omits an argument an implementation declares now raises HookCallError with no never-awaited coroutines left behind. The plain broadcast branch pre-binds every implementation's arguments, then delegates the call to pluggy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJHmNJYhVzkQG6B1r4dJV5

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant