httk.serve.optimade

Public generic OPTIMADE serving and query APIs.

Submodules

Exceptions

OptimadeError

Represent an OPTIMADE response error.

TranslatorError

Represent a filter translation failure with an HTTP response contract.

Classes

BackendAdapter

Bind a store to the OPTIMADE entry endpoints it serves.

EntrySource

Describe one queryable source behind an OPTIMADE entry endpoint.

InMemoryStore

Provide a store over dictionary rows.

StoredBackendAdapter

Serve one data federation per OPTIMADE entry type.

EndpointResponse

Represent an endpoint response for serialization by the web layer.

OptimadeConfig

Configure a served OPTIMADE database.

OptimadeIndexConfig

Configure an OPTIMADE index meta-database.

RawRequest

Represent an incoming OPTIMADE request from the web layer.

ValidatedParameters

Represent validated URL query parameters of an OPTIMADE request.

ValidatedRequest

Represent the result of validating a RawRequest.

Functions

create_asgi_app(adapter[, config, baseurl, debug, ...])

Create an ASGI application serving an OPTIMADE API for a backend or store.

create_index_asgi_app(config, *[, baseurl, debug, ...])

Create an ASGI application for an OPTIMADE index meta-database.

serve(adapter[, config, host, port, baseurl, debug, ...])

Serve an OPTIMADE API for a backend or entry store with a development server.

adapter_from_providers(providers, **options)

Build a BackendAdapter serving the given entry providers.

adapter_from_store(store, **options)

Build a lazy OPTIMADE adapter from every described family in one store.

adapter_from_stores(sources, **options)

Build a lazy store-backed adapter from durable entry sources.

providers_from_registry()

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

process(request, query_function, version, config, ...)

Process one OPTIMADE query.

Package Contents

httk.serve.optimade.create_asgi_app(adapter, config=None, *, baseurl=None, debug=False, report_level='warning', report_context_levels=None)[source]

Create an ASGI application serving an OPTIMADE API for a backend or store.

An absent baseurl makes the application derive a mount-aware URL from the request. An explicit value is authoritative.

Parameters:
Returns:

Configured serving application.

Return type:

httk.serve.http.ServeApp

httk.serve.optimade.create_index_asgi_app(config, *, baseurl=None, debug=False, report_level='warning', report_context_levels=None)[source]

Create an ASGI application for an OPTIMADE index meta-database.

The index serves only discovery, links, and unversioned version negotiation. It has no backend adapter and performs no query calls. The supplied configuration is retained as the response metadata source; the composed application’s caller owns its lifetime and configuration.

Parameters:
Returns:

Configured serving application.

Raises:

TypeError – If config is not an OptimadeIndexConfig.

Return type:

httk.serve.http.ServeApp

httk.serve.optimade.serve(adapter, config=None, *, host='127.0.0.1', port=8080, baseurl=None, debug=False, report_level='warning', report_context_levels=None)[source]

Serve an OPTIMADE API for a backend or entry store with a development server.

Parameters:
class httk.serve.optimade.BackendAdapter[source]

Bind 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.

Parameters:

  • store – Store implementing the neutral query protocol.

  • sources – Queryable sources keyed by entry endpoint.

  • schema – Required schema describing served entries and properties.

  • field_handlers – Optional filter handlers keyed by entry endpoint.

store: httk.store.query.Store
sources: collections.abc.Mapping[str, collections.abc.Sequence[EntrySource]]
schema: httk.serve.optimade.schema.served.ServedSchema
field_handlers: collections.abc.Mapping[str, httk.store.query.optimade_filters.HandlerTable]
query_function()[source]

Return the callback that executes queries through this adapter.

Returns:

Query callback consumed by the OPTIMADE request engine.

Return type:

httk.serve.optimade.model.results.QueryFunction

class httk.serve.optimade.EntrySource[source]

Describe one queryable source 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).

Parameters:

  • target – Store-specific target passed to searcher.variable.

  • fields – Response-field extractors applied to matched rows.

  • sort_keys – Response-field to backend-sort-field mappings.

  • relationships – Optional extractor for related-resource data.

  • property_metadata – Optional per-property metadata extractors.

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.serve.optimade.InMemoryStore(tables)[source]

Provide a store over dictionary rows.

Parameters:

tables (dict[str, list[Row]]) – Row lists keyed by table name.

tables
searcher(*, as_of=None)[source]

Create a searcher over this store’s tables.

Parameters:

as_of (object) – Optional historic timestamp cutoff; unsupported here.

Returns:

Fresh in-memory searcher.

Raises:

ValueError – If a historic cutoff is requested.

Return type:

MemorySearcher

class httk.serve.optimade.StoredBackendAdapter[source]

Serve one data federation per OPTIMADE entry type.

Parameters:

  • federations – Durable federations keyed by entry endpoint.

  • schema – Schema describing the federations’ served entries.

federations: collections.abc.Mapping[str, Any]
schema: httk.serve.optimade.schema.served.ServedSchema
snapshot_cutoff_ns(entry_type, now_ns)[source]

Return the resolution-aware snapshot cutoff for one entry type.

query_function()[source]

Return the callback that queries the configured federations.

Returns:

Query callback consumed by the OPTIMADE request engine.

Return type:

httk.serve.optimade.model.results.QueryFunction

httk.serve.optimade.adapter_from_providers(providers, **options)[source]

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.

A provider’s reverse relationships (EntryProvider.reverse_relationships()) are consumed too: their target-keyed related entries are append-merged into each served target entry’s relationships (never clobbering the forward entries), so a derived reverse edge is served on the entry it points at.

Parameters:
Returns:

Fully wired in-memory backend adapter.

Raises:

ValueError – If provider keys or served properties are invalid.

Return type:

httk.serve.optimade.backend.adapter.BackendAdapter

httk.serve.optimade.adapter_from_store(store, **options)[source]

Build a lazy OPTIMADE adapter from every described family in one store.

Families declared without an entry-type definition are deliberately ignored. This lets application-specific records, such as DSP publication declarations, coexist with OPTIMADE records in one durable layout.

Parameters:
Returns:

Lazy adapter over all configured OPTIMADE families.

Raises:

  • TypeError – If store does not implement EntryStore.

  • ValueError – If the store contains no OPTIMADE-described family.

Return type:

StoredBackendAdapter

httk.serve.optimade.adapter_from_stores(sources, **options)[source]

Build a lazy store-backed adapter from durable entry sources.

Sources with the same exact logical family are federated under one entry endpoint. The data layer owns all source/backing traversal and global pagination; this adapter advertises the family’s definition and turns only the returned page into OPTIMADE result rows.

Parameters:

  • sources (collections.abc.Sequence[httk.store.backend.sql.StoredEntrySource]) – Durable entry sources to federate by entry type.

  • **options (Any) – Schema options forwarded to build_served_schema(), e.g. default_includes (per served entry type, the served entry types to include by default on single-entry requests; always unioned with references).

Returns:

Lazy adapter over the supplied durable sources.

Raises:

  • ValueError – If sources conflict or expose incomplete sort mappings.

  • TypeError – If a source is not a stored entry source.

Return type:

StoredBackendAdapter

httk.serve.optimade.providers_from_registry()[source]

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

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

Returns:

Registered provider factories keyed by registry name.

Return type:

dict[str, collections.abc.Callable[…, httk.core.EntryProvider]]

httk.serve.optimade.process(request, query_function, version, config, schema, *, snapshot_cutoff_ns=None, debug=False)[source]

Process one 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.

Parameters:
Returns:

Endpoint response before web serialization.

Raises:

httk.serve.optimade.model.errors.OptimadeError – If request validation or endpoint processing fails.

Return type:

httk.serve.optimade.model.request.EndpointResponse

class httk.serve.optimade.EndpointResponse[source]

Represent an endpoint response for serialization by the web layer.

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

Parameters:

  • response_code – HTTP status code.

  • response_msg – HTTP status title.

  • content_type – Response media type.

  • encoding – Response character encoding.

  • content – Raw response body, when the response is not JSON.

  • json_response – JSON:API response document, when the response is JSON.

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.serve.optimade.OptimadeConfig[source]

Configure 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.

Parameters:

  • provider – Provider metadata for the OPTIMADE response envelope.

  • links – Provider links exposed by the /links endpoint.

  • implementation – Implementation metadata merged into response metadata.

  • database – Optional database metadata for response metadata.

  • schema_url – URL of the served schema, when one is available.

  • request_delay – Optional advertised request delay.

  • license – License metadata exposed by the base-info endpoint.

  • available_licenses – Licenses advertised for the service.

  • available_licenses_for_entries – Licenses advertised for entries.

  • page_limit_max – Largest page_limit accepted; larger requests get a 403.

  • partial_data_chunk_size – Number of outer items emitted per partial-data page.

  • cors_origins – Exact browser origins allowed to make cross-origin requests.

Raises:

ValueError – If page_limit_max is not an integer >= 1.

provider: 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
page_limit_max: int = 50
partial_data_chunk_size: int = 1000
cors_origins: tuple[str, ...] = ()
exception httk.serve.optimade.OptimadeError(message, response_code, response_message, longmsg=None)[source]

Bases: Exception

Represent an OPTIMADE response error.

Parameters:

  • message (str) – Short error detail used as the exception message.

  • response_code (int) – HTTP status code returned to the client.

  • response_message (str) – HTTP status title returned to the client.

  • longmsg (str | None) – Optional longer error detail returned in the response.

response_code
response_msg
content
class httk.serve.optimade.OptimadeIndexConfig[source]

Bases: OptimadeConfig

Configure an OPTIMADE index meta-database.

The links are the configured databases advertised by the index. Exactly one must have link_type == "root"; child links are the databases that may be selected as the index’s default relationship. The regular OptimadeConfig remains a non-index service configuration.

Parameters:

default_link_id – Identifier of the default configured child link, or None when the index has no default.

Raises:

ValueError – If configured links do not satisfy the links schema or the root/default-link constraints.

class httk.serve.optimade.RawRequest[source]

Represent an incoming OPTIMADE request from the web layer.

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

Parameters:

  • baseurl – Base URL used when generating response links.

  • representation – Request path and query representation.

  • relurl – Relative request URL, when supplied by the web layer.

  • querystr – Raw query string.

  • query – Parsed query parameters.

  • endpoint – Preselected endpoint, when supplied by the caller.

  • request_id – Preselected entry identifier, when supplied by the caller.

  • version – API version declared by the caller.

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.serve.optimade.TranslatorError(message, response_code, response_message, longmsg=None)[source]

Bases: OptimadeError

Represent a filter translation failure with an HTTP response contract.

class httk.serve.optimade.ValidatedParameters[source]

Represent validated URL query parameters of an OPTIMADE request.

Parameters:

  • response_format – Requested response format.

  • page_limit – Maximum number of entries in a page.

  • page_offset – Number of matching entries to skip.

  • response_fields – Comma-separated requested response fields.

  • filter – Raw OPTIMADE filter expression.

  • sort – Raw OPTIMADE sort expression.

  • include – Raw related-entry inclusion request.

  • as_of – Nanosecond timestamp cutoff for timestamp-capable stored sources; timestamp-disabled sources may serve current state and generic providers ignore it.

  • dimension_slices – Requested slices keyed by dimension name.

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
as_of: int | None = None
dimension_slices: dict[str, RequestedSlice]
as_query_dict()[source]

Return the parameters as a URL query mapping.

Returns:

Query values with unset optional parameters omitted.

Return type:

dict[str, str]

class httk.serve.optimade.ValidatedRequest[source]

Represent the result of validating a RawRequest.

Parameters:

  • baseurl – Base URL used when generating response links.

  • representation – Original request representation.

  • endpoint – Validated endpoint name.

  • version – Validated OPTIMADE version.

  • query – Validated query parameters.

  • url_version – Version segment present in the request URL.

  • request_id – Validated entry identifier.

  • revisions – Whether this is a stored revision request.

  • alternatives – Whether this is a stored alternative request.

  • request_immutable_id – Immutable revision identifier for a single revision request.

  • endpoint_path – Exact entry path used for collection-link generation.

  • recognized_response_fields – Requested fields known to the schema.

  • unrecognized_response_fields – Requested fields not known to the schema.

  • sort_fields – Validated sort fields and directions.

  • include_paths – Validated related-entry paths.

  • property_metadata_requested – Whether property metadata was requested.

  • partial_data_parts – Entry, identifier, and property for partial data.

  • partial_data_offset – Offset into a partial-data response.

  • warnings – Warnings collected while processing the request.

baseurl: str
representation: str
endpoint: str
version: str
query: ValidatedParameters
url_version: str | None = None
request_id: str | None = None
revisions: bool = False
alternatives: bool = False
request_immutable_id: str | None = None
endpoint_path: 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]] = []