{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# httk-core: a short tour\n",
    "\n",
    "`httk-core` supplies the shared primitives of *httk\u2082*: 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."
   ],
   "id": "cec9b4583"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Subpackages\n",
    "\n",
    "`httk.core.subpackages` reports the `httk.*` subpackages discovered in the current environment \u2014 the modules installed alongside httk-core."
   ],
   "id": "ca837cce7"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from httk.core import subpackages\n",
    "\n",
    "print(subpackages)"
   ],
   "id": "cc1ec15d9"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Datastream views\n",
    "\n",
    "Datastream *views* present some underlying stream through a familiar Python type. A view can also wrap literal in-memory content directly \u2014 pass `kind=\"content\"` so the argument is taken as the data itself rather than as a filename or URL.\n",
    "\n",
    "`TextstreamStringView` is a genuine `str`, and `BytestreamBytesView` is a genuine `bytes`, so each can be used anywhere the plain type is expected."
   ],
   "id": "c5ce5b713"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from httk.core import TextstreamStringView, BytestreamBytesView\n",
    "\n",
    "text = TextstreamStringView(\"hello, httk\", kind=\"content\")\n",
    "print(\"text  :\", repr(str(text)), \"| is str:\", isinstance(text, str))\n",
    "\n",
    "data = BytestreamBytesView(b\"\\x00\\x01\\x02httk\", kind=\"content\")\n",
    "print(\"bytes :\", bytes(data), \"| is bytes:\", isinstance(data, bytes))"
   ],
   "id": "c9c504ead"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## DataLoader\n",
    "\n",
    "`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`.\n",
    "\n",
    "First, write a small JSON file to a temporary path:"
   ],
   "id": "c09ee01c8"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "import tempfile\n",
    "from pathlib import Path\n",
    "\n",
    "tmpdir = Path(tempfile.mkdtemp())\n",
    "dataset_path = tmpdir / \"elements.json\"\n",
    "dataset_path.write_text(json.dumps({\"elements\": [\"Ga\", \"As\"], \"count\": 2}))\n",
    "\n",
    "print(dataset_path)"
   ],
   "id": "ca3cab92c"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Load it by filename \u2014 the format is resolved from the `.json` suffix, and the parsed value appears as `.data`:"
   ],
   "id": "c3b794e5c"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from httk.core import DataLoader\n",
    "\n",
    "loader = DataLoader(\"elements-dataset\", str(dataset_path))\n",
    "print(loader.data)"
   ],
   "id": "c6fd28faf"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The source need not be a file. With `kind=\"content\"`, a string *is* the data to parse \u2014 handy for tests and for feeding data assembled in memory:"
   ],
   "id": "c1eed2422"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "content = json.dumps({\"greeting\": \"hi\", \"value\": 42})\n",
    "inline = DataLoader(\"inline-dataset\", content, kind=\"content\")\n",
    "print(inline.data)"
   ],
   "id": "c50c2b467"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}