Add v2 entity_lists workspace sub-resource

Wraps the two endpoints exposed under a workspace by the v2 API:

  POST /api/workspaces/:workspace_id/entity_lists      → create
  GET  /api/workspaces/:workspace_id/entity_lists/:id  → show

No list/index endpoint exists yet on the server, so the client
deliberately ships create + get only. Reached via
client.workspaces.entity_lists.

EntityList and EntityListItem models normalise the persisted
'dataset_external_id' field back to 'dataset_id' so callers see
one name across create + show. Create accepts items either as
EntityListItem instances or as plain dicts, validates entity_type
against the server's enum (protein/peptide/gene) and the non-empty
items constraint before round-tripping.

Author: infusini

src/md_python/models/__init__.py

@@ -10,6 +10,7 @@
     NormalisationImputationDataset,
     PairwiseComparisonDataset,
 )
+from .entity_list import EntityList, EntityListItem
 from .experiment import Experiment
 from .metadata import ExperimentDesign, SampleMetadata
 from .registered_module import RegisteredModule
@@ -31,4 +32,6 @@
     "Tab",
     "TabModule",
     "RegisteredModule",
+    "EntityList",
+    "EntityListItem",
 ]

src/md_python/models/entity_list.py

@@ -0,0 +1,97 @@
+"""
+EntityList and EntityListItem models for the v2 workspaces entity_lists API.
+
+Mirror the ``ToHash::EntityList.to_hash_with_owner`` helper plus the
+appended ``items`` field set by ``present_entity_list`` in
+``app/api/api/v2/workspaces/api.rb``.
+
+An entity list groups together a fixed selection of proteins, peptides,
+or genes drawn from one or more datasets — used by visualisation modules
+that take a list-id (``proteinListId`` / ``entityListId``) instead of a
+full dataset.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from pydantic.dataclasses import dataclass as pydantic_dataclass
+
+
+def _parse_iso_datetime(value: Optional[str]) -> Optional[datetime]:
+    if value is not None and isinstance(value, str):
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    return None
+
+
+@pydantic_dataclass
+@dataclass
+class EntityListItem:
+    """A single membership row in an entity list.
+
+    ``dataset_id`` and ``group_id`` must both be set or both be null —
+    the server-side validator on ``EntityListItem`` enforces this. The
+    pair identifies a specific row in a specific dataset; ``entity_id``
+    is the human-readable identifier (e.g. protein group accession).
+    """
+
+    entity_id: str
+    group_id: Optional[int] = None
+    dataset_id: Optional[str] = None
+    id: Optional[UUID] = None
+
+    @classmethod
+    def from_json(cls, data: Dict[str, Any]) -> "EntityListItem":
+        # Server returns ``dataset_external_id`` on the persisted record
+        # but accepts ``dataset_id`` on create — normalise both back to
+        # ``dataset_id`` on the Python side so callers see one name.
+        raw_id = data.get("id")
+        return cls(
+            entity_id=str(data["entity_id"]),
+            group_id=data.get("group_id"),
+            dataset_id=data.get("dataset_id") or data.get("dataset_external_id"),
+            id=UUID(str(raw_id)) if raw_id is not None else None,
+        )
+
+    def to_create_payload(self) -> Dict[str, Any]:
+        """Render as the JSON shape the Create endpoint accepts."""
+        payload: Dict[str, Any] = {"entity_id": self.entity_id}
+        if self.group_id is not None:
+            payload["group_id"] = self.group_id
+        if self.dataset_id is not None:
+            payload["dataset_id"] = self.dataset_id
+        return payload
+
+
+@pydantic_dataclass
+@dataclass
+class EntityList:
+    """A named list of proteins / peptides / genes drawn from datasets."""
+
+    id: UUID
+    name: str
+    type: str  # 'protein' | 'peptide' | 'gene'
+    experiment_id: Optional[UUID] = None
+    items_count: int = 0
+    owner: bool = False
+    items: List[EntityListItem] = field(default_factory=list)
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+    @classmethod
+    def from_json(cls, data: Dict[str, Any]) -> "EntityList":
+        experiment_id_raw = data.get("experiment_id")
+        return cls(
+            id=UUID(str(data["id"])),
+            name=str(data["name"]),
+            type=str(data["type"]),
+            experiment_id=(
+                UUID(str(experiment_id_raw)) if experiment_id_raw is not None else None
+            ),
+            items_count=int(data.get("items_count") or 0),
+            owner=bool(data.get("owner", False)),
+            items=[EntityListItem.from_json(item) for item in data.get("items") or []],
+            created_at=_parse_iso_datetime(data.get("created_at")),
+            updated_at=_parse_iso_datetime(data.get("updated_at")),
+        )

src/md_python/resources/v2/__init__.py

@@ -4,6 +4,7 @@
 
 from .datasets import Datasets
 from .entities import Entities
+from .entity_lists import EntityLists
 from .jobs import Jobs
 from .module_registry import ModuleRegistry
 from .uploads import Uploads
@@ -13,6 +14,7 @@
     "Uploads",
     "Datasets",
     "Entities",
+    "EntityLists",
     "Jobs",
     "Workspaces",
     "Tabs",

src/md_python/resources/v2/entity_lists.py

@@ -0,0 +1,113 @@
+"""
+EntityLists resource for the MD Python v2 client.
+
+Maps the two endpoints exposed under a workspace:
+
+  POST /api/workspaces/:workspace_id/entity_lists      → create
+  GET  /api/workspaces/:workspace_id/entity_lists/:id  → show
+
+There is no list/index endpoint yet (the server-side controller exposes
+only Create and Show), so this resource intentionally does not implement
+``list``. Looking up an entity list requires its id.
+"""
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence, Union
+
+from ...models.entity_list import EntityList, EntityListItem
+
+if TYPE_CHECKING:
+    from ...base_client import BaseMDClient
+
+
+_JSON_HEADERS = {"Content-Type": "application/json"}
+
+
+def _check(response: Any, expected: int, action: str) -> None:
+    if response.status_code != expected:
+        raise Exception(f"Failed to {action}: {response.status_code} - {response.text}")
+
+
+# A caller can pass items as a list of EntityListItem objects or as a
+# list of plain dicts ({entity_id, group_id, dataset_id}). Both shapes
+# are normalised before sending.
+EntityListItemInput = Union[EntityListItem, Dict[str, Any]]
+
+
+class EntityLists:
+    """Workspace-scoped entity lists (proteins / peptides / genes).
+
+    Reached via ``client.workspaces.entity_lists`` and always
+    parameterised by ``workspace_id`` since lists live under a workspace.
+    """
+
+    def __init__(self, client: "BaseMDClient"):
+        self._client = client
+
+    def _base(self, workspace_id: str) -> str:
+        return f"/workspaces/{workspace_id}/entity_lists"
+
+    def create(
+        self,
+        workspace_id: str,
+        name: str,
+        entity_type: str,
+        items: Sequence[EntityListItemInput],
+    ) -> EntityList:
+        """Create a named entity list inside a workspace.
+
+        Args:
+            workspace_id: Parent workspace UUID.
+            name: Display name for the list.
+            entity_type: One of ``protein``, ``peptide``, or ``gene``.
+            items: At least one item. Each item is either an
+                :class:`EntityListItem` or a dict with ``entity_id``,
+                ``group_id`` and ``dataset_id``.
+
+        Returns:
+            The created :class:`EntityList` (with ``items`` populated).
+        """
+        if entity_type not in {"protein", "peptide", "gene"}:
+            raise ValueError(
+                "entity_type must be one of: protein, peptide, gene "
+                f"(got {entity_type!r})"
+            )
+        if not items:
+            raise ValueError("items must include at least one entry")
+
+        payload_items: List[Dict[str, Any]] = []
+        for item in items:
+            if isinstance(item, EntityListItem):
+                payload_items.append(item.to_create_payload())
+            elif isinstance(item, dict):
+                if "entity_id" not in item:
+                    raise ValueError("every item must have an 'entity_id' field")
+                payload_items.append(dict(item))
+            else:
+                raise TypeError(
+                    "items entries must be EntityListItem or dict, "
+                    f"got {type(item).__name__}"
+                )
+
+        response = self._client._make_request(
+            method="POST",
+            endpoint=self._base(workspace_id),
+            json={
+                "name": name,
+                "entity_type": entity_type,
+                "items": payload_items,
+            },
+            headers=_JSON_HEADERS,
+        )
+        _check(response, 201, "create entity list")
+        return EntityList.from_json(response.json())
+
+    def get(self, workspace_id: str, list_id: str) -> Optional[EntityList]:
+        """Get a single entity list, or ``None`` if not found."""
+        response = self._client._make_request(
+            method="GET",
+            endpoint=f"{self._base(workspace_id)}/{list_id}",
+        )
+        if response.status_code == 404:
+            return None
+        _check(response, 200, "get entity list")
+        return EntityList.from_json(response.json())

src/md_python/resources/v2/workspaces.py

@@ -13,6 +13,7 @@
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 from ...models import RegisteredModule, Tab, TabModule, Workspace
+from .entity_lists import EntityLists
 
 if TYPE_CHECKING:
     from ...base_client import BaseMDClient
@@ -411,6 +412,7 @@ def __init__(
         self._client = client
         self.tabs = Tabs(client)
         self.modules = TabModules(client, registry=registry)
+        self.entity_lists = EntityLists(client)
 
     def create(self, name: str, description: Optional[str] = None) -> Workspace:
         payload: Dict[str, Any] = {"name": name}