pd4castr-api-sdk 0.0.0__py3-none-any.whl

pd4castr_api_sdk/__init__.py

@@ -0,0 +1,13 @@
+from .client import Client
+from .errors import ApiError, NotFoundError
+from .models import Organisation, User
+
+__all__ = [
+    "Client",
+    "ApiError",
+    "NotFoundError",
+    "Organisation",
+    "User",
+]
+
+__version__ = "0.0.0"

pd4castr_api_sdk/auth.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import AuthenticationError
+from .transport import Transport
+
+
+def _normalize_auth0_domain(domain: str) -> str:
+    if domain.startswith("https://") or domain.startswith("http://"):
+        return domain.rstrip("/")
+    return f"https://{domain.rstrip('/')}"
+
+
+@dataclass
+class ClientCredentialsAuth:
+    auth0_domain: str
+    audience: str
+    client_id: str
+    client_secret: str
+
+    _access_token: str | None = None
+    _expires_at_epoch: float | None = None
+
+    def get_access_token(self, transport: Transport) -> str:
+        if self._access_token and self._expires_at_epoch:
+            # refresh a little early to avoid clock skew.
+            if time.time() < (self._expires_at_epoch - 10):
+                return self._access_token
+
+        token_url = f"{_normalize_auth0_domain(self.auth0_domain)}/oauth/token"
+
+        response = transport.request(
+            "POST",
+            token_url,
+            headers={"content-type": "application/x-www-form-urlencoded"},
+            data={
+                "grant_type": "client_credentials",
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+                "audience": self.audience,
+            },
+        )
+
+        if response.status_code >= 400:
+            raise AuthenticationError(
+                f"auth0 token request failed ({response.status_code})"
+            )
+
+        try:
+            payload: dict[str, Any] = response.json()
+        except Exception as exc:  # pragma: no cover
+            raise AuthenticationError("auth0 token response was not json") from exc
+
+        access_token = payload.get("access_token")
+        expires_in = payload.get("expires_in")
+
+        if not isinstance(access_token, str):
+            raise AuthenticationError("auth0 token response missing access_token")
+
+        if not isinstance(expires_in, int):
+            raise AuthenticationError("auth0 token response missing expires_in")
+
+        self._access_token = access_token
+        self._expires_at_epoch = time.time() + expires_in
+
+        return access_token

pd4castr_api_sdk/client.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .auth import ClientCredentialsAuth
+from .config import (
+    DEFAULT_API_URL,
+    DEFAULT_AUTH0_AUDIENCE,
+    DEFAULT_AUTH0_DOMAIN,
+    load_config,
+)
+from .errors import ApiError, NotFoundError
+from .models import Model, User
+from .transport import HttpxSyncTransport, Transport
+
+
+def _normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        auth0_domain: str | None = None,
+        auth0_audience: str | None = None,
+        client_id: str,
+        client_secret: str,
+        timeout: float = 30.0,
+        transport: Transport | None = None,
+    ) -> None:
+        config = load_config()
+
+        resolved_base_url = base_url or config.base_url or DEFAULT_API_URL
+        resolved_domain = auth0_domain or config.auth0_domain or DEFAULT_AUTH0_DOMAIN
+        resolved_audience = (
+            auth0_audience or config.auth0_audience or DEFAULT_AUTH0_AUDIENCE
+        )
+
+        self._base_url = _normalize_base_url(resolved_base_url)
+        self._auth = ClientCredentialsAuth(
+            auth0_domain=resolved_domain,
+            audience=resolved_audience,
+            client_id=client_id,
+            client_secret=client_secret,
+        )
+
+        self._transport = transport or HttpxSyncTransport(
+            client=httpx.Client(timeout=timeout)
+        )
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.close()
+
+    def get_models(self, *, time_horizon: str | None = None) -> list[Model]:
+        params: dict[str, Any] = {}
+        if time_horizon is not None:
+            params["timeHorizon"] = time_horizon
+
+        data = self._request_json("GET", "/model", params=params)
+        return [Model.model_validate(item) for item in data]
+
+    def get_model(self, model_id: str) -> Model:
+        data = self._request_json("GET", f"/model/{model_id}")
+        return Model.model_validate(data)
+
+    def get_current_user(self) -> User:
+        data = self._request_json("GET", "/user/current")
+        return User.model_validate(data)
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        token = self._auth.get_access_token(self._transport)
+
+        response = self._transport.request(
+            method,
+            url,
+            headers={
+                "authorization": f"Bearer {token}",
+                "accept": "application/json",
+            },
+            params=params,
+        )
+
+        if response.status_code == 404:
+            raise NotFoundError("resource not found")
+
+        if response.status_code >= 400:
+            body: Any | None
+            try:
+                body = response.json()
+            except Exception:
+                body = response.text
+
+            raise ApiError(
+                status_code=response.status_code,
+                message="request failed",
+                body=body,
+            )
+
+        try:
+            return response.json()
+        except ValueError as e:
+            raise ApiError(
+                status_code=response.status_code,
+                message=f"invalid JSON response: {e}",
+                body=response.text,
+            ) from e

pd4castr_api_sdk/config.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_API_URL = "https://api.v2.pd4castr.com.au"
+DEFAULT_AUTH0_DOMAIN = "pdview.au.auth0.com"
+DEFAULT_AUTH0_AUDIENCE = "https://api.pd4castr.com.au"
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    base_url: str
+    auth0_domain: str
+    auth0_audience: str
+
+
+def load_config() -> ClientConfig:
+    # allow overrides for advanced usage
+    base_url = os.environ.get("PD4CASTR_API_URL", DEFAULT_API_URL)
+    audience = os.environ.get("PD4CASTR_AUTH0_AUDIENCE", DEFAULT_AUTH0_AUDIENCE)
+
+    domain = os.environ.get("PD4CASTR_AUTH0_DOMAIN", DEFAULT_AUTH0_DOMAIN)
+
+    return ClientConfig(
+        base_url=base_url,
+        auth0_domain=domain,
+        auth0_audience=audience,
+    )

pd4castr_api_sdk/errors.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+class Pd4castrApiError(Exception):
+    pass
+
+
+class AuthenticationError(Pd4castrApiError):
+    pass
+
+
+class NotFoundError(Pd4castrApiError):
+    pass
+
+
+# exceptions must be mutable so python can attach traceback/cause details
+@dataclass
+class ApiError(Pd4castrApiError):
+    status_code: int
+    message: str
+    body: Any | None = None
+
+    def __str__(self) -> str:  # pragma: no cover
+        return f"{self.status_code}: {self.message}"

pd4castr_api_sdk/models.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Pd4castrBaseModel(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+
+class FileFormat(str, Enum):
+    json = "json"
+    csv = "csv"
+    parquet = "parquet"
+
+
+class TimeHorizon(Pd4castrBaseModel):
+    name: str
+    shortName: str
+    key: str
+
+
+class ModelMetadata(Pd4castrBaseModel):
+    description: str | None = None
+    releaseDate: str | None = None
+    resolution: str | None = None
+    baseComparisonModel: str | None = None
+
+
+class UISpecification(Pd4castrBaseModel):
+    seriesKey: bool | None = None
+    colours: list[str] | None = None
+
+
+class ColumnSpecification(Pd4castrBaseModel):
+    name: str
+    type: str
+    ui: UISpecification | None = None
+
+
+class SensitivitySpecification(Pd4castrBaseModel):
+    name: str
+    categories: list[str]
+
+
+class ForecastVariableSpecification(Pd4castrBaseModel):
+    name: str
+    shortName: str
+    key: str
+
+
+class Model(Pd4castrBaseModel):
+    id: str
+    modelGroupId: str
+    name: str
+    displayName: str
+    notes: str
+    revision: int
+    dockerImage: str
+    createdAt: str
+    horizon: TimeHorizon
+    modelMetadata: ModelMetadata
+    outputSpecification: list[ColumnSpecification]
+    tags: list[str]
+    sensitivities: list[SensitivitySpecification]
+    outputFileFormat: FileFormat
+    displayTimezone: str
+    forecastVariable: ForecastVariableSpecification
+
+
+class Organisation(Pd4castrBaseModel):
+    id: str
+    displayName: str
+    slug: str
+    domains: list[str]
+    permissions: list[str]
+
+
+class User(Pd4castrBaseModel):
+    id: str
+    email: str
+    organisation: Organisation | None = None

pd4castr_api_sdk/py.typed

@@ -0,0 +1 @@
+

pd4castr_api_sdk/transport.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+import httpx
+
+
+class Transport(Protocol):
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+    ) -> httpx.Response: ...
+
+    def close(self) -> None: ...
+
+
+@dataclass
+class HttpxSyncTransport:
+    client: httpx.Client
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+    ) -> httpx.Response:
+        return self.client.request(
+            method,
+            url,
+            headers=headers,
+            params=params,
+            json=json,
+            data=data,
+        )
+
+    def close(self) -> None:
+        self.client.close()

pd4castr_api_sdk-0.0.0.dist-info/METADATA

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: pd4castr-api-sdk
+Version: 0.0.0
+Summary: Python client for the pd4castr API
+Author: pd4castr
+License: MIT License (MIT)
+        
+        Copyright (c) 2026 Endgame Economics Pty Ltd t/as Endgame Analytics
+        <contact@endgameanalytics.com.au> https://endgameanalytics.com.au
+        
+        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.
+License-File: LICENSE.md
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic>=2.7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-sugar>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: respx>=0.21.1; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="./docs/assets/logo.png" alt="pdView logo" width="92">
+  
+  <h1>pd4castr API SDK</h1>
+  
+  <p>Official Python client for the pd4castr API</p>
+  
+  <p>
+    <a href="#installation">Installation</a> •
+    <a href="#quick-start">Quick Start</a> •
+    <a href="#usage">Usage</a> •
+    <a href="#api-reference">API Reference</a>
+  </p>
+</div>
+
+---
+
+## Installation
+
+> Requires Python >= 3.8
+
+```bash
+pip install pd4castr-api-sdk
+```
+
+## Quick Start
+
+Authenticate using your [pd4castr](https://v2.pd4castr.com.au) API credentials:
+
+```python
+from pd4castr_api_sdk import Client
+
+client = Client(
+    client_id="my-client-id",
+    client_secret="my-client-secret",
+)
+
+models = client.get_models()
+print(f"Found {len(models)} models")
+
+client.close()
+```
+
+### Context Manager
+
+The client implements context manager protocol for automatic cleanup:
+
+```python
+with Client(
+    client_id="my-client-id",
+    client_secret="my-client-secret",
+) as client:
+    models = client.get_models()
+```
+
+## Usage
+
+### List all Models
+
+[Reference: `Client.getModels`](#get_models)
+
+Retrieve all available models, optionally filtered by time horizon.
+
+```python
+# Get all models
+models = client.get_models()
+
+# Filter by time horizon
+models = client.get_models(time_horizon="day_ahead")
+```
+
+### Get a Model
+
+[Reference: `Client.get_model`](#clientgetmodel)
+
+Retrieve detailed information for a specific model.
+
+```python
+model = client.get_model("model-id")
+print(f"Model: {model.displayName}")
+```
+
+### Get Current User
+
+[Reference: `Client.get_current_user`](#clientgetcurrentuser)
+
+Retrieve information about the currently authenticated user.
+
+```python
+user = client.get_current_user()
+print(f"User: {user.email}")
+if user.organisation:
+    print(f"Organisation: {user.organisation.displayName}")
+```
+
+### Error Handling
+
+[Reference: Exceptions](#exceptions)
+
+Handle common error cases with typed exceptions.
+
+```python
+from pd4castr_api_sdk import NotFoundError, ApiError
+
+try:
+    model = client.get_model("invalid-id")
+except NotFoundError:
+    print("Model not found")
+except ApiError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## API Reference
+
+**Client:**
+
+- [`Client`](#client) - Main API client
+- [`Client#getModels`](#clientgetmodels) - List all models
+- [`Client#getModel`](#clientgetmodel) - Get a specific model
+- [`Client#getCurrentUser`](#clientgetcurrentuser) - Get the current user
+
+**Types:**
+
+- [`Model`](#model) - Model information and related types
+- [`User`](#user) - User information and related types
+
+**Exceptions:**
+
+- [`ApiError`](#apierror) - Base API error
+- [`NotFoundError`](#notfounderror) - Resource not found error
+
+### `Client`
+
+```python
+Client(
+    client_id: str,
+    client_secret: str,
+    timeout: float = 30.0,
+)
+```
+
+Main client class for interacting with the pd4castr API. Supports context
+manager protocol for automatic cleanup.
+
+**Configuration:**
+
+- `client_id` - OAuth client ID for authentication
+- `client_secret` - OAuth client secret for authentication
+- `timeout` - Request timeout in seconds (default: 30.0)
+
+### `Client#getModels`
+
+List all models with optional time horizon filter.
+
+`Client#getModels(*, time_horizon: str | None = None) -> list[`[`Model`](#model)`]`
+
+**Parameters:**
+
+- `time_horizon` (optional) - Filter models by time horizon:
+  - `day_ahead`
+  - `week_ahead`
+  - `quarterly`
+  - `historical`
+
+**Returns:** A list of [`Model`](#model) instances
+
+---
+
+### `Client#getModel`
+
+Get a specific model by ID.
+
+`Client#get_model(model_id: str) ->`[`Model`](#model)
+
+**Parameters:**
+
+- `model_id` - Unique model identifier
+
+**Returns:** [`Model`](#model) instance
+
+**Raises:**
+
+- [`NotFoundError`](#notfounderror) if model doesn't exist
+
+---
+
+### `Client#getCurrentUser`
+
+Get the currently authenticated user.
+
+`Client#get_current_user() ->`[`User`](#user)
+
+**Returns:** [`User`](#user) instance
+
+---
+
+### Types
+
+All types are implemented as
+[pydantic models](https://docs.pydantic.dev/latest/).
+
+#### `Model`
+
+```python
+class Model(BaseModel):
+    id: str
+    modelGroupId: str
+    name: str
+    displayName: str
+    displayTimezone: str
+    revision: int
+    dockerImage: str
+    notes: str
+    createdAt: str
+    horizon: TimeHorizon
+    modelMetadata: ModelMetadata
+    outputSpecification: list[ColumnSpecification]
+    tags: list[str]
+    sensitivities: list[SensitivitySpecification]
+    outputFileFormat: FileFormat
+    forecastVariable: ForecastVariableSpecification
+
+class TimeHorizon(BaseModel):
+    name: str
+    shortName: str
+    key: str
+
+class ModelMetadata(BaseModel):
+    description: str | None
+    releaseDate: str | None
+    resolution: str | None
+    baseComparisonModel: str | None
+
+class ColumnSpecification(BaseModel):
+    name: str
+    type: str
+    ui: UISpecification | None
+
+class UISpecification(BaseModel):
+    seriesKey: bool | None
+    colours: list[str] | None
+
+class SensitivitySpecification(BaseModel):
+    name: str
+    categories: list[str]
+
+class ForecastVariableSpecification(BaseModel):
+    name: str
+    shortName: str
+    key: str
+
+class FileFormat(Enum):
+    json = "json"
+    csv = "csv"
+    parquet = "parquet"
+```
+
+#### `User`
+
+```python
+class User(BaseModel):
+    id: str
+    email: str
+    organisation: Organisation | None
+
+class Organisation(BaseModel):
+    id: str
+    displayName: str
+    slug: str
+    domains: list[str]
+    permissions: list[str]
+```
+
+### Exceptions
+
+#### `ApiError`
+
+Base exception for API errors.
+
+```python
+class ApiError(Exception):
+    status_code: int
+    message: str
+    body: dict | None
+```
+
+#### `NotFoundError`
+
+Resource not found error (HTTP 404). Inherits from [`ApiError`](#apierror).
+
+```python
+class NotFoundError(ApiError):
+    pass
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, testing, and
+contribution guidelines.

pd4castr_api_sdk-0.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pd4castr_api_sdk/__init__.py,sha256=ZN-RwRsRe74lMXzYMth9tEeWSrm8EDJlu_cQV5wgTGY,231
+pd4castr_api_sdk/auth.py,sha256=eLZIzHvH5AW8ld_LKbNJTbjECyhYAs-snWnMkSi2ivw,2192
+pd4castr_api_sdk/client.py,sha256=490kYHScEAnBm77d7FNk32zsnI2mECBw4UnneugMJEU,3530
+pd4castr_api_sdk/config.py,sha256=LGP8xyfkdJNbMv4f9VYTMSjsQ6o2-BM7oJtIvs1UCxk,765
+pd4castr_api_sdk/errors.py,sha256=c_NwtrDG2IRHdzAhFGd4L4iG1JHMyFwxSXfDtbHuVow,536
+pd4castr_api_sdk/models.py,sha256=BBM5KDWKZkytVSuZPxmN-GILKvSLJwpfoTnBlXbnLc4,1684
+pd4castr_api_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+pd4castr_api_sdk/transport.py,sha256=caYhcCrig396wSgR4sF1tIGWYI3Ma04Jl9NDUpp22Y8,1022
+pd4castr_api_sdk-0.0.0.dist-info/METADATA,sha256=vMYZoqHhzl6hVNiKezdeP4rxORdw1UTkzbCuF-Elyb4,7765
+pd4castr_api_sdk-0.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pd4castr_api_sdk-0.0.0.dist-info/licenses/LICENSE.md,sha256=6UsCUcnUXgK2y-9gh9HBt7c9gl8VjONd-RVJHMSAmm8,1177
+pd4castr_api_sdk-0.0.0.dist-info/RECORD,,

pd4castr_api_sdk-0.0.0.dist-info/WHEEL

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

pd4castr_api_sdk-0.0.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License (MIT)
+
+Copyright (c) 2026 Endgame Economics Pty Ltd t/as Endgame Analytics
+<contact@endgameanalytics.com.au> https://endgameanalytics.com.au
+
+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.