data-hub-watcher 0.1.0__tar.gz

data_hub_watcher-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arcadia Science
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data_hub_watcher-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: data-hub-watcher
+Version: 0.1.0
+Summary: File-watcher agent for lab instrument PCs that ingests data into the Arcadia Science Data Hub.
+Author-email: Arcadia Science <engineering@arcadiascience.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Arcadia-Science/data-hub
+Project-URL: Documentation, https://github.com/Arcadia-Science/data-hub/blob/production/docs/guides/installing-a-watcher.md
+Project-URL: Repository, https://github.com/Arcadia-Science/data-hub
+Project-URL: Issues, https://github.com/Arcadia-Science/data-hub/issues
+Keywords: arcadia,data-hub,lab,instruments,watcher,uploader
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.2.1
+Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic>=2.11.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: windows-service
+Requires-Dist: pywin32; extra == "windows-service"
+Dynamic: license-file
+
+# data-hub-watcher
+
+A file-watcher agent that runs on lab instrument PCs and uploads new files to the [Arcadia Science Data Hub](https://github.com/Arcadia-Science/data-hub). It groups files into runs, retries uploads, sends heartbeats, and can optionally run as a Windows service.
+
+## Install
+
+```sh
+uv tool install data-hub-watcher
+```
+
+The CLI is published as the `data-hub-watcher` script. After installing, walk through the interactive setup wizard:
+
+```sh
+data-hub-watcher init
+```
+
+## Usage
+
+```sh
+data-hub-watcher watch          # start watching for files
+data-hub-watcher self-update    # check for and apply package updates
+data-hub-watcher service install  # Windows: install as a service
+```
+
+See [the operator guide](https://github.com/Arcadia-Science/data-hub/blob/main/docs/guides/installing-a-watcher.md) for the full setup walk-through, configuration reference, and troubleshooting.
+
+## License
+
+MIT — see the `LICENSE` file bundled with the wheel.

data_hub_watcher-0.1.0/README.md

@@ -0,0 +1,29 @@
+# data-hub-watcher
+
+A file-watcher agent that runs on lab instrument PCs and uploads new files to the [Arcadia Science Data Hub](https://github.com/Arcadia-Science/data-hub). It groups files into runs, retries uploads, sends heartbeats, and can optionally run as a Windows service.
+
+## Install
+
+```sh
+uv tool install data-hub-watcher
+```
+
+The CLI is published as the `data-hub-watcher` script. After installing, walk through the interactive setup wizard:
+
+```sh
+data-hub-watcher init
+```
+
+## Usage
+
+```sh
+data-hub-watcher watch          # start watching for files
+data-hub-watcher self-update    # check for and apply package updates
+data-hub-watcher service install  # Windows: install as a service
+```
+
+See [the operator guide](https://github.com/Arcadia-Science/data-hub/blob/main/docs/guides/installing-a-watcher.md) for the full setup walk-through, configuration reference, and troubleshooting.
+
+## License
+
+MIT — see the `LICENSE` file bundled with the wheel.

data_hub_watcher-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "data-hub-watcher"
+version = "0.1.0"
+description = "File-watcher agent for lab instrument PCs that ingests data into the Arcadia Science Data Hub."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Arcadia Science", email = "engineering@arcadiascience.com" },
+]
+keywords = ["arcadia", "data-hub", "lab", "instruments", "watcher", "uploader"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: System :: Filesystems",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "click>=8.2.1",
+    "packaging>=24.0",
+    "pydantic>=2.11.9",
+    "pyyaml>=6.0",
+    "python-dotenv>=1.0",
+    "watchdog>=4.0.0",
+]
+
+[project.optional-dependencies]
+windows-service = ["pywin32"]
+
+[project.urls]
+Homepage = "https://github.com/Arcadia-Science/data-hub"
+# Operator-facing install + auto-update guide — what someone landing on
+# the PyPI page actually needs. The developer-facing `docs/watcher.md`
+# describes the editable-checkout workflow and is reachable from the
+# repository link below.
+Documentation = "https://github.com/Arcadia-Science/data-hub/blob/production/docs/guides/installing-a-watcher.md"
+Repository = "https://github.com/Arcadia-Science/data-hub"
+Issues = "https://github.com/Arcadia-Science/data-hub/issues"
+
+# Test-only deps live in a PEP 735 group instead of `[project].dependencies`
+# so the published wheel does not advertise `data-hub-shared` as a runtime
+# requirement — the integration suite imports it (see `watcher/tests/integration/*`)
+# but no runtime watcher code does, and the package is not published to PyPI.
+# `uv sync` includes this group by default for local development.
+[dependency-groups]
+test = ["data-hub-shared"]
+
+[tool.uv.sources]
+data-hub-shared = { workspace = true }
+
+[project.scripts]
+data-hub-watcher = "data_hub_watcher.cli:cli"
+
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

data_hub_watcher-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

data_hub_watcher-0.1.0/src/data_hub_watcher/api_client.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+import logging
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+import requests
+
+from data_hub_watcher.models import (
+    ApiErrorDetail,
+    ConfigChecksumResponse,
+    EventsResponse,
+    FileResponse,
+    HeartbeatResponse,
+    InstrumentDetailResponse,
+    InstrumentResponse,
+    PresignedUploadResponse,
+    RegisterWatcherResponse,
+    RunDetailResponse,
+    RunResponse,
+    UploadQueueResponse,
+    WatcherUpdateInfoResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ApiError(Exception):
+    """Raised when the Data Hub API returns a non-2xx response."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 0,
+        detail: ApiErrorDetail | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+
+
+DEFAULT_TIMEOUT: tuple[float, float] = (5, 30)  # (connect, read) seconds
+
+
+class DataHubClient:
+    """HTTP client for the Data Hub API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: tuple[float, float] = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        # A persistent session reuses TCP connections across requests, which
+        # matters when the watcher is long-running and chatting with the API
+        # every heartbeat interval.
+        self._session = requests.Session()
+
+        # Allow the API key to be passed explicitly (e.g. during `init`) or
+        # fall back to the environment variable for normal operation.
+        key = api_key or os.environ.get("DATA_HUB_API_KEY", "")
+        if key:
+            self._session.headers["Authorization"] = f"Bearer {key}"
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def _handle_error(self, resp: requests.Response) -> None:
+        """Parse an error body and raise `ApiError`."""
+        detail: ApiErrorDetail | None = None
+        try:
+            body = resp.json()
+            if "error" in body:
+                detail = ApiErrorDetail.model_validate(body["error"])
+                msg = detail.message
+            else:
+                msg = resp.text
+        except Exception:
+            msg = resp.text
+        raise ApiError(msg, status_code=resp.status_code, detail=detail)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> requests.Response:
+        try:
+            resp = self._session.request(
+                method, self._url(path), json=json, params=params, timeout=self._timeout
+            )
+        except requests.ConnectionError as exc:
+            raise ApiError(f"Connection error: {exc}") from exc
+        except requests.Timeout as exc:
+            raise ApiError(f"Request timed out: {exc}") from exc
+
+        if not resp.ok:
+            self._handle_error(resp)
+        return resp
+
+    # ------------------------------------------------------------------
+    # Instruments
+    # ------------------------------------------------------------------
+
+    def list_instruments(self) -> list[InstrumentResponse]:
+        resp = self._request("GET", "/instruments")
+        return [InstrumentResponse.model_validate(item) for item in resp.json()]
+
+    def create_instrument(self, id: str, display_name: str | None = None) -> InstrumentResponse:
+        payload: dict[str, Any] = {"id": id}
+        if display_name:
+            payload["display_name"] = display_name
+        resp = self._request("POST", "/instruments", json=payload)
+        return InstrumentResponse.model_validate(resp.json())
+
+    def get_instrument(self, instrument_id: str) -> InstrumentDetailResponse:
+        resp = self._request("GET", f"/instruments/{instrument_id}")
+        return InstrumentDetailResponse.model_validate(resp.json())
+
+    # ------------------------------------------------------------------
+    # Watchers
+    # ------------------------------------------------------------------
+
+    def register_watcher(
+        self,
+        instrument_id: str,
+        hostname: str | None = None,
+        os_info: str | None = None,
+    ) -> RegisterWatcherResponse:
+        payload: dict[str, Any] = {"instrument_id": instrument_id}
+        if hostname:
+            payload["hostname"] = hostname
+        if os_info:
+            payload["os_info"] = os_info
+        resp = self._request("POST", "/watchers/register", json=payload)
+        return RegisterWatcherResponse.model_validate(resp.json())
+
+    def push_config(
+        self, watcher_id: str, config_yaml: str, checksum: str
+    ) -> ConfigChecksumResponse:
+        resp = self._request(
+            "PUT",
+            f"/watchers/{watcher_id}/config",
+            json={"config_yaml": config_yaml, "config_checksum": checksum},
+        )
+        return ConfigChecksumResponse.model_validate(resp.json())
+
+    def get_config_checksum(self, watcher_id: str) -> ConfigChecksumResponse | None:
+        """Return the remote checksum, or `None` if no config has been pushed.
+
+        A 404 is expected for newly registered watchers that haven't pushed
+        config yet — it is not an error condition.
+        """
+        try:
+            resp = self._request("GET", f"/watchers/{watcher_id}/config-checksum")
+            return ConfigChecksumResponse.model_validate(resp.json())
+        except ApiError as exc:
+            if exc.status_code == 404:
+                return None
+            raise
+
+    def send_heartbeat(self, watcher_id: str, payload: dict[str, Any]) -> HeartbeatResponse:
+        resp = self._request("POST", f"/watchers/{watcher_id}/heartbeat", json=payload)
+        return HeartbeatResponse.model_validate(resp.json())
+
+    def send_events(self, watcher_id: str, events: list[dict[str, Any]]) -> EventsResponse:
+        resp = self._request("POST", f"/watchers/{watcher_id}/events", json={"events": events})
+        return EventsResponse.model_validate(resp.json())
+
+    def get_update_info(self, watcher_id: str) -> WatcherUpdateInfoResponse:
+        """Fetch server-reported watcher release metadata.
+
+        Used by `self-update` and the in-process updater to decide whether
+        the running watcher should upgrade itself.
+        """
+        resp = self._request("GET", f"/watchers/{watcher_id}/update-check")
+        return WatcherUpdateInfoResponse.model_validate(resp.json())
+
+    # ------------------------------------------------------------------
+    # Runs
+    # ------------------------------------------------------------------
+
+    def report_run(self, instrument_id: str, run_data: dict[str, Any]) -> RunResponse:
+        resp = self._request("POST", f"/instruments/{instrument_id}/runs", json=run_data)
+        return RunResponse.model_validate(resp.json())
+
+    def update_run(
+        self, instrument_id: str, run_id: str, data: dict[str, Any]
+    ) -> RunDetailResponse:
+        resp = self._request("PATCH", f"/instruments/{instrument_id}/runs/{run_id}", json=data)
+        return RunDetailResponse.model_validate(resp.json())
+
+    # ------------------------------------------------------------------
+    # Upload queue / files
+    # ------------------------------------------------------------------
+
+    def get_upload_queue(self, watcher_id: str) -> UploadQueueResponse:
+        resp = self._request("GET", f"/watchers/{watcher_id}/upload-queue")
+        return UploadQueueResponse.model_validate(resp.json())
+
+    def request_upload_url(
+        self,
+        instrument_id: str,
+        run_id: str,
+        filename: str,
+        content_type: str | None = None,
+        size_bytes: int | None = None,
+        file_created_at_ts: float | None = None,
+    ) -> PresignedUploadResponse:
+        payload: dict[str, Any] = {"filename": filename}
+        if content_type:
+            payload["content_type"] = content_type
+        if size_bytes is not None:
+            payload["size_bytes"] = size_bytes
+        if file_created_at_ts:
+            payload["file_created_at"] = datetime.fromtimestamp(
+                file_created_at_ts, tz=timezone.utc
+            ).isoformat()
+        resp = self._request(
+            "POST",
+            f"/instruments/{instrument_id}/runs/{run_id}/request-upload-url",
+            json=payload,
+        )
+        return PresignedUploadResponse.model_validate(resp.json())
+
+    def mark_file_uploaded(self, file_id: int, s3_info: dict[str, Any]) -> FileResponse:
+        resp = self._request("PATCH", f"/files/{file_id}", json=s3_info)
+        return FileResponse.model_validate(resp.json())