Repository navigation
Adopt comprehensive type hints across the codebase (PEP 604, mypy CI) #215
Description
Goal
Adopt comprehensive Python type hints across the proxybroker codebase (currently ~5% covered) so contributors get accurate IDE autocomplete, static type checking via mypy/pyright, and self-documenting public APIs.
Current state
- Existing helpers added in feat(ipv6): full IPv6 support across the stack (#201) #212 have modern type hints (PEP 604 union syntax):
canonicalize_ip,find_proxy_pairs,_format_host_port. - Rest of the codebase has none. Public API surface (Broker, Proxy, Resolver, Checker, Server) is fully untyped.
- Pyright in default mode flags hundreds of "possibly unbound" / "attribute access" warnings on the existing code, indicating real type ambiguity that hints would resolve.
Scope
Add type hints to all public APIs in:
| Module | Public surface to annotate |
|---|---|
proxybroker/api.py |
Broker.__init__, find, grab, serve, stop |
proxybroker/proxy.py |
Proxy.__init__, Proxy.create, Proxy.connect, as_text, as_json, properties |
proxybroker/resolver.py |
Resolver.__init__, host_is_ip, resolve, get_real_ext_ip, get_ip_info |
proxybroker/checker.py |
Checker, _check_test_response, _get_anonymity_lvl |
proxybroker/server.py |
Server.__init__, start, stop |
proxybroker/judge.py |
Judge, get_judges |
proxybroker/providers.py |
Provider base + concrete impls' public methods |
proxybroker/provider_utils.py |
Helper classes (already partially typed per PR #208) |
proxybroker/negotiators.py |
BaseNegotiator.negotiate signatures |
proxybroker/utils.py |
All public functions (some done in #212) |
proxybroker/errors.py |
Exception class hierarchies (low priority) |
Conventions
- PEP 604 unions (
str | None, notOptional[str]) — already adopted in feat(ipv6): full IPv6 support across the stack (#201) #212; project supports Python 3.10+. - Built-in collections (
list[str],dict[str, int]) — same rationale. from __future__ import annotationsat the top of each module to defer evaluation and avoid runtime cost.- Protocols over ABCs for callable interfaces (e.g.,
Negotiatorprotocol) where it reduces coupling.
Mypy strictness ramp-up
Start with mypy --strict-optional (catches None bugs); progress to --strict after baseline coverage. Add a CI job (matrix dim or separate workflow) that runs mypy and fails on regressions. Don't enable strict mode globally upfront — gradual adoption per-module is the only realistic path.
Acceptance criteria
- All public APIs (everything not prefixed with
_) have type hints. - Pyright's
reportGeneralTypeIssuescount forproxybroker/drops below 10 (currently ~50+). - New CI job:
mypy proxybroker/runs on every PR; fails on regression. - Internal types (e.g.,
_NewcomerProxy) typed where they reduce ambiguity at call sites. - README + docs updated to mention type-hint coverage as part of the contributor experience.
Estimated effort
- ~6-10 hours for the full coverage pass (mostly mechanical).
- ~2 hours to set up mypy CI + baseline configuration.
- 1 hour for docs.
Suggest splitting by module into 5-6 PRs of ~1-2 hours each, so each lands cleanly without a giant review burden.
Why this matters
- Refactor confidence: mypy catches "you renamed this method but missed 3 call sites" before runtime.
- Onboarding: new contributors instantly understand
def find(types, limit)isdef find(types: list[str], limit: int) -> AsyncIterator[Proxy]. - IDE quality: autocomplete + jump-to-definition work correctly. Currently
proxy.<TAB>shows everything; with hints it's targeted. - Future-proof: the Python ecosystem has fully embraced typing; untyped libraries are increasingly the outliers.
Activity
chore(release): 2.0.0b3