{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Command Line Examples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Interface"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [],
   "source": "import json\nimport math\nimport socket\nimport sys\nimport threading\nimport urllib.parse\nfrom http.server import BaseHTTPRequestHandler, HTTPServer\n\nimport epicsarchiver.retrieval.EPICSEvent_pb2 as _ee\nfrom epicsarchiver.retrieval.EPICSEvent_pb2 import SCALAR_DOUBLE, PayloadInfo, ScalarDouble\nfrom epicsarchiver.retrieval.pb import escape_bytes\n\n_YEAR = 2026\n_BASE_SECS = 8_640_000\n\n# PV names returned by the mocked getMatchingPVs (search) endpoint.\n_SEARCH_RESULTS = [\"EXAMPLE:TEMPERATURE\", \"EXAMPLE:TEMPERATURE2\", \"EXAMPLE:PRESSURE\"]\n\n\ndef _make_doc_events(n=30):\n    return [\n        ScalarDouble(\n            secondsintoyear=_BASE_SECS + i * 10,\n            nano=int(abs(math.sin(i)) * 1_000_000_000),\n            val=28.0 + 0.5 * math.sin(i * 0.4),\n            severity=1,\n            status=4,\n            fieldvalues=[\n                _ee.FieldValue(name=\"EGU\", val=\"degC\"),\n                _ee.FieldValue(name=\"PREC\", val=\"2\"),\n            ],\n        )\n        for i in range(n)\n    ]\n\n\ndef _make_pb(pvname):\n    events = _make_doc_events()\n    info = PayloadInfo(type=SCALAR_DOUBLE, pvname=pvname, year=_YEAR)\n    info_bytes = escape_bytes(info.SerializeToString())\n    events_bytes = b\"\\n\".join(escape_bytes(e.SerializeToString()) for e in events)\n    return info_bytes + b\"\\n\" + events_bytes\n\n\nclass _MockHandler(BaseHTTPRequestHandler):\n    def do_GET(self):\n        parsed = urllib.parse.urlparse(self.path)\n        qs = urllib.parse.parse_qs(parsed.query)\n        if \"getMatchingPVs\" in parsed.path:\n            # Search endpoint: return a JSON list of PV names.\n            body = json.dumps(_SEARCH_RESULTS).encode()\n            content_type = \"application/json\"\n        else:\n            # Data endpoint: return PB-encoded events for the requested PV.\n            pv = qs.get(\"pv\", [\"unknown\"])[0]\n            body = _make_pb(pv)\n            content_type = \"application/octet-stream\"\n        self.send_response(200)\n        self.send_header(\"Content-Type\", content_type)\n        self.send_header(\"Content-Length\", str(len(body)))\n        self.end_headers()\n        self.wfile.write(body)\n\n    def log_message(self, *args):\n        pass  # silence server logs\n\n\nclass _ReusableHTTPServer(HTTPServer):\n    allow_reuse_address = True\n\n\n_mock_server = _ReusableHTTPServer((\"localhost\", 17668), _MockHandler)\n_server_thread = threading.Thread(target=_mock_server.serve_forever, daemon=True)\n_server_thread.start()"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "!arch-retrieval get --help"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": "!arch-retrieval --hostname localhost get EXAMPLE:TEMPERATURE"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "!arch-retrieval --hostname localhost get EXAMPLE:TEMPERATURE -p min -b 5"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "!arch-retrieval --hostname localhost get EXAMPLE:TEMPERATURE -p ncount"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "!arch-retrieval --hostname localhost get EXAMPLE:TEMPERATURE2 EXAMPLE:TEMPERATURE3  -s 2024-12-01T12:00:00 -e 2024-12-16T12:10:10.10 -p MEDIAN -b 6000"
  },
  {
   "cell_type": "markdown",
   "source": "## Export Data\n\nThe `export` command writes a single PV's data to stdout in a machine-readable format: `json` (default), `csv`, `arrow`, `parquet`, or `pb` (the raw Archiver Appliance protobuf). The `csv`/`arrow`/`parquet` formats require the `[polars]` extra. Redirect stdout to a file to save the result.",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "source": "!arch-retrieval export --help",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "code",
   "source": "!arch-retrieval --hostname localhost export --format csv EXAMPLE:TEMPERATURE | head",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "code",
   "source": "!arch-retrieval --hostname localhost export --format pb EXAMPLE:TEMPERATURE > example.pb",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "source": "## Search for PV Names\n\nThe `search` command looks up PV names matching a regex pattern. Optionally pass `-s`/`-e` to only return PVs that recorded data in a time range, and `-l` to change the result limit.",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "source": "!arch-retrieval search --help",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "code",
   "source": "!arch-retrieval --hostname localhost search \"EXAMPLE:.*\"",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "source": "## Read a Local PB File\n\nThe `read-pb` command displays the events stored in a local Archiver Appliance `.pb` file (for example one written by `export --format pb` above) as a table, without contacting a server.",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "source": "!arch-retrieval read-pb --help",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "code",
   "source": "!arch-retrieval --hostname localhost read-pb example.pb",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [],
   "source": "import os\n\n_mock_server.shutdown()\nif os.path.exists(\"example.pb\"):\n    os.remove(\"example.pb\")"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "jupyter",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.14.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}