httk-core: a short tour

httk-core supplies the shared primitives of httk₂: the httk.* namespace, datastream views, and the DatasetLoader. 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.

Core module layout

The public namespace is split across independently installable module distributions. This notebook uses httk-core, whose public API is grouped into subpackages such as httk.core.datastream.

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.datastream 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

DatasetLoader

DatasetLoader 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/tmp7usiq5ip/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 DatasetLoader

loader = DatasetLoader("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 = DatasetLoader("inline-dataset", content, kind="content")
print(inline.data)

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