checkanysite 0.1.0__py3-none-any.whl

checkanysite/__init__.py

@@ -0,0 +1,48 @@
+"""The official Python library for the CheckAnySite API: what is this website, with evidence.
+
+    from checkanysite import CheckAnySite
+
+    client = CheckAnySite()  # reads CHECKANYSITE_API_KEY
+    site = client.sites.retrieve("stripe.com", checks=["ai", "tech"])
+
+Docs: https://docs.checkanysite.com. The answers' types are in `checkanysite.models`.
+"""
+
+from . import models
+from ._client import AsyncCheckAnySite, CheckAnySite
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ScanTimeoutError,
+    UnprocessableEntityError,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncCheckAnySite",
+    "AuthenticationError",
+    "BadRequestError",
+    "CheckAnySite",
+    "ConflictError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ScanTimeoutError",
+    "UnprocessableEntityError",
+    "__version__",
+    "models",
+]

checkanysite/_base_client.py

@@ -0,0 +1,268 @@
+"""Sending a request to the API: authentication, idempotency keys, retries and typed answers.
+
+What: `SyncAPIClient` and `AsyncAPIClient`, the transport the clients in _client.py build on.
+Each call is one `httpx.Request` (with one Idempotency-Key for a POST), sent until it succeeds,
+fails in a way that won't pass (_retries.py), or runs out of retries; a success is parsed into
+its model with the answer's headers as `.meta`, an error answer into the class for its status.
+Why one request object for every try: a retried POST must carry the same Idempotency-Key, so the
+API replays the first answer instead of doing (and charging for) the work twice.
+Not here: the endpoints (resources/) or the retry rules (_retries.py).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import time
+import uuid
+from collections.abc import Awaitable, Mapping
+from typing import Callable, Optional, TypeVar, Union
+
+import httpx
+
+from ._constants import API_KEY_ENV, BASE_URL_ENV, DEFAULT_BASE_URL, USER_AGENT
+from ._retries import is_retryable_status, retry_delay_seconds
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    error_from_response,
+)
+from .models import ResponseMeta, ResponseModel
+
+ResponseT = TypeVar("ResponseT", bound=ResponseModel)
+
+Timeout = Union[float, httpx.Timeout]
+"""Seconds for each of connecting, sending and reading, or an `httpx.Timeout` for each apart."""
+
+RequestFailure = Union[APIStatusError, APIConnectionError]
+"""How one try can fail: an error answer, or no answer."""
+
+QueryParams = Mapping[str, Union[str, int]]
+JsonBody = Mapping[str, object]
+
+
+class _BaseClient:
+    """What the sync and async clients share: their settings, how a request is built and read."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        timeout: Timeout,
+        max_retries: int,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get(API_KEY_ENV)
+        if not key:
+            raise APIError(
+                f"No API key: pass api_key=... or set {API_KEY_ENV}. "
+                "Get one free at https://checkanysite.com/account/keys."
+            )
+        if max_retries < 0:
+            raise ValueError("max_retries must be 0 or more.")
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    def _build_request(
+        self,
+        http: Union[httpx.Client, httpx.AsyncClient],
+        method: str,
+        path: str,
+        params: Optional[QueryParams],
+        body: Optional[JsonBody],
+        idempotency_key: Optional[str],
+    ) -> httpx.Request:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if method == "POST":
+            # One key per call, reused by its retries, so a retried POST is never done twice.
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        return http.build_request(
+            method,
+            f"{self.base_url}{path}",
+            params=dict(params) if params else None,
+            json=dict(body) if body is not None else None,
+            headers=headers,
+            timeout=self.timeout,
+        )
+
+    def _retry_delay(self, retries_done: int, error: RequestFailure) -> Optional[float]:
+        """The wait before trying again after this error, or None to raise it now."""
+        if retries_done >= self.max_retries:
+            return None
+        if isinstance(error, APIStatusError):
+            if not is_retryable_status(error.status_code, error.code):
+                return None
+            return retry_delay_seconds(retries_done, error.retry_after_seconds)
+        # No answer at all (a connection error or a timeout): always worth another try.
+        return retry_delay_seconds(retries_done, None)
+
+
+class _OwnedClient(httpx.Client):
+    """The `httpx.Client` a client makes for itself, closed when it is garbage collected.
+
+    Why: a client used without `with` or `close()`, as a script's one client often is, would keep
+    its pooled connections open until the interpreter exits, and Python warns about each one
+    (ResourceWarning: unclosed socket).
+    """
+
+    def __del__(self) -> None:
+        if self.is_closed:
+            return
+        # Nothing can be reported from a finalizer, so a failure to close is let pass.
+        with contextlib.suppress(Exception):
+            self.close()
+
+
+class _OwnedAsyncClient(httpx.AsyncClient):
+    """The `httpx.AsyncClient` an async client makes for itself, closed when it is collected
+    while its event loop still runs (`async with` closes it for sure)."""
+
+    def __del__(self) -> None:
+        if self.is_closed:
+            return
+        # Without a running loop (RuntimeError) there is nothing to close it on.
+        with contextlib.suppress(Exception):
+            asyncio.get_running_loop().create_task(self.aclose())
+
+
+def _connection_error(exception: httpx.RequestError) -> APIConnectionError:
+    error = (
+        APITimeoutError()
+        if isinstance(exception, httpx.TimeoutException)
+        else APIConnectionError(f"Could not reach the CheckAnySite API: {exception}")
+    )
+    error.__cause__ = exception
+    return error
+
+
+def _parse(response: httpx.Response, cast_to: type[ResponseT]) -> ResponseT:
+    """The successful answer as its model, carrying the answer's headers as `.meta`."""
+    try:
+        data = response.json()
+    except ValueError as exception:
+        raise APIError(
+            f"The API answered {response.status_code} without a JSON body.",
+            status_code=response.status_code,
+            request_id=response.headers.get("x-request-id"),
+        ) from exception
+    model = cast_to.model_validate(data)
+    model._meta = ResponseMeta.from_headers(response.status_code, response.headers)
+    return model
+
+
+class SyncAPIClient(_BaseClient):
+    """Sends requests with `httpx.Client`, waiting between retries with `time.sleep`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        timeout: Timeout,
+        max_retries: int,
+        http_client: Optional[httpx.Client],
+    ) -> None:
+        super().__init__(
+            api_key=api_key, base_url=base_url, timeout=timeout, max_retries=max_retries
+        )
+        self._owns_http_client = http_client is None
+        self._http = http_client if http_client is not None else _OwnedClient()
+        # The clock and the wait, as attributes so tests can stand in for them.
+        self._sleep: Callable[[float], None] = time.sleep
+        self._clock: Callable[[], float] = time.monotonic
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        cast_to: type[ResponseT],
+        params: Optional[QueryParams] = None,
+        body: Optional[JsonBody] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> ResponseT:
+        request = self._build_request(self._http, method, path, params, body, idempotency_key)
+        retries_done = 0
+        while True:
+            error: RequestFailure
+            try:
+                response = self._http.send(request)
+            except httpx.RequestError as exception:
+                error = _connection_error(exception)
+            else:
+                if response.is_success:
+                    return _parse(response, cast_to)
+                error = error_from_response(response)
+            delay = self._retry_delay(retries_done, error)
+            if delay is None:
+                raise error
+            self._sleep(delay)
+            retries_done += 1
+
+    def close(self) -> None:
+        """Close the connections, unless the `http_client` was passed in (its owner closes it)."""
+        if self._owns_http_client:
+            self._http.close()
+
+
+class AsyncAPIClient(_BaseClient):
+    """Sends requests with `httpx.AsyncClient`, waiting between retries with `asyncio.sleep`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        timeout: Timeout,
+        max_retries: int,
+        http_client: Optional[httpx.AsyncClient],
+    ) -> None:
+        super().__init__(
+            api_key=api_key, base_url=base_url, timeout=timeout, max_retries=max_retries
+        )
+        self._owns_http_client = http_client is None
+        self._http = http_client if http_client is not None else _OwnedAsyncClient()
+        self._sleep: Callable[[float], Awaitable[None]] = asyncio.sleep
+        self._clock: Callable[[], float] = time.monotonic
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        cast_to: type[ResponseT],
+        params: Optional[QueryParams] = None,
+        body: Optional[JsonBody] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> ResponseT:
+        request = self._build_request(self._http, method, path, params, body, idempotency_key)
+        retries_done = 0
+        while True:
+            error: RequestFailure
+            try:
+                response = await self._http.send(request)
+            except httpx.RequestError as exception:
+                error = _connection_error(exception)
+            else:
+                if response.is_success:
+                    return _parse(response, cast_to)
+                error = error_from_response(response)
+            delay = self._retry_delay(retries_done, error)
+            if delay is None:
+                raise error
+            await self._sleep(delay)
+            retries_done += 1
+
+    async def close(self) -> None:
+        """Close the connections, unless the `http_client` was passed in (its owner closes it)."""
+        if self._owns_http_client:
+            await self._http.aclose()

checkanysite/_client.py

@@ -0,0 +1,130 @@
+"""The two clients: `CheckAnySite` (sync) and `AsyncCheckAnySite` (async), one surface for both.
+
+What: settings (key, base URL, timeout, retries) and the resources `sites`, `scans` and `usage`.
+Not here: sending and retrying requests (_base_client.py) or the endpoints (resources/).
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Optional
+
+import httpx
+
+from ._base_client import AsyncAPIClient, SyncAPIClient, Timeout
+from ._constants import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_SECONDS
+from .resources import (
+    AsyncScansResource,
+    AsyncSitesResource,
+    AsyncUsageResource,
+    ScansResource,
+    SitesResource,
+    UsageResource,
+)
+
+
+class CheckAnySite(SyncAPIClient):
+    """The CheckAnySite API client.
+
+    Example:
+        >>> from checkanysite import CheckAnySite
+        >>> client = CheckAnySite()  # reads CHECKANYSITE_API_KEY
+        >>> site = client.sites.retrieve("stripe.com", checks=["ai", "tech"])
+        >>> site.meta.credits_remaining
+
+    Args:
+        api_key: your key (`cas_live_…`); read from CHECKANYSITE_API_KEY when left out.
+        base_url: the API's address; CHECKANYSITE_BASE_URL, else https://api.checkanysite.com/v1.
+        timeout: seconds each request may take to connect, send and read (30 by default), or an
+            `httpx.Timeout`.
+        max_retries: retries after the first try for failures that may pass (2 by default; 0
+            turns retrying off).
+        http_client: an `httpx.Client` of your own (proxies, transports); you close it yourself.
+
+    Raises:
+        APIError: no API key was passed or found in the environment.
+    """
+
+    sites: SitesResource
+    """The Lookup API: stored results, at once, never a scan."""
+    scans: ScansResource
+    """The Scan API: live scans, answered asynchronously."""
+    usage: UsageResource
+    """This month's credits."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Timeout = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.sites = SitesResource(self)
+        self.scans = ScansResource(self)
+        self.usage = UsageResource(self)
+
+    def __enter__(self) -> CheckAnySite:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+
+class AsyncCheckAnySite(AsyncAPIClient):
+    """The CheckAnySite API client for asyncio, with the same methods as `CheckAnySite`.
+
+    Example:
+        >>> async with AsyncCheckAnySite() as client:
+        ...     site = await client.sites.retrieve("stripe.com", checks=["ai"])
+
+    Args: as for `CheckAnySite`, with an `httpx.AsyncClient` as `http_client`.
+    """
+
+    sites: AsyncSitesResource
+    scans: AsyncScansResource
+    usage: AsyncUsageResource
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Timeout = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.sites = AsyncSitesResource(self)
+        self.scans = AsyncScansResource(self)
+        self.usage = AsyncUsageResource(self)
+
+    async def __aenter__(self) -> AsyncCheckAnySite:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        await self.close()

checkanysite/_constants.py

@@ -0,0 +1,49 @@
+"""The library's defaults in one place: where the API is, how long to wait, how often to retry.
+
+Each can be changed per client (`CheckAnySite(timeout=..., max_retries=...)`); the base URL and
+the key can also come from the environment.
+"""
+
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.checkanysite.com/v1"
+"""The API v1 (https://checkanysite.com/api/v1 answers the same)."""
+
+API_KEY_ENV = "CHECKANYSITE_API_KEY"
+"""The environment variable read when no `api_key` is passed."""
+
+BASE_URL_ENV = "CHECKANYSITE_BASE_URL"
+"""The environment variable read when no `base_url` is passed."""
+
+USER_AGENT = f"checkanysite-python/{__version__}"
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+"""How long one request may wait for each of connecting, sending and reading."""
+
+DEFAULT_MAX_RETRIES = 2
+"""Retries after the first try, for failures that may pass (see _retries.py)."""
+
+INITIAL_RETRY_DELAY_SECONDS = 0.5
+"""The first retry's wait without a Retry-After header; it doubles with each retry."""
+
+MAX_RETRY_DELAY_SECONDS = 8.0
+"""The longest wait between retries without a Retry-After header."""
+
+RETRY_JITTER_FRACTION = 0.25
+"""Up to this share of a backoff wait is taken off at random, so clients don't retry in step."""
+
+MAX_RETRY_AFTER_SECONDS = 60.0
+"""The longest Retry-After the library waits out by itself; a longer one is raised to the caller.
+
+The API's rate limit window is 60 seconds; a longer wait (no capacity for new scans until later)
+is the caller's to decide.
+"""
+
+DEFAULT_WAIT_TIMEOUT_SECONDS = 120.0
+"""How long `scans.create_and_wait` waits for a scan to be complete before raising."""
+
+DEFAULT_POLL_INTERVAL_SECONDS = 3.0
+"""The wait between polls of a scan when the API sends no Retry-After (it sends 3 seconds)."""
+
+MIN_POLL_INTERVAL_SECONDS = 1.0
+"""Never poll a scan more than once a second, whatever Retry-After says (a polite client)."""

checkanysite/_retries.py

@@ -0,0 +1,60 @@
+"""When a failed request is tried again, and after how long (ADR 0102).
+
+What: two pure functions the sync and async clients share. A request is retried when the
+failure may pass by itself:
+- no answer (a connection error or a timeout);
+- 409 `idempotency_key_in_use`: the first request with this key is still running;
+- 429 only for `rate_limited`, never `quota_exceeded` or `key_limit_reached` (credits spent) or
+  `scan_limit_reached` (the day's new scans started);
+- 500, 502, 503 and 504.
+Retrying a POST is safe because it carries the same Idempotency-Key on every try.
+Not here: the loop itself, which sleeps in the sync or async way (_base_client.py).
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Callable, Optional
+
+from ._constants import (
+    INITIAL_RETRY_DELAY_SECONDS,
+    MAX_RETRY_AFTER_SECONDS,
+    MAX_RETRY_DELAY_SECONDS,
+    RETRY_JITTER_FRACTION,
+)
+
+RETRYABLE_STATUSES = frozenset({500, 502, 503, 504})
+"""Statuses retried whatever their code."""
+
+RETRYABLE_CODES = {409: frozenset({"idempotency_key_in_use"}), 429: frozenset({"rate_limited"})}
+"""Statuses retried only for these codes."""
+
+
+def is_retryable_status(status_code: int, code: Optional[str]) -> bool:
+    """True when an error answer with this status and code may succeed if asked again."""
+    if status_code in RETRYABLE_STATUSES:
+        return True
+    return code is not None and code in RETRYABLE_CODES.get(status_code, frozenset())
+
+
+def retry_delay_seconds(
+    retries_done: int,
+    retry_after_seconds: Optional[float],
+    random_fraction: Callable[[], float] = random.random,
+) -> Optional[float]:
+    """How long to wait before the next try, or None when the wait is the caller's to decide.
+
+    Args:
+        retries_done: how many retries came before this one (0 for the first).
+        retry_after_seconds: the answer's Retry-After, if it sent one.
+        random_fraction: a source of numbers in [0, 1), for the jitter (passed in by tests).
+
+    Returns:
+        The Retry-After when the API sent one it is reasonable to wait out (up to 60 seconds);
+        else an exponential backoff (0.5, 1, 2 … up to 8 seconds) with up to a quarter taken off
+        at random. None when the Retry-After is longer than the library waits by itself.
+    """
+    if retry_after_seconds is not None:
+        return retry_after_seconds if retry_after_seconds <= MAX_RETRY_AFTER_SECONDS else None
+    backoff: float = min(INITIAL_RETRY_DELAY_SECONDS * 2.0**retries_done, MAX_RETRY_DELAY_SECONDS)
+    return backoff * (1 - RETRY_JITTER_FRACTION * random_fraction())

checkanysite/_version.py

@@ -0,0 +1,3 @@
+"""The library's version: sent in the User-Agent header and read by the build (pyproject.toml)."""
+
+__version__ = "0.1.0"