Skip to content

base_cli.experimental raises ModuleNotFoundError — create reserved stub module #109

Description

@codeforester

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:

  1. It's indistinguishable from a typo or a missing install.
  2. It undermines the credibility of the stability docs — if the documented namespace doesn't exist, what else is out of sync?
  3. 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.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or product improvement

Type

No type

Projects

Status
Backlog

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions