phenostore-sdk-python 0.1.1__py3-none-any.whl

phenostore/__init__.py

@@ -0,0 +1,26 @@
+"""Python SDK for the Phenostore FHIR data API."""
+
+from .client import AsyncClient, Client
+from .errors import (
+    AuthenticationError,
+    InvalidResponseError,
+    OperationOutcomeError,
+    is_conflict,
+    is_forbidden,
+    is_gone,
+    is_not_found,
+)
+
+__version__ = "0.1.1"  # x-release-please-version
+
+__all__ = [
+    "AsyncClient",
+    "AuthenticationError",
+    "Client",
+    "InvalidResponseError",
+    "OperationOutcomeError",
+    "is_conflict",
+    "is_forbidden",
+    "is_gone",
+    "is_not_found",
+]

phenostore/_auth.py

@@ -0,0 +1,94 @@
+"""HTTPX OAuth2 client credentials authentication for both execution modes."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import threading
+import time
+from collections.abc import AsyncGenerator, Generator, Sequence
+
+import httpx
+
+from .errors import AuthenticationError
+
+
+class ClientCredentialsAuth(httpx.Auth):
+    requires_response_body = True
+
+    def __init__(
+        self, token_url: str, client_id: str, client_secret: str, scopes: Sequence[str]
+    ) -> None:
+        self._token_url = token_url
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._scopes = tuple(scopes)
+        self._token = ""
+        self._expires_at = 0.0
+        self._sync_lock = threading.Lock()
+        self._async_lock = asyncio.Lock()
+
+    def _expired(self) -> bool:
+        return not self._token or time.monotonic() >= self._expires_at
+
+    def _token_request(self, request: httpx.Request) -> httpx.Request:
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+        }
+        if self._scopes:
+            data["scope"] = " ".join(self._scopes)
+        return httpx.Request(
+            "POST",
+            self._token_url,
+            data=data,
+            headers={"Accept": "application/json"},
+            extensions={"timeout": request.extensions.get("timeout", {})},
+        )
+
+    def _receive_token(self, response: httpx.Response) -> None:
+        if response.status_code != 200:
+            raise AuthenticationError(response)
+        try:
+            data = response.json()
+            token = data["access_token"]
+            token_type = data["token_type"]
+            lifetime = float(data["expires_in"])
+            if (
+                not isinstance(token, str)
+                or not token
+                or not token.isascii()
+                or any(char.isspace() or ord(char) < 32 or ord(char) == 127 for char in token)
+                or not isinstance(token_type, str)
+                or token_type.lower() != "bearer"
+                or not math.isfinite(lifetime)
+                or lifetime <= 0
+            ):
+                raise ValueError("invalid token")
+        except (ValueError, TypeError, KeyError, OverflowError):
+            raise AuthenticationError(response, "invalid token response") from None
+        self._token = token
+        self._expires_at = time.monotonic() + lifetime - min(10, lifetime / 10)
+
+    def sync_auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        with self._sync_lock:
+            if self._expired():
+                response = yield self._token_request(request)
+                response.read()
+                self._receive_token(response)
+            request.headers["Authorization"] = f"Bearer {self._token}"
+        yield request
+
+    async def async_auth_flow(
+        self, request: httpx.Request
+    ) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        async with self._async_lock:
+            if self._expired():
+                response = yield self._token_request(request)
+                await response.aread()
+                self._receive_token(response)
+            request.headers["Authorization"] = f"Bearer {self._token}"
+        yield request

phenostore/client.py

@@ -0,0 +1,276 @@
+"""Small convenience layer over generated request builders and HTTPX."""
+
+from __future__ import annotations
+
+import ssl
+from collections.abc import Mapping, Sequence
+from typing import Any, Self, cast
+
+import httpx
+
+from ._auth import ClientCredentialsAuth
+from .errors import OperationOutcomeError, _json_object
+from .gen.api.fhir import (
+    create_resource,
+    delete_resource,
+    process_bundle,
+    read_resource,
+    search_resources,
+    update_resource,
+)
+from .gen.client import Client as GeneratedClient
+from .gen.models import FhirResource, ResourceType
+from .gen.types import UNSET
+
+JSON = dict[str, Any]
+SearchParams = Mapping[str, str | int | Sequence[str]] | Sequence[tuple[str, str | int]]
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        base_url: str,
+        client_id: str,
+        client_secret: str,
+        tenant: str,
+        store: str,
+        *,
+        scopes: Sequence[str] = (),
+        timeout: float | httpx.Timeout = 30.0,
+        verify: bool | ssl.SSLContext = True,
+        transport: httpx.BaseTransport | httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        url = httpx.URL(base_url)
+        if (
+            url.scheme not in ("http", "https")
+            or not url.host
+            or url.query
+            or url.fragment
+            or url.userinfo
+        ):
+            raise ValueError(
+                "base_url must be an absolute HTTP(S) URL without credentials or query"
+            )
+        if not all((client_id, client_secret, tenant, store)):
+            raise ValueError("client_id, client_secret, tenant, and store must be nonempty")
+        if isinstance(scopes, str):
+            raise TypeError("scopes must be a sequence of scope strings")
+        self.tenant = tenant
+        self.store = store
+        base_url = str(url).rstrip("/")
+        auth = ClientCredentialsAuth(base_url + "/oauth/token", client_id, client_secret, scopes)
+        self.inner = GeneratedClient(
+            base_url=base_url,
+            timeout=timeout if isinstance(timeout, httpx.Timeout) else httpx.Timeout(timeout),
+            verify_ssl=verify,
+            follow_redirects=False,
+            headers={"Accept": "application/fhir+json", "User-Agent": "phenostore-sdk-python"},
+            httpx_args={"auth": auth, "transport": transport},
+            raise_on_unexpected_status=True,
+        )
+
+    def _read(self, resource_type: str, id: str) -> JSON:
+        return read_resource._get_kwargs(
+            self.tenant, self.store, cast(ResourceType, resource_type), id
+        )
+
+    def _create(
+        self, resource_type: str, body: Mapping[str, Any], if_none_exist: str | None
+    ) -> JSON:
+        return create_resource._get_kwargs(
+            self.tenant,
+            self.store,
+            cast(ResourceType, resource_type),
+            body=FhirResource.from_dict(body),
+            if_none_exist=if_none_exist if if_none_exist is not None else UNSET,
+        )
+
+    def _update(
+        self, resource_type: str, id: str, body: Mapping[str, Any], if_match: str | None
+    ) -> JSON:
+        return update_resource._get_kwargs(
+            self.tenant,
+            self.store,
+            cast(ResourceType, resource_type),
+            id,
+            body=FhirResource.from_dict(body),
+            if_match=if_match if if_match is not None else UNSET,
+        )
+
+    def _delete(self, resource_type: str, id: str) -> JSON:
+        return delete_resource._get_kwargs(
+            self.tenant, self.store, cast(ResourceType, resource_type), id
+        )
+
+    def _search(self, resource_type: str, params: SearchParams | None) -> JSON:
+        kwargs = search_resources._get_kwargs(
+            self.tenant, self.store, cast(ResourceType, resource_type)
+        )
+        # The generated signature only includes parameters explicitly named in the
+        # spec. FHIR also allows arbitrary names, modifiers, chains and repetition.
+        kwargs["params"] = params if params is not None else {}
+        return kwargs
+
+    def _bundle(self, bundle: Mapping[str, Any]) -> JSON:
+        return process_bundle._get_kwargs(
+            self.tenant, self.store, body=FhirResource.from_dict(bundle)
+        )
+
+
+class Client(_BaseClient):
+    """Synchronous Phenostore client with lazy OAuth2 authentication.
+
+    Use as a context manager or call close() to release pooled connections.
+    The transport, timeout and TLS configuration also apply to token requests.
+    Access inner to use generated API functions and typed models directly.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        client_id: str,
+        client_secret: str,
+        tenant: str,
+        store: str,
+        *,
+        scopes: Sequence[str] = (),
+        timeout: float | httpx.Timeout = 30.0,
+        verify: bool | ssl.SSLContext = True,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        super().__init__(
+            base_url,
+            client_id,
+            client_secret,
+            tenant,
+            store,
+            scopes=scopes,
+            timeout=timeout,
+            verify=verify,
+            transport=transport,
+        )
+        # Construct once before the client can be shared between threads. Token
+        # acquisition stays lazy; the generated client's lazy initializer is not
+        # synchronized and can otherwise allocate multiple connection pools.
+        self.inner.get_httpx_client()
+
+    def _request(self, kwargs: JSON) -> httpx.Response:
+        response = self.inner.get_httpx_client().request(**kwargs)
+        if not 200 <= response.status_code < 300:
+            raise OperationOutcomeError(response)
+        return response
+
+    def read_resource(self, resource_type: str, id: str) -> JSON:
+        """Read a resource, preserving every JSON field."""
+        return _json_object(self._request(self._read(resource_type, id)))
+
+    def create_resource(
+        self, resource_type: str, body: Mapping[str, Any], *, if_none_exist: str | None = None
+    ) -> JSON:
+        """Create a resource, optionally with conditional search criteria."""
+        return _json_object(self._request(self._create(resource_type, body, if_none_exist)))
+
+    def update_resource(
+        self, resource_type: str, id: str, body: Mapping[str, Any], *, if_match: str | None = None
+    ) -> JSON:
+        """Update or upsert, optionally requiring an ETag such as W/\"1\"."""
+        return _json_object(self._request(self._update(resource_type, id, body, if_match)))
+
+    def delete_resource(self, resource_type: str, id: str) -> None:
+        """Delete a resource. Deleted and missing resources may raise API errors."""
+        self._request(self._delete(resource_type, id))
+
+    def search_resources(self, resource_type: str, params: SearchParams | None = None) -> JSON:
+        """Search with arbitrary FHIR parameters; sequence values repeat a parameter."""
+        return _json_object(self._request(self._search(resource_type, params)))
+
+    def process_bundle(self, bundle: Mapping[str, Any]) -> JSON:
+        """Execute a transaction or batch bundle."""
+        return _json_object(self._request(self._bundle(bundle)))
+
+    def close(self) -> None:
+        """Close the underlying synchronous HTTP client."""
+        self.inner.get_httpx_client().close()
+
+    def __enter__(self) -> Self:
+        self.inner.get_httpx_client().__enter__()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncClient(_BaseClient):
+    """Asynchronous equivalent of Client. Use async with or await aclose()."""
+
+    def __init__(
+        self,
+        base_url: str,
+        client_id: str,
+        client_secret: str,
+        tenant: str,
+        store: str,
+        *,
+        scopes: Sequence[str] = (),
+        timeout: float | httpx.Timeout = 30.0,
+        verify: bool | ssl.SSLContext = True,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        super().__init__(
+            base_url,
+            client_id,
+            client_secret,
+            tenant,
+            store,
+            scopes=scopes,
+            timeout=timeout,
+            verify=verify,
+            transport=transport,
+        )
+
+    async def _request(self, kwargs: JSON) -> httpx.Response:
+        response = await self.inner.get_async_httpx_client().request(**kwargs)
+        if not 200 <= response.status_code < 300:
+            raise OperationOutcomeError(response)
+        return response
+
+    async def read_resource(self, resource_type: str, id: str) -> JSON:
+        """Read a resource, preserving every JSON field."""
+        return _json_object(await self._request(self._read(resource_type, id)))
+
+    async def create_resource(
+        self, resource_type: str, body: Mapping[str, Any], *, if_none_exist: str | None = None
+    ) -> JSON:
+        """Create a resource, optionally with conditional search criteria."""
+        return _json_object(await self._request(self._create(resource_type, body, if_none_exist)))
+
+    async def update_resource(
+        self, resource_type: str, id: str, body: Mapping[str, Any], *, if_match: str | None = None
+    ) -> JSON:
+        """Update or upsert, optionally requiring an ETag."""
+        return _json_object(await self._request(self._update(resource_type, id, body, if_match)))
+
+    async def delete_resource(self, resource_type: str, id: str) -> None:
+        """Delete a resource."""
+        await self._request(self._delete(resource_type, id))
+
+    async def search_resources(
+        self, resource_type: str, params: SearchParams | None = None
+    ) -> JSON:
+        """Search with arbitrary FHIR parameters, including repeated values."""
+        return _json_object(await self._request(self._search(resource_type, params)))
+
+    async def process_bundle(self, bundle: Mapping[str, Any]) -> JSON:
+        """Execute a transaction or batch bundle."""
+        return _json_object(await self._request(self._bundle(bundle)))
+
+    async def aclose(self) -> None:
+        """Close the underlying asynchronous HTTP client."""
+        await self.inner.get_async_httpx_client().aclose()
+
+    async def __aenter__(self) -> Self:
+        await self.inner.get_async_httpx_client().__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

phenostore/errors.py

@@ -0,0 +1,93 @@
+"""Errors raised by the convenience clients."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+
+class OperationOutcomeError(Exception):
+    """An API error, retaining the HTTP response and unmodified response bytes."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.response = response
+        self.status_code = response.status_code
+        self.body = response.content
+        self.outcome: dict[str, Any] | None = None
+        message = f"phenostore: HTTP {self.status_code}"
+        try:
+            parsed = response.json()
+        except (ValueError, UnicodeError):
+            parsed = None
+        if isinstance(parsed, dict):
+            self.outcome = parsed
+            issues = parsed.get("issue")
+            if isinstance(issues, list) and issues and isinstance(issues[0], dict):
+                issue = issues[0]
+                message = "[{}/{}] {}".format(
+                    issue.get("severity", ""), issue.get("code", ""), issue.get("diagnostics", "")
+                )
+        super().__init__(message)
+
+
+class AuthenticationError(Exception):
+    """Token exchange failed or returned an invalid token response."""
+
+    def __init__(self, response: httpx.Response, message: str = "token exchange failed") -> None:
+        self.response = response
+        self.status_code = response.status_code
+        self.body = response.content
+        # Avoid putting credentials or token response bodies in exception messages.
+        super().__init__(f"phenostore: {message} (HTTP {self.status_code})")
+
+
+class InvalidResponseError(ValueError):
+    """A successful API response did not contain a JSON object."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.response = response
+        super().__init__(f"phenostore: expected a JSON object (HTTP {response.status_code})")
+
+
+def _has_status(error: BaseException | None, status: int) -> bool:
+    seen: set[int] = set()
+    while error is not None and id(error) not in seen:
+        seen.add(id(error))
+        if isinstance(error, OperationOutcomeError):
+            return error.status_code == status
+        error = error.__cause__ or error.__context__
+    return False
+
+
+def is_not_found(error: BaseException | None) -> bool:
+    """Return whether an error (including chained exceptions) represents HTTP 404."""
+    return _has_status(error, 404)
+
+
+def is_gone(error: BaseException | None) -> bool:
+    """Return whether an error represents HTTP 410."""
+    return _has_status(error, 410)
+
+
+def is_conflict(error: BaseException | None) -> bool:
+    """Return whether an error represents HTTP 412 (a failed precondition)."""
+    return _has_status(error, 412)
+
+
+def is_forbidden(error: BaseException | None) -> bool:
+    """Return whether an error represents HTTP 403."""
+    return _has_status(error, 403)
+
+
+def _json_object(response: httpx.Response) -> dict[str, Any]:
+    if not 200 <= response.status_code < 300:
+        raise OperationOutcomeError(response)
+    try:
+        result = response.json()
+    except (json.JSONDecodeError, UnicodeError) as exc:
+        raise InvalidResponseError(response) from exc
+    if not isinstance(result, dict):
+        raise InvalidResponseError(response)
+    return result

phenostore/gen/__init__.py

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

phenostore/gen/api/__init__.py

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

phenostore/gen/api/bulk/__init__.py

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

phenostore/gen/api/bulk/get_bulk_status.py

@@ -0,0 +1,194 @@
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.bulk_operation_status import BulkOperationStatus
+from ...models.operation_outcome import OperationOutcome
+from ...types import Response
+
+
+def _get_kwargs(
+    tenant_id: str,
+    store_id: str,
+    op_id: str,
+) -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/v1/tenants/{tenant_id}/stores/{store_id}/$bulk/{op_id}".format(
+            tenant_id=quote(str(tenant_id), safe=""),
+            store_id=quote(str(store_id), safe=""),
+            op_id=quote(str(op_id), safe=""),
+        ),
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> BulkOperationStatus | OperationOutcome | None:
+    if response.status_code == 200:
+        response_200 = BulkOperationStatus.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 202:
+        response_202 = BulkOperationStatus.from_dict(response.json())
+
+        return response_202
+
+    if response.status_code == 404:
+        response_404 = OperationOutcome.from_dict(response.json())
+
+        return response_404
+
+    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[BulkOperationStatus | OperationOutcome]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    tenant_id: str,
+    store_id: str,
+    op_id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[BulkOperationStatus | OperationOutcome]:
+    """Get bulk operation status
+
+    Args:
+        tenant_id (str):
+        store_id (str):
+        op_id (str):
+
+    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[BulkOperationStatus | OperationOutcome]
+    """
+
+    kwargs = _get_kwargs(
+        tenant_id=tenant_id,
+        store_id=store_id,
+        op_id=op_id,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    tenant_id: str,
+    store_id: str,
+    op_id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> BulkOperationStatus | OperationOutcome | None:
+    """Get bulk operation status
+
+    Args:
+        tenant_id (str):
+        store_id (str):
+        op_id (str):
+
+    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:
+        BulkOperationStatus | OperationOutcome
+    """
+
+    return sync_detailed(
+        tenant_id=tenant_id,
+        store_id=store_id,
+        op_id=op_id,
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    tenant_id: str,
+    store_id: str,
+    op_id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[BulkOperationStatus | OperationOutcome]:
+    """Get bulk operation status
+
+    Args:
+        tenant_id (str):
+        store_id (str):
+        op_id (str):
+
+    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[BulkOperationStatus | OperationOutcome]
+    """
+
+    kwargs = _get_kwargs(
+        tenant_id=tenant_id,
+        store_id=store_id,
+        op_id=op_id,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    tenant_id: str,
+    store_id: str,
+    op_id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> BulkOperationStatus | OperationOutcome | None:
+    """Get bulk operation status
+
+    Args:
+        tenant_id (str):
+        store_id (str):
+        op_id (str):
+
+    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:
+        BulkOperationStatus | OperationOutcome
+    """
+
+    return (
+        await asyncio_detailed(
+            tenant_id=tenant_id,
+            store_id=store_id,
+            op_id=op_id,
+            client=client,
+        )
+    ).parsed