energyscope-client 0.2.0__tar.gz

energyscope_client-0.2.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: energyscope-client
+Version: 0.2.0
+Summary: Python client for EnergyScope energy market data (Arrow Flight)
+Author-email: David Linton <contact@energyscope.io>
+License: MIT
+Project-URL: Homepage, https://energyscope.io
+Project-URL: Documentation, https://energyscope.io/connect
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: polars>=0.20
+Provides-Extra: demo
+Requires-Dist: streamlit>=1.30; extra == "demo"
+Requires-Dist: plotly>=5.0; extra == "demo"
+
+Python client for EnergyScope (energyscope.io) — energy market time series over Arrow Flight. `import energyscope as es; es.Client("YOUR_API_KEY").get("PET.RWTC.D", start="2024-01-01")`

energyscope_client-0.2.0/energyscope/__init__.py

@@ -0,0 +1,6 @@
+"""EnergyScope Python client — Arrow Flight interface to energy market data."""
+
+from .client import Client, SERVERS
+
+__all__ = ["Client", "SERVERS"]
+__version__ = "0.1.0"

energyscope_client-0.2.0/energyscope/client.py

@@ -0,0 +1,227 @@
+"""EnergyScope Flight client."""
+
+import json
+from typing import Optional
+
+import pyarrow as pa
+import pyarrow.flight as flight
+import polars as pl
+
+SERVERS = {
+    "data": "grpc+tls://data.energyscope.io:443",
+    "s0": "grpc://s0.energyscope.io:8815",
+    "s1": "grpc://s1.energyscope.io:8815",
+    "s2": "grpc://s2.energyscope.io:8815",
+    "aws": "grpc://18.198.51.233:8815",
+    "local": "grpc://localhost:8815",
+    "lan": "grpc://192.168.132.91:8815",
+    "vps": "grpc://147.93.89.98:8815",
+}
+
+
+class Client:
+    """Arrow Flight client for EnergyScope.
+
+    Usage:
+        import energyscope as es
+        client = es.Client()                    # default: data (Cloudflare)
+        client = es.Client(server="s0")         # MS-02 direct
+        client = es.Client(server="local")      # localhost
+
+        df = client.get("PET.RWTC.D", start="2024-01-01")
+        df = client.get(["PET.RWTC.D", "PET.RBRTE.D"], start="2024-01-01")
+        results = client.search("crude oil")
+        latest = client.latest("PET.RWTC.D")
+        health = client.health()
+    """
+
+    def __init__(self, api_key: Optional[str] = None, server: str = "data", address: Optional[str] = None):
+        """Connect to an EnergyScope Flight server.
+
+        Args:
+            api_key: API key for authentication (optional for demo/dev)
+            server: Preset name ("data", "s0", "s1", "s2", "local", "usb4", "vps")
+            address: Full address override (e.g. "grpc://myserver:8815")
+        """
+        if address:
+            self._address = address
+        elif server in SERVERS:
+            self._address = SERVERS[server]
+        else:
+            raise ValueError(f"Unknown server '{server}'. Choose from: {list(SERVERS.keys())}")
+
+        self._api_key = api_key
+        self._client: Optional[flight.FlightClient] = None
+
+    @property
+    def address(self) -> str:
+        return self._address
+
+    def _get_client(self) -> flight.FlightClient:
+        if self._client is None:
+            self._client = flight.connect(self._address)
+            if self._api_key:
+                # Handshake returns a bearer token header pair for subsequent calls
+                self._auth_header = self._client.authenticate_basic_token(self._api_key, "")
+            else:
+                self._auth_header = None
+        return self._client
+
+    def _call_opts(self) -> flight.FlightCallOptions:
+        """Get call options with auth header if authenticated."""
+        if self._auth_header:
+            return flight.FlightCallOptions(headers=[self._auth_header])
+        return flight.FlightCallOptions()
+
+    def _action(self, action_type: str, body: bytes = b"") -> str:
+        """Execute a Flight action and return the response body as string."""
+        client = self._get_client()
+        action = flight.Action(action_type, body)
+        results = list(client.do_action(action, self._call_opts()))
+        if results:
+            return results[0].body.to_pybytes().decode()
+        return ""
+
+    def get(
+        self,
+        series: str | list[str],
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+        pivot: bool = False,
+        fill: Optional[str] = None,
+    ) -> pl.DataFrame:
+        """Fetch time series data.
+
+        Args:
+            series: Series ID or list of IDs (e.g. "PET.RWTC.D")
+            start: Start date "YYYY-MM-DD" (optional)
+            end: End date "YYYY-MM-DD" (optional)
+            pivot: If True, pivot to wide format (dates as rows, series as columns)
+            fill: Fill strategy for pivoted data. Options:
+                "ffill" — forward-fill last known value (like Bloomberg BDH)
+                "null"  — leave nulls (default)
+                A number (e.g. 0) — fill with that value
+
+        Returns:
+            Polars DataFrame. Long format (series_id, period, value) by default,
+            or wide format (period as index, one column per series) if pivot=True.
+        """
+        if isinstance(series, str):
+            series = [series]
+
+        ticket_data = {"series": series}
+        if start:
+            ticket_data["start"] = start
+        if end:
+            ticket_data["end"] = end
+
+        client = self._get_client()
+        ticket = flight.Ticket(json.dumps(ticket_data).encode())
+        reader = client.do_get(ticket, self._call_opts())
+        table = reader.read_all()
+        df = pl.from_arrow(table)
+
+        if pivot and len(df) > 0:
+            df = df.pivot(on="series_id", index="period", values="value").sort("period")
+            if fill == "ffill":
+                df = df.fill_null(strategy="forward")
+            elif fill is not None and fill != "null":
+                try:
+                    df = df.fill_null(float(fill))
+                except (ValueError, TypeError):
+                    pass
+
+        return df
+
+    def get_arrow(
+        self,
+        series: str | list[str],
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+    ) -> pa.Table:
+        """Fetch time series data as Arrow table (zero-copy).
+
+        Same as get() but returns pyarrow.Table instead of pandas DataFrame.
+        """
+        if isinstance(series, str):
+            series = [series]
+
+        ticket_data = {"series": series}
+        if start:
+            ticket_data["start"] = start
+        if end:
+            ticket_data["end"] = end
+
+        client = self._get_client()
+        ticket = flight.Ticket(json.dumps(ticket_data).encode())
+        reader = client.do_get(ticket, self._call_opts())
+        return reader.read_all()
+
+    def search(self, query: str) -> list[dict]:
+        """Search series metadata by keyword.
+
+        Returns:
+            List of dicts with: series_id, name, f (frequency), units
+        """
+        body = self._action("search", query.encode())
+        return json.loads(body) if body else []
+
+    def latest(self, series: str | list[str]) -> list[dict]:
+        """Get latest value for one or more series.
+
+        Returns:
+            List of dicts with: series_id, period, value, name, units
+        """
+        if isinstance(series, str):
+            series = [series]
+        body = self._action("latest", json.dumps({"series": series}).encode())
+        return json.loads(body) if body else []
+
+    def health(self) -> dict:
+        """Check server health.
+
+        Returns:
+            Dict with: status, series_count, data_rows
+        """
+        body = self._action("healthcheck")
+        return json.loads(body) if body else {}
+
+    def browse(self, category_id: Optional[int] = None) -> dict | list:
+        """Browse category tree.
+
+        Args:
+            category_id: Category ID to browse into, or None for roots.
+
+        Returns:
+            Root list or category dict with children and series.
+        """
+        req = {"id": category_id} if category_id is not None else {}
+        body = self._action("browse", json.dumps(req).encode())
+        return json.loads(body) if body else []
+
+    def max_date(self, series: str | list[str]) -> Optional[str]:
+        """Get the latest data date across series.
+
+        Returns:
+            Date string "YYYY-MM-DD" or None
+        """
+        if isinstance(series, str):
+            series = [series]
+        body = self._action("max_date", json.dumps({"series": series}).encode())
+        result = json.loads(body) if body else {}
+        return result.get("max_date")
+
+    def close(self):
+        """Close the connection."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def __repr__(self):
+        return f"energyscope.Client('{self._address}')"

energyscope_client-0.2.0/energyscope_client.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: energyscope-client
+Version: 0.2.0
+Summary: Python client for EnergyScope energy market data (Arrow Flight)
+Author-email: David Linton <contact@energyscope.io>
+License: MIT
+Project-URL: Homepage, https://energyscope.io
+Project-URL: Documentation, https://energyscope.io/connect
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: polars>=0.20
+Provides-Extra: demo
+Requires-Dist: streamlit>=1.30; extra == "demo"
+Requires-Dist: plotly>=5.0; extra == "demo"
+
+Python client for EnergyScope (energyscope.io) — energy market time series over Arrow Flight. `import energyscope as es; es.Client("YOUR_API_KEY").get("PET.RWTC.D", start="2024-01-01")`

energyscope_client-0.2.0/energyscope_client.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+pyproject.toml
+energyscope/__init__.py
+energyscope/client.py
+energyscope_client.egg-info/PKG-INFO
+energyscope_client.egg-info/SOURCES.txt
+energyscope_client.egg-info/dependency_links.txt
+energyscope_client.egg-info/requires.txt
+energyscope_client.egg-info/top_level.txt

energyscope_client-0.2.0/energyscope_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

energyscope_client-0.2.0/energyscope_client.egg-info/requires.txt

@@ -0,0 +1,6 @@
+pyarrow>=14.0
+polars>=0.20
+
+[demo]
+streamlit>=1.30
+plotly>=5.0

energyscope_client-0.2.0/energyscope_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+energyscope

energyscope_client-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# PyPI name is energyscope-client (the bare "energyscope" name belongs to
+# EPFL's energy-system modeling tool); the IMPORT name stays energyscope.
+name = "energyscope-client"
+version = "0.2.0"
+description = "Python client for EnergyScope energy market data (Arrow Flight)"
+readme = { text = "Python client for EnergyScope (energyscope.io) — energy market time series over Arrow Flight. `import energyscope as es; es.Client(\"YOUR_API_KEY\").get(\"PET.RWTC.D\", start=\"2024-01-01\")`", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "David Linton", email = "contact@energyscope.io" }]
+dependencies = [
+    "pyarrow>=14.0",
+    "polars>=0.20",
+]
+
+[project.urls]
+Homepage = "https://energyscope.io"
+Documentation = "https://energyscope.io/connect"
+
+[project.optional-dependencies]
+demo = ["streamlit>=1.30", "plotly>=5.0"]
+
+[tool.setuptools]
+packages = ["energyscope"]

energyscope_client-0.2.0/setup.cfg

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