joltio 0.1.0__py3-none-any.whl

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/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/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/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/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",
+]

joltio/esios/manager.py

@@ -0,0 +1,237 @@
+"""ESIOS Data manager — preprocessed I90 market data from ClickHouse.
+
+Endpoints:
+    /data/metadata  — schema, programs, global stats
+    /data/query     — read-only SQL queries
+    /data/search    — fuzzy search across dimensions
+    /data/dimensions — unit/company/technology lookups
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+import polars as pl
+
+from joltio.esios.models import (
+    DimensionResult,
+    MetadataResult,
+    QueryResult,
+    SearchResult,
+)
+
+if TYPE_CHECKING:
+    from joltio.client import Client
+
+API_PREFIX = "/data"
+
+Backend = Literal["polars", "pandas"]
+
+
+class EsiosDataManager:
+    """Manager for ESIOS preprocessed data.
+
+    Usage::
+
+        from joltio import Client
+
+        client = Client(token="esd_live_...")
+
+        # SQL query → Polars DataFrame (default)
+        df = client.esios.query(
+            "SELECT unit, datetime, energy FROM esios.archives_i90 "
+            "WHERE program='PDBF' LIMIT 100"
+        )
+
+        # SQL query → pandas DataFrame
+        df = client.esios.query("SELECT ...", backend="pandas")
+
+        # Metadata (schema, programs, stats)
+        meta = client.esios.metadata()
+
+        # Search for dimension values
+        results = client.esios.search("iberdrola")
+
+        # Dimension lookup
+        techs = client.esios.dimensions("technology")
+    """
+
+    def __init__(self, client: Client):
+        self._client = client
+
+    def query(
+        self,
+        sql: str,
+        *,
+        limit: int | None = None,
+        backend: Backend = "polars",
+    ) -> Any:
+        """Execute a read-only SQL query and return a DataFrame.
+
+        Args:
+            sql: SQL SELECT query against ``esios.archives_i90`` (per-program
+                I90 dispatch) or ``esios.indicators`` (time series).
+            limit: Max rows to return. Server enforces 50 for raw queries,
+                10000 for aggregated queries.
+            backend: DataFrame backend — ``"polars"`` (default) or ``"pandas"``.
+                Pandas requires ``pip install joltio[pandas]``.
+
+        Returns:
+            Polars or pandas DataFrame with the query results.
+
+        Raises:
+            QueryError: On invalid SQL, timeout, or write attempt.
+        """
+        body: dict = {"sql": sql}
+        if limit is not None:
+            body["limit"] = limit
+
+        data = self._client.post(f"{API_PREFIX}/query", json=body)
+        result = QueryResult.model_validate(data)
+
+        if backend == "pandas":
+            return self._to_pandas(result)
+        return self._to_polars(result)
+
+    def query_raw(self, sql: str, *, limit: int | None = None) -> QueryResult:
+        """Execute a query and return the raw API response (no DataFrame conversion).
+
+        Useful when you need metadata (query_type, truncated, max_rows_applied)
+        or want to handle the data yourself.
+        """
+        body: dict = {"sql": sql}
+        if limit is not None:
+            body["limit"] = limit
+
+        data = self._client.post(f"{API_PREFIX}/query", json=body)
+        return QueryResult.model_validate(data)
+
+    def metadata(
+        self,
+        *,
+        lang: Literal["en", "es"] = "en",
+        detail: Literal["summary", "full"] = "summary",
+    ) -> MetadataResult:
+        """Get dataset metadata: schema, programs, and global statistics.
+
+        Args:
+            lang: Language for column descriptions ('en' or 'es').
+            detail: 'summary' for lightweight overview (~2.7K tokens),
+                'full' for complete stats + categorical values (~5.7K tokens).
+        """
+        data = self._client.get(
+            f"{API_PREFIX}/metadata",
+            params={"lang": lang, "detail": detail},
+        )
+        return MetadataResult.model_validate(data)
+
+    def search(
+        self,
+        q: str,
+        *,
+        column: str | None = None,
+    ) -> SearchResult:
+        """Fuzzy search across all metadata dimensions.
+
+        Searches unit codes, unit names, company names, technologies,
+        and other categorical values.
+
+        Args:
+            q: Search query (case-insensitive substring match).
+            column: Optional column to limit search to.
+
+        Examples::
+
+            client.esios.search("iber")      # → Iberdrola units/companies
+            client.esios.search("ciclo")      # → Ciclo Combinado technology
+            client.esios.search("CTGN")       # → unit codes CTGN1, CTGN2...
+        """
+        params: dict = {"q": q}
+        if column:
+            params["column"] = column
+
+        data = self._client.get(f"{API_PREFIX}/search", params=params)
+        return SearchResult.model_validate(data)
+
+    def dimensions(
+        self,
+        dim: Literal["unit", "company", "technology"] = "unit",
+        *,
+        detail: Literal["summary", "full"] = "summary",
+        q: str | None = None,
+    ) -> DimensionResult:
+        """Get dimension values (unit registry, companies, technologies).
+
+        Args:
+            dim: Dimension to query.
+            detail: 'summary' for flat list, 'full' for enriched records.
+            q: Optional fuzzy filter.
+        """
+        params: dict = {"dim": dim, "detail": detail}
+        if q:
+            params["q"] = q
+
+        data = self._client.get(f"{API_PREFIX}/dimensions", params=params)
+        return DimensionResult.model_validate(data)
+
+    def health(self) -> bool:
+        """Check if the ESIOS Data API is reachable."""
+        try:
+            data = self._client.get(f"{API_PREFIX}/health")
+            return data.get("status") == "ok"
+        except Exception:
+            return False
+
+    def coverage(self, table: str | None = None) -> list[dict]:
+        return self._client.get(f"{API_PREFIX}/coverage", params={"table": table} if table else None)
+
+    # -- Internal helpers ------------------------------------------------------
+
+    @staticmethod
+    def _to_polars(result: QueryResult) -> pl.DataFrame:
+        """Convert a QueryResult to a Polars DataFrame."""
+        col_names = [c.name for c in result.columns]
+        schema: dict[str, pl.DataType] = {}
+
+        for col in result.columns:
+            col_type = col.type.lower()
+            if "datetime" in col_type:
+                schema[col.name] = pl.Datetime("ms")
+            elif "date" in col_type:
+                schema[col.name] = pl.Date
+            elif "float" in col_type:
+                schema[col.name] = pl.Float64
+            elif "int" in col_type or "uint" in col_type:
+                schema[col.name] = pl.Int64
+            else:
+                schema[col.name] = pl.Utf8
+
+        data = dict(zip(col_names, zip(*result.rows))) if result.rows else {c: [] for c in col_names}
+        df = pl.DataFrame(data, schema=schema)
+        return df
+
+    @staticmethod
+    def _to_pandas(result: QueryResult) -> Any:
+        """Convert a QueryResult to a pandas DataFrame."""
+        try:
+            import pandas as pd
+        except ImportError:
+            raise ImportError(
+                "pandas is required for backend='pandas'. "
+                "Install it with: pip install joltio[pandas]"
+            ) from None
+
+        col_names = [c.name for c in result.columns]
+        df = pd.DataFrame(result.rows, columns=col_names)
+
+        for col in result.columns:
+            if "datetime" in col.type.lower() or "date" in col.type.lower():
+                try:
+                    df[col.name] = pd.to_datetime(df[col.name])
+                except Exception:
+                    pass
+
+        return df
+
+    def __repr__(self) -> str:
+        return f"EsiosDataManager(base_url='{self._client.base_url}{API_PREFIX}')"

joltio/esios/models.py

@@ -0,0 +1,121 @@
+"""Pydantic models for ESIOS Data API responses."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class ColumnInfo(BaseModel):
+    """Column metadata from schema."""
+
+    name: str
+    type: str
+    nullable: bool = False
+    default: str | None = None
+    description: str = ""
+
+
+class SchemaInfo(BaseModel):
+    """Table schema information."""
+
+    table: str
+    database: str
+    engine: str | None = None
+    columns: list[ColumnInfo]
+
+
+class ProgramStats(BaseModel):
+    """Per-program statistics."""
+
+    row_count: int
+    first_date: str
+    last_date: str
+    unique_units: int
+    energy_min: float | None = None
+    energy_max: float | None = None
+    energy_avg: float | None = None
+    price_min: float | None = None
+    price_max: float | None = None
+    price_avg: float | None = None
+    detected_resolution: str
+    columns_used: list[str]
+
+
+class ProgramInfo(BaseModel):
+    """Market program metadata."""
+
+    code: str
+    name: str
+    description: str
+    energy_source: str = ""
+    price_source: str = ""
+    energy_unit: str
+    aggregation: str = ""
+    stats: ProgramStats | None = None
+    # Summary-only fields
+    columns_used: list[str] = []
+    row_count: int = 0
+    date_range: list[str] = []
+
+
+class GlobalStats(BaseModel):
+    """Global dataset statistics."""
+
+    total_rows: int
+    date_min: str
+    date_max: str
+    unique_units: int
+    unique_companies: int
+
+
+class MetadataResult(BaseModel):
+    """Full metadata response."""
+
+    schema_info: SchemaInfo
+    programs: list[ProgramInfo]
+    global_stats: GlobalStats | None = None
+    categorical_values: dict[str, list[str]] = {}
+
+
+class QueryColumn(BaseModel):
+    """Column in a query result."""
+
+    name: str
+    type: str
+
+
+class QueryResult(BaseModel):
+    """SQL query result."""
+
+    columns: list[QueryColumn]
+    rows: list[list]
+    row_count: int
+    query_type: str
+    max_rows_applied: int
+    truncated: bool
+
+
+class SearchResult(BaseModel):
+    """Search response.
+
+    Shape as returned by ``/esios-data/search`` (May 2026 backend):
+    ``{query, count, results, hints, offset}``. ``results`` is a list of
+    matching records (dimension rows or domain-catalog entries depending on
+    the params sent).
+    """
+
+    query: str
+    count: int = 0
+    results: list[dict] = []
+    hints: list[str] | None = None
+    offset: int = 0
+
+
+class DimensionResult(BaseModel):
+    """Dimension lookup response."""
+
+    dimension: str = ""
+    detail: str = ""
+    count: int = 0
+    values: list[str] = []
+    records: list[dict] = []

joltio/exceptions.py

@@ -0,0 +1,57 @@
+"""Joltio client exceptions, including the legacy DatonsError alias."""
+
+
+class JoltioError(Exception):
+    """Base exception for all Joltio client errors."""
+
+
+DatonsError = JoltioError
+
+
+class AuthenticationError(DatonsError):
+    """Invalid or missing API key."""
+
+    def __init__(self, message: str = "Invalid or missing API key."):
+        super().__init__(message)
+
+
+class QueryError(DatonsError):
+    """Query execution failed (bad SQL, timeout, read-only violation, etc.)."""
+
+    def __init__(self, status_code: int, detail: str = ""):
+        self.status_code = status_code
+        super().__init__(f"Query error ({status_code}): {detail}")
+
+
+class RateLimitError(DatonsError):
+    """Rate limit exceeded.
+
+    Attributes:
+        retry_after: Seconds until the limit resets.
+        tier: Current API key tier (e.g. 'explorer', 'professional').
+        detail: Full error detail from the server.
+    """
+
+    def __init__(
+        self,
+        retry_after: int | None = None,
+        *,
+        tier: str | None = None,
+        detail: dict | str | None = None,
+    ):
+        self.retry_after = retry_after
+        self.tier = tier
+        self.detail = detail
+
+        # Build a human-readable message from the server response
+        if isinstance(detail, dict):
+            msg = detail.get("error", "Rate limit exceeded.")
+            upgrade = detail.get("upgrade")
+            if upgrade:
+                msg += f" {upgrade}"
+        else:
+            msg = "Rate limit exceeded."
+            if retry_after:
+                msg += f" Retry after {retry_after}s."
+
+        super().__init__(msg)

joltio-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+joltio/__init__.py,sha256=ScDHiX2pOf0CJdfpjmhI5YiVeH9HH-hpj5sseUyvWTk,345
+joltio/cli.py,sha256=Rs1SivH1ce0SEZ1iHGrISi8oPrSTEUAXtZEZ5JYjBu4,3500
+joltio/client.py,sha256=ncu3cJuiokdMjn_SlwEe_cnxudMpetEXU0w2nBd86mc,4341
+joltio/config.py,sha256=7h96er8iN7HvpeC0bNLW5f5FN03vu7FzVhMIU-pNjsw,2962
+joltio/exceptions.py,sha256=roCFOIzabU4WcwgNEx7pBijHPs3vc2GZyyDH5LIK-fA,1615
+joltio/esios/__init__.py,sha256=azapiBUvtxo3TngDtbQ3FhMQuw1PJeHhI4jX-mBjI8o,439
+joltio/esios/manager.py,sha256=8a_MQ89nz5l6pkmMYhW8LQwKmGujhO5BtfZlrkdmdR4,7657
+joltio/esios/models.py,sha256=QZALvLk9RedzeIrvYsY6XUsJfOk3hp-Wiiyl4lzbnKw,2563
+joltio-0.1.0.dist-info/METADATA,sha256=8eYxeh08afMSl7mA54KF26uBshlm0AGUNCilJ_Wgf80,2134
+joltio-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+joltio-0.1.0.dist-info/entry_points.txt,sha256=5qL7RQTVsj41RfXvMqKU19YoopIeJBFrcyibQ28kMWw,43
+joltio-0.1.0.dist-info/RECORD,,

joltio-0.1.0.dist-info/WHEEL

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

joltio-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+joltio = joltio.cli:main