nohead 0.1.0__py3-none-any.whl

nohead/__init__.py

@@ -0,0 +1,77 @@
+"""The official Python SDK for the Nohead API.
+
+from nohead import Nohead
+
+nohead = Nohead()  # NOHEAD_API_KEY
+for post in nohead.records.list("posts", filter={"status": "published"}):
+    print(post.data["title"])
+"""
+
+from . import models, params, types, webhooks
+from ._async._nohead import AsyncNohead
+from ._base import DEFAULT_BASE_URL, NoheadWarning
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    InternalServerError,
+    InvalidRequestError,
+    NoheadError,
+    NotFoundError,
+    PlanLimitExceededError,
+    PreconditionFailedError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UploadError,
+    ValidationError,
+    WebhookVerificationError,
+)
+from ._pagination import AsyncPage, AsyncPaginator, Page
+from ._sync._nohead import Nohead
+from ._uploads import Uploadable
+from ._version import __version__
+from .models import Asset, Collection, Field, Record, Schema, Webhook
+from .webhooks import WebhookEvent
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "Asset",
+    "AsyncNohead",
+    "AsyncPage",
+    "AsyncPaginator",
+    "AuthenticationError",
+    "AuthorizationError",
+    "Collection",
+    "ConflictError",
+    "Field",
+    "InternalServerError",
+    "InvalidRequestError",
+    "Nohead",
+    "NoheadError",
+    "NoheadWarning",
+    "NotFoundError",
+    "Page",
+    "PlanLimitExceededError",
+    "PreconditionFailedError",
+    "RateLimitError",
+    "Record",
+    "Schema",
+    "ServiceUnavailableError",
+    "UploadError",
+    "Uploadable",
+    "ValidationError",
+    "Webhook",
+    "WebhookEvent",
+    "WebhookVerificationError",
+    "__version__",
+    "models",
+    "params",
+    "types",
+    "webhooks",
+]

nohead/_async/_client.py

@@ -0,0 +1,184 @@
+# pyright: reportPrivateUsage=false
+"""The HTTP core of the async client: requests, retries, errors and pages.
+
+src/nohead/_sync is generated from this package by scripts/unasync.py: edit
+the async code and run `uv run python scripts/unasync.py`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import Any, TypeVar
+
+import httpx
+
+from .. import _base
+from .._errors import APIConnectionError, APITimeoutError, NoheadError, api_error
+from .._generated.operations import OPERATIONS
+from .._pagination import AsyncPage, AsyncPaginator, start_async_pages
+from .._uploads import UploadSource, aiter_file
+from ..models import ListMeta, Principal
+from ..types import IfMatch
+
+T = TypeVar("T")
+M = TypeVar("M")
+
+
+class AsyncAPIClient:
+    def __init__(self, settings: _base.Settings, http: httpx.AsyncClient | None) -> None:
+        self.settings = settings
+        self.http = http or httpx.AsyncClient()
+        self.owns_http = http is None
+        self._project_id = settings.project_id
+
+    def copy(self, settings: _base.Settings) -> AsyncAPIClient:
+        """The same connection pool and project, other settings."""
+        client = AsyncAPIClient(settings, self.http)
+        client.owns_http = False
+        client._project_id = settings.project_id or self._project_id
+        return client
+
+    async def close(self) -> None:
+        if self.owns_http:
+            await self.http.aclose()
+
+    async def project_id(self) -> str:
+        """The API key's project, from `GET /v1/me` the first time."""
+        if self._project_id is None:
+            me = await self.request("me_get", cast=Principal)
+            if me.api_key is None:
+                raise NoheadError("The credentials are not a project API key")
+            self._project_id = me.api_key.project_id
+        return self._project_id
+
+    async def request(
+        self,
+        operation: str,
+        *,
+        cast: type[T] | Any,
+        path: Mapping[str, str | int] | None = None,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        idempotency_key: str | None = None,
+        change_note: str | None = None,
+        if_match: IfMatch | None = None,
+    ) -> T:
+        data = await self.send(
+            operation,
+            path=path,
+            query=query,
+            body=body,
+            idempotency_key=idempotency_key,
+            change_note=change_note,
+            if_match=if_match,
+        )
+        return _base.validate(cast, data)
+
+    def paginate(
+        self,
+        operation: str,
+        *,
+        item: type[T],
+        meta: type[M] = ListMeta,
+        path: Mapping[str, str | int] | None = None,
+        query: Mapping[str, Any] | None = None,
+    ) -> AsyncPaginator[T, Any]:
+        """A list operation as pages of `item`."""
+        params = dict(query or {})
+
+        async def fetch(cursor: str | None) -> AsyncPage[T, Any]:
+            data = await self.send(operation, path=path, query={**params, "cursor": cursor})
+            items: list[T] = [_base.validate(item, raw) for raw in data["data"]]
+            return AsyncPage(items, _base.validate(meta, data["meta"]), fetch)
+
+        return start_async_pages(fetch, params.pop("cursor", None))
+
+    async def send(
+        self,
+        operation: str,
+        *,
+        path: Mapping[str, str | int] | None = None,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        idempotency_key: str | None = None,
+        change_note: str | None = None,
+        if_match: IfMatch | None = None,
+    ) -> Any:
+        """Sends one operation, retrying as the README describes; returns the JSON."""
+        method, template = OPERATIONS[operation]
+        values = dict(path or {})
+        if "{project_id}" in template and "project_id" not in values:
+            values["project_id"] = await self.project_id()
+        settings = self.settings
+        url = _base.url(settings, template, values)
+        headers = _base.headers(
+            settings,
+            method,
+            has_body=body is not None,
+            idempotency_key=idempotency_key,
+            change_note=change_note,
+            if_match=if_match,
+        )
+        content = None if body is None else _base.encode(body)
+        params = _base.query(query)
+
+        attempt = 0
+        while True:
+            try:
+                response = await self.http.request(
+                    method,
+                    url,
+                    params=params,
+                    headers=headers,
+                    content=content,
+                    timeout=settings.timeout,
+                )
+            except httpx.TransportError as error:
+                failure = _connection_error(error, settings.timeout, url)
+                if attempt >= settings.max_retries:
+                    raise failure from error
+                await asyncio.sleep(_base.backoff(attempt))
+                attempt += 1
+                continue
+
+            _base.warn(settings, operation, response)
+            if response.is_success:
+                return _base.parse(response)
+            error = api_error(response.status_code, _base.parse(response), response.headers)
+            delay = _base.retry_delay(error, attempt, settings.max_retries)
+            if delay is None:
+                raise error
+            await asyncio.sleep(delay)
+            attempt += 1
+
+    async def put_upload(
+        self, url: str, method: str, headers: Mapping[str, str], source: UploadSource
+    ) -> httpx.Response:
+        """Sends a file to a presigned storage URL (no API credentials)."""
+        settings = self.settings
+        retries = settings.max_retries if source.replayable else 0
+        attempt = 0
+        while True:
+            try:
+                response = await self.http.request(
+                    method,
+                    url,
+                    headers={**headers, "Content-Length": str(source.byte_size)},
+                    content=aiter_file(source),
+                    timeout=settings.timeout,
+                )
+                if response.status_code not in _base.RETRYABLE_STATUSES or attempt >= retries:
+                    return response
+            except httpx.TransportError as error:
+                if attempt >= retries:
+                    raise _connection_error(error, settings.timeout, url) from error
+            await asyncio.sleep(_base.backoff(attempt))
+            attempt += 1
+
+
+def _connection_error(error: httpx.TransportError, timeout: float, url: str) -> NoheadError:
+    host = httpx.URL(url).host
+    if isinstance(error, httpx.TimeoutException):
+        return APITimeoutError(f"The request to {host} timed out after {timeout} s")
+    return APIConnectionError(f"Could not reach {host}: {error}")

nohead/_async/_nohead.py

@@ -0,0 +1,147 @@
+# pyright: reportPrivateUsage=false
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from types import TracebackType
+from typing import Literal, Self
+
+import httpx
+
+from .. import _base
+from .._pagination import AsyncPaginator
+from ..models import Record, SearchResultsMeta
+from ._client import AsyncAPIClient
+from .resources.assets import AsyncAssets
+from .resources.other import AsyncAuditEvents, AsyncFeatureFlags, AsyncHealth, AsyncMe
+from .resources.records import AsyncRecords
+from .resources.schema import AsyncCollections, AsyncFields, AsyncMigrations
+from .resources.webhooks import AsyncWebhooks
+
+
+class AsyncNohead:
+    """An async client for the Nohead API, authenticated with a project API key.
+
+    async with AsyncNohead() as nohead:  # NOHEAD_API_KEY
+        async for post in nohead.records.list("posts"):
+            print(post.data["title"])
+    """
+
+    records: AsyncRecords
+    collections: AsyncCollections
+    fields: AsyncFields
+    migrations: AsyncMigrations
+    assets: AsyncAssets
+    webhooks: AsyncWebhooks
+    audit_events: AsyncAuditEvents
+    feature_flags: AsyncFeatureFlags
+    me: AsyncMe
+    health: AsyncHealth
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        project_id: str | None = None,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        headers: Mapping[str, str] | None = None,
+        warnings: bool = True,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """
+        Args:
+            api_key: A project API key (`sk_live_...`). Defaults to NOHEAD_API_KEY.
+            base_url: Defaults to NOHEAD_API_URL, else https://api.nohead.io.
+            project_id: The key's project. Looked up once with GET /v1/me when omitted.
+            max_retries: Retries of failed requests (see the README, "Retries").
+            timeout: Seconds per attempt.
+            headers: Headers added to every request.
+            warnings: Warn about deprecated operations and plan usage (once each).
+            http_client: An httpx client to send requests with (proxies, transports).
+        """
+        settings = _base.settings(
+            api_key=api_key,
+            base_url=base_url,
+            project_id=project_id,
+            max_retries=max_retries,
+            timeout=timeout,
+            headers=headers,
+            warnings=warnings,
+        )
+        self._setup(AsyncAPIClient(settings, http_client))
+
+    def _setup(self, client: AsyncAPIClient) -> None:
+        self._client = client
+        self.records = AsyncRecords(client)
+        self.collections = AsyncCollections(client)
+        self.fields = AsyncFields(client)
+        self.migrations = AsyncMigrations(client)
+        self.assets = AsyncAssets(client)
+        self.webhooks = AsyncWebhooks(client)
+        self.audit_events = AsyncAuditEvents(client)
+        self.feature_flags = AsyncFeatureFlags(client)
+        self.me = AsyncMe(client)
+        self.health = AsyncHealth(client)
+
+    def with_options(
+        self,
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Self:
+        """A client with other settings that shares this one's connections:
+        `nohead.with_options(timeout=5).records.get(id)`."""
+        current = self._client.settings
+        settings = _base.Settings(
+            api_key=current.api_key,
+            base_url=current.base_url,
+            project_id=current.project_id,
+            max_retries=current.max_retries if max_retries is None else max_retries,
+            timeout=current.timeout if timeout is None else timeout,
+            headers={**current.headers, **(headers or {})},
+            warnings=current.warnings,
+        )
+        copy = object.__new__(type(self))
+        copy._setup(self._client.copy(settings))
+        return copy
+
+    def search(
+        self,
+        query: str,
+        *,
+        collections: Sequence[str] | None = None,
+        status: Literal["draft", "published"] | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> AsyncPaginator[Record, SearchResultsMeta]:
+        """Full-text search across the key's project (or some of its collections),
+        most relevant first, through the first 1,000 hits."""
+        return self._client.paginate(
+            "projects_search",
+            item=Record,
+            meta=SearchResultsMeta,
+            query={
+                "q": query,
+                "collections": collections,
+                "filter": {"status": status},
+                "limit": limit,
+                "cursor": cursor,
+            },
+        )
+
+    async def close(self) -> None:
+        """Closes the connections (unless an `http_client` was passed in)."""
+        await self._client.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()

nohead/_async/resources/_resource.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from .._client import AsyncAPIClient
+
+
+class AsyncResource:
+    def __init__(self, client: AsyncAPIClient) -> None:
+        self._client = client

nohead/_async/resources/assets.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from typing_extensions import Unpack
+
+from ..._errors import UploadError
+from ..._pagination import AsyncPaginator
+from ..._uploads import Uploadable, open_upload
+from ...models import Asset, AssetUpload, DownloadUrl, ImageUrl
+from ...params import AssetUploadCreate
+from ._resource import AsyncResource
+
+
+class AsyncAssets(AsyncResource):
+    """Files of the key's project. `asset` is an asset ID (`ast_...`)."""
+
+    async def upload(
+        self,
+        file: Uploadable,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        byte_size: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> Asset:
+        """Uploads a file and returns the `ready` asset: creates the upload, sends the
+        bytes straight to storage, then completes it (which checks the file).
+
+        `file` is bytes, a path, or a file opened in binary mode. Raises UploadError if
+        storage refuses the bytes, and ValidationError if the file fails the checks.
+        """
+        source = open_upload(file, filename, content_type, byte_size)
+        try:
+            created = await self.create_upload(
+                filename=source.filename,
+                content_type=source.content_type,
+                byte_size=source.byte_size,
+                idempotency_key=idempotency_key,
+            )
+            response = await self._client.put_upload(
+                created.upload.url, created.upload.method, created.upload.headers, source
+            )
+        finally:
+            source.close()
+        if not response.is_success:
+            raise UploadError(
+                f"Storage refused the upload of {source.filename} ({response.status_code})",
+                response.status_code,
+            )
+        return await self.complete(created.asset.id)
+
+    async def create_upload(
+        self, *, idempotency_key: str | None = None, **params: Unpack[AssetUploadCreate]
+    ) -> AssetUpload:
+        """The first step of an upload: a `pending` asset and a presigned URL to PUT the
+        bytes to (for example from a browser). Then `complete` it."""
+        return await self._client.request(
+            "assets_upload", cast=AssetUpload, body=params, idempotency_key=idempotency_key
+        )
+
+    async def complete(self, asset: str, *, idempotency_key: str | None = None) -> Asset:
+        """Checks an uploaded file and marks the asset `ready`."""
+        return await self._client.request(
+            "assets_complete",
+            cast=Asset,
+            path={"asset_id": asset},
+            idempotency_key=idempotency_key,
+        )
+
+    def list(
+        self, *, deleted: bool | None = None, limit: int | None = None, cursor: str | None = None
+    ) -> AsyncPaginator[Asset]:
+        return self._client.paginate(
+            "assets_list",
+            item=Asset,
+            query={"deleted": deleted, "limit": limit, "cursor": cursor},
+        )
+
+    async def get(self, asset: str) -> Asset:
+        return await self._client.request("assets_get", cast=Asset, path={"asset_id": asset})
+
+    async def delete(self, asset: str, *, idempotency_key: str | None = None) -> Asset:
+        """Soft-deletes the asset; the file is purged after 30 days."""
+        return await self._client.request(
+            "assets_delete",
+            cast=Asset,
+            path={"asset_id": asset},
+            idempotency_key=idempotency_key,
+        )
+
+    async def restore(self, asset: str, *, idempotency_key: str | None = None) -> Asset:
+        return await self._client.request(
+            "assets_restore",
+            cast=Asset,
+            path={"asset_id": asset},
+            idempotency_key=idempotency_key,
+        )
+
+    async def image_url(
+        self,
+        asset: str,
+        *,
+        width: int | None = None,
+        height: int | None = None,
+        fit: Literal["contain", "cover", "fill"] | None = None,
+        format: Literal["original", "webp", "avif", "jpeg", "png"] | None = None,
+        quality: int | None = None,
+    ) -> ImageUrl:
+        """A signed, cacheable URL of an image rendition (`url`)."""
+        return await self._client.request(
+            "assets_image_url",
+            cast=ImageUrl,
+            path={"asset_id": asset},
+            query={
+                "width": width,
+                "height": height,
+                "fit": fit,
+                "format": format,
+                "quality": quality,
+            },
+        )
+
+    async def download_url(self, asset: str) -> DownloadUrl:
+        """A 15-minute link to download the original file (`url`)."""
+        return await self._client.request(
+            "assets_download_url", cast=DownloadUrl, path={"asset_id": asset}
+        )

nohead/_async/resources/other.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from ..._pagination import AsyncPaginator
+from ...models import AuditEvent, Principal
+from ...models import FeatureFlags as FeatureFlagValues
+from ...models import Health as HealthStatus
+from ...types import RecordFilter
+from ._resource import AsyncResource
+
+
+class AsyncAuditEvents(AsyncResource):
+    """The project's activity log, newest first. Needs the `audit:read` scope."""
+
+    def list(
+        self,
+        *,
+        filter: RecordFilter | None = None,
+        sort: Literal["id", "-id"] | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> AsyncPaginator[AuditEvent]:
+        """`filter` takes `action` (exact, or a `record.*` prefix), `resource_type`,
+        `resource_id`, `actor_type`, `actor_id`, `since` and `until`."""
+        return self._client.paginate(
+            "audit_events_list_for_project",
+            item=AuditEvent,
+            query={"filter": filter, "sort": sort, "limit": limit, "cursor": cursor},
+        )
+
+
+class AsyncFeatureFlags(AsyncResource):
+    async def list(self) -> FeatureFlagValues:
+        """Flags evaluated for the key's project."""
+        return await self._client.request("feature_flags_list", cast=FeatureFlagValues)
+
+
+class AsyncMe(AsyncResource):
+    async def get(self) -> Principal:
+        """The API key: its project, scopes, `published_only` and expiry."""
+        return await self._client.request("me_get", cast=Principal)
+
+
+class AsyncHealth(AsyncResource):
+    async def check(self) -> HealthStatus:
+        return await self._client.request("health_check", cast=HealthStatus)