Repository navigation
docs(hooks): scope plain callables to on_predict_start=/on_predict_end=, not hooks= - #987
Merged
NandhaKishorM merged 1 commit intoOct 7, 2026
Conversation
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.
4 tasks done
Owner
|
Merged in 0.3.29. A plain callable belongs to |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
docs/hooks/index.mditem 1 and thelaya/hooks.pymodule docstring both told the reader thata plain callable and a hook object are interchangeable on
hooks=. Neither is:_coerce_hooksin
laya/hooks.py:179-184raisesTypeErroron anyhooks=entry that implements none ofHOOK_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=andon_predict_end=are the plain-callable path;_StartAdapter/_EndAdapterwrap them intoHookobjects at construction.Why
The primer is the first thing a reader hits when they type
laya.load(..., hooks=[my_fn]). Theold 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_hooksremovesthat split-brain. The docstring is the same claim in
pydocand on the API page, so it goes withthe primer in the same PR rather than as a drive-by.
How it was verified
258 passed, 0 failed(was 252 before the six-assert gate appended to the same file).All checks passed!0(both files compile).Mutation harness —
laya-bench/mutate_hooks_plain_callable_scope.py, 4/4 CAUGHT (each entry is afaithful wrong implementation of exactly one clause; after every variant the tree is byte-restored
and the suite is rerun with
PYTHONDONTWRITEBYTECODE=1):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).(
docs_hooks/index.md scopes plain callable to on_predict_start=/on_predict_end=fails).laya/hooks.pymodule docstring "either a plain callable or an object"-> CAUGHT (
laya/hooks.py docstring drops 'a hook is either a plain callable'fails).hooks=TypeError raise block -> CAUGHT(
hooks= rejects a plain callable at constructionfails).Secret scan on
git diff(regexapi[_-]?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.mdhas zero open PRs.
laya/hooks.pyandtests/test_hooks.pyare touched by #908 (OptionStabilityHook),but its first hunk on
laya/hooks.pystarts at line 10 (@@ -10,13 +10,16 @@) and this PR's edit isthe 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
mainFixes #