add and exercise a few more api endpoints

minrk · minrk · commit 3a895871a4d9 · 2025-11-25T17:04:57.000-08:00
- patient lookup by email
- list data sources
- filter patients by org and study
- filter study by org
diff --git a/jupyterhealth_client/_client.py b/jupyterhealth_client/_client.py
@@ -220,24 +220,61 @@ def get_patient(self, id: int) -> dict[str, Any]:
         patient = cast(dict[str, Any], self._api_request(f"patients/{id}"))
         return patient
 
+    def lookup_patient(
+        self, *, email: str | None = None, external_id: str | None = None
+    ) -> dict[str, Any] | None:
+        """Lookup a patient by email or external id.
+
+        Raises KeyError if no patient is found, otherwise returns patient record.
+        """
+        if email is None and external_id is None:
+            raise TypeError(
+                "Specify one of `email` or `external_id` to lookup a patient"
+            )
+        if email:
+            for patient in self._api_request(
+                "patients/global_lookup", params={"email": email}
+            ):
+                return patient
+            raise KeyError(
+                f"No patient found with external identifier: {external_id!r}"
+            )
+        elif external_id:
+            # TODO: this should be a single lookup, but no API in JHE yet
+            for patient in self.list_patients():
+                if patient["identifier"] == external_id:
+                    return patient
+            raise KeyError(
+                f"No patient found with external identifier: {external_id!r}"
+            )
+
     def get_patient_by_external_id(self, external_id: str) -> dict[str, Any]:
         """Get a single patient by external id.
 
         For looking up the JHE Patient record by an external (e.g. EHR) patient id.
         """
+        warnings.warn(
+            f"get_patient_by_external_id is deprecated, use lookup_patient(external_id={external_id!r})",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.lookup_patient(external_id=external_id)
 
-        # TODO: this should be a single lookup, but no API in JHE yet
-        for patient in self.list_patients():
-            if patient["identifier"] == external_id:
-                return patient
-        raise KeyError(f"No patient found with external identifier: {external_id!r}")
-
-    def list_patients(self) -> Generator[dict[str, dict[str, Any]]]:
+    def list_patients(
+        self, organization_id: int | None = None, study_id: int | None = None
+    ) -> Generator[dict[str, dict[str, Any]]]:
         """Iterate over all patients.
 
+        Optionally filter by organization or study id.
+
         Patient ids are the keys that may be passed to e.g. :meth:`list_observations`.
         """
-        yield from self._list_api_request("patients")
+        params = {}
+        if organization_id is not None:
+            params["organization_id"] = organization_id
+        if study_id is not None:
+            params["study_id"] = study_id
+        yield from self._list_api_request("patients", params=params)
 
     def get_patient_consents(self, patient_id: int) -> dict[str, Any]:
         """Return patient consent status.
@@ -330,12 +367,17 @@ def get_study(self, id: int) -> dict[str, Any]:
         """
         return cast(dict[str, Any], self._api_request(f"studies/{id}"))
 
-    def list_studies(self) -> Generator[dict[str, dict[str, Any]]]:
+    def list_studies(
+        self, *, organization_id: int | None = None
+    ) -> Generator[dict[str, dict[str, Any]]]:
         """Iterate over studies.
 
         Only returns studies I have access to (i.e. owned by my organization(s)).
         """
-        return self._list_api_request("studies")
+        params = {}
+        if organization_id is not None:
+            params["organization_id"] = organization_id
+        return self._list_api_request("studies", params=params)
 
     def get_organization(self, id: int) -> dict[str, Any]:
         """Get a single organization by id.
@@ -366,6 +408,10 @@ def list_organizations(self) -> Generator[dict[str, dict[str, Any]]]:
         """
         return self._list_api_request("organizations")
 
+    def list_data_sources(self) -> Generator[dict[str, dict[str, Any]]]:
+        """List all registered data sources"""
+        return self._list_api_request("data_sources")
+
     def list_observations(
         self,
         patient_id: int | None = None,
diff --git a/jupyterhealth_client/_utils.py b/jupyterhealth_client/_utils.py
@@ -33,7 +33,7 @@ def flatten_dict(d: dict | list, prefix: str = "") -> dict:
         if prefix:
             key = f"{prefix}_{key}"
 
-        if isinstance(value, (dict, list)):
+        if isinstance(value, dict | list):
             for sub_key, sub_value in flatten_dict(value, prefix=key).items():
                 flat_dict[sub_key] = sub_value
         else:
diff --git a/pyproject.toml b/pyproject.toml
@@ -27,7 +27,11 @@ Issues = "https://github.com/jupyterhealth/jupyterhealth-client/issues"
 Source = "https://github.com/jupyterhealth/jupyterhealth-client"
 
 [project.optional-dependencies]
-test = ["pytest"]
+test = [
+  "pytest",
+  "pytest-cov",
+  "responses",
+]
 
 [build-system]
 requires = ["hatchling"]
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -0,0 +1,34 @@
+from pathlib import Path
+
+import pytest
+import yaml
+from responses import RequestsMock
+
+from jupyterhealth_client import JupyterHealthClient
+
+HOST = "https://jhe.local"
+
+# load mocked responses from a file
+_response_yaml = Path(__file__).parent / "responses.yaml"
+with _response_yaml.open() as f:
+    response_list = yaml.safe_load(f)
+
+for response in response_list:
+    response.setdefault("method", "GET")
+    response.setdefault("status", 200)
+    if "://" not in response["url"]:
+        assert response["url"].startswith("/")
+        response["url"] = HOST + response["url"]
+
+
+@pytest.fixture
+def responses():
+    with RequestsMock(assert_all_requests_are_fired=False) as responses:
+        for response in response_list:
+            responses.add(**response)
+        yield responses
+
+
+@pytest.fixture
+def jh_client(responses):
+    return JupyterHealthClient(url=HOST, token="abc123")
diff --git a/tests/responses.yaml b/tests/responses.yaml
@@ -0,0 +1,192 @@
+# mocked responses
+# optional:
+#  - method (default: GET)
+#  - status (default: 200)
+# required:
+#  - url
+#  - body OR json
+  - method: GET
+    url: /api/v1/users/profile
+    status: 200
+    json:
+      id: 10008
+      email: fake@email.com
+      firstName: first
+      lastName: last
+      patient:
+      userType: practitioner
+      isSuperUser: false
+  - url: /api/v1/organizations/20013
+    json:
+      children: []
+      currentUserRole: manager
+      id: 20013
+      name: Department
+      partOf: 20011
+      type: edu
+  - url: /api/v1/organizations/404
+    status: 404
+  - url: /api/v1/organizations
+    json:
+      count: 4
+      next:
+      previous:
+      results:
+        - children: []
+          currentUserRole: manager
+          id: 20013
+          name: Department
+          partOf: 20011
+          type: edu
+        - children: []
+          currentUserRole:
+          id: 0
+          name: ROOT
+          partOf:
+          type: root
+        - children: []
+          currentUserRole:
+          id: 20011
+          name: University A
+          partOf: 0
+          type: edu
+        - children: []
+          currentUserRole:
+          id: 20001
+          name: University B
+          partOf: 0
+          type: edu
+
+          count: 8
+  - url: /api/v1/studies
+    json:
+      count: 2
+      next:
+      previous:
+      results:
+        - description: Study description
+          iconUrl:
+          id: 30001
+          name: ACME Health CGM Study
+          organization:
+            id: 20013
+            name: Department
+            type: edu
+        - description: Another study
+          iconUrl:
+          id: 30012
+          name: Study 2
+          organization:
+            id: 20001
+            name: University B
+            type: edu
+  - url: /api/v1/studies?organization_id=20013
+    json:
+      count: 1
+      next:
+      previous:
+      results:
+        - description: Study description
+          iconUrl:
+          id: 30001
+          name: ACME Health CGM Study
+          organization:
+            id: 20013
+            name: Department
+            type: edu
+  - url: /api/v1/studies/30001
+    json:
+      description: Study description
+      iconUrl:
+      id: 30001
+      name: ACME Health CGM Study
+      organization:
+        id: 20013
+        name: Department
+        type: edu
+  - url: /api/v1/studies/404
+    status: 404
+  - url: /api/v1/studies?organization_id=404
+    json:
+      count: 0
+      next:
+      previous:
+      results: []
+  - url: /api/v1/patients
+    json:
+      count: 2
+      next:
+      previous:
+      results:
+        - birthDate: '1955-01-01'
+          id: 40001
+          identifier: demouser-min
+          jheUserId: 10007
+          nameFamily: Patient
+          nameGiven: Demo
+          organizations:
+            - children: []
+              currentUserRole:
+              id: 20013
+              name: Department
+              partOf: 20011
+              type: edu
+          telecomEmail: demouser@jupyterhealth.example.org
+          telecomPhone:
+        - birthDate: '1980-01-01'
+          id: 40002
+          identifier: demouser-simon
+          jheUserId: 10011
+          nameFamily: Patient
+          nameGiven: Simon
+          organizations:
+            - children: []
+              currentUserRole:
+              id: 20013
+              name: Department
+              partOf: 20011
+              type: edu
+          telecomEmail: simondemo@example.com
+          telecomPhone:
+  - url: /api/v1/patients/40001
+    json:
+      birthDate: '1955-01-01'
+      id: 40001
+      identifier: demouser-min
+      jheUserId: 10007
+      nameFamily: Patient
+      nameGiven: Demo
+      organizations:
+        - children: []
+          currentUserRole:
+          id: 20013
+          name: Department
+          partOf: 20011
+          type: edu
+      telecomEmail: demouser@jupyterhealth.example.org
+      telecomPhone:
+  - url: /api/v1/patients/404
+    status: 404
+    json:
+      detail: No patient matches the given query
+  - url: /api/v1/patients/global_lookup?email=demouser%40jupyterhealth.example.org
+    json:
+      - id: 40001
+        identifier: demouser-min
+        jheUserId: 10007
+  - url: /api/v1/patients/global_lookup?email=nosuchuser%40jupyterhealth.example.org
+    json: []
+  - url: /api/v1/data_sources
+    json:
+      count: 2
+      next:
+      previous:
+      results:
+        - id: 70002
+          name: Another Device
+          supportedScopes: []
+          type: personal_device
+        - id: 70001
+          name: Some Device
+          supportedScopes: []
+          type: personal_device
diff --git a/tests/test_client.py b/tests/test_client.py
