Capability registry API

quantas.api.registry allows a frontend to discover scientific modules, passive types, and supported operations without importing implementation classes or forcing every workflow into one inheritance hierarchy.

from quantas.api import registry
from quantas.api.registry import Capability

for descriptor in registry.list_modules():
    print(descriptor.name, sorted(item.value for item in descriptor.capabilities))

qha = registry.get("qha")
run_qha = qha.operation(Capability.RUN)

elasticity = registry.get("elasticity")
if elasticity.has(Capability.PLOT_INVENTORY):
    describe = elasticity.operation(Capability.PLOT_INVENTORY)

All supported scientific modules now advertise PLOT_INVENTORY. The one-shot modules describe a typed result, while EOS describes an archive plus an optional slot or immutable fit record. The capability therefore remains semantically uniform without forcing EOS into the one-shot lifecycle.

Capability and descriptor contracts

class quantas.api.registry.Capability(*values)

Bases: str, Enum

Frontend-neutral operation supported by a public API namespace.

The values describe workflow capabilities rather than implementation classes. Frontends use them to discover operations without importing Click, Rich, Dash, Matplotlib, or module-internal calculators.

Notes

A capability is declared only when the corresponding operation is part of the supported quantas.api contract. Scientific modules are not required to implement the same capability set.

class quantas.api.registry.ModuleDescriptor(name, title, api_module, result_key, capabilities, operations, operation_catalog=(), input_type_name=None, options_type_name=None, result_type_name=None)

Bases: object

Describe one public scientific namespace without importing it eagerly.

Parameters:

namestr

Stable module identifier used in result metadata.

titlestr

Human-readable scientific module title.

api_modulestr

Import path of the public namespace.

result_keystr or None

Key used in quantas.models.ResultData, when applicable.

capabilitiesfrozenset of Capability

Operations supported by the namespace.

operationstuple of tuple

Mapping from capabilities to canonical public function names.

operation_catalogtuple of OperationDescriptor, optional

Named public operations used when a capability has several distinct supported functions or when applications need stable operation keys.

input_type_name, options_type_name, result_type_namestr or None

Public type aliases resolved lazily from the namespace.

Parameters:

• name (str)

• title (str)

• api_module (str)

• result_key (str | None)

• capabilities (frozenset[Capability])

• operations (tuple[tuple[Capability, str], ...])

• operation_catalog (tuple[OperationDescriptor, ...])

• input_type_name (str | None)

• options_type_name (str | None)

• result_type_name (str | None)

load()

Import and return the public namespace lazily.

Returns:

ModuleType

Imported module identified by api_module.

Raises:

ImportError

If the declared namespace cannot be imported.

Return type:

ModuleType

has(capability)

Return whether one capability is declared.

Parameters:

capabilityCapability or str

Capability enum member or its stable string value.

Returns:

bool

True when the module advertises the capability.

Raises:

ValueError

If a string is not a valid Capability value.

Parameters:

capability (Capability | str)

Return type:

bool

operation(capability)

Resolve the public function implementing one capability.

Raises:

ValueError

If the capability is not declared for this module.

AttributeError

If the declared public operation is absent.

Parameters:

capability (Capability | str)

Return type:

Callable[[…], Any]

list_operations(capability=None)

Return named public operations, optionally filtered by capability.

Canonical single-operation capabilities that predate the named catalog are exposed through synthesized descriptors, so frontends can use one discovery path for both simple and multi-operation workflows.

Parameters:

capability (Capability | str | None)

Return type:

tuple[OperationDescriptor, …]

operations_for(capability)

Resolve all public callables implementing one capability.

Parameters:

capability (Capability | str)

Return type:

tuple[Callable[[…], Any], …]

named_operation(key)

Resolve one public operation by its stable module-local key.

Parameters:

key (str)

Return type:

Callable[[…], Any]

resolve_type(name)

Resolve a declared public type alias lazily.

Parameters:

namestr or None

Public type alias in the module namespace. None represents an unsupported or inapplicable contract type.

Returns:

type or None

Resolved public class, or None when no alias was declared.

Raises:

AttributeError

If the declared alias is missing from the namespace.

TypeError

If the resolved object is not a class.

Parameters:

name (str | None)

Return type:

type[Any] | None

property input_type: type[Any] | None

Return the public input type, when applicable.

Returns:

type or None

Namespace Input/dataset class, or None when the workflow has no single input contract.

property options_type: type[Any] | None

Return the public options type, when applicable.

Returns:

type or None

Namespace options class, or None when configuration is operation-specific.

property result_type: type[Any] | None

Return the public scientific result type, when applicable.

Returns:

type or None

Typed scientific payload or fit-result class exposed by the namespace, or None when no single result type applies.

class quantas.api.registry.OperationDescriptor(key, capability, function_name, name, description='')

Bases: object

Describe one named public operation within a module capability.

Parameters:

keystr

Stable operation identifier unique within the module.

capabilityCapability

Broad frontend-neutral capability implemented by the operation.

function_namestr

Public callable name in the module API namespace.

namestr

Human-readable operation name.

descriptionstr, optional

Concise workflow description suitable for application discovery.

Parameters:

• key (str)

• capability (Capability)

• function_name (str)

• name (str)

• description (str)

resolve(module)

Resolve the described callable from an imported API namespace.

Parameters:

module (ModuleType)

Return type:

Callable[[…], Any]

A capability may have one canonical operation and additional named operations. For example, Thermoelasticity and EOS expose several scientifically distinct exports. Use operations_for to enumerate them and named_operation to resolve one stable operation key.

eos = registry.get("eos")
for operation in eos.list_operations(Capability.EXPORT):
    print(operation.key, operation.name)

write_diagnostics = eos.named_operation("export_diagnostics_csv")

Discovery

quantas.api.registry.get(name)

Return one public module descriptor by stable identifier.

Parameters:

namestr

Stable module identifier such as qha or eos.

Returns:

ModuleDescriptor

Public API and capability descriptor.

Raises:

KeyError

If the module identifier is unknown.

Parameters:

name (str)

Return type:

ModuleDescriptor

quantas.api.registry.iter_modules()

Iterate over public scientific module descriptors.

Returns:

iterator of ModuleDescriptor

Lazy iterator over the stable descriptor sequence.

Return type:

Iterator[ModuleDescriptor]

quantas.api.registry.list_modules()

Return all public scientific module descriptors.

Returns:

tuple of ModuleDescriptor

Immutable descriptors in stable frontend display order.

Return type:

tuple[ModuleDescriptor, …]

Result dispatch

module_from_result inspects native metadata rather than filename conventions. open_result dispatches to the public module reader or EOS archive as appropriate.

quantas.api.registry.module_from_result(path)

Inspect native HDF5 metadata and return the responsible module.

Parameters:

pathstr or Path

Native Quantas HDF5 result or archive.

Returns:

ModuleDescriptor

Descriptor selected from the persisted metadata/module value.

Raises:

ValueError

If Quantas metadata are absent.

KeyError

If the persisted module identifier is unsupported.

Parameters:

path (str | Path)

Return type:

ModuleDescriptor

quantas.api.registry.open_result(path, *, writable=False)

Open a native Quantas result using metadata-driven dispatch.

Parameters:

pathstr or Path

Native Quantas HDF5 result or archive.

writablebool, optional

Request writable access. This is supported only by archive-style modules such as EOS.

Returns:

Any

quantas.models.ResultData for single-shot modules or an active module-specific archive for archive-style workflows.

Raises:

ValueError

If writable access is requested for a single-shot result or the module has no registered native reader.

KeyError

If the persisted module identifier is unsupported.

Parameters:

• path (str | Path)

• writable (bool)

Return type:

Any

Notes

EOS returns an active archive because it stores datasets and immutable fit records rather than one result envelope. Callers must close that archive.

See also

• Python API

• Native HDF5 results

• Inspecting and extracting native HDF5 data