cnovatech-sdk-core 0.1.0__py3-none-any.whl

cnovatech/sdk_core/__init__.py

@@ -0,0 +1,24 @@
+"""Shared foundation of the Cnovatech Python SDKs.
+
+This package is not used directly by application code. The product SDKs build
+on its modules (``config``, ``transport``, ``client``, ``resource``, ``models``,
+``pagination``, ``errors``, ...) and re-export what their users need. It knows
+nothing about any product: no endpoint, field name or domain concept lives
+here, and CI enforces that boundary.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .config import CORE_DISTRIBUTION_NAME
+from .metadata import read_distribution_version
+
+__version__ = read_distribution_version(CORE_DISTRIBUTION_NAME)
+
+# Libraries log but never configure logging. The null handler keeps Python from
+# printing "No handlers could be found" when the application has not set up
+# logging; the application routes the `cnovatech` logger wherever it wants.
+logging.getLogger("cnovatech").addHandler(logging.NullHandler())
+
+__all__ = ["__version__"]

cnovatech/sdk_core/client.py

@@ -0,0 +1,146 @@
+"""What every product client shares: configuration, transport, accounting and lifecycle.
+
+A product SDK subclasses :class:`BaseSyncClient` and :class:`BaseAsyncClient`,
+binds its :class:`ProductSettings` and attaches its resources. Everything
+else, from reading the environment to closing the connection pool, is here.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .config import DEFAULT_MAX_RETRIES, DEFAULT_READ_TIMEOUT_SECONDS, build_client_config
+from .transport import AsyncTransport, SyncTransport
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    import httpx
+    from typing_extensions import Self
+
+    from .config import ProductSettings
+    from .usage import RateLimitState, UsageTracker
+
+
+class BaseSyncClient:
+    """A client using blocking I/O. See the product client for the constructor arguments."""
+
+    def __init__(
+        self,
+        product: ProductSettings,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_READ_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_units_per_request: int | None = None,
+        http_client: httpx.Client | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._config = build_client_config(
+            product,
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_units_per_request=max_units_per_request,
+        )
+        self._transport = SyncTransport(self._config, http_client=http_client, transport=transport)
+
+    @property
+    def base_url(self) -> str:
+        """Origin the client talks to."""
+        return self._config.base_url
+
+    @property
+    def usage(self) -> UsageTracker:
+        """Quota spent through this client: ``spent``, ``calls`` and the ``last`` usage block."""
+        return self._transport.usage
+
+    @property
+    def rate_limit(self) -> RateLimitState:
+        """The per-minute rate limit as last reported by the API."""
+        return self._transport.rate_limit
+
+    def close(self) -> None:
+        """Release the connection pool. Clients supplied through ``http_client`` are left open."""
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(base_url={self._config.base_url!r}, "
+            f"api_key={self._config.masked_api_key!r})"
+        )
+
+
+class BaseAsyncClient:
+    """A client using asyncio. See the product client for the constructor arguments."""
+
+    def __init__(
+        self,
+        product: ProductSettings,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_READ_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_units_per_request: int | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._config = build_client_config(
+            product,
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_units_per_request=max_units_per_request,
+        )
+        self._transport = AsyncTransport(self._config, http_client=http_client, transport=transport)
+
+    @property
+    def base_url(self) -> str:
+        """Origin the client talks to."""
+        return self._config.base_url
+
+    @property
+    def usage(self) -> UsageTracker:
+        """Quota spent through this client: ``spent``, ``calls`` and the ``last`` usage block."""
+        return self._transport.usage
+
+    @property
+    def rate_limit(self) -> RateLimitState:
+        """The per-minute rate limit as last reported by the API."""
+        return self._transport.rate_limit
+
+    async def aclose(self) -> None:
+        """Release the connection pool. Clients supplied through ``http_client`` are left open."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(base_url={self._config.base_url!r}, "
+            f"api_key={self._config.masked_api_key!r})"
+        )

cnovatech/sdk_core/config.py

@@ -0,0 +1,257 @@
+"""Client configuration shared by every Cnovatech SDK.
+
+A product SDK describes itself once through :class:`ProductSettings`. The core
+combines that with the constructor arguments and the environment into an
+immutable :class:`ClientConfig`, validating everything before any request is
+sent.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+
+import httpx
+from pydantic import SecretStr
+
+from .errors import APIStatusError, ConfigurationError
+from .metadata import read_distribution_version
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+CORE_DISTRIBUTION_NAME = "cnovatech-sdk-core"
+
+DEFAULT_READ_TIMEOUT_SECONDS = 150.0
+DEFAULT_CONNECT_TIMEOUT_SECONDS = 10.0
+DEFAULT_WRITE_TIMEOUT_SECONDS = 10.0
+DEFAULT_POOL_TIMEOUT_SECONDS = 10.0
+# The server closes any request that runs longer than this.
+MAX_READ_TIMEOUT_SECONDS = 300.0
+DEFAULT_MAX_RETRIES = 2
+
+API_KEY_ENV_SUFFIX = "API_KEY"
+BASE_URL_ENV_SUFFIX = "BASE_URL"
+
+_LOOPBACK_HOSTNAMES = frozenset({"localhost", "127.0.0.1", "::1"})
+_MASK_PREFIX_MAX_LENGTH = 4
+
+
+@dataclass(frozen=True, slots=True)
+class ProductSettings:
+    """What a product SDK tells the core about itself.
+
+    Attributes:
+        distribution_name: Name on PyPI. Appears in the ``User-Agent`` header.
+        version: Installed version of the product SDK.
+        env_prefix: Prefix of the environment variables the client reads,
+            for example ``"DATAMARKET_"``.
+        default_base_url: Production origin of the API, without a trailing slash.
+        api_prefix: Path prefix shared by the authenticated endpoints.
+        api_key_header: Header that carries the API key.
+        error_overrides: Exception classes to raise for specific error codes,
+            in place of the class chosen by HTTP status.
+    """
+
+    distribution_name: str
+    version: str
+    env_prefix: str
+    default_base_url: str
+    api_prefix: str = "/api/v1"
+    api_key_header: str = "X-API-Key"
+    error_overrides: Mapping[str, type[APIStatusError]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class ClientConfig:
+    """Validated settings of one client instance. Build it with :func:`build_client_config`."""
+
+    product: ProductSettings
+    api_key: SecretStr | None
+    base_url: str
+    timeout: httpx.Timeout
+    max_retries: int
+    max_units_per_request: int | None
+    user_agent: str
+
+    @property
+    def hostname(self) -> str:
+        """Host part of ``base_url``, safe to show in messages."""
+        return urlsplit(self.base_url).hostname or self.base_url
+
+    @property
+    def read_timeout_seconds(self) -> float:
+        """Read timeout in seconds. :func:`build_timeout` guarantees it is set."""
+        read_timeout = self.timeout.read
+        if read_timeout is None:
+            raise ConfigurationError("The read timeout must be set.")
+        return float(read_timeout)
+
+    @property
+    def masked_api_key(self) -> str:
+        """The API key as it may appear in ``repr`` and logs."""
+        return mask_api_key(self.api_key)
+
+
+def mask_api_key(api_key: SecretStr | None) -> str:
+    """Redact a key, keeping only a short public prefix such as ``dm_****``."""
+    if api_key is None:
+        return "<not set>"
+    prefix, separator, _ = api_key.get_secret_value().partition("_")
+    if separator and 0 < len(prefix) <= _MASK_PREFIX_MAX_LENGTH:
+        return f"{prefix}_****"
+    return "****"
+
+
+def build_user_agent(product: ProductSettings) -> str:
+    """Identify the product SDK, the core, Python and httpx, in that order."""
+    python_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    core_version = read_distribution_version(CORE_DISTRIBUTION_NAME)
+    return (
+        f"{product.distribution_name}/{product.version} "
+        f"{CORE_DISTRIBUTION_NAME}/{core_version} "
+        f"python/{python_version} httpx/{httpx.__version__}"
+    )
+
+
+def build_client_config(
+    product: ProductSettings,
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout: float | httpx.Timeout = DEFAULT_READ_TIMEOUT_SECONDS,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    max_units_per_request: int | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> ClientConfig:
+    """Resolve and validate the settings of a client.
+
+    Explicit arguments win over environment variables, which win over the
+    product defaults. A blank string counts as not given, at every level.
+    ``environ`` replaces ``os.environ`` in tests.
+
+    Raises:
+        ConfigurationError: A value is invalid. Nothing has been sent.
+    """
+    env = os.environ if environ is None else environ
+    api_key_value = _first_present(api_key, env.get(product.env_prefix + API_KEY_ENV_SUFFIX))
+    base_url_value = (
+        _first_present(base_url, env.get(product.env_prefix + BASE_URL_ENV_SUFFIX))
+        or product.default_base_url
+    )
+    return ClientConfig(
+        product=product,
+        api_key=_validate_api_key(api_key_value) if api_key_value is not None else None,
+        base_url=validate_base_url(base_url_value),
+        timeout=build_timeout(timeout),
+        max_retries=_validate_max_retries(max_retries),
+        max_units_per_request=_validate_max_units_per_request(max_units_per_request),
+        user_agent=build_user_agent(product),
+    )
+
+
+def validate_base_url(base_url: str) -> str:
+    """Normalise a base URL and reject anything the client must not talk to.
+
+    The URL must be absolute, name a host, and use HTTPS. Plain HTTP is accepted
+    only for loopback addresses, so a local API can be used in development
+    without ever sending a key in clear text over a network.
+    """
+    candidate = base_url.strip().rstrip("/")
+    parts = urlsplit(candidate)
+    if parts.scheme not in {"http", "https"} or not parts.hostname:
+        raise ConfigurationError(
+            f"base_url must be an absolute http(s) URL with a host, got {base_url!r}."
+        )
+    if parts.query or parts.fragment:
+        raise ConfigurationError("base_url must not carry a query string or fragment.")
+    if parts.scheme == "http" and parts.hostname not in _LOOPBACK_HOSTNAMES:
+        raise ConfigurationError(
+            f"base_url must use https; plain http is only accepted for loopback, got {base_url!r}."
+        )
+    return candidate
+
+
+def build_timeout(timeout: float | httpx.Timeout) -> httpx.Timeout:
+    """Turn the constructor's ``timeout`` into a complete httpx timeout.
+
+    A number sets the read timeout only; connect, write and pool keep their
+    defaults. An ``httpx.Timeout`` is used as given. The read timeout must be
+    a finite number greater than zero and at most :data:`MAX_READ_TIMEOUT_SECONDS`.
+    """
+    if isinstance(timeout, httpx.Timeout):
+        resolved = timeout
+    else:
+        if not _is_number(timeout):
+            raise ConfigurationError(
+                f"timeout must be a number of seconds or an httpx.Timeout, got {timeout!r}."
+            )
+        resolved = httpx.Timeout(
+            connect=DEFAULT_CONNECT_TIMEOUT_SECONDS,
+            read=float(timeout),
+            write=DEFAULT_WRITE_TIMEOUT_SECONDS,
+            pool=DEFAULT_POOL_TIMEOUT_SECONDS,
+        )
+    read_timeout = resolved.read
+    if (
+        read_timeout is None
+        or not math.isfinite(read_timeout)
+        or read_timeout <= 0
+        or read_timeout > MAX_READ_TIMEOUT_SECONDS
+    ):
+        raise ConfigurationError(
+            "The read timeout must be greater than 0 and at most "
+            f"{MAX_READ_TIMEOUT_SECONDS:g} seconds, the server's own limit; got {read_timeout!r}."
+        )
+    return resolved
+
+
+def _first_present(*candidates: str | None) -> str | None:
+    """The first candidate that is not ``None`` or blank, stripped."""
+    for candidate in candidates:
+        if candidate is not None and candidate.strip():
+            return candidate.strip()
+    return None
+
+
+def _validate_api_key(api_key: str) -> SecretStr:
+    """Refuse a key that cannot travel in an HTTP header. The key itself is never in the message."""
+    if not (api_key.isascii() and api_key.isprintable()) or " " in api_key:
+        raise ConfigurationError(
+            "The API key contains characters that cannot be sent in an HTTP header: only "
+            "printable ASCII without spaces is accepted. Check for invisible characters or "
+            "line breaks copied along with the key."
+        )
+    return SecretStr(api_key)
+
+
+def _validate_max_retries(max_retries: int) -> int:
+    if not _is_integer(max_retries) or max_retries < 0:
+        raise ConfigurationError(
+            f"max_retries must be an integer of at least 0, got {max_retries!r}."
+        )
+    return max_retries
+
+
+def _validate_max_units_per_request(max_units: int | None) -> int | None:
+    if max_units is None:
+        return None
+    if not _is_integer(max_units) or max_units < 1:
+        raise ConfigurationError(
+            f"max_units_per_request must be an integer of at least 1 or None, got {max_units!r}."
+        )
+    return max_units
+
+
+def _is_integer(value: object) -> bool:
+    """An ``int`` that is not a ``bool``; ``True`` would otherwise pass as 1."""
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _is_number(value: object) -> bool:
+    """An ``int`` or ``float`` that is not a ``bool``; numeric strings do not count."""
+    return isinstance(value, (int, float)) and not isinstance(value, bool)

cnovatech/sdk_core/dataframe.py

@@ -0,0 +1,159 @@
+"""Conversion of list responses to pandas DataFrames. pandas is imported only when used."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+from .models import APIResponse
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    import pandas
+
+ENVELOPE_FIELDS_SKIPPED = frozenset({"meta"})
+NESTED_ROWS_SEPARATOR = "."
+_CAMEL_CASE_BOUNDARY = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+class TabularResponse(APIResponse):
+    """A response whose main content is a list of rows.
+
+    Subclasses name the list in ``rows_field`` when it is not ``data``. A
+    dotted name such as ``"groups.members"`` points at a list nested in each
+    item of another list; the parent's own fields are repeated on each row.
+    """
+
+    rows_field: ClassVar[str] = "data"
+
+    def to_dataframe(self, *, include_envelope: bool = True) -> pandas.DataFrame:
+        """One row per item of the list, as a pandas DataFrame.
+
+        Nested objects are flattened with ``_``: ``stats.median_price`` becomes
+        ``stats_median_price``. With ``include_envelope``, the scalar fields
+        around the list, such as the queried entity, the summary and the
+        ``usage`` block, are repeated on every row, prefixed by their name. An
+        envelope field that shares its name with a row field is prefixed with
+        the response's name instead, as in ``product_image_url`` next to the
+        offer's ``image_url``, so no value is lost. Lists inside items are kept
+        as Python lists.
+
+        Requires pandas, available through the SDK's ``pandas`` extra.
+        """
+        return build_dataframe(self, rows_field=self.rows_field, include_envelope=include_envelope)
+
+
+def build_dataframe(
+    response: APIResponse, *, rows_field: str, include_envelope: bool
+) -> pandas.DataFrame:
+    """Build the DataFrame of ``response`` from the list in ``rows_field``.
+
+    Only the named list is serialised; sibling lists are left out of the dump
+    since the envelope never includes them.
+    """
+    parent_field, _, child_field = rows_field.partition(NESTED_ROWS_SEPARATOR)
+    payload = response.model_dump(mode="python", exclude=_other_lists(response, parent_field))
+    parents = [row for row in payload.pop(parent_field, None) or [] if isinstance(row, dict)]
+    if child_field:
+        rows = [
+            {**flatten(_without(parent, child_field)), **flatten(child)}
+            for parent in parents
+            for child in parent.get(child_field) or []
+            if isinstance(child, dict)
+        ]
+    else:
+        rows = [flatten(row) for row in parents]
+    envelope: dict[str, Any] = {}
+    if include_envelope:
+        envelope = disambiguate_envelope(
+            flatten_envelope(payload), rows, prefix=response_prefix(response)
+        )
+    records = [{**envelope, **row} for row in rows]
+    return records_to_dataframe(records, columns=column_union(records) or list(envelope))
+
+
+def disambiguate_envelope(
+    envelope: Mapping[str, Any], rows: Sequence[Mapping[str, Any]], *, prefix: str
+) -> dict[str, Any]:
+    """Prefix the envelope columns that a row also uses, so both values get a column."""
+    row_keys = {key for row in rows for key in row}
+    return {
+        (f"{prefix}_{key}" if key in row_keys else key): value for key, value in envelope.items()
+    }
+
+
+def response_prefix(response: APIResponse) -> str:
+    """The response's class name in snake case: ``PriceHistory`` gives ``price_history``."""
+    return _CAMEL_CASE_BOUNDARY.sub("_", type(response).__name__).lower()
+
+
+def column_union(records: Sequence[Mapping[str, Any]]) -> list[str]:
+    """Every key seen across the records, in order of first appearance.
+
+    Rows need not share the same keys: free-form objects and fields the API
+    adds to some rows only still get a column.
+    """
+    seen: dict[str, None] = {}
+    for record in records:
+        for key in record:
+            seen.setdefault(key, None)
+    return list(seen)
+
+
+def records_to_dataframe(
+    records: Sequence[Mapping[str, Any]], *, columns: Sequence[str]
+) -> pandas.DataFrame:
+    """Build a DataFrame from flat records, importing pandas on first use."""
+    try:
+        import pandas as pandas_module
+    except ImportError as exc:
+        raise ImportError(
+            "pandas is not installed. Install it, or install the SDK with its 'pandas' extra."
+        ) from exc
+    # pandas ships partial inline types, so the constructor resolves to Any.
+    return cast("pandas.DataFrame", pandas_module.DataFrame(list(records), columns=list(columns)))
+
+
+def flatten(mapping: Mapping[str, Any], prefix: str = "") -> dict[str, Any]:
+    """Flatten nested mappings into one level, joining keys with ``_``."""
+    flat: dict[str, Any] = {}
+    for key, value in mapping.items():
+        name = f"{prefix}{key}"
+        if isinstance(value, dict):
+            flat.update(flatten(value, f"{name}_"))
+        else:
+            flat[name] = value
+    return flat
+
+
+def flatten_envelope(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Flatten what surrounds the rows: scalars as they are, objects prefixed by their name.
+
+    A field of an object that already starts with the object's name keeps it:
+    ``store.store_id`` becomes ``store_id``, ``store.city`` becomes
+    ``store_city``. Lists and pagination metadata are left out.
+    """
+    flat: dict[str, Any] = {}
+    for key, value in payload.items():
+        if key in ENVELOPE_FIELDS_SKIPPED or isinstance(value, list):
+            continue
+        if isinstance(value, dict):
+            for inner_key, inner_value in flatten(value).items():
+                name = inner_key if inner_key.startswith(f"{key}_") else f"{key}_{inner_key}"
+                flat[name] = inner_value
+        else:
+            flat[key] = value
+    return flat
+
+
+def _other_lists(response: APIResponse, keep: str) -> set[str]:
+    return {
+        name
+        for name in type(response).model_fields
+        if name != keep and isinstance(getattr(response, name, None), list)
+    }
+
+
+def _without(mapping: Mapping[str, Any], key: str) -> dict[str, Any]:
+    return {name: value for name, value in mapping.items() if name != key}