joltio 0.1.0__tar.gz

joltio-0.1.0/.github/workflows/joltio-publish.yml

@@ -0,0 +1,24 @@
+name: Publish joltio
+
+on:
+  push:
+    tags:
+      - joltio-v*
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build joltio from the tag
+        run: |
+          python -m pip install build
+          python -m build --sdist --wheel --outdir dist
+      - name: Publish joltio to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

joltio-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.egg
+.pytest_cache/
+.ruff_cache/

joltio-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: joltio
+Version: 0.1.0
+Summary: Python client for Joltio Data
+Project-URL: Homepage, https://joltio.app/data
+Project-URL: Documentation, https://joltio.app/data/docs
+Project-URL: Repository, https://github.com/datons/python-joltio
+Project-URL: Issues, https://github.com/datons/python-joltio/issues
+Author-email: Jesús López <jesus.lopez@datons.com>
+License-Expression: MIT
+Keywords: api,data,datons,electricity,energy,esios,spain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: polars>=1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# joltio
+
+Python client for [Joltio Data](https://joltio.app/data). The canonical endpoint is `https://api.joltio.app/data`.
+
+## Installation
+
+```bash
+pip install joltio
+```
+
+## Quick start
+
+```python
+from joltio import Client
+
+client = Client(api_key="jol_live_...")
+
+# Query the electricity market clearing price
+df = client.data.query(
+    "SELECT datetime, price "
+    "FROM omie.prices "
+    "WHERE country = 'ES' AND datetime >= now() - INTERVAL 7 DAY "
+    "LIMIT 100"
+)
+
+# Dataset metadata (schema, programs, stats)
+meta = client.data.metadata()
+
+# Search for units, companies, technologies
+results = client.data.search("iberdrola")
+```
+
+## Authentication
+
+Request a personal Data key from your Joltio workspace administrator.
+
+Pass it directly or set `JOLTIO_API_KEY`. `DATONS_API_KEY` remains a fallback during migration.
+
+```bash
+export JOLTIO_API_KEY="jol_live_..."
+```
+
+```python
+from joltio import Client
+
+client = Client()  # picks up JOLTIO_API_KEY
+```

joltio-0.1.0/README.md

@@ -0,0 +1,47 @@
+# joltio
+
+Python client for [Joltio Data](https://joltio.app/data). The canonical endpoint is `https://api.joltio.app/data`.
+
+## Installation
+
+```bash
+pip install joltio
+```
+
+## Quick start
+
+```python
+from joltio import Client
+
+client = Client(api_key="jol_live_...")
+
+# Query the electricity market clearing price
+df = client.data.query(
+    "SELECT datetime, price "
+    "FROM omie.prices "
+    "WHERE country = 'ES' AND datetime >= now() - INTERVAL 7 DAY "
+    "LIMIT 100"
+)
+
+# Dataset metadata (schema, programs, stats)
+meta = client.data.metadata()
+
+# Search for units, companies, technologies
+results = client.data.search("iberdrola")
+```
+
+## Authentication
+
+Request a personal Data key from your Joltio workspace administrator.
+
+Pass it directly or set `JOLTIO_API_KEY`. `DATONS_API_KEY` remains a fallback during migration.
+
+```bash
+export JOLTIO_API_KEY="jol_live_..."
+```
+
+```python
+from joltio import Client
+
+client = Client()  # picks up JOLTIO_API_KEY
+```

joltio-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "joltio"
+version = "0.1.0"
+description = "Python client for Joltio Data"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Jesús López", email = "jesus.lopez@datons.com" },
+]
+keywords = ["datons", "energy", "esios", "electricity", "spain", "api", "data"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "httpx>=0.27",
+    "polars>=1.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.0"]
+
+[project.scripts]
+joltio = "joltio.cli:main"
+
+[project.urls]
+Homepage = "https://joltio.app/data"
+Documentation = "https://joltio.app/data/docs"
+Repository = "https://github.com/datons/python-joltio"
+Issues = "https://github.com/datons/python-joltio/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/joltio"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

joltio-0.1.0/src/joltio/__init__.py

@@ -0,0 +1,19 @@
+"""Joltio — Python client for Joltio Data."""
+
+from joltio.client import Client
+from joltio.exceptions import (
+    AuthenticationError,
+    DatonsError,
+    JoltioError,
+    QueryError,
+    RateLimitError,
+)
+
+__all__ = [
+    "Client",
+    "AuthenticationError",
+    "DatonsError",
+    "JoltioError",
+    "QueryError",
+    "RateLimitError",
+]

joltio-0.1.0/src/joltio/cli.py

@@ -0,0 +1,111 @@
+"""Joltio CLI — query data and manage authentication.
+
+Usage:
+    joltio auth set <KEY>     Save API key to ~/.config/joltio/config.toml
+    joltio auth show          Show the saved key (masked)
+    joltio auth remove        Remove the saved key
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from joltio.config import read_api_key, remove_api_key, write_api_key
+
+def _data(args: argparse.Namespace) -> None:
+    from joltio import Client
+    with Client() as client:
+        if args.data_command == 'query':
+            result = client.data.query_raw(args.sql).model_dump()
+        elif args.data_command == 'coverage':
+            result = client.data.coverage(args.table)
+        elif args.data_command == 'search':
+            result = client.data.search(args.query).model_dump()
+        else:
+            result = client.data.metadata().model_dump()
+        print(json.dumps(result, default=str))
+
+
+def _auth_set(args: argparse.Namespace) -> None:
+    write_api_key(args.key)
+    masked = args.key[:8] + "..." + args.key[-4:] if len(args.key) > 12 else args.key[:4] + "..."
+    print(f"API key saved: {masked}")
+
+
+def _auth_show(_args: argparse.Namespace) -> None:
+    key = read_api_key()
+    if not key:
+        print("No API key configured.")
+        print("Set one with: joltio auth set <KEY>")
+        sys.exit(1)
+    masked = key[:8] + "..." + key[-4:] if len(key) > 12 else key[:4] + "..."
+    print(f"API key: {masked}")
+
+
+def _auth_remove(_args: argparse.Namespace) -> None:
+    if remove_api_key():
+        print("API key removed.")
+    else:
+        print("No API key to remove.")
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="joltio",
+        description="Joltio Data CLI",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    data_parser = subparsers.add_parser('data', help='Query Joltio Data')
+    data_sub = data_parser.add_subparsers(dest='data_command', required=True)
+    query = data_sub.add_parser('query')
+    query.add_argument('sql')
+    query.set_defaults(func=_data)
+    search = data_sub.add_parser('search')
+    search.add_argument('query')
+    search.set_defaults(func=_data)
+    coverage = data_sub.add_parser('coverage')
+    coverage.add_argument('--table')
+    coverage.set_defaults(func=_data)
+    metadata = data_sub.add_parser('metadata')
+    metadata.set_defaults(func=_data)
+
+    # joltio auth
+    auth_parser = subparsers.add_parser("auth", help="Manage API key authentication")
+    auth_sub = auth_parser.add_subparsers(dest="auth_command")
+
+    # joltio auth set <KEY>
+    set_parser = auth_sub.add_parser("set", help="Save API key")
+    set_parser.add_argument("key", help="Your Joltio API key")
+    set_parser.set_defaults(func=_auth_set)
+
+    # joltio auth show
+    show_parser = auth_sub.add_parser("show", help="Show saved API key (masked)")
+    show_parser.set_defaults(func=_auth_show)
+
+    # joltio auth remove
+    remove_parser = auth_sub.add_parser("remove", help="Remove saved API key")
+    remove_parser.set_defaults(func=_auth_remove)
+
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "auth" and not args.auth_command:
+        auth_parser.print_help()
+        sys.exit(0)
+
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

joltio-0.1.0/src/joltio/client.py

@@ -0,0 +1,142 @@
+"""Joltio API client.
+
+Central entry point that lazily initializes product-specific managers.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from joltio.exceptions import AuthenticationError, DatonsError, QueryError, RateLimitError
+
+DEFAULT_BASE_URL = "https://api.joltio.app"
+DEFAULT_TIMEOUT = 30.0
+
+
+class Client:
+    """Client for Joltio Data APIs.
+
+    Usage::
+
+        from joltio import Client
+
+        client = Client(api_key="jol_live_...")
+        df = client.data.query("SELECT unit, energy FROM esios.archives_i90 WHERE program='PDBF' LIMIT 10")
+
+    Or with context manager::
+
+        with Client(api_key="jol_live_...") as client:
+            df = client.data.query("SELECT ...")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        token: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.token = api_key or token or os.getenv("JOLTIO_API_KEY") or os.getenv("DATONS_API_KEY")
+        if not self.token:
+            from joltio.config import read_api_key
+
+            self.token = read_api_key()
+        if not self.token:
+            raise DatonsError(
+                "API key required. Pass api_key=, set JOLTIO_API_KEY, or run: joltio auth set <KEY>"
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "X-API-Key": self.token,
+                "User-Agent": "python-joltio/0.1.0",
+            },
+            timeout=self.timeout,
+        )
+
+        # Lazy-initialized managers
+        self._esios: Any = None
+
+    @property
+    def data(self):
+        return self.esios
+
+    @property
+    def esios(self):
+        """Access ESIOS preprocessed data (I90, market programs)."""
+        if self._esios is None:
+            from joltio.esios.manager import EsiosDataManager
+
+            self._esios = EsiosDataManager(self)
+        return self._esios
+
+    # -- HTTP primitives (used by managers) ------------------------------------
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        """Issue a GET request."""
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> dict:
+        """Issue a POST request."""
+        return self._request("POST", path, json=json)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> dict:
+        """Execute an HTTP request with error handling."""
+        try:
+            response = self._http.request(method, path, params=params, json=json)
+        except httpx.ConnectError as exc:
+            raise DatonsError(f"Connection failed: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise DatonsError(f"Request timed out: {exc}") from exc
+
+        if response.status_code == 401:
+            raise AuthenticationError()
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            # Parse structured error body from server
+            try:
+                body = response.json()
+                detail = body.get("detail", body)
+            except Exception:
+                detail = None
+            tier = detail.get("tier") if isinstance(detail, dict) else None
+            raise RateLimitError(
+                int(retry_after) if retry_after else None,
+                tier=tier,
+                detail=detail,
+            )
+        if response.status_code >= 400:
+            detail = response.text[:500]
+            raise QueryError(response.status_code, detail)
+
+        return response.json()
+
+    # -- Lifecycle -------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection."""
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        masked = self.token[:8] + "..." if self.token else "None"
+        return f"Client(token='{masked}', base_url='{self.base_url}')"

joltio-0.1.0/src/joltio/config.py

@@ -0,0 +1,91 @@
+"""Configuration file management for Joltio CLI.
+
+Reads and writes API keys to ~/.config/joltio/config.toml.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "joltio"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+
+def _parse_toml(text: str) -> dict[str, dict[str, str]]:
+    """Minimal TOML parser — handles [section] and key = "value" pairs."""
+    result: dict[str, dict[str, str]] = {}
+    current_section: str | None = None
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith("[") and stripped.endswith("]"):
+            current_section = stripped[1:-1].strip()
+            result.setdefault(current_section, {})
+        elif "=" in stripped and current_section is not None:
+            key, _, value = stripped.partition("=")
+            value = value.strip().strip('"').strip("'")
+            result[current_section][key.strip()] = value
+    return result
+
+
+def _write_toml(data: dict[str, dict[str, str]]) -> str:
+    """Serialize a dict of sections to minimal TOML."""
+    lines: list[str] = []
+    for section, entries in data.items():
+        lines.append(f"[{section}]")
+        for key, value in entries.items():
+            lines.append(f'{key} = "{value}"')
+        lines.append("")
+    return "\n".join(lines)
+
+
+def read_api_key() -> str | None:
+    """Read the API key from the config file, or None if not set."""
+    if not CONFIG_FILE.exists():
+        return None
+    try:
+        text = CONFIG_FILE.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    data = _parse_toml(text)
+    return data.get("auth", {}).get("api_key") or None
+
+
+def write_api_key(api_key: str) -> None:
+    """Write the API key to the config file, preserving other sections."""
+    data: dict[str, dict[str, str]] = {}
+    if CONFIG_FILE.exists():
+        try:
+            text = CONFIG_FILE.read_text(encoding="utf-8")
+            data = _parse_toml(text)
+        except OSError:
+            pass
+    data.setdefault("auth", {})
+    data["auth"]["api_key"] = api_key
+
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(_write_toml(data), encoding="utf-8")
+    CONFIG_FILE.chmod(0o600)
+
+
+def remove_api_key() -> bool:
+    """Remove the API key from the config file. Returns True if it existed."""
+    if not CONFIG_FILE.exists():
+        return False
+    try:
+        text = CONFIG_FILE.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    data = _parse_toml(text)
+    if "auth" not in data or "api_key" not in data["auth"]:
+        return False
+    del data["auth"]["api_key"]
+    if not data["auth"]:
+        del data["auth"]
+    if data:
+        CONFIG_FILE.write_text(_write_toml(data), encoding="utf-8")
+    else:
+        CONFIG_FILE.unlink(missing_ok=True)
+    return True

joltio-0.1.0/src/joltio/esios/__init__.py

@@ -0,0 +1,21 @@
+"""ESIOS Data — preprocessed Spanish electricity market data from ClickHouse."""
+
+from joltio.esios.manager import EsiosDataManager
+from joltio.esios.models import (
+    ColumnInfo,
+    DimensionResult,
+    MetadataResult,
+    ProgramInfo,
+    QueryResult,
+    SearchResult,
+)
+
+__all__ = [
+    "EsiosDataManager",
+    "ColumnInfo",
+    "DimensionResult",
+    "MetadataResult",
+    "ProgramInfo",
+    "QueryResult",
+    "SearchResult",
+]