biosero-data-services-sdk 0.1.1__tar.gz

biosero_data_services_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: biosero-data-services-sdk
+Version: 0.1.1
+Summary: SDK for interacting with the Biosero Data Services API
+Author: Eli Fine
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12.7
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: structlog>=25.3.0
+Requires-Dist: nested-diff>=1.8.0
+Requires-Dist: requests>=2.32.4
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+[![Actions status](https://github.com/lab-sync/biosero-data-services-sdk/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/lab-sync/biosero-data-services-sdk/actions)
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/lab-sync/biosero-data-services-sdk)
+[![PyPI Version](https://img.shields.io/pypi/v/biosero-data-services-sdk.svg)](https://pypi.org/project/biosero-data-services-sdk/)
+[![Downloads](https://pepy.tech/badge/biosero-data-services-sdk)](https://pepy.tech/project/biosero-data-services-sdk)
+[![Python Versions](https://img.shields.io/pypi/pyversions/biosero-data-services-sdk.svg)](https://pypi.org/project/biosero-data-services-sdk/)
+[![Codecov](https://codecov.io/gh/lab-sync/biosero-data-services-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/lab-sync/biosero-data-services-sdk)
+
+# Usage
+Documentation is hosted on [ReadTheDocs](https://biosero-data-services-sdk.readthedocs.io/en/latest/?badge=latest).
+
+# Development
+This project has a dev container. If you already have VS Code and Docker installed, you can click the badge above or [here](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/lab-sync/biosero-data-services-sdk) to get started. Clicking these links will cause VS Code to automatically install the Dev Containers extension if needed, clone the source code into a container volume, and spin up a dev container for use.
+
+To publish a new version of the repository, you can run the `Publish` workflow manually and publish to the staging registry from any branch, and you can check the 'Publish to Primary' option when on `main` to publish to the primary registry and create a git tag.
+
+Open a connection to the EC2 instance hosting GBG Data Services in AWS:
+```bash
+aws ssm start-session --target i-0e5fd6d0bcdfd3c03 --document-name AWS-StartPortForwardingSession --parameters '{"portNumber":["8105"],"localPortNumber":["8105"]}'
+```
+
+When running the unit test suite, `pytest-recording` library is used. If it gives you errors about a cassette missing, the parameter to invoke a live HTTP request is `--record-mode=once` (add on to the end of the `pytest` command)
+
+
+
+## Updating from the template
+This repository uses a copier template. To pull in the latest updates from the template, use the command:
+`copier update --trust --conflict rej --defaults`

biosero_data_services_sdk-0.1.1/README.md

@@ -0,0 +1,31 @@
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+[![Actions status](https://github.com/lab-sync/biosero-data-services-sdk/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/lab-sync/biosero-data-services-sdk/actions)
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/lab-sync/biosero-data-services-sdk)
+[![PyPI Version](https://img.shields.io/pypi/v/biosero-data-services-sdk.svg)](https://pypi.org/project/biosero-data-services-sdk/)
+[![Downloads](https://pepy.tech/badge/biosero-data-services-sdk)](https://pepy.tech/project/biosero-data-services-sdk)
+[![Python Versions](https://img.shields.io/pypi/pyversions/biosero-data-services-sdk.svg)](https://pypi.org/project/biosero-data-services-sdk/)
+[![Codecov](https://codecov.io/gh/lab-sync/biosero-data-services-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/lab-sync/biosero-data-services-sdk)
+
+# Usage
+Documentation is hosted on [ReadTheDocs](https://biosero-data-services-sdk.readthedocs.io/en/latest/?badge=latest).
+
+# Development
+This project has a dev container. If you already have VS Code and Docker installed, you can click the badge above or [here](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/lab-sync/biosero-data-services-sdk) to get started. Clicking these links will cause VS Code to automatically install the Dev Containers extension if needed, clone the source code into a container volume, and spin up a dev container for use.
+
+To publish a new version of the repository, you can run the `Publish` workflow manually and publish to the staging registry from any branch, and you can check the 'Publish to Primary' option when on `main` to publish to the primary registry and create a git tag.
+
+Open a connection to the EC2 instance hosting GBG Data Services in AWS:
+```bash
+aws ssm start-session --target i-0e5fd6d0bcdfd3c03 --document-name AWS-StartPortForwardingSession --parameters '{"portNumber":["8105"],"localPortNumber":["8105"]}'
+```
+
+When running the unit test suite, `pytest-recording` library is used. If it gives you errors about a cassette missing, the parameter to invoke a live HTTP request is `--record-mode=once` (add on to the end of the `pytest` command)
+
+
+
+## Updating from the template
+This repository uses a copier template. To pull in the latest updates from the template, use the command:
+`copier update --trust --conflict rej --defaults`

biosero_data_services_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "biosero-data-services-sdk"
+version = "0.1.1"
+description = "SDK for interacting with the Biosero Data Services API"
+authors = [
+    {name = "Eli Fine"},
+
+]
+readme = "README.md"
+requires-python = ">=3.12.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+
+    "Programming Language :: Python :: 3.12",
+
+    "Programming Language :: Python :: 3.13",
+
+]
+dependencies = [
+    "pydantic>=2.11.7",
+    "structlog>=25.3.0",
+    "nested-diff>=1.8.0",
+    "requests>=2.32.4",
+]
+
+
+[dependency-groups]
+dev = [
+    # Specific to this repository
+
+    "vcrpy>=7.0.0",
+    "pytest-recording>=0.13.4",
+    "time-machine>=2.17.0",
+    "beautifulsoup4>=4.13.4",
+    "syrupy>=4.9.1",
+    "pytest-mock>=3.14.0",
+
+    # Managed by upstream template
+    "pyright>=1.1.403",
+    "pytest>=8.4.1",
+    "pytest-cov>=6.2.1",
+    "pytest-randomly>=3.16.0",
+
+
+]
+
+[tool.setuptools]
+license-files = [] # kludge until this bug is fixed https://github.com/pypa/setuptools/issues/4759
+
+[tool.uv]
+package = true
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple/"
+publish-url = "https://upload.pypi.org/legacy/"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"

biosero_data_services_sdk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

biosero_data_services_sdk-0.1.1/src/biosero_data_services_sdk/__init__.py

@@ -0,0 +1,156 @@
+from . import sdk
+from .constants import BIOSERO_CONTAINER_IDENTITY_TYPE_ID
+from .constants import BIOSERO_DATA_SERVICES_HOSTNAME_ENVVAR_NAME
+from .constants import BIOSERO_MATERIAL_IDENTITY_TYPE_ID
+from .constants import BIOSERO_RESOURCE_IDENTITY_TYPE_ID
+from .constants import BIOSERO_SAMPLE_IDENTITY_TYPE_ID
+from .constants import BIOSERO_TRANSFER_STATION_IDENTITY_TYPE_ID
+from .constants import DATA_STORE_ARBITRARY_JSON_ID_BASE
+from .constants import DATA_STORE_GENERIC_STATE_ID_BASE
+from .constants import DATA_STORE_ROOT_ID_BASE
+from .constants import DATA_STORE_TENANT_SUFFIX_ENVVAR_NAME
+from .constants import DATA_STORE_TENANT_SUFFIX_LENGTH
+from .constants import DEFAULT_DATA_STORE_TENANT_SUFFIX
+from .constants import IDENTITY_ROOT_ID
+from .constants import WASTE_LOCATION_ID
+from .exceptions import DataRecordOverflowError
+from .exceptions import DataServicesApiError
+from .exceptions import DataStoreArbitraryJsonIdentityMissingError
+from .exceptions import DataStoreRootIdentityMissingError
+from .exceptions import EventDoesNotExistError
+from .exceptions import IdentityAlreadyExistsError
+from .exceptions import IdentityDoesNotExistError
+from .exceptions import IdentityIsNotContainerError
+from .exceptions import IdentityIsNotSubstanceError
+from .exceptions import IdentityIsNotTransferStationError
+from .exceptions import InvalidEventQueryParametersError
+from .exceptions import NothingToScanProvidedError
+from .exceptions import OrderDoesNotExistError
+from .exceptions import OrderParameterNotInTemplateError
+from .exceptions import OrderTemplateAlreadyExistsError
+from .exceptions import OrderTemplateDoesNotExistError
+from .exceptions import SeeminglyInfiniteLocationPathError
+from .exceptions import TransportationRequestDoesNotExistError
+from .logger_config import configure_logging
+from .models import BAD_ORDER_STATUSES
+from .models import LIQUID_TRANSFER_EVENT_TOPIC
+from .models import LOCATION_CHANGED_EVENT_TOPIC
+from .models import DataServicesContainer
+from .models import DataServicesEvent
+from .models import DataServicesIdentity
+from .models import DataServicesIdentityProperty
+from .models import DataServicesIdentityPropertyQuery
+from .models import DataServicesLocation
+from .models import DataServicesMaterialInContainer
+from .models import DataServicesModel
+from .models import DataServicesSampleInContainer
+from .models import DataServicesSubstanceInContainer
+from .models import DataServicesTransportationRequest
+from .models import IdentityPropertyNotFoundError
+from .models import IdentityPropertyValueType
+from .models import LiquidTransferEvent
+from .models import LocationChangedEvent
+from .models import NullContainerIdError
+from .models import NullIdentityPropertyValueError
+from .models import Order
+from .models import OrderParameter
+from .models import OrderStatus
+from .models import OrderTemplate
+from .models import OrderTemplateScript
+from .models import OrderTemplateWorkflow
+from .models import TransportationRequestStatus
+from .models import VolumeAmount
+from .reports import DataServicesInconsistenciesReport
+from .reports import EventUploadReport
+from .reports import IdentitiesMergeReport
+from .reports import IdentityDiff
+from .reports import MissingIdentitiesAtLocationReport
+from .reports import MissingIdentitiesAtLocationWithChildrenReport
+from .sdk import DataServicesSdk
+from .sdk import clear_items_in_waste_cache
+from .sdk import get_items_in_waste_cache
+from .sdk_base import DataStoreStateBase
+from .types import EventId
+from .types import IdentityId
+from .types import IdentityName
+from .types import LocationPath
+
+__all__ = [
+    "BAD_ORDER_STATUSES",
+    "BIOSERO_CONTAINER_IDENTITY_TYPE_ID",
+    "BIOSERO_DATA_SERVICES_HOSTNAME_ENVVAR_NAME",
+    "BIOSERO_MATERIAL_IDENTITY_TYPE_ID",
+    "BIOSERO_RESOURCE_IDENTITY_TYPE_ID",
+    "BIOSERO_SAMPLE_IDENTITY_TYPE_ID",
+    "BIOSERO_TRANSFER_STATION_IDENTITY_TYPE_ID",
+    "DATA_STORE_ARBITRARY_JSON_ID_BASE",
+    "DATA_STORE_GENERIC_STATE_ID_BASE",
+    "DATA_STORE_ROOT_ID_BASE",
+    "DATA_STORE_TENANT_SUFFIX_ENVVAR_NAME",
+    "DATA_STORE_TENANT_SUFFIX_LENGTH",
+    "DEFAULT_DATA_STORE_TENANT_SUFFIX",
+    "IDENTITY_ROOT_ID",
+    "LIQUID_TRANSFER_EVENT_TOPIC",
+    "LOCATION_CHANGED_EVENT_TOPIC",
+    "WASTE_LOCATION_ID",
+    "DataRecordOverflowError",
+    "DataServicesApiError",
+    "DataServicesContainer",
+    "DataServicesEvent",
+    "DataServicesIdentity",
+    "DataServicesIdentityProperty",
+    "DataServicesIdentityPropertyQuery",
+    "DataServicesInconsistenciesReport",
+    "DataServicesLocation",
+    "DataServicesMaterialInContainer",
+    "DataServicesModel",
+    "DataServicesSampleInContainer",
+    "DataServicesSdk",
+    "DataServicesSubstanceInContainer",
+    "DataServicesTransportationRequest",
+    "DataStoreArbitraryJsonIdentityMissingError",
+    "DataStoreArbitraryJsonIdentityMissingError",
+    "DataStoreRootIdentityMissingError",
+    "DataStoreStateBase",
+    "EventDoesNotExistError",
+    "EventId",
+    "EventUploadReport",
+    "IdentitiesMergeReport",
+    "IdentityAlreadyExistsError",
+    "IdentityDiff",
+    "IdentityDoesNotExistError",
+    "IdentityId",
+    "IdentityIsNotContainerError",
+    "IdentityIsNotSubstanceError",
+    "IdentityIsNotTransferStationError",
+    "IdentityName",
+    "IdentityPropertyNotFoundError",
+    "IdentityPropertyValueType",
+    "InvalidEventQueryParametersError",
+    "LiquidTransferEvent",
+    "LocationChangedEvent",
+    "LocationPath",
+    "MissingIdentitiesAtLocationReport",
+    "MissingIdentitiesAtLocationWithChildrenReport",
+    "NothingToScanProvidedError",
+    "NullContainerIdError",
+    "NullIdentityPropertyValueError",
+    "Order",
+    "OrderDoesNotExistError",
+    "OrderParameter",
+    "OrderParameterNotInTemplateError",
+    "OrderStatus",
+    "OrderTemplate",
+    "OrderTemplateAlreadyExistsError",
+    "OrderTemplateDoesNotExistError",
+    "OrderTemplateScript",
+    "OrderTemplateWorkflow",
+    "SeeminglyInfiniteLocationPathError",
+    "TransportationRequestDoesNotExistError",
+    "TransportationRequestStatus",
+    "VolumeAmount",
+    "clear_items_in_waste_cache",
+    "configure_logging",
+    "get_items_in_waste_cache",
+    "sdk",
+]

biosero_data_services_sdk-0.1.1/src/biosero_data_services_sdk/constants.py

@@ -0,0 +1,17 @@
+# IDs created by BioSero within  DataServices itself
+IDENTITY_ROOT_ID = "7818C3CC-51AC-42FE-B38F-A9342857A859"
+BIOSERO_MATERIAL_IDENTITY_TYPE_ID = "885C27BC-8121-4ABC-8FAD-A9DD08B26B09"
+BIOSERO_SAMPLE_IDENTITY_TYPE_ID = "A1A3E1FA-1016-4E68-89A9-EDFE98E4F419"
+BIOSERO_RESOURCE_IDENTITY_TYPE_ID = "C6E397A9-447E-41B0-B7B7-0459249F3C69"
+BIOSERO_CONTAINER_IDENTITY_TYPE_ID = "AE62812F-A108-47E0-8B96-2B0CA7617CE2"
+BIOSERO_TRANSFER_STATION_IDENTITY_TYPE_ID = "97E22FF1-0393-4B3D-96C2-45343919AC92"
+# Arbitrarily created IDs
+WASTE_LOCATION_ID = "Waste"
+DATA_STORE_ROOT_ID_BASE = "CFC74038-9FC8-474B-A9A2-909"
+DATA_STORE_ARBITRARY_JSON_ID_BASE = "A52E078A-A300-49F3-96F3-7E8"
+DATA_STORE_GENERIC_STATE_ID_BASE = "9B2A01A1-BFAE-4479-B4F1-C2F"
+DEFAULT_DATA_STORE_TENANT_SUFFIX = "unittes"
+DATA_STORE_TENANT_SUFFIX_ENVVAR_NAME = "DATA_SERVICES_DATA_STORE_TENANT_SUFFIX"
+DATA_STORE_TENANT_SUFFIX_LENGTH = 7  # keep it consistent so the overall ID is the same length as UUID
+
+BIOSERO_DATA_SERVICES_HOSTNAME_ENVVAR_NAME = "BIOSERO_DATA_SERVICES_HOSTNAME"

biosero_data_services_sdk-0.1.1/src/biosero_data_services_sdk/events_sdk.py

@@ -0,0 +1,100 @@
+import datetime
+import json
+import logging
+from pathlib import Path
+from typing import cast
+
+import requests
+from pydantic import JsonValue
+
+from .exceptions import DataServicesApiError
+from .exceptions import EventDoesNotExistError
+from .exceptions import InvalidEventQueryParametersError
+from .models import DataServicesEvent
+from .reports import EventUploadReport
+from .sdk_base import SdkBase
+from .types import EventId
+
+logger = logging.getLogger(__name__)
+
+
+class EventsSdk(SdkBase):
+    def publish_event(self, event: DataServicesEvent, *, explicitly_set_id: bool = False) -> EventId:
+        # Although the Swagger documentation says that the `data` field is nullable, we seem to get errors trying to publish an event with no data...unclear if we should refactor to assume it's non-nullable in all cases or just leave as-is
+
+        payload = event.to_api_request()
+        # Although the Swagger documentation says that the `createdDateUtc` field can be supplied, it doesn't seem to be respected when supplied
+        _ = payload.pop("createdDateUtc", None)
+        if not explicitly_set_id:
+            _ = payload.pop("eventId", None)
+
+        response = self._post_request(query="EventService", payload=payload)
+        assert isinstance(response, str), f"Expected a string, got {type(response)} with value {response}"
+        return response
+
+    def get_events(
+        self, *, start: datetime.datetime | None = None, end: datetime.datetime | None = None, topic: str | None = None
+    ) -> list[DataServicesEvent]:
+        payload: dict[str, JsonValue] = {}
+        if start is not None:
+            payload["start"] = start.isoformat()
+        if end is not None:
+            payload["end"] = end.isoformat()
+        if topic is not None:
+            payload["topic"] = topic
+        if not payload:
+            raise InvalidEventQueryParametersError
+        response = self._post_request(query="QueryService/Events", payload=payload)
+        assert isinstance(response, list), f"Expected a list, got {type(response)} with value {response}"
+        event_list: list[DataServicesEvent] = []
+        for item in response:
+            assert isinstance(item, dict), f"Expected a dict, got {type(item)} with value {item}"
+            event = DataServicesEvent.from_api_response(item)
+            event_list.append(event)
+        return event_list
+
+    def get_event_by_id(self, event_id: str) -> DataServicesEvent:
+        try:
+            response = self._get_query(f"events/{event_id}", api_version=3)
+        except DataServicesApiError as e:
+            if e.status_code == requests.codes.not_found and "Event with EventId" in e.body:
+                raise EventDoesNotExistError(event_id) from e
+            raise  # pragma: nocover # not sure how to test this defensive statement
+        assert isinstance(response, dict), f"Expected a dict, got {type(response)} with value {response}"
+        return DataServicesEvent.from_api_response(response)
+
+    def upload_events_from_file(self, savepoint_dir: Path, *, preview: bool = False) -> EventUploadReport:
+        all_events_json_files = sorted(savepoint_dir.rglob("*events*.json"))
+        report = EventUploadReport()
+        for json_file in all_events_json_files:
+            with json_file.open() as f:
+                json_data = json.load(f)
+            assert isinstance(json_data, list), f"Expected list but got type {type(json_data)} for file {json_file}"
+            num_events_in_file = len(json_data)  # pyright: ignore[reportUnknownArgumentType] # we're loading in JSON and then asserting about it
+            for idx, event_json in enumerate(json_data):  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType] # we're loading in JSON and then asserting about it
+                event_json = cast(dict[str, JsonValue], event_json)
+                assert isinstance(event_json, dict), f"Expected dict but got type {type(event_json)} for {event_json}"
+                event_in_file = DataServicesEvent.from_api_response(event_json)
+                logger.info(
+                    f"Processing event {event_in_file.id} from file {json_file} for upload. {idx + 1}/{num_events_in_file} in file"
+                )
+                matching_existing_event: DataServicesEvent | None = None
+                try:
+                    matching_existing_event = self.get_event_by_id(event_in_file.id)
+                except EventDoesNotExistError:
+                    matching_existing_event = None
+
+                if matching_existing_event is None:
+                    if not preview:
+                        _ = self.publish_event(event_in_file, explicitly_set_id=True)
+                    report.created.append(event_in_file.id)
+                    continue
+                fields_to_exclude = {"created_at", "original_full_json_string"}
+                existing_event_fields = matching_existing_event.model_dump(exclude=fields_to_exclude)
+                event_in_file_fields = event_in_file.model_dump(exclude=fields_to_exclude)
+                if existing_event_fields == event_in_file_fields:
+                    report.untouched.append(event_in_file.id)
+                    continue
+                report.conflicts.append(event_in_file.id)
+
+        return report

biosero_data_services_sdk-0.1.1/src/biosero_data_services_sdk/exceptions.py

@@ -0,0 +1,119 @@
+from .models import DataServicesIdentity
+from .types import RequestWithOffset
+
+
+class DataServicesApiError(Exception):
+    def __init__(self, *, url: str, status_code: int, reason: str, body: str) -> None:
+        self.url = url
+        self.status_code = status_code
+        self.reason = reason
+        self.body = body
+        super().__init__(f"Error querying {url}. Status code: {status_code}. Reason: {reason}. Body: {body}")
+
+
+class SeeminglyInfiniteLocationPathError(Exception):
+    def __init__(self, *, original_id: str, location_path: list[str]):
+        super().__init__(
+            f"The location path for {original_id} seems to be infinite. This is likely due to a circular reference in the location hierarchy. Please check the location data for circular references. {location_path}"
+        )
+
+
+class IdentityIsNotSubstanceError(Exception):
+    def __init__(self, info: str | DataServicesIdentity) -> None:
+        super().__init__(
+            f"The provided identity {info} is not a Substance. It must be a direct child of Sample or Material identities for Data Services to be able to handle it."
+        )
+
+
+class IdentityIsNotContainerError(Exception):
+    def __init__(self, info: str | DataServicesIdentity) -> None:
+        super().__init__(
+            f"The provided identity {info} is not a Container. It must be within the hierarchy of Container definitions."
+        )
+
+
+class IdentityIsNotTransferStationError(Exception):
+    def __init__(self, info: str | DataServicesIdentity) -> None:
+        super().__init__(
+            f"The provided identity {info} is not a Transfer Station. It must be within the hierarchy of Transfer Station definitions."
+        )
+
+
+class OrderParameterNotInTemplateError(Exception):
+    def __init__(self, *, parameter_name: str, template_name: str, template_parameters: list[str]):
+        super().__init__(
+            f"Order parameter '{parameter_name}' is not in the order template '{template_name}'. Available parameters: {', '.join(template_parameters)}"
+        )
+
+
+class IdentityDoesNotExistError(Exception):
+    def __init__(self, *, id: str, extra_message: str = "") -> None:
+        super().__init__(
+            f"Identity with identifier '{id}' does not exist" + (f"\n{extra_message}" if extra_message else "")
+        )
+
+
+class OrderDoesNotExistError(Exception):
+    def __init__(self, id: str):
+        super().__init__(f"Order with ID {id} does not exist.")
+
+
+class OrderTemplateDoesNotExistError(Exception):
+    def __init__(self, name: str):
+        super().__init__(f"Order template '{name}' does not exist.")
+
+
+class OrderTemplateAlreadyExistsError(Exception):
+    def __init__(self, name: str):
+        super().__init__(f"Order template '{name}' already exists.")
+
+
+class TransportationRequestDoesNotExistError(Exception):
+    def __init__(self, request_id: str):
+        super().__init__(f"Transportation request with id {request_id} does not exist.")
+
+
+class IdentityAlreadyExistsError(Exception):
+    def __init__(self, id: str):
+        super().__init__(f"Identity with identifier '{id}' already exists.")
+
+
+class EventDoesNotExistError(Exception):
+    def __init__(self, event_id: str):
+        super().__init__(f"Event with ID {event_id} does not exist.")
+
+
+class InvalidEventQueryParametersError(Exception):
+    def __init__(self):
+        super().__init__("At least one of the query parameters must be provided.")
+
+
+class DataStoreRootIdentityMissingError(IdentityDoesNotExistError):
+    pass
+
+
+class DataStoreArbitraryJsonIdentityMissingError(IdentityDoesNotExistError):
+    pass
+
+
+class NothingToScanProvidedError(Exception):
+    def __init__(self):
+        super().__init__("Nothing to check for inconsistencies was passed in as an argument.")
+
+
+class DataRecordOverflowError(Exception):
+    def __init__(self, *, max_limit: int, request: RequestWithOffset):
+        request_info = self._get_request_info(request)
+        super().__init__(
+            f"Exceeded maximum limit of {max_limit} items while fetching data from DataServices API using {request_info}."
+        )
+
+    def _get_request_info(self, request: RequestWithOffset) -> str:
+        """Extract meaningful information from the request, especially if it's a partial function."""
+        if hasattr(request, "func") and hasattr(request, "keywords"):  # It's likely a partial
+            func_name = request.func.__name__ if hasattr(request.func, "__name__") else str(request.func)  # pyright: ignore[reportUnknownArgumentType,reportUnknownMemberType,reportAttributeAccessIssue,reportUnknownVariableType] # this is tested and it works
+            keywords = ", ".join(f"{k}={v!r}" for k, v in request.keywords.items())  # pyright: ignore[reportUnknownMemberType,reportAttributeAccessIssue,reportUnknownVariableType] # this is tested and it works
+            return f"partial({func_name}, {keywords})"
+        raise NotImplementedError(
+            f"Not sure how we got here, but this should always be called with a partial. The request was {request!r}"
+        )

biosero_data_services_sdk-0.1.1/src/biosero_data_services_sdk/identities_sdk.py

@@ -0,0 +1,70 @@
+import logging
+
+from .exceptions import IdentityDoesNotExistError
+from .models import DataServicesIdentity
+from .sdk_base import SdkBase
+from .types import IdentityId
+
+logger = logging.getLogger(__name__)
+
+
+class IdentitiesSdk(SdkBase):
+    def get_child_identities(
+        self, parent_id: str, *, recursive: bool = False, confirm_parent_id_exists: bool = True
+    ) -> list[DataServicesIdentity]:
+        # The API for ChildIdentities does not actually check if the parent exists...it will just silently return an empty list. That's unexpected API behavior, so we check it ourselves, which will raise an error if it doesn't exist
+        if confirm_parent_id_exists:
+            _ = self.get_identity_by_id(parent_id)
+        limit = 999999  # arbitrarily large number
+        identity_list: list[DataServicesIdentity] = []
+        response = self._get_query(f"QueryService/ChildIdentities?parentTypeId={parent_id}&limit={limit}")
+        assert isinstance(response, list), f"Expected a list, got {type(response)} with value {response}"
+
+        for item in response:
+            assert isinstance(item, dict), f"Expected a dict, got {type(item)} with value {item}"
+            identity = DataServicesIdentity.from_api_response(item)
+            identity_list.append(identity)
+            if recursive:
+                child_identities = self.get_child_identities(
+                    identity.id, recursive=True, confirm_parent_id_exists=False
+                )
+                identity_list.extend(child_identities)
+        return identity_list
+
+    def is_identity_name_a_child_of(self, *, name: str, parent_id: str) -> bool:
+        identities = self._get_query(f"identities?name={name}&typeIdentifier={parent_id}&limit=1", api_version=3)
+        assert isinstance(identities, list), f"Expected a list, got {type(identities)} with value {identities}"
+        return len(identities) > 0
+
+    def is_identity_a_descendent_of(
+        self,
+        *,
+        identity_id: str,
+        ancestor_id: str,
+        is_being_called_recursively: bool = False,
+        identities_cache: dict[IdentityId, DataServicesIdentity] | None = None,
+    ) -> bool:
+        if identities_cache is None:
+            identities_cache = {}
+        if identity_id in identities_cache:
+            identity = identities_cache[identity_id]
+        else:
+            try:
+                identity = self.get_identity_by_id(identity_id)
+            except IdentityDoesNotExistError:
+                if not is_being_called_recursively:
+                    raise
+                return False
+            identities_cache[identity_id] = identity
+        if identity.parent_id == ancestor_id:
+            return True
+        if identity.parent_id == "":
+            return False
+        if identity.parent_id is None:
+            return False
+        return self.is_identity_a_descendent_of(
+            identity_id=identity.parent_id,
+            ancestor_id=ancestor_id,
+            is_being_called_recursively=True,
+            identities_cache=identities_cache,
+        )