hydopt-client 0.0.2__py3-none-any.whl

hydopt_client/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("hydopt-client")

hydopt_client/auth.py

@@ -0,0 +1,17 @@
+from google.auth.transport import requests as google_requests
+from google.oauth2 import id_token
+
+SERVER_URL = "https://hydopt-api-131385138719.us-central1.run.app"
+AUDIENCE = "131385138719-463u6bbculfbqd491e2falsocsdr0rca.apps.googleusercontent.com"
+
+
+class TokenProvider:
+    def __init__(
+        self,
+        audience: str | None = None,
+    ) -> None:
+        self.audience = audience or AUDIENCE
+
+    def get_token(self) -> str:
+        request = google_requests.Request()
+        return id_token.fetch_id_token(request, self.audience)

hydopt_client/client.py

@@ -0,0 +1,193 @@
+import http
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+import httpx
+
+from hydopt_client.auth import SERVER_URL, TokenProvider
+from hydopt_client.models import (
+    CatchmentRecord,
+    HydoptRecord,
+    ObjectStatReport,
+    Order,
+    parse_records,
+)
+
+FILTER_KEYS = {
+    "country": "country",
+    "region": "region",
+    "locality": "locality",
+    "owners": "owners",
+    "point_group": "pointGroup",
+    "category2": "category2",
+    "category3": "category3",
+    "value_type": "valueType",
+    "data_sources": "dateSources",
+    "id": "id",
+    "start": "start",
+    "end": "end",
+}
+
+
+@dataclass
+class Filters:
+    country: list[str] = field(default_factory=list)
+    region: list[str] = field(default_factory=list)
+    locality: list[str] = field(default_factory=list)
+    owners: list[str] = field(default_factory=list)
+    point_group: list[str] = field(default_factory=list)
+    category2: list[str] = field(default_factory=list)
+    category3: list[str] = field(default_factory=list)
+    value_type: list[str] = field(default_factory=list)
+    data_sources: list[str] = field(default_factory=list)
+    id: list[str] = field(default_factory=list)
+    start: str | None = None
+    end: str | None = None
+
+    def to_query(self) -> dict[str, str | list[str]]:
+        return {
+            FILTER_KEYS[name]: values for name, values in vars(self).items() if values
+        }
+
+
+class GroupBy(StrEnum):
+    country = "country"
+    region = "region"
+    locality = "locality"
+    point_group = "pointGroup"
+    category2 = "category2"
+    category3 = "category3"
+    owner = "owner"
+    id = "id"
+    point_id = "pointId"
+
+
+class Client:
+    def __init__(
+        self,
+        url: str | None = None,
+        timeout: int = 30,
+        http_client: httpx.Client | None = None,
+        token_provider: TokenProvider | None = None,
+    ) -> None:
+        self.url = url or SERVER_URL
+        self.token_provider = (
+            token_provider if token_provider is not None else TokenProvider()
+        )
+        self.timeout = timeout
+        self.http_client = http_client or httpx.Client()
+
+    def get_token(self) -> str:
+        return self.token_provider.get_token()
+
+    def authorization_header(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.get_token()}"}
+
+    def _request(
+        self, method: str, path: str, params: dict[str, Any] | None = None
+    ) -> httpx.Response:
+        response = self.http_client.request(
+            method,
+            f"{self.url}{path}",
+            headers=self.authorization_header(),
+            params=params,
+            timeout=self.timeout,
+        )
+        if response.status_code == http.HTTPStatus.UNAUTHORIZED:
+            response = self.http_client.request(
+                method,
+                f"{self.url}{path}",
+                headers=self.authorization_header(),
+                timeout=self.timeout,
+                params=params,
+            )
+        return response
+
+    def get_items(
+        self,
+        path: str,
+        filters: Filters | None,
+        group_by: list[GroupBy] | None,
+    ) -> list[HydoptRecord]:
+        params: dict[str, str | list[str]] = {}
+        if filters:
+            params.update(filters.to_query())
+        if group_by:
+            params["groupby"] = [g.value for g in group_by]
+
+        response = self._request("GET", path, params=params)
+        response.raise_for_status()
+        return parse_records(response.json()["items"])
+
+    def series(
+        self,
+        asof: str,
+        category1: str,
+        filters: Filters | None = None,
+        group_by: list[GroupBy] | None = None,
+    ) -> list[HydoptRecord]:
+        return self.get_items(f"/v1/series/{asof}/{category1}", filters, group_by)
+
+    def diff(
+        self,
+        category1: str,
+        from_asof: str,
+        to_asof: str,
+        filters: Filters | None = None,
+        group_by: list[GroupBy] | None = None,
+    ) -> list[HydoptRecord]:
+        return self.get_items(
+            f"/v1/diff/{category1}/{from_asof}/{to_asof}", filters, group_by
+        )
+
+    def dataset(
+        self,
+        dataset: str,
+        category1: str,
+        filters: Filters | None,
+        group_by: list[GroupBy] | None,
+    ) -> list[HydoptRecord]:
+        return self.get_items(f"/v1/{dataset}/{category1}", filters, group_by)
+
+    def static(
+        self,
+        category1: str,
+        filters: Filters | None = None,
+        group_by: list[GroupBy] | None = None,
+    ) -> list[HydoptRecord]:
+        return self.dataset("static", category1, filters, group_by)
+
+    def realized(
+        self,
+        category1: str,
+        filters: Filters | None = None,
+        group_by: list[GroupBy] | None = None,
+    ) -> list[HydoptRecord]:
+        return self.dataset("realized", category1, filters, group_by)
+
+    def list_partitions(self) -> list[str]:
+        response = self._request("GET", "/v1/dates")
+        response.raise_for_status()
+        return response.json()["availableDates"]
+
+    def catchments(self, asof: str) -> list[CatchmentRecord]:
+        response = self._request("GET", f"/v1/catchments/{asof}")
+        response.raise_for_status()
+        return [
+            CatchmentRecord.model_validate(item) for item in response.json()["items"]
+        ]
+
+    def object_report(self, source_date: str, target_date: str) -> ObjectStatReport:
+        response = self._request(
+            "GET", f"/v1/object-report/{source_date}/{target_date}"
+        )
+        response.raise_for_status()
+        return ObjectStatReport.model_validate(response.json())
+
+    def orders(self, asof: str) -> list[Order]:
+        response = self._request("GET", f"/v1/orders/{asof}")
+        response.raise_for_status()
+        return [
+            Order.model_validate(item) for item in response.json().get("orders") or []
+        ]

hydopt_client/models.py

@@ -0,0 +1,132 @@
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic.alias_generators import to_camel
+
+
+class ProcessingInfo(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    group_key: str | None = None
+    reduced_group_key: str | None = None
+    color: str | None = None
+
+
+class HydoptRecord(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    row_num: int
+    asof: datetime
+    category1: str
+    category2: str
+    category3: str
+    country: str
+    data_source: str
+    id: str
+    locality: str
+    name: str
+    owner: str
+    point_group: str
+    region: str
+    unit: str
+    value_type: str
+    x: list[datetime]
+    y: list[float]
+    processing_info: ProcessingInfo | None = None
+
+    @field_validator("x", "y", mode="before")
+    @classmethod
+    def null_to_empty(cls, v: object) -> object:
+        return v if v is not None else []
+
+
+def parse_records(items: list[dict]) -> list[HydoptRecord]:
+    return [HydoptRecord.model_validate(item) for item in items]
+
+
+class CatchmentRecord(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    id: str
+    region: str
+    locality: str
+    polygon: str = Field(alias="shape")
+    name: str
+    created_time: datetime
+
+
+class Identity(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    asof: datetime
+    category1: str
+    category2: str
+    category3: str
+    country: str
+    data_source: str
+    id: str
+    locality: str
+    name: str
+    owner: str
+    point_group: str
+    region: str
+    unit: str
+    value_type: str
+
+
+class IndividualReaderStats(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    name: str
+    size_mb: int
+    num_records: int
+
+
+class CompareResult(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    stat: list[IndividualReaderStats]
+    appearing: list[Identity]
+    disappearing: list[Identity]
+
+
+class PartitionComparison(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    name: str
+    diff: CompareResult
+
+
+class MissingPartition(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    is_in: str
+    name: str
+
+
+class ObjectStatReport(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    source_date: str
+    target_date: str
+    created_at: datetime
+    missing: list[MissingPartition] | None = None
+    partition_comparisons: list[PartitionComparison]
+
+
+class OrderDirection(StrEnum):
+    production = "production"
+    demand = "demand"
+
+
+class Order(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    id: str
+    price: float
+    quantity: float
+    region: str
+    direction: OrderDirection
+    start: datetime
+    end: datetime

hydopt_client-0.0.2.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: hydopt-client
+Version: 0.0.2
+Summary: Python client for the HydOpt hydropower optimization API
+Requires-Python: >=3.13
+Requires-Dist: google-auth>=2.56.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: requests>=2.34.2
+Description-Content-Type: text/markdown
+
+# hydopt-client
+
+Python client for the [HydOpt](https://hydopt.io) hydropower optimization API.
+
+## Install
+
+```bash
+uv add hydopt-client
+```
+
+## Authentication
+
+Authenticate with Google Cloud:
+
+```bash
+gcloud auth application-default login
+```
+
+## Quick Start
+
+```python
+from hydopt_client.client import Client
+
+client = Client()
+
+# List available partition dates
+dates = client.list_partitions()
+print(dates)  # ["2026-01-01", "2026-01-02", ...]
+
+# Fetch a time series
+records = client.series(dates[0], "production")
+for record in records:
+    print(record.name, record.x[0], record.y[0])
+
+# Filter and group results
+from hydopt_client.client import Filters, GroupBy
+
+filtered = client.series(
+    dates[0],
+    "production",
+    filters=Filters(country=["norway"]),
+    group_by=[GroupBy.region],
+)
+```
+
+## Available Methods
+
+| Method | Description |
+|--------|-------------|
+| `list_partitions()` | List available partition dates |
+| `series(asof, category1, ...)` | Query time-series data |
+| `diff(category1, from, to, ...)` | Compare two partitions |
+| `static(category1, ...)` | Query static dataset |
+| `realized(category1, ...)` | Query realized dataset |
+| `catchments(asof)` | Fetch catchment geometries |
+| `orders(asof)` | Fetch energy orders |
+| `object_report(source, target)` | Compare two partition objects |

hydopt_client-0.0.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+hydopt_client/__init__.py,sha256=iHQOlnZ7hvhtmRgX05Y3G-2LobTXpDlRbqXnyNkNWC0,79
+hydopt_client/auth.py,sha256=MgELQa6rhm__Mn4BFZr63z8wfORE_oFdsFFWKCB2aJE,543
+hydopt_client/client.py,sha256=rCED4Pn1WzooEjpX8MvXO4pQTsdwe8aMuJ7eBKRIpMQ,5883
+hydopt_client/models.py,sha256=yYYcrTmhT9eIU1zd2w1aH7ATQ5xDgQZguCP5JU-0Q2M,3035
+hydopt_client-0.0.2.dist-info/METADATA,sha256=Kl9boGQe_Br_vYlsjw_eCKWm6wqSHHEgJXwLLyP1yVU,1643
+hydopt_client-0.0.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+hydopt_client-0.0.2.dist-info/RECORD,,

hydopt_client-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any