Modalities.get_async() + move_async()

Author: amazy

orthanc_api_client/job.py

@@ -34,6 +34,7 @@ def __init__(self, json_job: object):
         self.status = json_job.get('State')
         self.type = json_job.get('Type')
         self.content = json_job.get('Content')
+        self.dimseErrorStatus = json_job.get('DimseErrorStatus')  # new in Orthanc 1.12.10
 
 
 class Job:

orthanc_api_client/modalities.py

@@ -173,6 +173,25 @@ def get_study(self, from_modality: str, dicom_id: str):
             from_modality=from_modality
         )
 
+    def get_study_async(self, from_modality: str, dicom_id: str) -> Job:
+        """
+        retrieves a study from a remote modality (C-Get)
+
+        This call is asynchronous and returns a job.
+
+        :param from_modality: the modality alias configured in orthanc
+        :param dicom_id: the StudyInstanceUid of the study to move
+        """
+        return Job.from_json(self._api_client, self._get(
+            level="Study",
+            resource={
+                "StudyInstanceUID": dicom_id
+            },
+            from_modality=from_modality,
+            asynchronous=True
+        ))
+
+
     def get_series(self, from_modality: str, dicom_id: str, study_dicom_id: str):
         """
         retrieves a series from a remote modality (C-Get)
@@ -232,6 +251,26 @@ def move_study(self, from_modality: str, dicom_id: str, to_modality_aet: str = N
             to_modality_aet=to_modality_aet
         )
 
+    def move_study_async(self, from_modality: str, dicom_id: str, to_modality_aet: str = None) -> Job:
+        """
+        moves a study from a remote modality (C-Move) to a target modality (AET)
+
+        This call is asynchronous.  It returns a job.
+
+        :param from_modality: the modality alias configured in orthanc
+        :param dicom_id: the StudyInstanceUid of the study to move
+        :param to_modality_aet: the AET of the target modality
+        """
+        return Job.from_json(self._api_client, self._move(
+            level="Study",
+            resource={
+                "StudyInstanceUID": dicom_id
+            },
+            from_modality=from_modality,
+            to_modality_aet=to_modality_aet,
+            asynchronous=True
+        ))
+
     def move_series(self, from_modality: str, dicom_id: str, study_dicom_id: str, to_modality_aet: str = None):
         """
         moves a series from a remote modality (C-Move) to a target modality (AET)
@@ -276,30 +315,29 @@ def move_instance(self, from_modality: str, dicom_id: str, series_dicom_id: str,
             to_modality_aet=to_modality_aet
         )
 
-    def _move(self, level: str, resource: object, from_modality: str, to_modality_aet: str = None):
+    def _move(self, level: str, resource: object, from_modality: str, to_modality_aet: str = None, asynchronous: bool = False):
         """
         moves a study from a remote modality (C-Move) to a target modality (AET)
 
-        this call is synchronous.  It completes once the C-Move is complete.
-
         :param from_modality: the modality alias configured in orthanc
         :param to_modality_aet: the AET of the target modality
         """
 
         payload = {
             'Level': level,
-            'Resources': [resource]
+            'Resources': [resource],
+            'Asynchronous': asynchronous
         }
 
         if to_modality_aet:
             payload['TargetAet'] = to_modality_aet
 
-        self._api_client.post(
+        return self._api_client.post(
             endpoint=f"{self._url_segment}/{from_modality}/move",
-            json=payload)
+            json=payload).json()
 
 
-    def _get(self, level: str, resource: object, from_modality: str):
+    def _get(self, level: str, resource: object, from_modality: str, asynchronous: bool = False):
         """
         retrieves a study from a remote modality (C-Get)
 
@@ -310,12 +348,13 @@ def _get(self, level: str, resource: object, from_modality: str):
 
         payload = {
             'Level': level,
-            'Resources': [resource]
+            'Resources': [resource],
+            'Asynchronous': asynchronous
         }
 
-        self._api_client.post(
+        return self._api_client.post(
             endpoint=f"{self._url_segment}/{from_modality}/get",
-            json=payload)
+            json=payload).json()
 
 
     def query_studies(self, from_modality: str, query: object) -> typing.List[RemoteModalityStudy]:

orthanc_api_client/resources/resources.py

@@ -450,7 +450,7 @@ def print_daily_stats(self, from_date: datetime.date = None, to_date: datetime.d
             print(f"{current_date} - " + str(len(r.json())))
             current_date += datetime.timedelta(days=1)
 
-    def _lookup(self, filter: str, dicom_id: str) -> str:
+    def _lookup(self, filter: str, dicom_id: str) -> Optional[str]:
         """
         finds a resource in Orthanc based on its dicom id
 

orthanc_api_client/resources/studies.py

@@ -1,5 +1,5 @@
 import datetime
-from typing import List, Any, Union, Set
+from typing import List, Any, Union, Set, Optional
 
 from .resources import Resources
 from ..tags import Tags
@@ -63,7 +63,7 @@ def get_modalities(self, orthanc_id: str) -> Set[str]:
     def get_parent_patient_id(self, orthanc_id: str) -> str:
         return self._api_client.get_json(f"{self._url_segment}/{orthanc_id}/patient")['ID']
 
-    def lookup(self, dicom_id: str) -> str:
+    def lookup(self, dicom_id: str) -> Optional[str]:
         """
         finds a study in Orthanc based on its StudyInstanceUid
 

release-notes.md

@@ -1,3 +1,8 @@
+v 0.20.0
+========
+
+- Added `Modalities.get_async()` & `Modalities.move_async()`
+
 v 0.19.0
 ========
 

setup.py

@@ -28,7 +28,7 @@
     # For a discussion on single-sourcing the version across setup.py and the
     # project code, see
     # https://packaging.python.org/guides/single-sourcing-package-version/
-    version='0.19.0',  # Required
+    version='0.20.0',  # Required
 
     # This is a one-line description or tagline of what your project does. This
     # corresponds to the "Summary" metadata field:

tests/docker-setup/docker-compose.yml

@@ -1,4 +1,3 @@
-version: "3"
 services:
   orthanc-a:
     image: orthancteam/orthanc:25.8.2

tests/test_api_client.py

@@ -443,9 +443,8 @@ def test_modalities_move(self):
         self.assertIsNotNone(self.ob.instances.lookup('7.8.9'))
 
         #request C to move it from B to A
-
         self.oc.modalities.move_study(from_modality='orthanc-b', dicom_id='1.2.3', to_modality_aet='ORTHANCA')
-        self.assertIsNotNone(1, self.oa.studies.lookup('1.2.3'))
+        self.assertIsNotNone(self.oa.studies.lookup('1.2.3'))
         self.oa.delete_all_content()
 
         self.oc.modalities.move_series(from_modality='orthanc-b', dicom_id='4.5.6', study_dicom_id='1.2.3', to_modality_aet='ORTHANCA')
@@ -459,7 +458,7 @@ def test_modalities_move(self):
 
         #request A to move it from B to A (retrieve)
         self.oa.modalities.move_study(from_modality='orthanc-b', dicom_id='1.2.3')
-        self.assertIsNotNone(1, self.oa.studies.lookup('1.2.3'))
+        self.assertIsNotNone(self.oa.studies.lookup('1.2.3'))
         self.oa.delete_all_content()
 
         self.oa.modalities.move_series(from_modality='orthanc-b', dicom_id='4.5.6', study_dicom_id='1.2.3')
@@ -470,9 +469,28 @@ def test_modalities_move(self):
         self.assertIsNotNone(self.oa.instances.lookup('7.8.9'))
         self.oa.delete_all_content()
 
+        # move async
+        job = self.oa.modalities.move_study_async(from_modality='orthanc-b', dicom_id='1.2.3')
+        job.wait_completed()
+        self.assertEqual(JobStatus.SUCCESS, job.info.status)
+        self.assertIsNotNone(self.oa.studies.lookup('1.2.3'))
+        self.oa.delete_all_content()
+
+        # move async (study that does not exists)
+        job = self.oa.modalities.move_study_async(from_modality='orthanc-b', dicom_id='10.20.30')
+        job.wait_completed()
+        if self.oa.is_orthanc_version_at_least(1, 12, 10):
+            self.assertEqual(JobStatus.FAILURE, job.info.status)
+            # not validated yet
+            # self.assertIsNotNone(job.info.dimseErrorStatus)
+            # self.assertEqual(0xC000, job.info.dimseErrorStatus)
+        self.assertIsNone(self.oa.studies.lookup('10.20.30'))
+        self.oa.delete_all_content()
+
+
         #request A to get it from B
         self.oa.modalities.get_study(from_modality='orthanc-b', dicom_id='1.2.3')
-        self.assertIsNotNone(1, self.oa.studies.lookup('1.2.3'))
+        self.assertIsNotNone(self.oa.studies.lookup('1.2.3'))
         self.oa.delete_all_content()
 
         self.oa.modalities.get_series(from_modality='orthanc-b', dicom_id='4.5.6', study_dicom_id='1.2.3')
@@ -483,9 +501,26 @@ def test_modalities_move(self):
         self.assertIsNotNone(self.oa.instances.lookup('7.8.9'))
         self.oa.delete_all_content()
 
+        # get async
+        job = self.oa.modalities.get_study_async(from_modality='orthanc-b', dicom_id='1.2.3')
+        job.wait_completed()
+        self.assertEqual(JobStatus.SUCCESS, job.info.status)
+        self.assertIsNotNone(self.oa.studies.lookup('1.2.3'))
+        self.oa.delete_all_content()
+
+        # get async (study that does not exists)
+        job = self.oa.modalities.get_study_async(from_modality='orthanc-b', dicom_id='10.20.30')
+        job.wait_completed()
+        if self.oa.is_orthanc_version_at_least(1, 12, 10):
+            self.assertEqual(JobStatus.FAILURE, job.info.status)
+            self.assertIsNotNone(job.info.dimseErrorStatus)
+            self.assertEqual(0xC000, job.info.dimseErrorStatus)
+        self.assertIsNone(self.oa.studies.lookup('10.20.30'))
+        self.oa.delete_all_content()
+
         #request A to get it from B
         self.oa.modalities.retrieve_study(from_modality='orthanc-b', dicom_id='1.2.3', retrieve_method=RetrieveMethod.GET)
-        self.assertIsNotNone(1, self.oa.studies.lookup('1.2.3'))
+        self.assertIsNotNone(self.oa.studies.lookup('1.2.3'))
         self.oa.delete_all_content()