httk-core: a short tour

httk-core supplies the shared primitives of httk₂: the httk.* namespace, datastream views, and the DataLoader. Its versioned module documentation is listed in the site module directory. This notebook is executed during the docs build, so its outputs reflect the current API.

Subpackages

httk.core.subpackages reports the httk.* subpackages discovered in the current environment — the modules installed alongside httk-core.

from httk.core import subpackages

print(subpackages)

['httk.atomistic', 'httk.core', 'httk.data', 'httk.io', 'httk.optimade', 'httk.web', 'httk.workflow']

Datastream views

Datastream views present some underlying stream through a familiar Python type. A view can also wrap literal in-memory content directly — pass kind="content" so the argument is taken as the data itself rather than as a filename or URL.

TextstreamStringView is a genuine str, and BytestreamBytesView is a genuine bytes, so each can be used anywhere the plain type is expected.

from httk.core import TextstreamStringView, BytestreamBytesView

text = TextstreamStringView("hello, httk", kind="content")
print("text  :", repr(str(text)), "| is str:", isinstance(text, str))

data = BytestreamBytesView(b"\x00\x01\x02httk", kind="content")
print("bytes :", bytes(data), "| is bytes:", isinstance(data, bytes))

text  : 'hello, httk' | is str: True
bytes : b'\x00\x01\x02httk' | is bytes: True

DataLoader

DataLoader lazily reads an httk dataset file. Construction records the arguments and does no I/O; the source is read the first time .data (or .meta / .index) is accessed. A plain JSON source is exposed directly as .data.

First, write a small JSON file to a temporary path:

import json
import tempfile
from pathlib import Path

tmpdir = Path(tempfile.mkdtemp())
dataset_path = tmpdir / "elements.json"
dataset_path.write_text(json.dumps({"elements": ["Ga", "As"], "count": 2}))

print(dataset_path)

/tmp/tmp5odktxdh/elements.json

Load it by filename — the format is resolved from the .json suffix, and the parsed value appears as .data:

from httk.core import DataLoader

loader = DataLoader("elements-dataset", str(dataset_path))
print(loader.data)

{'elements': ['Ga', 'As'], 'count': 2}

The source need not be a file. With kind="content", a string is the data to parse — handy for tests and for feeding data assembled in memory:

content = json.dumps({"greeting": "hi", "value": 42})
inline = DataLoader("inline-dataset", content, kind="content")
print(inline.data)

{'greeting': 'hi', 'value': 42}