Toilal / rebulk / 28249870856

96%

master: 97%

Build Type

push

github

Committed by Toilal

Commit Message

feat(typing): precise return types for query methods via @overload

The library ships py.typed and runs mypy --strict, yet every query method
on Matches/Match returned Any because filter_index() returns a list, a
single Match, or None depending on whether index is passed. Downstream
users therefore got no usable type information.

Add @overload signatures so the return type is now:
- list[Match] when no index is given
- Match | None when index (or a predicate-as-int shortcut) is given

Covered: named, tagged, starting, ending, previous, next, conflicting,
at_match, at_span, at_index, range, holes, chain_before, chain_after
(Matches) and crop, split (Match). Pattern.matches / BasePattern.matches
gain Literal[bool] overloads so with_raw_matches=True yields a tuple and
the default yields list[Match]; Chain.matches is aligned (its prior
type: ignore[override] is no longer needed).

Pure typing change, no runtime behavior change. Redundant casts that the
new signatures make unnecessary are removed, and a few tests are narrowed
where a method now correctly returns Match | None.

Closes #33

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Coverage Stats

136 of 136 new or added lines in 4 files covered. (100.0%)

17 existing lines in 3 files now uncovered.

1718 of 1789 relevant lines covered (96.03%)

6.7 hits per line