httk.core.register

Backward-compatible exports for registry implementations split by type.

Submodules

• httk.core.register.cli
• httk.core.register.entries
• httk.core.register.io
• httk.core.register.schemas

Attributes

CLIHandler
entry_providers
format_adapters
format_serializers
reader_filenames
readers
writer_filenames
writer_formats
writers

Classes

PluginRegistry	Registry mapping keys -> plugin specs.
CLICommand	Store registration metadata for one top-level httk command.
OptimadeEntryBinding	Describe lazy typed handling for one exact entry-type definition IRI.

Functions

resolve_callable(ref)	Resolve a callable reference.
cli_command(name)	Return command metadata without importing its implementation.
register_cli_command(name, handler, summary)	Register a lazy top-level httk command.
entry_family_info(name)	Return entry-family metadata without importing its class.
entry_record_info(name)	Return record, family, and definition metadata without importing the record class.
known_entry_families()	Return registered entry-family names.
known_entry_providers()	Return registered entry-provider names.
known_entry_records([family])	Return registered record names, optionally limited to a family.
known_optimade_entry_bindings()	Return registered entry-type definition IRIs without resolving imports.
optimade_entry_binding(definition_id)	Return the exact-IRI binding without importing its backend or view.
register_entry_family(*, name, family[, definition_id])	Register a lazy entry-family class reference without importing it.
register_entry_provider(*, name, factory)	Register an EntryProvider factory under name.
register_entry_record(*, name, record[, family, ...])	Register a lazy record-class reference and optional family and definition IRI.
register_optimade_entry_binding(*, name, ...[, ...])	Register one lazy typed binding, selected only by exact definition IRI.
resolve_entry_family(name)	Import and return a registered entry-family class.
resolve_entry_record(name)	Import and return a registered record class.
has_reader_for(name)	Return whether name matches a registered reader key.
known_extensions()	Return the registered reader extensions.
known_filenames()	Return the registered reader basenames.
known_format_adapters()	Return format tags mapped to their registered adapter names.
known_writer_formats()	Return registered writer format tags.
known_writers()	Return the registered writer extension and basename dispatch keys.
register_format_adapter(*, name, adapter, formats)	Register one lazy adapter for each neutral payload format in formats.
register_format_serializer(*, format, serializer)	Register one lazy serializer for a neutral payload format tag.
register_reader(*, name, reader[, extensions, filenames])	Register a reader under one or more file extensions and/or filenames.
register_writer(*, name, writer, format[, extensions, ...])	Register a writer under one or more extensions and/or exact basenames.
known_entry_type_definitions()	Return registered entry-type definition IRIs.
known_property_definitions()	Return registered property definition IRIs.
load_entry_type_definition(definition_id)	Load and verify a registered entry-type definition resource.
load_property_definition(definition_id)	Load and verify a registered property definition resource.
register_entry_type_definition(*, definition_id, resource)	Register one resource for an entry-type definition IRI.
register_property_definition(*, definition_id, resource)	Register one resource for a property definition IRI.

Package Contents

class httk.core.register.PluginRegistry

Registry mapping keys -> plugin specs.

Intended use:

• readers: key is file extension “.cif”

• savers: key is file extension “.cif” or format name

• show/visualization: key is format/backend name

register(*, key, handler, name=None)

keys()

items()

get(key)

require(key)

dispatch(key, *args, **kwargs)

httk.core.register.resolve_callable(ref)

Resolve a callable reference.

Accepts:

• a callable object

• a string of form “module.submodule:callable_name”

class httk.core.register.CLICommand

Store registration metadata for one top-level httk command.

Parameters:

• name – The lowercase hyphen-separated command name.

• handler – The command callable or lazy reference.

• summary – The one-line command summary.

name: str

handler: str | collections.abc.Callable[Ellipsis, Any]

summary: str

resolve()

Import and return the registered command implementation.

Returns:

The resolved command handler.

Return type:

CLIHandler

httk.core.register.CLIHandler

httk.core.register.cli_command(name)

Return command metadata without importing its implementation.

Parameters:

name (str) – The command name to look up.

Returns:

Command metadata, or None if it is not registered.

Return type:

CLICommand | None

httk.core.register.register_cli_command(name, handler, summary)

Register a lazy top-level httk command.

A handler is either a callable or a lazy "module:callable" reference with the contract (argv: Sequence[str], context: CLIContext) -> int. Names use lowercase, hyphen-separated command syntax. Registration is intentionally strict: reserved names and duplicate registrations are errors rather than order-dependent overrides.

Parameters:

• name (str) – The lowercase hyphen-separated command name.

• handler (str | collections.abc.Callable[Ellipsis, Any]) – The command callable or lazy "module:callable" reference.

• summary (str) – The nonempty one-line command summary.

Raises:

• TypeError – If handler is neither callable nor a lazy reference.

• ValueError – If the name, handler reference, summary, or registration is invalid.

class httk.core.register.OptimadeEntryBinding

Describe lazy typed handling for one exact entry-type definition IRI.

Parameters:

• name – The binding registry name.

• definition_id – The exact entry-type definition IRI selected by the binding.

• backend – The lazy backend class reference.

• view – The lazy view class reference.

• property_decoders – Property definition IRIs mapped to lazy decoder references.

• query_fields – Property definition IRIs supported for querying, if restricted.

name: str

definition_id: str

backend: str

view: str

property_decoders: collections.abc.Mapping[str, str]

query_fields: tuple[str, Ellipsis] | None = None

resolve_backend()

Import and return this binding’s backend class on demand.

Returns:

The resolved backend class.

Raises:

TypeError – If the lazy reference does not resolve to a class.

Return type:

type

resolve_view()

Import and return this binding’s view class on demand.

Returns:

The resolved view class.

Raises:

TypeError – If the lazy reference does not resolve to a class.

Return type:

type

resolve_property_decoder(definition_id)

Resolve one property decoder, or return None when it is unbound.

Parameters:

definition_id (str) – The property definition IRI to resolve.

Returns:

The decoder callable, or None when no decoder is registered.

Return type:

collections.abc.Callable[Ellipsis, Any] | None

httk.core.register.entry_family_info(name)

Return entry-family metadata without importing its class.

Parameters:

name (str) – The registered entry-family name.

Returns:

The lazy family reference and optional definition IRI.

Raises:

ValueError – If name is not registered.

Return type:

tuple[str, str | None]

httk.core.register.entry_providers

httk.core.register.entry_record_info(name)

Return record, family, and definition metadata without importing the record class.

Parameters:

name (str) – The registered record name.

Returns:

The lazy record reference and optional family and definition IRI.

Raises:

ValueError – If name is not registered.

Return type:

tuple[str, str | None, str | None]

httk.core.register.known_entry_families()

Return registered entry-family names.

Returns:

Registered entry-family names.

Return type:

list[str]

httk.core.register.known_entry_providers()

Return registered entry-provider names.

Returns:

Registered provider names.

Return type:

list[str]

httk.core.register.known_entry_records(family=None)

Return registered record names, optionally limited to a family.

Parameters:

family (str | None) – An entry-family name to filter by, or None for all records.

Returns:

Matching record registry names.

Return type:

list[str]

httk.core.register.known_optimade_entry_bindings()

Return registered entry-type definition IRIs without resolving imports.

Returns:

Exact definition IRIs with registered bindings.

Return type:

tuple[str, Ellipsis]

httk.core.register.optimade_entry_binding(definition_id)

Return the exact-IRI binding without importing its backend or view.

Parameters:

definition_id (str) – The exact entry-type definition IRI to look up.

Returns:

The binding, or None if no exact match is registered.

Return type:

OptimadeEntryBinding | None

httk.core.register.register_entry_family(*, name, family, definition_id=None)

Register a lazy entry-family class reference without importing it.

Parameters:

• name (str) – The entry-family registry name.

• family (str) – The lazy "module:class" family reference.

• definition_id (str | None) – The family’s definition IRI, if any.

Raises:

ValueError – If validation fails or name is already registered.

httk.core.register.register_entry_provider(*, name, factory)

Register an EntryProvider factory under name.

factory is a lazy "module:callable" reference to a callable that constructs a provider (providers need data, so applications call the factory themselves; the registry only records how to reach it). This mirrors register_reader.

Parameters:

• name (str) – The provider registry name.

• factory (str) – The lazy "module:callable" factory reference.

httk.core.register.register_entry_record(*, name, record, family=None, definition_id=None)

Register a lazy record-class reference and optional family and definition IRI.

Parameters:

• name (str) – The record registry name.

• record (str) – The lazy "module:class" record reference.

• family (str | None) – The logical entry-family name, if any.

• definition_id (str | None) – The record’s definition IRI, if any.

Raises:

ValueError – If validation fails or name is already registered.

httk.core.register.register_optimade_entry_binding(*, name, definition_id, backend, view, property_decoders=None, query_fields=None)

Register one lazy typed binding, selected only by exact definition IRI.

Parameters:

• name (str) – The binding registry name.

• definition_id (str) – The exact entry-type definition IRI selected by the binding.

• backend (str) – The lazy backend class reference.

• view (str) – The lazy view class reference.

• property_decoders (collections.abc.Mapping[str, str] | None) – Property definition IRIs mapped to lazy decoder references.

• query_fields (tuple[str, Ellipsis] | None) – Property definition IRIs supported for querying, if restricted.

Raises:

ValueError – If the definition IRI is already registered or input is invalid.

httk.core.register.resolve_entry_family(name)

Import and return a registered entry-family class.

Parameters:

name (str) – The registered entry-family name.

Returns:

The resolved entry-family class.

Raises:

• ValueError – If name is not registered.

• TypeError – If the reference does not resolve to a class.

Return type:

type

httk.core.register.resolve_entry_record(name)

Import and return a registered record class.

Parameters:

name (str) – The registered record name.

Returns:

The resolved frozen dataclass record class.

Raises:

• ValueError – If name is not registered.

• TypeError – If the reference does not resolve to a frozen dataclass.

Return type:

type

httk.core.register.format_adapters

httk.core.register.format_serializers

httk.core.register.has_reader_for(name)

Return whether name matches a registered reader key.

Parameters:

name (str) – Filename or URL path whose reader registration is checked.

Returns:

Whether the name matches a registered extension or exact basename.

Return type:

bool

httk.core.register.known_extensions()

Return the registered reader extensions.

Returns:

Lower-case reader suffixes.

Return type:

list[str]

httk.core.register.known_filenames()

Return the registered reader basenames.

Returns:

Lower-case reader basenames.

Return type:

list[str]

httk.core.register.known_format_adapters()

Return format tags mapped to their registered adapter names.

Returns:

Format tags mapped to registry names.

Return type:

dict[str, str]

httk.core.register.known_writer_formats()

Return registered writer format tags.

Returns:

Registered neutral payload format tags.

Return type:

list[str]

httk.core.register.known_writers()

Return the registered writer extension and basename dispatch keys.

Returns:

Writer keys selected by extensions or exact basenames.

Return type:

list[str]

httk.core.register.reader_filenames

httk.core.register.readers

httk.core.register.register_format_adapter(*, name, adapter, formats)

Register one lazy adapter for each neutral payload format in formats.

adapter may be a callable or a lazy "module:callable" reference. A format tag has one owner: registering it again raises an error naming both the existing and attempted registrants.

Parameters:

• name (str) – The registry name for the adapter.

• adapter (str | collections.abc.Callable[Ellipsis, Any]) – The adapter callable or lazy "module:callable" reference.

• formats (collections.abc.Sequence[str]) – Neutral payload format tags served by the adapter.

Raises:

ValueError – If a format tag is invalid, duplicated, or already owned.

httk.core.register.register_format_serializer(*, format, serializer)

Register one lazy serializer for a neutral payload format tag.

Parameters:

• format (str) – The neutral payload format tag.

• serializer (str | collections.abc.Callable[Ellipsis, Any]) – The serializer callable or lazy reference.

Raises:

ValueError – If format is invalid or already has another serializer.

httk.core.register.register_reader(*, name, reader, extensions=(), filenames=())

Register a reader under one or more file extensions and/or filenames.

extensions are matched (case-insensitively) against a file’s suffix, e.g. ".cif". filenames are exact basenames matched (case-insensitively) against a file’s name with any recognized compression suffix stripped, e.g. "POSCAR" matches POSCAR, poscar, and POSCAR.bz2.

Parameters:

• name (str) – The registry name for the reader.

• reader (str) – A lazy "module:callable" reference to the reader.

• extensions (tuple[str, Ellipsis]) – File suffixes that select the reader.

• filenames (tuple[str, Ellipsis]) – Exact basenames that select the reader.

httk.core.register.register_writer(*, name, writer, format, extensions=(), filenames=())

Register a writer under one or more extensions and/or exact basenames.

A format can have one writer owner; registering a conflicting writer raises an error. Extension and basename keys are matched case-insensitively.

Parameters:

• name (str) – The registry name for the writer.

• writer (str | collections.abc.Callable[Ellipsis, Any]) – The writer callable or lazy "module:callable" reference.

• format (str) – The neutral payload format emitted by the writer.

• extensions (tuple[str, Ellipsis]) – File suffixes that select the writer.

• filenames (tuple[str, Ellipsis]) – Exact basenames that select the writer.

Raises:

ValueError – If format is invalid or conflicts with an existing writer.

httk.core.register.writer_filenames

httk.core.register.writer_formats

httk.core.register.writers

httk.core.register.known_entry_type_definitions()

Return registered entry-type definition IRIs.

Returns:

Registered entry-type definition identifiers.

Return type:

list[str]

httk.core.register.known_property_definitions()

Return registered property definition IRIs.

Returns:

Registered property definition identifiers.

Return type:

list[str]

httk.core.register.load_entry_type_definition(definition_id)

Load and verify a registered entry-type definition resource.

Parameters:

definition_id (str) – The registered entry-type definition IRI.

Returns:

The loaded and validated entry-type definition.

Raises:

ValueError – If the IRI is unregistered or disagrees with the document.

Return type:

httk.core.property_definitions.EntryTypeDefinition

httk.core.register.load_property_definition(definition_id)

Load and verify a registered property definition resource.

Parameters:

definition_id (str) – The registered property definition IRI.

Returns:

The loaded and validated property definition.

Raises:

ValueError – If the IRI is unregistered or disagrees with the document.

Return type:

httk.core.property_definitions.PropertyDefinition

httk.core.register.register_entry_type_definition(*, definition_id, resource)

Register one resource for an entry-type definition IRI.

Parameters:

• definition_id (str) – The entry-type definition IRI.

• resource (str) – The package resource reference to load.

Raises:

ValueError – If definition_id is already registered.

httk.core.register.register_property_definition(*, definition_id, resource)

Register one resource for a property definition IRI.

Parameters:

• definition_id (str) – The property definition IRI.

• resource (str) – The package resource reference to load.

Raises:

ValueError – If definition_id is already registered.