novastar-client 1.2.0__tar.gz

novastar_client-1.2.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: novastar-client
+Version: 1.2.0
+Summary: Python client for NovaStar REST endpoints (Stations)
+Author: Jeff Gregory
+Author-email: Jeff Gregory <jeffrey.s.gregory@usace.army.mil>
+License-Expression: MIT
+Requires-Dist: requests>=2.31.0
+Requires-Dist: click
+Requires-Dist: pandas
+Requires-Dist: hecdss
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Panama Canal Authority NovaStar API Client, novastar_client
+
+## novastar_client
+
+A Python client library for working with the NovaStar API, with documentation published via pdoc on GitHub pages.  See [Releases](https://github.com/jeffsuperglide/novastar_client/releases) and the latest release for this package details and install guidance.
+
+## Overview
+
+`novastar_client` is meant for developers who want to control or integrate NovaStar workflows from Python code instead of relying entirely on desktop tools.  The documentation site is structured as API reference material, so the package is best approached as importable library for scripts, services, and internal utilities.
+
+## What it includes
+
+- A Python package under the `novastar_client` name, documented with pdoc.
+- An API-first layout intended for code-based usage.
+- Published release artifacts for installation from GitHub release pages.
+
+## Installation
+
+Install from the repository's [Releases](https://github.com/jeffsuperglide/novastar_client/releases) using the package file provided on the GitHub release page.  Release assets include a tarball and wheel.  Download to install with pip, or install directly from the release version.  It is suggested to use the wheel for installation because it will be a quicker install.
+
+### pip install wheel, Windows CMD
+
+```cmd
+pip install .\novastar_client-0.1.0-py3-none-any.whl
+```
+
+### pip install tarball, Windows CMD
+
+```cmd
+pip install .\novastar_client-0.1.0.tar.gz
+```
+
+### Direct pip install whl, Windows CMD
+
+```cmd
+pip install "https://github.com/jeffsuperglide/novastar_client/releases/download/v0.1.0/novastar_client-0.1.0-py3-none-any.whl"
+```
+
+## Documentation
+
+The full API reference is published at https://jeffsuperglide.github.io/novastar_client/.  Reference for:
+
+- Module and class names.
+- Method signatures.
+- Parmeter details.
+- Return values.
+
+## Reference Links
+
+[API-UI](https://panama-cloud-ns5.trilynx-novastar.systems/novastar/data/api/v1/api-ui)
+
+[Operator Manual](https://panama-cloud-ns5.trilynx-novastar.systems/novastar/doc/operator/user/)
+
+[Operator Map](https://panama-cloud-ns5.trilynx-novastar.systems/novastar/operator/map)
+
+[Stations API Call - Simple](https://panama-cloud-ns5.trilynx-novastar.systems/novastar/data/api/v1/stations)
+
+[TriLynx NovaStar Web Services Docs Home](https://software.trilynx.systems/nsdataws/latest/doc-user/).
+
+[Jython.org](https://www.jython.org/)
+
+[Python 2.7](https://docs.python.org/2.7/)

novastar_client-1.2.0/README.md

@@ -0,0 +1,62 @@
+# Panama Canal Authority NovaStar API Client, novastar_client
+
+## novastar_client
+
+A Python client library for working with the NovaStar API, with documentation published via pdoc on GitHub pages.  See [Releases](https://github.com/jeffsuperglide/novastar_client/releases) and the latest release for this package details and install guidance.
+
+## Overview
+
+`novastar_client` is meant for developers who want to control or integrate NovaStar workflows from Python code instead of relying entirely on desktop tools.  The documentation site is structured as API reference material, so the package is best approached as importable library for scripts, services, and internal utilities.
+
+## What it includes
+
+- A Python package under the `novastar_client` name, documented with pdoc.
+- An API-first layout intended for code-based usage.
+- Published release artifacts for installation from GitHub release pages.
+
+## Installation
+
+Install from the repository's [Releases](https://github.com/jeffsuperglide/novastar_client/releases) using the package file provided on the GitHub release page.  Release assets include a tarball and wheel.  Download to install with pip, or install directly from the release version.  It is suggested to use the wheel for installation because it will be a quicker install.
+
+### pip install wheel, Windows CMD
+
+```cmd
+pip install .\novastar_client-0.1.0-py3-none-any.whl
+```
+
+### pip install tarball, Windows CMD
+
+```cmd
+pip install .\novastar_client-0.1.0.tar.gz
+```
+
+### Direct pip install whl, Windows CMD
+
+```cmd
+pip install "https://github.com/jeffsuperglide/novastar_client/releases/download/v0.1.0/novastar_client-0.1.0-py3-none-any.whl"
+```
+
+## Documentation
+
+The full API reference is published at https://jeffsuperglide.github.io/novastar_client/.  Reference for:
+
+- Module and class names.
+- Method signatures.
+- Parmeter details.
+- Return values.
+
+## Reference Links
+
+[API-UI](https://panama-cloud-ns5.trilynx-novastar.systems/novastar/data/api/v1/api-ui)
+
+[Operator Manual](https://panama-cloud-ns5.trilynx-novastar.systems/novastar/doc/operator/user/)
+
+[Operator Map](https://panama-cloud-ns5.trilynx-novastar.systems/novastar/operator/map)
+
+[Stations API Call - Simple](https://panama-cloud-ns5.trilynx-novastar.systems/novastar/data/api/v1/stations)
+
+[TriLynx NovaStar Web Services Docs Home](https://software.trilynx.systems/nsdataws/latest/doc-user/).
+
+[Jython.org](https://www.jython.org/)
+
+[Python 2.7](https://docs.python.org/2.7/)

novastar_client-1.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "novastar-client"
+version = "1.2.0"
+description = "Python client for NovaStar REST endpoints (Stations)"
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "requests>=2.31.0",
+    "click",
+    "pandas",
+    "hecdss",
+]
+
+[[project.authors]]
+name = "Jeff Gregory"
+email = "jeffrey.s.gregory@usace.army.mil"
+
+[project.scripts]
+ns5acp = "novastar_client.cli.ns5acp:cli"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "mypy>=1.0",
+    "ruff>=0.4.0",
+    "pdocs",
+]

novastar_client-1.2.0/pyproject.toml.orig

@@ -0,0 +1,25 @@
+[build-system]
+    requires = ["uv_build>=0.12.5,<0.13"]
+    build-backend = "uv_build"
+
+[project]
+    name = "novastar-client"
+    version = "1.2.0"
+    description = "Python client for NovaStar REST endpoints (Stations)"
+    authors = [{ name = "Jeff Gregory", email = "jeffrey.s.gregory@usace.army.mil" }]
+    license = "MIT"
+    readme = "README.md"
+    requires-python = ">=3.12"
+    dependencies = ["requests>=2.31.0", "click", "pandas", "hecdss"]
+
+[project.scripts]
+    ns5acp = "novastar_client.cli.ns5acp:cli"
+
+[dependency-groups]
+    dev = [
+        "pytest>=7.0",
+        "pytest-cov>=4.0",
+        "mypy>=1.0",
+        "ruff>=0.4.0",
+        "pdocs",
+    ]

novastar_client-1.2.0/src/novastar_client/README.md

@@ -0,0 +1,333 @@
+# novastar-client
+
+`novastar-client` is a Python client for NovaStar-style REST data endpoints exposed under paths like:
+
+- `/novastar/data/api/v1/stations`
+- `/novastar/data/api/v1/time-series`
+- `/novastar/data/api/v1/ratings`
+- `/novastar/data/api/v1/points`
+- `/novastar/data/api/v1/general`
+
+It provides:
+
+- A version-aware client (`v1`, `v2`, etc.) using a configurable `api_version`
+- Grouped services (Stations, Time Series, Ratings, Points, General)
+- Typed models for resources (starting with Stations), including support for both `jsonFormat=full` and `jsonFormat=bare` response shapes
+
+
+## Features
+
+- **Versioned API root**: Requests go to `/novastar/data/api/{api_version}/...` based on configuration.
+- **Grouped endpoints**: Access resources via `client.stations`, `client.time_series`, `client.ratings`, `client.points`, and `client.general`.
+- **Stations models**:
+  - `jsonFormat=bare`: top-level JSON is an array of station objects.
+  - `jsonFormat=full`: top-level JSON is an envelope with `apiVersion`, `attributionAndUsage`, `responseInfo`, and `stations`.
+- **Editable install**: Designed for `pip install -e .` so you can iterate quickly while developing.
+
+
+## Installation (local editable)
+
+Create a virtual environment and install the package in editable mode:
+
+```bash
+# from the repository root (where pyproject.toml lives)
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+This will:
+
+- Install `novastar-client` in editable mode
+- Install dev tools like `pytest` (defined under `[project.optional-dependencies].dev` in `pyproject.toml`)
+
+
+## Configuration
+
+The client configuration is defined via `NovaStarConfig`:
+
+```python
+from novastar_client import NovaStarClient, NovaStarConfig
+
+config = NovaStarConfig(
+    base_url="https://panama-cloud-ns5.trilynx-novastar.systems",
+    api_version="v1",  # or "v2" when you support it
+    timeout=30,
+    verify_ssl=True,
+)
+
+client = NovaStarClient(config)
+```
+
+Key options:
+
+- `base_url`: Root of the NovaStar deployment
+- `api_version`: Version segment used in the URL, e.g. `"v1"` → `/novastar/data/api/v1/...`
+- `timeout`: Request timeout in seconds
+- `verify_ssl`: SSL verification toggle
+
+
+## Client structure
+
+The top-level client wires a shared HTTP session into category-specific services:
+
+```python
+from novastar_client import NovaStarClient, NovaStarConfig
+
+client = NovaStarClient(NovaStarConfig(api_version="v1"))
+
+# Services
+stations_service = client.stations
+# (time_series, ratings, points, general can be added similarly)
+```
+
+
+## Stations API
+
+The `StationsAPI` exposes a `list` method that maps directly to the `stations` endpoint and supports both `jsonFormat=full` and `jsonFormat=bare`.
+
+### Parameters
+
+The following query parameters are supported:
+
+- `station_num_ids` → `stationNumId` (comma-separated list)
+- `station_name` → `stationName` (supports `*` wildcard at start and/or end)
+- `include_retired_stations` → `includeRetiredStations`
+- `include_test_stations` → `includeTestStations`
+- `debug` → `debug`
+- `json_format` → `jsonFormat` (`"full"` or `"bare"`)
+- `xml_format` → `xmlFormat`
+- `format_pretty_print` → `formatPrettyPrint`
+
+### jsonFormat=bare
+
+When `json_format="bare"`, the endpoint returns a JSON array of station objects, and the client returns a `List[Station]`.
+
+```python
+from novastar_client import NovaStarClient, NovaStarConfig
+
+client = NovaStarClient(NovaStarConfig(api_version="v1"))
+
+stations = client.stations.list(
+    station_num_ids=,[1][2]
+    json_format="bare",
+)
+
+for s in stations:
+    print(s.num_id, s.name, s.latitude, s.longitude)
+```
+
+`Station` fields (derived from the bare JSON) include:
+
+- `id: int`
+- `num_id: int` (from `numId`)
+- `name: str`
+- `description: Optional[str]`
+- `description_text: Optional[str]`
+- `dashboard_url: Optional[str]`
+- `elevation: Optional[float]`
+- `last_time_polled: Optional[str]`
+- `latitude: Optional[float]`
+- `longitude: Optional[float]`
+- `out_of_service: Optional[bool]`
+- `remote_tag: Optional[str]`
+- `retired_station: Optional[bool]`
+- `tag_name: Optional[str]`
+- `test_station: Optional[bool]`
+- `type_id: Optional[int]`
+- `station_type_name: Optional[str]`
+- `station_type_protocol: Optional[str]`
+
+
+### jsonFormat=full
+
+When `json_format="full"`, the endpoint returns a structured envelope with version metadata, attribution/usage info, response info, and a `stations` array. The client returns a `StationsResponse` model.
+
+```python
+resp = client.stations.list(
+    station_name="*PANAMA*",
+    json_format="full",
+)
+
+print(resp.api_version.api_dot_delimited_version)
+print(resp.response_info.size)
+for s in resp.stations:
+    print(s.num_id, s.name)
+```
+
+`StationsResponse` contains:
+
+- `api_version: ApiVersion`
+- `attribution_and_usage: AttributionAndUsage`
+- `response_info: ResponseInfo`
+- `stations: List[Station]`
+
+This lets you access both the actual station data and useful metadata such as query timing, caching, and attribution requirements.
+
+
+## Models
+
+Models live under `src/novastar_client/models/` and are responsible for mapping API JSON into typed Python objects.
+
+Currently implemented:
+
+- `Station`: one station record
+- `StationsResponse`: full envelope for the stations endpoint
+- `ApiVersion`, `AttributionAndUsage`, `ResponseInfo`: envelope metadata
+
+Each model provides a `from_api` class method to construct it from a raw `dict`:
+
+```python
+from novastar_client.models import Station, StationsResponse
+
+station = Station.from_api(raw_station_dict)
+stations_response = StationsResponse.from_api(raw_envelope_dict)
+```
+
+
+## Running tests
+
+Tests use `pytest` and mock the HTTP session so you can verify behavior without hitting a real NovaStar instance.
+
+To run all tests:
+
+```bash
+pytest
+```
+
+### Example: test for Stations API
+
+The `tests/test_stations_api.py` file exercises both `jsonFormat=bare` and `jsonFormat=full` behavior:
+
+- Ensures the correct query parameter (`jsonFormat`) is sent.
+- Asserts that `json_format="bare"` returns a `List[Station]`.
+- Asserts that `json_format="full"` returns a `StationsResponse`.
+
+A simplified example:
+
+```python
+from typing import Any
+from unittest.mock import MagicMock
+
+from novastar_client import NovaStarClient, NovaStarConfig
+from novastar_client.models import Station, StationsResponse
+
+
+def test_stations_list_bare_returns_station_models():
+    bare_payload = [
+        {
+            "id": 1,
+            "numId": 123,
+            "name": "TEST STATION",
+            "description": "",
+            "descriptionText": "",
+            "dashboardUrl": None,
+            "elevation": 10.5,
+            "lastTimePolled": "2024-01-01T00:00:00-05:00",
+            "latitude": 9.0,
+            "longitude": -79.5,
+            "outOfService": False,
+            "remoteTag": "123",
+            "retiredStation": False,
+            "tagName": "TST",
+            "testStation": False,
+            "typeId": 20,
+            "stationTypeName": "Campbell Scientific ALERT2 Radio",
+            "stationTypeProtocol": "ALERT2",
+        }
+    ]
+
+    config = NovaStarConfig(api_version="v1")
+    client = NovaStarClient(config)
+
+    mock_get = MagicMock(return_value=bare_payload)
+    client.session.get = mock_get  # type: ignore[attr-defined]
+
+    result = client.stations.list(json_format="bare")
+
+    assert isinstance(result, list)
+    assert isinstance(result, Station)
+    assert result.num_id == 123
+    assert result.name == "TEST STATION"
+
+    called_path, called_kwargs = mock_get.call_args
+    assert called_path == "stations"
+    assert called_kwargs["params"]["jsonFormat"] == "bare"
+
+
+def test_stations_list_full_returns_stations_response():
+    full_payload: dict[str, Any] = {
+        "apiVersion": {
+            "apiVersionMajor": "1",
+            "apiVersionMinor": "0",
+            "apiVersionMicro": "0",
+            "apiVersionModifier": "",
+            "apiVersionDate": "2024-01-01",
+            "apiVersionTime": "00:00:00",
+            "apiDotDelimitedVersion": "1.0.0",
+        },
+        "attributionAndUsage": {
+            "providerOrganizationText": "Test Org",
+            "providerOrganizationUri": "https://example.com",
+            "dataPolicyUri": "",
+            "disclaimerText": "",
+            "disclaimerUri": "",
+            "licenseText": "",
+            "licenseUri": "",
+            "usageConstraintsText": "",
+            "usageConstraintsUri": "",
+            "recommendedAttributionText": "",
+        },
+        "responseInfo": {
+            "urlOriginal": "https://example.com",
+            "urlOriginalEncoded": "",
+            "url": "",
+            "urlEncoded": "",
+            "periodStart": None,
+            "periodEnd": None,
+            "size": 1,
+            "queryStart": "2024-01-01T00:00:00Z",
+            "queryMs": 10,
+            "queryTargetMs": 50,
+            "queryTargetMet": True,
+            "isCached": False,
+            "cacheExpirationTime": None,
+        },
+        "stations": bare_payload,
+    }
+
+    config = NovaStarConfig(api_version="v1")
+    client = NovaStarClient(config)
+
+    mock_get = MagicMock(return_value=full_payload)
+    client.session.get = mock_get  # type: ignore[attr-defined]
+
+    result = client.stations.list(json_format="full")
+
+    assert isinstance(result, StationsResponse)
+    assert result.api_version.api_dot_delimited_version == "1.0.0"
+    assert len(result.stations) == 1
+    assert result.stations.name == "TEST STATION"
+
+    called_path, called_kwargs = mock_get.call_args
+    assert called_path == "stations"
+    assert called_kwargs["params"]["jsonFormat"] == "full"
+```
+
+
+## Roadmap
+
+- Add service modules and models for:
+  - Time Series
+  - Ratings
+  - Points
+  - General (health, info, etc.)
+- Introduce version strategies for `v2` when the API contract diverges from `v1` while keeping the Python interface stable.
+- Optional: add higher-level helpers (e.g., “get latest measurement for station X and point Y”) on top of the raw endpoints.
+
+
+## License
+
+TBD (add your preferred license here).

novastar_client-1.2.0/src/novastar_client/__init__.py

@@ -0,0 +1,30 @@
+"""
+Importing all the modules
+"""
+
+# __version__ = "1.0.0"
+# my_package/__init__.py
+from importlib.metadata import version, PackageNotFoundError
+
+from novastar_client import models
+from novastar_client import services
+from novastar_client import transform
+
+from novastar_client.client import NovaStarClient
+from novastar_client.config import NovaStarConfig
+from novastar_client.session import NovaStarSession
+
+__all__ = [
+    "models",
+    "services",
+    "transform",
+    "NovaStarClient",
+    "NovaStarConfig",
+    "NovaStarSession",
+    "cli",  # type: ignore
+]
+
+try:
+    __version__ = version("my-package")
+except PackageNotFoundError:
+    __version__ = "v0.1.0"  # or some sensible default

novastar_client-1.2.0/src/novastar_client/cli/__init__.py

@@ -0,0 +1,11 @@
+"""NovaStar Client Interface"""
+
+from novastar_client.cli import commands, context, logging, ns5acp, settings
+
+__all__ = [
+    "commands",
+    "context",
+    "logging",
+    "ns5acp",
+    "settings",
+]

novastar_client-1.2.0/src/novastar_client/cli/commands/__init__.py

@@ -0,0 +1,11 @@
+"""NovaStar Client Interface Commands"""
+
+from novastar_client.cli.commands import stations
+from novastar_client.cli.commands import ts
+from novastar_client.cli.commands import tscatalog
+
+__all__ = [
+    "stations",
+    "ts",
+    "tscatalog",
+]

novastar_client-1.2.0/src/novastar_client/cli/commands/stations.py

@@ -0,0 +1,59 @@
+"""NovaStar Client command line interface subcommand, stations"""
+
+from __future__ import annotations
+
+import json
+import logging
+import typing
+import pprint
+
+import click
+
+from novastar_client.cli.helpers import output_pretty_json
+
+from ..context import AppContext
+from ..settings import CONTEXT_SETTINGS
+from ...client import NovaStarClient
+from ...config import NovaStarConfig
+
+logger = logging.getLogger(__name__)
+
+pass_app = click.make_pass_decorator(AppContext)
+
+pp = pprint.PrettyPrinter(indent=4, width=80, compact=False)
+
+
+@click.command(context_settings=CONTEXT_SETTINGS)
+@click.option(
+    "--station-numid",
+    multiple=True,
+    help="Station numerical ID filter, using public identifiers, single "
+    "number or comma-separated list, can be repeated.",
+)
+@click.option(
+    "--pretty-print",
+    is_flag=True,
+)
+@pass_app
+def stations(app: AppContext, station_numid: typing.Tuple, pretty_print: bool) -> None:
+    """Subcommand returning a list of station metadata."""
+
+    config = NovaStarConfig(base_url=app.api_url, api_version=app.api_version)
+    client = NovaStarClient(config=config)
+
+    station_numbers = (
+        ",".join(station_numid) if len(station_numid) > 1 else "".join(station_numid)
+    )
+
+    resp = client.stations.get(stationNumId=station_numbers)
+
+    if resp is None:
+        logger.warning("Stations command line interface returned %s", resp)
+        return None
+
+    resp_as_dict = resp.to_dict()  # type: ignore
+
+    if pretty_print:
+        click.echo(output_pretty_json(resp_as_dict))
+    else:
+        click.echo(json.dumps(resp_as_dict))