docket-client 0.3.2__py3-none-any.whl

docket/models/update_template_request.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeVar, BinaryIO, TextIO, TYPE_CHECKING, Generator
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..types import UNSET, Unset
+
+from ..types import UNSET, Unset
+from typing import cast
+
+if TYPE_CHECKING:
+    from ..models.acquisition_variable import AcquisitionVariable
+    from ..models.person_assignment import PersonAssignment
+    from ..models.settings_selector import SettingsSelector
+
+
+T = TypeVar("T", bound="UpdateTemplateRequest")
+
+
+@_attrs_define
+class UpdateTemplateRequest:
+    """Change a template. Every field except `expected_version` is optional: an
+    omitted field is left unchanged. For the scalar defaults (`subject_id`,
+    `instrument_id`, `project_id`, `operator_instructions`,
+    `duration_minutes`, `local_start_time`) an explicit `null` clears the
+    default. `name`, `people`, `type_refs` and `variables` cannot be
+    null; send an empty list to clear a list. Lists replace the whole list when present.
+
+        Attributes:
+            expected_version (int): The `version` the client last read. A stale value is rejected with 409
+                `version_conflict`.
+            name (str | Unset): New name; unique among non-archived templates.
+            subject_id (None | str | Unset): New default subject; `null` clears it.
+            instrument_id (None | str | Unset): New default instrument; `null` clears it.
+            project_id (None | str | Unset): New default project; `null` clears it.
+            operator_instructions (None | str | Unset): New default operator text; `null` clears it.
+            people (list[PersonAssignment] | Unset): Replaces the default people.
+            type_refs (list[SettingsSelector] | Unset): Replaces the default type refs.
+            variables (list[AcquisitionVariable] | Unset): Replaces the default variables.
+            duration_minutes (int | None | Unset): New default duration in minutes; `null` clears it.
+            local_start_time (None | str | Unset):
+    """
+
+    expected_version: int
+    name: str | Unset = UNSET
+    subject_id: None | str | Unset = UNSET
+    instrument_id: None | str | Unset = UNSET
+    project_id: None | str | Unset = UNSET
+    operator_instructions: None | str | Unset = UNSET
+    people: list[PersonAssignment] | Unset = UNSET
+    type_refs: list[SettingsSelector] | Unset = UNSET
+    variables: list[AcquisitionVariable] | Unset = UNSET
+    duration_minutes: int | None | Unset = UNSET
+    local_start_time: None | str | Unset = UNSET
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        from ..models.acquisition_variable import AcquisitionVariable
+        from ..models.person_assignment import PersonAssignment
+        from ..models.settings_selector import SettingsSelector
+
+        expected_version = self.expected_version
+
+        name = self.name
+
+        subject_id: None | str | Unset
+        if isinstance(self.subject_id, Unset):
+            subject_id = UNSET
+        else:
+            subject_id = self.subject_id
+
+        instrument_id: None | str | Unset
+        if isinstance(self.instrument_id, Unset):
+            instrument_id = UNSET
+        else:
+            instrument_id = self.instrument_id
+
+        project_id: None | str | Unset
+        if isinstance(self.project_id, Unset):
+            project_id = UNSET
+        else:
+            project_id = self.project_id
+
+        operator_instructions: None | str | Unset
+        if isinstance(self.operator_instructions, Unset):
+            operator_instructions = UNSET
+        else:
+            operator_instructions = self.operator_instructions
+
+        people: list[dict[str, Any]] | Unset = UNSET
+        if not isinstance(self.people, Unset):
+            people = []
+            for people_item_data in self.people:
+                people_item = people_item_data.to_dict()
+                people.append(people_item)
+
+        type_refs: list[dict[str, Any]] | Unset = UNSET
+        if not isinstance(self.type_refs, Unset):
+            type_refs = []
+            for type_refs_item_data in self.type_refs:
+                type_refs_item = type_refs_item_data.to_dict()
+                type_refs.append(type_refs_item)
+
+        variables: list[dict[str, Any]] | Unset = UNSET
+        if not isinstance(self.variables, Unset):
+            variables = []
+            for variables_item_data in self.variables:
+                variables_item = variables_item_data.to_dict()
+                variables.append(variables_item)
+
+        duration_minutes: int | None | Unset
+        if isinstance(self.duration_minutes, Unset):
+            duration_minutes = UNSET
+        else:
+            duration_minutes = self.duration_minutes
+
+        local_start_time: None | str | Unset
+        if isinstance(self.local_start_time, Unset):
+            local_start_time = UNSET
+        else:
+            local_start_time = self.local_start_time
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "expected_version": expected_version,
+            }
+        )
+        if name is not UNSET:
+            field_dict["name"] = name
+        if subject_id is not UNSET:
+            field_dict["subject_id"] = subject_id
+        if instrument_id is not UNSET:
+            field_dict["instrument_id"] = instrument_id
+        if project_id is not UNSET:
+            field_dict["project_id"] = project_id
+        if operator_instructions is not UNSET:
+            field_dict["operator_instructions"] = operator_instructions
+        if people is not UNSET:
+            field_dict["people"] = people
+        if type_refs is not UNSET:
+            field_dict["type_refs"] = type_refs
+        if variables is not UNSET:
+            field_dict["variables"] = variables
+        if duration_minutes is not UNSET:
+            field_dict["duration_minutes"] = duration_minutes
+        if local_start_time is not UNSET:
+            field_dict["local_start_time"] = local_start_time
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        from ..models.acquisition_variable import AcquisitionVariable
+        from ..models.person_assignment import PersonAssignment
+        from ..models.settings_selector import SettingsSelector
+
+        d = dict(src_dict)
+        expected_version = d.pop("expected_version")
+
+        name = d.pop("name", UNSET)
+
+        def _parse_subject_id(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        subject_id = _parse_subject_id(d.pop("subject_id", UNSET))
+
+        def _parse_instrument_id(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        instrument_id = _parse_instrument_id(d.pop("instrument_id", UNSET))
+
+        def _parse_project_id(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        project_id = _parse_project_id(d.pop("project_id", UNSET))
+
+        def _parse_operator_instructions(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        operator_instructions = _parse_operator_instructions(d.pop("operator_instructions", UNSET))
+
+        _people = d.pop("people", UNSET)
+        people: list[PersonAssignment] | Unset = UNSET
+        if _people is not UNSET:
+            people = []
+            for people_item_data in _people:
+                people_item = PersonAssignment.from_dict(people_item_data)
+
+                people.append(people_item)
+
+        _type_refs = d.pop("type_refs", UNSET)
+        type_refs: list[SettingsSelector] | Unset = UNSET
+        if _type_refs is not UNSET:
+            type_refs = []
+            for type_refs_item_data in _type_refs:
+                type_refs_item = SettingsSelector.from_dict(type_refs_item_data)
+
+                type_refs.append(type_refs_item)
+
+        _variables = d.pop("variables", UNSET)
+        variables: list[AcquisitionVariable] | Unset = UNSET
+        if _variables is not UNSET:
+            variables = []
+            for variables_item_data in _variables:
+                variables_item = AcquisitionVariable.from_dict(variables_item_data)
+
+                variables.append(variables_item)
+
+        def _parse_duration_minutes(data: object) -> int | None | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(int | None | Unset, data)
+
+        duration_minutes = _parse_duration_minutes(d.pop("duration_minutes", UNSET))
+
+        def _parse_local_start_time(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        local_start_time = _parse_local_start_time(d.pop("local_start_time", UNSET))
+
+        update_template_request = cls(
+            expected_version=expected_version,
+            name=name,
+            subject_id=subject_id,
+            instrument_id=instrument_id,
+            project_id=project_id,
+            operator_instructions=operator_instructions,
+            people=people,
+            type_refs=type_refs,
+            variables=variables,
+            duration_minutes=duration_minutes,
+            local_start_time=local_start_time,
+        )
+
+        update_template_request.additional_properties = d
+        return update_template_request
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

docket/models/weekday.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class Weekday(str, Enum):
+    FRIDAY = "friday"
+    MONDAY = "monday"
+    SATURDAY = "saturday"
+    SUNDAY = "sunday"
+    THURSDAY = "thursday"
+    TUESDAY = "tuesday"
+    WEDNESDAY = "wednesday"
+
+    def __str__(self) -> str:
+        return str(self.value)

docket/types.py

@@ -0,0 +1,54 @@
+"""Contains some shared types for properties"""
+
+from collections.abc import Mapping, MutableMapping
+from http import HTTPStatus
+from typing import BinaryIO, Generic, TypeVar, Literal, IO
+
+from attrs import define
+
+
+class Unset:
+    def __bool__(self) -> Literal[False]:
+        return False
+
+
+UNSET: Unset = Unset()
+
+# The types that `httpx.Client(files=)` can accept, copied from that library.
+FileContent = IO[bytes] | bytes | str
+FileTypes = (
+    # (filename, file (or bytes), content_type)
+    tuple[str | None, FileContent, str | None]
+    # (filename, file (or bytes), content_type, headers)
+    | tuple[str | None, FileContent, str | None, Mapping[str, str]]
+)
+RequestFiles = list[tuple[str, FileTypes]]
+
+
+@define
+class File:
+    """Contains information for file uploads"""
+
+    payload: BinaryIO
+    file_name: str | None = None
+    mime_type: str | None = None
+
+    def to_tuple(self) -> FileTypes:
+        """Return a tuple representation that httpx will accept for multipart/form-data"""
+        return self.file_name, self.payload, self.mime_type
+
+
+T = TypeVar("T")
+
+
+@define
+class Response(Generic[T]):
+    """A response from an endpoint"""
+
+    status_code: HTTPStatus
+    content: bytes
+    headers: MutableMapping[str, str]
+    parsed: T | None
+
+
+__all__ = ["UNSET", "File", "FileTypes", "RequestFiles", "Response", "Unset"]

docket_auth/__init__.py

@@ -0,0 +1,239 @@
+"""Bearer-token providers for the docket client.
+
+Hand-written; ``client/docket/`` is generated and never edited. A *token
+provider* is any zero-argument callable returning a current access token.
+[`authenticated_client`][docket_auth.authenticated_client] asks it before every request, so tokens refresh
+without rebuilding the client.
+
+Two providers use ``msal`` (install ``docket-client[auth]``):
+
+* [`ClientCredentialsTokenProvider`][docket_auth.ClientCredentialsTokenProvider] - rigs, clabe and services: a
+  confidential client signing in as itself (Entra app role ``Docket.Machine``).
+* [`DeviceCodeTokenProvider`][docket_auth.DeviceCodeTokenProvider] - people: device-code sign-in in a terminal,
+  with a token cache so the code is needed once.
+
+Reads need no token; only mutations do. Run tokens (``/runs/{token}``) identify
+a run and grant no authority.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Callable, Generator
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from docket import AuthenticatedClient
+
+__all__ = [
+    "ClientCredentialsTokenProvider",
+    "api_token_provider",
+    "DeviceCodeTokenProvider",
+    "TokenProvider",
+    "authenticated_client",
+    "static_provider",
+]
+
+TokenProvider = Callable[[], str]
+"""Returns a valid access token; called before each request."""
+
+
+class AuthenticationError(RuntimeError):
+    """Raised when a token cannot be acquired."""
+
+
+def _authority(tenant_id: str | None, authority: str | None) -> tuple[str, bool]:
+    """Returns (authority URL, is_generic_oidc). Entra by tenant id, or any OIDC authority."""
+    if authority:
+        return authority.rstrip("/"), True
+    if not tenant_id:
+        raise ValueError("Pass tenant_id (Microsoft Entra) or authority (another OIDC provider).")
+    return f"https://login.microsoftonline.com/{tenant_id}", False
+
+
+def _msal_kwargs(tenant_id: str | None, authority: str | None) -> dict[str, Any]:
+    url, generic = _authority(tenant_id, authority)
+    return {"oidc_authority": url} if generic else {"authority": url}
+
+
+def _result_token(result: dict[str, Any] | None) -> str:
+    result = result or {}
+    token = result.get("access_token")
+    if not token:
+        # error / error_description never contain the secret or a token.
+        raise AuthenticationError(
+            f"Could not get a token: {result.get('error')}: {result.get('error_description')}"
+        )
+    return str(token)
+
+
+class ClientCredentialsTokenProvider:
+    """Signs in as an application (OAuth2 client credentials) with ``msal``.
+
+    Args:
+        client_id: The application (client) id of the rig's app registration.
+        client_secret: Its client secret. Keep it out of source control.
+        scope: What to request, normally ``"<API client id or app id URI>/.default"``.
+        tenant_id: The Entra tenant id. Omit when ``authority`` is given.
+        authority: Another OIDC authority (the dev mock server), e.g. ``http://localhost:8003/docket``.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        scope: str,
+        *,
+        tenant_id: str | None = None,
+        authority: str | None = None,
+    ) -> None:
+        import msal
+
+        self._scopes = [scope]
+        self._app = msal.ConfidentialClientApplication(
+            client_id,
+            client_credential=client_secret,
+            **_msal_kwargs(tenant_id, authority),
+        )
+
+    def __call__(self) -> str:
+        # msal serves the cached token until shortly before it expires.
+        return _result_token(self._app.acquire_token_for_client(scopes=self._scopes))
+
+
+class DeviceCodeTokenProvider:
+    """Signs a person in with the device-code flow (``msal`` public client).
+
+    The first call prints a URL and a code to open in any browser; after that
+    the cached token and its refresh token are used. Pass ``cache_path`` to keep
+    the cache between runs (it holds refresh tokens: protect the file).
+
+    Args:
+        client_id: The SPA / public-client application id registered for this API.
+        scope: Normally ``"<API client id or app id URI>/access_as_user"``.
+        tenant_id: The Entra tenant id. Omit when ``authority`` is given.
+        authority: Another OIDC authority (the dev mock server).
+        cache_path: File to persist the token cache in. Omit for in-memory.
+        prompt: Called with the sign-in instructions; defaults to printing them.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        scope: str,
+        *,
+        tenant_id: str | None = None,
+        authority: str | None = None,
+        cache_path: str | Path | None = None,
+        prompt: Callable[[str], None] | None = None,
+    ) -> None:
+        import msal
+
+        self._scopes = [scope]
+        self._prompt = prompt or (lambda message: print(message, file=sys.stderr))
+        self._cache_path = Path(cache_path).expanduser() if cache_path else None
+        self._cache = msal.SerializableTokenCache()
+        if self._cache_path and self._cache_path.exists():
+            self._cache.deserialize(self._cache_path.read_text(encoding="utf-8"))
+        self._app = msal.PublicClientApplication(
+            client_id, token_cache=self._cache, **_msal_kwargs(tenant_id, authority)
+        )
+
+    def __call__(self) -> str:
+        for account in self._app.get_accounts():
+            result = self._app.acquire_token_silent(self._scopes, account=account)
+            if result and result.get("access_token"):
+                self._save()
+                return str(result["access_token"])
+
+        flow = self._app.initiate_device_flow(scopes=self._scopes)
+        if "user_code" not in flow:
+            raise AuthenticationError(
+                f"Could not start device sign-in: {flow.get('error_description')}"
+            )
+        self._prompt(str(flow["message"]))
+        token = _result_token(self._app.acquire_token_by_device_flow(flow))
+        self._save()
+        return token
+
+    def silent_token(self) -> str | None:
+        """A cached token if one can be had without any interaction, else None (never signs in)."""
+        for account in self._app.get_accounts():
+            result = self._app.acquire_token_silent(self._scopes, account=account)
+            if result and result.get("access_token"):
+                self._save()
+                return str(result["access_token"])
+        return None
+
+    def _save(self) -> None:
+        if self._cache_path and self._cache.has_state_changed:
+            # It holds refresh tokens: created owner-only (the mode is ignored on Windows,
+            # where the user profile's ACLs apply).
+            self._cache_path.parent.mkdir(parents=True, exist_ok=True)
+            descriptor = os.open(self._cache_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            with os.fdopen(descriptor, "w", encoding="utf-8") as cache_file:
+                cache_file.write(self._cache.serialize())
+            if os.name == "posix":
+                self._cache_path.chmod(0o600)
+
+
+class _ProviderAuth(httpx.Auth):
+    """Sets ``Authorization: Bearer <token>`` from the provider on every request."""
+
+    def __init__(self, provider: TokenProvider) -> None:
+        self._provider = provider
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self._provider()}"
+        yield request
+
+
+def authenticated_client(
+    base_url: str,
+    token_provider: TokenProvider,
+    *,
+    verify_ssl: bool | str = True,
+    **kwargs: Any,
+) -> AuthenticatedClient:
+    """An [`docket.AuthenticatedClient`][docket.client.AuthenticatedClient] that gets its token from ``token_provider``.
+
+    Extra keyword arguments (``timeout``, ``headers``, ...) go to the client.
+    The provider is called for every request, so rotation and refresh need no
+    special handling.
+    """
+    httpx_args = dict(kwargs.pop("httpx_args", {}))
+    httpx_args["auth"] = _ProviderAuth(token_provider)
+    return AuthenticatedClient(
+        base_url=base_url,
+        token="provider",  # placeholder; replaced per request by _ProviderAuth
+        verify_ssl=verify_ssl,
+        httpx_args=httpx_args,
+        **kwargs,
+    )
+
+
+def api_token_provider(variable: str = "DOCKET_API_TOKEN") -> TokenProvider:
+    """A provider for a Docket-issued API token (``dkt_...``) read from the environment.
+
+    No Entra registration is involved: an admin issues the token in Docket's Access page and
+    it is set as ``DOCKET_API_TOKEN`` on the rig or script host. The variable is read on every
+    request, so a rotated token is picked up without a restart. The token is never printed.
+    """
+
+    def provider() -> str:
+        token = os.environ.get(variable, "").strip()
+        if not token:
+            raise AuthenticationError(
+                f"Set {variable} to a Docket API token (issued by a Docket admin)."
+            )
+        return token
+
+    return provider
+
+
+def static_provider(token: str) -> TokenProvider:
+    """A provider that always returns ``token`` (tests, or a token you obtained elsewhere)."""
+    return lambda: token