firmendata 0.1.0__py3-none-any.whl

firmendata/__init__.py

@@ -0,0 +1,51 @@
+"""Official Python client for the firmendata German company-data API.
+
+Autocomplete is free and needs no API key::
+
+    from firmendata import FirmenData
+
+    for hit in FirmenData().autocomplete("siemens")["data"]:
+        print(hit["display_name"], hit["eu_id"])
+
+Everything else needs a key from https://firmendata.com/de/account/api-keys::
+
+    fd = FirmenData(api_key="firmendata_live_...")
+    company = fd.get_company("DEB1103R_HRB123456")
+"""
+
+from ._version import __version__
+from .async_client import AsyncFirmenData
+from .client import FirmenData
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    FirmenDataError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TokenExpiredError,
+    ValidationError,
+)
+
+__all__ = [
+    "__version__",
+    "FirmenData",
+    "AsyncFirmenData",
+    # errors
+    "FirmenDataError",
+    "APIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "TokenExpiredError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+]

firmendata/_base.py

@@ -0,0 +1,97 @@
+"""Shared plumbing between the sync and async clients."""
+
+from __future__ import annotations
+
+import json as _json
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+
+from ._retry import DEFAULT_MAX_RETRIES
+from ._version import __version__
+from .errors import build_error
+
+DEFAULT_BASE_URL = "https://api.firmendata.com"
+DEFAULT_TIMEOUT = 30.0
+
+ParamValue = str | int | float | bool | Sequence[str] | Sequence[int] | None
+
+#: Exactly the element type httpx declares for `params`. We only ever emit
+#: strings, but `list` is invariant, so a narrower `list[tuple[str, str]]`
+#: would not be accepted where httpx wants this.
+QueryParamPairs = list[tuple[str, str | int | float | bool | None]]
+
+
+class _BaseClient:
+    """URL, header and parameter handling. No I/O lives here."""
+
+    def __init__(
+            self,
+            api_key: str | None = None,
+            *,
+            base_url: str = DEFAULT_BASE_URL,
+            timeout: float = DEFAULT_TIMEOUT,
+            max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        #: ``None`` is legitimate: ``autocomplete()`` works without a key.
+        #: Every other endpoint will raise ``AuthenticationError``.
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+
+    # -- request shaping ---------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"firmendata-python/{__version__}",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    @staticmethod
+    def _params(raw: Mapping[str, ParamValue]) -> QueryParamPairs:
+        """Flatten query parameters, dropping ``None``.
+
+        Returned as a list of pairs rather than a dict so array filters
+        (``city``, ``industry_slug``, …) repeat the key — ``?city=Berlin&
+        city=Hamburg`` — which is the form the API parses. Booleans are
+        lower-cased because ``str(True)`` is ``"True"``, which FastAPI's bool
+        coercion rejects.
+        """
+        out: QueryParamPairs = []
+        for key, value in raw.items():
+            if value is None:
+                continue
+            if isinstance(value, bool):
+                out.append((key, "true" if value else "false"))
+            elif isinstance(value, (str, int, float)):
+                out.append((key, str(value)))
+            elif isinstance(value, Iterable):
+                for item in value:
+                    if item is None:
+                        continue
+                    out.append((key, str(item)))
+            else:  # pragma: no cover - defensive
+                out.append((key, str(value)))
+        return out
+
+    # -- response handling -------------------------------------------------
+
+    @staticmethod
+    def _decode(status_code: int, content: bytes, headers: Mapping[str, str]) -> Any:
+        """Parse a response body, raising the mapped error for non-2xx."""
+        body: Any = None
+        if content:
+            try:
+                body = _json.loads(content)
+            except ValueError:
+                body = None
+
+        if 200 <= status_code < 300:
+            return body
+        raise build_error(status_code, body, headers)

firmendata/_retry.py

@@ -0,0 +1,72 @@
+"""Retry policy, kept as pure functions so sync and async share one brain.
+
+Two rules do the real work:
+
+* **429 is always safe to retry, on any method.** The server rejects a
+  rate-limited call *before* the handler runs — nothing happened, nothing was
+  billed. Its ``Retry-After`` is authoritative and is used verbatim.
+
+* **5xx and connection failures are retried only for idempotent methods.**
+  A ``POST /v1/subscriptions`` that fails with a 502 may well have created the
+  subscription before the proxy gave up; retrying it would create a second
+  one. GET and DELETE can be repeated safely, POST cannot.
+
+Backoff is exponential with **full jitter** (``random(0, base * 2**n)``)
+rather than a fixed ramp: when many clients trip the same limit at once, an
+undithered backoff simply reconvenes them all at the same instant.
+"""
+
+from __future__ import annotations
+
+import random
+
+#: Methods that may be replayed after an ambiguous failure.
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+
+DEFAULT_MAX_RETRIES = 2
+_BASE_DELAY_SECONDS = 0.5
+_MAX_DELAY_SECONDS = 20.0
+
+
+def should_retry(
+        *,
+        method: str,
+        status_code: int | None,
+        attempt: int,
+        max_retries: int,
+) -> bool:
+    """Whether to make attempt ``attempt + 1``.
+
+    ``status_code`` is ``None`` for a transport failure (no response).
+    """
+    if attempt >= max_retries:
+        return False
+
+    idempotent = method.upper() in IDEMPOTENT_METHODS
+
+    if status_code is None:          # connection reset, timeout, DNS
+        return idempotent
+    if status_code == 429:           # never executed — always replayable
+        return True
+    if status_code == 408:           # server-side timeout, same reasoning as 5xx
+        return idempotent
+    if status_code >= 500:
+        return idempotent
+    return False
+
+
+def backoff_seconds(
+        attempt: int,
+        *,
+        retry_after: float | None = None,
+        rng: random.Random | None = None,
+) -> float:
+    """Delay before the next attempt. ``attempt`` is 0-based.
+
+    A server-supplied ``Retry-After`` wins outright — it knows when the window
+    actually resets, and guessing shorter just burns another rejection.
+    """
+    if retry_after is not None and retry_after >= 0:
+        return min(retry_after, _MAX_DELAY_SECONDS)
+    ceiling = min(_BASE_DELAY_SECONDS * (2 ** attempt), _MAX_DELAY_SECONDS)
+    return (rng or random).uniform(0.0, ceiling)

firmendata/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

firmendata/async_client.py

@@ -0,0 +1,229 @@
+"""Asynchronous client for the firmendata public API.
+
+Mirrors :class:`firmendata.client.FirmenData` method for method. The
+signatures and semantics are identical — only the transport differs — so the
+docstrings there are the reference for both. Retry policy is shared verbatim
+via :mod:`firmendata._retry`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Unpack
+
+import httpx
+
+from ._base import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, _BaseClient
+from ._retry import DEFAULT_MAX_RETRIES, backoff_seconds, should_retry
+from .errors import APIConnectionError, APITimeoutError, RateLimitError
+from .params import SearchFilters, SubscriptionFilters
+from .types import (
+    AutocompleteResponse,
+    CompanyDetail,
+    CompanyDocumentDownload,
+    CompanyFinancials,
+    CompanyHistory,
+    SearchResponse,
+    ShareholdersReport,
+    Subscription,
+    SubscriptionCreated,
+    SubscriptionEvent,
+    SubscriptionEventList,
+    SubscriptionEventResendResponse,
+    SubscriptionList,
+    SubscriptionTestResponse,
+    UboReport,
+)
+
+__all__ = ["AsyncFirmenData"]
+
+
+class AsyncFirmenData(_BaseClient):
+    """Async client for ``https://api.firmendata.com``.
+
+        >>> async with AsyncFirmenData() as fd:
+        ...     hits = await fd.autocomplete("siemens")
+
+    The API key is optional; without one only :meth:`autocomplete` works.
+    """
+
+    def __init__(
+            self,
+            api_key: str | None = None,
+            *,
+            base_url: str = DEFAULT_BASE_URL,
+            timeout: float = DEFAULT_TIMEOUT,
+            max_retries: int = DEFAULT_MAX_RETRIES,
+            http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            api_key, base_url=base_url, timeout=timeout, max_retries=max_retries,
+        )
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+    # -- lifecycle ---------------------------------------------------------
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncFirmenData:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    # -- transport ---------------------------------------------------------
+
+    async def _request(
+            self,
+            method: str,
+            path: str,
+            *,
+            params: dict[str, Any] | None = None,
+            json: dict[str, Any] | None = None,
+    ) -> Any:
+        url = self._url(path)
+        query = self._params(params or {})
+        attempt = 0
+
+        while True:
+            status: int | None = None
+            retry_after: float | None = None
+            try:
+                response = await self._http.request(
+                    method, url,
+                    params=httpx.QueryParams(query) if query else None,
+                    json=json,
+                    headers=self._headers(),
+                    timeout=self.timeout,
+                )
+                status = response.status_code
+                if 200 <= status < 300:
+                    return self._decode(status, response.content, response.headers)
+
+                try:
+                    self._decode(status, response.content, response.headers)
+                except RateLimitError as exc:
+                    retry_after = exc.retry_after
+                    error: Exception = exc
+                except Exception as exc:  # noqa: BLE001 - re-raised below
+                    error = exc
+                else:  # pragma: no cover - _decode always raises here
+                    raise AssertionError("non-2xx did not raise")
+
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                error = APITimeoutError(str(exc)) if isinstance(
+                    exc, httpx.TimeoutException
+                ) else APIConnectionError(str(exc))
+
+            if not should_retry(
+                method=method, status_code=status,
+                attempt=attempt, max_retries=self.max_retries,
+            ):
+                raise error
+
+            await asyncio.sleep(backoff_seconds(attempt, retry_after=retry_after))
+            attempt += 1
+
+    # -- companies ---------------------------------------------------------
+
+    async def autocomplete(
+            self, q: str, *, limit: int = 10, fetch_realtime: bool = False,
+    ) -> AutocompleteResponse:
+        """Free, keyless company-name suggestions. See the sync client."""
+        return await self._request(
+            "GET", "/v1/companies/autocomplete",
+            params={"q": q, "limit": limit, "fetch_realtime": fetch_realtime},
+        )
+
+    async def search(self, **filters: Unpack[SearchFilters]) -> SearchResponse:
+        """Advanced register search."""
+        return await self._request("GET", "/v1/companies/search", params=dict(filters))
+
+    async def get_company(
+            self, eu_id: str, *, fetch_realtime: bool = False,
+    ) -> CompanyDetail:
+        return await self._request(
+            "GET", f"/v1/companies/{eu_id}", params={"fetch_realtime": fetch_realtime},
+        )
+
+    async def get_financials(self, eu_id: str) -> CompanyFinancials:
+        return await self._request("GET", f"/v1/companies/{eu_id}/financials")
+
+    async def get_shareholders(
+            self, eu_id: str, *, fetch_realtime: bool = False,
+    ) -> ShareholdersReport:
+        return await self._request(
+            "GET", f"/v1/companies/{eu_id}/shareholders",
+            params={"fetch_realtime": fetch_realtime},
+        )
+
+    async def get_ubo(self, eu_id: str, *, fetch_realtime: bool = False) -> UboReport:
+        return await self._request(
+            "GET", f"/v1/companies/{eu_id}/ubo",
+            params={"fetch_realtime": fetch_realtime},
+        )
+
+    async def get_history(
+            self, eu_id: str, *, fetch_realtime: bool = False,
+    ) -> CompanyHistory:
+        return await self._request(
+            "GET", f"/v1/companies/{eu_id}/history",
+            params={"fetch_realtime": fetch_realtime},
+        )
+
+    async def download_document(
+            self,
+            eu_id: str,
+            *,
+            file_type: str,
+            file_id: str | None = None,
+            fetch_realtime: bool = False,
+    ) -> CompanyDocumentDownload:
+        return await self._request(
+            "GET", f"/v1/companies/{eu_id}/documents/download",
+            params={
+                "file_type": file_type,
+                "file_id": file_id,
+                "fetch_realtime": fetch_realtime,
+            },
+        )
+
+    # -- subscriptions -----------------------------------------------------
+
+    async def list_subscriptions(
+            self, **filters: Unpack[SubscriptionFilters],
+    ) -> SubscriptionList:
+        return await self._request("GET", "/v1/subscriptions", params=dict(filters))
+
+    async def create_subscription(self, **body: Any) -> SubscriptionCreated:
+        """Not retried on 5xx — a replay could create a duplicate."""
+        return await self._request("POST", "/v1/subscriptions", json=body)
+
+    async def get_subscription(self, subscription_id: str) -> Subscription:
+        return await self._request("GET", f"/v1/subscriptions/{subscription_id}")
+
+    async def delete_subscription(self, subscription_id: str) -> Any:
+        return await self._request("DELETE", f"/v1/subscriptions/{subscription_id}")
+
+    async def list_events(
+            self, subscription_id: str, *, limit: int | None = None,
+            offset: int | None = None,
+    ) -> SubscriptionEventList:
+        return await self._request(
+            "GET", f"/v1/subscriptions/{subscription_id}/events",
+            params={"limit": limit, "offset": offset},
+        )
+
+    async def get_event(self, event_id: str) -> SubscriptionEvent:
+        return await self._request("GET", f"/v1/subscriptions/events/{event_id}")
+
+    async def resend_event(self, event_id: str) -> SubscriptionEventResendResponse:
+        return await self._request(
+            "POST", f"/v1/subscriptions/events/{event_id}/resend",
+        )
+
+    async def test_delivery(self, **body: Any) -> SubscriptionTestResponse:
+        return await self._request("POST", "/v1/subscriptions/test", json=body)