httk.core¶

Public core APIs for loading, reporting, project anchors, and registration.

Importing this package discovers installed capability modules and exposes their registered readers, writers, adapters, and related public APIs.

The deliberate public surface contains 90 names.

Attributes¶

`credits`
`BytestreamLike`
`DatastreamLike`
`TextstreamLike`
`NumericVector`
`ScalarLike`
`VectorLike`

Classes¶

`CLIContext`	Carry invocation context to a registered top-level command.
`DataRecord`	Store one canonical JSON value of one declared property.
`DataRecordEntry`	Logical entry family for served `DataRecord` records.
`DatasetLoader`	Lazy loader for httk dataset files, resolved only when data is first accessed.
`DatasetLoaderRecord`	Read-only attribute and mapping view over a `Mapping[str, Any]`.
`DatasetMeta`	Describe header metadata extracted from a structured JSON-LD document.
`Dataset`	Describe one published dataset independently of a transport or provider.
`DatasetDistribution`	Describe one retrievable representation of a dataset.
`DatasetRecord`	Store one `Dataset` using the core dataset storage contract.
`BytestreamFileView`	A view presenting an underlying data streaming backend via an io.IOBase-like API.
`BytestreamURLView`	A view presenting an underlying data streaming backend via a URL string.
`CompressionCodec`	A decompression codec for a single container format.
`DatastreamURL`	An explicit network-consent value carrying a URL and optional timeout for lazy consumers, which resolve it through the existing
`TextstreamFileView`	A view presenting an underlying data streaming backend via the full io.TextIOBase API, which is a superset of TextstreamAPI.
`TextstreamURLView`	A view presenting an underlying data streaming backend via a URL string.
`EntryProvider`	Supplies described, queryable entry types as plain JSON-able records.
`RelatedEntry`	One related entry of a record, as reported by `EntryProvider.relationships()`.
`Calculation`	The `calculations` entry type.
`File`	The `files` entry type.
`Reference`	The `references` entry type.
`FileEntry`	Logical entry family for served `FileRecord` records.
`FileRecord`	Store one OPTIMADE `files` entry with a content identity.
`EntryTypeDefinition`	An immutable OPTIMADE entry-type definition.
`PropertyDefinition`	An immutable wrapper around one full OPTIMADE property definition.
`ProductLink`	A curation `has_product`/`is_product` edge between data entries.
`Run`	One workflow execution with loose provenance edges.
`RunEdge`	Store one loose labeled reference from a run to another entry.
`RunEntry`	Logical entry family for served `Run` records.
`Service`	Describe one service independently of its publication transport.
`ServiceRecord`	Store one `Service` using the core service storage contract.
`IdentitySkip`	Field marker: exclude the field from content identity.
`Indexed`	Field marker: request a single-column index on this field's column(s).
`Related`	Field marker: relationship metadata for a reference or list-of-storable field.
`RelationshipLink`	Class-level relationship declaration: each stored row expresses one FROM→TO relationship.
`Shape`	Field marker: fixed or variable shape for a vector-valued field.
`Skip`	Field marker: the field exists on the dataclass but is not stored.
`StorageInfo`	Optional class-level storage declaration for a storable dataclass.
`Unique`	Field marker: request a unique index on this field's column(s).
`stored_property`	A derived property that a storage layer stores and makes queryable.
`FracScalar`	Represents the fractional number `nom/denom`. This is a subclass of FracVector with the
`FracVector`	Immutable exact-rational vector that is also its own vector backend.
`MutableFracVector`	Same as `FracVector`, only this version allows
`SurdScalar`	A scalar `SurdVector` (shape `()`): a single field element
`SurdVector`	An immutable exact tensor over the squarefree-radical field
`Backend`	Abstract base class to be subclassed into classes that keep track of alternative
`View`	A set of views allow manipulating data and state of a backend through different interfaces.

Functions¶

`register_citation`(*, applies_to, references)	Register one or more references under a human-readable explanation.
`known_compressions`()	Return the registered codec names, in registration order.
`register_compression`(codec)	Register (or replace) a codec under its `name` (case-insensitive).
`fetch`(url, *[, raw, timeout, kind])	Fetch a URL as an OPTIMADE entry or a registered file format.
`has_reader_for`(name)	Return whether `name` matches a registered reader key.
`load`(filename, *[, raw])	Load `filename` and adapt its neutral payload to a domain object.
`load_many`(sources, *[, processes, errors])	Load multiple sources lazily, preserving input order.
`load_source`(source, name, *[, raw])	Load `source` using the reader selected by `name`.
`combined_precision`(values)	Return the precision of a set of values taken together: the coarsest of them.
`decimal_precision`(text)	Return the absolute precision implied by how a number was written, or `None`.
`known_definition_prefixes`()	Return the registered database-specific property-name prefixes.
`register_definition_prefix`(prefix, id_base)	Register a database-specific OPTIMADE property-name `prefix`.
`standard_entry_type`(name)	Return one of httk-core's vendored standard OPTIMADE entry types.
`register_cli_command`(name, handler, summary)	Register a lazy top-level httk command.
`known_entry_providers`()	Return registered entry-provider names.
`register_entry_family`(*, name, family[, definition_id])	Register a lazy entry-family class reference without importing it.
`register_entry_provider`(*, name, factory)	Register an `EntryProvider` factory under `name`.
`register_entry_record`(*, name, record[, family, ...])	Register a lazy record-class reference and optional family and definition IRI.
`register_optimade_entry_binding`(*, name, ...[, ...])	Register one lazy typed binding, selected only by exact definition IRI.
`register_format_adapter`(*, name, adapter, formats)	Register one lazy adapter for each neutral payload format in `formats`.
`register_format_serializer`(*, format, serializer)	Register one lazy serializer for a neutral payload format tag.
`register_reader`(*, name, reader[, extensions, filenames])	Register a reader under one or more file `extensions` and/or `filenames`.
`register_writer`(*, name, writer, format[, extensions, ...])	Register a writer under one or more extensions and/or exact basenames.
`load_entry_type_definition`(definition_id)	Load and verify a registered entry-type definition resource.
`load_property_definition`(definition_id)	Load and verify a registered property definition resource.
`register_entry_type_definition`(*, definition_id, resource)	Register one resource for an entry-type definition IRI.
`register_property_definition`(*, definition_id, resource)	Register one resource for a property definition IRI.
`has_writer_for`(name)	Return whether `name` matches a registered writer key.
`save`(obj, destination, *[, format])	Save `obj` to a local destination selected by its name or `format` hint.
`content_id`(obj, *[, as_record, projector])	Return the lowercase SHA-256 content identity of `obj`.
`numpy_available`()	Return whether the optional numpy dependency is available for the numeric helpers.
`to_numeric`(obj)	Present `obj` as plain numpy numbers: a `numpy.ndarray` for a tensor, a `float` for a
`to_numeric_scalar`(obj)	Convert a single scalar value to a plain `float`, deterministically.
`coerce`(value, target)	Coerce `value` strictly: return a non-View instance of the requested target or raise.
`coerce_view`(value, target)	Coerce `value` to a target class or prototype instance, backend-aware and best-effort.
`unview`(obj)	Shed the httk View wrapper from `obj`, returning a plain instance of the presented type.
`unwrap`(obj)	Given a Backend or a View, return the most raw representation possible, i.e., if the backend has an internal representaion -

Package Contents¶

httk.core.credits[source]¶

httk.core.register_citation(*, applies_to, references)[source]¶

References are normalized on registration and duplicate references under the same explanation are retained only once. The registration is visible through credits, allowing imported modules to contribute their citation requirements as they are loaded.

Parameters:

applies_to (str) – Human-readable explanation of when the references apply.
references (httk.core.entry_types.Reference | collections.abc.Mapping[str, Any] | collections.abc.Sequence[httk.core.entry_types.Reference | collections.abc.Mapping[str, Any]]) – One reference, mapping, or sequence of references to register.

Raises:

TypeError – If references is not a reference, mapping, or sequence of references.
ValueError – If applies_to is invalid or references is empty.

class httk.core.CLIContext[source]¶

Carry invocation context to a registered top-level command.

Parameters:

program – Program name used in command output and help.
cwd – Working directory selected for the command invocation.

program: str¶

cwd: pathlib.Path¶

class httk.core.DataRecord[source]¶

Store one canonical JSON value of one declared property.

value_json is canonical JSON, with sorted object keys, compact separators, and no non-finite numeric values. value decodes it on access; value_number exposes finite numeric values for numeric queries. The immutable and timestamp metadata fields are excluded from content identity.

Parameters:

definition_id – The property definition IRI for the value.
name – The property name.
value_json – The canonical JSON representation of the value.
immutable_id – An optional provider-specific immutable identifier.
last_modified – The optional timezone-aware metadata timestamp.

definition_id: str¶

name: str¶

value_json: str¶

immutable_id: Annotated[str | None, IdentitySkip()] = None¶

last_modified: Annotated[datetime.datetime | None, IdentitySkip()] = None¶

property type: str¶

Return the served entry type name.

property id: str¶

Return the content identity of this record.

property value: Any¶

Decode and return the stored property value.

property value_number: float | None¶

The decoded numeric value, stored as a numeric SQL query column.

classmethod from_value(definition_id, name, value, *, immutable_id=None, last_modified=None)[source]¶

Encode a value canonically and construct its data record.

Parameters:

definition_id (str) – The property definition IRI for the value.
name (str) – The property name.
value (Any) – The JSON value to encode.
immutable_id (str | None) – An optional provider-specific immutable identifier.
last_modified (datetime.datetime | None) – The optional timezone-aware metadata timestamp.

Returns:

A data record containing the canonical JSON value.

Raises:

TypeError – If the value contains an unsupported object.
ValueError – If the value is circular or contains a non-finite number, or if definition_id or name is invalid or last_modified is not timezone-aware.

Return type:

Self

classmethod create(obj)[source]¶

Coerce a mapping or existing record into a DataRecord.

Parameters:

obj (DataRecord | Mapping[str, Any]) – A data record instance or field mapping.

Returns:

The existing or newly constructed data record.

Raises:

TypeError – If obj is neither a data record nor a mapping.
ValueError – If the mapping has unknown or invalid fields.

Return type:

Self

class httk.core.DataRecordEntry[source]¶

Logical entry family for served DataRecord records.

This family is not itself storable; store a DataRecord directly.

type = '_httk_records'¶

definition_id = 'https://schemas.httk.org/defs/v0.1/entrytypes/records'¶

class httk.core.DatasetLoader(identifier, source, decode_object=None, **hints)[source]¶

Lazy loader for httk dataset files, resolved only when data is first accessed.

A DatasetLoader is a declare-time placeholder: constructing it records its arguments and performs no I/O. The source is read the first time data, meta, or index is accessed. Files are either plain JSON (any JSON value is exposed as data with meta/index set to None) or a structured JSON-LD document (with @context, header fields, data, and optional indicies) whose header is exposed via meta, datasets via data.<name>, and lookup indices via index.<name>.

Loaders that share an identifier deduplicate through a class-level registry: the first load wins, and later loaders reusing that identifier return the same result while their source and decode_object arguments are ignored. Keeping identifiers unique is the caller’s responsibility. Not thread-safe.

Format is resolved from the source name after stripping any compression suffix: a .json name (e.g. data.json or data.json.gz) is parsed as JSON; any other recognizable suffix raises ValueError; a source with no determinable name is treated as JSON. Compression is handled transparently by the stream layer, so .json.gz and similar load directly. A plain .sqlar file is an alternative structured JSON-LD representation. It contains header.json, optional indicies.json, scalar data/{D}.json members, and list members at data/{D}/{i:05d}.json or data/{D}/{i:05d}/{field}.json. Sqlar sources require a real filename because their immutable SQLite connection is retained for the lifetime of the cached load; they cannot be compressed, streamed, or loaded from content. Empty list datasets and empty dictionary records cannot be represented and are rejected by the writer; individual members are limited to 256 MiB. Sqlar-backed record/sequence/data views (and DatasetLoaderRecord) pickle by materializing to plain containers; live iterators over them are not picklable. A str/Path source is interpreted as a filename unless its scheme marks it as a URL (http, https, ftp, file); bare network URLs are refused at read time, so pass kind="url" or a urllib.request.Request. Pass kind="content" for literal content or kind="filename" to force a filename interpretation.

Example

symmetry_basics = DatasetLoader(“symmetry_basics”, “data/spacegroup_symbols.json”) spacegroups = symmetry_basics.data.spacegroups # first access triggers the load

Parameters:

identifier (str) – The deduplication key for this load.
source (httk.core.datastream.TextstreamLike) – The filename, URL-like stream, request, or literal content to read.
decode_object (DecodeObjectCallback | None) – An optional callback for JSON-LD objects identified by context URLs.
**hints (Any) – Stream interpretation hints such as kind.

property data: Any¶

Return the lazily loaded dataset value.

property meta: DatasetMeta | None¶

Return structured-document metadata, or None for plain JSON.

property index: DatasetLoaderRecord | None¶

Return structured-document lookup indices, or None when absent.

class httk.core.DatasetLoaderRecord(data)[source]¶

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

Read-only attribute and mapping view over a Mapping[str, Any].

Top-level keys are reachable both as attributes (record.name) and as items (record["name"]); the wrapped values are the plain parsed JSON and are not themselves wrapped. Supports iteration over keys, len(), in, and keys().

Parameters:: data (collections.abc.Mapping[str, Any]) – The parsed top-level object exposed by this view.

keys()[source]¶

Return a dynamic view of the record’s top-level keys.

Returns:: The wrapped mapping’s keys view.
Return type:: collections.abc.KeysView[str]

class httk.core.DatasetMeta[source]¶

Describe header metadata extracted from a structured JSON-LD document.

Parameters:

context – The raw document context.
id – The document identifier, if present.
type – The document type, if present.
header – Remaining top-level header fields.
dataset_ids – Dataset names mapped to their identifiers.
fields – Dataset names mapped to their field property URLs.

context: dict[str, Any]¶: The raw @context object.

id: str | None¶: The document @id, or None if absent.

type_: str | None¶: The document @type, or None if absent (trailing underscore avoids the builtin type).

header: dict[str, Any]¶: All remaining top-level keys except data, indicies, and @-keys (titles, creator, license, provenance, …).

dataset_ids: dict[str, str]¶: Mapping of dataset name to its @id.

fields: dict[str, dict[str, str]]¶: Mapping of dataset name to a mapping of field name to its property URL.

class httk.core.Dataset[source]¶

Describe one published dataset independently of a transport or provider.

id and publisher_id are absolute IRIs. The remaining fields are human-readable metadata and retain their supplied text exactly.

Parameters:

id – The dataset’s absolute IRI.
title – The dataset’s human-readable title.
description – A non-empty description of the dataset.
publisher_id – The publisher’s absolute IRI.
publisher_name – The publisher’s human-readable name.
distributions – The dataset’s retrievable representations.

id: str¶

title: str¶

description: str¶

publisher_id: str¶

publisher_name: str¶

distributions: tuple[DatasetDistribution, Ellipsis] = ()¶

classmethod create(obj)[source]¶

Coerce a mapping or existing dataset into a Dataset.

Parameters:

obj (Dataset | Mapping[str, Any]) – A dataset instance or a mapping with exactly the dataset fields.

Returns:

The existing or newly constructed dataset.

Raises:

TypeError – If obj is neither a dataset nor a mapping.
ValueError – If the mapping has missing, unknown, or invalid fields.

Return type:

Self

class httk.core.DatasetDistribution[source]¶

Describe one retrievable representation of a dataset.

Identifier and vocabulary fields must be well-formed absolute IRIs. access_url may instead be a root-relative URL for later resolution by a serving application. byte_size is a non-negative integer, and sha256 is a lowercase hexadecimal digest.

Parameters:

id – An optional identifier for this representation.
access_url – An optional URL from which the representation can be retrieved.
media_type_iri – An optional IRI identifying the media type.
format_iri – An optional IRI identifying the representation format.
byte_size – The optional representation size in bytes.
sha256 – The optional lowercase SHA-256 digest.

id: str | None = None¶

access_url: str | None = None¶

media_type_iri: str | None = None¶

format_iri: str | None = None¶

byte_size: int | None = None¶

sha256: str | None = None¶

classmethod create(obj)[source]¶

Coerce a distribution instance or exact-field mapping.

Parameters:

obj (DatasetDistribution | Mapping[str, Any]) – A distribution instance or a mapping of distribution fields.

Returns:

The existing or newly constructed distribution.

Raises:

TypeError – If obj is neither a distribution nor a mapping.
ValueError – If the mapping has unknown or invalid fields.

Return type:

Self

class httk.core.DatasetRecord[source]¶

Bases: Dataset

Store one Dataset using the core dataset storage contract.

Parameters:

id – The dataset’s absolute IRI.
title – The dataset’s human-readable title.
description – A non-empty description of the dataset.
publisher_id – The publisher’s absolute IRI.
publisher_name – The publisher’s human-readable name.
distributions – The dataset’s retrievable representations.

classmethod create(obj)[source]¶

Coerce a dataset record, neutral dataset, or field mapping.

Parameters:

obj (DatasetRecord | Dataset | Mapping[str, Any]) – A dataset record, neutral dataset, or exact-field mapping.

Returns:

The existing or newly constructed dataset record.

Raises:

TypeError – If obj is not a dataset or mapping.
ValueError – If the mapping has unknown, missing, or invalid fields.

Return type:

Self

class httk.core.BytestreamFileView(obj, **hints)[source]¶

Bases: httk.core.datastream.bytestream_view.BytestreamView, io.IOBase, httk.core.datastream.bytestream_api.BytestreamAPI

A view presenting an underlying data streaming backend via an io.IOBase-like API.

Parameters:

obj (httk.core.datastream.bytestream_like.BytestreamLike) – Byte-stream source to present through the file API.
**hints (Any) – Backend-selection and compression hints.

unwrap()[source]¶

Return the raw representation of the wrapped backend.

Returns:: The backend’s most raw available representation.
Return type:: Any

property name: str | None¶

Return the backend’s source name when one exists.

property closed: bool¶

Report whether the backend is closed.

close()[source]¶

Close the underlying backend.

readable()[source]¶

Report that the view supports reading.

Returns:: Always True.
Return type:: bool

writable()[source]¶

Report that the view does not support writing.

Returns:: Always False.
Return type:: bool

seekable()[source]¶

Report whether the backend supports seeking and telling.

Returns:: Whether both operations are available.
Return type:: bool

flush()[source]¶

Flush the backend when it provides flushing.

Raises:: ValueError – If the view is closed.

read(size=-1)[source]¶

Read up to size bytes, or all remaining bytes when size is negative.

Parameters:: size (int | None) – Maximum number of bytes to read; None also means all remaining bytes.
Returns:: The bytes read from the stream.
Raises:: ValueError – If the view is closed.
Return type:: bytes

readline(size=-1)[source]¶

Read one line, optionally limited to size bytes.

Parameters:: size (int | None) – Maximum number of bytes to read; None means no limit.
Returns:: The line read, including its newline when present.
Raises:: ValueError – If the view is closed.
Return type:: bytes

readlines(hint=-1)[source]¶

Read lines until EOF or until the accumulated size reaches hint.

Parameters:: hint (int) – Approximate minimum number of bytes to collect, or a negative value for no limit.
Returns:: The lines read from the stream.
Raises:: ValueError – If the view is closed.
Return type:: list[bytes]

seek(offset, whence=io.SEEK_SET)[source]¶

Move the stream position and discard buffered line data.

Parameters:

offset (int) – Position adjustment interpreted according to whence.
whence (int) – Reference point for offset.

Returns:

The resulting absolute stream position.

Raises:

ValueError – If the view is closed.
io.UnsupportedOperation – If the backend is not seekable.

Return type:

int

tell()[source]¶

Return the logical stream position before buffered line data.

Returns:

The logical absolute stream position.

Raises:

ValueError – If the view is closed.
io.UnsupportedOperation – If the backend does not support telling.

Return type:

int

detach()[source]¶

Reject detaching because the view owns its backend interface.

Raises:: io.UnsupportedOperation – Always, because detaching is unsupported.

type httk.core.BytestreamLike = bytestream_backend.BytestreamBackend | bytestream_view.BytestreamView | io.IOBase | io.BytesIO | bytes | bytearray | str | pathlib.Path | urllib.request.Request[source]¶

class httk.core.BytestreamURLView(obj, **hints)[source]¶

Bases: httk.core.datastream.bytestream_view.BytestreamView, str

A view presenting an underlying data streaming backend via a URL string. This view is mostly useful for providing a URL to functions that will open it. Note: this view is not lazy (this is impossible for views inheriting str, since str is immutable).

Raises TypeError if created with a streaming data source that does not come with a URL.

Parameters:

obj (httk.core.datastream.bytestream_like.BytestreamLike) – Byte-stream source whose URL should be presented.
**hints (Any) – Backend-selection, consent, timeout, and compression hints.

Raises:

TypeError – If the source has no URL.

unwrap()[source]¶

Return the raw representation of the wrapped backend.

Returns:: The backend’s most raw available representation.
Return type:: Any

class httk.core.CompressionCodec[source]¶

A decompression codec for a single container format.

A codec is an orthogonal layer below the datastream backends: it turns a compressed binary stream into an uncompressed binary stream, independently of where the compressed bytes come from (a filename, an open file, raw bytes, or a remote response).

Parameters:

name – Canonical name used to select the codec explicitly.
extensions – Filename suffixes that identify the codec.
magics – Leading byte signatures used to detect the codec.
open_stream – Function that wraps compressed bytes for reading.

name: str¶: Canonical, lower-case codec name (e.g. "gzip"); also how an explicit hint selects it.

extensions: tuple[str, Ellipsis]¶: Recognized filename suffixes including the leading dot (e.g. (".gz",)).

magics: tuple[bytes, Ellipsis]¶: Leading magic-byte signatures; an empty tuple means the format cannot be sniffed.

open_stream: collections.abc.Callable[[io.IOBase], io.IOBase]¶: Wrap a compressed binary stream and return a readable, decompressed binary stream.

type httk.core.DatastreamLike = BytestreamLike | TextstreamLike | DatastreamURL[source]¶

class httk.core.DatastreamURL(url, *, timeout=None)[source]¶

An explicit network-consent value carrying a URL and optional timeout for lazy consumers, which resolve it through the existing fetch/loader machinery; constructing it performs no network I/O.

Parameters:

url (str) – URL whose explicit use permits network-backed lazy access.
timeout (float | None) – Optional timeout to apply when the URL is opened.

Raises:

ValueError – If the URL uses an unsupported scheme.

property url: str¶

Return the explicit URL.

property timeout: float | None¶

Return the timeout to use when opening the URL.

class httk.core.TextstreamFileView(obj, **hints)[source]¶

Bases: httk.core.datastream.textstream_view.TextstreamView, io.TextIOBase, httk.core.datastream.textstream_api.TextstreamAPI

A view presenting an underlying data streaming backend via the full io.TextIOBase API, which is a superset of TextstreamAPI.

Parameters:

obj (httk.core.datastream.textstream_like.TextstreamLike) – Text-stream source to present through the text file API.
**hints (Any) – Backend-selection, encoding, and compression hints.

unwrap()[source]¶

Return the raw representation of the wrapped backend.

Returns:: The backend’s most raw available representation.
Return type:: Any

property name: str | None¶

Return the backend’s source name when one exists.

property closed: bool¶

Report whether the backend is closed.

close()[source]¶

Close the underlying backend.

readable()[source]¶

Report that the view supports reading.

Returns:: Always True.
Return type:: bool

writable()[source]¶

Report that the view does not support writing.

Returns:: Always False.
Return type:: bool

seekable()[source]¶

Report whether the backend supports seeking and telling.

Returns:: Whether both operations are available.
Return type:: bool

flush()[source]¶

Flush the backend when it provides flushing.

Raises:: ValueError – If the view is closed.

read(size=-1)[source]¶

Read up to size characters, or all remaining characters when size is negative.

Parameters:: size (int | None) – Maximum number of characters to read; None also means all remaining characters.
Returns:: The text read from the stream.
Raises:: ValueError – If the view is closed.
Return type:: str

readline(size=-1)[source]¶

Read one line, optionally limited to size characters.

Parameters:: size (int | None) – Maximum number of characters to read; None means no limit.
Returns:: The line read, including its newline when present.
Raises:: ValueError – If the view is closed.
Return type:: str

readlines(hint=-1)[source]¶

Read lines until EOF or until the accumulated size reaches hint.

Parameters:: hint (int) – Approximate minimum number of characters to collect, or a negative value for no limit.
Returns:: The lines read from the stream.
Raises:: ValueError – If the view is closed.
Return type:: list[str]

seek(offset, whence=io.SEEK_SET)[source]¶

Move the stream position and discard buffered line data.

Parameters:

offset (int) – Position adjustment interpreted according to whence.
whence (int) – Reference point for offset.

Returns:

The resulting absolute stream position.

Raises:

ValueError – If the view is closed.
io.UnsupportedOperation – If the backend is not seekable.

Return type:

int

tell()[source]¶

Return the logical stream position before buffered line data.

Returns:

The logical absolute stream position.

Raises:

ValueError – If the view is closed.
io.UnsupportedOperation – If the backend does not support telling.

Return type:

int

detach()[source]¶

Reject detaching because the view owns its backend interface.

Raises:: io.UnsupportedOperation – Always, because detaching is unsupported.

property encoding: str | None¶

Return the backend’s text encoding when available.

property errors: str | None¶

Return the backend’s error handling mode when available.

property newlines: str | tuple[str, Ellipsis] | None¶

Return the newline conventions observed by the backend when available.

type httk.core.TextstreamLike = textstream_backend.TextstreamBackend | textstream_view.TextstreamView | io.TextIOBase | io.StringIO | str | pathlib.Path | urllib.request.Request[source]¶

class httk.core.TextstreamURLView(obj, **hints)[source]¶

Bases: httk.core.datastream.textstream_view.TextstreamView, str

Raises TypeError if created with a streaming data source that does not come with a URL.

Parameters:

obj (httk.core.datastream.textstream_like.TextstreamLike) – Text-stream source whose URL should be presented.
**hints (Any) – Backend-selection, consent, encoding, timeout, and compression hints.

Raises:

TypeError – If the source has no URL.

unwrap()[source]¶

Return the raw representation of the wrapped backend.

Returns:: The backend’s most raw available representation.
Return type:: Any

httk.core.known_compressions()[source]¶

Return the registered codec names, in registration order.

Returns:: The registered codec names.
Return type:: list[str]

httk.core.register_compression(codec)[source]¶

Parameters:: codec (CompressionCodec) – Codec to add to the registry.

class httk.core.EntryProvider[source]¶

Bases: abc.ABC

Supplies described, queryable entry types as plain JSON-able records.

A provider serves one or more entry types, each identified by a name (e.g. "structures"). For every entry type it describes the entry type and its properties, states how each served property maps to a record key, and yields the records themselves.

Three notions define the contract:

Definitions (entry_types()) are first-class EntryTypeDefinition objects — the OPTIMADE property-definition model shared across httk₂ modules. A provider obtains them from the vendored standards (via standard_entry_type() or load_entry_type_definition()) or builds them from from_optimade() and from_simple(). A standard definition typically describes more properties than a provider serves; the served subset is exactly the property names in property_keys().
Property keys (property_keys()) map each served property name to the key under which that property’s value is found in a record. Every entry type’s property-key map MUST cover at least id and type, and every served name MUST be described by the entry type’s definition (custom properties must therefore live in an extended() definition).
Records (records()) are plain JSON-able mappings keyed by the record keys named in property_keys() (values are strings, numbers, booleans, None, or nested lists/dicts of the same).

A consumer combines the three: the definitions become the served schema, the property keys drive both response-field extraction and filter handling, and the records are loaded into a store the consumer queries.

A provider may additionally declare relationships (relationships()): a flat tuple of RelatedEntry values per entry id, each naming a related entry (and optionally the relationship’s description/role metadata) that the consumer serves as the entry’s relationships block.

abstractmethod entry_types()[source]¶

Return the served entry types keyed by name.

Each value is an EntryTypeDefinition describing the entry type and its properties. The subset a provider actually serves is named by property_keys(); a definition may describe more properties than are served.

Returns:: The served entry-type definitions keyed by entry type name.
Return type:: collections.abc.Mapping[str, httk.core.property_definitions.EntryTypeDefinition]

abstractmethod property_keys(entry_type)[source]¶

Return the served-property-name to record-key map for entry_type.

The mapping MUST include entries for at least id and type. Every key names a property described by entry_types(); every value names the key under which that property’s value is found in a record from records().

Parameters:: entry_type (str) – The entry type whose property mapping is requested.
Returns:: The served property names mapped to record keys.
Return type:: collections.abc.Mapping[str, str]

abstractmethod records(entry_type)[source]¶

Yield the records for entry_type as plain JSON-able mappings.

Each record is a mapping keyed by the record keys named in property_keys(); values are JSON-able (strings, numbers, booleans, None, or nested lists/dicts of the same).

Parameters:: entry_type (str) – The entry type whose records are requested.
Returns:: An iterable of JSON-able records.
Return type:: collections.abc.Iterable[collections.abc.Mapping[str, Any]]

relationships(entry_type)[source]¶

Return the related entries for each record of entry_type.

The result maps an entry id to a flat tuple of RelatedEntry values, e.g. {"struct-1": (RelatedEntry("references", "ref-1"), RelatedEntry("references", "ref-2", description="Cites the method"))}. Grouping the related entries by related entry type is the serving layer’s concern (JSON:API groups them at render time). This is the neutral source of an OPTIMADE relationships block: a consumer turns each related entry into a resource identifier under its entry type (carrying the description/role metadata when present), and an include=<type> request then embeds those related resources. The default implementation returns an empty mapping (no relationships); a provider overrides it to declare them. Ids referring to records this provider (or a sibling provider serving the related type) does not supply are simply not resolvable by the consumer.

Parameters:: entry_type (str) – The entry type whose relationships are requested.
Returns:: Related entries keyed by the source record identifier.
Return type:: collections.abc.Mapping[str, tuple[RelatedEntry, Ellipsis]]

class httk.core.RelatedEntry[source]¶

One related entry of a record, as reported by EntryProvider.relationships().

Mirrors the OPTIMADE v1.3 relationships model: a related entry is named by its entry type and id, optionally carrying the per-identifier metadata the standard defines — description (the human-readable relationship description introduced in OPTIMADE v1.2 as meta.description) and role (the machine-readable relationship role introduced in OPTIMADE v1.3 as meta.role, e.g. "input"/"output" for the calculations↔files relationship). An absent role means exactly that — no role is declared and no default is assumed. label is the provenance edge label (the OPTIMADE relation-object label); until relation-object serving exists, it is served on the OPTIMADE side as prefixed relationship metadata.

Parameters:

entry_type – The entry type of the related entry.
id – The identifier of the related entry.
description – The human-readable relationship description, if declared.
role – The machine-readable relationship role, if declared.
label – The provenance edge label, if declared.

entry_type: str¶: The entry type of the related entry (e.g. "references").

id: str¶: The id of the related entry.

description: str | None = None¶: A human-readable description of the relationship, if declared.

role: str | None = None¶: The machine-readable role of the relationship, if declared.

label: str | None = None¶: The provenance edge label, if declared.

class httk.core.Calculation[source]¶

The calculations entry type.

The calculations entry type describes calculations. Related files entries specified as relationships list files used or produced by a calculation. They MAY be defined as either input or output files by the role field inside the meta dictionary of the JSON:API resource identifier object. The allowed values are input for input files and output for output files. If the role field is not provided or the value is set to null, a default role SHOULD NOT be assumed. It is RECOMMENDED to order the output files in the list of calculation’s relationships in a way that prioritizes the files most likely to contain details which could be used to automatically analyze the performed calculation. Such an approach minimizes the number of calculation output files that need to be analyzed to possibly identify the code, type and parameters of the performed calculation.

Schema properties:

Variables:

immutable_id –
The entry’s immutable ID (e.g., a UUID).

Requirements/Conventions:
- This is important for databases having preferred IDs that point to “the latest version” of a record, but still offer access to older variants.
- This ID maps to the version-specific record, in case it changes in the future.
last_modified – Date and time representing when the entry was last modified.

immutable_id: str | None = None¶

last_modified: datetime.datetime | None = None¶

classmethod create(obj)[source]¶

class httk.core.File[source]¶

The files entry type.

The files entry type describes a file with metadata and a URL to retrieve it

Schema properties:

Variables:

immutable_id –
The entry’s immutable ID (e.g., a UUID).

Requirements/Conventions:
- This is important for databases having preferred IDs that point to “the latest version” of a record, but still offer access to older variants.
- This ID maps to the version-specific record, in case it changes in the future.
last_modified – Date and time representing when the entry was last modified.
url –
The URL to get the contents of a file.

Requirements/Conventions:
- The URL MUST point to the actual contents of a file (i.e. byte stream), not an intermediate (preview) representation. For example, if referring to a file on GitHub, a link should point to raw contents.
url_stable_until –
Point in time until which the URL in url is guaranteed to stay stable.

Requirements/Conventions:
- null means that there is no stability guarantee for the URL in url. Indefinite support could be communicated by providing a date sufficiently far in the future, for example, 9999-12-31.
name –
Base name of a file.

Requirements/Conventions:
- File name extension is an integral part of a file name and, if available, MUST be included.
size –
Size of a file in bytes.

Requirements/Conventions:
- If provided, it MUST be guaranteed that either exact size of a file is given or its upper bound. This way if a client reserves a static buffer or truncates the download stream after this many bytes the whole file would be received. Such provision is included to allow the providers to serve on-the-fly compressed files.
media_type – Media type identifier (also known as MIME type), for a file as per [RFC 6838 Media Type Specifications and Registration Procedures](https://datatracker.ietf.org/doc/html/rfc6838).
version –
Version information of a file (e.g., commit, revision, timestamp).

Requirements/Conventions:
- If provided, it MUST be guaranteed that file contents pertaining to the same combination of id and version are the same.
modification_timestamp –
Timestamp of the last modification of file contents. A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous.

Requirements/Conventions:
- Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps).
description – Free-form description of a file.
checksums –
Dictionary providing checksums of file contents.

Requirements/Conventions:
- The keys in the dictionary identify checksum functions and the values are strings containing the corresponding checksum.
- Supported dictionary keys: md5, sha1, sha224, sha256, sha384, sha512. Checksums outside this list MAY be used, but their names MUST be prefixed by database-provider-specific namespace prefix.
atime – Time of last access of a file as per POSIX standard.
ctime – Time of last status change of a file as per POSIX standard.
mtime –
Time of last modification of a file as per POSIX standard.

Requirements/Conventions:
- It should be noted that the values of last_modified, modification_timestamp and mtime do not necessary match. last_modified pertains to the modification of the OPTIMADE metadata, modification_timestamp pertains to file contents and mtime pertains to the modification of the file (not necessary changing its contents). For example, appending an empty string to a file would result in the change of mtime in some operating systems, but this would not be deemed as a modification of its contents.

url: str¶

name: str¶

immutable_id: str | None = None¶

last_modified: datetime.datetime | None = None¶

url_stable_until: datetime.datetime | None = None¶

size: int | None = None¶

media_type: str | None = None¶

version: str | None = None¶

modification_timestamp: datetime.datetime | None = None¶

description: str | None = None¶

checksums: collections.abc.Mapping[str, str] | None = None¶

atime: datetime.datetime | None = None¶

ctime: datetime.datetime | None = None¶

mtime: datetime.datetime | None = None¶

classmethod create(obj)[source]¶

class httk.core.Reference[source]¶

The references entry type.

The references entry type describes a reference

Schema properties:

Variables:

immutable_id –
The entry’s immutable ID (e.g., a UUID).

Requirements/Conventions:
- This is important for databases having preferred IDs that point to “the latest version” of a record, but still offer access to older variants.
- This ID maps to the version-specific record, in case it changes in the future.
last_modified – Date and time representing when the entry was last modified.
address – Typically the location of the publisher or institution (the address field in the BibTeX specification).
annote – Additional notes or comments on the reference (the annote field in the BibTeX specification).
booktitle – The title of a book being cited; for parts of a book, use the title field instead (the booktitle field in the BibTeX specification).
chapter – The chapter, section, or similar part number (the chapter field in the BibTeX specification).
crossref – The database key of the entry being cross referenced (the crossref field in the BibTeX specification).
edition – The edition of a book (the edition field in the BibTeX specification).
howpublished – The method of publication (the howpublished field in the BibTeX specification)
institution – The sponsoring institution of a technical report (the institution field in the BibTeX specification).
journal – The name of a journal (the journal field in the BibTeX specification).
key – Used for alphabetizing, cross-referencing, and creating a label (the key field in the BibTeX specification).
month – The three-letter abbreviation of the month of publication or writing (the month field in the BibTeX specification).
note – Additional information about the reference (the note field in the BibTeX specification).
number – The number of a journal, magazine, technical report, or work in a series (the number field in the BibTeX specification).
organization – The organization sponsoring a conference or publishing a manual (the organization field in the BibTeX specification)
pages – The page number(s) of the reference (the pages field in the BibTeX specification).
publisher – The name of the publisher (the publisher field in the BibTeX specification).
school – The name of the school where a thesis was written (the school field in the BibTeX specification).
series – The name of a series or set of books (the series field in the BibTeX specification).
title – The title of the work (the title field in the BibTeX specification).
volume – The volume number of a journal or multivolume book (the volume field in the BibTeX specification).
year – The year of publication or writing.
bib_type – Type of the reference (the type field in the BibTeX specification).
authors –
A list of dictionaries with names of the authors.

Requirements/Conventions:
- Each list member MUST be a dictionary with the following keys:
  - name: Full name of the person, REQUIRED.
  - firstname, lastname: Parts of the person’s name, OPTIONAL.
editors –
A list of dictionaries with names of the editors.

Requirements/Conventions:
- Each list member MUST be a dictionary with the following keys:
  - name: Full name of the person, REQUIRED.
  - firstname, lastname: Parts of the person’s name, OPTIONAL.
doi – The doi identifier of the object being referenced.
url – The URL of the object being referenced.

immutable_id: str | None = None¶

last_modified: datetime.datetime | None = None¶

address: str | None = None¶

annote: str | None = None¶

booktitle: str | None = None¶

chapter: str | None = None¶

crossref: str | None = None¶

edition: str | None = None¶

howpublished: str | None = None¶

institution: str | None = None¶

journal: str | None = None¶

key: str | None = None¶

month: str | None = None¶

note: str | None = None¶

number: str | None = None¶

organization: str | None = None¶

pages: str | None = None¶

publisher: str | None = None¶

school: str | None = None¶

series: str | None = None¶

title: str | None = None¶

volume: str | None = None¶

year: str | None = None¶

bib_type: str | None = None¶

authors: tuple[collections.abc.Mapping[str, Any], Ellipsis] | None = None¶

editors: tuple[collections.abc.Mapping[str, Any], Ellipsis] | None = None¶

doi: str | None = None¶

url: str | None = None¶

classmethod create(obj)[source]¶

httk.core.fetch(url, *, raw=False, timeout=None, kind=None, **kwargs)[source]¶

Fetch a URL as an OPTIMADE entry or a registered file format.

kind="optimade" forces OPTIMADE handling and kind="load" forces file-reader handling. With no kind, a reader-claimed extension wins over an OPTIMADE-shaped path; a reader-claimed basename is ambiguous and requires an explicit kind. file:// URLs are supported in either branch. Redirects follow urllib defaults.

As the explicit URL entry point, this function supplies the same network consent represented by DatastreamURL; it does not use implicit bare-string network access for the reader branch.

Parameters:

url (str) – URL to fetch.
raw (bool) – Whether to return a neutral payload without a format adapter.
timeout (float | None) – Optional timeout for URL-backed reader access or OPTIMADE requests.
kind (str | None) – Optional branch selector: "optimade" or "load".
**kwargs (Any) – Additional options passed to the file reader.

Returns:

The fetched OPTIMADE resource or loaded file value.

Raises:

ValueError – If the URL, kind, or automatic branch selection is invalid.

Return type:

Any

class httk.core.FileEntry[source]¶

Logical entry family for served FileRecord records.

This family is not itself storable; store a FileRecord directly.

type = 'files'¶

definition_id = 'https://schemas.optimade.org/defs/v1.2/entrytypes/optimade/files'¶

class httk.core.FileRecord[source]¶

Bases: httk.core.entry_types.File

Store one OPTIMADE files entry with a content identity.

URL and name remain required positional fields. The URL is included in identity so separate paths to identical bytes remain separate entries. Metadata timestamps and immutable identifiers are excluded from identity. checksums is skipped because mapping fields are not SQL-storable; store the flat sha256 value when a storable digest is needed.

Parameters:

url – The URL to get the contents of the file.
name – The base name of the file.
immutable_id – An optional provider-specific immutable identifier.
last_modified – The optional timezone-aware metadata timestamp.
url_stable_until – The optional URL stability deadline.
size – The file size in bytes, if known.
media_type – The file MIME type, if known.
version – The file version, if known.
modification_timestamp – The optional content modification timestamp.
description – An optional free-form file description.
checksums – Optional checksums, kept out of SQL storage.
atime – The optional POSIX access timestamp.
ctime – The optional POSIX status-change timestamp.
mtime – The optional POSIX modification timestamp.
sha256 – The optional flat SHA-256 digest.

immutable_id: Annotated[str | None, IdentitySkip()] = None¶

last_modified: Annotated[datetime.datetime | None, IdentitySkip()] = None¶

url_stable_until: Annotated[datetime.datetime | None, IdentitySkip()] = None¶

size: int | None = None¶

media_type: str | None = None¶

version: str | None = None¶

modification_timestamp: Annotated[datetime.datetime | None, IdentitySkip()] = None¶

description: str | None = None¶

checksums: Annotated[collections.abc.Mapping[str, str] | None, Skip()] = None¶

atime: Annotated[datetime.datetime | None, IdentitySkip()] = None¶

ctime: Annotated[datetime.datetime | None, IdentitySkip()] = None¶

mtime: Annotated[datetime.datetime | None, IdentitySkip()] = None¶

sha256: str | None = None¶

property type: str¶

Return the served entry type name.

property id: str¶

Return the content identity of this file record.

httk.core.has_reader_for(name)[source]¶

Return whether name matches a registered reader key.

Parameters:: name (str) – Filename or URL path whose reader registration is checked.
Returns:: Whether the name matches a registered extension or exact basename.
Return type:: bool

httk.core.load(filename, *, raw=False, **kwargs)[source]¶

Load filename and adapt its neutral payload to a domain object.

Dispatch strips at most one recognized compression suffix (.gz, .bz2, …) to obtain an inner name, then selects a reader by that inner name’s extension (.cif, .poscar, …) or, failing that, by its exact basename (POSCAR, CONTCAR; case-insensitive). The selected reader always receives the original filename; readers open it through the datastream layer, which transparently decompresses. By default, a mapping with a string "format" tag is passed to the registered domain adapter for that format. raw=True is the neutral-payload escape hatch. Payloads with unknown formats, and non-mapping reader results, pass through unchanged.

Parameters:

filename (str) – Local filename to read.
raw (bool) – Whether to return the neutral reader result without adaptation.
**kwargs (Any) – Additional options passed to the selected reader.

Returns:

The loaded and optionally adapted value.

Raises:

ValueError – If filename is a URL or no reader matches it.

Return type:

Any

httk.core.load_many(sources, *, processes=None, errors='raise', **kwargs)[source]¶

Load multiple sources lazily, preserving input order.

processes=None uses the process-pool default. processes=0 or processes=1 loads in the current process, which is also the guaranteed path for readers registered at runtime. Parallel workers rediscover installed registration packages, but runtime registrations are not guaranteed to be present in a fresh worker. Parallel work uses bounded ordered futures rather than map() so worker failures and result-pickling failures can be returned per source.

Parameters:

sources (collections.abc.Iterable[Any]) – Sources accepted by load().
processes (int | None) – Number of worker processes, or None for the default.
errors (Literal['raise', 'return']) – Whether to raise failures or yield them as exception values.
**kwargs (Any) – Options forwarded to every load() call.

Returns:

A lazy iterator of (source, result) pairs in input order.

Raises:

ValueError – If errors is not "raise" or "return", or if processes is negative.
TypeError – If processes is not an integer or None.

Return type:

collections.abc.Generator[tuple[Any, Any], None, None]

httk.core.load_source(source, name, *, raw=False, **kwargs)[source]¶

Load source using the reader selected by name.

Parameters:

source (Any) – Source passed to the selected reader.
name (str) – Name used for extension or exact-basename dispatch.
raw (bool) – Whether to return the neutral reader result without adaptation.
**kwargs (Any) – Additional options passed to the selected reader.

Returns:

The reader result, optionally adapted to a domain value.

Raises:

ValueError – If no reader matches the name; the error lists known extensions and basenames.

Return type:

Any

httk.core.combined_precision(values)[source]¶

Return the precision of a set of values taken together: the coarsest of them.

A structure is only as precisely stated as its least precisely stated number, so one sloppy 0.5 among a table of six-decimal coordinates really does mean the table is good to 1e-1. Taking the coarsest is the conservative reading and the one that keeps a derived tolerance from being too tight to match anything.

Each value may be a literal to be interpreted by decimal_precision(), or an already-computed precision, such as a standard uncertainty read from a file. Numeric values convert through their decimal spelling, so 0.005 lands on 1/200 rather than a binary approximation of it. Values that state no precision are skipped, and None is returned when none of them state one.

Parameters:: values (collections.abc.Iterable[object]) – Values or precision bounds to combine.
Returns:: The largest absolute precision bound, or None if none is stated.
Return type:: fractions.Fraction | None

httk.core.decimal_precision(text)[source]¶

Return the absolute precision implied by how a number was written, or None.

None means the literal makes no precision claim, which is a different thing from claiming perfect precision. It is returned for an empty or missing value, for CIF’s ? and . placeholders, for anything that is not a decimal literal, and — this one matters — for an exact rational such as "1/3", which states a value rather than a measurement and so should not drag a structure’s precision down to the width of its last digit.

Examples, all exact:

"0.123" -> 1/1000 — three digits after the point
"-0.5" -> 1/10 — the sign is not part of the claim
".25" -> 1/100 — a leading point is still two digits
"5." -> 1 — a trailing point states no fraction
"10" -> None — an integer literal states a value exactly, like a rational
"1.2e-3" -> 1/10000 — one digit, then scaled by the exponent
"1/3" -> None — exact, not measured
"?" -> None — no value at all

Parameters:: text (object) – Value whose textual representation supplies the precision claim.
Returns:: The absolute precision bound, or None when the value makes no measured-precision claim.
Return type:: fractions.Fraction | None

class httk.core.EntryTypeDefinition(name, description, properties, definition_id=None, extends_id=None)[source]¶

An immutable OPTIMADE entry-type definition.

Bundles the entry type’s name and description with an insertion-ordered mapping of PropertyDefinition objects (one per described property). A standard definition typically describes more properties than any given deployment serves; the served subset is chosen separately (an EntryProvider names it through its property_keys()).

definition_id identifies the source document when present. An extended definition is a new document, so it clears that identity and retains the original standard IRI in extends_id instead.

Parameters:

name (str) – The entry type name.
description (str) – The human-readable entry type description.
properties (collections.abc.Mapping[str, PropertyDefinition]) – Property definitions keyed by property name.
definition_id (str | None) – The source document IRI, if one exists.
extends_id (str | None) – The standard document IRI extended by this definition, if any.

classmethod from_optimade(name, entrytype)[source]¶

Build an entry-type definition from a vendored OPTIMADE entry type.

entrytype is the vendored document shape: a description string, an optional top-level $id, and a properties mapping of property name to full property definition. A clear ValueError is raised when either required field is missing. The optional ID identifies the source document; ad-hoc definitions remain valid without one.

Parameters:

name (str) – The entry type name.
entrytype (collections.abc.Mapping[str, Any]) – The vendored entry-type definition document.

Returns:

An entry-type definition built from the document.

Raises:

ValueError – If description or properties is missing.

Return type:

Self

property name: str¶

Return the entry type name.

property description: str¶

Return the entry type description.

property definition_id: str | None¶

Return this definition’s document IRI, if it has a standard one.

property extends_id: str | None¶

Return the original standard IRI extended to make this definition, if any.

property properties: collections.abc.Mapping[str, PropertyDefinition]¶

Return a copy of the property definitions keyed by name.

extended(extra, *, allow_unprefixed=False)[source]¶

Return a copy with extra custom property definitions merged in.

Each name in extra MUST be new (a collision with an existing property raises ValueError naming it) and, unless allow_unprefixed is set, MUST carry a registered database-specific prefix (see register_definition_prefix() / known_definition_prefixes()); a custom property that does not is rejected with a ValueError explaining the OPTIMADE prefix rule. The result deliberately has no definition_id: it is a new document, not the standard resource. Its extends_id records the original standard ID so repeated extensions retain that provenance.

Parameters:

extra (collections.abc.Mapping[str, PropertyDefinition]) – New custom property definitions to add.
allow_unprefixed (bool) – Whether to allow custom names without a registered prefix.

Returns:

A new definition containing the original and extra properties.

Raises:

ValueError – If a property collides or violates the prefix rule.

Return type:

Self

as_optimade()[source]¶

Return the entry type as a vendored-shape OPTIMADE document.

Returns:: The entry-type document with independent property payloads.
Return type:: dict[str, Any]

class httk.core.PropertyDefinition(name, payload)[source]¶

An immutable wrapper around one full OPTIMADE property definition.

Instances are constructed from a vendored definition document (from_optimade()) or generated from a compact description (from_simple()). The wrapped document is always deep-copied on the way in and out, so an instance never shares mutable state with its inputs or its callers.

Parameters:

name (str) – The canonical property name.
payload (collections.abc.Mapping[str, Any]) – The complete property-definition document.

classmethod from_optimade(name, definition)[source]¶

Wrap a full vendored OPTIMADE property definition.

definition must at least carry $id, description, x-optimade-type, and type; a clear ValueError is raised otherwise. The document is deep-copied.

Parameters:

name (str) – The canonical property name.
definition (collections.abc.Mapping[str, Any]) – The full property-definition document to wrap.

Returns:

A validated property definition.

Raises:

ValueError – If a required property-definition field is missing.

Return type:

Self

classmethod from_simple(name, *, description, fulltype='string', unit=None, dimensions=None, dict_properties=None, metadata_definition=None, required_response=False, definition_id=None)[source]¶

Generate a property definition from a compact description.

This mirrors the OPTIMADE property-definition generator: it emits the $schema meta-schema reference, a synthesized $id (under the base registered for a matching prefix via register_definition_prefix() — e.g. httk.org for _httk_ — under schemas.optimade.org otherwise, unless definition_id overrides it), a title, the description, the OPTIMADE type derived from fulltype ("string", "integer", "float", "boolean", "timestamp", "dict", or "list of ..."), the x-optimade-unit (with an ångström unit definition when unit == "angstrom"), the x-optimade-definition stamp (format "1.2"; see the module docstring), the JSON type with nullability derived from required_response, items for lists, a date-time format for timestamps, inner properties for dicts (from dict_properties), x-optimade-dimensions from dimensions, and an x-optimade-metadata-definition (explicit, or a generated list_axes definition when dimensions is given).

The result is implementation-neutral: per-deployment sortable and response-default flags are layered on later via with_implementation().

Parameters:

name (str) – The canonical property name.
description (str) – The human-readable property description.
fulltype (str) – The OPTIMADE property type description.
unit (str | None) – The unit associated with numeric or list values.
dimensions (collections.abc.Mapping[str, Any] | None) – Dimension names and sizes for list values.
dict_properties (collections.abc.Mapping[str, str] | None) – Inner property names and type descriptions for dictionaries.
metadata_definition (collections.abc.Mapping[str, Any] | None) – An explicit metadata definition for the property.
required_response (bool) – Whether responses must contain a non-null value.
definition_id (str | None) – An explicit property-definition IRI.

Returns:

A generated property definition.

Return type:

Self

property name: str¶

Return the canonical property name.

property definition_id: str¶

Return the property’s definition IRI.

property title: str | None¶

Return the property’s title, if declared.

property description: str¶

Return the property’s human-readable description.

property optimade_type: str¶

Return the property’s OPTIMADE type name.

property json_type: Any¶

Return the property’s JSON Schema type declaration.

property nullable: bool¶

Return whether the property’s JSON type permits null.

property unit: str | None¶

Return the property’s declared unit, if any.

property format_version: str | None¶

Return the property’s definition-format version, if declared.

property requirements: collections.abc.Mapping[str, Any]¶

Return the property’s OPTIMADE requirements mapping.

property dimensions: collections.abc.Mapping[str, Any] | None¶

Return the property’s dimensions declaration, if any.

property metadata_definition: collections.abc.Mapping[str, Any] | None¶

Return the property’s metadata definition, if any.

with_implementation(*, sortable=None, response_default=None)[source]¶

Return a copy carrying this deployment’s implementation flags.

Adds an x-optimade-implementation object with the sortable and response-default keys that are provided (a None argument leaves that key unset), and — when sortable is given — mirrors it in a top-level sortable field. The original instance is untouched. The original $id and x-optimade-definition are retained because the vendored v1.2 Property Definitions meta-schema says definitions “SHOULD be regarded as the same if they only differ by” changes to x-optimade-implementation; the specification says a redefinition “MUST change the $id”. Top-level sortable is the additional field required by the Entry Listing Info Endpoints section.

Parameters:

sortable (bool | None) – Whether the property can be sorted by the deployment.
response_default (bool | None) – Whether the property is included by default in responses.

Returns:

A copy with the requested implementation flags.

Return type:

Self

as_optimade()[source]¶

Return a deep copy of the wrapped property-definition document.

Returns:: The wrapped document, independent of the instance’s state.
Return type:: dict[str, Any]

httk.core.known_definition_prefixes()[source]¶

Return the registered database-specific property-name prefixes.

The tuple reflects the current state of the prefix registry (see register_definition_prefix()); _httk_ is pre-registered.

Returns:: The registered prefixes in registration order.
Return type:: tuple[str, Ellipsis]

httk.core.register_definition_prefix(prefix, id_base)[source]¶

A custom property served by a database MUST use such a prefix (see the OPTIMADE specification, “Database-Specific Properties”). Once registered, a property name carrying prefix gets its $id synthesized under id_base by PropertyDefinition.from_simple(), and EntryTypeDefinition.extended() accepts it as a custom property.

prefix must be a lower-case alphanumeric token wrapped in single underscores (matching _[a-z0-9]+_); anything else raises a clear ValueError. Re-registering an existing prefix overwrites its base.

Parameters:

prefix (str) – The database-specific property-name prefix to register.
id_base (str) – The IRI base used for synthesized property definition IDs.

Raises:

ValueError – If prefix does not match _[a-z0-9]+_.

httk.core.standard_entry_type(name)[source]¶

Return one of httk-core’s vendored standard OPTIMADE entry types.

Supported names are "references", "files", and "calculations"; an unknown name raises a ValueError listing the known ones. The structures standard is vendored by httk-atomistic, not httk-core.

Parameters:: name (str) – The standard entry type name to load.
Returns:: The vendored entry-type definition.
Raises:: ValueError – If name is not vendored by httk-core.
Return type:: EntryTypeDefinition

class httk.core.ProductLink[source]¶

A curation has_product/is_product edge between data entries.

A label is unique per source entry across links; that constraint is enforced at the serving projection rather than on each record.

Parameters:

source_type – The source entry type name.
source_id – The source entry identifier.
target_type – The target entry type name.
target_id – The target entry identifier.
label – The relationship label, unique per source entry at serving time.
workflow_declaration_uri – The workflow declaration IRI, if declared.

source_type: str¶

source_id: str¶

target_type: str¶

target_id: str¶

label: str¶

workflow_declaration_uri: str | None = None¶

classmethod create(obj)[source]¶

Coerce a mapping or existing link into a ProductLink.

Parameters:

obj (ProductLink | Mapping[str, Any]) – A product-link instance or field mapping.

Returns:

The existing or newly constructed product link.

Raises:

TypeError – If obj is neither a product link nor a mapping.
ValueError – If the mapping has unknown or invalid fields.

Return type:

Self

class httk.core.Run[source]¶

One workflow execution with loose provenance edges.

inputs are has_input edges to consumed entries, artifacts are has_artifact edges to created entries, and outputs are has_output edges to returned entries. Artifact single-creator exclusivity across runs is documented here, not enforced per record.

Every invariant is cheap and total, so there is deliberately no __httk_validate__ hook.

Edges remain loose string triples by design, never object references. Labels are unique independently on each of inputs, artifacts, and outputs.

Parameters:

workflow_declaration_uri – The workflow declaration IRI, if declared.
inputs – The labeled entries consumed by the run.
artifacts – The labeled entries created by the run.
outputs – The labeled entries returned by the run.
immutable_id – An optional provider-specific immutable identifier.
last_modified – The optional timezone-aware metadata timestamp.

workflow_declaration_uri: str | None = None¶

inputs: tuple[RunEdge, Ellipsis] = ()¶

artifacts: tuple[RunEdge, Ellipsis] = ()¶

outputs: tuple[RunEdge, Ellipsis] = ()¶

immutable_id: Annotated[str | None, IdentitySkip()] = None¶

last_modified: Annotated[datetime.datetime | None, IdentitySkip()] = None¶

property type: str¶

Return the served entry type name.

property id: str¶

Return the content identity of this run.

classmethod create(obj)[source]¶

Coerce a mapping or existing run into a Run.

Parameters:

obj (Run | Mapping[str, Any]) – A run instance or field mapping.

Returns:

The existing or newly constructed run.

Raises:

TypeError – If obj is neither a run nor a mapping.
ValueError – If the mapping has unknown or invalid fields.

Return type:

Self

class httk.core.RunEdge[source]¶

Store one loose labeled reference from a run to another entry.

Edges deliberately keep the related entry’s type and identifier as strings rather than object references, so a run can refer to entries served by another provider.

Parameters:

label – The relationship label.
entry_type – The related entry type name.
entry_id – The related entry identifier.

label: str¶

entry_type: str¶

entry_id: str¶

classmethod create(obj)[source]¶

Coerce a mapping or existing edge into a RunEdge.

Parameters:

obj (RunEdge | Mapping[str, Any]) – A run edge instance or field mapping.

Returns:

The existing or newly constructed run edge.

Raises:

TypeError – If obj is neither a run edge nor a mapping.
ValueError – If the mapping has unknown or invalid fields.

Return type:

Self

class httk.core.RunEntry[source]¶

Logical entry family for served Run records.

This family is not itself storable; store a Run directly.

type = '_httk_runs'¶

definition_id = 'https://schemas.httk.org/defs/v0.1/entrytypes/runs'¶

httk.core.register_cli_command(name, handler, summary)[source]¶

A handler is either a callable or a lazy "module:callable" reference with the contract (argv: Sequence[str], context: CLIContext) -> int. Names use lowercase, hyphen-separated command syntax. Registration is intentionally strict: reserved names and duplicate registrations are errors rather than order-dependent overrides.

Parameters:

name (str) – The lowercase hyphen-separated command name.
handler (str | collections.abc.Callable[Ellipsis, Any]) – The command callable or lazy "module:callable" reference.
summary (str) – The nonempty one-line command summary.

Raises:

TypeError – If handler is neither callable nor a lazy reference.
ValueError – If the name, handler reference, summary, or registration is invalid.

httk.core.known_entry_providers()[source]¶

Return registered entry-provider names.

Returns:: Registered provider names.
Return type:: list[str]

httk.core.register_entry_family(*, name, family, definition_id=None)[source]¶

Parameters:

name (str) – The entry-family registry name.
family (str) – The lazy "module:class" family reference.
definition_id (str | None) – The family’s definition IRI, if any.

Raises:

ValueError – If validation fails or name is already registered.

httk.core.register_entry_provider(*, name, factory)[source]¶

factory is a lazy "module:callable" reference to a callable that constructs a provider (providers need data, so applications call the factory themselves; the registry only records how to reach it). This mirrors register_reader.

Parameters:

name (str) – The provider registry name.
factory (str) – The lazy "module:callable" factory reference.

httk.core.register_entry_record(*, name, record, family=None, definition_id=None)[source]¶

Parameters:

name (str) – The record registry name.
record (str) – The lazy "module:class" record reference.
family (str | None) – The logical entry-family name, if any.
definition_id (str | None) – The record’s definition IRI, if any.

Raises:

ValueError – If validation fails or name is already registered.

httk.core.register_optimade_entry_binding(*, name, definition_id, backend, view, property_decoders=None, query_fields=None)[source]¶

Parameters:

name (str) – The binding registry name.
definition_id (str) – The exact entry-type definition IRI selected by the binding.
backend (str) – The lazy backend class reference.
view (str) – The lazy view class reference.
property_decoders (collections.abc.Mapping[str, str] | None) – Property definition IRIs mapped to lazy decoder references.
query_fields (tuple[str, Ellipsis] | None) – Property definition IRIs supported for querying, if restricted.

Raises:

ValueError – If the definition IRI is already registered or input is invalid.

httk.core.register_format_adapter(*, name, adapter, formats)[source]¶

adapter may be a callable or a lazy "module:callable" reference. A format tag has one owner: registering it again raises an error naming both the existing and attempted registrants.

Parameters:

name (str) – The registry name for the adapter.
adapter (str | collections.abc.Callable[Ellipsis, Any]) – The adapter callable or lazy "module:callable" reference.
formats (collections.abc.Sequence[str]) – Neutral payload format tags served by the adapter.

Raises:

ValueError – If a format tag is invalid, duplicated, or already owned.

httk.core.register_format_serializer(*, format, serializer)[source]¶

Parameters:

format (str) – The neutral payload format tag.
serializer (str | collections.abc.Callable[Ellipsis, Any]) – The serializer callable or lazy reference.

Raises:

ValueError – If format is invalid or already has another serializer.

httk.core.register_reader(*, name, reader, extensions=(), filenames=())[source]¶

extensions are matched (case-insensitively) against a file’s suffix, e.g. ".cif". filenames are exact basenames matched (case-insensitively) against a file’s name with any recognized compression suffix stripped, e.g. "POSCAR" matches POSCAR, poscar, and POSCAR.bz2.

Parameters:

name (str) – The registry name for the reader.
reader (str) – A lazy "module:callable" reference to the reader.
extensions (tuple[str, Ellipsis]) – File suffixes that select the reader.
filenames (tuple[str, Ellipsis]) – Exact basenames that select the reader.

httk.core.register_writer(*, name, writer, format, extensions=(), filenames=())[source]¶

A format can have one writer owner; registering a conflicting writer raises an error. Extension and basename keys are matched case-insensitively.

Parameters:

name (str) – The registry name for the writer.
writer (str | collections.abc.Callable[Ellipsis, Any]) – The writer callable or lazy "module:callable" reference.
format (str) – The neutral payload format emitted by the writer.
extensions (tuple[str, Ellipsis]) – File suffixes that select the writer.
filenames (tuple[str, Ellipsis]) – Exact basenames that select the writer.

Raises:

ValueError – If format is invalid or conflicts with an existing writer.

httk.core.load_entry_type_definition(definition_id)[source]¶

Load and verify a registered entry-type definition resource.

Parameters:: definition_id (str) – The registered entry-type definition IRI.
Returns:: The loaded and validated entry-type definition.
Raises:: ValueError – If the IRI is unregistered or disagrees with the document.
Return type:: httk.core.property_definitions.EntryTypeDefinition

httk.core.load_property_definition(definition_id)[source]¶

Load and verify a registered property definition resource.

Parameters:: definition_id (str) – The registered property definition IRI.
Returns:: The loaded and validated property definition.
Raises:: ValueError – If the IRI is unregistered or disagrees with the document.
Return type:: httk.core.property_definitions.PropertyDefinition

httk.core.register_entry_type_definition(*, definition_id, resource)[source]¶

Parameters:

definition_id (str) – The entry-type definition IRI.
resource (str) – The package resource reference to load.

Raises:

ValueError – If definition_id is already registered.

httk.core.register_property_definition(*, definition_id, resource)[source]¶

Parameters:

definition_id (str) – The property definition IRI.
resource (str) – The package resource reference to load.

Raises:

ValueError – If definition_id is already registered.

httk.core.has_writer_for(name)[source]¶

Return whether name matches a registered writer key.

Parameters:: name (str) – Destination filename whose writer registration is checked.
Returns:: Whether the name matches a registered extension or exact basename.
Return type:: bool

httk.core.save(obj, destination, *, format=None, **kwargs)[source]¶

Save obj to a local destination selected by its name or format hint.

The writer registry selects by extension first and exact basename second, case-insensitively after stripping one recognized compression suffix, unless format selects a registered writer directly. The format-serializer registry converts non-neutral objects before writing, and a recognized compression suffix wraps the destination transparently.

Parameters:

obj (Any) – Object or neutral payload to serialize and write.
destination (str | os.PathLike[str]) – Local filename or path to write.
format (str | None) – Optional registered format name that selects the writer.
**kwargs (Any) – Additional options passed to the selected writer.

Raises:

ValueError – If the destination or format has no writer, no serializer exists, or the destination is a URL.

class httk.core.Service[source]¶

Describe one service independently of its publication transport.

The service and endpoint identifiers are absolute IRIs; this neutral core contract does not impose a particular scheme. conforms_to names one or more standards the service implements, and may be supplied as any ordered non-string iterable.

Parameters:

id – The service’s absolute IRI.
title – The service’s human-readable title.
endpoint_url – The service endpoint’s absolute IRI.
conforms_to – Non-empty unique absolute IRIs for implemented standards.
serves_dataset_ids – Optional non-empty unique absolute IRIs for served datasets.
endpoint_description – An optional absolute IRI describing the endpoint.

id: str¶

title: str¶

endpoint_url: str¶

conforms_to: tuple[str, Ellipsis]¶

serves_dataset_ids: tuple[str, Ellipsis] | None = None¶

endpoint_description: str | None = None¶

classmethod create(obj)[source]¶

Coerce a mapping or existing service into a Service.

Parameters:

obj (Service | Mapping[str, Any]) – A service instance or a mapping with service fields.

Returns:

The existing or newly constructed service.

Raises:

TypeError – If obj is neither a service nor a mapping.
ValueError – If the mapping has missing, unknown, or invalid fields.

Return type:

Self

class httk.core.ServiceRecord[source]¶

Bases: Service

Store one Service using the core service storage contract.

Parameters:

id – The service’s absolute IRI.
title – The service’s human-readable title.
endpoint_url – The service endpoint’s absolute IRI.
conforms_to – Non-empty unique absolute IRIs for implemented standards.
serves_dataset_ids – Optional non-empty unique absolute IRIs for served datasets.
endpoint_description – An optional absolute IRI describing the endpoint.

classmethod create(obj)[source]¶

Coerce a service record, neutral service, or field mapping.

Parameters:

obj (ServiceRecord | Service | Mapping[str, Any]) – A service record, neutral service, or service field mapping.

Returns:

The existing or newly constructed service record.

Raises:

TypeError – If obj is not a service or mapping.
ValueError – If the mapping has unknown, missing, or invalid fields.

Return type:

Self

httk.core.content_id(obj, *, as_record=None, projector=project_storage_record)[source]¶

Return the lowercase SHA-256 content identity of obj.

The digest covers canonical_form(), including exact-type leaf encodings and excluding fields marked with IdentitySkip.

Parameters:

obj (Any) – The record or projected source to identify.
as_record (type[Any] | None) – An explicit record class override, if supplied.
projector (collections.abc.Callable[[type[Any], Any], collections.abc.Mapping[str, object]]) – The record-level projection function.

Returns:

The lowercase SHA-256 hexadecimal digest.

Raises:

TypeError – If a value or projection cannot be represented.
ValueError – If a projection is invalid or contains a cycle.

Return type:

str

class httk.core.IdentitySkip[source]¶: Field marker: exclude the field from content identity.

class httk.core.Indexed[source]¶: Field marker: request a single-column index on this field’s column(s).

class httk.core.Related[source]¶

Field marker: relationship metadata for a reference or list-of-storable field.

Applies to a field holding another storable class (a reference field) or a list/tuple of storable classes. When the field’s target class is served alongside the declaring class, the storage layer surfaces the field as a relationship; this marker attaches the OPTIMADE per-identifier metadata that flows into each emitted RelatedEntry — role (machine readable, OPTIMADE v1.3 meta.role) and description (human readable, OPTIMADE v1.2 meta.description). serve=False suppresses the field as a relationship entirely.

Parameters:

role – The machine-readable relationship role, if any.
description – The human-readable relationship description, if any.
serve – Whether the field is served as a relationship at all.

role: str | None = None¶

description: str | None = None¶

serve: bool = True¶

class httk.core.RelationshipLink[source]¶

Class-level relationship declaration: each stored row expresses one FROM→TO relationship.

Declared in StorageInfo.links. source and target each name a reference field of the declaring class, or are None to mean the declaring class's own entry: for every stored row, one relationship is declared from the entry the source side resolves to, to the entry the target side resolves to. The two canonical shapes:

join-object: RelationshipLink("structure", "reference") on a StructureRef join class — every StructureRef row relates its structure to its reference (structures → references), without the join class itself being served.
field-inverse: RelationshipLink("structure", None, role="output") on a Calculation class — every Calculation row relates its structure to the calculation itself (structures → calculations), i.e. the inverse of the structure reference field.

role and description carry the same OPTIMADE per-identifier metadata as Related into each relationship the link declares.

Parameters:

source – The reference field naming the FROM-side entry, or None for the declaring class’s own entry.
target – The reference field naming the TO-side entry, or None for the declaring class’s own entry.
role – The machine-readable relationship role, if any.
description – The human-readable relationship description, if any.

Raises:

ValueError – If both endpoints are None (which would relate every entry to itself), or if they name the same field.

source: str | None¶

target: str | None¶

role: str | None = None¶

description: str | None = None¶

class httk.core.Shape[source]¶

Field marker: fixed or variable shape for a vector-valued field.

rows >= 1 declares a fixed-shape value stored inline (flattened row-major into columns). rows == 0 declares a variable number of rows with cols fixed columns each, stored out-of-line (one row per entry, in insertion order).

Parameters:

rows – Number of rows; 0 means variable-length.
cols – Number of columns per row; must be at least 1.

Raises:

ValueError – If rows is negative or cols is less than 1.

rows: int¶

cols: int = 1¶

class httk.core.Skip[source]¶: Field marker: the field exists on the dataclass but is not stored.

class httk.core.StorageInfo[source]¶

Optional class-level storage declaration for a storable dataclass.

Attach as the class attribute named by STORAGE_INFO_ATTRIBUTE (__httk_storage__), annotated ClassVar[StorageInfo] so dataclass processing ignores it. A storage layer may also accept an instance as an external override for classes that cannot be modified.

Parameters:

storage_name – The physical storage name; None derives one from the class name. Relational backends use it as the table name, and document stores use it as the collection name.
indexes – Composite indexes, each a tuple of field names.
dedup – The deduplication policy applied when saving; see DedupPolicy.
links – Class-level relationship declarations; see RelationshipLink.
identity_name – The logical name included in content identity; None derives it from the declaring class and its bases.

Raises:

ValueError – If dedup or an identity name or index declaration is invalid.

storage_name: str | None = None¶

indexes: tuple[tuple[str, Ellipsis], Ellipsis] = ()¶

dedup: DedupPolicy = 'content_id'¶

links: tuple[RelationshipLink, Ellipsis] = ()¶

identity_name: str | None = None¶

class httk.core.Unique[source]¶: Field marker: request a unique index on this field’s column(s).

class httk.core.stored_property(fget=None, fset=None, fdel=None, doc=None)[source]¶

Bases: property

A derived property that a storage layer stores and makes queryable.

Use exactly like property (getter only). The value type is read from the getter’s return annotation. On save, the storage layer evaluates and stores the value alongside the declared fields; on load, the value is recomputed by the property rather than passed to __init__. The getter must declare a return annotation when the property is created.

Parameters:

fget (collections.abc.Callable[Ellipsis, Any] | None) – The getter function whose derived value is stored.
fset (collections.abc.Callable[Ellipsis, Any] | None) – An optional setter, normally unused by storage declarations.
fdel (collections.abc.Callable[Ellipsis, Any] | None) – An optional deleter, normally unused by storage declarations.
doc (str | None) – An optional property documentation string.

Raises:

TypeError – If fget has no return annotation.

class httk.core.FracScalar(value, *, denom=None, simplify=True, chain=False, min_accuracy=fractions.Fraction(1, 10000))[source]¶

Bases: FracVector

Represents the fractional number nom/denom. This is a subclass of FracVector with the purpose of making it clear when a scalar fracvector is needed/used.

Convert a value into a FracScalar.

FracScalar(something) where something may be any object that can be used in the constructor of the Python Fraction class (also works with strings!).

For signature compatibility with the FracVector constructor, this accepts but ignores chain and min_accuracy, and converts strings exactly via the Fraction constructor.

Parameters:

value (Any) – The scalar value or values to convert.
denom (int | None) – An optional additional denominator.
simplify (bool) – Whether to reduce the resulting denominator.
chain (bool) – An accepted compatibility parameter; it does not affect scalar creation.
min_accuracy (fractions.Fraction | None) – An accepted compatibility parameter; scalar strings are exact.

classmethod from_noms_and_denom(noms, denom=1)[source]¶

Build from a trusted raw integer nominator and denominator, without validation.

class httk.core.FracVector(values, *, denom=None, simplify=True, chain=False, min_accuracy=fractions.Fraction(1, 10000))[source]¶

Bases: FracVectorBase, httk.core.vectors.vector_backend.VectorBackend

Immutable exact-rational vector that is also its own vector backend.

property fractions: httk.core.vectors.vector_api.Fractions¶

Return this vector in the exact nested Fraction interchange format.

class httk.core.MutableFracVector(values, *, denom=None, simplify=True, chain=False, min_accuracy=fractions.Fraction(1, 10000))[source]¶

Bases: httk.core.vectors.fracvector.FracVectorBase

Same as FracVector, only this version allows assignment of elements, e.g.:

mfracvec[2, 7] = 5

and, e.g.:

mfracvec[:, 7] = [1, 2, 3, 4]

Other than this, the FracVector methods exist and do the same, i.e., they return copies of the fracvector, rather than modifying it.

Parameters:

values (Any) – A rational value-like to convert, such as nested sequences or scalars.
denom (int | None) – An optional additional common denominator.
simplify (bool) – Whether to reduce the resulting denominator.
chain (bool) – Whether to flatten the outermost nested sequence.
min_accuracy (fractions.Fraction | None) – Minimum accuracy for decimal values, or None for exact conversion.

Methods with set_* prefixes perform mutating operations, e.g.:

A.set_T()

replaces A with its own transpose, whereas:

A.T()

just returns a new MutableFracVector that is the transpose of A, leaving A unmodified.

nested_map: ClassVar[collections.abc.Callable[Ellipsis, Any]]¶

nested_inmap: ClassVar[collections.abc.Callable[Ellipsis, Any]]¶

nested_map_fractions: ClassVar[collections.abc.Callable[Ellipsis, Any]]¶

noms: Any¶

validate()[source]¶

Return whether the vector’s stored list structure is valid.

invalidate()[source]¶

Internal method to call when the MutableFracVector is changed in such a way that cached properties are invalidated (e.g., _dim).

Returns:: None.
Return type:: None

set_negative()[source]¶

Change the MutableFracVector inline into its own negative: self -> -self.

set_T()[source]¶

Change the MutableFracVector inline into its own transpose: self -> self.T.

set_inv()[source]¶

Change the MutableFracVector inline into its own inverse: self -> self^-1.

Returns:: The inverse scalar when self is scalar; otherwise None after mutation.
Return type:: Any

set_simplify()[source]¶

Change the MutableFracVector; reduces any common factor between the denominator and all nominators.

set_set_denominator(resolution=1000000000)[source]¶

Change the MutableFracVector; reduces resolution.

Parameters:: resolution (int) – The new denominator; each element becomes the closest numerical approximation using this denominator.

set_normalize()[source]¶

Add/remove an integer +/-N to each element to place it in the range [0, 1).

set_normalize_half()[source]¶

Add/remove an integer +/-N to each element to place it in the range [-1/2, 1/2).

This is useful to find the shortest vector C between two points A, B in a space with periodic boundary conditions [0, 1):

C = (A - B).normalize_half()

type httk.core.NumericVector = float | numpy.ndarray[source]¶

type httk.core.ScalarLike = int | float | str | fractions.Fraction | decimal.Decimal | fracvector.FracScalar | surdvector.SurdScalar[source]¶

class httk.core.SurdScalar(value)[source]¶

Bases: SurdVector

A scalar SurdVector (shape ()): a single field element $\sum_r q_r\sqrt r$.

Adds the scalar-only operations — the field inverse, exact sign and ordering, and Decimal rendering — that need a single value rather than a tensor.

Parameters:: value (Any) – A rational scalar/nested sequence accepted by FracVector, or an existing SurdVector or SurdScalar, returned unchanged.

inverse()[source]¶

Return the multiplicative inverse 1/self (raises ZeroDivisionError on zero).

Returns:: The exact multiplicative inverse.
Return type:: SurdScalar

sign()[source]¶

Return the exact sign of the value: -1, 0 or 1.

For an irrational value the sign is decided by refining rational lower/upper bounds on each sqrt(r) (from integer_sqrt() at increasing precision) and summing the weighted intervals until the total interval excludes zero — which always happens in finitely many steps because a nonzero surd is bounded away from zero.

Returns:: -1, 0, or 1 according to the exact sign.
Return type:: int

classmethod cos_degrees(q)[source]¶

Return cos(q degrees) as an exact SurdScalar, or None when it is not a surd.

The value lies in the squarefree-radical field precisely when the angle, reduced modulo 360, is a multiple of 15 or of 36 degrees — e.g. $\cos 30° = \tfrac{\sqrt3}2$, $\cos 15° = \tfrac{\sqrt6+\sqrt2}4$, $\cos 36° = \tfrac{1+\sqrt5}4$. q may be an int, Fraction, or numeric string (parsed via any_to_fraction()).

That list is complete: $\cos(2\pi a/b)$ lies in a field generated by square roots of rationals iff the Galois group $(\mathbb{Z}/b)^\times/\{\pm1\}$ of $\mathbb{Q}(\cos 2\pi/b)$ has exponent at most 2, which holds exactly for $b \in \{1,2,3,4,5,6,8,10,12,24\}$ — the rational-degree angles that are multiples of 15° or 36°. (Niven’s theorem is the rational-value special case of this classification.) A None result is therefore a proof that the exact cosine lies outside $\mathbb{Q}[\sqrt n]$ — use cos() with degrees=True for a deterministic rational approximation in that case.

Parameters:: q (Any) – The angle in degrees.
Returns:: The exact cosine, or None outside the surd field.
Return type:: SurdScalar | None

classmethod sin_degrees(q)[source]¶

Return sin(q degrees) as an exact SurdScalar, or None when the value lies outside the supported surd field (when 90 - q is not in the exact surd-cosine set).

Computed as cos(90 - q) degrees, so exactness follows the same classification as cos_degrees() applied to 90 - q: exact when 90 - q is a multiple of 15 or 36 degrees, and None otherwise (a proof that the exact sine is outside the field). For example, sin(54°) is exact because it is cos(36°).

Parameters:: q (Any) – The angle in degrees.
Returns:: The exact sine, or None outside the surd field.
Return type:: SurdScalar | None

acos_degrees()[source]¶

Return the exact arccos of this value in degrees over $[0, 180]$, or None.

This is the reverse table lookup: the result is an exact rational number of degrees precisely when the value equals the cosine of a multiple of 15° or 36° (the complete set of rational-degree angles with surd cosines — see cos_degrees()), decided by exact surd equality; otherwise None (the exact angle is then irrational in degrees). Raises ValueError — decided exactly via sign() — when the value lies outside $[-1, 1]$.

Returns:: The exact angle in degrees, or None when not represented by the table.
Return type:: fractions.Fraction | None

to_float(prec=fractions.Fraction(1, 10**30))[source]¶

Return the value as a float via a high-precision exact rational approximation.

Parameters:: prec (fractions.Fraction) – The maximum approximation error.
Returns:: The value as a float.
Return type:: float

to_decimal(digits=None, rounding='half_even', max_refinements=None)[source]¶

Render the value as a correctly-rounded decimal.Decimal.

Reuses the exact-math module’s Ziv refinement loop (_to_decimal): a rational value renders exactly (its finite expansion when it fits, else quantized), and an irrational surd — never on a rational rounding boundary — is rendered by refining the rational approximation until the rounding is determined. digits (significant digits; default: the active decimal context precision), rounding ("half_even"/"down") and max_refinements match sqrt() in Decimal mode.

Parameters:

digits (int | None) – The number of significant decimal digits, or the active context precision when omitted.
rounding (str) – The decimal rounding mode.
max_refinements (int | None) – The maximum number of approximation refinements.

Returns:

The correctly rounded decimal value.

Return type:

Any

class httk.core.SurdVector(value)[source]¶

Bases: httk.core.vectors.vector_backend.VectorBackend

An immutable exact tensor over the squarefree-radical field $\mathbb{Q}[\sqrt n : n\ \text{squarefree}]$.

A SurdVector is a map {squarefree radicand -> FracVector coefficient} (all coefficients sharing one dim); radicand 1 is the rational part. It is stored canonically — coefficients simplified, all-zero coefficients dropped — so the representation is unique and equality/zero-detection are exact. Like FracVector it is immutable and hashable.

See the module docstring for the field facts, the fractional-vs-Cartesian motivation, and the magnitude-vs-linear-structure purpose boundary.

Parameters:: value (Any) – An existing SurdVector or SurdScalar, returned unchanged, or a rational scalar/nested sequence accepted by FracVector; rational values become the radicand-1 component.

classmethod from_components(components, dim)[source]¶

Build from trusted component vectors and a shared shape.

classmethod from_radicand_map(mapping)[source]¶

Compose a SurdVector from a {radicand -> coefficient} mapping.

Radicands are positive integers and need not be squarefree — each is normalized via square_part (sqrt(radicand) = s*sqrt(r)) and the coefficients (FracVector-like, all of one shape) folded together canonically.

Parameters:: mapping (dict[int, Any]) – Radicands mapped to their coefficient tensors.
Returns:: The canonical SurdVector representation.
Return type:: SurdVector

classmethod sqrt_of(q)[source]¶

Return the exact square root of a nonnegative rational q as a SurdScalar.

The result is a plain rational when q is a perfect square (e.g. sqrt_of(4/9) == 2/3) and otherwise a single-radical surd (sqrt_of(8) == 2*sqrt(2)). sqrt(p/q) is normalized as sqrt(p*q)/q so the stored radicand is always a positive squarefree integer (sqrt_of(1/2) == sqrt(2)/2). Raises ValueError on a negative argument — there is no exact square root of a surd (no nested radicals), only of a rational.

Parameters:: q (Any) – A nonnegative rational value.
Returns:: Its exact square root.
Return type:: SurdScalar

classmethod zero(dim=())[source]¶

The zero SurdVector of shape dim (a SurdScalar for the default ()).

Parameters:: dim (tuple[int, Ellipsis]) – The shape of the zero tensor.
Returns:: The zero SurdVector or SurdScalar.
Return type:: SurdVector

classmethod one()[source]¶

The scalar 1.

property dim: tuple[int, Ellipsis]¶

The shape tuple, as for dim.

property is_rational: bool¶

True iff the value is purely rational (only the radicand-1 term is present).

is_zero()[source]¶

True iff the value is exactly zero (empty canonical form).

property radicands: tuple[int, Ellipsis]¶

The sorted squarefree radicands present in the canonical form.

coefficient(radicand)[source]¶

Return the FracVector coefficient of sqrt(radicand) (a zero tensor when absent).

Parameters:: radicand (int) – The radicand whose coefficient to retrieve.
Returns:: The coefficient, or a zero tensor when absent.
Return type:: httk.core.vectors.fracvector.FracVector

T()[source]¶

Return the transpose, transposing each radicand’s coefficient tensor.

Returns:: The transposed tensor.
Return type:: SurdVector

dot(other)[source]¶

Return the vector dot product of two 1-D SurdVectors (sum a_i b_i).

Parameters:: other (Any) – The other 1-D SurdVector.
Returns:: The exact scalar dot product.
Return type:: SurdScalar

lengthsqr()[source]¶

Return the squared length A * A^T as a SurdScalar.

Returns:: The exact squared length.
Return type:: SurdScalar

length()[source]¶

Return the exact length sqrt(lengthsqr) as a SurdScalar.

Exact precisely when lengthsqr is rational — which canonical arithmetic guarantees for a difference of Cartesian sites under a rational metric (the crystallographic case). When lengthsqr is itself irrational the length would be a nested radical (sqrt(a + b*sqrt(c))), which is outside the field, so this raises ValueError.

Returns:: The exact length when the squared length is rational.
Return type:: SurdScalar

det()[source]¶

Return the determinant of a 3x3 SurdVector as a SurdScalar.

Returns:: The exact determinant.
Return type:: SurdScalar

inv()[source]¶

Return the inverse of a 3x3 SurdVector via the adjugate and the scalar field inverse.

Returns:: The exact inverse matrix.
Return type:: SurdVector

to_fractions_approx(prec=fractions.Fraction(1, 10**30))[source]¶

A deterministic nested list of fractions.Fraction within prec of the true value.

Exact (not merely within prec) whenever the value is rational. This is the compute(prec)-shaped rational approximation reused by the Decimal rendering.

Parameters:: prec (fractions.Fraction) – The maximum elementwise approximation error.
Returns:: Nested rational approximations of the values.
Return type:: Any

to_floats(prec=fractions.Fraction(1, 10**30))[source]¶

Return a nested list of floats via a high-precision exact rational approximation.

Parameters:: prec (fractions.Fraction) – The maximum elementwise approximation error.
Returns:: Nested floating-point approximations of the values.
Return type:: Any

property fractions: httk.core.vectors.vector_api.Fractions¶

Return the exact or deterministic rational hub representation.

property fractions_exact: bool¶

Return whether the Fraction interchange is exact for this surd.

type httk.core.VectorLike = vector_backend.VectorBackend | vector_view.VectorView | fracvector.FracVector | surdvector.SurdVector | tuple[Any, ...] | list[Any] | 'numpy.ndarray'[source]¶

httk.core.numpy_available()[source]¶

Return whether the optional numpy dependency is available for the numeric helpers.

This reads the vectors package’s _numpy_available flag freshly on each call (the flag set when httk.core.vectors conditionally imports/registers the numpy backend), so tests may monkeypatch httk.core.vectors._numpy_available to exercise the numpy-absent path.

Returns:: True when numpy is available, otherwise False.
Return type:: bool

httk.core.to_numeric(obj)[source]¶

Present obj as plain numpy numbers: a numpy.ndarray for a tensor, a float for a scalar.

A tensor becomes a base-class float64 numpy.ndarray (never a view subclass) via VectorNumpyView; a scalar input (shape ()) returns a plain float via to_numeric_scalar() (never a 0-d array).

The numeric presentation is numpy-backed, so this always requires numpy: it raises ImportError (naming the httk-core[numpy] extra) when numpy is not installed, uniformly, so the contract is predictable regardless of the input shape. Use to_numeric_scalar() directly for a single float without a numpy requirement.

Parameters:

obj (httk.core.vectors.vector_like.VectorLike | float | str | fractions.Fraction) – The vector-like value to present numerically.

Returns:

The converted scalar or tensor value.

Raises:

ImportError – If numpy is unavailable.
TypeError – If the value cannot be converted to the numeric presentation.

Return type:

NumericVector

httk.core.to_numeric_scalar(obj)[source]¶

Convert a single scalar value to a plain float, deterministically.

A SurdScalar (or scalar SurdVector) and a scalar FracVector render through their own exact to_float(); a Fraction, int, float, or numeric str render via any_to_fraction(). A non-scalar shape raises TypeError.

Unlike to_numeric(), this needs no numpy: a plain float conversion has no numpy dependency, so it works unconditionally and never raises for a missing numpy.

Parameters:: obj (Any) – The scalar value to convert.
Returns:: The converted scalar value.
Raises:: TypeError – If obj is not scalar or cannot be converted to a scalar float.
Return type:: float

class httk.core.Backend[BackendT: Backend](backend, **hints)[source]¶

Bases: abc.ABC

Abstract base class to be subclassed into classes that keep track of alternative representations of certain types of data, all adhering to a common API interface.

The class variable backend_classes is a list of all classes that can carry the kind of data the subclass represents.

A system of “hints” are used primarily to disambiguate between multiple valid interpretations of the same input object. Unless otherwise documented for a specific backend, extra hints that do not affect this interpretation are ignored.

A set of backends are meant to be combined with a set of Views.

Concrete backends implement _backend_adopt to accept an object and return an initialized backend instance, or None to decline it. The kind hint convention is used to disambiguate between multiple valid interpretations.

Parameters:

backend (Any) – Source value or backend being adopted by the concrete backend.
**hints (Any) – Backend-specific initialization hints.

backend_classes: ClassVar[list[type[Backend[Any]]]]¶

classmethod create(obj, **hints)[source]¶

Given a source data (obj) and a set of hints, create a backend from one of the alternatives in the class variable backend_classes.

By design this creation depends heavily on order of the classes in backend_classes. Each class is tried in the order they appear until one of them is successful, in the sense that their _backend_adopt returns an initialized instance. Sometimes multiple backend classes can handle the same input type. In that case, dispatch is guided by keyword arguments **hints, with the convention that:

if a hint named kind is given, a backend class should accept the object only if it matches that kind;
when kind matches, additional unrecognized hints may be ignored.

Parameters:

obj (Any) – Source object to represent with a registered backend.
**hints (Any) – Backend-selection and disambiguation hints.

Returns:

A backend that represents obj.

Raises:

TypeError – If no registered backend accepts obj and the hints.

Return type:

Self

unwrap()[source]¶

Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

Returns:: The backend’s most raw available representation.
Return type:: Any

class httk.core.View[BackendT: httk.core.views.backend.Backend][source]¶

A set of views allow manipulating data and state of a backend through different interfaces. Hence, creating a View from a Backend, or from another View, allows to read and operate on the data through the interface of that view, even if it is not the natural representation of the underlying data.

Important: views are always meant to reference the data and state of the same underlying object, hence, e.g.:

If a function is given an X object, and the function applies an Xvariant1View and then calls, e.g., close() via that view, the expectation should be that the original X object is also closed.
When, e.g., a TextstreamStringView is created on an already partially read stream, only the unread data will appear through that string interface.

All backends and views of the same kind of data (X) should be combined into a type union XLike that functions use to declare they support this kind of data. Such functions should start with creating a View on the passed data, giving them access to the data in a single desired format.

Views are lazy by default: construction stores only the backend, while cached_property shadows and group fills materialize presentation state on first access. Size fills to the subset served by each backend call; validate before assigning, never read a shadowed attribute from a fill, and document why a view must remain eager. The explicit coerce_view()/coerce() paths materialize via _ensure_materialized(); laziness is for pass-through use.

unwrap()[source]¶

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

Returns:: The backend’s most raw available representation.
Return type:: Any

unview()[source]¶

Return the view’s presented representation as a plain, non-View instance.

Concrete views that mimic a value type override this to shed the httk wrapper; the result may alias the view’s storage (no copy is promised). The default raises TypeError, which is the correct behavior for views that only adapt an interface and have no faithful standalone value.

Returns:: The presented value as a plain, non-View instance.
Raises:: TypeError – If this interface-only view has no standalone plain value.
Return type:: Any

httk.core.coerce(value, target)[source]¶

Coerce value strictly: return a non-View instance of the requested target or raise.

The exact string "natural" returns value unchanged (no coercion, even for a View). Otherwise the resolution of coerce_view() applies, and then: an httk View result is shed via unview() unless the requested target is itself a View class; a View result that cannot shed raises unview’s own TypeError; and the final result must satisfy isinstance(result, target) — a lossless fallback of another type (available through coerce_view()) makes strict coercion fail with TypeError. An existing non-View subtype of the target is an identity result.

Parameters:

value (Any) – Value to convert.
target (Any) – Target class, prototype instance, or the "natural" sentinel.

Returns:

A non-View instance matching the requested target.

Raises:

TypeError – If strict conversion cannot produce the requested target.

Return type:

Any

httk.core.coerce_view(value, target)[source]¶

Coerce value to a target class or prototype instance, backend-aware and best-effort.

The exact string "natural" is a documented sentinel that returns value unchanged. Otherwise, a class target is used directly and an instance target is treated as a prototype, using its type. Values already matching the target are returned unchanged — including httk Views that subclass the target, so the exact backend is retained. A target that is a View subclass is then tried directly as a view conversion of value, so any view family works without a registered coercer. Failing that, registered coercers whose declared targets match are tried in registration order, and the first non-None result wins. If none succeeds, TypeError is raised naming the value type and target. Coercion is best effort and favors lossless view wrapping; a coercer may return a lossless fallback of another type (e.g. Fraction(1, 2) for target int), and individual coercers document any deliberately lossy conversion. Callers that need a plain, exactly-typed result use coerce() instead.

Parameters:

value (Any) – Value to convert.
target (Any) – Target class, prototype instance, or the "natural" sentinel.

Returns:

The best available backend-aware conversion.

Raises:

TypeError – If no registered or direct conversion succeeds.

Return type:

Any

httk.core.unview(obj)[source]¶

Shed the httk View wrapper from obj, returning a plain instance of the presented type.

Unlike unwrap(), which goes down to the backend’s raw source representation, unview goes sideways: it removes the httk wrapper while keeping the presentation the view exposes. The result is not promised to be a copy — it may alias the view’s (or the original input’s) storage; use the target representation’s normal copy operation when independent mutation is required. A non-View input is returned unchanged. Views that only adapt an interface and have no faithful standalone value raise TypeError.

Parameters:: obj (Any) – Value or view to shed.
Returns:: The presented value without its httk view wrapper.
Raises:: TypeError – If a view has no faithful standalone value.
Return type:: Any

httk.core.unwrap(obj)[source]¶

Given a Backend or a View, return the most raw representation possible, i.e., if the backend has an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

Parameters:: obj (Any) – Value, backend, or view to unwrap.
Returns:: The most raw available representation.
Return type:: Any

httk.core¶

Submodules¶

Attributes¶

Classes¶

Functions¶

Package Contents¶