adding optional params to search and retrieve functions

Author: chinacat567

src/dicomweb_client/web.py

@@ -1628,7 +1628,8 @@ def search_for_studies(
         offset: Optional[int] = None,
         fields: Optional[Sequence[str]] = None,
         search_filters: Optional[Dict[str, Any]] = None,
-        get_remaining: bool = False
+        get_remaining: bool = False,
+        additional_params: Optional[Dict[str, Any]] = None
     ) -> List[Dict[str, dict]]:
         """Search for studies.
 
@@ -1649,19 +1650,23 @@ def search_for_studies(
         get_remaining: bool, optional
             Whether remaining results should be included (this may repeatedly
             query the server for remaining results)
+        additional_params: Union[Dict[str, Any], None], optional
+            Additional HTTP GET query parameters to include in the request.
 
         Returns
         -------
         List[Dict[str, dict]]
             Study representations
             (see `Study Result Attributes <http://dicom.nema.org/medical/dicom/current/output/chtml/part18/sect_6.7.html#table_6.7.1-2>`_)
 
-        Note
+        Notes
         ----
-        The server may only return a subset of search results. In this case,
+        - The server may only return a subset of search results. In this case,
         a warning will notify the client that there are remaining results.
         Remaining results can be requested via repeated calls using the
         `offset` parameter.
+        - If `additional_params` is provided, it will be merged into the standard query parameters,
+        with its values overwriting any existing keys if duplicates are present.
 
         """  # noqa: E501: E501
         logger.info('search for studies')
@@ -1673,6 +1678,8 @@ def search_for_studies(
             fields=fields,
             search_filters=search_filters
         )
+        if additional_params:
+            params.update(additional_params)
         return self._http_get_application_json(
             url,
             params=params,
@@ -1918,7 +1925,8 @@ def _get_study(
         self,
         study_instance_uid: str,
         media_types: Optional[Tuple[Union[str, Tuple[str, str]], ...]] = None,
-        stream: bool = False
+        stream: bool = False,
+        params: Optional[Dict[str, Any]] = None
     ) -> Iterator[pydicom.dataset.Dataset]:
         """Get all instances of a study.
 
@@ -1932,6 +1940,8 @@ def _get_study(
         stream: bool, optional
             Whether data should be streamed (i.e., requested using chunked
             transfer encoding)
+        params: Union[Dict[str, Any], None], optional
+            Additional HTTP GET query parameters
 
         Returns
         -------
@@ -1947,6 +1957,7 @@ def _get_study(
         if media_types is None:
             return self._http_get_multipart_application_dicom(
                 url,
+                params=params,
                 stream=stream
             )
         common_media_types = self._get_common_media_types(media_types)
@@ -1964,6 +1975,7 @@ def _get_study(
         return self._http_get_multipart_application_dicom(
             url,
             media_types=media_types,
+            params=params,
             stream=stream
         )
 
@@ -2129,7 +2141,8 @@ def search_for_series(
         offset: Optional[int] = None,
         fields: Optional[Sequence[str]] = None,
         search_filters: Optional[Dict[str, Any]] = None,
-        get_remaining: bool = False
+        get_remaining: bool = False,
+        additional_params: Optional[Dict[str, Any]] = None
     ) -> List[Dict[str, dict]]:
         """Search for series.
 
@@ -2152,19 +2165,23 @@ def search_for_series(
         get_remaining: bool, optional
             Whether remaining results should be included (this may repeatedly
             query the server for remaining results)
+        additional_params: Union[Dict[str, Any], None], optional
+            Additional HTTP GET query parameters to include in the request.
 
         Returns
         -------
         List[Dict[str, dict]]
             Series representations
             (see `Series Result Attributes <http://dicom.nema.org/medical/dicom/current/output/chtml/part18/sect_6.7.html#table_6.7.1-2a>`_)
 
-        Note
+        Notes
         ----
-        The server may only return a subset of search results. In this case,
+        - The server may only return a subset of search results. In this case,
         a warning will notify the client that there are remaining results.
         Remaining results can be requested via repeated calls using the
         `offset` parameter.
+        - If `additional_params` is provided, it will be merged into the standard query parameters,
+        with its values overwriting any existing keys if duplicates are present.
 
         """  # noqa: E501
         if study_instance_uid is not None:
@@ -2180,6 +2197,8 @@ def search_for_series(
             fields=fields,
             search_filters=search_filters
         )
+        if additional_params:
+            params.update(additional_params)
         return self._http_get_application_json(
             url,
             params=params,
@@ -2191,7 +2210,8 @@ def _get_series(
         study_instance_uid: str,
         series_instance_uid: str,
         media_types: Optional[Tuple[Union[str, Tuple[str, str]], ...]] = None,
-        stream: bool = False
+        stream: bool = False,
+        params: Optional[Dict[str, Any]] = None
     ) -> Iterator[pydicom.dataset.Dataset]:
         """Get instances of a series.
 
@@ -2207,6 +2227,8 @@ def _get_series(
         stream: bool, optional
             Whether data should be streamed (i.e., requested using chunked
             transfer encoding)
+        params: Union[Dict[str, Any], None], optional
+            Additional HTTP GET query parameters
 
         Returns
         -------
@@ -2236,6 +2258,7 @@ def _get_series(
         if media_types is None:
             return self._http_get_multipart_application_dicom(
                 url,
+                params=params,
                 stream=stream
             )
         common_media_types = self._get_common_media_types(media_types)
@@ -2253,6 +2276,7 @@ def _get_series(
         return self._http_get_multipart_application_dicom(
             url,
             media_types=media_types,
+            params=params,
             stream=stream
         )
 
@@ -2514,7 +2538,8 @@ def search_for_instances(
         offset: Optional[int] = None,
         fields: Optional[Sequence[str]] = None,
         search_filters: Optional[Dict[str, Any]] = None,
-        get_remaining: bool = False
+        get_remaining: bool = False,
+        additional_params: Optional[Dict[str, Any]] = None
     ) -> List[Dict[str, dict]]:
         """Search for instances.
 
@@ -2539,6 +2564,8 @@ def search_for_instances(
         get_remaining: bool, optional
             Whether remaining results should be included (this may repeatedly
             query the server for remaining results)
+        additional_params: Union[Dict[str, Any], None], optional
+            Additional HTTP GET query parameters to include in the request.
 
         Returns
         -------
@@ -2548,10 +2575,12 @@ def search_for_instances(
 
         Note
         ----
-        The server may only return a subset of search results. In this case,
+        - The server may only return a subset of search results. In this case,
         a warning will notify the client that there are remaining results.
         Remaining results can be requested via repeated calls using the
         `offset` parameter.
+        - If `additional_params` is provided, it will be merged into the standard query parameters,
+        with its values overwriting any existing keys if duplicates are present.
 
         """  # noqa: E501
         message = 'search for instances'
@@ -2585,6 +2614,7 @@ def retrieve_instance(
         series_instance_uid: str,
         sop_instance_uid: str,
         media_types: Optional[Tuple[Union[str, Tuple[str, str]], ...]] = None,
+        params: Optional[Dict[str, Any]] = None
     ) -> pydicom.dataset.Dataset:
         """Retrieve an individual instance.
 
@@ -2599,6 +2629,8 @@ def retrieve_instance(
         media_types: Union[Tuple[Union[str, Tuple[str, str]], ...], None], optional
             Acceptable media types and optionally the UIDs of the
             acceptable transfer syntaxes
+        params: Union[Dict[str, Any], None], optional
+            Additional HTTP GET query parameters
 
         Returns
         -------
@@ -2657,7 +2689,11 @@ def retrieve_instance(
                 f'Media type "{common_media_type}" is not supported for '
                 'retrieval of an instance. It must be "application/dicom".'
             )
-        iterator = self._http_get_multipart_application_dicom(url, media_types)
+        iterator = self._http_get_multipart_application_dicom(
+            url,
+            media_types=media_types,
+            params=params
+        )
         instances = list(iterator)
         if len(instances) > 1:
             # This should not occur, but safety first.