httk.optimade

Submodules

• httk.optimade.api
• httk.optimade.backend
• httk.optimade.endpoints
• httk.optimade.engine
• httk.optimade.filter
• httk.optimade.model
• httk.optimade.runtime
• httk.optimade.schema

Exceptions

OptimadeError	Common base class for all non-exit exceptions.
TranslatorError	Common base class for all non-exit exceptions.

Classes

BackendAdapter	Binds a store to the OPTIMADE entry endpoints it serves.
EntrySource	One queryable source (table/type) behind an OPTIMADE entry endpoint.
InMemoryStore	A store over dict rows: InMemoryStore({'structures': [ {...}, ... ]}).
EndpointResponse	A response produced by an endpoint, to be serialized by the web layer.
OptimadeConfig	Configuration of a served OPTIMADE database.
RawRequest	An incoming OPTIMADE request, as handed over by the web layer.
ValidatedParameters	Validated URL query parameters of an OPTIMADE request.
ValidatedRequest	The result of validating a RawRequest.

Functions

create_asgi_app(→ starlette.applications.Starlette)	Create an ASGI application serving an OPTIMADE API for the given backend.
serve(→ None)	Serve an OPTIMADE API for the given backend with a development web server.
adapter_from_providers(...)	Build a BackendAdapter serving the given entry providers.
providers_from_registry(→ dict[str, ...)	Return the registered entry-provider factories keyed by their registered name.
process(→ httk.optimade.model.request.EndpointResponse)	Process an OPTIMADE query.
process_init(→ None)	Precompute the number of available entries per entry endpoint.

Package Contents

httk.optimade.create_asgi_app(adapter: httk.optimade.backend.adapter.BackendAdapter, config: httk.optimade.model.config.OptimadeConfig | None = None, *, baseurl: str | None = None, debug: bool = False) → starlette.applications.Starlette

Create an ASGI application serving an OPTIMADE API for the given backend.

httk.optimade.serve(adapter: httk.optimade.backend.adapter.BackendAdapter, config: httk.optimade.model.config.OptimadeConfig | None = None, *, host: str = '127.0.0.1', port: int = 8080, baseurl: str | None = None, debug: bool = False) → None

Serve an OPTIMADE API for the given backend with a development web server.

class httk.optimade.BackendAdapter

Binds a store to the OPTIMADE entry endpoints it serves.

sources maps entry endpoint names (e.g. 'structures') to the sources queried for that endpoint; an endpoint with several sources (e.g. several calculation result types) is queried across all of them.

schema is required: it declares the served entry types and properties. field_handlers maps each entry type to its filter-handler table. When omitted (left empty) it is derived from schema via simple_property_handlers(), using an identity property-key map (each property is filtered against a backend field of the same name); a backend whose field names differ, or that wants finer control, supplies its own tables instead.

store: httk.data.query.Store

sources: collections.abc.Mapping[str, collections.abc.Sequence[EntrySource]]

schema: httk.optimade.schema.served.ServedSchema

field_handlers: collections.abc.Mapping[str, httk.data.optimade_query.HandlerTable]

query_function() → httk.optimade.model.results.QueryFunction

class httk.optimade.EntrySource

One queryable source (table/type) behind an OPTIMADE entry endpoint.

target is what gets passed to searcher.variable(); fields maps OPTIMADE response-field names to extractors applied to matched row objects. relationships, when set, is an extractor mapping a matched row to a dictionary keyed by related entry type, each value a list of {'id': str, 'description': str?, 'role': str?} dictionaries. sort_keys maps response-field names to the backend field names to sort on. property_metadata maps response-field names to extractors returning the per-property metadata dictionary for a matched row (or None when there is no metadata for that row).

target: Any

fields: collections.abc.Mapping[str, FieldExtractor]

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

relationships: FieldExtractor | None = None

property_metadata: collections.abc.Mapping[str, FieldExtractor]

class httk.optimade.InMemoryStore(tables: dict[str, list[Row]])

A store over dict rows: InMemoryStore({'structures': [ {...}, ... ]}).

tables

searcher() → MemorySearcher

httk.optimade.adapter_from_providers(providers: collections.abc.Iterable[httk.core.EntryProvider], **options: Any) → httk.optimade.backend.adapter.BackendAdapter

Build a BackendAdapter serving the given entry providers.

Every provider’s entry_types() become served entry types (described by their EntryTypeDefinition), its property_keys() name the served subset and drive both the filter handlers (via simple_property_handlers()) and the response-field extractors, and its records() are loaded into an InMemoryStore. Every served property MUST be described by the entry type’s definition (a custom property must therefore live in an extended() definition); a ValueError names any offender. All served properties beyond id/type are marked default-response. Extra keyword options (e.g. sortable, recognized_prefixes) are forwarded to build_served_schema(); every served property is sortable-capable, since the provider’s property-key map is passed through as the source’s sort_keys.

Declared relationships (relationships()) are fully auto-wired for serving and filtering: for each entry type with declared relationships, a synthetic __rel_<related_type> id-list field is materialized on EVERY row of that entry type (an empty list when the row has no related entries of that type, so inverse set semantics are well-defined), and a '<related_type>.id' entry built with relationship_id_handler() is merged into the entry type’s derived filter-handler table (never overwriting an entry already present, mirroring how BackendAdapter respects explicitly supplied handler tables). <related_type>.id HAS ... filters — and, through the related-property resolver of translate_filter(), depth-1 relationship-property filters such as references.doi CONTAINS "10.1" — therefore work without any hand-wiring.

httk.optimade.providers_from_registry() → dict[str, collections.abc.Callable[Ellipsis, httk.core.EntryProvider]]

Return the registered entry-provider factories keyed by their registered name.

Resolves each factory registered via httk.core.register_entry_provider() (through httk.handlers.* self-registration) into a callable. Providers need data, so applications instantiate them: providers_from_registry()["atomistic-structures"](data).

httk.optimade.process(request: httk.optimade.model.request.RawRequest, query_function: httk.optimade.model.results.QueryFunction, version: str, config: httk.optimade.model.config.OptimadeConfig, schema: httk.optimade.schema.served.ServedSchema, *, debug: bool = False) → httk.optimade.model.request.EndpointResponse

Process an OPTIMADE query.

request carries the incoming request; only baseurl and representation must be set, missing information is derived from representation. query_function is the callback used to execute entry queries against the backend. schema describes the served entry types and properties.

httk.optimade.process_init(config: httk.optimade.model.config.OptimadeConfig, query_function: httk.optimade.model.results.QueryFunction, schema: httk.optimade.schema.served.ServedSchema, *, debug: bool = False) → None

Precompute the number of available entries per entry endpoint.

class httk.optimade.EndpointResponse

A response produced by an endpoint, to be serialized by the web layer.

Either json_response (a JSON:API document) or content (a raw body) is set.

response_code: int = 200

response_msg: str = 'OK'

content_type: str = 'application/vnd.api+json'

encoding: str = 'utf-8'

content: str | None = None

json_response: dict[str, Any] | None = None

class httk.optimade.OptimadeConfig

Configuration of a served OPTIMADE database.

implementation extends/overrides the fields of the meta -> implementation dictionary (e.g. issue_tracker, source_url, maintainer). database, schema_url, and request_delay populate the corresponding optional meta fields (OPTIMADE v1.2+) when set. license, available_licenses, and available_licenses_for_entries populate the corresponding optional base-info attributes when set. data_available is filled in by process_init with the number of available entries per entry endpoint.

provider: dict[str, Any]

links: list[dict[str, Any]] = []

implementation: dict[str, Any]

database: dict[str, Any] | None = None

schema_url: str | None = None

request_delay: float | None = None

license: dict[str, Any] | str | None = None

available_licenses: list[str] | None = None

available_licenses_for_entries: list[str] | None = None

data_available: dict[str, int]

partial_data_chunk_size: int = 1000

exception httk.optimade.OptimadeError(message: str, response_code: int, response_message: str, longmsg: str | None = None)

Bases: Exception

Common base class for all non-exit exceptions.

response_code

response_msg

content

class httk.optimade.RawRequest

An incoming OPTIMADE request, as handed over by the web layer.

Only baseurl and representation are mandatory; missing information is derived from representation during validation.

baseurl: str

representation: str

relurl: str | None = None

querystr: str | None = None

query: dict[str, str] | None = None

endpoint: str | None = None

request_id: str | None = None

version: str | None = None

exception httk.optimade.TranslatorError(message: str, response_code: int, response_message: str, longmsg: str | None = None)

Bases: OptimadeError

Common base class for all non-exit exceptions.

class httk.optimade.ValidatedParameters

Validated URL query parameters of an OPTIMADE request.

response_format: str = 'json'

page_limit: int = 50

page_offset: int = 0

response_fields: str | None = None

filter: str | None = None

sort: str | None = None

include: str | None = None

dimension_slices: dict[str, RequestedSlice]

as_query_dict() → dict[str, str]

Return the parameters as a URL query dict, omitting unset values.

class httk.optimade.ValidatedRequest

The result of validating a RawRequest.

baseurl: str

representation: str

endpoint: str

version: str

query: ValidatedParameters

url_version: str | None = None

request_id: str | None = None

recognized_response_fields: list[str] = []

unrecognized_response_fields: list[str] = []

sort_fields: list[tuple[str, bool]] = []

include_paths: list[str] = []

property_metadata_requested: bool = False

partial_data_parts: tuple[str, str, str] | None = None

partial_data_offset: int = 0

warnings: list[dict[str, Any]] = []