otcat 1.0.0__tar.gz

otcat-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+/bin/
+/coverage.out
+*.test
+/dist/
+__pycache__/
+*.pyc
+python/dist/
+python/build/
+python/*.egg-info/
+python/.pytest_cache/
+python/.mypy_cache/
+python/.ruff_cache/

otcat-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: otcat
+Version: 1.0.0
+Summary: Python bindings for otcat, the netcat for industrial I/O -- reads and writes Modbus TCP through the real Go core.
+Project-URL: Homepage, https://github.com/QuitOperation/otcat
+Project-URL: Go core, https://github.com/QuitOperation/otcat
+Project-URL: Documentation, https://github.com/QuitOperation/otcat/tree/main/python
+Project-URL: Issues, https://github.com/QuitOperation/otcat/issues
+Author-email: Moustafa Mahmoud Atta <MoustafaAt1a@outlook.com>
+License: MIT
+Keywords: automation,ics,industrial,modbus,ot,plc,scada
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100; extra == 'all'
+Requires-Dist: pandas>=1.5; extra == 'all'
+Requires-Dist: streamlit>=1.28; extra == 'all'
+Requires-Dist: uvicorn>=0.23; extra == 'all'
+Provides-Extra: dashboard
+Requires-Dist: streamlit>=1.28; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: uvicorn>=0.23; extra == 'fastapi'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# otcat (Python)
+
+Python bindings for [otcat](https://github.com/QuitOperation/otcat),
+the netcat for industrial I/O. This package wraps the real, compiled
+Go binary — every Modbus read and write is still executed by the same
+tested, fuzzed Go core the main project's paper describes, not a
+Python reimplementation of the protocol.
+
+```python
+from otcat import Client
+
+c = Client("127.0.0.1:502")
+v = c.read("holding:40001")
+print(v.value, v.quality, v.ts)
+
+for v in c.watch("holding:40001", interval="500ms", count=10):
+    print(v.ts, v.value)
+
+c.write("holding:40001", 100)  # confirm=True by default -- see "Write safety" below
+```
+
+## Install
+
+```sh
+pip install otcat                 # core client only, zero extra dependencies
+pip install otcat[pandas]         # + DataFrame helpers
+pip install otcat[fastapi]        # + the async client's natural home
+pip install otcat[dashboard]      # + Streamlit
+pip install otcat[all]            # everything
+```
+
+The Go binary itself ships bundled inside platform-specific wheels; if
+none is available for your platform, install it separately (`go
+install github.com/QuitOperation/otcat/cmd/otcat@latest`, or one of the
+[Cloudsmith packages](../docs/releasing.md)) and either put it on
+`$PATH` or point `OTCAT_BINARY` at it directly. See
+[`docs/packaging.md`](docs/packaging.md) for exactly how the bundled
+binary is resolved.
+
+## Write safety: one deliberate difference from the CLI
+
+The Go CLI refuses every write by default unless `--confirm` is passed
+or an interactive operator answers a y/N prompt — the right default
+for a human typing a command who might have a typo. `Client.write()`
+defaults to `confirm=True` instead, because a library call is already
+the result of a programmer's code deciding, deliberately, to write a
+specific value; there is no keystroke left to protect against. Pass
+`confirm=False` if you want the stricter behavior and are prepared to
+catch `WriteAbortedError`.
+
+## Modules
+
+| Module | What it's for |
+|---|---|
+| `otcat.Client` | Synchronous read/write/watch/dry_run — the core |
+| `otcat.aio.AsyncClient` | Same API, `asyncio`-native — FastAPI, WebSockets |
+| `otcat.pandas_ext` | `Value` lists ↔ `DataFrame`, plus a bounded `RollingBuffer` for live dashboards |
+| `otcat.alerting` | Threshold rules with debounce → callbacks, for automations and paging |
+| `otcat.audit` | Read-only OT asset discovery / device fingerprinting (never writes — see its module docstring) |
+
+## Examples
+
+See [`examples/`](examples/): a pandas time-series pull, a FastAPI
+service with a live WebSocket, a Streamlit dashboard, a threshold
+alerting script, and a read-only network audit script.
+
+## Exit codes → exceptions
+
+| Go CLI exit code | Python exception |
+|---|---|
+| 1 | `otcat.UsageError` |
+| 2 | `otcat.ConnectionError` |
+| 3 | `otcat.ProtocolError` (`.exception_code` holds the Modbus exception, e.g. `"0x02"`) |
+| 4 | `otcat.WriteAbortedError` |
+| 5 | `otcat.IOFailureError` |
+| (n/a) | `otcat.Timeout` — a Python-side watchdog, distinct from otcat's own `--timeout` |
+
+## Testing
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Every test is an integration test against a freshly spawned
+`otcat-mockplc` — see `tests/conftest.py`. Building `otcat-mockplc`
+requires a Go 1.22+ toolchain on `$PATH` at test time (the shipped
+wheel itself needs no Go toolchain to *use*, only this repo's test
+suite needs one to build its own test fixture).
+
+## License
+
+MIT — same as the Go core.

otcat-1.0.0/README.md

@@ -0,0 +1,93 @@
+# otcat (Python)
+
+Python bindings for [otcat](https://github.com/QuitOperation/otcat),
+the netcat for industrial I/O. This package wraps the real, compiled
+Go binary — every Modbus read and write is still executed by the same
+tested, fuzzed Go core the main project's paper describes, not a
+Python reimplementation of the protocol.
+
+```python
+from otcat import Client
+
+c = Client("127.0.0.1:502")
+v = c.read("holding:40001")
+print(v.value, v.quality, v.ts)
+
+for v in c.watch("holding:40001", interval="500ms", count=10):
+    print(v.ts, v.value)
+
+c.write("holding:40001", 100)  # confirm=True by default -- see "Write safety" below
+```
+
+## Install
+
+```sh
+pip install otcat                 # core client only, zero extra dependencies
+pip install otcat[pandas]         # + DataFrame helpers
+pip install otcat[fastapi]        # + the async client's natural home
+pip install otcat[dashboard]      # + Streamlit
+pip install otcat[all]            # everything
+```
+
+The Go binary itself ships bundled inside platform-specific wheels; if
+none is available for your platform, install it separately (`go
+install github.com/QuitOperation/otcat/cmd/otcat@latest`, or one of the
+[Cloudsmith packages](../docs/releasing.md)) and either put it on
+`$PATH` or point `OTCAT_BINARY` at it directly. See
+[`docs/packaging.md`](docs/packaging.md) for exactly how the bundled
+binary is resolved.
+
+## Write safety: one deliberate difference from the CLI
+
+The Go CLI refuses every write by default unless `--confirm` is passed
+or an interactive operator answers a y/N prompt — the right default
+for a human typing a command who might have a typo. `Client.write()`
+defaults to `confirm=True` instead, because a library call is already
+the result of a programmer's code deciding, deliberately, to write a
+specific value; there is no keystroke left to protect against. Pass
+`confirm=False` if you want the stricter behavior and are prepared to
+catch `WriteAbortedError`.
+
+## Modules
+
+| Module | What it's for |
+|---|---|
+| `otcat.Client` | Synchronous read/write/watch/dry_run — the core |
+| `otcat.aio.AsyncClient` | Same API, `asyncio`-native — FastAPI, WebSockets |
+| `otcat.pandas_ext` | `Value` lists ↔ `DataFrame`, plus a bounded `RollingBuffer` for live dashboards |
+| `otcat.alerting` | Threshold rules with debounce → callbacks, for automations and paging |
+| `otcat.audit` | Read-only OT asset discovery / device fingerprinting (never writes — see its module docstring) |
+
+## Examples
+
+See [`examples/`](examples/): a pandas time-series pull, a FastAPI
+service with a live WebSocket, a Streamlit dashboard, a threshold
+alerting script, and a read-only network audit script.
+
+## Exit codes → exceptions
+
+| Go CLI exit code | Python exception |
+|---|---|
+| 1 | `otcat.UsageError` |
+| 2 | `otcat.ConnectionError` |
+| 3 | `otcat.ProtocolError` (`.exception_code` holds the Modbus exception, e.g. `"0x02"`) |
+| 4 | `otcat.WriteAbortedError` |
+| 5 | `otcat.IOFailureError` |
+| (n/a) | `otcat.Timeout` — a Python-side watchdog, distinct from otcat's own `--timeout` |
+
+## Testing
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Every test is an integration test against a freshly spawned
+`otcat-mockplc` — see `tests/conftest.py`. Building `otcat-mockplc`
+requires a Go 1.22+ toolchain on `$PATH` at test time (the shipped
+wheel itself needs no Go toolchain to *use*, only this repo's test
+suite needs one to build its own test fixture).
+
+## License
+
+MIT — same as the Go core.

otcat-1.0.0/docs/packaging.md

@@ -0,0 +1,118 @@
+# Python packaging: how the Go binary gets into the wheel
+
+## What's real vs. what's the plan
+
+This source tree ships one bundled binary,
+`python/otcat/_bin/otcat-linux-amd64`, built directly from this
+project's own Go source in this environment. It is what makes the
+Python test suite an actual integration test rather than a mock of a
+mock: `Client()` with no arguments resolves to that real binary and
+talks to a real `otcat-mockplc` over a real socket (see
+`tests/conftest.py`).
+
+Shipping *one* platform's binary in a source checkout is fine for
+development. Shipping it on PyPI is not — a `pip install otcat` on
+macOS or Windows would silently get a Linux binary that can't execute.
+The correct end state is **platform-specific wheels**, each containing
+only the one binary that platform needs, which is what the CI
+pipeline below is designed to produce. It has not been run for real
+end-to-end (that requires PyPI publish credentials this project's
+build environment doesn't have) — the Linux leg has been verified
+directly (build binary → build wheel → install wheel → run tests
+against it, all in this repo's own CI-equivalent commands); the
+macOS/Windows legs follow the identical, mechanical pattern.
+
+## The pipeline
+
+```
+GoReleaser (.goreleaser.yaml)
+  --> dist/otcat_<os>_<arch>/otcat[.exe]     (already verified, see docs/releasing.md)
+        |
+        v
+copy each into python/otcat/_bin/otcat-<os>-<arch>[.exe]
+        |
+        v
+build ONE wheel per (os, arch) pair, each containing only its own binary,
+tagged with the right platform tag (manylinux_x86_64, macosx_11_0_arm64,
+win_amd64, ...) so pip's own platform matching does the rest
+        |
+        v
+twine upload dist/*.whl  (+ one sdist, which ships NO binary and falls
+                           back to $PATH / OTCAT_BINARY at import time --
+                           see otcat/_binary.py)
+```
+
+## Why platform-specific wheels instead of one universal wheel
+
+A wheel is not allowed to contain multiple incompatible native
+binaries and pick one at install time — `pip` picks the *wheel* based
+on platform tags before anything inside it runs. The standard,
+widely-used pattern (the same one `ruff`, ripgrep's Python wrapper, and
+many other Go/Rust-backed Python tools use) is: build the native
+binary once per target with the language's own cross-compiler (Go's
+`GOOS`/`GOARCH`, already free — see `.goreleaser.yaml`), then build a
+separate wheel per target that embeds just that one binary and
+declares the matching platform tag.
+
+## GitHub Actions sketch (`python-release.yml`, not yet added to
+## `.github/workflows/` -- add it once PyPI publishing is actually
+## wanted, so a stray push can't trigger a broken/premature publish)
+
+```yaml
+name: python-release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  build-wheels:
+    strategy:
+      matrix:
+        include:
+          - { os: ubuntu-latest,  goos: linux,   goarch: amd64, tag: manylinux_2_17_x86_64 }
+          - { os: ubuntu-latest,  goos: linux,   goarch: arm64, tag: manylinux_2_17_aarch64 }
+          - { os: macos-latest,   goos: darwin,  goarch: amd64, tag: macosx_11_0_x86_64 }
+          - { os: macos-latest,   goos: darwin,  goarch: arm64, tag: macosx_11_0_arm64 }
+          - { os: windows-latest, goos: windows, goarch: amd64, tag: win_amd64 }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with: { go-version: "1.22" }
+      - run: |
+          ext=""; [ "${{ matrix.goos }}" = "windows" ] && ext=".exe"
+          GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} \
+            go build -ldflags "-s -w" \
+            -o python/otcat/_bin/otcat-${{ matrix.goos }}-${{ matrix.goarch }}$ext \
+            ./cmd/otcat
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install build
+      - working-directory: python
+        run: python -m build --wheel -C--build-option=--plat-name -C--build-option=${{ matrix.tag }}
+      - uses: actions/upload-artifact@v4
+        with: { name: wheel-${{ matrix.tag }}, path: python/dist/*.whl }
+
+  publish:
+    needs: build-wheels
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { path: dist, merge-multiple: true }
+      - run: pip install twine
+      - run: twine upload dist/*.whl
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+```
+
+## Before actually publishing to PyPI
+
+- Confirm the name `otcat` is available on PyPI (not checked from this
+  environment — no network path to pypi.org's search from here that
+  wouldn't also require deciding on a fallback name in the same
+  breath; do this manually before the first publish).
+- Decide the sdist's behavior deliberately: it ships no binary at all
+  (by design, per the pipeline above), so `pip install otcat` from
+  source on a platform with no wheel falls straight to `_binary.py`'s
+  `$PATH`/`OTCAT_BINARY` search. Document that clearly in the PyPI
+  project description, not just in this file.

otcat-1.0.0/examples/alerting_example.py

@@ -0,0 +1,47 @@
+"""Threshold alerting: page/log/trigger an automation when a tank
+level crosses a limit, with debounce so noise near the threshold
+doesn't spam.
+
+    otcat-mockplc --addr 127.0.0.1:15020 &
+    python examples/alerting_example.py 127.0.0.1:15020
+"""
+import sys
+
+from otcat import Client
+from otcat.alerting import AlertEngine
+
+
+def page_oncall(value) -> None:
+    print(f"[ALERT] {value.address} = {value.value} at {value.ts} -- paging on-call")
+
+
+def clear_alert(value) -> None:
+    print(f"[CLEAR] {value.address} = {value.value} at {value.ts} -- back to normal")
+
+
+def trigger_automation(value) -> None:
+    print(f"[AUTOMATION] {value.address} crossed threshold -- running downstream action")
+
+
+def main() -> None:
+    endpoint = sys.argv[1] if len(sys.argv) > 1 else "127.0.0.1:15020"
+    client = Client(endpoint, raw_address=True)
+
+    engine = AlertEngine(client)
+    engine.threshold(
+        "holding:0", above=25_00,  # tank level is x100 fixed point; 25.00%
+        on_trigger=page_oncall, on_clear=clear_alert, debounce=3,
+        name="tank-high",
+    )
+    engine.threshold(
+        "holding:0", above=21_00,
+        on_trigger=trigger_automation, debounce=2,
+        name="tank-automation-threshold",
+    )
+
+    print(f"watching {endpoint} holding:0, polling every 500ms (Ctrl+C to stop)")
+    engine.run(interval_seconds=0.5)
+
+
+if __name__ == "__main__":
+    main()

otcat-1.0.0/examples/audit_example.py

@@ -0,0 +1,40 @@
+"""A read-only asset audit: fingerprint a device, then sweep a table
+range and report which addresses respond. Never writes -- see
+otcat.audit's module docstring for why that's a permanent property of
+this module, not a flag you can turn off.
+
+Only run this against equipment you are authorized to test.
+
+    otcat-mockplc --addr 127.0.0.1:15020 &
+    python examples/audit_example.py 127.0.0.1:15020
+"""
+import sys
+
+from otcat import Client
+from otcat.audit import fingerprint, scan_range
+
+
+def main() -> None:
+    endpoint = sys.argv[1] if len(sys.argv) > 1 else "127.0.0.1:15020"
+    client = Client(endpoint, raw_address=True, timeout=2.0)
+
+    print(f"fingerprinting {endpoint} ...")
+    fp = fingerprint(client, samples=20)
+    if not fp.reachable:
+        print("device unreachable")
+        return
+    print(f"  reachable: {fp.reachable}")
+    print(f"  tables responsive: {fp.tables_responsive}")
+    print(f"  latency p50={fp.latency_ms_p50:.2f}ms p99={fp.latency_ms_p99:.2f}ms "
+          f"({fp.samples} samples)")
+
+    print()
+    print("scanning holding:0..49 ...")
+    report = scan_range(client, "holding", start=0, count=50, delay_seconds=0.0)
+    print("  " + report.summary())
+    print(f"  responsive addresses: {report.responsive_addresses[:10]}"
+          f"{' ...' if len(report.responsive_addresses) > 10 else ''}")
+
+
+if __name__ == "__main__":
+    main()

otcat-1.0.0/examples/fastapi_service.py

@@ -0,0 +1,74 @@
+"""A minimal FastAPI service exposing a Modbus device over HTTP/WebSocket.
+
+    pip install otcat[fastapi]
+    otcat-mockplc --addr 127.0.0.1:15020 &
+    OTCAT_ENDPOINT=127.0.0.1:15020 uvicorn fastapi_service:app --reload
+
+Then:
+    curl localhost:8000/read/holding:100?raw_address=true
+    curl -X POST localhost:8000/write -d '{"spec":"holding:100","value":42,"raw_address":true}' -H 'content-type: application/json'
+    websocat ws://localhost:8000/watch/holding:0?raw_address=true&interval=500ms
+
+This intentionally does not add its own write-confirmation UI/flow on
+top of otcat's -- see otcat.Client's docstring on why the library
+defaults to confirm=True. If you're building a service that lets a
+remote caller trigger writes, put your own authorization and
+confirmation step in *this* layer (the FastAPI app), since the network
+boundary that actually needs protecting is "who can call this HTTP
+endpoint at all," which is entirely this app's responsibility, not
+otcat's.
+"""
+import os
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from pydantic import BaseModel
+
+from otcat import ProtocolError
+from otcat import ConnectionError as OtcatConnectionError
+from otcat.aio import AsyncClient
+
+ENDPOINT = os.environ.get("OTCAT_ENDPOINT", "127.0.0.1:15020")
+
+app = FastAPI(title="otcat FastAPI example")
+
+
+class WriteRequest(BaseModel):
+    spec: str
+    value: str
+    raw_address: bool = False
+    confirm: bool = True
+
+
+@app.get("/read/{spec:path}")
+async def read(spec: str, raw_address: bool = False):
+    client = AsyncClient(ENDPOINT, raw_address=raw_address)
+    try:
+        v = await client.read(spec)
+    except ProtocolError as e:
+        return {"error": str(e), "exception_code": e.exception_code}
+    except OtcatConnectionError as e:
+        return {"error": str(e)}
+    return {"address": v.address, "value": v.value, "quality": v.quality, "ts": v.ts.isoformat()}
+
+
+@app.post("/write")
+async def write(req: WriteRequest):
+    client = AsyncClient(ENDPOINT, raw_address=req.raw_address)
+    try:
+        await client.write(req.spec, req.value, confirm=req.confirm)
+    except Exception as e:
+        return {"ok": False, "error": str(e)}
+    return {"ok": True}
+
+
+@app.websocket("/watch/{spec:path}")
+async def watch(websocket: WebSocket, spec: str, raw_address: bool = False, interval: str = "1s"):
+    await websocket.accept()
+    client = AsyncClient(ENDPOINT, raw_address=raw_address)
+    try:
+        async for v in client.watch(spec, interval=interval):
+            await websocket.send_json(
+                {"address": v.address, "value": v.value, "quality": v.quality, "ts": v.ts.isoformat()}
+            )
+    except WebSocketDisconnect:
+        pass

otcat-1.0.0/examples/pandas_quickstart.py

@@ -0,0 +1,35 @@
+"""Pull a live register into pandas and compute rolling statistics --
+the shape of a lot of predictive-maintenance and data-science work:
+get real sensor data into a DataFrame with the least possible glue code.
+
+Run against otcat-mockplc for a no-hardware demo:
+    otcat-mockplc --addr 127.0.0.1:15020 &
+    python examples/pandas_quickstart.py 127.0.0.1:15020
+"""
+import sys
+
+from otcat import Client
+from otcat.pandas_ext import watch_df
+
+
+def main() -> None:
+    endpoint = sys.argv[1] if len(sys.argv) > 1 else "127.0.0.1:15020"
+    client = Client(endpoint, raw_address=True)
+
+    print(f"pulling 30 samples of holding:0 from {endpoint} ...")
+    df = watch_df(client, "holding:0", count=30, interval="200ms")
+
+    # holding:0 on otcat-mockplc is a tank level, x100 fixed point
+    df["percent"] = df["value"] / 100.0
+
+    print(df[["address", "percent", "quality"]].tail(10))
+    print()
+    print("rolling 5-sample mean:")
+    print(df["percent"].rolling(5).mean().tail(10))
+    print()
+    print(f"min={df['percent'].min():.2f}%  max={df['percent'].max():.2f}%  "
+          f"mean={df['percent'].mean():.2f}%  std={df['percent'].std():.3f}")
+
+
+if __name__ == "__main__":
+    main()

otcat-1.0.0/examples/streamlit_dashboard.py

@@ -0,0 +1,52 @@
+"""A live dashboard for one register.
+
+    pip install otcat[dashboard]
+    otcat-mockplc --addr 127.0.0.1:15020 &
+    streamlit run streamlit_dashboard.py
+"""
+import time
+
+import pandas as pd
+import streamlit as st
+
+from otcat import Client
+from otcat.pandas_ext import RollingBuffer
+
+st.set_page_config(page_title="otcat live dashboard", layout="wide")
+st.title("otcat live dashboard")
+
+endpoint = st.sidebar.text_input("Modbus endpoint", "127.0.0.1:15020")
+spec = st.sidebar.text_input("Address spec", "holding:0")
+raw_address = st.sidebar.checkbox("--raw-address", value=True)
+window = st.sidebar.slider("Rolling window (samples)", 10, 500, 100)
+interval_ms = st.sidebar.slider("Poll interval (ms)", 100, 2000, 500)
+
+if "buffer" not in st.session_state or st.session_state.get("_spec") != spec:
+    st.session_state.buffer = RollingBuffer(maxlen=window)
+    st.session_state._spec = spec
+
+placeholder = st.empty()
+run = st.sidebar.toggle("Running", value=True)
+
+if run:
+    client = Client(endpoint, raw_address=raw_address, timeout=2.0)
+    try:
+        v = client.read(spec)
+        st.session_state.buffer.push(v)
+    except Exception as e:
+        st.sidebar.error(str(e))
+
+    df = st.session_state.buffer.to_dataframe()
+    with placeholder.container():
+        col1, col2, col3 = st.columns(3)
+        if not df.empty:
+            col1.metric("latest", df["value"].iloc[-1])
+            col2.metric("mean", f"{pd.to_numeric(df['value'], errors='coerce').mean():.2f}")
+            col3.metric("quality", df["quality"].iloc[-1])
+            st.line_chart(df["value"])
+            st.dataframe(df.tail(20), use_container_width=True)
+        else:
+            st.info("waiting for first reading...")
+
+    time.sleep(interval_ms / 1000)
+    st.rerun()

otcat-1.0.0/otcat/__init__.py

@@ -0,0 +1,56 @@
+"""otcat: Python bindings for the otcat Go core.
+
+A thin, typed wrapper around the real otcat/otc binary -- every read
+and write in this package is executed by the same tested, fuzzed Go
+Modbus TCP client the accompanying paper describes, not a Python
+reimplementation of the protocol. See client.py's module docstring for
+why that's a subprocess boundary rather than a cgo/ctypes one.
+
+Quick start::
+
+    from otcat import Client
+
+    c = Client("127.0.0.1:502")
+    v = c.read("holding:40001")
+    print(v.value, v.quality)
+
+    for v in c.watch("holding:40001", interval="500ms", count=10):
+        print(v.ts, v.value)
+
+    c.write("holding:40001", 100)  # confirm=True by default in the library
+
+Optional extras (install with e.g. ``pip install otcat[pandas]``):
+
+- ``otcat.pandas_ext`` -- DataFrame conversion, a rolling-window buffer
+- ``otcat.alerting`` -- threshold rules with debounce, for automations
+- ``otcat.audit`` -- read-only OT asset discovery / fingerprinting
+- ``otcat.aio`` -- asyncio client for FastAPI and friends
+"""
+from .client import Client
+from .exceptions import (
+    ConnectionError,
+    IOFailureError,
+    OtcatBinaryNotFoundError,
+    OtcatError,
+    ProtocolError,
+    Timeout,
+    UsageError,
+    WriteAbortedError,
+)
+from .models import Value, WritePlan
+
+__all__ = [
+    "Client",
+    "Value",
+    "WritePlan",
+    "OtcatError",
+    "OtcatBinaryNotFoundError",
+    "UsageError",
+    "ConnectionError",
+    "ProtocolError",
+    "WriteAbortedError",
+    "IOFailureError",
+    "Timeout",
+]
+
+__version__ = "1.0.0"