farsounder 0.1.0__tar.gz

farsounder-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: farsounder
+Version: 0.1.0
+Summary: Python client to communicate with FarSounder's ARGOS sensors
+Author-email: FarSounder Software Team <sw@farsounder.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: httpx
+Requires-Dist: protobuf
+Requires-Dist: pyzmq
+
+# SDK Client for live FarSounder data
+
+Python client to communicate with SonaSoft via API.
+
+## Usage
+
+Clone locally and install (uv add .) or install from pypi like:
+
+```
+uv add farsounder
+```
+(or use pip, etc)
+
+Then - for example to subscribe to `TargetData` messages:
+
+```python
+import asyncio
+
+from farsounder import config, requests, subscriber
+from farsounder.proto import nav_api_pb2
+
+
+async def main() -> None:
+    cfg = config.build_config(
+        host="127.0.0.1",
+        subscribe=["TargetData"],
+    )
+
+    sub = subscriber.subscribe(config)
+
+    def on_targets(message: nav_api_pb2.TargetData) -> None:
+        print("Got a TargetData!")
+        print("Targets:", len(message.groups))
+
+    # Pub/Sub
+    sub.on("TargetData", on_targets)
+    await sub.start()
+
+    # Req/rep
+    settings = await requests.get_processor_settings(config)
+    print(settings)
+
+    # History data
+    history = await requests.get_history_data(
+        config,
+        latitude=41.7223,
+        longitude=-71.35,
+        radius_meters=500,
+    )
+    print(history.gridded_bottom_detections)
+
+    await asyncio.sleep(1.0)
+    await sub.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Simulated backend
+
+You can run a local simulated backend that publishes dummy messages and responds
+to request/reply calls:
+
+```
+uv run examples/simulated_backend.py
+```
+
+Note: the `examples/` directory is not installed with `uv add farsounder`.
+Clone the repo to run the examples locally.
+
+# Development
+
+## Re-generate Protobuf stubs
+
+Protobuf sources live in `proto/`. Generate Python stubs with:
+
+```
+uv run --group dev gen-protos
+```
+
+Or:
+
+```
+uv run tools/gen_protos.py
+```
+
+## Tests
+
+Run tests with:
+
+```
+uv run --group dev pytest
+```

farsounder-0.1.0/README.md

@@ -0,0 +1,94 @@
+# SDK Client for live FarSounder data
+
+Python client to communicate with SonaSoft via API.
+
+## Usage
+
+Clone locally and install (uv add .) or install from pypi like:
+
+```
+uv add farsounder
+```
+(or use pip, etc)
+
+Then - for example to subscribe to `TargetData` messages:
+
+```python
+import asyncio
+
+from farsounder import config, requests, subscriber
+from farsounder.proto import nav_api_pb2
+
+
+async def main() -> None:
+    cfg = config.build_config(
+        host="127.0.0.1",
+        subscribe=["TargetData"],
+    )
+
+    sub = subscriber.subscribe(config)
+
+    def on_targets(message: nav_api_pb2.TargetData) -> None:
+        print("Got a TargetData!")
+        print("Targets:", len(message.groups))
+
+    # Pub/Sub
+    sub.on("TargetData", on_targets)
+    await sub.start()
+
+    # Req/rep
+    settings = await requests.get_processor_settings(config)
+    print(settings)
+
+    # History data
+    history = await requests.get_history_data(
+        config,
+        latitude=41.7223,
+        longitude=-71.35,
+        radius_meters=500,
+    )
+    print(history.gridded_bottom_detections)
+
+    await asyncio.sleep(1.0)
+    await sub.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Simulated backend
+
+You can run a local simulated backend that publishes dummy messages and responds
+to request/reply calls:
+
+```
+uv run examples/simulated_backend.py
+```
+
+Note: the `examples/` directory is not installed with `uv add farsounder`.
+Clone the repo to run the examples locally.
+
+# Development
+
+## Re-generate Protobuf stubs
+
+Protobuf sources live in `proto/`. Generate Python stubs with:
+
+```
+uv run --group dev gen-protos
+```
+
+Or:
+
+```
+uv run tools/gen_protos.py
+```
+
+## Tests
+
+Run tests with:
+
+```
+uv run --group dev pytest
+```

farsounder-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "farsounder"
+version = "0.1.0"
+description = "Python client to communicate with FarSounder's ARGOS sensors"
+readme = "README.md"
+authors = [
+    { name = "FarSounder Software Team", email = "sw@farsounder.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "httpx",
+    "protobuf",
+    "pyzmq",
+]
+
+[project.scripts]
+gen-protos = "farsounder.tools.gen_protos:main"
+
+[dependency-groups]
+dev = [
+    "grpcio-tools",
+    "pytest",
+    "ruff>=0.14.14",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+exclude = [
+    "src/farsounder/proto/proto/**",
+]

farsounder-0.1.0/setup.cfg

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

farsounder-0.1.0/src/farsounder/__init__.py

@@ -0,0 +1,5 @@
+from farsounder.client import config as config
+from farsounder.client import requests as requests
+from farsounder.client import subscriber as subscriber
+from farsounder.client import exceptions as exceptions
+from farsounder.proto import proto as proto

farsounder-0.1.0/src/farsounder/client/config.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Literal, Mapping
+
+PubSubMessage = Literal[
+    "HydrophoneData",
+    "TargetData",
+    "ProcessorSettings",
+    "VesselInfo",
+]
+
+ReqRepEndpoint = Literal[
+    "GetProcessorSettings",
+    "SetFieldOfView",
+    "SetBottomDetection",
+    "SetInWaterSquelch",
+    "SetSquelchlessInWaterDetector",
+    "GetVesselInfo",
+    "SetDraft",
+    "SetKeelOffset",
+]
+
+RestEndpoint = Literal["GetHistoryData",]
+
+PUBSUB_DEFAULT_PORTS: dict[PubSubMessage, int] = {
+    "HydrophoneData": 61501,
+    "TargetData": 61502,
+    "ProcessorSettings": 61503,
+    "VesselInfo": 61504,
+}
+
+REQREP_DEFAULT_PORTS: dict[ReqRepEndpoint, int] = {
+    "GetProcessorSettings": 60501,
+    "SetFieldOfView": 60502,
+    "SetBottomDetection": 60503,
+    "SetInWaterSquelch": 60504,
+    "SetSquelchlessInWaterDetector": 60505,
+    "GetVesselInfo": 60506,
+    "SetDraft": 60507,
+    "SetKeelOffset": 60508,
+}
+
+REST_DEFAULT_PORTS: dict[RestEndpoint, int] = {
+    "GetHistoryData": 3000,
+}
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Configuration for the ZeroMQ client.
+
+    Parameters
+    ----------
+    host
+        Hostname or IP address for all sockets.
+    subscribe
+        Pub-sub message types to subscribe to.
+    pubsub_ports
+        Port mapping for pub-sub message types.
+    reqrep_ports
+        Port mapping for request-reply endpoints.
+    rest_ports
+        Port mapping for REST endpoints.
+    callback_executor
+        Whether to run sync callbacks in a thread pool or inline.
+    timeout_seconds
+        Request-reply timeout in seconds.
+    """
+
+    host: str
+    subscribe: tuple[PubSubMessage, ...]
+    pubsub_ports: dict[PubSubMessage, int]
+    reqrep_ports: dict[ReqRepEndpoint, int]
+    rest_ports: dict[RestEndpoint, int]
+    callback_executor: Literal["threadpool", "inline"]
+    timeout_seconds: float
+
+
+def build_config(
+    host: str = "127.0.0.1",
+    subscribe: Iterable[PubSubMessage] | None = None,
+    port_overrides: Mapping[str, int] | None = None,
+    callback_executor: Literal["threadpool", "inline"] = "threadpool",
+    timeout_seconds: float = 2.0,
+) -> ClientConfig:
+    """Build a client configuration.
+
+    Parameters
+    ----------
+    host
+        Hostname or IP address for all sockets.
+    subscribe
+        Iterable of message types to subscribe to. Defaults to all pub-sub
+        messages.
+    port_overrides
+        Mapping of message or endpoint name to port number. Keys can be any
+        pub-sub message name, request-reply endpoint name, or REST endpoint
+        name such as GetHistoryData.
+    callback_executor
+        Whether to run sync callbacks in a thread pool or inline.
+    timeout_seconds
+        Request-reply timeout in seconds.
+
+    Returns
+    -------
+    ClientConfig
+        The constructed configuration.
+    """
+
+    pubsub_ports = dict(PUBSUB_DEFAULT_PORTS)
+    reqrep_ports = dict(REQREP_DEFAULT_PORTS)
+    rest_ports = dict(REST_DEFAULT_PORTS)
+
+    if port_overrides:
+        for key, port in port_overrides.items():
+            if key in pubsub_ports:
+                pubsub_ports[key] = port
+            elif key in reqrep_ports:
+                reqrep_ports[key] = port
+            elif key in rest_ports:
+                rest_ports[key] = port
+            else:
+                raise ValueError(f"Unknown port override key: {key}")
+
+    subscribe_list = tuple(subscribe) if subscribe is not None else tuple(pubsub_ports)
+    for message_type in subscribe_list:
+        if message_type not in pubsub_ports:
+            raise ValueError(f"Unknown pub-sub message type: {message_type}")
+
+    return ClientConfig(
+        host=host,
+        subscribe=subscribe_list,
+        pubsub_ports=pubsub_ports,
+        reqrep_ports=reqrep_ports,
+        rest_ports=rest_ports,
+        callback_executor=callback_executor,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+def resolve_pubsub_port(config: ClientConfig, message_type: PubSubMessage) -> int:
+    """Resolve the port for a pub-sub message type."""
+
+    return config.pubsub_ports[message_type]
+
+
+def resolve_reqrep_port(config: ClientConfig, endpoint: ReqRepEndpoint) -> int:
+    """Resolve the port for a request-reply endpoint."""
+
+    return config.reqrep_ports[endpoint]
+
+
+def resolve_rest_port(config: ClientConfig, endpoint: RestEndpoint) -> int:
+    """Resolve the port for a REST endpoint."""
+
+    return config.rest_ports[endpoint]

farsounder-0.1.0/src/farsounder/client/exceptions.py

@@ -0,0 +1,2 @@
+class RequestTimeoutError(TimeoutError):
+    """Request-reply operation timed out."""

farsounder-0.1.0/src/farsounder/client/history_types.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class GriddedBottomDetection:
+    timestamp_utc: float
+    latitude_degrees: float
+    longitude_degrees: float
+    grid_interval_meters: float
+    target_strength_db: float
+    is_tide_corrected: bool
+    uploaded_to_cloud: bool
+    number_of_points: int
+    depth_meters: float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GriddedBottomDetection":
+        return cls(
+            timestamp_utc=float(data["timestamp_utc"]),
+            latitude_degrees=float(data["latitude_degrees"]),
+            longitude_degrees=float(data["longitude_degrees"]),
+            grid_interval_meters=float(data["grid_interval_meters"]),
+            target_strength_db=float(data["target_strength_db"]),
+            is_tide_corrected=bool(data["is_tide_corrected"]),
+            uploaded_to_cloud=bool(data["uploaded_to_cloud"]),
+            number_of_points=int(data["number_of_points"]),
+            depth_meters=float(data["depth_meters"]),
+        )
+
+
+@dataclass(frozen=True)
+class GriddedInwaterDetection:
+    timestamp_utc: float
+    latitude_degrees: float
+    longitude_degrees: float
+    grid_interval_meters: float
+    target_strength_db: float
+    is_tide_corrected: bool
+    uploaded_to_cloud: bool
+    number_of_points: int
+    deepest_depth_meters: float | None
+    shallowest_depth_meters: float | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GriddedInwaterDetection":
+        return cls(
+            timestamp_utc=float(data["timestamp_utc"]),
+            latitude_degrees=float(data["latitude_degrees"]),
+            longitude_degrees=float(data["longitude_degrees"]),
+            grid_interval_meters=float(data["grid_interval_meters"]),
+            target_strength_db=float(data["target_strength_db"]),
+            is_tide_corrected=bool(data["is_tide_corrected"]),
+            uploaded_to_cloud=bool(data["uploaded_to_cloud"]),
+            number_of_points=int(data["number_of_points"]),
+            deepest_depth_meters=(
+                float(data["deepest_depth_meters"])
+                if data.get("deepest_depth_meters") is not None
+                else None
+            ),
+            shallowest_depth_meters=(
+                float(data["shallowest_depth_meters"])
+                if data.get("shallowest_depth_meters") is not None
+                else None
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class HistoryData:
+    gridded_bottom_detections: list[GriddedBottomDetection]
+    gridded_inwater_detections: list[GriddedInwaterDetection]
+    history_count: int | None = None
+
+    @classmethod
+    def from_dict(
+        cls, data: dict[str, Any], *, history_count: int | None = None
+    ) -> "HistoryData":
+        bottom_raw = data.get("gridded_bottom_detections", [])
+        inwater_raw = data.get("gridded_inwater_detections", [])
+        return cls(
+            gridded_bottom_detections=[
+                GriddedBottomDetection.from_dict(item) for item in bottom_raw
+            ],
+            gridded_inwater_detections=[
+                GriddedInwaterDetection.from_dict(item) for item in inwater_raw
+            ],
+            history_count=history_count,
+        )