Repository navigation
[v1.0] Segment and freeze the public API facade #242
Description
Goal
Make the stable public surface deliberate and maintainable before 1.0.
Scope
- Classify exported symbols as core, integration, advanced, or provisional.
- Reduce accidental re-exports from base_cli.init.
- Publish a small core API and move optional integrations behind explicit modules/extras.
- Generate an API manifest and compatibility test for every stable symbol.
- Define deprecation and removal timelines for provisional exports.
Acceptance criteria
- The stable API is explicitly listed and reviewed.
- Optional dependencies are not required to import the core API.
- Public-symbol additions require compatibility and documentation coverage.
- The API manifest and generated reference agree.
Project fields
- Status: Backlog
- Priority: P1
- Area: Python
- Initiative: v1.0 Readiness
- Size: L
Metadata
Metadata
Assignees
Type
Projects
- Status
Activity
codeforester commentedon Sep 12, 2026
2026-09-12 repository review refresh
The public facade currently exports 124 names. Keep the basic adoption path small and classify advanced runtime, protocol, integration, and testing APIs before a v1 freeze. The 1,134-line README also says an adapter may provide async support while App.async_command()/run_async() already ship. CONTRIBUTING.md says framework-wide strict typing is separately tracked, while tests/full_validate.sh already runs strict mypy on the package. Include these entry-document corrections in the API map; do not remove public exports without the documented compatibility process.
Validated against current main (
7faf347a5b90969e169c88f3ac18e7202d142dd0). This review files and scopes work; it does not claim implementation or authorize release/admin changes.codeforester commentedon Oct 22, 2026
Implementation evidence is in PR #461: #461
The PR adds a checked-in API manifest covering all 124 facade exports, a 28-symbol
base_cli.corestarting surface, validation in the contract gate, and generated/reference documentation. Local focused/full validation is green; required hosted checks are green. The issue remains In Review pending review/merge.codeforester commentedon Oct 23, 2026
Review follow-up completed in PR #461. The core surface is now generated from the manifest, manifest/facade/core identity is enforced, malformed manifests fail with concise errors, the API-reference generator reads the manifest, and the optional-import test runs in an isolated subprocess. Commits: b10eddf, f4ff373. Full pytest and contract/style checks pass locally; all review threads are resolved.
enhancement: classify and freeze the public API surface (#242) (#461)