Add Pydantic argument validation to cloud API functions (Issue #6)

Add @validate_call with Annotated types to all ndi.cloud.api.* functions,
matching MATLAB arguments blocks: non-empty string IDs, pagination bounds,
mustBeMember scope enum, and mustBeFile path checks. 47 functions covered
across datasets, documents, files, compute, and users modules.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: audristroyer

pyproject.toml

@@ -40,6 +40,7 @@ dependencies = [
     "networkx>=2.6",
     "jsonschema>=4.0.0",
     "requests>=2.28.0",
+    "pydantic>=2.0",
 ]
 
 [project.optional-dependencies]

src/ndi/cloud/api/_validators.py

@@ -0,0 +1,53 @@
+"""Pydantic argument validators matching MATLAB arguments blocks.
+
+Provides reusable ``Annotated`` types for cloud API functions.  Each type
+maps to a specific MATLAB argument constraint:
+
+    CloudId     -> (1,1) string   (non-empty resource identifier)
+    NonEmptyStr -> (1,1) string   (non-empty general string)
+    PageNumber  -> (1,1) double   (integer >= 1)
+    PageSize    -> (1,1) double   (integer >= 1)
+    Scope       -> {mustBeMember} (Literal enum)
+    FilePath    -> {mustBeFile}   (file must exist on disk)
+
+Usage::
+
+    from pydantic import validate_call
+    from ._validators import CloudId, PageNumber, VALIDATE_CONFIG
+
+    @_auto_client
+    @validate_call(config=VALIDATE_CONFIG)
+    def get_dataset(dataset_id: CloudId, *, client: CloudClient | None = None):
+        ...
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import AfterValidator, ConfigDict, Field
+
+# -- (1,1) string: non-empty scalar string -----------------------------------
+CloudId = Annotated[str, Field(min_length=1)]
+NonEmptyStr = Annotated[str, Field(min_length=1)]
+
+# -- (1,1) double: pagination integers ---------------------------------------
+PageNumber = Annotated[int, Field(ge=1)]
+PageSize = Annotated[int, Field(ge=1)]
+
+# -- {mustBeMember(scope, ["public", "private", "all"])} ---------------------
+Scope = Literal["public", "private", "all"]
+
+
+# -- {mustBeFile}: file must exist on disk ------------------------------------
+def _check_file_exists(v: str) -> str:
+    if not Path(v).is_file():
+        raise ValueError(f"File not found: {v}")
+    return v
+
+
+FilePath = Annotated[str, AfterValidator(_check_file_exists)]
+
+# -- Shared validate_call config ---------------------------------------------
+VALIDATE_CONFIG = ConfigDict(arbitrary_types_allowed=True)

src/ndi/cloud/api/compute.py

@@ -9,20 +9,23 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import Annotated, Any
 
-from ..client import APIResponse, _auto_client
+from pydantic import SkipValidation, validate_call
 
-if TYPE_CHECKING:
-    from ..client import CloudClient
+from ..client import APIResponse, CloudClient, _auto_client
+from ._validators import VALIDATE_CONFIG, NonEmptyStr
+
+_Client = Annotated[CloudClient | None, SkipValidation()]
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def start_session(
-    pipeline_id: str,
+    pipeline_id: NonEmptyStr,
     input_params: dict[str, Any] | None = None,
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
 ) -> dict[str, Any]:
     """POST /compute/start -- Start a new compute session."""
     body: dict[str, Any] = {"pipelineId": pipeline_id}
@@ -32,17 +35,19 @@ def start_session(
 
 
 @_auto_client
-def get_session_status(session_id: str, *, client: CloudClient | None = None) -> dict[str, Any]:
+@validate_call(config=VALIDATE_CONFIG)
+def get_session_status(session_id: NonEmptyStr, *, client: _Client = None) -> dict[str, Any]:
     """GET /compute/{sessionId} -- Get session status."""
     return client.get("/compute/{sessionId}", sessionId=session_id)
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def trigger_stage(
-    session_id: str,
-    stage_id: str,
+    session_id: NonEmptyStr,
+    stage_id: NonEmptyStr,
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
 ) -> dict[str, Any]:
     """POST /compute/{sessionId}/stage/{stageId}"""
     return client.post(
@@ -53,7 +58,8 @@ def trigger_stage(
 
 
 @_auto_client
-def finalize_session(session_id: str, *, client: CloudClient | None = None) -> dict[str, Any]:
+@validate_call(config=VALIDATE_CONFIG)
+def finalize_session(session_id: NonEmptyStr, *, client: _Client = None) -> dict[str, Any]:
     """POST /compute/{sessionId}/finalize"""
     return client.post(
         "/compute/{sessionId}/finalize",
@@ -62,14 +68,15 @@ def finalize_session(session_id: str, *, client: CloudClient | None = None) -> d
 
 
 @_auto_client
-def abort_session(session_id: str, *, client: CloudClient | None = None) -> bool:
+@validate_call(config=VALIDATE_CONFIG)
+def abort_session(session_id: NonEmptyStr, *, client: _Client = None) -> bool:
     """POST /compute/{sessionId}/abort"""
     client.post("/compute/{sessionId}/abort", sessionId=session_id)
     return True
 
 
 @_auto_client
-def list_sessions(*, client: CloudClient | None = None) -> APIResponse:
+def list_sessions(*, client: _Client = None) -> APIResponse:
     """GET /compute -- List all compute sessions."""
     result = client.get("/compute")
     # Handle both APIResponse (has .data) and raw dict/list from mocks

src/ndi/cloud/api/datasets.py

@@ -11,27 +11,31 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import Annotated, Any
 
-from ..client import APIResponse, _auto_client
+from pydantic import SkipValidation, validate_call
 
-if TYPE_CHECKING:
-    from ..client import CloudClient
+from ..client import APIResponse, CloudClient, _auto_client
+from ._validators import VALIDATE_CONFIG, CloudId, NonEmptyStr, PageNumber, PageSize
+
+_Client = Annotated[CloudClient | None, SkipValidation()]
 
 
 @_auto_client
-def get_dataset(dataset_id: str, *, client: CloudClient | None = None) -> dict[str, Any]:
+@validate_call(config=VALIDATE_CONFIG)
+def get_dataset(dataset_id: CloudId, *, client: _Client = None) -> dict[str, Any]:
     """GET /datasets/{datasetId}"""
     return client.get("/datasets/{datasetId}", datasetId=dataset_id)
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def create_dataset(
-    org_id: str,
-    name: str,
+    org_id: NonEmptyStr,
+    name: NonEmptyStr,
     description: str = "",
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
     **kwargs: Any,
 ) -> dict[str, Any]:
     """POST /organizations/{organizationId}/datasets"""
@@ -47,10 +51,11 @@ def create_dataset(
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def update_dataset(
-    dataset_id: str,
+    dataset_id: CloudId,
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
     **fields: Any,
 ) -> dict[str, Any]:
     """POST /datasets/{datasetId}"""
@@ -62,11 +67,12 @@ def update_dataset(
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def delete_dataset(
-    dataset_id: str,
+    dataset_id: CloudId,
     when: str = "7d",
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
 ) -> dict[str, Any]:
     """DELETE /datasets/{datasetId}?when=...
 
@@ -86,12 +92,13 @@ def delete_dataset(
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def list_datasets(
-    org_id: str,
-    page: int = 1,
-    page_size: int = 1000,
+    org_id: NonEmptyStr,
+    page: PageNumber = 1,
+    page_size: PageSize = 1000,
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
 ) -> dict[str, Any]:
     """GET /organizations/{organizationId}/datasets?page=&pageSize="""
     return client.get(
@@ -105,7 +112,8 @@ def list_datasets(
 
 
 @_auto_client
-def list_all_datasets(org_id: str, *, client: CloudClient | None = None) -> APIResponse:
+@validate_call(config=VALIDATE_CONFIG)
+def list_all_datasets(org_id: NonEmptyStr, *, client: _Client = None) -> APIResponse:
     """Auto-paginate through all datasets for an organisation."""
     all_datasets: list[dict[str, Any]] = []
     page = 1
@@ -121,11 +129,12 @@ def list_all_datasets(org_id: str, *, client: CloudClient | None = None) -> APIR
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def get_published_datasets(
-    page: int = 1,
-    page_size: int = 1000,
+    page: PageNumber = 1,
+    page_size: PageSize = 1000,
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
 ) -> dict[str, Any]:
     """GET /datasets/published"""
     return client.get(
@@ -135,41 +144,47 @@ def get_published_datasets(
 
 
 @_auto_client
-def publish_dataset(dataset_id: str, *, client: CloudClient | None = None) -> dict[str, Any]:
+@validate_call(config=VALIDATE_CONFIG)
+def publish_dataset(dataset_id: CloudId, *, client: _Client = None) -> dict[str, Any]:
     """POST /datasets/{datasetId}/publish"""
     return client.post("/datasets/{datasetId}/publish", datasetId=dataset_id)
 
 
 @_auto_client
-def unpublish_dataset(dataset_id: str, *, client: CloudClient | None = None) -> dict[str, Any]:
+@validate_call(config=VALIDATE_CONFIG)
+def unpublish_dataset(dataset_id: CloudId, *, client: _Client = None) -> dict[str, Any]:
     """POST /datasets/{datasetId}/unpublish"""
     return client.post("/datasets/{datasetId}/unpublish", datasetId=dataset_id)
 
 
 @_auto_client
-def submit_dataset(dataset_id: str, *, client: CloudClient | None = None) -> dict[str, Any]:
+@validate_call(config=VALIDATE_CONFIG)
+def submit_dataset(dataset_id: CloudId, *, client: _Client = None) -> dict[str, Any]:
     """POST /datasets/{datasetId}/submit"""
     return client.post("/datasets/{datasetId}/submit", datasetId=dataset_id)
 
 
 @_auto_client
-def create_branch(dataset_id: str, *, client: CloudClient | None = None) -> dict[str, Any]:
+@validate_call(config=VALIDATE_CONFIG)
+def create_branch(dataset_id: CloudId, *, client: _Client = None) -> dict[str, Any]:
     """POST /datasets/{datasetId}/branch"""
     return client.post("/datasets/{datasetId}/branch", datasetId=dataset_id)
 
 
 @_auto_client
-def get_branches(dataset_id: str, *, client: CloudClient | None = None) -> list[dict[str, Any]]:
+@validate_call(config=VALIDATE_CONFIG)
+def get_branches(dataset_id: CloudId, *, client: _Client = None) -> list[dict[str, Any]]:
     """GET /datasets/{datasetId}/branches"""
     return client.get("/datasets/{datasetId}/branches", datasetId=dataset_id)
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def get_unpublished(
-    page: int = 1,
-    page_size: int = 20,
+    page: PageNumber = 1,
+    page_size: PageSize = 20,
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
 ) -> dict[str, Any]:
     """GET /datasets/unpublished
 
@@ -182,7 +197,8 @@ def get_unpublished(
 
 
 @_auto_client
-def undelete_dataset(dataset_id: str, *, client: CloudClient | None = None) -> dict[str, Any]:
+@validate_call(config=VALIDATE_CONFIG)
+def undelete_dataset(dataset_id: CloudId, *, client: _Client = None) -> dict[str, Any]:
     """POST /datasets/{datasetId}/undelete
 
     Reverse a deferred (soft) delete before the pruner runs.
@@ -193,11 +209,12 @@ def undelete_dataset(dataset_id: str, *, client: CloudClient | None = None) -> d
 
 
 @_auto_client
+@validate_call(config=VALIDATE_CONFIG)
 def list_deleted_datasets(
-    page: int = 1,
-    page_size: int = 1000,
+    page: PageNumber = 1,
+    page_size: PageSize = 1000,
     *,
-    client: CloudClient | None = None,
+    client: _Client = None,
 ) -> dict[str, Any]:
     """GET /datasets/deleted?page=&pageSize=