httk.core.optimade

OPTIMADE resources, typed entries, and filter parsing.

Submodules

• httk.core.optimade.entries
• httk.core.optimade.filter
• httk.core.optimade.resources

Attributes

FilterAst

Exceptions

IncompleteOptimadeResourceError	A resource lacks, nulls, or malforms a local record property.
ParserError	Common base class for all non-exit exceptions.
ParserSyntaxError	Common base class for all non-exit exceptions.

Classes

CalculationView	Present an OptimadeCalculation as a lazy canonical view.
FileView	Present an OptimadeFile as a lazy canonical view.
OptimadeCalculation	Bind an OPTIMADE resource to the standard calculations schema.
OptimadeEntryBackend	Store one typed handle around an authoritative OPTIMADE resource.
OptimadeEntryView	Present one typed resource backend as a lazy generated record.
OptimadeFile	Bind an OPTIMADE resource to the standard files schema.
OptimadeReference	Bind an OPTIMADE resource to the standard references schema.
ReferenceView	Present an OptimadeReference as a lazy canonical view.
OptimadeDocument	Original OPTIMADE response text and the URL from which it was obtained.
OptimadeResource	Represent one immutable resource in an OPTIMADE response envelope.
OptimadeSchemaSnapshot	Describe the /info/<entry_type> document for a resource response.

Functions

decode_optimade_value(definition, value)	Decode one value exactly from its local property definition.
parse_optimade_filter(filter_string[, verbosity])	Parse an OPTIMADE filter into the public abstract syntax tree format.
parse_optimade_filter_raw(filter_string[, verbosity])	Parse an OPTIMADE filter and return its raw grammar parse tree.
is_optimade_entry_url(url)	Return whether url has the shape of an OPTIMADE single-entry URL.
optimade_document_root(document)	Return the immutable, Decimal-preserving root of document lazily.
optimade_entry_url_info(url)	Return an OPTIMADE entry type and its derived info URL, if url has that shape.
optimade_resource_from_url(url, *[, timeout])	Fetch one OPTIMADE entry and its schema snapshot from url.
redact_optimade_document_text(text)	Sanitize only top-level pagination URLs, preserving source authority.
redact_optimade_url(url)	Return url without userinfo, recognized sensitive query parameters, or its fragment.

Package Contents

class httk.core.optimade.CalculationView(backend)

Bases: OptimadeEntryView

Present an OptimadeCalculation as a lazy canonical view.

Parameters:

backend (OptimadeEntryBackend | OptimadeEntryView) – Calculation backend to present, or an existing compatible view.

backend_class

record_class

class httk.core.optimade.FileView(backend)

Bases: OptimadeEntryView

Present an OptimadeFile as a lazy canonical view.

Parameters:

backend (OptimadeEntryBackend | OptimadeEntryView) – File backend to present, or an existing compatible view.

backend_class

record_class

exception httk.core.optimade.IncompleteOptimadeResourceError

Bases: ValueError

A resource lacks, nulls, or malforms a local record property.

class httk.core.optimade.OptimadeCalculation

Bases: OptimadeEntryBackend

Bind an OPTIMADE resource to the standard calculations schema.

Parameters:

resource – Source resource and its schema provenance.

entry_type_name: ClassVar[str] = 'calculations'

entry_type_definition_id: ClassVar[str] = 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/calculations'

class httk.core.optimade.OptimadeEntryBackend

Store one typed handle around an authoritative OPTIMADE resource.

Parameters:

resource – Source resource and its schema provenance.

resource: httk.core.optimade.resources.OptimadeResource

kind: ClassVar[str] = 'optimade'

entry_type_name: ClassVar[str]

entry_type_definition_id: ClassVar[str]

property raw: collections.abc.Mapping[str, httk.core.optimade.resources.FrozenJson]

The immutable JSON API resource mapping, retaining source provenance.

unwrap()

Return the exact source resource, including document and schema provenance.

Returns:

The source resource represented by this backend.

Return type:

httk.core.optimade.resources.OptimadeResource

property local_schema: httk.core.property_definitions.EntryTypeDefinition

Return the standard local schema for this backend.

value_by_definition_id(definition_id, *, default=_MISSING)

Return a raw value by exact semantic IRI, retaining missing vs. null.

Values are intentionally undecoded here. This lets record views name missing/null semantic properties accurately and gives callers access to exact raw JSON before selecting a representation.

Parameters:

• definition_id (str) – Semantic property IRI to look up.

• default (object) – Value to return when the property is not present.

Returns:

The raw property value, or default when it is absent.

Raises:

ValueError – If the resource attributes or schema mapping is malformed.

Return type:

object

decode_value(definition, value)

Decode value, applying an exact-IRI binding override when present.

Parameters:

• definition (httk.core.property_definitions.PropertyDefinition) – Local property definition for the value.

• value (object) – Raw value to decode.

Returns:

Decoded value from the matching generic or binding-specific decoder.

Raises:

• TypeError – If the value does not match the selected property decoder.

• ValueError – If the property definition or value is invalid.

Return type:

object

property id: str

Return the semantic resource identifier.

property type: str

Return the semantic resource type identifier.

property immutable_id: str | None

Return the optional immutable semantic identifier.

property last_modified: datetime.datetime | None

Return the optional last-modified timestamp.

class httk.core.optimade.OptimadeEntryView(backend)

Present one typed resource backend as a lazy generated record.

Parameters:

backend (OptimadeEntryBackend | OptimadeEntryView) – Typed backend to present, or an existing compatible view.

backend_class: ClassVar[type[OptimadeEntryBackend]]

record_class: ClassVar[type[httk.core.entry_types.Reference] | type[httk.core.entry_types.File] | type[httk.core.entry_types.Calculation]]

property backend: OptimadeEntryBackend

Return the typed backend behind this view.

unwrap()

Return the exact source resource behind this view.

property id: str

Return the resource identifier.

property type: str

Return the resource type identifier.

property record: httk.core.entry_types.Reference | httk.core.entry_types.File | httk.core.entry_types.Calculation

Return the lazily materialized canonical record.

class httk.core.optimade.OptimadeFile

Bases: OptimadeEntryBackend

Bind an OPTIMADE resource to the standard files schema.

Parameters:

resource – Source resource and its schema provenance.

entry_type_name: ClassVar[str] = 'files'

entry_type_definition_id: ClassVar[str] = 'https://schemas.optimade.org/defs/v1.2/entrytypes/optimade/files'

class httk.core.optimade.OptimadeReference

Bases: OptimadeEntryBackend

Bind an OPTIMADE resource to the standard references schema.

Parameters:

resource – Source resource and its schema provenance.

entry_type_name: ClassVar[str] = 'references'

entry_type_definition_id: ClassVar[str] = 'https://schemas.optimade.org/defs/v1.2/entrytypes/optimade/references'

class httk.core.optimade.ReferenceView(backend)

Bases: OptimadeEntryView

Present an OptimadeReference as a lazy canonical view.

Parameters:

backend (OptimadeEntryBackend | OptimadeEntryView) – Reference backend to present, or an existing compatible view.

backend_class

record_class

httk.core.optimade.decode_optimade_value(definition, value)

Decode one value exactly from its local property definition.

Binding-specific decoder callables use the stable signature decoder(value, definition) and replace this generic decoder for their exact property-definition IRI. JSON floats are retained as Decimal; nested lists and dictionaries become tuples and immutable mappings.

Parameters:

• definition (httk.core.property_definitions.PropertyDefinition) – Local property definition that describes the value.

• value (object) – Raw value to decode.

Returns:

Decoded value with nested containers made immutable.

Raises:

• TypeError – If the value does not match the declared property shape.

• ValueError – If the property definition is unsupported or malformed.

Return type:

object

type httk.core.optimade.FilterAst = tuple[Any, ...]

exception httk.core.optimade.ParserError

Bases: Exception

Common base class for all non-exit exceptions.

exception httk.core.optimade.ParserSyntaxError(*args)

Bases: ParserError

Common base class for all non-exit exceptions.

info

line

pos

linestr

httk.core.optimade.parse_optimade_filter(filter_string, verbosity=0)

Parse an OPTIMADE filter into the public abstract syntax tree format.

Parameters:

• filter_string (str) – OPTIMADE filter expression to parse.

• verbosity (int | Any) – Diagnostic verbosity setting passed to the parser.

Returns:

Nested tuple abstract syntax tree in ojf format.

Raises:

ParserError – If the filter cannot be parsed.

Return type:

FilterAst

httk.core.optimade.parse_optimade_filter_raw(filter_string, verbosity=0)

Parse an OPTIMADE filter and return its raw grammar parse tree.

Parameters:

• filter_string (str) – OPTIMADE filter expression to parse.

• verbosity (int | Any) – Diagnostic verbosity setting passed to the parser.

Returns:

Raw nested tuple parse tree before ojf conversion.

Raises:

ParserError – If the filter cannot be parsed.

Return type:

tuple[Any, Ellipsis]

class httk.core.optimade.OptimadeDocument

Original OPTIMADE response text and the URL from which it was obtained.

Direct construction performs no sanitization. Use create() before storing an externally sourced document or URL.

Parameters:

• text – Original response text, optionally sanitized by create().

• source_url – URL from which the response was obtained.

text: str

source_url: str

classmethod create(text, source_url)

Construct a source-exact document with safe pagination provenance.

Parameters:

• text (str) – Response text to sanitize and retain.

• source_url (str) – Source URL to sanitize and retain.

Returns:

A source document with safe pagination provenance.

Return type:

OptimadeDocument

class httk.core.optimade.OptimadeResource

Bases: collections.abc.Mapping[str, FrozenJson]

Represent one immutable resource in an OPTIMADE response envelope.

Parameters:

• document – Source-exact response document to decode lazily.

• data_index – Index of the resource in the response data member.

• schema – Schema snapshot applicable to the response.

document: OptimadeDocument

data_index: int

schema: OptimadeSchemaSnapshot

unwrap()

Return the immutable resource object at this response’s data index.

Returns:

Immutable resource mapping selected from the response.

Raises:

• TypeError – If data_index is not an integer.

• IndexError – If data_index is outside the response data.

• ValueError – If the response data is not an object or array of objects.

Return type:

collections.abc.Mapping[str, FrozenJson]

property id: str

The protocol-mandated JSON API resource identifier.

This intentionally reads the JSON API envelope directly. It is a generic source-resource capability, not semantic recognition of a transport property name.

property type: str

The protocol-mandated JSON API resource type identifier.

class httk.core.optimade.OptimadeSchemaSnapshot

Describe the /info/<entry_type> document for a resource response.

Parameters:

• entry_type – Entry type named by the schema endpoint.

• info_document – Source-exact schema response document.

entry_type: str

info_document: OptimadeDocument

httk.core.optimade.is_optimade_entry_url(url)

Return whether url has the shape of an OPTIMADE single-entry URL.

Parameters:

url (str) – Candidate URL to inspect.

Returns:

Whether the URL identifies one OPTIMADE entry.

Return type:

bool

httk.core.optimade.optimade_document_root(document)

Return the immutable, Decimal-preserving root of document lazily.

This is intentionally a small public seam for source-model consumers that need to interpret an OPTIMADE envelope or an /info document without duplicating JSON parsing. The returned mapping is cached per equal OptimadeDocument and must be treated as immutable.

Parameters:

document (OptimadeDocument) – Source document to parse lazily.

Returns:

Cached immutable document root.

Raises:

ValueError – If the document is invalid JSON or has a non-object root.

Return type:

collections.abc.Mapping[str, FrozenJson]

httk.core.optimade.optimade_entry_url_info(url)

Return an OPTIMADE entry type and its derived info URL, if url has that shape.

Parameters:

url (str) – Candidate single-entry URL.

Returns:

Entry type and derived info URL, or None when the shape is invalid.

Return type:

tuple[str, str] | None

httk.core.optimade.optimade_resource_from_url(url, *, timeout=None)

Fetch one OPTIMADE entry and its schema snapshot from url.

Redirects follow urllib defaults. Both requests use the datastream layer and honor timeout (or its configured default when it is None).

Parameters:

• url (str) – Single-entry URL to fetch.

• timeout (float | None) – Optional timeout applied to both requests.

Returns:

Resource backed by the entry and its schema snapshot.

Raises:

ValueError – If the URL or either response is not a valid OPTIMADE resource.

Return type:

OptimadeResource

httk.core.optimade.redact_optimade_document_text(text)

Sanitize only top-level pagination URLs, preserving source authority.

A direct string links.next or its JSON:API link-object href has recognized URL credentials removed. Every other byte remains untouched: in particular URL-like object keys, resource attributes, relationships, extension values, whitespace, and number spelling are semantic source data. Malformed JSON is returned unchanged because its envelope path cannot be identified safely without guessing.

Parameters:

text (str) – JSON document text to sanitize.

Returns:

Text with only recognized pagination credentials removed.

Raises:

TypeError – If text is not a string.

Return type:

str

httk.core.optimade.redact_optimade_url(url)

Return url without userinfo, recognized sensitive query parameters, or its fragment.

Non-URL strings are returned unchanged except for fragment removal. Non-sensitive URL spelling is retained byte-for-byte; decoding is used only to recognize query keys. Fragments are not semantically load-bearing for OPTIMADE URLs or file fetches and are never retained in diagnostics.

Parameters:

url (str) – URL or diagnostic string to sanitize.

Returns:

Sanitized URL or unchanged non-URL string.

Raises:

TypeError – If url is not a string.

Return type:

str