ballotdata 1.0.0__py3-none-any.whl

ballotdata/__init__.py

@@ -0,0 +1,90 @@
+"""The official Python client for the BallotData API: elections, contests,
+endorsers and endorsements for every U.S. ballot, plus a live stream of
+endorsement changes.
+
+::
+
+    from ballotdata import BallotData
+
+    client = BallotData()  # reads BALLOTDATA_API_KEY
+    for endorsement in client.endorsements.list(states="CA", categories="labor"):
+        print(endorsement["endorser"]["name"], endorsement["choice"]["label"])
+
+Docs: https://github.com/EndorsedByOrg/pylib#readme and https://api.ballotdata.net/docs
+"""
+
+from ._base import RateLimit, ResponseInfo
+from ._client import AsyncBallotData, BallotData
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    BallotDataError,
+    ConflictError,
+    CursorExpiredError,
+    InternalServerError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from .helpers import ContestEndorsements, EndorsementPick, EndorsementPosition, group_by_contest, sort_picks
+from .pagination import AsyncPage, AsyncPaginator, SyncPage
+from .postbacks import (
+    SIGNATURE_HEADER,
+    PostbackSignatureError,
+    construct_postback,
+    sign_postback,
+    verify_postback_signature,
+)
+from .stream import (
+    AsyncEndorsementStream,
+    EndorsementMessage,
+    EndorsementStream,
+    ReadyMessage,
+    ReconnectInfo,
+    StreamMessage,
+)
+
+__all__ = [
+    "__version__",
+    "BallotData",
+    "AsyncBallotData",
+    "ResponseInfo",
+    "RateLimit",
+    "SyncPage",
+    "AsyncPage",
+    "AsyncPaginator",
+    "EndorsementStream",
+    "AsyncEndorsementStream",
+    "StreamMessage",
+    "ReadyMessage",
+    "EndorsementMessage",
+    "ReconnectInfo",
+    "BallotDataError",
+    "APIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "CursorExpiredError",
+    "PayloadTooLargeError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "SIGNATURE_HEADER",
+    "PostbackSignatureError",
+    "verify_postback_signature",
+    "construct_postback",
+    "sign_postback",
+    "group_by_contest",
+    "sort_picks",
+    "ContestEndorsements",
+    "EndorsementPosition",
+    "EndorsementPick",
+]

ballotdata/_base.py

@@ -0,0 +1,187 @@
+"""What the sync and async transports share: settings, query encoding, headers,
+response facts and the retry rules."""
+
+from __future__ import annotations
+
+import datetime as dt
+import os
+import random
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.ballotdata.net"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+MAX_RETRY_AFTER = 60.0
+"""Don't sleep longer than this on a Retry-After; a daily limit can ask for hours."""
+
+USER_AGENT = f"ballotdata-python/{__version__}"
+
+
+@dataclass(frozen=True)
+class RateLimit:
+    """Rate-limit headers from a response. Values are None when the API didn't send them."""
+
+    limit: int | None
+    """Requests allowed per minute on your plan."""
+    remaining: int | None
+    """Requests left this minute."""
+    reset: int | None
+    """Seconds until the minute resets."""
+    daily_limit: int | None
+    """Requests allowed per UTC day, on plans with a daily cap."""
+    daily_remaining: int | None
+    """Requests left today."""
+
+
+@dataclass(frozen=True)
+class ResponseInfo:
+    """Facts about one HTTP response, passed to ``on_response`` and kept on ``client.last_response``."""
+
+    method: str
+    url: str
+    status: int
+    request_id: str | None
+    """The X-Request-Id header. Quote it when you write to BallotData."""
+    rate_limit: RateLimit
+
+
+def _int_header(headers: httpx.Headers, name: str) -> int | None:
+    value = headers.get(name)
+    if value is None or value == "":
+        return None
+    try:
+        return int(float(value))
+    except ValueError:
+        return None
+
+
+def response_info(response: httpx.Response) -> ResponseInfo:
+    h = response.headers
+    return ResponseInfo(
+        method=response.request.method,
+        url=str(response.request.url),
+        status=response.status_code,
+        request_id=h.get("x-request-id"),
+        rate_limit=RateLimit(
+            limit=_int_header(h, "ratelimit-limit"),
+            remaining=_int_header(h, "ratelimit-remaining"),
+            reset=_int_header(h, "ratelimit-reset"),
+            daily_limit=_int_header(h, "x-daily-limit"),
+            daily_remaining=_int_header(h, "x-daily-remaining"),
+        ),
+    )
+
+
+def encode_value(value: Any) -> str | None:
+    """One query value as the API expects it, or None to leave it out."""
+    if value is None or value == "":
+        return None
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, dt.datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=dt.timezone.utc)
+        return str(value.astimezone(dt.timezone.utc).isoformat()).replace("+00:00", "Z")
+    if isinstance(value, dt.date):
+        return value.isoformat()
+    if isinstance(value, (list, tuple, set, frozenset)):
+        items = [s for s in (encode_value(v) for v in value) if s is not None]
+        return ",".join(items) if items else None
+    return str(value)
+
+
+def encode_query(query: Mapping[str, Any] | None) -> dict[str, str]:
+    """Query values as the API expects them: lists comma-separated, booleans true/false, times ISO 8601."""
+    out: dict[str, str] = {}
+    for name, value in (query or {}).items():
+        encoded = encode_value(value)
+        if encoded is not None:
+            out[name] = encoded
+    return out
+
+
+def params(values: Mapping[str, Any], *, rename: Mapping[str, str] | None = None) -> dict[str, Any]:
+    """Keyword arguments to query parameters, dropping the ones not given."""
+    rename = rename or {}
+    return {rename.get(k, k): v for k, v in values.items() if v is not None}
+
+
+def backoff(attempt: int) -> float:
+    """Exponential backoff with jitter: about 0.5s, 1s, 2s … up to 8s."""
+    return float(min(8.0, 0.5 * 2**attempt) * (0.75 + random.random() * 0.5))
+
+
+def retryable_status(status: int, method: str, retry_after: float | None) -> bool:
+    """Whether a response with this status is worth retrying."""
+    # 429 and 503 mean the request wasn't processed, so any method can retry.
+    if status in (429, 503):
+        return retry_after is None or retry_after <= MAX_RETRY_AFTER
+    return method != "POST" and status in (500, 502, 504)
+
+
+class BaseSettings:
+    """Client settings, read from arguments and the environment."""
+
+    api_key: str
+    base_url: str
+    max_retries: int
+    timeout: float
+    default_headers: dict[str, str]
+    on_response: Callable[[ResponseInfo], None] | None
+    last_response: ResponseInfo | None
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str | None,
+        max_retries: int | None,
+        timeout: float | None,
+        default_headers: Mapping[str, str] | None,
+        on_response: Callable[[ResponseInfo], None] | None,
+    ) -> None:
+        key = api_key or os.environ.get("BALLOTDATA_API_KEY")
+        if not key:
+            raise ValueError(
+                "No BallotData API key. Pass api_key=... or set BALLOTDATA_API_KEY. "
+                "Keys come with a purchase at https://ballotdata.net/pricing."
+            )
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get("BALLOTDATA_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = DEFAULT_MAX_RETRIES if max_retries is None else max_retries
+        self.timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        self.default_headers = dict(default_headers or {})
+        self.on_response = on_response
+        self.last_response = None
+
+    def headers(self, extra: Mapping[str, str] | None = None, *, accept: str = "application/json") -> dict[str, str]:
+        """Headers for a request."""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": accept,
+            "User-Agent": USER_AGENT,
+            **self.default_headers,
+            **(extra or {}),
+        }
+
+    def url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def observe(self, response: httpx.Response) -> None:
+        """Record a response for ``last_response`` and ``on_response``."""
+        info = response_info(response)
+        self.last_response = info
+        if self.on_response is not None:
+            self.on_response(info)
+
+
+def path_segment(value: str | int) -> str:
+    """A path segment, escaped."""
+    return quote(str(value), safe="")

ballotdata/_client.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, Literal
+
+import httpx
+
+from ._base import ResponseInfo
+from ._transport import AsyncTransport, RequestOptions, SyncTransport
+from .pagination import AsyncPaginator, SyncPage
+from .resources.contests import AsyncContests, Contests
+from .resources.elections import AsyncElections, Elections
+from .resources.endorsements import AsyncEndorsements, Endorsements
+from .resources.endorsers import AsyncEndorsers, Endorsers
+from .resources.officeholders import AsyncOfficeholders, Officeholders
+from .resources.reference import (
+    AsyncCoverageResource,
+    AsyncEndorserCategories,
+    AsyncStates,
+    CoverageResource,
+    EndorserCategories,
+    States,
+)
+from .resources.subscriptions import AsyncSubscriptions, Subscriptions
+from .stream import AsyncEvents, AsyncStream, Events, Stream
+
+HTTPMethod = Literal["GET", "POST", "PUT", "DELETE"]
+
+
+class BallotData:
+    """A client for the BallotData API.
+
+    ::
+
+        from ballotdata import BallotData
+
+        client = BallotData()  # reads BALLOTDATA_API_KEY
+        contest = client.contests.get(4410, categories="labor")
+
+    Every method also takes ``timeout``, ``max_retries`` and ``extra_headers``
+    keyword arguments to override the client's settings for that call. Use the
+    client as a context manager, or call :meth:`close`, to let go of its
+    connections.
+
+    :param api_key: Your API key (``ebk_…``). Defaults to the ``BALLOTDATA_API_KEY``
+        environment variable. Keys come with a purchase at https://ballotdata.net/pricing
+        and are created in the console at https://api.ballotdata.net/console/keys.
+        Keep keys on servers, never in a browser or mobile app.
+    :param base_url: API origin. Defaults to ``BALLOTDATA_API_URL``, then ``https://api.ballotdata.net``.
+    :param max_retries: How many times to retry a request that failed in a way worth
+        retrying: 429 and 503 (after Retry-After), connection errors and timeouts,
+        and 500, 502 and 504 on GET, PUT and DELETE. Default 2. Set 0 to turn retries off.
+    :param timeout: Seconds to wait for each response. Default 30.
+    :param http_client: An ``httpx.Client`` to send requests with (for proxies, custom
+        TLS, or tests). You close it yourself.
+    :param default_headers: Extra headers to send on every request.
+    :param on_response: Called after every HTTP response (including ones that are
+        retried) with a :class:`ResponseInfo`. Handy for logging and watching rate limits.
+    :raises ValueError: when there is no API key.
+    """
+
+    states: States
+    """``GET /v1/states``."""
+    coverage: CoverageResource
+    """``GET /v1/coverage``."""
+    elections: Elections
+    """``GET /v1/elections``."""
+    contests: Contests
+    """``GET /v1/contests``, ``GET /v1/contests/{id}``."""
+    endorser_categories: EndorserCategories
+    """``GET /v1/endorser-categories``."""
+    endorsers: Endorsers
+    """``GET /v1/endorsers``, ``GET /v1/endorsers/{slug}``."""
+    endorsements: Endorsements
+    """``GET /v1/endorsements``."""
+    officeholders: Officeholders
+    """``GET /v1/officeholders``, ``GET /v1/officeholders/{id}``."""
+    stream: Stream
+    """``GET /v1/stream`` (Server-Sent Events)."""
+    events: Events
+    """``GET /v1/events`` (polling)."""
+    subscriptions: Subscriptions
+    """``/v1/subscriptions``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_retries: int | None = None,
+        timeout: float | None = None,
+        http_client: httpx.Client | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        on_response: Callable[[ResponseInfo], None] | None = None,
+    ) -> None:
+        t = self._transport = SyncTransport(
+            http_client=http_client,
+            api_key=api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+            default_headers=default_headers,
+            on_response=on_response,
+        )
+        self.states = States(t)
+        self.coverage = CoverageResource(t)
+        self.elections = Elections(t)
+        self.contests = Contests(t)
+        self.endorser_categories = EndorserCategories(t)
+        self.endorsers = Endorsers(t)
+        self.endorsements = Endorsements(t)
+        self.officeholders = Officeholders(t)
+        self.stream = Stream(t)
+        self.events = Events(t)
+        self.subscriptions = Subscriptions(t)
+
+    @property
+    def base_url(self) -> str:
+        """The API origin requests go to."""
+        return self._transport.base_url
+
+    @property
+    def last_response(self) -> ResponseInfo | None:
+        """Status, request id and rate-limit headers of the most recent response, or None before the first."""
+        return self._transport.last_response
+
+    def request(
+        self,
+        method: HTTPMethod,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Call any endpoint directly, with the client's key, retries and errors.
+        For endpoints added to the API after this version of the library.
+        Returns the parsed JSON body (None for 204).
+
+        Example::
+
+            body = client.request("GET", "/v1/states")
+        """
+        return self._transport.request(method, path, query=query, body=body, options=RequestOptions(timeout, max_retries, extra_headers))
+
+    def paginate(
+        self,
+        path: str,
+        query: Mapping[str, Any] | None = None,
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> SyncPage[Any]:
+        """Walk any paged list endpoint (``{"data": [...], "next_cursor": ...}``).
+
+        Example::
+
+            for item in client.paginate("/v1/endorsements", {"states": "CA"}):
+                ...
+        """
+        opts = RequestOptions(timeout, max_retries, extra_headers)
+        query = dict(query or {})
+
+        def fetch(cursor: str | None) -> Any:
+            return self._transport.request("GET", path, query={**query, "cursor": cursor}, options=opts)
+
+        return SyncPage(fetch(query.get("cursor")), fetch)
+
+    def close(self) -> None:
+        """Close the client's connections (not an ``http_client`` you passed in)."""
+        self._transport.close()
+
+    def __enter__(self) -> BallotData:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"BallotData(base_url={self.base_url!r})"
+
+
+class AsyncBallotData:
+    """A client for the BallotData API, for asyncio.
+
+    ::
+
+        from ballotdata import AsyncBallotData
+
+        async with AsyncBallotData() as client:  # reads BALLOTDATA_API_KEY
+            contest = await client.contests.get(4410, categories="labor")
+            async for endorsement in client.endorsements.list(states="CA"):
+                ...
+
+    Takes the same arguments as :class:`BallotData`, with an ``httpx.AsyncClient``
+    as ``http_client``.
+    """
+
+    states: AsyncStates
+    """``GET /v1/states``."""
+    coverage: AsyncCoverageResource
+    """``GET /v1/coverage``."""
+    elections: AsyncElections
+    """``GET /v1/elections``."""
+    contests: AsyncContests
+    """``GET /v1/contests``, ``GET /v1/contests/{id}``."""
+    endorser_categories: AsyncEndorserCategories
+    """``GET /v1/endorser-categories``."""
+    endorsers: AsyncEndorsers
+    """``GET /v1/endorsers``, ``GET /v1/endorsers/{slug}``."""
+    endorsements: AsyncEndorsements
+    """``GET /v1/endorsements``."""
+    officeholders: AsyncOfficeholders
+    """``GET /v1/officeholders``, ``GET /v1/officeholders/{id}``."""
+    stream: AsyncStream
+    """``GET /v1/stream`` (Server-Sent Events)."""
+    events: AsyncEvents
+    """``GET /v1/events`` (polling)."""
+    subscriptions: AsyncSubscriptions
+    """``/v1/subscriptions``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_retries: int | None = None,
+        timeout: float | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        on_response: Callable[[ResponseInfo], None] | None = None,
+    ) -> None:
+        t = self._transport = AsyncTransport(
+            http_client=http_client,
+            api_key=api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+            default_headers=default_headers,
+            on_response=on_response,
+        )
+        self.states = AsyncStates(t)
+        self.coverage = AsyncCoverageResource(t)
+        self.elections = AsyncElections(t)
+        self.contests = AsyncContests(t)
+        self.endorser_categories = AsyncEndorserCategories(t)
+        self.endorsers = AsyncEndorsers(t)
+        self.endorsements = AsyncEndorsements(t)
+        self.officeholders = AsyncOfficeholders(t)
+        self.stream = AsyncStream(t)
+        self.events = AsyncEvents(t)
+        self.subscriptions = AsyncSubscriptions(t)
+
+    @property
+    def base_url(self) -> str:
+        """The API origin requests go to."""
+        return self._transport.base_url
+
+    @property
+    def last_response(self) -> ResponseInfo | None:
+        """Status, request id and rate-limit headers of the most recent response, or None before the first."""
+        return self._transport.last_response
+
+    async def request(
+        self,
+        method: HTTPMethod,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Call any endpoint directly. See :meth:`BallotData.request`."""
+        return await self._transport.request(
+            method, path, query=query, body=body, options=RequestOptions(timeout, max_retries, extra_headers)
+        )
+
+    def paginate(
+        self,
+        path: str,
+        query: Mapping[str, Any] | None = None,
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> AsyncPaginator[Any]:
+        """Walk any paged list endpoint. Await for the first page, or ``async for`` every item."""
+        opts = RequestOptions(timeout, max_retries, extra_headers)
+        query = dict(query or {})
+
+        async def fetch(cursor: str | None) -> Any:
+            return await self._transport.request("GET", path, query={**query, "cursor": cursor}, options=opts)
+
+        return AsyncPaginator(fetch, query.get("cursor"))
+
+    async def close(self) -> None:
+        """Close the client's connections (not an ``http_client`` you passed in)."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> AsyncBallotData:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncBallotData(base_url={self.base_url!r})"
+
+
+__all__ = ["BallotData", "AsyncBallotData"]

ballotdata/_sse.py

@@ -0,0 +1,95 @@
+"""A Server-Sent Events parser, following the WHATWG rules."""
+
+from __future__ import annotations
+
+import codecs
+import re
+from collections.abc import AsyncIterable, AsyncIterator, Iterable, Iterator
+from dataclasses import dataclass
+
+_LINE_END = re.compile(r"\r\n|\n|\r")
+_DIGITS = re.compile(r"^\d+$")
+
+
+@dataclass(frozen=True)
+class SSEMessage:
+    """One parsed SSE message."""
+
+    event: str
+    """The ``event:`` field; ``message`` when there was none. Empty for a block that only set ``id`` or ``retry``."""
+    data: str
+    """The ``data:`` lines joined with newlines."""
+    id: str | None = None
+    """The ``id:`` field, when the block had one."""
+    retry: int | None = None
+    """The ``retry:`` field in milliseconds, when the block had one."""
+
+
+class SSEDecoder:
+    """Feed it bytes; it hands back complete messages. Comment lines (the API's
+    ``: ping`` heartbeat) are skipped. A block left unfinished when the stream
+    ends is dropped, as the SSE rules require."""
+
+    def __init__(self) -> None:
+        self._decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+        self._buffer = ""
+        self._event = ""
+        self._data: list[str] = []
+        self._id: str | None = None
+        self._retry: int | None = None
+
+    def feed(self, chunk: bytes) -> list[SSEMessage]:
+        self._buffer += self._decoder.decode(chunk)
+        out: list[SSEMessage] = []
+        while True:
+            match = _LINE_END.search(self._buffer)
+            if match is None:
+                break
+            # A lone \r at the end of what we have may be the first half of \r\n.
+            if match.group() == "\r" and match.start() == len(self._buffer) - 1:
+                break
+            text = self._buffer[: match.start()]
+            self._buffer = self._buffer[match.end() :]
+            message = self._line(text)
+            if message is not None:
+                out.append(message)
+        return out
+
+    def _line(self, text: str) -> SSEMessage | None:
+        if text == "":
+            message = None
+            if self._data or self._event:
+                message = SSEMessage(self._event or "message", "\n".join(self._data), self._id, self._retry)
+            elif self._id is not None or self._retry is not None:
+                message = SSEMessage("", "", self._id, self._retry)
+            self._event, self._data, self._id, self._retry = "", [], None, None
+            return message
+        if text.startswith(":"):
+            return None
+        field, colon, value = text.partition(":")
+        if colon and value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            self._event = value
+        elif field == "data":
+            self._data.append(value)
+        elif field == "id" and "\0" not in value:
+            self._id = value
+        elif field == "retry" and _DIGITS.match(value):
+            self._retry = int(value)
+        return None
+
+
+def iter_sse(chunks: Iterable[bytes]) -> Iterator[SSEMessage]:
+    """Parse an SSE byte stream into messages."""
+    decoder = SSEDecoder()
+    for chunk in chunks:
+        yield from decoder.feed(chunk)
+
+
+async def aiter_sse(chunks: AsyncIterable[bytes]) -> AsyncIterator[SSEMessage]:
+    """Parse an async SSE byte stream into messages."""
+    decoder = SSEDecoder()
+    async for chunk in chunks:
+        for message in decoder.feed(chunk):
+            yield message