httk.core.optimade.entries¶

Typed, exact OPTIMADE resource backends for core standard entry types.

The resource and its schema snapshot remain the sole source of truth. A typed backend recognizes values by property-definition IRI from the supplied /info/<entry> document; a remote transport name is only an address after that IRI match has been established. The record views deliberately defer all document parsing and generated-record construction until .record (or a delegated field) is requested.

Attributes¶

OptimadeValueDecoder

Exceptions¶

IncompleteOptimadeResourceError

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

Classes¶

`OptimadeEntryBackend`	Store one typed handle around an authoritative OPTIMADE resource.
`OptimadeReference`	Bind an OPTIMADE resource to the standard references schema.
`OptimadeFile`	Bind an OPTIMADE resource to the standard files schema.
`OptimadeCalculation`	Bind an OPTIMADE resource to the standard calculations schema.
`OptimadeEntryView`	Present one typed resource backend as a lazy generated record.
`ReferenceView`	Present an `OptimadeReference` as a lazy canonical view.
`FileView`	Present an `OptimadeFile` as a lazy canonical view.
`CalculationView`	Present an `OptimadeCalculation` as a lazy canonical view.

Functions¶

`decode_optimade_value`(definition, value)	Decode one value exactly from its local property definition.
`decode_optional_timestamp`(value, *, source_url)	Decode an optional RFC 3339 timestamp, treating an offset-less value as unknown.

Module Contents¶

type httk.core.optimade.entries.OptimadeValueDecoder = Callable[[object, PropertyDefinition], object][source]¶

exception httk.core.optimade.entries.IncompleteOptimadeResourceError[source]¶

Bases: ValueError

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

httk.core.optimade.entries.decode_optimade_value(definition, value)[source]¶

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

httk.core.optimade.entries.decode_optional_timestamp(value, *, source_url)[source]¶

Decode an optional RFC 3339 timestamp, treating an offset-less value as unknown.

A string with a full RFC 3339 date-time shape (a YYYY-MM-DD date, a T or space separator, and a time to at least the second with an optional fraction) but no UTC offset violates RFC 3339 and has no defined meaning, so it is reported once per service origin through the report channel and decodes to None rather than being interpreted as UTC. None decodes to None and an offset-bearing value (including a Z suffix) decodes to the aware timestamp. Every other value – a non-string, an unparseable string, or a partial form such as a bare date or an hour-minute time – raises.

Parameters:

value (object) – Raw value to decode; None decodes to None.
source_url (str) – Redacted source URL of the serving document, used to derive the service origin that scopes the once-per-origin deviation warning.

Returns:

The decoded offset-aware timestamp, or None when the value is absent or is a full offset-less RFC 3339 date-time.

Raises:

ValueError – If the value is not None and is not a parseable, full-shape RFC 3339 timestamp string.

Return type:

datetime.datetime | None

class httk.core.optimade.entries.OptimadeEntryBackend[source]¶

Store one typed handle around an authoritative OPTIMADE resource.

Parameters:: resource – Source resource and its schema provenance.

resource: httk.core.optimade.resources.OptimadeResource[source]¶

kind: ClassVar[str] = 'optimade'[source]¶

entry_type_name: ClassVar[str][source]¶

entry_type_definition_id: ClassVar[str][source]¶

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

The immutable JSON API resource mapping, retaining source provenance.

unwrap()[source]¶

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[source]¶

Return the standard local schema for this backend.

value_by_definition_id(definition_id, *, default=_MISSING)[source]¶

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)[source]¶

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[source]¶

Return the semantic resource identifier.

property type: str[source]¶

Return the semantic resource type identifier.

property immutable_id: str | None[source]¶

Return the optional immutable semantic identifier.

property last_modified: datetime.datetime | None[source]¶

Return the optional last-modified timestamp.

A value without a UTC offset violates RFC 3339 and has no defined meaning, so it is treated as unknown (decoded to None with a once-per-origin deviation warning) rather than being interpreted as UTC.

class httk.core.optimade.entries.OptimadeReference[source]¶

Bases: OptimadeEntryBackend

Bind an OPTIMADE resource to the standard references schema.