Capabilities¶

The capability API is the public surface for #119 reader, writer, and converter registration and lookup. It is a registry layer: it records typed declarations and returns matching declarations with optional opaque implementation objects. Public read handles, open_artifact(), and catalog writer-result merge are separate follow-up APIs.

Registry¶

class ogcat.CapabilityRegistry(capabilities=())[source]¶

In-memory registry for artifact capabilities.

register(capability)[source]¶

Parameters:: capability (ArtifactCapability) – Capability descriptor to register.
Return type:: ArtifactCapability
Returns:: The registered capability.
Raises:: CapabilityRegistrationError – If the capability is invalid or duplicated.

list()[source]¶

Return registered capabilities in insertion order.

Return type:: tuple[ArtifactCapability, ...]

find(*, kind=None, name=None, namespace=None, version=None, descriptor=None, input_claims=(), output_claims=(), required_facets=())[source]¶

Find capabilities matching the supplied filters.

Parameters:

kind (CapabilityKind | str | None) – Optional capability kind filter.
name (str | None) – Optional capability name filter.
namespace (str | None) – Optional capability namespace filter.
version (str | None) – Optional capability version filter.
descriptor (ArtifactDescriptor | None) – Optional artifact descriptor capabilities must support.
input_claims (Iterable[ArtifactClaim | Mapping[str, object]]) – Input claims the capability must require.
output_claims (Iterable[ArtifactClaim | Mapping[str, object]]) – Output claims the capability must produce.
required_facets (Iterable[ArtifactFacet | Mapping[str, object]]) – Required facets the capability must declare.

Return type:

tuple[ArtifactCapability, ...]

Returns:

Matching capabilities in registration order.

Raises:

InvalidCapabilityLookupError – If lookup claim or facet filters are malformed.

select(*, kind=None, name=None, namespace=None, version=None, descriptor=None, input_claims=(), output_claims=(), required_facets=())[source]¶

Select exactly one capability for an explicit request.

Parameters:

kind (CapabilityKind | str | None) – Optional capability kind filter.
name (str | None) – Optional capability name filter.
namespace (str | None) – Optional capability namespace filter.
version (str | None) – Optional capability version filter.
descriptor (ArtifactDescriptor | None) – Optional artifact descriptor capabilities must support.
input_claims (Iterable[ArtifactClaim | Mapping[str, object]]) – Input claims the capability must require.
output_claims (Iterable[ArtifactClaim | Mapping[str, object]]) – Output claims the capability must produce.
required_facets (Iterable[ArtifactFacet | Mapping[str, object]]) – Required facets the capability must declare.

Return type:

ArtifactCapability

Returns:

The single selected capability.

Raises:

UnsupportedInterfaceError – If a requested interface claim is absent from descriptor.
MissingCapabilityError – If no capability supports the request.
AmbiguousCapabilityError – If more than one capability supports the request.
InvalidCapabilityLookupError – If lookup claim or facet filters are malformed.

Capability declarations¶

class ogcat.ArtifactCapability(kind, name, namespace='ogcat.core', version='1', input_claims=<factory>, output_claims=<factory>, required_facets=<factory>, options=<factory>, metadata=<factory>, implementation=None)[source]¶

Descriptor for an artifact capability implementation.

Parameters:

kind (CapabilityKind | str) – Capability category, such as CapabilityKind.READER.
name (str) – Namespace-local capability name.
namespace (str) – Stable namespace that owns the capability.
version (str) – Version of the capability contract.
input_claims (Iterable[ArtifactClaim | Mapping[str, object]]) – Claims required on input descriptors. Inputs may be ArtifactClaim instances or normalized claim dictionaries and are stored as normalized dictionaries.
output_claims (Iterable[ArtifactClaim | Mapping[str, object]]) – Claims produced by the capability. Inputs may be ArtifactClaim instances or normalized claim dictionaries and are stored as normalized dictionaries.
required_facets (Iterable[ArtifactFacet | Mapping[str, object]]) – Facets required on descriptors used for lookup. Facets may be ArtifactFacet instances or normalized facet dictionaries and are stored as normalized dictionaries.
options (Mapping[str, object]) – JSON-compatible capability option metadata.
metadata (Mapping[str, object]) – JSON-compatible descriptive metadata.
implementation (object | None) – Opaque implementation object stored by the registry.

property key: tuple[str, str, str, str]¶: Return the stable registry key for this capability.

property display_name: str¶: Return a deterministic user-facing capability identifier.

class ogcat.CapabilityKind(value)[source]¶

Standard capability kinds recognized by the core registry.

READER = 'reader'¶

WRITER = 'writer'¶

CONVERTER = 'converter'¶

Lookup behavior¶

CapabilityRegistry.find(...) returns all matching ArtifactCapability objects in registration order. select(...) returns exactly one match or raises a lookup error.

Artifact lookup uses ogcat.ArtifactDescriptor claims and facets. It does not dispatch by CatalogRecord.record_type. If a descriptor advertises several interfaces, callers should request the exact desired interface through input_claims and/or output_claims.

Claim matching uses the claim namespace/kind/name/version envelope only; claim metadata is descriptive. Facet matching uses the facet envelope plus required metadata as a subset, so values that must influence dispatch, such as text encodings, table delimiters, member identifiers, or local path requirements, belong in facets.

Errors¶

class ogcat.CapabilityError[source]¶: Base class for capability registry errors.

class ogcat.CapabilityRegistrationError[source]¶: Raised when a capability cannot be registered.

class ogcat.CapabilityLookupError[source]¶: Base class for capability lookup errors.

class ogcat.InvalidCapabilityLookupError[source]¶: Raised when lookup filters contain malformed claims, facets, or kinds.

class ogcat.MissingCapabilityError[source]¶: Raised when no registered capability satisfies a supported request.

class ogcat.UnsupportedInterfaceError[source]¶: Raised when a descriptor does not expose a requested interface claim.

class ogcat.AmbiguousCapabilityError(candidates)[source]¶: Raised when a lookup request matches more than one capability.