tutorflow-content 0.1.0__py3-none-any.whl

tutorflow_content/__init__.py

@@ -0,0 +1,42 @@
+"""Python client for the TutorFlow Content API.
+
+Generated routes and models live in `tutorflow_content.generated`
+(openapi-python-client); this package adds the client factory, retries,
+pagination, run polling, typed errors and webhook verification.
+"""
+
+from .client import DEFAULT_BASE_URL, create_client, is_test_key, new_idempotency_key
+from .errors import ContentApiError, ContentPreconditionFailedError, error_from_response, unwrap
+from .pagination import paginate
+from .retry import AsyncRetryTransport, RetryConfig, RetryTransport, is_safe_to_repeat
+from .runs import ContentWaitError, wait_for_build, wait_for_render, wait_for_run
+from .webhooks import (
+    DEFAULT_TOLERANCE_SECONDS,
+    SIGNATURE_HEADER,
+    WebhookVerificationError,
+    verify_webhook,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOLERANCE_SECONDS",
+    "SIGNATURE_HEADER",
+    "AsyncRetryTransport",
+    "ContentApiError",
+    "ContentPreconditionFailedError",
+    "ContentWaitError",
+    "RetryConfig",
+    "RetryTransport",
+    "WebhookVerificationError",
+    "create_client",
+    "error_from_response",
+    "is_safe_to_repeat",
+    "is_test_key",
+    "new_idempotency_key",
+    "paginate",
+    "unwrap",
+    "verify_webhook",
+    "wait_for_build",
+    "wait_for_render",
+    "wait_for_run",
+]

tutorflow_content/client.py

@@ -0,0 +1,71 @@
+"""Builds the generated AuthenticatedClient with retries and a Content API key."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Mapping
+
+import httpx
+
+from .generated import AuthenticatedClient
+from .retry import AsyncRetryTransport, RetryConfig, RetryTransport
+
+DEFAULT_BASE_URL = "https://api.tutorflow.io"
+KEY_PREFIX = "tf_content_"
+TEST_KEY_PREFIX = "tf_content_test_"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+def is_test_key(api_key: str) -> bool:
+    """Whether a key is a sandbox (test mode) key."""
+    return api_key.startswith(TEST_KEY_PREFIX)
+
+
+def new_idempotency_key() -> str:
+    """A fresh key for the `idempotency_key=` argument of a POST. Keep it to retry the same call later."""
+    return str(uuid.uuid4())
+
+
+def create_client(
+    api_key: str,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    retry: RetryConfig | None = RetryConfig(),
+    transport: httpx.BaseTransport | None = None,
+    async_transport: httpx.AsyncBaseTransport | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    headers: Mapping[str, str] | None = None,
+) -> AuthenticatedClient:
+    """A client for every generated call (`tutorflow_content.generated.api...`).
+
+    The key is sent as a bearer token. Rate-limited requests, and failed
+    requests that are safe to repeat, are retried (see retry.py); pass
+    `retry=None` to send every request once. `transport` and `async_transport`
+    replace the network, e.g. with httpx.MockTransport in tests.
+    """
+    key = api_key.strip()
+    if not key.startswith(KEY_PREFIX):
+        raise ValueError("api_key must be a Content API key that starts with tf_content_")
+
+    root = base_url.rstrip("/")
+    all_headers = {**(headers or {}), "Authorization": f"Bearer {key}"}
+    sync_transport = transport or httpx.HTTPTransport()
+    async_base = async_transport or httpx.AsyncHTTPTransport()
+    client = AuthenticatedClient(base_url=root, token=key, headers=dict(all_headers))
+    client.set_httpx_client(
+        httpx.Client(
+            base_url=root,
+            headers=all_headers,
+            timeout=timeout,
+            transport=RetryTransport(sync_transport, retry) if retry else sync_transport,
+        )
+    )
+    client.set_async_httpx_client(
+        httpx.AsyncClient(
+            base_url=root,
+            headers=all_headers,
+            timeout=timeout,
+            transport=AsyncRetryTransport(async_base, retry) if retry else async_base,
+        )
+    )
+    return client

tutorflow_content/errors.py

@@ -0,0 +1,87 @@
+"""Typed errors built from the Content API error envelope."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Protocol
+
+PRECONDITION_FAILED = 412
+UNKNOWN_ERROR_CODE = "content_http_error"
+
+
+class _ResponseLike(Protocol):
+    """httpx.Response and the generated client's Response both fit."""
+
+    status_code: int
+    content: bytes
+    headers: Mapping[str, str]
+
+
+def parse_retry_after(value: str | None, now: datetime | None = None) -> float | None:
+    """Seconds from a Retry-After header, which may be seconds or an HTTP date."""
+    if value is None or value.strip() == "":
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    current = now or datetime.now(timezone.utc)
+    return max(0.0, (when - current).total_seconds())
+
+
+def _envelope(content: bytes) -> dict[str, Any]:
+    try:
+        body = json.loads(content or b"null")
+    except ValueError:
+        return {}
+    error = body.get("error") if isinstance(body, dict) else None
+    return error if isinstance(error, dict) else {}
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    """Headers are case-insensitive; the generated Response keeps a plain mapping."""
+    lowered = name.lower()
+    return next((value for key, value in headers.items() if key.lower() == lowered), None)
+
+
+class ContentApiError(Exception):
+    """A Content API answer outside 2xx, with every field of the error envelope."""
+
+    def __init__(self, status: int, error: Mapping[str, Any], headers: Mapping[str, str] | None = None) -> None:
+        headers = headers or {}
+        super().__init__(error.get("message") or f"The Content API answered HTTP {status}")
+        self.code: str = error.get("code") or UNKNOWN_ERROR_CODE
+        self.status: int = int(error.get("status") or status)
+        self.request_id: str | None = error.get("requestId") or _header(headers, "Request-Id")
+        retry_after = error.get("retryAfterSeconds")
+        self.retry_after_seconds: float | None = (
+            float(retry_after) if retry_after is not None else parse_retry_after(_header(headers, "Retry-After"))
+        )
+        self.current_etag: str | None = error.get("currentETag")
+        self.details: list[dict[str, Any]] = list(error.get("details") or [])
+        self.body: dict[str, Any] = dict(error)
+
+
+class ContentPreconditionFailedError(ContentApiError):
+    """A 412: the resource changed since the ETag sent in If-Match; see current_etag."""
+
+
+def error_from_response(response: _ResponseLike) -> ContentApiError:
+    """The exception for a non-2xx response."""
+    status = int(response.status_code)
+    error_class = ContentPreconditionFailedError if status == PRECONDITION_FAILED else ContentApiError
+    return error_class(status, _envelope(response.content), response.headers)
+
+
+def unwrap(response: Any) -> Any:
+    """The parsed body of a `*_detailed` call, or a raised ContentApiError."""
+    if not 200 <= int(response.status_code) < 300:
+        raise error_from_response(response)
+    return response.parsed

tutorflow_content/generated/__init__.py

@@ -0,0 +1,8 @@
+
+""" A client library for accessing TutorFlow Content API """
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

tutorflow_content/generated/api/__init__.py

@@ -0,0 +1 @@
+""" Contains methods for accessing the API """

tutorflow_content/generated/api/content_api_keys/__init__.py

@@ -0,0 +1 @@
+""" Contains endpoint functions for accessing the API """

tutorflow_content/generated/api/content_api_keys/content_integration_api_key_controller_create_api_key.py

@@ -0,0 +1,243 @@
+from http import HTTPStatus
+from typing import Any, cast
+from urllib.parse import quote
+
+import httpx
+
+from ...client import AuthenticatedClient, Client
+from ...types import Response, UNSET
+from ... import errors
+
+from ...models.content_api_error import ContentApiError
+from ...models.content_api_key_created_res_dto import ContentApiKeyCreatedResDto
+from ...models.create_content_api_key_req_dto import CreateContentApiKeyReqDto
+from typing import cast
+from uuid import UUID
+
+
+
+def _get_kwargs(
+    organization_id: UUID,
+    *,
+    body: CreateContentApiKeyReqDto,
+
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+
+    
+
+    
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/v1/content/organizations/{organization_id}/api-keys".format(organization_id=quote(str(organization_id), safe=""),),
+    }
+
+    _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+
+def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> ContentApiError | ContentApiKeyCreatedResDto | None:
+    if response.status_code == 201:
+        response_201 = ContentApiKeyCreatedResDto.from_dict(response.json())
+
+
+
+        return response_201
+
+    if response.status_code == 400:
+        response_400 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_404
+
+    if response.status_code == 422:
+        response_422 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_422
+
+    if response.status_code == 500:
+        response_500 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_500
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Response[ContentApiError | ContentApiKeyCreatedResDto]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    organization_id: UUID,
+    *,
+    client: AuthenticatedClient,
+    body: CreateContentApiKeyReqDto,
+
+) -> Response[ContentApiError | ContentApiKeyCreatedResDto]:
+    """ Create a Content Integration API key
+
+     Signed-in TutorFlow session of an organization admin; not callable with a `tf_content_` key.
+
+    Args:
+        organization_id (UUID):
+        body (CreateContentApiKeyReqDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ContentApiError | ContentApiKeyCreatedResDto]
+     """
+
+
+    kwargs = _get_kwargs(
+        organization_id=organization_id,
+body=body,
+
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+def sync(
+    organization_id: UUID,
+    *,
+    client: AuthenticatedClient,
+    body: CreateContentApiKeyReqDto,
+
+) -> ContentApiError | ContentApiKeyCreatedResDto | None:
+    """ Create a Content Integration API key
+
+     Signed-in TutorFlow session of an organization admin; not callable with a `tf_content_` key.
+
+    Args:
+        organization_id (UUID):
+        body (CreateContentApiKeyReqDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ContentApiError | ContentApiKeyCreatedResDto
+     """
+
+
+    return sync_detailed(
+        organization_id=organization_id,
+client=client,
+body=body,
+
+    ).parsed
+
+async def asyncio_detailed(
+    organization_id: UUID,
+    *,
+    client: AuthenticatedClient,
+    body: CreateContentApiKeyReqDto,
+
+) -> Response[ContentApiError | ContentApiKeyCreatedResDto]:
+    """ Create a Content Integration API key
+
+     Signed-in TutorFlow session of an organization admin; not callable with a `tf_content_` key.
+
+    Args:
+        organization_id (UUID):
+        body (CreateContentApiKeyReqDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ContentApiError | ContentApiKeyCreatedResDto]
+     """
+
+
+    kwargs = _get_kwargs(
+        organization_id=organization_id,
+body=body,
+
+    )
+
+    response = await client.get_async_httpx_client().request(
+        **kwargs
+    )
+
+    return _build_response(client=client, response=response)
+
+async def asyncio(
+    organization_id: UUID,
+    *,
+    client: AuthenticatedClient,
+    body: CreateContentApiKeyReqDto,
+
+) -> ContentApiError | ContentApiKeyCreatedResDto | None:
+    """ Create a Content Integration API key
+
+     Signed-in TutorFlow session of an organization admin; not callable with a `tf_content_` key.
+
+    Args:
+        organization_id (UUID):
+        body (CreateContentApiKeyReqDto):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ContentApiError | ContentApiKeyCreatedResDto
+     """
+
+
+    return (await asyncio_detailed(
+        organization_id=organization_id,
+client=client,
+body=body,
+
+    )).parsed

tutorflow_content/generated/api/content_api_keys/content_integration_api_key_controller_delete_api_key.py

@@ -0,0 +1,251 @@
+from http import HTTPStatus
+from typing import Any, cast
+from urllib.parse import quote
+
+import httpx
+
+from ...client import AuthenticatedClient, Client
+from ...types import Response, UNSET
+from ... import errors
+
+from ...models.content_api_error import ContentApiError
+from ...models.content_integration_api_key_controller_delete_api_key_response_200 import ContentIntegrationApiKeyControllerDeleteApiKeyResponse200
+from typing import cast
+from uuid import UUID
+
+
+
+def _get_kwargs(
+    organization_id: UUID,
+    key_id: UUID,
+
+) -> dict[str, Any]:
+    
+
+    
+
+    
+
+    _kwargs: dict[str, Any] = {
+        "method": "delete",
+        "url": "/v1/content/organizations/{organization_id}/api-keys/{key_id}".format(organization_id=quote(str(organization_id), safe=""),key_id=quote(str(key_id), safe=""),),
+    }
+
+
+    return _kwargs
+
+
+
+def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200 | None:
+    if response.status_code == 200:
+        response_200 = ContentIntegrationApiKeyControllerDeleteApiKeyResponse200.from_dict(response.json())
+
+
+
+        return response_200
+
+    if response.status_code == 400:
+        response_400 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_404
+
+    if response.status_code == 409:
+        response_409 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_409
+
+    if response.status_code == 422:
+        response_422 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_422
+
+    if response.status_code == 500:
+        response_500 = ContentApiError.from_dict(response.json())
+
+
+
+        return response_500
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Response[ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    organization_id: UUID,
+    key_id: UUID,
+    *,
+    client: AuthenticatedClient,
+
+) -> Response[ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200]:
+    """ Delete a revoked or expired Content Integration API key
+
+     Removes a key that no longer works from the key list. A key that still works answers `409`
+    `content_api_key_active`: revoke it first. Signed-in TutorFlow session of an organization admin; not
+    callable with a `tf_content_` key.
+
+    Args:
+        organization_id (UUID):
+        key_id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200]
+     """
+
+
+    kwargs = _get_kwargs(
+        organization_id=organization_id,
+key_id=key_id,
+
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+def sync(
+    organization_id: UUID,
+    key_id: UUID,
+    *,
+    client: AuthenticatedClient,
+
+) -> ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200 | None:
+    """ Delete a revoked or expired Content Integration API key
+
+     Removes a key that no longer works from the key list. A key that still works answers `409`
+    `content_api_key_active`: revoke it first. Signed-in TutorFlow session of an organization admin; not
+    callable with a `tf_content_` key.
+
+    Args:
+        organization_id (UUID):
+        key_id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200
+     """
+
+
+    return sync_detailed(
+        organization_id=organization_id,
+key_id=key_id,
+client=client,
+
+    ).parsed
+
+async def asyncio_detailed(
+    organization_id: UUID,
+    key_id: UUID,
+    *,
+    client: AuthenticatedClient,
+
+) -> Response[ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200]:
+    """ Delete a revoked or expired Content Integration API key
+
+     Removes a key that no longer works from the key list. A key that still works answers `409`
+    `content_api_key_active`: revoke it first. Signed-in TutorFlow session of an organization admin; not
+    callable with a `tf_content_` key.
+
+    Args:
+        organization_id (UUID):
+        key_id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200]
+     """
+
+
+    kwargs = _get_kwargs(
+        organization_id=organization_id,
+key_id=key_id,
+
+    )
+
+    response = await client.get_async_httpx_client().request(
+        **kwargs
+    )
+
+    return _build_response(client=client, response=response)
+
+async def asyncio(
+    organization_id: UUID,
+    key_id: UUID,
+    *,
+    client: AuthenticatedClient,
+
+) -> ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200 | None:
+    """ Delete a revoked or expired Content Integration API key
+
+     Removes a key that no longer works from the key list. A key that still works answers `409`
+    `content_api_key_active`: revoke it first. Signed-in TutorFlow session of an organization admin; not
+    callable with a `tf_content_` key.
+
+    Args:
+        organization_id (UUID):
+        key_id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ContentApiError | ContentIntegrationApiKeyControllerDeleteApiKeyResponse200
+     """
+
+
+    return (await asyncio_detailed(
+        organization_id=organization_id,
+key_id=key_id,
+client=client,
+
+    )).parsed