Skip to content

docs(hooks): scope plain callables to on_predict_start=/on_predict_end=, not hooks= - #987

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:fix-hooks-plain-callable-scope
Oct 7, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:fix-hooks-plain-callable-scope

Conversation

@aashish254

Copy link
Copy Markdown
Contributor

What

docs/hooks/index.md item 1 and the laya/hooks.py module docstring both told the reader that
a plain callable and a hook object are interchangeable on hooks=. Neither is: _coerce_hooks
in laya/hooks.py:179-184 raises TypeError on any hooks= entry that implements none of
HOOK_EVENTS = ("on_predict_start", "on_predict_end", "on_route", "on_load", "on_evict", "on_error"),
and the raise's own message says "Pass a plain callable as on_predict_start= / on_predict_end=
instead." This PR scopes the two pages to what the code enforces:

  • hooks= takes only the object form (an instance carrying one or more lifecycle methods).
  • on_predict_start= and on_predict_end= are the plain-callable path; _StartAdapter /
    _EndAdapter wrap them into Hook objects at construction.

Why

The primer is the first thing a reader hits when they type laya.load(..., hooks=[my_fn]). The
old sentence promised the shape that the constructor refuses, so the crash message the user sees
contradicts the documentation they just read. Fixing the prose to match _coerce_hooks removes
that split-brain. The docstring is the same claim in pydoc and on the API page, so it goes with
the primer in the same PR rather than as a drive-by.

How it was verified

python -B tests/test_hooks.py

258 passed, 0 failed (was 252 before the six-assert gate appended to the same file).

ruff check laya/hooks.py tests/test_hooks.py --select=E9,F63,F7,F82,F401,F811 --line-length=120

All checks passed!

python -B -m compileall -q laya/hooks.py tests/test_hooks.py

0 (both files compile).

Mutation harness — laya-bench/mutate_hooks_plain_callable_scope.py, 4/4 CAUGHT (each entry is a
faithful wrong implementation of exactly one clause; after every variant the tree is byte-restored
and the suite is rerun with PYTHONDONTWRITEBYTECODE=1):

  • m1 restore the pre-fix Both are passed to \hooks=` / `on_predict_start=` / `on_predict_end=`.ondocs/hooks/index.md -> CAUGHT (docs_hooks/index.md drops the ... equal-share claim` fails).
  • m2 drop only the scoping sentence, keep the rest of the paragraph -> CAUGHT
    (docs_hooks/index.md scopes plain callable to on_predict_start=/on_predict_end= fails).
  • m3 restore the pre-fix laya/hooks.py module docstring "either a plain callable or an object"
    -> CAUGHT (laya/hooks.py docstring drops 'a hook is either a plain callable' fails).
  • m4 remove the hooks= TypeError raise block -> CAUGHT
    (hooks= rejects a plain callable at construction fails).

Secret scan on git diff (regex api[_-]?key|secret|token|password|credential|bearer|BEGIN (RSA|PRIVATE)) -> no hits.

Deconfliction (gh pr list --state open --json number,title,files, 53 open PRs): docs/hooks/index.md
has zero open PRs. laya/hooks.py and tests/test_hooks.py are touched by #908 (OptionStabilityHook),
but its first hunk on laya/hooks.py starts at line 10 (@@ -10,13 +10,16 @@) and this PR's edit is
the module docstring on lines 1-8; #908's tests are added inside the existing suite, this PR appends
the gate block below the report. Hunks are disjoint.

Checklist

  • Focused on one change (split unrelated work into another PR)
  • Rebased on the latest main
  • Tests pass locally
  • Docs or examples updated when the public API changed

Fixes #

The primer and the module docstring said a hook on `hooks=` may be a plain callable.
`_coerce_hooks` in laya/hooks.py:179-184 raises TypeError for any entry without one of
HOOK_EVENTS. The correct wording scopes bare callables to the two single-event parameters.

Adds a six-assert gate in tests/test_hooks.py that bans the pre-fix phrase, requires the new
scoping sentence, and drives both paths through normalise_hooks.
@NandhaKishorM
NandhaKishorM merged commit 5c6967f into NandhaKishorM:main Oct 7, 2026
32 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged in 0.3.29.

A plain callable belongs to on_predict_start= and on_predict_end=, not to hooks=, and the pages implied otherwise. A reader who passes a bare function to hooks= gets no hook and no error, which is the same silent-drop failure #936 fixed on the TypeScript batch path in the last release.

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.

2 participants