Problem
docs/api-stability.md explicitly reserves the base_cli.experimental namespace:
base_cli.experimental is reserved for preview APIs. No experimental symbols are currently shipped. A future preview must live under that namespace, be labelled experimental in its documentation, and must not be re-exported from the stable facade until it is promoted.
However, base_cli/experimental.py (or base_cli/experimental/__init__.py) does not exist. Any consumer or tool that reads the stability docs and tries to check what is currently experimental receives:
import base_cli.experimental
# ModuleNotFoundError: No module named 'base_cli.experimental'
This is a worse user experience than an intentional empty namespace, because:
- It's indistinguishable from a typo or a missing install.
- It undermines the credibility of the stability docs — if the documented namespace doesn't exist, what else is out of sync?
- CI tooling that tries to enumerate
base_cli.* submodules may fail on the import.
Fix
Create lib/python/base_cli/experimental.py as an intentionally empty stub:
"""
Preview APIs under active development.
Names in this module are subject to change without notice. They will not be
re-exported from the stable base_cli facade until promoted. See
docs/api-stability.md for the promotion policy.
"""
__all__: list[str] = []
Add experimental to base_cli.__all__ as a module (alongside history, testing, etc.) so that import base_cli; base_cli.experimental resolves correctly.
This is a trivial change — the value is in having the namespace exist and be self-documenting when a consumer inspects it.
Problem
docs/api-stability.mdexplicitly reserves thebase_cli.experimentalnamespace:However,
base_cli/experimental.py(orbase_cli/experimental/__init__.py) does not exist. Any consumer or tool that reads the stability docs and tries to check what is currently experimental receives:This is a worse user experience than an intentional empty namespace, because:
base_cli.*submodules may fail on the import.Fix
Create
lib/python/base_cli/experimental.pyas an intentionally empty stub:Add
experimentaltobase_cli.__all__as a module (alongsidehistory,testing, etc.) so thatimport base_cli; base_cli.experimentalresolves correctly.This is a trivial change — the value is in having the namespace exist and be self-documenting when a consumer inspects it.