powerdev 0.1.0__py3-none-any.whl

powerdev/__init__.py

@@ -0,0 +1,48 @@
+"""Official Python client for the PowerDev Data API v2."""
+
+from powerdev.client import PowerDevClient
+from powerdev.config import PRODUCTION_BASE_URL, ClientConfig
+from powerdev.exceptions import (
+    AccessDeniedError,
+    ApiVersionUnavailableError,
+    DatasetUnavailableError,
+    InternalServerError,
+    InvalidRequestError,
+    PowerDevApiError,
+    PowerDevConfigurationError,
+    PowerDevDeprecationWarning,
+    PowerDevError,
+    PowerDevProtocolError,
+    PowerDevTransportError,
+    ResourceNotFoundError,
+    UnauthenticatedError,
+    UsageLimitExceededError,
+)
+from powerdev.models import CsvStream, ResponseMetadata
+from powerdev.result import QueryResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PRODUCTION_BASE_URL",
+    "AccessDeniedError",
+    "ApiVersionUnavailableError",
+    "ClientConfig",
+    "CsvStream",
+    "DatasetUnavailableError",
+    "InternalServerError",
+    "InvalidRequestError",
+    "PowerDevApiError",
+    "PowerDevClient",
+    "PowerDevConfigurationError",
+    "PowerDevDeprecationWarning",
+    "PowerDevError",
+    "PowerDevProtocolError",
+    "PowerDevTransportError",
+    "QueryResult",
+    "ResourceNotFoundError",
+    "ResponseMetadata",
+    "UnauthenticatedError",
+    "UsageLimitExceededError",
+    "__version__",
+]

powerdev/client.py

@@ -0,0 +1,160 @@
+"""PowerDevClient: thin synchronous client over the v2 endpoints (design 14/P01, P04)."""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, BinaryIO, Iterator, Mapping
+from urllib.parse import quote
+
+import httpx
+
+from powerdev import query as query_encoding
+from powerdev.config import DEFAULT_CONNECT_TIMEOUT, DEFAULT_READ_TIMEOUT, ClientConfig
+from powerdev.models import CsvStream, ResponseMetadata
+from powerdev.result import QueryResult
+from powerdev.transport import Transport
+
+CSV_FORMAT = "CSV"
+
+
+class PowerDevClient:
+    """Synchronous client; use it as a context manager or call close() when done."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        connect_timeout: float | None = DEFAULT_CONNECT_TIMEOUT,
+        read_timeout: float | None = DEFAULT_READ_TIMEOUT,
+        headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        from powerdev import __version__
+
+        self.config = ClientConfig.resolve(api_key, base_url, connect_timeout, read_timeout)
+        self._transport = Transport(self.config, user_agent=f"powerdev-python/{__version__}", http_client=http_client, headers=headers)
+
+    def __enter__(self) -> "PowerDevClient":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __repr__(self) -> str:
+        return f"PowerDevClient({self.config!r})"
+
+    @property
+    def last_response(self) -> ResponseMetadata | None:
+        """Status and contract headers of the most recent successful call."""
+        return self._transport.last_response
+
+    # System (anonymous)
+
+    def get_info(self) -> dict[str, Any]:
+        return self._get("info", auth=False)
+
+    def get_status(self) -> dict[str, Any]:
+        return self._get("status", auth=False)
+
+    # Discovery
+
+    def list_catalogs(self) -> list[dict[str, Any]]:
+        return self._get("catalogs")
+
+    def list_datasets(
+        self,
+        catalog: str | None = None,
+        *,
+        iso_or_provider_list: list[str] | None = None,
+        search: str | None = None,
+        include_details: bool | None = None,
+    ) -> list[dict[str, Any]]:
+        path = f"catalogs/datasets/{_catalog_route(catalog)}" if catalog else "catalogs/datasets"
+        return self._get(path, iso_or_provider_list=iso_or_provider_list, search=search, include_details=include_details)
+
+    def get_dataset(self, dataset_key: str, *, exclude_schema: bool | None = None, exclude_filters: bool | None = None) -> dict[str, Any]:
+        return self._get(f"datasets/{_route_segment(dataset_key)}", exclude_schema=exclude_schema, exclude_filters=exclude_filters)
+
+    # Query
+
+    def query(self, dataset_key: str, *, method: str = query_encoding.GET, convert: bool = True, **params: Any) -> QueryResult:
+        params.pop("format", None)
+        verb, path, kwargs = self._query_request(dataset_key, params, method)
+        response = self._transport.request_json(verb, path, **kwargs)
+        return QueryResult(response.payload, response.metadata, convert=convert)
+
+    @contextmanager
+    def stream_csv(self, dataset_key: str, *, method: str = query_encoding.GET, **params: Any) -> Iterator[CsvStream]:
+        params["format"] = CSV_FORMAT
+        verb, path, kwargs = self._query_request(dataset_key, params, method)
+        with self._transport.stream(verb, path, **kwargs) as response:
+            yield CsvStream(response)
+
+    def save_csv(self, dataset_key: str, target: str | os.PathLike[str] | BinaryIO, *, method: str = query_encoding.GET, **params: Any) -> ResponseMetadata:
+        with self.stream_csv(dataset_key, method=method, **params) as stream:
+            if hasattr(target, "write"):
+                _copy(stream, target)  # type: ignore[arg-type]
+            else:
+                with Path(target).open("wb") as handle:
+                    _copy(stream, handle)
+            return stream.metadata
+
+    # Locations
+
+    def list_locations(self, *, iso_or_provider_list: list[str] | None = None, search: str | None = None, limit: int | None = None) -> list[dict[str, Any]]:
+        return self._get("lookups/locations", iso_or_provider_list=iso_or_provider_list, search=search, limit=limit)
+
+    def get_location(self, location_id: int | str) -> dict[str, Any]:
+        return self._get(f"lookups/location/{_route_segment(str(location_id))}")
+
+    # Usage
+
+    def get_usage(self) -> dict[str, Any]:
+        return self._get("usage")
+
+    # API key management (credentials per call; nothing is stored)
+
+    def list_api_keys(self, *, email: str, password: str) -> list[dict[str, Any]]:
+        return self._credentials_post("api-keys/list", email, password, {})
+
+    def create_api_key(self, *, email: str, password: str, key_name: str | None = None) -> dict[str, Any]:
+        return self._credentials_post("api-keys/create", email, password, {"key_name": key_name})
+
+    def revoke_api_key(self, *, email: str, password: str, key_id: str) -> dict[str, Any]:
+        return self._credentials_post("api-keys/revoke", email, password, {"key_id": key_id})
+
+    # Internals
+
+    def _get(self, path: str, *, auth: bool = True, **params: Any) -> Any:
+        pairs, _ = query_encoding.prepare(params, query_encoding.GET)
+        return self._transport.request_json(query_encoding.GET, path, params=pairs or None, auth=auth).data
+
+    def _credentials_post(self, path: str, email: str, password: str, extra: Mapping[str, Any]) -> Any:
+        body = {"email": email, "password": password, **extra}
+        return self._transport.request_json(query_encoding.POST, path, body=body, auth=False).data
+
+    def _query_request(self, dataset_key: str, params: Mapping[str, Any], method: str) -> tuple[str, str, dict[str, Any]]:
+        verb = query_encoding.normalize_method(method)
+        pairs, body = query_encoding.prepare(params, verb)
+        path = f"datasets/{_route_segment(dataset_key)}/query"
+        return verb, path, {"params": pairs or None, "body": body}
+
+
+def _route_segment(value: str) -> str:
+    return quote(value.strip(), safe="")
+
+
+def _catalog_route(catalog: str) -> str:
+    """Catalog keys are snake_case; their route segments are kebab-case (forecast_versions -> forecast-versions)."""
+    return _route_segment(catalog.lower().replace("_", "-"))
+
+
+def _copy(stream: CsvStream, handle: BinaryIO) -> None:
+    for chunk in stream.iter_bytes():
+        handle.write(chunk)

powerdev/config.py

@@ -0,0 +1,91 @@
+"""Client configuration: key and base URL resolution, URL scheme and timeout rules (design 14/P02)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from powerdev.exceptions import PowerDevConfigurationError
+
+PRODUCTION_BASE_URL = "https://api.power.dev/v2/"
+ENV_API_KEY = "POWERDEV_API_KEY"
+ENV_BASE_URL = "POWERDEV_BASE_URL"
+
+DEFAULT_CONNECT_TIMEOUT = 30.0
+MAX_CONNECT_TIMEOUT = 180.0
+DEFAULT_READ_TIMEOUT = 120.0
+
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    api_key: str | None
+    base_url: str
+    connect_timeout: float | None
+    read_timeout: float | None
+
+    @classmethod
+    def resolve(
+        cls,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        connect_timeout: float | None = DEFAULT_CONNECT_TIMEOUT,
+        read_timeout: float | None = DEFAULT_READ_TIMEOUT,
+    ) -> "ClientConfig":
+        key = _clean(api_key) or _clean(os.environ.get(ENV_API_KEY))
+        url = _clean(base_url) or _clean(os.environ.get(ENV_BASE_URL)) or PRODUCTION_BASE_URL
+        return cls(key, normalize_base_url(url), validate_connect_timeout(connect_timeout), validate_read_timeout(read_timeout))
+
+    @property
+    def has_api_key(self) -> bool:
+        return bool(self.api_key)
+
+    def __repr__(self) -> str:
+        key = "set" if self.api_key else "missing"
+        return (
+            f"ClientConfig(api_key=<{key}>, base_url={self.base_url!r}, "
+            f"connect_timeout={self.connect_timeout!r}, read_timeout={self.read_timeout!r})"
+        )
+
+
+def normalize_base_url(value: str) -> str:
+    parts = urlsplit(value)
+    host = (parts.hostname or "").lower()
+    if parts.scheme == "https" and host:
+        pass
+    elif parts.scheme == "http" and host in _LOCAL_HOSTS:
+        pass
+    else:
+        raise PowerDevConfigurationError(
+            "base_url must be an https:// URL; plain http:// is accepted only for localhost."
+        )
+    if parts.query or parts.fragment:
+        raise PowerDevConfigurationError("base_url cannot carry a query string or fragment.")
+    return value if value.endswith("/") else value + "/"
+
+
+def validate_connect_timeout(value: float | None) -> float | None:
+    if value is None:
+        return None
+    if value <= 0 or value > MAX_CONNECT_TIMEOUT:
+        raise PowerDevConfigurationError(
+            f"connect_timeout must be between 0 and {MAX_CONNECT_TIMEOUT:g} seconds, or None to disable it explicitly."
+        )
+    return float(value)
+
+
+def validate_read_timeout(value: float | None) -> float | None:
+    if value is None:
+        return None
+    if value <= 0:
+        raise PowerDevConfigurationError("read_timeout must be positive, or None to disable it explicitly.")
+    return float(value)
+
+
+def _clean(value: str | None) -> str | None:
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None

powerdev/exceptions.py

@@ -0,0 +1,106 @@
+"""Exception hierarchy of the client (design 14/P07). Secrets never enter messages or reprs."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+class PowerDevError(Exception):
+    """Base class of every error raised by the client."""
+
+
+class PowerDevConfigurationError(PowerDevError):
+    """Local misuse: missing API key, invalid base URL or timeout, conflicting query options."""
+
+
+class PowerDevTransportError(PowerDevError):
+    """Network, DNS, TLS, timeout or an unexpected redirect; no response envelope was read."""
+
+
+class PowerDevProtocolError(PowerDevError):
+    """The response does not follow the v2 contract (wrong content type, malformed JSON, row/header mismatch)."""
+
+
+class PowerDevDeprecationWarning(UserWarning):
+    """Emitted once per process for responses that carry Deprecation or Sunset headers."""
+
+
+class PowerDevApiError(PowerDevError):
+    """An HTTP error answered with the shared error envelope: {"error": {"code", "message", "details"}}."""
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        details: Mapping[str, Any] | None = None,
+        *,
+        retry_after: int | None = None,
+        headers: Mapping[str, str] | None = None,
+        body_preview: str | None = None,
+    ) -> None:
+        super().__init__(f"{status_code} {code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.details = dict(details) if details else None
+        self.retry_after = retry_after
+        self.headers = dict(headers or {})
+        self.body_preview = body_preview
+
+    @property
+    def limit_type(self) -> str | None:
+        return self.details.get("limit_type") if self.details else None
+
+    @property
+    def fields(self) -> list[dict[str, Any]]:
+        value = self.details.get("fields") if self.details else None
+        return list(value) if isinstance(value, list) else []
+
+
+class InvalidRequestError(PowerDevApiError):
+    """400 INVALID_REQUEST."""
+
+
+class UnauthenticatedError(PowerDevApiError):
+    """401 UNAUTHENTICATED."""
+
+
+class AccessDeniedError(PowerDevApiError):
+    """403 ACCESS_DENIED."""
+
+
+class ResourceNotFoundError(PowerDevApiError):
+    """404 RESOURCE_NOT_FOUND."""
+
+
+class ApiVersionUnavailableError(PowerDevApiError):
+    """410 API_VERSION_UNAVAILABLE."""
+
+
+class UsageLimitExceededError(PowerDevApiError):
+    """429 USAGE_LIMIT_EXCEEDED; retry_after and details.reset_at say when the limit resets."""
+
+
+class InternalServerError(PowerDevApiError):
+    """500 INTERNAL_ERROR."""
+
+
+class DatasetUnavailableError(PowerDevApiError):
+    """503 DATASET_UNAVAILABLE."""
+
+
+_BY_STATUS: dict[int, type[PowerDevApiError]] = {
+    400: InvalidRequestError,
+    401: UnauthenticatedError,
+    403: AccessDeniedError,
+    404: ResourceNotFoundError,
+    410: ApiVersionUnavailableError,
+    429: UsageLimitExceededError,
+    500: InternalServerError,
+    503: DatasetUnavailableError,
+}
+
+
+def api_error_class(status_code: int) -> type[PowerDevApiError]:
+    return _BY_STATUS.get(status_code, PowerDevApiError)

powerdev/models.py

@@ -0,0 +1,95 @@
+"""Small standard-library models that keep the server payload and the safe response metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Mapping
+
+import httpx
+
+TRUNCATED_HEADER = "x-powerdev-truncated"
+UNRESOLVED_LOCATIONS_HEADER = "x-powerdev-unresolved-location-count"
+_KEPT_HEADERS = (
+    "content-type",
+    "retry-after",
+    "deprecation",
+    "sunset",
+    "link",
+    TRUNCATED_HEADER,
+    UNRESOLVED_LOCATIONS_HEADER,
+)
+
+
+@dataclass(frozen=True)
+class ResponseMetadata:
+    """HTTP status and the contract headers of one response; never carries request headers."""
+
+    status_code: int
+    headers: Mapping[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> "ResponseMetadata":
+        kept = {name: response.headers[name] for name in _KEPT_HEADERS if name in response.headers}
+        return cls(response.status_code, kept)
+
+    @property
+    def content_type(self) -> str | None:
+        return self.headers.get("content-type")
+
+    @property
+    def retry_after(self) -> int | None:
+        value = self.headers.get("retry-after")
+        return int(value) if value and value.isdigit() else None
+
+    @property
+    def deprecation(self) -> str | None:
+        return self.headers.get("deprecation")
+
+    @property
+    def sunset(self) -> str | None:
+        return self.headers.get("sunset")
+
+    @property
+    def link(self) -> str | None:
+        return self.headers.get("link")
+
+    @property
+    def truncated(self) -> bool:
+        return self.headers.get(TRUNCATED_HEADER, "").lower() == "true"
+
+    @property
+    def unresolved_location_count(self) -> int | None:
+        value = self.headers.get(UNRESOLVED_LOCATIONS_HEADER)
+        return int(value) if value and value.isdigit() else None
+
+
+@dataclass(frozen=True)
+class ApiResponse:
+    """Parsed JSON body plus metadata; `payload` is the full envelope, `data` its data member when present."""
+
+    payload: Any
+    metadata: ResponseMetadata
+
+    @property
+    def data(self) -> Any:
+        return self.payload.get("data") if isinstance(self.payload, Mapping) else self.payload
+
+
+class CsvStream:
+    """Chunked access to a CSV response body inside a `with client.stream_csv(...)` block."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self._response = response
+        self.metadata = ResponseMetadata.from_response(response)
+
+    def iter_bytes(self, chunk_size: int | None = None) -> Iterator[bytes]:
+        return self._response.iter_bytes(chunk_size)
+
+    def iter_text(self, chunk_size: int | None = None) -> Iterator[str]:
+        return self._response.iter_text(chunk_size)
+
+    def iter_lines(self) -> Iterator[str]:
+        return self._response.iter_lines()
+
+    def read(self) -> bytes:
+        return self._response.read()

powerdev/query.py

@@ -0,0 +1,73 @@
+"""Encodes query options for GET (repeated lists, URL-encoded JSON filters) and POST (native JSON) (design 14/P04–P06)."""
+
+from __future__ import annotations
+
+import json
+from datetime import date, datetime
+from typing import Any, Mapping
+
+from powerdev.exceptions import PowerDevConfigurationError
+
+GET = "GET"
+POST = "POST"
+_METHODS = {GET, POST}
+
+_CONFLICTS = (
+    ("location_ids", "location_names"),
+    ("include_columns", "exclude_columns"),
+)
+
+
+def normalize_method(method: str) -> str:
+    upper = (method or "").upper()
+    if upper not in _METHODS:
+        raise PowerDevConfigurationError("method must be 'GET' or 'POST'.")
+    return upper
+
+
+def prepare(params: Mapping[str, Any], method: str) -> tuple[list[tuple[str, str]] | None, dict[str, Any] | None]:
+    """Returns (query_params, json_body) for the chosen method; None values are dropped."""
+    options = {key: value for key, value in params.items() if value is not None}
+    for left, right in _CONFLICTS:
+        if left in options and right in options:
+            raise PowerDevConfigurationError(f"{left} and {right} cannot be used in the same query.")
+
+    if method == POST:
+        return None, {key: _json_value(value) for key, value in options.items()}
+
+    pairs: list[tuple[str, str]] = []
+    for key, value in options.items():
+        pairs.extend(_get_pairs(key, value))
+    return pairs, None
+
+
+def _get_pairs(key: str, value: Any) -> list[tuple[str, str]]:
+    if isinstance(value, Mapping):
+        return [(key, json.dumps(_json_value(value), separators=(",", ":")))]
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [(key, _scalar(item)) for item in value]
+    return [(key, _scalar(value))]
+
+
+def _scalar(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return str(value)
+
+
+def _json_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {str(key): _json_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [_json_value(item) for item in value]
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return value

powerdev/result.py

@@ -0,0 +1,124 @@
+"""QueryResult keeps the server structure and converts cells with the column metadata (design 14/P03)."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any, Callable, Iterator, Mapping, Sequence
+
+from powerdev.exceptions import PowerDevProtocolError
+from powerdev.models import ResponseMetadata
+
+ARRAY_OF_ARRAYS = "ARRAY_OF_ARRAYS"
+ARRAY_OF_OBJECTS = "ARRAY_OF_OBJECTS"
+
+_CONVERTERS: dict[str, Callable[[Any], Any]] = {
+    "integer": int,
+    "float": float,
+    "decimal": lambda value: Decimal(str(value)),
+    "boolean": bool,
+    "string": str,
+    "date": lambda value: date.fromisoformat(str(value)),
+    "timestamp": lambda value: datetime.fromisoformat(str(value)),
+}
+
+
+class QueryResult:
+    """A JSON query response: meta, echoed request, column metadata and the rows in the server's row_format."""
+
+    def __init__(self, payload: Mapping[str, Any], metadata: ResponseMetadata, *, convert: bool = True) -> None:
+        data = _mapping(payload.get("data"), "data")
+        self.meta: dict[str, Any] = dict(_mapping(payload.get("meta"), "meta"))
+        self.request: dict[str, Any] = dict(_mapping(payload.get("request"), "request"))
+        self.metadata = metadata
+        self.row_format: str = str(data.get("row_format") or ARRAY_OF_ARRAYS)
+        self.header_keys: list[str] = [str(key) for key in _sequence(data.get("header_keys"), "header_keys")]
+        self.header_labels: list[str] = [str(label) for label in _sequence(data.get("header_labels") or [], "header_labels")]
+        self.column_info: list[dict[str, Any]] = [dict(_mapping(column, "column_info")) for column in _sequence(data.get("column_info") or [], "column_info")]
+        rows = _sequence(data.get("rows"), "rows")
+        self.rows: list[Any] = _convert_rows(rows, self.header_keys, self.column_info, self.row_format) if convert else list(rows)
+
+    @property
+    def dataset_key(self) -> str | None:
+        return self.meta.get("dataset_key")
+
+    @property
+    def granularity(self) -> str | None:
+        return self.meta.get("granularity")
+
+    @property
+    def row_count(self) -> int:
+        return int(self.meta.get("row_count", len(self.rows)))
+
+    @property
+    def truncated(self) -> bool:
+        return bool(self.meta.get("truncated", False))
+
+    @property
+    def column_types(self) -> dict[str, str]:
+        return {str(column["key"]): str(column["type"]) for column in self.column_info if "key" in column}
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self.rows)
+
+    def to_records(self) -> list[dict[str, Any]]:
+        if self.row_format == ARRAY_OF_OBJECTS:
+            return [dict(row) for row in self.rows]
+        return [dict(zip(self.header_keys, row)) for row in self.rows]
+
+    def to_dataframe(self) -> Any:
+        try:
+            import pandas
+        except ImportError as exc:
+            raise ImportError("QueryResult.to_dataframe() needs pandas; install the extra with: pip install 'powerdev[pandas]'") from exc
+        if self.row_format == ARRAY_OF_OBJECTS:
+            return pandas.DataFrame.from_records(self.rows, columns=self.header_keys)
+        return pandas.DataFrame(self.rows, columns=self.header_keys)
+
+    def __repr__(self) -> str:
+        return f"QueryResult(dataset_key={self.dataset_key!r}, rows={len(self.rows)}, columns={len(self.header_keys)}, row_format={self.row_format!r})"
+
+
+def _convert_rows(rows: Sequence[Any], keys: list[str], column_info: list[dict[str, Any]], row_format: str) -> list[Any]:
+    types = {str(column.get("key")): str(column.get("type")) for column in column_info}
+    converters = [_CONVERTERS.get(types.get(key, ""), _identity) for key in keys]
+    width = len(keys)
+
+    if row_format == ARRAY_OF_OBJECTS:
+        by_key = dict(zip(keys, converters))
+        return [{key: _cell(by_key.get(key, _identity), value) for key, value in _mapping(row, "rows").items()} for row in rows]
+
+    converted: list[list[Any]] = []
+    for index, row in enumerate(rows):
+        if not isinstance(row, Sequence) or isinstance(row, (str, bytes)) or len(row) != width:
+            raise PowerDevProtocolError(f"Row {index} does not match the {width} header keys.")
+        converted.append([_cell(converters[position], value) for position, value in enumerate(row)])
+    return converted
+
+
+def _cell(converter: Callable[[Any], Any], value: Any) -> Any:
+    if value is None:
+        return None
+    try:
+        return converter(value)
+    except (ValueError, TypeError, ArithmeticError) as exc:
+        raise PowerDevProtocolError(f"Cell value {value!r} cannot be converted with {getattr(converter, '__name__', 'converter')}.") from exc
+
+
+def _identity(value: Any) -> Any:
+    return value
+
+
+def _mapping(value: Any, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise PowerDevProtocolError(f"The response has no '{name}' object.")
+    return value
+
+
+def _sequence(value: Any, name: str) -> Sequence[Any]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise PowerDevProtocolError(f"The response has no '{name}' list.")
+    return value

powerdev/transport.py

@@ -0,0 +1,161 @@
+"""One long-lived httpx.Client, header-based authentication and envelope-aware error mapping (design 14/P02, P07)."""
+
+from __future__ import annotations
+
+import json
+import warnings
+from contextlib import contextmanager
+from typing import Any, Iterator, Mapping, Sequence
+from urllib.parse import urljoin
+
+import httpx
+
+from powerdev.config import ClientConfig
+from powerdev.exceptions import (
+    PowerDevConfigurationError,
+    PowerDevDeprecationWarning,
+    PowerDevProtocolError,
+    PowerDevTransportError,
+    api_error_class,
+)
+from powerdev.models import ApiResponse, ResponseMetadata
+
+API_KEY_HEADER = "x-api-key"
+JSON_CONTENT_TYPE = "application/json"
+_RESERVED_HEADERS = {API_KEY_HEADER, "apikey"}
+_PREVIEW_LIMIT = 200
+
+Params = Sequence[tuple[str, str]] | Mapping[str, Any] | None
+
+
+class Transport:
+    def __init__(
+        self,
+        config: ClientConfig,
+        *,
+        user_agent: str,
+        http_client: httpx.Client | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self.config = config
+        self._owns_client = http_client is None
+        self._extra_headers = _validated_extra_headers(headers)
+        self._user_agent = user_agent
+        self._client = http_client or httpx.Client(
+            timeout=httpx.Timeout(connect=config.connect_timeout, read=config.read_timeout, write=config.read_timeout, pool=config.connect_timeout),
+            follow_redirects=False,
+        )
+        self._closed = False
+        self.last_response: ResponseMetadata | None = None
+
+    def request_json(self, method: str, path: str, *, params: Params = None, body: Any = None, auth: bool = True) -> ApiResponse:
+        response = self._send(method, path, params=params, body=body, auth=auth, stream=False)
+        try:
+            self._raise_for_error(response)
+            metadata = self._record(response)
+            if JSON_CONTENT_TYPE not in response.headers.get("content-type", ""):
+                raise PowerDevProtocolError(
+                    f"Expected a JSON response but received {response.headers.get('content-type') or 'no content type'}."
+                )
+            try:
+                payload = response.json()
+            except ValueError as exc:
+                raise PowerDevProtocolError("The response body is not valid JSON.") from exc
+            return ApiResponse(payload, metadata)
+        finally:
+            response.close()
+
+    @contextmanager
+    def stream(self, method: str, path: str, *, params: Params = None, body: Any = None, auth: bool = True) -> Iterator[httpx.Response]:
+        response = self._send(method, path, params=params, body=body, auth=auth, stream=True)
+        try:
+            if response.status_code >= 300:
+                response.read()
+            self._raise_for_error(response)
+            self._record(response)
+            yield response
+        finally:
+            response.close()
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._owns_client:
+            self._client.close()
+
+    def _send(self, method: str, path: str, *, params: Params, body: Any, auth: bool, stream: bool) -> httpx.Response:
+        if self._closed:
+            raise PowerDevConfigurationError("The client is closed.")
+        headers = dict(self._extra_headers)
+        headers["User-Agent"] = self._user_agent
+        headers["Accept"] = JSON_CONTENT_TYPE
+        if auth:
+            if not self.config.api_key:
+                raise PowerDevConfigurationError(
+                    "This call needs an API key. Pass api_key=... or set the POWERDEV_API_KEY environment variable."
+                )
+            headers[API_KEY_HEADER] = self.config.api_key
+
+        url = urljoin(self.config.base_url, path)
+        request = self._client.build_request(method, url, params=params, json=body, headers=headers)
+        try:
+            return self._client.send(request, stream=stream)
+        except httpx.TimeoutException as exc:
+            raise PowerDevTransportError(f"The request to {method} {path} timed out.") from exc
+        except httpx.TransportError as exc:
+            raise PowerDevTransportError(f"The request to {method} {path} failed: {type(exc).__name__}.") from exc
+
+    def _record(self, response: httpx.Response) -> ResponseMetadata:
+        metadata = ResponseMetadata.from_response(response)
+        self.last_response = metadata
+        if metadata.deprecation or metadata.sunset:
+            warnings.warn(
+                f"{response.request.method} {response.request.url.path} is deprecated"
+                + (f" (sunset {metadata.sunset})" if metadata.sunset else "")
+                + (f"; see {metadata.link}" if metadata.link else "") + ".",
+                PowerDevDeprecationWarning,
+                stacklevel=4,
+            )
+        return metadata
+
+    def _raise_for_error(self, response: httpx.Response) -> None:
+        status = response.status_code
+        if 300 <= status < 400:
+            raise PowerDevTransportError(f"Unexpected redirect ({status}); redirects are not followed.")
+        if status < 400:
+            return
+
+        metadata = ResponseMetadata.from_response(response)
+        envelope = _parse_error_envelope(response)
+        if envelope is None:
+            preview = response.text[:_PREVIEW_LIMIT] if response.text else None
+            raise api_error_class(status)(
+                status, f"HTTP_{status}", "The server returned an error without the shared error envelope.",
+                retry_after=metadata.retry_after, headers=metadata.headers, body_preview=preview,
+            )
+
+        code = str(envelope.get("code") or f"HTTP_{status}")
+        message = str(envelope.get("message") or "")
+        details = envelope.get("details") if isinstance(envelope.get("details"), Mapping) else None
+        raise api_error_class(status)(status, code, message, details, retry_after=metadata.retry_after, headers=metadata.headers)
+
+
+def _parse_error_envelope(response: httpx.Response) -> Mapping[str, Any] | None:
+    if JSON_CONTENT_TYPE not in response.headers.get("content-type", ""):
+        return None
+    try:
+        payload = json.loads(response.text)
+    except ValueError:
+        return None
+    error = payload.get("error") if isinstance(payload, Mapping) else None
+    return error if isinstance(error, Mapping) else None
+
+
+def _validated_extra_headers(headers: Mapping[str, str] | None) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for name, value in (headers or {}).items():
+        if name.lower() in _RESERVED_HEADERS:
+            raise PowerDevConfigurationError("Authentication headers cannot be overridden; pass api_key instead.")
+        result[name] = value
+    return result

powerdev-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: powerdev
+Version: 0.1.0
+Summary: Official Python client for the PowerDev Data API v2
+Author-email: PowerDev <helpdesk@power.dev>
+License-Expression: MIT
+Project-URL: Documentation, https://docs.power.dev
+Project-URL: Homepage, https://www.power.dev
+Keywords: powerdev,energy,electricity,iso,lmp,data-api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == "pandas"
+Dynamic: license-file
+
+# powerdev
+
+Official Python client for the [PowerDev Data API v2](https://docs.power.dev). It is a thin, synchronous
+wrapper: every method maps to one documented v2 endpoint, nothing is cached, retried or converted behind
+your back, and the server stays the authority for validation.
+
+- Python 3.11 or newer, one runtime dependency (`httpx`)
+- Discovery-driven: catalogs, datasets, filters and columns come from the API, not from constants baked into the package
+- JSON queries return a `QueryResult` with typed cells; CSV is streamed or saved as the server sends it
+- Optional `pandas` extra for `to_dataframe()`
+- Typed exceptions; no built-in retry
+
+## Installation
+
+```bash
+pip install powerdev
+pip install "powerdev[pandas]"   # with DataFrame support
+```
+
+## Authentication
+
+Pass the key explicitly or set `POWERDEV_API_KEY`. The key is sent only in the `x-api-key` header and never
+appears in URLs, reprs, logs or exception messages.
+
+```python
+from powerdev import PowerDevClient
+
+with PowerDevClient(api_key="YOUR_API_KEY") as client:
+    print(client.get_usage())
+```
+
+`base_url` defaults to `https://api.power.dev/v2/` and can be overridden with the `base_url` argument or the
+`POWERDEV_BASE_URL` variable. Remote URLs must use HTTPS. Without a key only `get_info()` and `get_status()`
+work; any other call raises `PowerDevConfigurationError` before a request is sent.
+
+## Discovery
+
+```python
+catalogs = client.list_catalogs()
+datasets = client.list_datasets("common", iso_or_provider_list=["SPP"], search="fuel")
+info = client.get_dataset("spp_fuel_mix")
+
+print(info["granularity"]["options"])
+print(info["schema"]["default_columns"])
+print([f["key"] for f in info["filters"]])
+```
+
+Discovery methods return the `data` part of the response as plain dictionaries and lists, so new server
+fields are available immediately. Fetch dataset info once per session; it does not count against the API
+call quota, but calling it before every query is wasted latency.
+
+## Querying data
+
+```python
+from datetime import date
+
+result = client.query(
+    "spp_fuel_mix",
+    start_date=date(2026, 10, 21),
+    end_date=date(2026, 10, 22),
+    filters={"balancing_area": ["SPP"]},
+    include_columns=["interval_start", "fuel_type", "value"],
+)
+
+print(result.header_keys)
+for row in result.rows:
+    print(row)
+```
+
+Accepted options are the public query parameters: `start_date`, `end_date`, `publish_start`, `publish_end`,
+`granularity`, `filters`, `location_ids`, `location_names`, `include_columns`, `exclude_columns`,
+`row_format`, `generate_unique_hash_key`. Values are sent as you give them: `date` and `datetime` objects
+become ISO strings, naive datetimes are not given a time zone, lists are repeated on GET and sent as JSON
+arrays on POST, and `filters` is URL-encoded JSON on GET. Requests use GET by default; pass
+`method="POST"` for long parameter lists. The client never switches methods on its own, and
+`location_ids` with `location_names` or `include_columns` with `exclude_columns` is rejected locally.
+
+`QueryResult` keeps the server structure:
+
+| Attribute | Content |
+|---|---|
+| `meta`, `request` | The response `meta` and echoed `request` objects |
+| `header_keys`, `header_labels`, `column_info` | Column keys, labels and metadata in response order |
+| `row_format`, `rows` | `ARRAY_OF_ARRAYS` (lists) or `ARRAY_OF_OBJECTS` (dicts), as requested |
+| `row_count`, `truncated`, `granularity`, `dataset_key` | Shortcuts into `meta` |
+| `to_records()` | Rows as dictionaries keyed by `header_keys` |
+| `to_dataframe()` | A pandas DataFrame in `header_keys` order (needs the `pandas` extra) |
+
+Cells are converted with the column metadata: `integer` to `int`, `float` to `float`, `decimal` to
+`decimal.Decimal` (no binary rounding, trailing zeros kept), `boolean` to `bool`, `date` to `datetime.date`,
+`timestamp` to a timezone-aware `datetime` with the offset the server sent, `string` to `str`. `null` stays
+`None`. Pass `convert=False` to keep the raw JSON values.
+
+## CSV
+
+```python
+client.save_csv("spp_fuel_mix", "spp_fuel_mix.csv", start_date="2026-10-21", end_date="2026-10-22")
+
+with client.stream_csv("spp_fuel_mix", start_date="2026-10-21", end_date="2026-10-22") as stream:
+    for chunk in stream.iter_bytes():
+        ...
+```
+
+CSV bodies are streamed without conversion. If the server answers with an error, the JSON envelope is
+parsed and raised; nothing is written to the file.
+
+## Locations (LMP datasets)
+
+```python
+nodes = client.list_locations(iso_or_provider_list=["PJM"], search="western", limit=20)
+node = client.get_location(nodes[0]["id"])
+prices = client.query("pjm_lmp_da", start_date="2026-10-21", end_date="2026-10-22", location_ids=[node["id"]])
+print(prices.meta["locations"], client.last_response.unresolved_location_count)
+```
+
+## Errors
+
+All exceptions derive from `PowerDevError`:
+
+| Exception | When |
+|---|---|
+| `PowerDevConfigurationError` | Missing key, invalid base URL or timeout, conflicting query options, closed client |
+| `PowerDevTransportError` | DNS, connection, TLS or timeout failure, or an unexpected redirect |
+| `PowerDevProtocolError` | The response does not match the v2 contract |
+| `PowerDevApiError` | Any HTTP error with the shared envelope; `status_code`, `code`, `message`, `details`, `retry_after`, `headers` |
+
+`PowerDevApiError` has one subclass per public status: `InvalidRequestError` (400), `UnauthenticatedError`
+(401), `AccessDeniedError` (403), `ResourceNotFoundError` (404), `ApiVersionUnavailableError` (410),
+`UsageLimitExceededError` (429), `InternalServerError` (500), `DatasetUnavailableError` (503).
+
+```python
+from powerdev import UsageLimitExceededError
+
+try:
+    result = client.query("spp_fuel_mix", start_date="2026-10-21", end_date="2026-10-22")
+except UsageLimitExceededError as error:
+    print(error.limit_type, error.retry_after, error.details)
+```
+
+The client makes exactly one HTTP attempt per call. If you need retries, wrap the call in your own policy
+and honour `retry_after`; the client will not wait or resend for you.
+
+Responses that carry `Deprecation` or `Sunset` headers raise a `PowerDevDeprecationWarning` and keep the
+headers in `client.last_response`.
+
+## API key management
+
+Credentials are passed per call and never stored. The created key is shown once in the response.
+
+```python
+keys = client.list_api_keys(email="you@example.com", password="...")
+created = client.create_api_key(email="you@example.com", password="...", key_name="etl")
+client.revoke_api_key(email="you@example.com", password="...", key_id=created["key_id"])
+```
+
+## Transport details
+
+- One long-lived `httpx.Client`; pass your own with `http_client=` for proxies or tests (it is not closed for you)
+- Connect timeout 30 s by default (at most 180 s), read timeout 120 s; `None` disables a timeout explicitly
+- Redirects are not followed; TLS verification is on
+- `headers=` adds request headers, but authentication headers cannot be overridden
+
+## Versioning
+
+The package follows Semantic Versioning and targets the public v2 contract. Additive server fields never
+break the client because payloads are kept as raw mappings. See `CHANGELOG.md` for release notes.
+
+Questions: helpdesk@power.dev

powerdev-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+powerdev/__init__.py,sha256=lUZ7xU4MNMk06932Jahj9ohwL6Wp2_ZbnyVAB--olX0,1263
+powerdev/client.py,sha256=kI8t79W2ylJ9MgtfNiAnYnwzV2AO46ZVtmk8yGFekps,6608
+powerdev/config.py,sha256=xlm3r6ZJoDPJoS_r8t5r2zHqhENCrRcJFAOYcWe_W3w,2954
+powerdev/exceptions.py,sha256=mr0Ace0tJqZjE7ooo9EhTPrDcq-3pvfz-WoQOzUWHh0,3110
+powerdev/models.py,sha256=4uSyFFf-LtLV6nwOTFqEt3Ux1SdyIFDpBrCiSCg9vwo,2870
+powerdev/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+powerdev/query.py,sha256=A2_KOQUGlRWLTwu4K7yF_iLFhT6F4NZxB0mq2hlRR6A,2438
+powerdev/result.py,sha256=2GUBtwVuCT-BqDc9AVrh18s7ZYS1U2kT9qVftLF_Hx0,5220
+powerdev/transport.py,sha256=fo1u5FuF-jg1xFeX6IetyLtyb5k-drunGGjYbtTtC7g,6757
+powerdev-0.1.0.dist-info/licenses/LICENSE,sha256=UG_PBf6E4zLx7GBs2SH0kvtfOhu_H7bh2KkFXMVyL0E,1065
+powerdev-0.1.0.dist-info/METADATA,sha256=OqxXbZ0Nt4JJ0PHCX6C5t0qgqK2WYMSf5KLg1DtWuR0,8332
+powerdev-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+powerdev-0.1.0.dist-info/top_level.txt,sha256=Np4foL5FwCL4Oeto1XO2rCnzxQRofijYHJERIWzwvAM,9
+powerdev-0.1.0.dist-info/RECORD,,

powerdev-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

powerdev-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PowerDev
+
+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.

powerdev-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+powerdev