envoyproxy / envoyproxy/toolshed

Phased migration away from custom abstracts framework (implementer, abstraction, interface)

Open
#4,507 0 comments 0 reactions 1 assignee Claimed by @phlax View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.