Errors

provide.foundation.cli.errors

CLI adapter error classes.

Foundation-based errors for CLI adapter system.

Classes

CLIAdapterNotFoundError

CLIAdapterNotFoundError(
    framework: str, package: str | None = None
)

Bases: CLIError

Raised when CLI adapter dependencies are missing.

This error occurs when attempting to use a CLI framework adapter but the required framework package is not installed.

Examples:

>>> # Raises if Click not installed
>>> adapter = get_cli_adapter('click')

Initialize with framework details.

Parameters:

Name	Type	Description	Default
framework	str	Name of the CLI framework (e.g., 'click')	required
package	str | None	Optional package name to install	None

Source code in provide/foundation/cli/errors.py

def __init__(self, framework: str, package: str | None = None) -> None:
    """Initialize with framework details.

    Args:
        framework: Name of the CLI framework (e.g., 'click')
        package: Optional package name to install

    """
    pkg = package or framework
    super().__init__(
        f"CLI adapter for '{framework}' requires: pip install 'provide-foundation[{pkg}]'",
        code="CLI_ADAPTER_NOT_FOUND",
        framework=framework,
        package=pkg,
    )
    self.framework = framework
    self.package = pkg

Functions

CLIBuildError

CLIBuildError(
    message: str,
    *,
    code: str | None = None,
    context: dict[str, Any] | None = None,
    cause: Exception | None = None,
    **extra_context: Any
)

Bases: CLIError

Raised when CLI command/group building fails.

This error occurs during the conversion of framework-agnostic CommandInfo to framework-specific CLI objects.

Source code in provide/foundation/errors/base.py

def __init__(
    self,
    message: str,
    *,
    code: str | None = None,
    context: dict[str, Any] | None = None,
    cause: Exception | None = None,
    **extra_context: Any,
) -> None:
    self.message = message
    self.code = code or self._default_code()
    self.context = context or {}
    self.context.update(extra_context)
    self.cause = cause
    if cause:
        self.__cause__ = cause
    super().__init__(message)

CLIError

CLIError(
    message: str,
    *,
    code: str | None = None,
    context: dict[str, Any] | None = None,
    cause: Exception | None = None,
    **extra_context: Any
)

Bases: FoundationError

Base error for CLI adapter operations.

Raised when CLI adapter operations fail.

Source code in provide/foundation/errors/base.py

def __init__(
    self,
    message: str,
    *,
    code: str | None = None,
    context: dict[str, Any] | None = None,
    cause: Exception | None = None,
    **extra_context: Any,
) -> None:
    self.message = message
    self.code = code or self._default_code()
    self.context = context or {}
    self.context.update(extra_context)
    self.cause = cause
    if cause:
        self.__cause__ = cause
    super().__init__(message)

InvalidCLIHintError

InvalidCLIHintError(hint: str, param_name: str)

Bases: CLIError

Raised when an invalid CLI hint is provided in Annotated.

This error occurs when a parameter uses typing.Annotated with an invalid CLI rendering hint. Valid hints are 'option' and 'argument'.

Examples:

>>> # Valid usage
>>> def cmd(user: Annotated[str, 'option']): ...

>>> # Invalid - will raise InvalidCLIHintError
>>> def cmd(user: Annotated[str, 'invalid']): ...

Initialize with hint and parameter details.

Parameters:

Name	Type	Description	Default
hint	str	The invalid hint that was provided	required
param_name	str	Name of the parameter with invalid hint	required

Source code in provide/foundation/cli/errors.py

def __init__(self, hint: str, param_name: str) -> None:
    """Initialize with hint and parameter details.

    Args:
        hint: The invalid hint that was provided
        param_name: Name of the parameter with invalid hint

    """
    super().__init__(
        f"Invalid CLI hint '{hint}' for parameter '{param_name}'. Must be 'option' or 'argument'.",
        code="CLI_INVALID_HINT",
        hint=hint,
        param_name=param_name,
    )
    self.hint = hint
    self.param_name = param_name

Functions