httk.core.optimade.resources

Exact, immutable source documents received from an OPTIMADE service.

OptimadeDocument deliberately stores the original response text. Use OptimadeDocument.create when a document may be persisted: it removes credentials specifically from the top-level pagination links.next value without parsing and reserializing the whole response, so semantic URL values, JSON number spelling, and unrelated whitespace remain authoritative. Direct dataclass construction is also available when the caller controls the values.

Attributes

FrozenJson

Classes

OptimadeDocument	Original OPTIMADE response text and the URL from which it was obtained.
OptimadeSchemaSnapshot	Describe the /info/<entry_type> document for a resource response.
OptimadeResource	Represent one immutable resource in an OPTIMADE response envelope.

Functions

redact_optimade_url(url)	Return url without userinfo, recognized sensitive query parameters, or its fragment.
redact_optimade_document_text(text)	Sanitize only top-level pagination URLs, preserving source authority.
optimade_entry_url_info(url)	Return an OPTIMADE entry type and its derived info URL, if url has that shape.
is_optimade_entry_url(url)	Return whether url has the shape of an OPTIMADE single-entry URL.
optimade_resource_from_url(url, *[, timeout])	Fetch one OPTIMADE entry and its schema snapshot from url.
optimade_document_root(document)	Return the immutable, Decimal-preserving root of document lazily.

Module Contents

httk.core.optimade.resources.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

httk.core.optimade.resources.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

class httk.core.optimade.resources.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.resources.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.resources.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.resources.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.resources.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

type httk.core.optimade.resources.FrozenJson = None | bool | int | Decimal | str | tuple['FrozenJson', ...] | Mapping[str, 'FrozenJson']

httk.core.optimade.resources.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]

class httk.core.optimade.resources.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.