httk.serve.optimade.model

Public request, response, configuration, and result models.

Submodules

• httk.serve.optimade.model.config
• httk.serve.optimade.model.errors
• httk.serve.optimade.model.request
• httk.serve.optimade.model.results
• httk.serve.optimade.model.versions

Attributes

optimade_default_version
optimade_supported_versions

Exceptions

OptimadeError	Represent an OPTIMADE response error.
TranslatorError	Represent a filter translation failure with an HTTP response contract.

Classes

OptimadeConfig	Configure a served OPTIMADE database.
OptimadeIndexConfig	Configure an OPTIMADE index meta-database.
EndpointResponse	Represent an endpoint response for serialization by the web layer.
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.
OptimadeAdapter	Structural adapter contract consumed by the public serving helpers.
QueryFunction	The callback seam through which the request engine runs queries on a backend.
QueryResults	The results of a query against a backend, as consumed by the entry endpoints.
ResultRow	Represent one entry result and its envelope data.

Package Contents

class httk.serve.optimade.model.OptimadeConfig

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]

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

page_limit_max: int = 50

partial_data_chunk_size: int = 1000

cors_origins: tuple[str, Ellipsis] = ()

class httk.serve.optimade.model.OptimadeIndexConfig

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.

default_link_id: str | None = None

exception httk.serve.optimade.model.OptimadeError(message, response_code, response_message, longmsg=None)

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

exception httk.serve.optimade.model.TranslatorError(message, response_code, response_message, longmsg=None)

Bases: OptimadeError

Represent a filter translation failure with an HTTP response contract.

class httk.serve.optimade.model.EndpointResponse

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.model.RawRequest

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

class httk.serve.optimade.model.ValidatedParameters

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()

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.model.ValidatedRequest

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.

• 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

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]] = []

class httk.serve.optimade.model.OptimadeAdapter

Bases: Protocol

Structural adapter contract consumed by the public serving helpers.

Query execution may be backed by the ordinary Store/Searcher adapter or a storage federation with its own bounded paging policy. The HTTP layer only needs the served schema and a callback implementing QueryFunction.

property schema: httk.serve.optimade.schema.served.ServedSchema

Return the schema supplied by the adapter.

query_function()

Return the callback used to execute entry queries.

class httk.serve.optimade.model.QueryFunction

Bases: Protocol

The callback seam through which the request engine runs queries on a backend.

class httk.serve.optimade.model.QueryResults

Bases: Protocol

The results of a query against a backend, as consumed by the entry endpoints.

Iteration yields one ResultRow per entry; its values map OPTIMADE response-field names to values, and the id and type keys are always present.

property more_data_available: bool

Report whether another page is available.

count()

Return the total number of matches before pagination.

class httk.serve.optimade.model.ResultRow

Represent one entry result and its envelope data.

Parameters:

• values – Response-field values keyed by OPTIMADE property name.

• relationships – Related resources keyed by entry type.

• property_metadata – Per-property metadata keyed by response field.

values: dict[str, Any]

relationships: dict[str, list[dict[str, Any]]]

property_metadata: dict[str, Any]

httk.serve.optimade.model.optimade_default_version: Final[str] = '1.3.0'

httk.serve.optimade.model.optimade_supported_versions: Final[dict[str, str]]