gaard-plugin-api 0.1.0__py3-none-any.whl

gaard_plugin_api/__init__.py

@@ -0,0 +1,29 @@
+from gaard_plugin_api.discovery import (
+    EXTENSION_ENTRY_POINT_GROUP,
+    ExtensionManager,
+    discover_extensions,
+)
+from gaard_plugin_api.models import (
+    EXTENSION_API_VERSION,
+    ExtensionActivationError,
+    ExtensionCompatibilityError,
+    ExtensionContext,
+    ExtensionManifest,
+    ExtensionManifestError,
+    ExtensionRecord,
+    ExtensionStatus,
+)
+
+__all__ = [
+    "EXTENSION_API_VERSION",
+    "EXTENSION_ENTRY_POINT_GROUP",
+    "ExtensionActivationError",
+    "ExtensionCompatibilityError",
+    "ExtensionContext",
+    "ExtensionManager",
+    "ExtensionManifest",
+    "ExtensionManifestError",
+    "ExtensionRecord",
+    "ExtensionStatus",
+    "discover_extensions",
+]

gaard_plugin_api/discovery.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, entry_points, version
+from typing import Any, Protocol, cast
+
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+
+from gaard_plugin_api.models import (
+    EXTENSION_API_VERSION,
+    ExtensionActivationError,
+    ExtensionCompatibilityError,
+    ExtensionContext,
+    ExtensionManifest,
+    ExtensionManifestError,
+    ExtensionRecord,
+    ExtensionStatus,
+)
+
+
+EXTENSION_ENTRY_POINT_GROUP = "gaard.extensions"
+
+
+class EntryPointLike(Protocol):
+    name: str
+
+    def load(self) -> Any: ...
+
+
+ContributionLoader = Callable[[str], Callable[[ExtensionContext], None]]
+PackageVersionResolver = Callable[[str], str]
+
+
+def discover_extensions(
+    entry_point_items: Iterable[EntryPointLike] | None = None,
+    package_version: PackageVersionResolver = version,
+) -> list[ExtensionRecord]:
+    """Discover installed manifests without activating their contributions."""
+
+    selected_entry_points = (
+        list(entry_point_items)
+        if entry_point_items is not None
+        else list(entry_points(group=EXTENSION_ENTRY_POINT_GROUP))
+    )
+    records: list[ExtensionRecord] = []
+
+    for entry_point in sorted(selected_entry_points, key=lambda item: item.name):
+        record = ExtensionRecord(entry_point_name=entry_point.name)
+        records.append(record)
+
+        try:
+            manifest = _load_manifest(entry_point)
+            _validate_compatibility(manifest, package_version)
+        except (
+            ExtensionCompatibilityError,
+            ExtensionManifestError,
+            PackageNotFoundError,
+            TypeError,
+            ValueError,
+        ) as exc:
+            record.status = ExtensionStatus.FAILED
+            record.error = str(exc)
+            continue
+        except Exception as exc:  # pragma: no cover - defensive boundary for third-party code
+            record.status = ExtensionStatus.FAILED
+            record.error = f"Unable to load extension manifest: {exc}"
+            continue
+
+        record.manifest = manifest
+        record.status = ExtensionStatus.VALIDATED
+
+    return records
+
+
+class ExtensionManager:
+    """Discovers and activates typed extension contributions for one host process."""
+
+    def __init__(
+        self,
+        entry_point_items: Iterable[EntryPointLike] | None = None,
+        package_version: PackageVersionResolver = version,
+        contribution_loader: ContributionLoader | None = None,
+    ) -> None:
+        self._entry_point_items = entry_point_items
+        self._package_version = package_version
+        self._contribution_loader = contribution_loader or load_contribution
+        self.records: list[ExtensionRecord] = []
+
+    def discover(self) -> list[ExtensionRecord]:
+        self.records = discover_extensions(
+            entry_point_items=self._entry_point_items,
+            package_version=self._package_version,
+        )
+        return self.records
+
+    def activate(
+        self,
+        capability: str,
+        registry: Any,
+        services: Mapping[str, Any] | None = None,
+    ) -> list[ExtensionRecord]:
+        """Activate one capability for every validated extension that declares it."""
+
+        if not self.records:
+            self.discover()
+
+        activated: list[ExtensionRecord] = []
+
+        for record in self.records:
+            if record.status not in {ExtensionStatus.VALIDATED, ExtensionStatus.ACTIVE}:
+                continue
+            if record.manifest is None or capability not in record.manifest.contributions:
+                continue
+            if capability in record.active_capabilities:
+                continue
+
+            target = record.manifest.contributions[capability]
+            context = ExtensionContext(
+                extension_id=record.manifest.id,
+                capability=capability,
+                registry=registry,
+                services=services or {},
+            )
+
+            try:
+                contribution = self._contribution_loader(target)
+                contribution(context)
+            except Exception as exc:  # pragma: no cover - defensive boundary for third-party code
+                record.status = ExtensionStatus.FAILED
+                record.error = f"Unable to activate {capability!r} contribution: {exc}"
+                continue
+
+            record.active_capabilities.add(capability)
+            record.status = ExtensionStatus.ACTIVE
+            activated.append(record)
+
+        return activated
+
+
+def load_contribution(target: str) -> Callable[[ExtensionContext], None]:
+    """Import one declared contribution factory from a `module:attribute` target."""
+
+    module_name, separator, attribute_name = target.partition(":")
+    if not separator or not module_name or not attribute_name:
+        raise ExtensionActivationError(
+            "Extension contribution targets must use the 'module:attribute' format."
+        )
+
+    module = import_module(module_name)
+    contribution = getattr(module, attribute_name)
+
+    if not callable(contribution):
+        raise ExtensionActivationError(f"Extension contribution {target!r} is not callable.")
+
+    return cast(Callable[[ExtensionContext], None], contribution)
+
+
+def _load_manifest(entry_point: EntryPointLike) -> ExtensionManifest:
+    candidate = entry_point.load()
+    manifest = candidate() if callable(candidate) else candidate
+
+    if not isinstance(manifest, ExtensionManifest):
+        raise ExtensionManifestError(
+            f"Entry point {entry_point.name!r} must resolve to an ExtensionManifest or a factory."
+        )
+
+    return manifest
+
+
+def _validate_compatibility(
+    manifest: ExtensionManifest,
+    package_version: PackageVersionResolver,
+) -> None:
+    if manifest.extension_api_version != EXTENSION_API_VERSION:
+        raise ExtensionCompatibilityError(
+            f"Extension {manifest.id!r} requires extension API "
+            f"{manifest.extension_api_version!r}, but host supports {EXTENSION_API_VERSION!r}."
+        )
+
+    for package_name, version_specifier in manifest.requires.items():
+        try:
+            requirement = SpecifierSet(version_specifier)
+        except InvalidSpecifier as exc:
+            raise ExtensionCompatibilityError(
+                f"Extension {manifest.id!r} has invalid version specifier "
+                f"{version_specifier!r} for {package_name!r}."
+            ) from exc
+
+        installed_version = package_version(package_name)
+        if installed_version not in requirement:
+            raise ExtensionCompatibilityError(
+                f"Extension {manifest.id!r} requires {package_name}{version_specifier}, "
+                f"but {installed_version} is installed."
+            )

gaard_plugin_api/models.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Any
+
+
+EXTENSION_API_VERSION = "1"
+_EXTENSION_ID_PATTERN = re.compile(r"^[a-z][a-z0-9-]{0,62}$")
+
+
+class ExtensionManifestError(ValueError):
+    """Raised when an extension manifest does not satisfy the public contract."""
+
+
+class ExtensionCompatibilityError(RuntimeError):
+    """Raised when an installed extension is incompatible with the host."""
+
+
+class ExtensionActivationError(RuntimeError):
+    """Raised when an extension contribution cannot be activated."""
+
+
+class ExtensionStatus(StrEnum):
+    DISCOVERED = "discovered"
+    VALIDATED = "validated"
+    ACTIVE = "active"
+    DISABLED = "disabled"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionManifest:
+    """Public metadata describing one installed GAARD extension."""
+
+    id: str
+    version: str
+    extension_api_version: str = EXTENSION_API_VERSION
+    requires: Mapping[str, str] = field(default_factory=dict)
+    contributions: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not _EXTENSION_ID_PATTERN.fullmatch(self.id):
+            raise ExtensionManifestError(
+                "Extension id must use lowercase letters, digits, and hyphens, "
+                "and must start with a letter."
+            )
+
+        if not self.version.strip():
+            raise ExtensionManifestError("Extension version must not be empty.")
+
+        for package_name, version_specifier in self.requires.items():
+            if not package_name.strip() or not version_specifier.strip():
+                raise ExtensionManifestError(
+                    "Extension package requirements must contain a package name and version specifier."
+                )
+
+        for capability, target in self.contributions.items():
+            if not capability.strip():
+                raise ExtensionManifestError("Extension contribution capability must not be empty.")
+            if not _is_import_target(target):
+                raise ExtensionManifestError(
+                    "Extension contribution targets must use the 'module:attribute' format."
+                )
+
+        object.__setattr__(self, "requires", MappingProxyType(dict(self.requires)))
+        object.__setattr__(self, "contributions", MappingProxyType(dict(self.contributions)))
+
+
+@dataclass(slots=True)
+class ExtensionRecord:
+    """Runtime state for a discovered extension."""
+
+    entry_point_name: str
+    manifest: ExtensionManifest | None = None
+    status: ExtensionStatus = ExtensionStatus.DISCOVERED
+    error: str | None = None
+    active_capabilities: set[str] = field(default_factory=set)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionContext:
+    """Controlled context supplied to one extension contribution factory."""
+
+    extension_id: str
+    capability: str
+    registry: Any
+    services: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "services", MappingProxyType(dict(self.services)))
+
+
+def _is_import_target(value: str) -> bool:
+    module_name, separator, attribute_name = value.partition(":")
+    return bool(separator and module_name.strip() and attribute_name.strip())

gaard_plugin_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: gaard-plugin-api
+Version: 0.1.0
+Summary: Versioned extension contracts and discovery for GAARD
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: packaging>=24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# gaard-plugin-api
+
+`gaard-plugin-api` provides the stable, dependency-light contracts used by
+GAARD extension packages. It defines extension manifests, discovery through
+Python entry points, compatibility validation, and contribution activation.
+
+An extension is trusted, installed Python code. GAARD does not load executable
+extensions from database records, configuration files, or arbitrary URLs.

gaard_plugin_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+gaard_plugin_api/__init__.py,sha256=nx8rv6UBQmkucHTwGWhq8E46i3qyjZ3ueplX6c8_lUY,690
+gaard_plugin_api/discovery.py,sha256=aSl6uHW6bF0L5keeVlzw2GvY5Agy-mhU5OkmcFhTi5Y,6800
+gaard_plugin_api/models.py,sha256=QwFlOIdEJZTvozzh5i_CI32dSz96QCmyLPeijBhhVBA,3367
+gaard_plugin_api-0.1.0.dist-info/METADATA,sha256=OuZdx9GuC0FD8go5gR89pX866B6JS3j555Q2V3B0Wf8,772
+gaard_plugin_api-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gaard_plugin_api-0.1.0.dist-info/top_level.txt,sha256=Ta4rk_wVsVyWJ1AeClMcgCu6ZzoZUYO597tfRBAe_pY,17
+gaard_plugin_api-0.1.0.dist-info/RECORD,,

gaard_plugin_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gaard_plugin_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gaard_plugin_api