powerdev 0.1.0__tar.gz

powerdev-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,168 @@
+# 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/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "powerdev"
+version = "0.1.0"
+description = "Official Python client for the PowerDev Data API v2"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "PowerDev", email = "helpdesk@power.dev" }]
+keywords = ["powerdev", "energy", "electricity", "iso", "lmp", "data-api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1.0"]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.0"]
+
+[project.urls]
+Documentation = "https://docs.power.dev"
+Homepage = "https://www.power.dev"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+powerdev = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

powerdev-0.1.0/setup.cfg

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

powerdev-0.1.0/src/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-0.1.0/src/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)