ovok-sdk 0.1.0.dev13__tar.gz → 0.1.0.dev19__tar.gz

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ovok-sdk
-Version: 0.1.0.dev13
+Version: 0.1.0.dev19
 Summary: Python SDK for integrating Ovok Core healthcare services.
 Author: Actimi
 Author-email: Actimi <info@actimi.com>
@@ -255,15 +255,20 @@ the same details in the body.
 
 ## Documentation
 
-See the [Python SDK documentation](https://docs.ovok.com/python-sdk) for setup and
-client reference.
+See the [Python SDK documentation](https://docs.ovok.com/python-sdk) for guides and the
+[API reference](https://docs.ovok.com/python-sdk/reference/index.html), generated from the docstrings.
 
 ## Development
 
 ```bash
 uv run python -m unittest discover -s tests
+uv run ruff check
+uv run --group docs mkdocs build
 ```
 
+`ruff check` fails on a missing or malformed docstring. `mkdocs build` writes the API reference
+to `site/`; see [AGENTS.md](AGENTS.md) for the docs rule.
+
 Tests never reach a server: `tests/fake_transport.py` queues replies, and `tests/route_harness.py` turns a
 namespace call into a line such as `"GET v1/me/consent/legal"` (`request_line`) or its JSON body
 (`request_body`).

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/README.md

@@ -242,15 +242,20 @@ the same details in the body.
 
 ## Documentation
 
-See the [Python SDK documentation](https://docs.ovok.com/python-sdk) for setup and
-client reference.
+See the [Python SDK documentation](https://docs.ovok.com/python-sdk) for guides and the
+[API reference](https://docs.ovok.com/python-sdk/reference/index.html), generated from the docstrings.
 
 ## Development
 
 ```bash
 uv run python -m unittest discover -s tests
+uv run ruff check
+uv run --group docs mkdocs build
 ```
 
+`ruff check` fails on a missing or malformed docstring. `mkdocs build` writes the API reference
+to `site/`; see [AGENTS.md](AGENTS.md) for the docs rule.
+
 Tests never reach a server: `tests/fake_transport.py` queues replies, and `tests/route_harness.py` turns a
 namespace call into a line such as `"GET v1/me/consent/legal"` (`request_line`) or its JSON body
 (`request_body`).

ovok_sdk-0.1.0.dev19/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "ovok-sdk"
+version = "0.1.0.dev19"
+description = "Python SDK for integrating Ovok Core healthcare services."
+readme = "README.md"
+license = "AGPL-3.0-only"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+
+[[project.authors]]
+name = "Actimi"
+email = "info@actimi.com"
+
+[project.urls]
+Repository = "https://github.com/Actimi/ovok-python-sdk"
+Documentation = "https://docs.ovok.com/python-sdk"
+
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["ruff>=0.17.3,<0.18"]
+docs = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.6,<10",
+    "mkdocstrings[python]>=1",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "ANN",
+    "D",
+]
+ignore = [
+    "ANN401",
+    "D107",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/**" = [
+    "ANN",
+    "D",
+]
+"tests/**" = [
+    "ANN",
+    "D",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ovok-sdk"
-version = "0.1.0.dev13"
+version = "0.1.0.dev19"
 description = "Python SDK for integrating Ovok Core healthcare services."
 readme = "README.md"
 authors = [
@@ -18,3 +18,28 @@ Documentation = "https://docs.ovok.com/python-sdk"
 [build-system]
 requires = ["uv_build>=0.11.25,<0.12.0"]
 build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["ruff>=0.17.3,<0.18"]
+docs = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.6,<10",
+    "mkdocstrings[python]>=1",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["ANN", "D"]
+ignore = ["ANN401", "D107"]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/**" = ["ANN", "D"]
+"tests/**" = ["ANN", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/__init__.py

@@ -1,3 +1,5 @@
+"""Python SDK for Ovok Core: FHIR R4 and platform APIs through one tenant-scoped client."""
+
 from ovok_sdk.auth.session import OvokReference, Session
 from ovok_sdk.config import UnauthenticatedReason
 from ovok_sdk.errors import (

ovok_sdk-0.1.0.dev19/src/ovok_sdk/auth/__init__.py

@@ -0,0 +1 @@
+"""Sessions, tokens and the credentials that sign requests."""

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/auth/access_token.py

@@ -1,3 +1,5 @@
+"""OAuth access tokens and their expiry."""
+
 from __future__ import annotations
 
 from dataclasses import dataclass, field
@@ -8,11 +10,19 @@ REFRESH_MARGIN_MS = 60_000
 
 
 def expires_at_for(expires_in_seconds: float, now_ms: int) -> int:
+    """Return the epoch-millisecond expiry of a token that lives `expires_in_seconds` from `now_ms`."""
     return now_ms + round(expires_in_seconds * MS_PER_SECOND)
 
 
 @dataclass(frozen=True)
 class AccessToken:
+    """A bearer token and when it expires.
+
+    Attributes:
+        value: The token; never shown in `repr`.
+        expires_at_ms: Expiry in epoch milliseconds.
+    """
+
     value: str = field(repr=False)
     expires_at_ms: int
 

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/auth/client_credentials.py

@@ -1,3 +1,5 @@
+"""Machine-client authentication with the OAuth client-credentials grant."""
+
 from __future__ import annotations
 
 from ovok_sdk.auth.access_token import AccessToken, expires_at_for
@@ -10,7 +12,13 @@ CLIENT_CREDENTIALS_GRANT = "client_credentials"
 
 
 class ClientCredentials:
-    """A machine client's own token, fetched from the OAuth endpoint and renewed before it expires."""
+    """A machine client's own token, fetched from the OAuth endpoint and renewed before it expires.
+
+    Args:
+        endpoint: The OAuth token endpoint.
+        client: The machine client's credentials.
+        clock: Current time in epoch milliseconds.
+    """
 
     def __init__(self, endpoint: TokenEndpoint, client: MachineClient, clock: Clock = epoch_ms) -> None:
         self._endpoint = endpoint
@@ -20,12 +28,18 @@ class ClientCredentials:
         self._flight: SingleFlight[AccessToken] = SingleFlight()
 
     def access_token(self) -> str:
+        """Return a fresh access token, requesting a new one when the current one is stale."""
         token = self._token
         if token is None or token.is_stale_at(self._clock()):
             token = self._flight.run(self._request_token)
         return token.value
 
     def refresh(self) -> bool:
+        """Request a new token.
+
+        Returns:
+            Always True; a failed request raises instead.
+        """
         self._flight.run(self._request_token)
         return True
 

ovok_sdk-0.1.0.dev19/src/ovok_sdk/auth/credentials.py

@@ -0,0 +1,28 @@
+"""The interface that supplies bearer tokens to requests."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class Credentials(Protocol):
+    """Supplies the bearer token for each request and renews it on demand."""
+
+    def access_token(self) -> str | None:
+        """Return the current access token, or None when there is none."""
+        ...
+
+    def refresh(self) -> bool:
+        """Renew the token; return whether a new one is available."""
+        ...
+
+
+class _NoCredentials:
+    def access_token(self) -> None:
+        return None
+
+    def refresh(self) -> bool:
+        return False
+
+
+NO_CREDENTIALS: Credentials = _NoCredentials()

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/auth/pkce.py

@@ -1,3 +1,5 @@
+"""PKCE (RFC 7636) verifier and challenge generation."""
+
 from __future__ import annotations
 
 import base64
@@ -14,15 +16,24 @@ BASE64_PADDING = "="
 
 @dataclass(frozen=True)
 class PkcePair:
+    """A PKCE code verifier and its S256 challenge.
+
+    Attributes:
+        code_verifier: Random secret; never shown in `repr`.
+        code_challenge: Base64url SHA-256 of the verifier, without padding.
+    """
+
     code_verifier: str = field(repr=False)
     code_challenge: str
 
 
 def generate_pkce_pair() -> PkcePair:
+    """Return a new random verifier of 128 unreserved characters and its challenge."""
     verifier = "".join(secrets.choice(UNRESERVED_CHARACTERS) for _ in range(VERIFIER_LENGTH))
     return PkcePair(verifier, code_challenge_for(verifier))
 
 
 def code_challenge_for(verifier: str) -> str:
+    """Return the S256 code challenge for `verifier`."""
     digest = hashlib.sha256(verifier.encode(ASCII)).digest()
     return base64.urlsafe_b64encode(digest).decode(ASCII).rstrip(BASE64_PADDING)

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/auth/session.py

@@ -1,3 +1,5 @@
+"""The signed-in user's session and its JSON conversions."""
+
 from __future__ import annotations
 
 from collections.abc import Mapping
@@ -10,12 +12,29 @@ from ovok_sdk.auth.token_endpoint import TokenResponse
 
 @dataclass(frozen=True)
 class OvokReference:
+    """A FHIR reference to a resource.
+
+    Attributes:
+        reference: Relative reference, such as `Patient/123`.
+        display: Human-readable label, when the API sends one.
+    """
+
     reference: str
     display: str | None = None
 
 
 @dataclass(frozen=True)
 class Session:
+    """The signed-in user's tokens, project and profile.
+
+    Attributes:
+        access_token: Bearer token; never shown in `repr`.
+        refresh_token: Token that renews the session, if any; never shown in `repr`.
+        expires_at_ms: Access-token expiry in epoch milliseconds.
+        project: The project the user signed in to.
+        profile: The user's profile resource, such as a Patient or Practitioner.
+    """
+
     access_token: str = field(repr=False)
     refresh_token: str | None = field(repr=False)
     expires_at_ms: int
@@ -23,11 +42,20 @@ class Session:
     profile: OvokReference
 
     def is_stale_at(self, now_ms: int) -> bool:
+        """Whether the access token is within a minute of expiring at `now_ms`."""
         return AccessToken(self.access_token, self.expires_at_ms).is_stale_at(now_ms)
 
 
 def session_from_login(tokens: Mapping[str, Any], now_ms: int) -> Session:
-    """`tokens` is the camelCase body every Ovok sign-in route answers with."""
+    """Build a session from a sign-in response.
+
+    Args:
+        tokens: The camelCase body every Ovok sign-in route answers with.
+        now_ms: Current time in epoch milliseconds.
+
+    Returns:
+        The new session.
+    """
     return Session(
         access_token=tokens["accessToken"],
         refresh_token=tokens.get("refreshToken"),
@@ -38,6 +66,7 @@ def session_from_login(tokens: Mapping[str, Any], now_ms: int) -> Session:
 
 
 def session_after_refresh(session: Session, response: TokenResponse, now_ms: int) -> Session:
+    """Return `session` with the tokens from a refresh, keeping the old refresh token if none came back."""
     return replace(
         session,
         access_token=response.access_token,
@@ -47,8 +76,10 @@ def session_after_refresh(session: Session, response: TokenResponse, now_ms: int
 
 
 def reference_from_json(value: Mapping[str, Any]) -> OvokReference:
+    """Read a reference from its FHIR JSON shape."""
     return OvokReference(value["reference"], value.get("display"))
 
 
 def reference_to_json(reference: OvokReference) -> dict[str, Any]:
+    """Write a reference in its FHIR JSON shape."""
     return {"reference": reference.reference, "display": reference.display}

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/auth/session_store.py

@@ -1,3 +1,5 @@
+"""Persistence of the user session in `OvokStorage`."""
+
 from __future__ import annotations
 
 import json
@@ -11,7 +13,12 @@ SESSION_KEY = "ovok:{tenant_code}:session"
 
 
 class SessionStore:
-    """Keeps the session as JSON in the TypeScript SDK's shape, so stores are interchangeable."""
+    """Keeps the session as JSON in the TypeScript SDK's shape, so stores are interchangeable.
+
+    Args:
+        storage: Where the session is kept.
+        key: Storage key of the session.
+    """
 
     def __init__(self, storage: OvokStorage, key: str) -> None:
         self._storage = storage
@@ -23,13 +30,16 @@ class SessionStore:
         return cls(storage, SESSION_KEY.format(tenant_code=tenant_code))
 
     def load(self) -> Session | None:
+        """Return the stored session, or None when none is stored or it is unreadable."""
         raw = self._storage.get_item(self._key)
         return None if raw is None else _session_from_json(raw)
 
     def save(self, session: Session) -> None:
+        """Store `session`, replacing any earlier one."""
         self._storage.set_item(self._key, _session_to_json(session))
 
     def clear(self) -> None:
+        """Delete the stored session."""
         self._storage.remove_item(self._key)
 
 

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/auth/single_flight.py

@@ -1,3 +1,5 @@
+"""Deduplication of concurrent calls, such as token refreshes."""
+
 from __future__ import annotations
 
 import threading
@@ -19,6 +21,14 @@ class SingleFlight(Generic[T]):
         self._latest: Settled[T] = _nothing_ran
 
     def run(self, call: Callable[[], T]) -> T:
+        """Run `call`, or wait for the run in progress and share its outcome.
+
+        Returns:
+            The call's result.
+
+        Raises:
+            Exception: Whatever the shared call raised.
+        """
         calls_seen = self._finished_calls
         with self._lock:
             if self._finished_calls == calls_seen:

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/auth/token_endpoint.py

@@ -1,3 +1,5 @@
+"""The OAuth token endpoint."""
+
 from __future__ import annotations
 
 from collections.abc import Mapping
@@ -15,22 +17,46 @@ FORM_HEADERS = {"Content-Type": "application/x-www-form-urlencoded", "Accept": "
 
 @dataclass(frozen=True)
 class TokenResponse:
+    """A successful token endpoint response.
+
+    Attributes:
+        access_token: The new bearer token; never shown in `repr`.
+        expires_in: Lifetime of the access token in seconds.
+        refresh_token: A new refresh token, when the endpoint issues one.
+    """
+
     access_token: str = field(repr=False)
     expires_in: float
     refresh_token: str | None = field(default=None, repr=False)
 
     @classmethod
     def from_json(cls, body: Mapping[str, Any]) -> TokenResponse:
+        """Read the snake_case OAuth response body."""
         return cls(body["access_token"], body["expires_in"], body.get("refresh_token"))
 
 
 class TokenEndpoint:
-    """Ovok's OAuth token endpoint: one plain form POST, without retries or credentials."""
+    """Ovok's OAuth token endpoint: one plain form POST, without retries or credentials.
+
+    Args:
+        settings: The client's settings.
+    """
 
     def __init__(self, settings: OvokSettings) -> None:
         self._settings = settings
 
     def request(self, form: Mapping[str, str]) -> TokenResponse:
+        """Post `form` to the token endpoint.
+
+        Args:
+            form: OAuth form fields, such as `grant_type`.
+
+        Returns:
+            The issued tokens.
+
+        Raises:
+            OvokError: The endpoint answered with an error.
+        """
         response = self._settings.transport(
             OvokRequest(
                 method="POST",

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/auth/user_session.py

@@ -1,3 +1,5 @@
+"""The signed-in user's session and its token refresh."""
+
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping
@@ -16,7 +18,14 @@ REJECTED_REFRESH_STATUSES = frozenset({400, 401, 403})
 
 
 class UserSession:
-    """The signed-in user's tokens, kept in storage and refreshed a minute before they expire."""
+    """The signed-in user's tokens, kept in storage and refreshed a minute before they expire.
+
+    Args:
+        store: Where the session is kept.
+        endpoint: The OAuth token endpoint used to refresh.
+        settings: The client's settings.
+        clock: Current time in epoch milliseconds.
+    """
 
     def __init__(
         self,
@@ -33,28 +42,51 @@ class UserSession:
         self._listeners: list[Callable[[], None]] = []
 
     def current(self) -> Session | None:
+        """Return the stored session, or None when no one is signed in."""
         return self._store.load()
 
     def begin(self, tokens: Mapping[str, Any]) -> Session:
+        """Start a session from a sign-in response and notify listeners.
+
+        Args:
+            tokens: The camelCase body of an Ovok sign-in route.
+
+        Returns:
+            The new session.
+        """
         session = session_from_login(tokens, self._clock())
         self._store.save(session)
         self._notify_change()
         return session
 
     def end(self) -> None:
+        """Delete the session and notify listeners."""
         self._store.clear()
         self._notify_change()
 
     def on_change(self, listener: Callable[[], None]) -> None:
+        """Call `listener` whenever the session starts, refreshes or ends."""
         self._listeners.append(listener)
 
     def access_token(self) -> str | None:
+        """Return the access token, refreshing it first when it is stale; None when signed out."""
         if self._needs_refresh(self.current()):
             self.refresh()
         session = self.current()
         return None if session is None else session.access_token
 
     def refresh(self) -> bool:
+        """Exchange the refresh token for new tokens.
+
+        A refused refresh signs the user out and calls `on_unauthenticated`.
+
+        Returns:
+            True when the session was refreshed; False when there is nothing to refresh
+            or the refresh was refused.
+
+        Raises:
+            OvokError: The refresh failed for another reason, such as an outage.
+        """
         return self._flight.run(self._exchange_refresh_token)
 
     def _needs_refresh(self, session: Session | None) -> bool:

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/clock.py

@@ -1,3 +1,5 @@
+"""Wall-clock time in epoch milliseconds."""
+
 import time
 from collections.abc import Callable
 
@@ -8,4 +10,5 @@ Clock = Callable[[], int]
 
 
 def epoch_ms() -> int:
+    """Return the current time in milliseconds since the Unix epoch."""
     return time.time_ns() // NS_PER_MS

{ovok_sdk-0.1.0.dev13 → ovok_sdk-0.1.0.dev19}/src/ovok_sdk/config.py

@@ -1,3 +1,5 @@
+"""Client options, checked once when the client is constructed."""
+
 from __future__ import annotations
 
 import re
@@ -19,12 +21,26 @@ REFRESH_REJECTED = "refresh-rejected"
 
 @dataclass(frozen=True)
 class MachineClient:
+    """A machine client's OAuth credentials.
+
+    Attributes:
+        client_id: The client's ID.
+        client_secret: The client's secret; never shown in `repr`.
+    """
+
     client_id: str
     client_secret: str = field(repr=False)
 
 
 @dataclass(frozen=True)
 class UnauthenticatedReason:
+    """Why the user was signed out; passed to the `on_unauthenticated` callback.
+
+    Attributes:
+        status: HTTP status of the refused token refresh.
+        type: Kind of sign-out; always `"refresh-rejected"` today.
+    """
+
     status: int
     type: str = REFRESH_REJECTED
 
@@ -34,6 +50,21 @@ OnUnauthenticated = Callable[[UnauthenticatedReason], None]
 
 @dataclass(frozen=True)
 class OvokSettings:
+    """The client's checked options; see `Ovok` for what each one means.
+
+    Attributes:
+        base_url: API base URL, ending in `/`.
+        tenant_code: Tenant every request is scoped to.
+        fhir_path: Path of the FHIR API under `base_url`, without slashes at either end.
+        storage: Where the session is kept.
+        transport: Sends the HTTP requests.
+        timeout: Request timeout in seconds.
+        max_network_retries: Retries for safe requests that fail on the network.
+        client_id: App client ID, if one was given.
+        machine_client: Machine credentials, when a client secret was given.
+        on_unauthenticated: Called when the user is signed out.
+    """
+
     base_url: str
     tenant_code: str
     fhir_path: str
@@ -59,7 +90,16 @@ def read_settings(
     max_network_retries: int = DEFAULT_MAX_NETWORK_RETRIES,
     on_unauthenticated: OnUnauthenticated | None = None,
 ) -> OvokSettings:
-    """Checks every option up front, so a bad one fails at construction, not on the first request."""
+    """Checks every option up front, so a bad one fails at construction, not on the first request.
+
+    Takes the same arguments as `Ovok`.
+
+    Returns:
+        The checked settings, with defaults filled in.
+
+    Raises:
+        OvokConfigError: An option is missing or invalid.
+    """
     return OvokSettings(
         base_url=_read_base_url(base_url),
         tenant_code=_require_text(tenant_code, "tenant_code"),