envoyproxy / envoyproxy/toolshed
Phased migration away from custom abstracts framework (implementer, abstraction, interface)
- Dominant language
- Python
- Stars
- 12
- Forks
- 24
- Avg merge
- 6h 37m
- Merged PRs (30d)
- 92
Description
A phased plan for migration off the current custom `abstracts` (implementer, interface, abstraction) to a smaller, safer and more maintainable model that uses the stdlib `abc`+salvaged helpers.
## Phase 1: Fix current `abstracts` issues
- Fix early `return` in `add_docs` (should be `continue`)
- Fix (or document+test) precedence direction in implementation_info
- Fix misleading TypeError message in `abstract_info`
- Correct `@implementer` return annotation and update affected call sites for better type safety
- Add/fix test for synthetic subclass oddities (slots, qualname, pickling)
- Encourage use of explicit class-keyword path over decorator (do not deprecate yet)
## Phase 2: Add `abstracts2`
- New module that:
- Exposes `Abstraction`, `Interface` as subclasses of `abc.ABC`
- Provides `@implements` decorator (does no synthetic subclassing — mutates class directly; can replace both the decorator and class-keyword forms)
- Offers `interfacemethod` helper that raises always (like today, but less magical)
- Exposes `provides(obj, iface)` and `implementations(iface)` as future hooks for adapter/lookup registry
- Has a trivial stub `resolve(obj, iface)` (identity if isinstance, else LookupError) — but signature and import are reserved for future use
- Tests to validate that all testable discipline enforced in current `abstracts` can be replicated by `abstracts2`+unittest
## Phase 3: Migrate consumers
- Switch internal packages to import from `abstracts2` (can be codemodded as most usage is mechanical)
- Clean up any use of the decorator form that relies on synthetic class (resolve test breakage for pickling, __qualname__, slots etc)
- Any places that need true adapter semantics can switch to using `resolve()` but this is not required in the migration plan
## Phase 4 (later): Deprecate legacy `abstracts`
- Alias old `abstracts` to new API with DeprecationWarning
- Optionally remove after downstreams have migrated
---
Ticket is to plan and coordinate the migration (sub-issues can track each phase).
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.