Add reserved experimental namespace

CHANGELOG.md

@@ -102,6 +102,8 @@ the API stability policy and migration guide before upgrading from `0.3.x`.
 
 - Add the MkDocs documentation site configuration, strict documentation checks,
   and GitHub Pages deployment workflow.
+- Add the importable, intentionally empty `base_cli.experimental` namespace for
+  future preview APIs without expanding the stable API surface.
 
 ### Changed
 

docs/api-stability.md

@@ -27,10 +27,10 @@ and history implementation details are not stable machine interfaces unless a
 separate contract document says otherwise. Consumers that need automation
 should select the JSON or record protocol contracts.
 
-`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.
+The importable `base_cli.experimental` module 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.
 
 ## Versioning and compatibility
 

lib/python/base_cli/__init__.py

@@ -30,7 +30,17 @@ def _resolve_version() -> str:
 
 __version__ = _resolve_version()
 
-from . import command_filters, command_protocol, deprecations, extensions, history, integrations, json_contracts, testing
+from . import (
+    command_filters,
+    command_protocol,
+    deprecations,
+    experimental,
+    extensions,
+    history,
+    integrations,
+    json_contracts,
+    testing,
+)
 from .attachment import (
     AttachmentAdapter,
     AttachmentContextFactory,
@@ -182,6 +192,7 @@ def _resolve_version() -> str:
     "command_matches",
     "command_protocol",
     "deprecations",
+    "experimental",
     "json_contracts",
     "JSON_CONTRACT_VERSION",
     "JSON_ERROR_SCHEMA",

lib/python/base_cli/experimental.py

@@ -0,0 +1,8 @@
+"""Preview APIs under active development.
+
+Names in this module are subject to change without notice. They will not be
+re-exported from the stable :mod:`base_cli` facade until promoted. See
+``docs/api-stability.md`` for the promotion policy.
+"""
+
+__all__: list[str] = []

tests/test_api_stability.py

@@ -55,6 +55,7 @@
         "command_matches",
         "command_protocol",
         "deprecations",
+        "experimental",
         "json_contracts",
         "JSON_CONTRACT_VERSION",
         "JSON_ERROR_SCHEMA",

tests/test_public_api.py

@@ -12,6 +12,7 @@
     command_protocol,
     config,
     deprecations,
+    experimental,
     history,
     json_contracts,
     lifecycle_options,
@@ -62,6 +63,7 @@ def test_facade_exports_supported_modules_functions_and_types(self) -> None:
             "command_filters",
             "command_matches",
             "command_protocol",
+            "experimental",
             "dumps_record",
             "dumps_records",
             "get_command_app",
@@ -83,6 +85,7 @@ def test_facade_exports_supported_modules_functions_and_types(self) -> None:
         self.assertIs(base_cli.typer, typer)
         self.assertIs(base_cli.json_contracts, json_contracts)
         self.assertIs(base_cli.deprecations, deprecations)
+        self.assertIs(base_cli.experimental, experimental)
         self.assertTrue(issubclass(base_cli.ConfigurationError, ValueError))
 
     def test_module_all_surfaces_are_explicit(self) -> None:
@@ -160,6 +163,7 @@ def test_module_all_surfaces_are_explicit(self) -> None:
             },
         )
         self.assertEqual(set(deprecations.__all__), {"BaseCliDeprecationWarning", "deprecated"})
+        self.assertEqual(experimental.__all__, [])
         self.assertEqual(base_cli.testing.__all__, ["invoke"])
 
     def test_entry_points_have_docstrings(self) -> None: