diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 410d81b..bf0b4bd 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,6 +11,7 @@ on: - "mkdocs.yml" - "pyproject.toml" - "scripts/validate_docs.py" + - "scripts/generate_api_reference.py" - "tests/validate.sh" - ".github/workflows/docs.yml" pull_request: @@ -21,6 +22,7 @@ on: - "mkdocs.yml" - "pyproject.toml" - "scripts/validate_docs.py" + - "scripts/generate_api_reference.py" - "tests/validate.sh" - ".github/workflows/docs.yml" workflow_dispatch: @@ -52,6 +54,9 @@ jobs: - name: Validate repository links and examples run: python scripts/validate_docs.py + - name: Validate generated public API reference + run: python scripts/generate_api_reference.py --check + - name: Build documentation with strict warnings run: python -m mkdocs build --strict --site-dir site diff --git a/CHANGELOG.md b/CHANGELOG.md index 86fa707..3811523 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,8 @@ and versions are tracked in the repo-root `VERSION` file. production-lifecycle positioning for Click and Typer adopters. - Add deterministic SPDX SBOMs, artifact checksums, and OIDC-backed GitHub attestations to protected release workflows. +- Add a generated public API reference and a strict CI drift check so every + stable facade export remains searchable and documented. ### Changed diff --git a/README.md b/README.md index 7884f0b..e98e431 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,8 @@ The supported public facade, compatibility promises, deprecation warning mechanism, and migration requirements are documented in [`docs/api-stability.md`](https://basefoundry.github.io/base-cli/api-stability/) and [`docs/migrations.md`](https://basefoundry.github.io/base-cli/migrations/). +The complete generated facade is listed in the +[`public API reference`](https://basefoundry.github.io/base-cli/api-reference/). Security reporting, runtime trust boundaries, threat assumptions, and the release security checklist are documented in [`SECURITY.md`](SECURITY.md), diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..5300181 --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,1974 @@ +# Public API reference + +This page is generated from `base_cli.__all__`. It is the complete stable +facade: private modules and names are deliberately excluded. Each entry +includes the runtime signature when Python can inspect one, the public +docstring summary, compatibility guidance, and a minimal usage shape. +For behavior that is shared by several symbols, follow the linked +versioned contracts and the source annotations. + +!!! note + Regenerate this page after changing a public export: + `python scripts/generate_api_reference.py`. CI runs the same command + in check mode and fails when the committed page is stale. + + + +The facade currently documents **124** public symbols. + +## Classes and protocols + +### `App` +**Kind:** class +**Signature:** `App(name: 'str | None' = None, version: 'str | None' = None, help: 'str | None' = None, log_to_file: 'bool' = True, max_log_files: 'int | None' = None, profile: 'CliProfile | None' = None, lifecycle_options: 'LifecycleOptions | None' = None, retention: 'RetentionPolicy | None' = None, max_run_bundles: 'int | None' = None, max_run_age_seconds: 'float | None' = None, max_run_total_bytes: 'int | None' = None, rich: 'bool' = False, telemetry: 'TelemetryOptions | None' = None) -> 'None'` + +**Behavior:** Define a Click-backed command with a shared runtime lifecycle. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.App(...) +``` + +### `AttachmentAdapter` +**Kind:** class +**Signature:** `AttachmentAdapter(*args, **kwargs)` + +**Behavior:** Lifecycle adapter contract implemented by :class:`base_cli.App`. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.AttachmentAdapter(...) +``` + +### `AttachmentContextFactory` +**Kind:** class +**Signature:** `AttachmentContextFactory(*args, **kwargs)` + +**Behavior:** Create consumer-owned application state for an active Context. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.AttachmentContextFactory(...) +``` + +### `AttachmentContract` +**Kind:** class +**Signature:** `AttachmentContract(app: 'Any', command: 'CommandT', context_factory: 'Callable[[Context[Any, Any, Any]], Any] | None', service_factory: 'Callable[[Context[Any, Any, Any]], Any] | None', sensitive_parameters: 'frozenset[str]', lifecycle_options: 'Any', standard_bindings: 'dict[str, Any]') -> None` + +**Behavior:** Immutable attachment state shared by the private Click adapter. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.AttachmentContract(...) +``` + +### `AttachmentServiceFactory` +**Kind:** class +**Signature:** `AttachmentServiceFactory(*args, **kwargs)` + +**Behavior:** Create consumer-owned services for an active Context. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.AttachmentServiceFactory(...) +``` + +### `TyperAdapter` +**Kind:** class +**Signature:** `TyperAdapter(typer_app: '_TyperApp') -> 'None'` + +**Behavior:** Attach one Typer application to a base-cli lifecycle. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.TyperAdapter(...) +``` + +### `BatteriesIncludedConfigLoader` +**Kind:** class +**Signature:** `BatteriesIncludedConfigLoader(cli_name: 'str', *, user_config_dir: 'Path', user_config_name: 'str' = 'config.yaml', project_config_name: 'str' = '.base-cli.yaml', environment_dir_name: 'str' = 'environments') -> 'None'` + +**Behavior:** Load conventional user, project, environment, and explicit layers. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.BatteriesIncludedConfigLoader(...) +``` + +### `BaseCliDeprecationWarning` +**Kind:** class +**Signature:** (value is not callable) + +**Behavior:** Warning emitted when a supported base-cli API is being retired. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.BaseCliDeprecationWarning(...) +``` + +### `CliProfile` +**Kind:** class +**Signature:** `CliProfile(discover_project: 'ProjectDiscovery', load_user_config: 'UserConfigLoader', load_config: 'ConfigLoader', resolve_runtime: 'RuntimeResolver', history_writer: 'HistoryWriter | None' = None, display_command: 'DisplayCommandResolver' = , history_display_command: 'HistoryDisplayResolver' = , resolve_workspace_root: 'WorkspaceRootResolver' = , load_config_for_environment: 'EnvironmentConfigLoader | None' = None) -> None` + +**Behavior:** Policy boundary between the generic CLI lifecycle and its consumer. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.CliProfile(...) +``` + +### `ConfigLoader` +**Kind:** class +**Signature:** `ConfigLoader(*args, **kwargs)` + +**Behavior:** Load validated framework configuration and opaque consumer settings. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ConfigLoader(...) +``` + +### `ConfigSnapshot` +**Kind:** class +**Signature:** `ConfigSnapshot(config: 'dict[str, Any]', framework: 'FrameworkConfig', provenance: 'Mapping[str, str]') -> None` + +**Behavior:** One deterministic layered configuration result. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ConfigSnapshot(...) +``` + +### `CommandCodec` +**Kind:** class +**Signature:** `CommandCodec(registry: 'CommandSchemaRegistry | None' = None) -> 'None'` + +**Behavior:** Encode and decode records using one isolated schema registry. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.CommandCodec(...) +``` + +### `CommandProtocolError` +**Kind:** class +**Signature:** (value is not callable) + +**Behavior:** Raised when a command-protocol schema or payload violates its contract. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.CommandProtocolError(...) +``` + +### `CommandSchemaRegistry` +**Kind:** class +**Signature:** `CommandSchemaRegistry() -> 'None'` + +**Behavior:** Own an isolated set of command record schemas. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.CommandSchemaRegistry(...) +``` + +### `ConfigurationError` +**Kind:** class +**Signature:** (value is not callable) + +**Behavior:** A user-correctable configuration error that is safe to show. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ConfigurationError(...) +``` + +### `CommandExtension` +**Kind:** class +**Signature:** `CommandExtension(*args, **kwargs)` + +**Behavior:** Callable contract for ``base_cli.commands`` entry points. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.CommandExtension(...) +``` + +### `Context` +**Kind:** class +**Signature:** `Context(cli_name: 'str', run_id: 'str', state_dir: 'Path', log_dir: 'Path', cache_dir: 'Path', temp_dir: 'Path', log_file: 'Path | None', config: 'ConfigT', environment: 'str', debug: 'bool', keep_temp: 'bool', log: 'logging.Logger', dry_run: 'bool' = False, application_home: 'Path | None' = None, project_root: 'Path | None' = None, manifest_path: 'Path | None' = None, project_name: 'str | None' = None, history_scope: 'str' = 'primary', history_parent_run_id: 'str | None' = None, user_config: 'object | None' = None, history_display_command: 'Callable[[str, list[str]], str]' = , cleanup_hooks: 'list[Callable[[], None]]' = , workspace_root: 'Path | None' = None, quiet: 'bool' = False, runtime_owner: 'str' = 'default', owner_root: 'Path | None' = None, run_root: 'Path | None' = None, application_context: 'ApplicationStateT | None' = None, services: 'ServicesT | None' = None, framework_config: 'FrameworkConfig | None' = None, config_provenance: 'Mapping[str, str]' = , json_output: 'bool' = False, rich: 'bool' = False) -> None` + +**Behavior:** Runtime state and cleanup hooks available to an active CLI command. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.Context(...) +``` + +### `ExtensionCompatibilityError` +**Kind:** class +**Signature:** `ExtensionCompatibilityError(descriptor: 'ExtensionDescriptor', supported: 'Sequence[str]') -> 'None'` + +**Behavior:** Raised when an extension declares an unsupported SDK version. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExtensionCompatibilityError(...) +``` + +### `ExtensionCollisionError` +**Kind:** class +**Signature:** `ExtensionCollisionError(group: 'str', name: 'str', descriptors: 'Sequence[ExtensionDescriptor]') -> 'None'` + +**Behavior:** Raised when more than one distribution claims the same extension name. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExtensionCollisionError(...) +``` + +### `ExtensionDescriptor` +**Kind:** class +**Signature:** `ExtensionDescriptor(group: 'str', name: 'str', value: 'str', distribution: 'str | None', version: 'str | None', extras: 'tuple[str, ...]' = (), api_version: 'str' = '1', capabilities: 'tuple[str, ...]' = ()) -> None` + +**Behavior:** Stable metadata for one entry point, before its object is loaded. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExtensionDescriptor(...) +``` + +### `ExtensionDiscovery` +**Kind:** class +**Signature:** `ExtensionDiscovery(*, disabled: 'bool' = False, allowlist: 'Iterable[str] | None' = None, entry_points: 'Iterable[Any] | EntryPointProvider | None' = None, paths: 'Iterable[Path] | None' = None, supported_api_versions: 'Iterable[str]' = ('1',)) -> 'None'` + +**Behavior:** Discover and lazily load command, profile, and plugin entry points. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExtensionDiscovery(...) +``` + +### `ExtensionDiscoveryError` +**Kind:** class +**Signature:** (value is not callable) + +**Behavior:** Base class for actionable extension discovery failures. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExtensionDiscoveryError(...) +``` + +### `ExtensionLoadError` +**Kind:** class +**Signature:** `ExtensionLoadError(descriptor: 'ExtensionDescriptor', cause: 'BaseException') -> 'None'` + +**Behavior:** Wrap an extension import failure without hiding its source metadata. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExtensionLoadError(...) +``` + +### `ExtensionLoadResult` +**Kind:** class +**Signature:** `ExtensionLoadResult(descriptor: 'ExtensionDescriptor', value: 'Any | None' = None, error: 'ExtensionLoadError | None' = None) -> None` + +**Behavior:** Result of an isolated bulk extension load. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExtensionLoadResult(...) +``` + +### `ExtensionsDisabledError` +**Kind:** class +**Signature:** (value is not callable) + +**Behavior:** Raised when a caller attempts to load an extension while disabled. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExtensionsDisabledError(...) +``` + +### `DisplayCommandResolver` +**Kind:** class +**Signature:** `DisplayCommandResolver(*args, **kwargs)` + +**Behavior:** Resolve the process-facing command label used in diagnostics. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.DisplayCommandResolver(...) +``` + +### `EnvironmentConfigLoader` +**Kind:** class +**Signature:** `EnvironmentConfigLoader(*args, **kwargs)` + +**Behavior:** Load configuration with an explicitly selected environment. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.EnvironmentConfigLoader(...) +``` + +### `ExitCode` +**Kind:** class +**Signature:** `ExitCode()` + +**Behavior:** Standard command exit code constants. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ExitCode(...) +``` + +### `FieldSpec` +**Kind:** class +**Signature:** `FieldSpec(value_type: 'str', nullable: 'bool' = False) -> None` + +**Behavior:** Describe the wire type and nullability of one command-record field. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.FieldSpec(...) +``` + +### `FrameworkConfig` +**Kind:** class +**Signature:** `FrameworkConfig(environment: 'str' = 'dev', log_level: 'str | None' = None, keep_temp: 'bool' = False) -> None` + +**Behavior:** Validated lifecycle settings separated from consumer configuration. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.FrameworkConfig(...) +``` + +### `LifecycleOption` +**Kind:** class +**Signature:** `LifecycleOption(*param_decls: 'str', name: 'str | None' = None, help: 'str | None' = None, metavar: 'str | None' = None, envvar: 'str | tuple[str, ...] | list[str] | None' = None, show_envvar: 'bool' = False, show_default: 'bool | str | None' = None, hidden: 'bool' = False, default: 'Any' = None) -> 'None'` + +**Behavior:** Immutable public configuration for one lifecycle-owned Click option. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.LifecycleOption(...) +``` + +### `LifecycleOptions` +**Kind:** class +**Signature:** `LifecycleOptions(debug: 'LifecycleOption | None' = , quiet: 'LifecycleOption | None' = , environment: 'LifecycleOption | None' = , config: 'LifecycleOption | None' = , keep_temp: 'LifecycleOption | None' = , log_file: 'LifecycleOption | None' = , version: 'LifecycleOption | None' = , dry_run: 'LifecycleOption | None' = None, json: 'LifecycleOption | None' = None) -> None` + +**Behavior:** Composable option policy used by native and attached applications. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.LifecycleOptions(...) +``` + +### `LifecycleValues` +**Kind:** class +**Signature:** `LifecycleValues(debug: 'bool' = False, quiet: 'bool' = False, environment: 'str | None' = None, config: 'Path | None' = None, keep_temp: 'bool' = False, log_file: 'Path | None' = None, dry_run: 'bool' = False, json: 'bool' = False) -> None` + +**Behavior:** Normalized lifecycle values resolved for the active Click context. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.LifecycleValues(...) +``` + +### `JsonLogFormatter` +**Kind:** class +**Signature:** `JsonLogFormatter(run_id: 'str | None' = None) -> 'None'` + +**Behavior:** Format one ``LogRecord`` as a bounded, redacted JSON object. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.JsonLogFormatter(...) +``` + +### `NdjsonWriter` +**Kind:** class +**Signature:** `NdjsonWriter(stream: 'TextIO', schema: 'str' = 'base-cli.record', schema_version: 'int' = 1) -> None` + +**Behavior:** Write versioned structured records as newline-delimited JSON. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.NdjsonWriter(...) +``` + +### `OutputFormatError` +**Kind:** class +**Signature:** (value is not callable) + +**Behavior:** Raised when a public output format is not supported. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.OutputFormatError(...) +``` + +### `StructuredResultWriter` +**Kind:** class +**Signature:** `StructuredResultWriter(*args, **kwargs)` + +**Behavior:** Typed sink for one structured result at a time. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.StructuredResultWriter(...) +``` + +### `ProjectInfo` +**Kind:** class +**Signature:** `ProjectInfo(root: 'Path | None' = None, manifest: 'Path | None' = None, name: 'str | None' = None) -> None` + +**Behavior:** Consumer-neutral project information discovered for an invocation. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ProjectInfo(...) +``` + +### `ProjectDiscovery` +**Kind:** class +**Signature:** `ProjectDiscovery(*args, **kwargs)` + +**Behavior:** Discover consumer-owned project information for the current directory. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ProjectDiscovery(...) +``` + +### `RuntimeLayout` +**Kind:** class +**Signature:** `RuntimeLayout(owner_root: 'Path', run_root: 'Path', state_dir: 'Path', log_dir: 'Path', cache_dir: 'Path', temp_dir: 'Path') -> None` + +**Behavior:** Filesystem locations owned by one base-cli runtime binding. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.RuntimeLayout(...) +``` + +### `PluginExtension` +**Kind:** class +**Signature:** `PluginExtension(*args, **kwargs)` + +**Behavior:** Callable contract for ``base_cli.plugins`` entry points. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.PluginExtension(...) +``` + +### `ProfileExtension` +**Kind:** class +**Signature:** `ProfileExtension(*args, **kwargs)` + +**Behavior:** Callable contract for ``base_cli.profiles`` entry points. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.ProfileExtension(...) +``` + +### `RetentionPolicy` +**Kind:** class +**Signature:** `RetentionPolicy(max_bundles: 'int | None' = None, max_age_seconds: 'float | None' = None, max_total_bytes: 'int | None' = None) -> None` + +**Behavior:** Bounds for complete invocation bundles. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.RetentionPolicy(...) +``` + +### `RuntimeResolver` +**Kind:** class +**Signature:** `RuntimeResolver(*args, **kwargs)` + +**Behavior:** Resolve the runtime directories and ownership for one invocation. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.RuntimeResolver(...) +``` + +### `RuntimeBinding` +**Kind:** class +**Signature:** `RuntimeBinding(cache_root: 'Path', layout: 'RuntimeLayout', application_home: 'Path | None', runtime_owner: 'str', project_root: 'Path | None', project_name: 'str | None', inherited_path: 'Path | None', history_parent_run_id: 'str | None', run_id: 'str', primary_log_file: 'Path | None' = None, history_scope: 'str' = 'primary', write_identity: 'bool' = False) -> None` + +**Behavior:** Runtime decisions supplied by a consumer profile. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.RuntimeBinding(...) +``` + +### `TelemetryOptions` +**Kind:** class +**Signature:** `TelemetryOptions(enabled: 'bool' = True, tracer: 'Any | None' = None, tracer_provider: 'Any | None' = None, tracer_name: 'str' = 'base_cli') -> None` + +**Behavior:** Opt-in OpenTelemetry configuration for one :class:`base_cli.App`. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.TelemetryOptions(...) +``` + +### `TelemetrySession` +**Kind:** class +**Signature:** `TelemetrySession(span: 'Any', started_monotonic_ns: 'int') -> None` + +**Behavior:** Best-effort state for a single lifecycle span. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.TelemetrySession(...) +``` + +### `HistoryWriter` +**Kind:** class +**Signature:** `HistoryWriter(*args, **kwargs)` + +**Behavior:** Persist one completed invocation using the active typed Context. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.HistoryWriter(...) +``` + +### `HistoryDisplayResolver` +**Kind:** class +**Signature:** `HistoryDisplayResolver(*args, **kwargs)` + +**Behavior:** Resolve the command label persisted in consumer history. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.HistoryDisplayResolver(...) +``` + +### `UserConfigLoader` +**Kind:** class +**Signature:** `UserConfigLoader(*args, **kwargs)` + +**Behavior:** Load opaque consumer-owned user configuration. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.UserConfigLoader(...) +``` + +### `WorkspaceRootResolver` +**Kind:** class +**Signature:** `WorkspaceRootResolver(*args, **kwargs)` + +**Behavior:** Project a consumer-owned user configuration into a workspace root. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.WorkspaceRootResolver(...) +``` + +## Functions + +### `command_matches` +**Kind:** function +**Signature:** `command_matches(value: 'str', command_filters: 'tuple[str, ...]', *, normalizer: 'CommandFilterNormalizer | None' = None) -> 'bool'` + +**Behavior:** Return whether a command value matches one of the normalized filters. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.command_matches(...) +``` + +### `dumps_envelope` +**Kind:** function +**Signature:** `dumps_envelope(envelope: 'Mapping[str, Any]') -> 'str'` + +**Behavior:** Serialize an envelope as one compact, newline-terminated JSON record. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.dumps_envelope(...) +``` + +### `dumps_record` +**Kind:** function +**Signature:** `dumps_record(record_type: 'str', record: 'Record', *, protocol_header: 'str' = 'COMMAND_PROTOCOL_V1', registry: 'CommandSchemaRegistry | None' = None) -> 'str'` + +**Behavior:** Serialize one typed command record using the protocol framing. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.dumps_record(...) +``` + +### `dumps_records` +**Kind:** function +**Signature:** `dumps_records(record_type: 'str', records: 'tuple[Record, ...] | list[Record]', *, protocol_header: 'str' = 'COMMAND_PROTOCOL_V1', registry: 'CommandSchemaRegistry | None' = None) -> 'str'` + +**Behavior:** Serialize a sequence of typed command records using the protocol framing. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.dumps_records(...) +``` + +### `error_envelope` +**Kind:** function +**Signature:** `error_envelope(*, run_id: 'str | None', code: 'str', message: 'str', details: 'Mapping[str, Any] | None' = None) -> 'dict[str, Any]'` + +**Behavior:** Return the stable v1 machine-readable error envelope. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.error_envelope(...) +``` + +### `inspection_envelope` +**Kind:** function +**Signature:** `inspection_envelope(*, command: 'str', status: 'InspectionStatus', data: 'Mapping[str, Any]', error: 'Mapping[str, Any] | None' = None) -> 'dict[str, Any]'` + +**Behavior:** Build the stable v1 envelope for read-only inspection commands. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.inspection_envelope(...) +``` + +### `render_inspection_json` +**Kind:** function +**Signature:** `render_inspection_json(*, command: 'str', status: 'InspectionStatus', data: 'Mapping[str, Any]', error: 'Mapping[str, Any] | None' = None) -> 'str'` + +**Behavior:** Serialize the stable inspection envelope with Python's JSON encoder. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.render_inspection_json(...) +``` + +### `argument` +**Kind:** function +**Signature:** `argument(*param_decls: 'str', sensitive: 'bool' = False, **attrs: 'Any') -> 'Callable[[Callable[_P, _R]], Callable[_P, _R]]'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.argument(...) +``` + +### `run_async` +**Kind:** function +**Signature:** `run_async(awaitable: 'Awaitable[_T]') -> '_T'` + +**Behavior:** Run one awaitable with an adapter-owned event loop. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.run_async(...) +``` + +### `attach` +**Kind:** function +**Signature:** `attach(command: '_ClickCommandT', *, app: 'App | None' = None, context_factory: 'Callable[[Context[Any, Any, Any]], Any] | None' = None, service_factory: 'Callable[[Context[Any, Any, Any]], Any] | None' = None, sensitive_parameters: 'Iterable[str]' = (), **app_kwargs: 'Any') -> '_ClickCommandT'` + +**Behavior:** Attach lifecycle middleware and return the same Click command object. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.attach(...) +``` + +### `attach_typer` +**Kind:** function +**Signature:** `attach_typer(typer_app: '_TyperApp', *, app: 'App | None' = None, context_factory: 'Callable[[Context[Any, Any, Any]], Any] | None' = None, service_factory: 'Callable[[Context[Any, Any, Any]], Any] | None' = None, sensitive_parameters: 'Iterable[str]' = (), name: 'str | None' = None, **app_kwargs: 'Any') -> '_ClickCommand'` + +**Behavior:** Attach a Typer application and return its native Click command. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.attach_typer(...) +``` + +### `command` +**Kind:** function +**Signature:** `command(*args: 'Any', **kwargs: 'Any') -> 'Callable[[Callable[_P, _R]], Callable[_P, _R]]'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.command(...) +``` + +### `configure_logger` +**Kind:** function +**Signature:** `configure_logger(cli_name: 'str', log_file: 'Path | None', debug: 'bool', *, quiet: 'bool' = False, stream: 'TextIO | None' = None, formatter: 'logging.Formatter | None' = None, json_logs: 'bool' = False, run_id: 'str | None' = None) -> 'logging.Logger'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.configure_logger(...) +``` + +### `delegated_display_command` +**Kind:** function +**Signature:** `delegated_display_command(default: 'str | None' = None) -> 'str | None'` + +**Behavior:** Return the wrapper display label or ``default`` when none is set. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.delegated_display_command(...) +``` + +### `deprecated` +**Kind:** function +**Signature:** `deprecated(since: 'str', *, remove: 'str', alternative: 'str | None' = None) -> 'Callable[[Callable[P, R]], Callable[P, R]]'` + +**Behavior:** Mark a callable as deprecated while preserving its normal behavior. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.deprecated(...) +``` + +### `get_command_app` +**Kind:** function +**Signature:** `get_command_app(command_func: 'Any') -> 'App'` + +**Behavior:** Return the :class:`App` owning a registered function or attached tree. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.get_command_app(...) +``` + +### `get_current_context` +**Kind:** function +**Signature:** `get_current_context() -> 'Context[Any, Any, Any]'` + +**Behavior:** Return the active command context or raise when called outside a command. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.get_current_context(...) +``` + +### `get_typer_command` +**Kind:** function +**Signature:** `get_typer_command(typer_app: '_TyperApp') -> '_ClickCommand'` + +**Behavior:** Materialize Typer's native Click command tree. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.get_typer_command(...) +``` + +### `get_lifecycle_values` +**Kind:** function +**Signature:** `get_lifecycle_values(click_context: 'Any | None' = None) -> 'LifecycleValues'` + +**Behavior:** Return normalized lifecycle values stored on an active Click context. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.get_lifecycle_values(...) +``` + +### `log_critical` +**Kind:** function +**Signature:** `log_critical(message: 'str', *args: 'object') -> 'None'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.log_critical(...) +``` + +### `log_debug` +**Kind:** function +**Signature:** `log_debug(message: 'str', *args: 'object') -> 'None'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.log_debug(...) +``` + +### `log_error` +**Kind:** function +**Signature:** `log_error(message: 'str', *args: 'object') -> 'None'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.log_error(...) +``` + +### `log_info` +**Kind:** function +**Signature:** `log_info(message: 'str', *args: 'object') -> 'None'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.log_info(...) +``` + +### `log_warning` +**Kind:** function +**Signature:** `log_warning(message: 'str', *args: 'object') -> 'None'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.log_warning(...) +``` + +### `loads_records` +**Kind:** function +**Signature:** `loads_records(payload: 'str', expected_record_type: 'str | None' = None, *, protocol_header: 'str' = 'COMMAND_PROTOCOL_V1', registry: 'CommandSchemaRegistry | None' = None) -> 'tuple[str, tuple[dict[str, RecordValue], ...]]'` + +**Behavior:** Validate and decode protocol-framed command records. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.loads_records(...) +``` + +### `normalize_command_filter` +**Kind:** function +**Signature:** `normalize_command_filter(value: 'str', *, normalizer: 'CommandFilterNormalizer | None' = None) -> 'str'` + +**Behavior:** Normalize one command name for matching. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.normalize_command_filter(...) +``` + +### `normalize_command_filters` +**Kind:** function +**Signature:** `normalize_command_filters(value: 'str | None', *, normalizer: 'CommandFilterNormalizer | None' = None) -> 'tuple[str, ...]'` + +**Behavior:** Normalize a comma-separated command filter and reject empty entries. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.normalize_command_filters(...) +``` + +### `is_terminal` +**Kind:** function +**Signature:** `is_terminal(stream: 'TextIO | None' = None) -> 'bool'` + +**Behavior:** Return whether *stream* is an interactive terminal. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.is_terminal(...) +``` + +### `output_format_choices` +**Kind:** function +**Signature:** `output_format_choices() -> 'str'` + +**Behavior:** Return the public choices in help/error-message order. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.output_format_choices(...) +``` + +### `option` +**Kind:** function +**Signature:** `option(*param_decls: 'str', sensitive: 'bool' = False, dry_run: 'bool' = False, **attrs: 'Any') -> 'Callable[[Callable[_P, _R]], Callable[_P, _R]]'` + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.option(...) +``` + +### `render_document` +**Kind:** function +**Signature:** `render_document(document: 'Mapping[str, Any]', *, requested_format: 'str | None', records_key: 'str | None' = None, columns: 'Sequence[tuple[str, str]] | None' = None, stream: 'TextIO | None' = None) -> 'str'` + +**Behavior:** Render a structured report or leave terminal text to its existing renderer. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.render_document(...) +``` + +### `render_records` +**Kind:** function +**Signature:** `render_records(records: 'Iterable[Mapping[str, Any]]', *, requested_format: 'str | None', columns: 'Sequence[tuple[str, str]]', stream: 'TextIO | None' = None, footer: 'str | None' = None, minimum_widths: 'Sequence[int] | None' = None, terminal_width: 'int | None' = None, max_cell_width: 'int | None' = 80, rich: 'bool' = False) -> 'str'` + +**Behavior:** Render records according to the shared public output contract. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.render_records(...) +``` + +### `register_record_schema` +**Kind:** function +**Signature:** `register_record_schema(record_type: 'str', fields: 'Mapping[str, FieldSpec]') -> 'None'` + +**Behavior:** Register an application-specific record schema for the wire protocol. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.register_record_schema(...) +``` + +### `redact_json_value` +**Kind:** function +**Signature:** `redact_json_value(value: 'Any', *, _key: 'str | None' = None) -> 'Any'` + +**Behavior:** Recursively redact secret-looking JSON keys and text values. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.redact_json_value(...) +``` + +### `resolve_output_format` +**Kind:** function +**Signature:** `resolve_output_format(requested: 'str | None', *, stream: 'TextIO | None' = None) -> 'str'` + +**Behavior:** Resolve a requested format, making text TTY-aware. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.resolve_output_format(...) +``` + +### `run_app` +**Kind:** function +**Signature:** `run_app(app: 'App | Callable[..., Any]', argv: 'list[str] | None' = None, *, reraise_unexpected: 'bool' = False) -> 'int'` + +**Behavior:** Run an App, registered command, or attached Click tree and return its status. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.run_app(...) +``` + +### `success_envelope` +**Kind:** function +**Signature:** `success_envelope(*, run_id: 'str | None', details: 'Mapping[str, Any] | None' = None, message: 'str' = 'Success', code: 'str' = 'ok') -> 'dict[str, Any]'` + +**Behavior:** Return the stable v1 machine-readable success envelope. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.success_envelope(...) +``` + +### `try_render_rich_table` +**Kind:** function +**Signature:** `try_render_rich_table(stream: 'TextIO', headers: 'Sequence[str]', rows: 'Sequence[Sequence[str]]', footer: 'str | None', *, terminal_width: 'int | None' = None) -> 'bool'` + +**Behavior:** Render a human table with Rich when it is installed and healthy. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +# See the callable signature above and pass consumer-owned values. +base_cli.try_render_rich_table(...) +``` + +## Modules + +### `asyncio_adapter` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Explicit asyncio support for commands that opt into an async boundary. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.asyncio_adapter +``` + +### `command_filters` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Shared command-name filter normalization for CLI reports. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.command_filters +``` + +### `command_protocol` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.command_protocol +``` + +### `deprecations` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Small, consistent deprecation primitives for public base-cli APIs. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.deprecations +``` + +### `experimental` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Preview APIs under active development. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.experimental +``` + +### `json_contracts` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Versioned JSON contracts for machine-facing CLI consumers. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.json_contracts +``` + +### `extensions` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Lazy, deterministic discovery of optional Python entry-point extensions. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.extensions +``` + +### `history` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.history +``` + +### `integrations` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Optional Rich and OpenTelemetry integrations. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.integrations +``` + +### `testing` +**Kind:** module +**Signature:** (value is not callable) + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +base_cli.testing +``` + +## Constants and typing helpers + +### `__version__` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.__version__ +``` + +### `BOOLEAN` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Describe the wire type and nullability of one command-record field. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.BOOLEAN +``` + +### `ApplicationStateT` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Type variable. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.ApplicationStateT +``` + +### `CommandFilterNormalizer` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Public facade symbol; see the linked contract and source annotations for details. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.CommandFilterNormalizer +``` + +### `COMMAND_ENTRY_POINT_GROUP` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.COMMAND_ENTRY_POINT_GROUP +``` + +### `ConfigT` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Type variable. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.ConfigT +``` + +### `ENTRY_POINT_GROUPS` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Built-in immutable sequence. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.ENTRY_POINT_GROUPS +``` + +### `EXTENSION_API_VERSION` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.EXTENSION_API_VERSION +``` + +### `DEFAULT_SCHEMA_REGISTRY` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Own an isolated set of command record schemas. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.DEFAULT_SCHEMA_REGISTRY +``` + +### `LIFECYCLE_META_KEY` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.LIFECYCLE_META_KEY +``` + +### `NULLABLE_STRING` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Describe the wire type and nullability of one command-record field. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.NULLABLE_STRING +``` + +### `STRING` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Describe the wire type and nullability of one command-record field. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.STRING +``` + +### `JSON_CONTRACT_VERSION` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** int([x]) -> integer int(x, base=10) -> integer + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.JSON_CONTRACT_VERSION +``` + +### `JSON_ERROR_SCHEMA` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.JSON_ERROR_SCHEMA +``` + +### `JSON_LOG_SCHEMA` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.JSON_LOG_SCHEMA +``` + +### `JSON_OUTPUT_SCHEMA` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.JSON_OUTPUT_SCHEMA +``` + +### `MAX_JSON_LOG_MESSAGE_LENGTH` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** int([x]) -> integer int(x, base=10) -> integer + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.MAX_JSON_LOG_MESSAGE_LENGTH +``` + +### `NDJSON_SCHEMA` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.NDJSON_SCHEMA +``` + +### `NDJSON_SCHEMA_VERSION` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** int([x]) -> integer int(x, base=10) -> integer + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.NDJSON_SCHEMA_VERSION +``` + +### `PUBLIC_OUTPUT_FORMATS` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Built-in immutable sequence. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.PUBLIC_OUTPUT_FORMATS +``` + +### `StructuredRecord` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** A Mapping is a generic container for associating key/value pairs. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.StructuredRecord +``` + +### `RECORD_SCHEMAS` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2) + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.RECORD_SCHEMAS +``` + +### `PLUGIN_ENTRY_POINT_GROUP` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.PLUGIN_ENTRY_POINT_GROUP +``` + +### `PROFILE_ENTRY_POINT_GROUP` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.PROFILE_ENTRY_POINT_GROUP +``` + +### `ServicesT` +**Kind:** constant/type +**Signature:** (value is not callable) + +**Behavior:** Type variable. + +**Errors and compatibility:** Follow the contract documentation linked in the description. Callers should handle the documented exception types and pin a compatible minor release. + +**Example:** +```python +import base_cli + +value = base_cli.ServicesT +``` diff --git a/docs/index.md b/docs/index.md index 1cfc91b..13a4bc2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -60,6 +60,8 @@ application. production evaluation. - Read [API stability](api-stability.md) and the [migration guide](migrations.md) before upgrading across a compatibility boundary. +- Browse the [complete public API reference](api-reference.md) for exported + symbols, signatures, and usage shapes. - Follow [consumer profiles](consumer-profiles.md) when your application owns project discovery or configuration policy. - Use the [Typer adapter](typer-adapter.md) to bring an existing Typer command diff --git a/mkdocs.yml b/mkdocs.yml index b8450b1..a3b080f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,7 @@ nav: - Platform support: platform-support.md - Consumer profiles: consumer-profiles.md - API and contracts: + - Public API reference: api-reference.md - API stability: api-stability.md - Dependency support: dependency-support.md - Migration guide: migrations.md diff --git a/scripts/generate_api_reference.py b/scripts/generate_api_reference.py new file mode 100644 index 0000000..6fb8153 --- /dev/null +++ b/scripts/generate_api_reference.py @@ -0,0 +1,148 @@ +#!/usr/bin/env python3 +"""Generate and validate the stable ``base_cli`` API reference. + +The reference is intentionally derived from the package facade rather than +from every importable module. This keeps private implementation details out +of the published documentation while making a public-export change fail the +documentation check until the generated page is refreshed. +""" + +from __future__ import annotations + +import inspect +import re +import sys +from pathlib import Path +from typing import Any + +ROOT = Path(__file__).resolve().parents[1] +PACKAGE_ROOT = ROOT / "lib" / "python" +REFERENCE = ROOT / "docs" / "api-reference.md" +MARKER = "" +HEADING_PATTERN = re.compile(r"^### `([^`]+)`$", re.MULTILINE) + + +def _load_package() -> Any: + sys.path.insert(0, str(PACKAGE_ROOT)) + import base_cli + + return base_cli + + +def _kind(value: Any) -> str: + if inspect.ismodule(value): + return "module" + if inspect.isclass(value): + return "class" + if inspect.isfunction(value) or inspect.ismethod(value): + return "function" + if isinstance(value, type): + return "class" + return "constant/type" + + +def _signature(name: str, value: Any) -> str: + try: + if inspect.isclass(value) or inspect.isfunction(value) or inspect.ismethod(value): + signature = str(inspect.signature(value)) + # Default callback reprs contain process-specific memory addresses. + signature = re.sub(r" at 0x[0-9a-fA-F]+", "", signature) + return f"`{name}{signature}`" + except (TypeError, ValueError): + pass + return "(value is not callable)" + + +def _description(value: Any) -> str: + doc = inspect.getdoc(value) + if not doc: + return "Public facade symbol; see the linked contract and source annotations for details." + first_paragraph = doc.split("\n\n", 1)[0].replace("\n", " ").strip() + return first_paragraph + + +def _example(name: str, value: Any) -> str: + kind = _kind(value) + if kind == "module": + return f"```python\nimport base_cli\n\nbase_cli.{name}\n```" + if kind in {"function", "class"}: + return f"```python\nimport base_cli\n\n# See the callable signature above and pass consumer-owned values.\nbase_cli.{name}(...)\n```" + return f"```python\nimport base_cli\n\nvalue = base_cli.{name}\n```" + + +def render(base_cli: Any) -> str: + sections: dict[str, list[str]] = {"class": [], "function": [], "module": [], "constant/type": []} + for name in base_cli.__all__: + value = getattr(base_cli, name) + kind = _kind(value) + sections[kind].append( + "\n".join( + ( + f"### `{name}`", + f"**Kind:** {kind} ", + f"**Signature:** {_signature(name, value)}", + "", + f"**Behavior:** {_description(value)}", + "", + "**Errors and compatibility:** Follow the contract documentation linked in the description. " + "Callers should handle the documented exception types and pin a compatible minor release.", + "", + "**Example:**", + _example(name, value), + "", + ) + ) + ) + + lines = [ + "# Public API reference", + "", + "This page is generated from `base_cli.__all__`. It is the complete stable", + "facade: private modules and names are deliberately excluded. Each entry", + "includes the runtime signature when Python can inspect one, the public", + "docstring summary, compatibility guidance, and a minimal usage shape.", + "For behavior that is shared by several symbols, follow the linked", + "versioned contracts and the source annotations.", + "", + "!!! note", + " Regenerate this page after changing a public export:", + " `python scripts/generate_api_reference.py`. CI runs the same command", + " in check mode and fails when the committed page is stale.", + "", + f"{MARKER}", + "", + f"The facade currently documents **{len(base_cli.__all__)}** public symbols.", + "", + ] + for title, kind in ( + ("Classes and protocols", "class"), + ("Functions", "function"), + ("Modules", "module"), + ("Constants and typing helpers", "constant/type"), + ): + lines.extend([f"## {title}", "", *sections[kind]]) + return "\n".join(lines).rstrip() + "\n" + + +def main() -> None: + check = "--check" in sys.argv[1:] + base_cli = _load_package() + rendered = render(base_cli) + if check: + current = REFERENCE.read_text(encoding="utf-8") if REFERENCE.exists() else "" + if current != rendered: + print(f"{REFERENCE.relative_to(ROOT)} is stale; run scripts/generate_api_reference.py", file=sys.stderr) + raise SystemExit(1) + documented = set(HEADING_PATTERN.findall(current)) + exported = set(base_cli.__all__) + if documented != exported: + print("generated API headings do not match base_cli.__all__", file=sys.stderr) + raise SystemExit(1) + print(f"Validated {len(exported)} public API symbols.") + return + REFERENCE.write_text(rendered, encoding="utf-8") + print(f"Generated {REFERENCE.relative_to(ROOT)} for {len(base_cli.__all__)} public symbols.") + + +if __name__ == "__main__": + main() diff --git a/tests/validate.sh b/tests/validate.sh index 61f5a20..a7e862f 100755 --- a/tests/validate.sh +++ b/tests/validate.sh @@ -23,6 +23,7 @@ required_files=( docs/releasing.md docs/index.md docs/api-stability.md + docs/api-reference.md docs/dependency-support.md docs/user-config-typing.md docs/migrations.md @@ -33,6 +34,7 @@ required_files=( scripts/validate_package_artifact.py scripts/validate_installed_package.py scripts/validate_docs.py + scripts/generate_api_reference.py scripts/validate_examples.py scripts/validate_consumers.py scripts/generate_release_metadata.py