Skip to content

Add partial type stubs for core modules - #95

Open
heejaechang wants to merge 1 commit into
Pylons:mainfrom
heejaechang:heejaechang-complete-bundled-stubs
Open

Add partial type stubs for core modules#95
heejaechang wants to merge 1 commit into
Pylons:mainfrom
heejaechang:heejaechang-complete-bundled-stubs

Conversation

@heejaechang

Copy link
Copy Markdown

Summary

  • add complete sidecar stubs for hupper.interfaces, hupper.logger, hupper.polling, and hupper.utils
  • ship the PEP 561 py.typed marker in wheels and sdists
  • preserve each touched module's complete public runtime surface, including real reexports, mutable fields, nominal ABC/Thread inheritance, parameter names, and defaults

This is intentionally partial. hupper.watchdog remains unstubbed because its real platform-selected watchdog.observers.Observer base is not a legal static base alias and its concrete external bases remain partially unknown under unfiltered VerifyTypes. ipc/worker/reloader also remain unstubbed because the Windows IPC surface publicly reexports hupper.winapi, including the real partially-unknown ctypes.WinDLL object. Hiding or replacing either boundary would misrepresent the runtime API.

Type completeness

Exact unfiltered pyright --verifytypes hupper --outputjson, without --ignoreexternal:

Environment Before After
watchdog 6.0 installed 29.20% (80 known / 23 ambiguous / 171 unknown; 274 total) 48.43% (139 known / 20 ambiguous / 128 unknown; 287 total)
watchdog absent 29.20% 48.43%

The 13 added denominator symbols are real runtime reexports made explicit by the complete touched-module stubs; no exports were invented or hidden. Every touched export is known.

Validation

  • strict Pyright and mypy compile all four stubs and positive consumers
  • adversarial consumers reject wrong callback arity, invalid factory returns, incomplete monitors, nominal logger impostors, and streams without isatty
  • exact runtime/stub comparison passes for module names, class members, instance/class fields, signature names/kinds/defaults, and MROs
  • unflagged scoped python -m mypy.stubtest passes all four modules in fresh wheels with watchdog installed and absent
  • full stubtest reaches only documented untouched source errors (watchdog.Observer, conditional winapi/ipc, and removed distutils)
  • tox format, lint, check-manifest, build, twine, and coverage tasks pass
  • Python 3.9, 3.12, 3.13, 3.14, and 3.15 produce the same clean-main result: 8 tests pass and 2 existing integration tests fail because current pytest-cov no longer provides pytest_cov.embed
  • fresh installed wheels pass polling delivery, logger/ABC checks, and a real spawned subprocess IPC round-trip, both with watchdog installed and absent
  • wheel and sdist contain exactly the four .pyi files plus py.typed; runtime .py hashes are unchanged

Local limitations: Python 3.7, 3.8, 3.10, 3.11, PyPy, and POSIX were unavailable. Pyright's Python 3.7 mode accepts the stubs; mypy 1.4.1 accepts the four stubs for Python 3.7. The docs tox environment matches clean main by failing only because POSIX make is unavailable on this Windows host.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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