orchestrata_ultimate.plugin.exceptions

Reference › orchestrata_ultimate › plugin › exceptions

The plugin exception hierarchy. PluginError extends the core BaseError and carries a message, a machine-readable code prefixed PLG_ (default PLG_GENERIC) and a context dictionary. Its subclasses each set their own default message and code: PluginManifestError (an invalid plugin.yaml, raised by manifest), PluginLoadError (import or entry-point failures, raised by the loader and discovery), PluginLifecycleError, PluginDependencyError and PluginCircularDependencyError (dependency ordering), CapabilityDeniedError (a capability or governance refusal), PluginConfigError, PluginNotFoundError and PluginRegistrationError (duplicate or invalid registration, raised by registration and the registry). Callers can catch PluginError for any of them.

At a glance


Source	`src/orchestrata_ultimate/plugin/exceptions.py`
Lines of code	268
Classes	10
Functions	0
Imports (internal)	`orchestrata_ultimate.core.base.error`, `orchestrata_ultimate.core.base.traces`
Imported by	`orchestrata_ultimate.plugin`, `orchestrata_ultimate.plugin.context`, `orchestrata_ultimate.plugin.discovery`, `orchestrata_ultimate.plugin.loader`, `orchestrata_ultimate.plugin.manager`, `orchestrata_ultimate.plugin.manifest`, `orchestrata_ultimate.plugin.registration`, `orchestrata_ultimate.plugin.registry`
Tests that import it	`tests/generated_plugin/test_exceptions_generated.py`, `tests/plugin/test_context_pure.py`, `tests/plugin/test_discovery.py`, `tests/plugin/test_discovery_extended.py`, `tests/plugin/test_exceptions.py`, `tests/plugin/test_install_plugin_git.py`, `tests/plugin/test_loader_extended.py`, `tests/plugin/test_manager.py`, `tests/plugin/test_manager_extended.py`, `tests/plugin/test_manifest.py`, `tests/plugin/test_registration.py`, `tests/plugin/test_registration_extended.py`, `tests/plugin/test_registry.py`, `tests/plugin/test_sdk.py`, `tests/test_plugin.py`

Class diagram

Dependency diagram

API

Classes

`PluginError`

Bases: BaseError · Line 11

Base exception for all plugin-related errors.

Method	Signature	Summary
`__init__`	`__init__(message: str = '', error_code: str = 'PLG_GENERIC', context: dict \| None = None) -> None`	Initialize plugin error.

`PluginManifestError`

Bases: PluginError · Decorators: traces(spec='015', story='US-001', reqs=['REQ-015-004']) · Line 41

Raised when a plugin manifest is invalid or missing.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Invalid plugin manifest', context: dict \| None = None) -> None`	Initialize manifest error.

`PluginLoadError`

Bases: PluginError · Decorators: traces(spec='015', story='US-001', reqs=['REQ-015-011']) · Line 67

Raised when a plugin fails to load.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Plugin load failed', context: dict \| None = None) -> None`	Initialize load error.

`PluginLifecycleError`

Bases: PluginError · Line 92

Raised when a plugin lifecycle transition fails.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Plugin lifecycle error', context: dict \| None = None) -> None`	Initialize lifecycle error.

`PluginDependencyError`

Bases: PluginError · Decorators: traces(spec='015', story='US-001', reqs=['REQ-015-134']) · Line 118

Raised when plugin dependencies cannot be satisfied.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Plugin dependency unsatisfied', context: dict \| None = None) -> None`	Initialize dependency error.

`PluginCircularDependencyError`

Bases: PluginError · Decorators: traces(spec='015', story='US-010', reqs=['REQ-015-133']) · Line 144

Raised when circular plugin dependencies are detected.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Circular plugin dependency detected', context: dict \| None = None) -> None`	Initialize circular dependency error.

`CapabilityDeniedError`

Bases: PluginError · Decorators: traces(spec='015', story='US-009', reqs=['REQ-015-108']) · Line 170

Raised when a plugin accesses an undeclared capability.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Plugin capability denied', context: dict \| None = None) -> None`	Initialize capability denied error.

`PluginConfigError`

Bases: PluginError · Decorators: traces(spec='015', story='US-008', reqs=['REQ-015-100']) · Line 196

Raised when plugin configuration is invalid.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Invalid plugin configuration', context: dict \| None = None) -> None`	Initialize config error.

`PluginNotFoundError`

Bases: PluginError · Line 221

Raised when a referenced plugin does not exist.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Plugin not found', context: dict \| None = None) -> None`	Initialize not found error.

`PluginRegistrationError`

Bases: PluginError · Line 246

Raised when a plugin registration operation fails.

Method	Signature	Summary
`__init__`	`__init__(message: str = 'Plugin registration failed', context: dict \| None = None) -> None`	Initialize registration error.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/plugin/exceptions.py

"""Plugin-specific exceptions for Orchestrata Plugin SDK.

All plugin exceptions inherit from BaseError for structured
error information: code, message, context dict, timestamp.
"""

from orchestrata_ultimate.core.base.error import BaseError
from orchestrata_ultimate.core.base.traces import traces


class PluginError(BaseError):
    """Base exception for all plugin-related errors.

    Attributes:
        error_code: Machine-readable code prefixed with PLG_.
        message: Human-readable description.
        context: Additional context dict.
    """

    def __init__(
        self,
        message: str = "",
        error_code: str = "PLG_GENERIC",
        context: dict | None = None,
    ) -> None:
        """Initialize plugin error.

        Args:
            message: Error description.
            error_code: Machine-readable error code.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code=error_code,
            context=context,
        )


@traces(spec="015", story="US-001", reqs=["REQ-015-004"])
class PluginManifestError(PluginError):
    """Raised when a plugin manifest is invalid or missing.

    Attributes:
        error_code: PLG_MANIFEST_INVALID.
    """

    def __init__(
        self,
        message: str = "Invalid plugin manifest",
        context: dict | None = None,
    ) -> None:
        """Initialize manifest error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_MANIFEST_INVALID",
            context=context,
        )


@traces(spec="015", story="US-001", reqs=["REQ-015-011"])
class PluginLoadError(PluginError):
    """Raised when a plugin fails to load.

    Attributes:
        error_code: PLG_LOAD_FAILED.
    """

    def __init__(
        self,
        message: str = "Plugin load failed",
        context: dict | None = None,
    ) -> None:
        """Initialize load error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_LOAD_FAILED",
            context=context,
        )


class PluginLifecycleError(PluginError):
    """Raised when a plugin lifecycle transition fails.

    Attributes:
        error_code: PLG_LIFECYCLE_ERROR.
    """

    def __init__(
        self,
        message: str = "Plugin lifecycle error",
        context: dict | None = None,
    ) -> None:
        """Initialize lifecycle error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_LIFECYCLE_ERROR",
            context=context,
        )


@traces(spec="015", story="US-001", reqs=["REQ-015-134"])
class PluginDependencyError(PluginError):
    """Raised when plugin dependencies cannot be satisfied.

    Attributes:
        error_code: PLG_DEPENDENCY_UNSATISFIED.
    """

    def __init__(
        self,
        message: str = "Plugin dependency unsatisfied",
        context: dict | None = None,
    ) -> None:
        """Initialize dependency error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_DEPENDENCY_UNSATISFIED",
            context=context,
        )


@traces(spec="015", story="US-010", reqs=["REQ-015-133"])
class PluginCircularDependencyError(PluginError):
    """Raised when circular plugin dependencies are detected.

    Attributes:
        error_code: PLG_CIRCULAR_DEPENDENCY.
    """

    def __init__(
        self,
        message: str = "Circular plugin dependency detected",
        context: dict | None = None,
    ) -> None:
        """Initialize circular dependency error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_CIRCULAR_DEPENDENCY",
            context=context,
        )


@traces(spec="015", story="US-009", reqs=["REQ-015-108"])
class CapabilityDeniedError(PluginError):
    """Raised when a plugin accesses an undeclared capability.

    Attributes:
        error_code: PLG_CAPABILITY_DENIED.
    """

    def __init__(
        self,
        message: str = "Plugin capability denied",
        context: dict | None = None,
    ) -> None:
        """Initialize capability denied error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_CAPABILITY_DENIED",
            context=context,
        )


@traces(spec="015", story="US-008", reqs=["REQ-015-100"])
class PluginConfigError(PluginError):
    """Raised when plugin configuration is invalid.

    Attributes:
        error_code: PLG_CONFIG_INVALID.
    """

    def __init__(
        self,
        message: str = "Invalid plugin configuration",
        context: dict | None = None,
    ) -> None:
        """Initialize config error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_CONFIG_INVALID",
            context=context,
        )


class PluginNotFoundError(PluginError):
    """Raised when a referenced plugin does not exist.

    Attributes:
        error_code: PLG_NOT_FOUND.
    """

    def __init__(
        self,
        message: str = "Plugin not found",
        context: dict | None = None,
    ) -> None:
        """Initialize not found error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_NOT_FOUND",
            context=context,
        )


class PluginRegistrationError(PluginError):
    """Raised when a plugin registration operation fails.

    Attributes:
        error_code: PLG_REGISTRATION_FAILED.
    """

    def __init__(
        self,
        message: str = "Plugin registration failed",
        context: dict | None = None,
    ) -> None:
        """Initialize registration error.

        Args:
            message: Error description.
            context: Additional context dict.
        """
        super().__init__(
            message=message,
            error_code="PLG_REGISTRATION_FAILED",
            context=context,
        )