benchling-sdk 1.18.1__py3-none-any.whl → 1.19.0__py3-none-any.whl

benchling_sdk/helpers/client_helpers.py

@@ -11,6 +11,11 @@ def replace_client_path(client: Client, base_path: str) -> Client:
     return client.with_base_url(updated_url.geturl())
 
 
+def v2_stable_client(client: Client) -> Client:
+    """Override a client's base URL with a v2 stable path."""
+    return replace_client_path(client, "api/v2")
+
+
 def v2_alpha_client(client: Client) -> Client:
     """Override a client's base URL with a v2-alpha path."""
     return replace_client_path(client, "api/v2-alpha")

benchling_sdk/helpers/task_helpers.py

@@ -0,0 +1,145 @@
+from dataclasses import dataclass
+from typing import Any, cast, Generic, Optional, Type, TypeVar
+
+from benchling_api_client.v2.stable.client import Client
+
+from benchling_sdk.helpers.serialization_helpers import unset_as_none
+from benchling_sdk.models import AsyncTaskErrors, AsyncTaskLink, AsyncTaskStatus
+
+ResponseT = TypeVar("ResponseT")
+
+
+@dataclass
+class TaskCompletion(Generic[ResponseT]):
+    """Return type for TaskHelper.wait_for_task, same as AsyncTask but with a typed response."""
+
+    success: bool
+    errors: Optional[AsyncTaskErrors] = None
+    message: Optional[str] = None
+    response: Optional[ResponseT] = None
+
+
+@dataclass
+class TaskFailureException(Exception):
+    """Exception type used by :py:class:`.TaskHelper` methods."""
+
+    errors: AsyncTaskErrors
+    message: Optional[str]
+
+
+class EmptyTaskResponse:
+    """A sentinel object used for tasks that do not return any response data on completion."""
+
+    pass
+
+
+EMPTY_TASK_RESPONSE = EmptyTaskResponse()
+
+
+class TaskHelper(AsyncTaskLink, Generic[ResponseT]):
+    """Used by Benchling async task endpoints to provide the task response in an appropriate type.
+
+    In the API spec, endpoints that create a long-running task are defined as returning an
+    :py:class:`benchling_sdk.models.AsyncTaskLink`, which can be used with
+    :py:class:`benchling_sdk.services.v2.stable.TaskService` to query the task status and
+    response. But AsyncTaskLink and the task query endpoint do not define a specific schema
+    for the task response.
+
+    To work around that limitation, those SDK endpoints now return a TaskHelper instead. This is
+    subclassed from AsyncTaskLink for backward compatibility, but unlike AsyncTaskLink, TaskHelper
+    knows what the type of the task response should be. It also retains an association with the API
+    client, so rather than calling a separate service method, you can simply call
+    :py:meth:`.TaskHelper.wait_for_completion` or :py:meth:`.TaskHelper.wait_for_response`.
+
+    You can access a task for up to 30 minutes after its completion, after which its data will no
+    longer be available.
+    """
+
+    _client: Client
+    _response_class: Type[ResponseT]
+    _response_decoder: Any
+    # _response_decoder is really a Callable, but adding that type hint would cause problems because
+    # mypy would treat it as an instance method and assume it should have a self parameter.
+
+    def __init__(self, from_task_link: AsyncTaskLink, client: Client, response_class: Type[ResponseT]):
+        """Initialize the instance. This should only be used internally by Benchling API methods."""
+        self.task_id = from_task_link.task_id
+        self.additional_properties = from_task_link.additional_properties
+        self._client = client
+        self._response_class = response_class
+
+        if response_class is not EmptyTaskResponse:
+            assert hasattr(response_class, "from_dict")
+            self._response_decoder = getattr(response_class, "from_dict")
+
+    def wait_for_completion(
+        self, interval_wait_seconds: int = 1, max_wait_seconds: int = 600
+    ) -> TaskCompletion[ResponseT]:
+        """Wait for the task to succeed or fail.
+
+        This is equivalent to the :py:meth:`benchling_sdk.services.v2.stable.task_service.TaskService.wait_for_task`
+        method in :py:class:`benchling_sdk.services.v2.stable.task_service.TaskService`, except that
+        instead of returning an :py:class:`benchling_sdk.models.AsyncTask` whose `response` property is
+        a dict, it returns a :py:class:`TaskCompletion` whose `response` property is the appropriate type
+        for the API method you called. For instance, if the method was `AaSequenceService.bulk_create`,
+        the response type will be :py:class:`benchling_sdk.models.BulkCreateAaSequencesAsyncTaskResponse`.
+
+        :param interval_wait_seconds: time to wait between API calls in seconds
+        :param max_wait_seconds: maximum wait time in seconds before raising an error
+        :return: The task completion status. Check `status` for success or failure
+        :rtype: TaskCompletion
+        :raises benchling_sdk.errors.WaitForTaskExpiredError: if the maximum wait time has elapsed
+        """
+        from benchling_sdk.helpers.client_helpers import v2_stable_client
+        from benchling_sdk.services.v2.stable.task_service import TaskService
+
+        # The "get task" polling endpoint is part of the v2 stable API; it doesn't exist in alpha or beta.
+        task_service = TaskService(v2_stable_client(self._client))
+
+        task = task_service.wait_for_task(
+            self.task_id, interval_wait_seconds=interval_wait_seconds, max_wait_seconds=max_wait_seconds
+        )
+        response: Optional[ResponseT]
+        if task.status != AsyncTaskStatus.SUCCEEDED:
+            response = None
+        elif self._response_class is EmptyTaskResponse:
+            response = cast(ResponseT, EMPTY_TASK_RESPONSE)
+        else:
+            response = self._response_decoder(task.response.to_dict())
+        errors = None if task.status != AsyncTaskStatus.FAILED else unset_as_none(task.errors)
+        message = None if task.status != AsyncTaskStatus.FAILED else unset_as_none(task.message)
+        return TaskCompletion(
+            success=task.status == AsyncTaskStatus.SUCCEEDED,
+            errors=errors,
+            message=message,
+            response=response,
+        )
+
+    def wait_for_response(self, interval_wait_seconds: int = 1, max_wait_seconds: int = 600) -> ResponseT:
+        """Wait for the task and return the response object on success, or raise an exception on failure.
+
+        This is a convenience method for calling :py:meth:`wait_for_completion` and then getting the
+        `response` property of the returned object if the task succeeded, in cases where you're not
+        interested in any :py:class:`.TaskCompletion` properties except the response.
+
+        The type of the returned object is depends on the API method you called. For instance, if the
+        method was `AaSequenceService.bulk_create`, the response type will be
+        :py:class:`benchling_sdk.models.BulkCreateAaSequencesAsyncTaskResponse`.
+
+        :param interval_wait_seconds: time to wait between API calls in seconds
+        :param max_wait_seconds: maximum wait time in seconds before raising an error
+        :return: The response object, if the task succeeded.
+        :rtype: ResponseT
+        :raises benchling_sdk.errors.WaitForTaskExpiredError: if the maximum wait time has elapsed
+        :raises .TaskFailureException: if the task failed
+        """
+        task_completion = self.wait_for_completion(interval_wait_seconds, max_wait_seconds)
+        if not task_completion.success:
+            raise TaskFailureException(task_completion.errors or AsyncTaskErrors(), task_completion.message)
+        assert task_completion.response, "completed task should have contained a response"
+        # This assertion matches the behavior of TaskHelper.wait_for_completion(): response is only set
+        # to None if the task failed, otherwise it should always be an object even if that object is an
+        # EmptyTaskResponse. This also matches how we define async task models in the API spec, where
+        # if we don't care about the response field, it's an empty object rather than null.
+
+        return task_completion.response

benchling_sdk/services/v2/alpha/v2_alpha_assembly_service.py

@@ -11,6 +11,7 @@ from benchling_api_client.v2.alpha.models.create_and_finalize_assembly_json_body
 
 from benchling_sdk.helpers.decorators import api_method
 from benchling_sdk.helpers.response_helpers import model_from_detailed
+from benchling_sdk.helpers.task_helpers import TaskHelper
 from benchling_sdk.models import AsyncTaskLink
 from benchling_sdk.services.v2.base_service import BaseService
 
@@ -36,17 +37,18 @@ class V2AlphaAssemblyService(BaseService):
         return model_from_detailed(response)
 
     @api_method
-    def create_and_finalize(self, create: CreateAndFinalizeAssemblyJsonBody) -> AsyncTaskLink:
+    def create_and_finalize(self, create: CreateAndFinalizeAssemblyJsonBody) -> TaskHelper[Assembly]:
         """
         Create and finalize a new bulk assembly in a single step.
 
-        This endpoint launches a long-running task and returns the Task ID of the launched task.
-        The task response contains a finalized bulk assembly.
+        This endpoint launches a long-running task and returns a
+        :py:class:`benchling_sdk.helpers.task_helpers.TaskHelper` for waiting on the task.
+        On success, the task's response will be an :py:class:`.Assembly`.
 
         See https://benchling.com/api/v2-alpha/reference#/Assemblies/CreateAndFinalizeAssembly
         """
         response = create_and_finalize_assembly.sync_detailed(client=self.client, json_body=create)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, Assembly)
 
     @api_method
     def validate(self, assembly: AssemblySpecShared) -> AsyncTaskLink:

benchling_sdk/services/v2/base_service.py

@@ -1,9 +1,15 @@
 from abc import ABC
+from typing import Type, TYPE_CHECKING
 
 from benchling_api_client.v2.stable.client import Client
+from benchling_api_client.v2.types import Response
 
+from benchling_sdk.helpers.response_helpers import model_from_detailed
 from benchling_sdk.helpers.retry_helpers import RetryStrategy
 
+if TYPE_CHECKING:
+    from benchling_sdk.helpers.task_helpers import TaskHelper
+
 
 class BaseService(ABC):
     """Abstract class for Benchling functional namespaces."""
@@ -37,3 +43,8 @@ class BaseService(ABC):
         Override this in alpha and beta services that use a client other than self._client.
         """
         return cls(self._client, self._retry_strategy)
+
+    def _task_helper_from_response(self, response: Response, result_type: Type) -> "TaskHelper":
+        from benchling_sdk.helpers.task_helpers import TaskHelper
+
+        return TaskHelper(model_from_detailed(response), self.client, result_type)

benchling_sdk/services/v2/beta/v2_beta_audit_service.py

@@ -2,8 +2,8 @@ from benchling_api_client.v2.beta.api.audit import audit_log
 from benchling_api_client.v2.beta.models.audit_log_export import AuditLogExport
 
 from benchling_sdk.helpers.decorators import api_method
-from benchling_sdk.helpers.response_helpers import model_from_detailed
-from benchling_sdk.models import AsyncTaskLink
+from benchling_sdk.helpers.task_helpers import TaskHelper
+from benchling_sdk.models import ExportAuditLogAsyncTaskResponse
 from benchling_sdk.services.v2.base_service import BaseService
 
 
@@ -17,25 +17,30 @@ class V2BetaAuditService(BaseService):
     """
 
     @api_method
-    def get_audit_log(self, object_id: str, export: AuditLogExport) -> AsyncTaskLink:
+    def get_audit_log(
+        self, object_id: str, export: AuditLogExport
+    ) -> TaskHelper[ExportAuditLogAsyncTaskResponse]:
         """
         Export an audit log file for a Benchling object.
 
-        This endpoint launches a long-running task and returns the Task ID of the
-        launched task. The task response contains a link to download the exported audit
-        log file from Amazon S3. This endpoint is subject to a rate limit of 500 requests
-        per hour, in conjunction with the global request rate limit. Export throughput
-        will additionally be rate limited around the scale of 70,000 total audit events
-        exported in csv format or 30,000 total audit events exported in pdf format per hour.
+        This endpoint launches a long-running task and returns a
+        :py:class:`benchling_sdk.helpers.task_helpers.TaskHelper`. On success, the task's
+        response will be an :py:class:`.ExportAuditLogAsyncTaskResponse` containing a link to
+        download the exported audit log file from Amazon S3.
+
+        This endpoint is subject to a rate limit of 500 requests per hour, in conjunction with
+        the global request rate limit. Export throughput will additionally be rate limited around
+        the scale of 70,000 total audit events exported in csv format or 30,000 total audit events
+        exported in pdf format per hour.
 
         Example of submitting an export request and then getting the download URL from
         the completed task:
 
-            task_link = benchling.v2.beta.audit.get_audit_log(object_id, export)
-            task = benchling.tasks.wait_for_task(task_link.task_id)
-            url = task.response["downloadURL"]
+            task = benchling.v2.beta.audit.get_audit_log(object_id, export)
+            task_result = task.wait_for_response()
+            url = task_result.download_url
 
         See https://benchling.com/api/v2-beta/reference#/Audit/auditLog
         """
         response = audit_log.sync_detailed(client=self.client, object_id=object_id, json_body=export)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, ExportAuditLogAsyncTaskResponse)

benchling_sdk/services/v2/beta/v2_beta_data_frame_service.py

@@ -19,7 +19,7 @@ import httpx
 from benchling_sdk.errors import DataFrameInProgressError, InvalidDataFrameError, raise_for_status
 from benchling_sdk.helpers.decorators import api_method
 from benchling_sdk.helpers.response_helpers import model_from_detailed
-from benchling_sdk.models import AsyncTaskLink
+from benchling_sdk.helpers.task_helpers import TaskHelper
 from benchling_sdk.services.v2.base_service import BaseService
 
 _DEFAULT_HTTP_TIMEOUT_UPLOAD_DATA_FRAME: float = 60.0
@@ -55,7 +55,7 @@ class V2BetaDataFrameService(BaseService):
         return model_from_detailed(response)
 
     @api_method
-    def update(self, data_frame_id: str, data_frame: DataFrameUpdate) -> AsyncTaskLink:
+    def update(self, data_frame_id: str, data_frame: DataFrameUpdate) -> TaskHelper[DataFrame]:
         """
         Update a data frame.
 
@@ -64,7 +64,7 @@ class V2BetaDataFrameService(BaseService):
         response = patch_data_frame.sync_detailed(
             client=self.client, data_frame_id=data_frame_id, json_body=data_frame
         )
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, DataFrame)
 
     def upload_bytes(
         self,
@@ -114,15 +114,15 @@ class V2BetaDataFrameService(BaseService):
         data_frame: DataFrameCreate,
         input_bytes: Union[BytesIO, bytes],
         timeout_seconds: float = _DEFAULT_HTTP_TIMEOUT_UPLOAD_DATA_FRAME,
-    ) -> AsyncTaskLink:
+    ) -> TaskHelper[DataFrame]:
         """Create a data frame from bytes or BytesIO data.
 
         :param data_frame: The DataFrameCreate specification for the data. This must be provided, as it cannot be inferred from file names.
         :param input_bytes: Data to upload as bytes or BytesIO
         :param timeout_seconds: Extends the normal HTTP timeout settings since DataFrame uploads can be large
             Use this to extend even further if streams are very large
-        :return: An AsyncTaskLink that can be polled to know when the data frame has completed processing
-        :rtype: AsyncTaskLink
+        :return: A TaskHelper that can be polled to know when the data frame has completed processing
+        :rtype: TaskHelper[DataFrame]
         """
         # This is a current limit of the DataFrame API. We may need additional methods in the future
         # to allow multi upload
@@ -150,15 +150,15 @@ class V2BetaDataFrameService(BaseService):
         file: Path,
         data_frame: Optional[DataFrameCreate] = None,
         timeout_seconds: float = _DEFAULT_HTTP_TIMEOUT_UPLOAD_DATA_FRAME,
-    ) -> AsyncTaskLink:
+    ) -> TaskHelper[DataFrame]:
         """Create a data frame from file data.
 
         :param file: A valid Path to an existing file containing the data to upload
         :param data_frame: The DataFrameCreate specification for the data. If not provided, it will be inferred from the file name
         :param timeout_seconds: Extends the normal HTTP timeout settings since DataFrame uploads can be large
             Use this to extend even further if streams are very large
-        :return: An AsyncTaskLink that can be polled to know when the data frame has completed processing
-        :rtype: AsyncTaskLink
+        :return: A TaskHelper that can be polled to know when the data frame has completed processing
+        :rtype: TaskHelper[DataFrame]
         """
         if file.is_dir():
             raise IsADirectoryError(

benchling_sdk/services/v2/stable/aa_sequence_service.py

@@ -32,6 +32,7 @@ from benchling_sdk.helpers.serialization_helpers import (
     optional_array_query_param,
     schema_fields_query_param,
 )
+from benchling_sdk.helpers.task_helpers import EmptyTaskResponse, TaskHelper
 from benchling_sdk.models import (
     AaSequence,
     AaSequenceBulkCreate,
@@ -49,10 +50,13 @@ from benchling_sdk.models import (
     AaSequencesUnarchive,
     AaSequenceUpdate,
     AaSequenceUpsert,
-    AsyncTaskLink,
     AutoAnnotateAaSequences,
     BackTranslate,
+    BulkCreateAaSequencesAsyncTaskResponse,
+    BulkCreateDnaSequencesAsyncTaskResponse,
+    BulkUpdateAaSequencesAsyncTaskResponse,
     EntityArchiveReason,
+    FindMatchingRegionsAsyncTaskResponse,
     ListAASequencesSort,
 )
 from benchling_sdk.services.v2.base_service import BaseService
@@ -264,7 +268,9 @@ class AaSequenceService(BaseService):
         return aa_sequences_results.aa_sequences
 
     @api_method
-    def bulk_create(self, aa_sequences: Iterable[AaSequenceBulkCreate]) -> AsyncTaskLink:
+    def bulk_create(
+        self, aa_sequences: Iterable[AaSequenceBulkCreate]
+    ) -> TaskHelper[BulkCreateAaSequencesAsyncTaskResponse]:
         """
         Bulk create AA sequences.
 
@@ -272,10 +278,12 @@ class AaSequenceService(BaseService):
         """
         body = AaSequencesBulkCreateRequest(list(aa_sequences))
         response = bulk_create_aa_sequences.sync_detailed(client=self.client, json_body=body)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkCreateAaSequencesAsyncTaskResponse)
 
     @api_method
-    def bulk_update(self, aa_sequences: Iterable[AaSequenceBulkUpdate]) -> AsyncTaskLink:
+    def bulk_update(
+        self, aa_sequences: Iterable[AaSequenceBulkUpdate]
+    ) -> TaskHelper[BulkUpdateAaSequencesAsyncTaskResponse]:
         """
         Bulk update AA sequences.
 
@@ -283,17 +291,17 @@ class AaSequenceService(BaseService):
         """
         body = AaSequencesBulkUpdateRequest(list(aa_sequences))
         response = bulk_update_aa_sequences.sync_detailed(client=self.client, json_body=body)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkUpdateAaSequencesAsyncTaskResponse)
 
     @api_method
-    def auto_annotate(self, auto_annotate: AutoAnnotateAaSequences) -> AsyncTaskLink:
+    def auto_annotate(self, auto_annotate: AutoAnnotateAaSequences) -> TaskHelper[EmptyTaskResponse]:
         """
         Auto-annotate AA sequences with matching features from specified Feature Libraries.
 
         See https://benchling.com/api/reference#/AA%20Sequences/autoAnnotateAaSequences
         """
         response = auto_annotate_aa_sequences.sync_detailed(client=self.client, json_body=auto_annotate)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, EmptyTaskResponse)
 
     @api_method
     def upsert(self, entity_registry_id: str, aa_sequence: AaSequenceUpsert) -> AaSequence:
@@ -310,7 +318,7 @@ class AaSequenceService(BaseService):
     @api_method
     def bulk_upsert(
         self, body: AaSequencesBulkUpsertRequest, returning: Optional[Iterable[str]] = None
-    ) -> AsyncTaskLink:
+    ) -> TaskHelper[BulkUpdateAaSequencesAsyncTaskResponse]:
         """
         Bulk create or update AA sequences.
 
@@ -320,10 +328,12 @@ class AaSequenceService(BaseService):
         response = bulk_upsert_aa_sequences.sync_detailed(
             client=self.client, json_body=body, returning=none_as_unset(returning_string)
         )
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkUpdateAaSequencesAsyncTaskResponse)
 
     @api_method
-    def find_matching_regions(self, find_matching_region: AaSequencesFindMatchingRegion) -> AsyncTaskLink:
+    def find_matching_regions(
+        self, find_matching_region: AaSequencesFindMatchingRegion
+    ) -> TaskHelper[FindMatchingRegionsAsyncTaskResponse]:
         """
         Find matching regions for AA sequences.
 
@@ -332,17 +342,17 @@ class AaSequenceService(BaseService):
         response = find_matching_regions_aa_sequences.sync_detailed(
             client=self.client, json_body=find_matching_region
         )
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, FindMatchingRegionsAsyncTaskResponse)
 
     @api_method
-    def back_translate(self, translate: BackTranslate) -> AsyncTaskLink:
+    def back_translate(self, translate: BackTranslate) -> TaskHelper[BulkCreateDnaSequencesAsyncTaskResponse]:
         """
         Create back-translated DNA sequences from AA sequences.
 
         See https://benchling.com/api/v2/reference#/AA%20Sequences/backTranslate
         """
         response = back_translate.sync_detailed(client=self.client, json_body=translate)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkCreateDnaSequencesAsyncTaskResponse)
 
     @api_method
     def _match_bases_page(self, match_bases: AaSequencesMatchBases) -> Response[AaSequencesPaginatedList]:

benchling_sdk/services/v2/stable/app_service.py

@@ -442,7 +442,7 @@ class AppService(BaseService):
     #     return PageIterator(api_call, results_extractor)
 
     @api_method
-    def get_canvas_by_id(self, canvas_id: str) -> AppCanvas:
+    def get_canvas_by_id(self, canvas_id: str, returning: Optional[List[str]] = None) -> AppCanvas:
         """
         Get the current state of the App Canvas, including user input elements.
 
@@ -451,6 +451,7 @@ class AppService(BaseService):
         response = get_app_canvas.sync_detailed(
             client=self.client,
             canvas_id=canvas_id,
+            returning=none_as_unset(optional_array_query_param(returning)),
         )
         return model_from_detailed(response)
 
@@ -511,7 +512,7 @@ class AppService(BaseService):
         return model_from_detailed(response)
 
     @api_method
-    def get_session_by_id(self, session_id: str) -> AppSession:
+    def get_session_by_id(self, session_id: str, returning: Optional[List[str]] = None) -> AppSession:
         """
         Get a Benchling App session.
 
@@ -520,6 +521,7 @@ class AppService(BaseService):
         response = get_app_session_by_id.sync_detailed(
             client=self.client,
             id=session_id,
+            returning=none_as_unset(optional_array_query_param(returning)),
         )
         return model_from_detailed(response)
 

benchling_sdk/services/v2/stable/assay_result_service.py

@@ -25,6 +25,7 @@ from benchling_sdk.helpers.serialization_helpers import (
     none_as_unset,
     optional_array_query_param,
 )
+from benchling_sdk.helpers.task_helpers import TaskHelper
 from benchling_sdk.helpers.transaction_manager import TransactionManager
 from benchling_sdk.models import (
     AssayResult,
@@ -37,7 +38,6 @@ from benchling_sdk.models import (
     AssayResultsCreateResponse,
     AssayResultsPaginatedList,
     AssayResultTransactionCreateResponse,
-    AsyncTaskLink,
     ListAssayResultsSort,
 )
 from benchling_sdk.services.v2.base_service import BaseService
@@ -202,7 +202,7 @@ class AssayResultService(BaseService):
     @api_method
     def bulk_create(
         self, assay_results: Iterable[AssayResultCreate], table_id: Optional[str] = None
-    ) -> AsyncTaskLink:
+    ) -> TaskHelper[AssayResultsCreateResponse]:
         """
         Create 1 or more results.
 
@@ -212,7 +212,7 @@ class AssayResultService(BaseService):
             assay_results=list(assay_results), **({"table_id": table_id} if table_id else {})
         )
         response = bulk_create_assay_results.sync_detailed(client=self.client, json_body=request_body)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, AssayResultsCreateResponse)
 
     @api_method
     def archive(self, assay_result_ids: Iterable[str]) -> AssayResultIdsResponse:

benchling_sdk/services/v2/stable/container_service.py

@@ -34,8 +34,10 @@ from benchling_sdk.helpers.serialization_helpers import (
     optional_array_query_param,
     schema_fields_query_param,
 )
+from benchling_sdk.helpers.task_helpers import TaskHelper
 from benchling_sdk.models import (
-    AsyncTaskLink,
+    BulkCreateContainersAsyncTaskResponse,
+    BulkUpdateContainersAsyncTaskResponse,
     Container,
     ContainerBulkUpdateItem,
     ContainerContent,
@@ -59,6 +61,7 @@ from benchling_sdk.models import (
     MultipleContainersTransfersList,
     PrintLabels,
     SampleRestrictionStatus,
+    TransfersAsyncTaskResponse,
 )
 from benchling_sdk.services.v2.base_service import BaseService
 
@@ -264,7 +267,9 @@ class ContainerService(BaseService):
         return containers_list.containers
 
     @api_method
-    def bulk_create(self, containers: Iterable[ContainerCreate]) -> AsyncTaskLink:
+    def bulk_create(
+        self, containers: Iterable[ContainerCreate]
+    ) -> TaskHelper[BulkCreateContainersAsyncTaskResponse]:
         """
         Bulk create containers.
 
@@ -272,10 +277,12 @@ class ContainerService(BaseService):
         """
         body = ContainersBulkCreateRequest(list(containers))
         response = bulk_create_containers.sync_detailed(client=self.client, json_body=body)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkCreateContainersAsyncTaskResponse)
 
     @api_method
-    def bulk_update(self, containers: Iterable[ContainerBulkUpdateItem]) -> AsyncTaskLink:
+    def bulk_update(
+        self, containers: Iterable[ContainerBulkUpdateItem]
+    ) -> TaskHelper[BulkUpdateContainersAsyncTaskResponse]:
         """
         Bulk update containers.
 
@@ -283,7 +290,7 @@ class ContainerService(BaseService):
         """
         body = ContainersBulkUpdateRequest(list(containers))
         response = bulk_update_containers.sync_detailed(client=self.client, json_body=body)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkUpdateContainersAsyncTaskResponse)
 
     @api_method
     def create(self, container: ContainerCreate) -> Container:
@@ -440,7 +447,7 @@ class ContainerService(BaseService):
     @api_method
     def transfer_into_containers(
         self, transfer_requests: Iterable[MultipleContainersTransfer]
-    ) -> AsyncTaskLink:
+    ) -> TaskHelper[TransfersAsyncTaskResponse]:
         """
         Transfer into containers.
 
@@ -448,4 +455,4 @@ class ContainerService(BaseService):
         """
         multiple_requests = MultipleContainersTransfersList(transfers=list(transfer_requests))
         response = transfer_into_containers.sync_detailed(client=self.client, json_body=multiple_requests)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, TransfersAsyncTaskResponse)

benchling_sdk/services/v2/stable/custom_entity_service.py

@@ -26,8 +26,10 @@ from benchling_sdk.helpers.serialization_helpers import (
     optional_array_query_param,
     schema_fields_query_param,
 )
+from benchling_sdk.helpers.task_helpers import TaskHelper
 from benchling_sdk.models import (
-    AsyncTaskLink,
+    BulkCreateCustomEntitiesAsyncTaskResponse,
+    BulkUpdateCustomEntitiesAsyncTaskResponse,
     CustomEntitiesArchivalChange,
     CustomEntitiesArchive,
     CustomEntitiesBulkCreateRequest,
@@ -250,7 +252,9 @@ class CustomEntityService(BaseService):
         return custom_entities.custom_entities
 
     @api_method
-    def bulk_create(self, entities: Iterable[CustomEntityBulkCreate]) -> AsyncTaskLink:
+    def bulk_create(
+        self, entities: Iterable[CustomEntityBulkCreate]
+    ) -> TaskHelper[BulkCreateCustomEntitiesAsyncTaskResponse]:
         """
         Bulk create custom entities.
 
@@ -258,10 +262,12 @@ class CustomEntityService(BaseService):
         """
         body = CustomEntitiesBulkCreateRequest(list(entities))
         response = bulk_create_custom_entities.sync_detailed(client=self.client, json_body=body)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkCreateCustomEntitiesAsyncTaskResponse)
 
     @api_method
-    def bulk_update(self, entities: Iterable[CustomEntityBulkUpdate]) -> AsyncTaskLink:
+    def bulk_update(
+        self, entities: Iterable[CustomEntityBulkUpdate]
+    ) -> TaskHelper[BulkUpdateCustomEntitiesAsyncTaskResponse]:
         """
         Bulk update custom entities.
 
@@ -269,7 +275,7 @@ class CustomEntityService(BaseService):
         """
         body = CustomEntitiesBulkUpdateRequest(list(entities))
         response = bulk_update_custom_entities.sync_detailed(client=self.client, json_body=body)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkUpdateCustomEntitiesAsyncTaskResponse)
 
     @api_method
     def upsert(self, entity_registry_id: str, entity: CustomEntityUpsertRequest) -> CustomEntity:
@@ -284,11 +290,13 @@ class CustomEntityService(BaseService):
         return model_from_detailed(response)
 
     @api_method
-    def bulk_upsert(self, body: CustomEntitiesBulkUpsertRequest) -> AsyncTaskLink:
+    def bulk_upsert(
+        self, body: CustomEntitiesBulkUpsertRequest
+    ) -> TaskHelper[BulkUpdateCustomEntitiesAsyncTaskResponse]:
         """
         Bulk update custom entities.
 
         See https://benchling.com/api/reference#/Custom%20Entities/bulkUpsertCustomEntities
         """
         response = bulk_upsert_custom_entities.sync_detailed(client=self.client, json_body=body)
-        return model_from_detailed(response)
+        return self._task_helper_from_response(response, BulkUpdateCustomEntitiesAsyncTaskResponse)