Handle warning headers for remaining quido results

A server may limit the number of search results that it returns for each
search request. In this case, it will include a warning header to inform
the client that there are remaining results.

docs/usage.rst

@@ -86,6 +86,28 @@ Note that attributes can be specified in ``search_filters`` using either the key
 
     studies = client.search_for_studies(search_filters={'00100020': 'ABC123'})
 
+Search for all studies but limit the number of returned results using the ``limit`` parameter.
+
+.. code-block:: python
+
+    studies_subset = client.search_for_studies(limit=100)
+
+A server may also automatically limit the number of results that it returns per search request.
+In this case, the method can be called repeatedly to request remaining results using the ``offset`` parameter.
+
+.. code-block:: python
+
+    studies = client.search_for_studies()
+    batch_size = len(studies)
+    count = 1
+    while True:
+        offset = batch_size * count
+        try:
+            subset = client.search_for_studies(offset=offset)
+        except requests.exceptions.HTTPError:
+            break
+        studies.extend(subset)
+        count += 1
 
 .. _searchforseries:
 

src/dicomweb_client/api.py

@@ -413,6 +413,11 @@ def _http_get(self, url, params, headers):
         logger.debug('GET: {}'.format(url))
         response = self._session.get(url=url, headers=headers)
         response.raise_for_status()
+        # The server may not return all results, but rather include a warning
+        # header to notify that client that there are remaining results.
+        # (see DICOM Part 3.18 Section 6.7.1.2)
+        if 'Warning' in response.headers:
+            logger.warn(response.headers['Warning'])
         return response
 
     def _http_get_application_json(self, url, **params):
@@ -665,7 +670,14 @@ def search_for_studies(self, fuzzymatching=None, limit=None, offset=None,
         -------
         List[Dict[str, dict]]
             study representations
-            (see `returned attributes <http://dicom.nema.org/medical/dicom/current/output/chtml/part18/sect_6.7.html#table_6.7.1-2>`_)
+            (see `Study Result Attributes <http://dicom.nema.org/medical/dicom/current/output/chtml/part18/sect_6.7.html#table_6.7.1-2>`_)
+
+        Note
+        ----
+        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.
 
         ''' # noqa
         url = self._get_studies_url('qido')
@@ -801,7 +813,14 @@ def search_for_series(self, study_instance_uid=None, fuzzymatching=None,
         -------
         List[Dict[str, dict]]
             series representations
-            (see `returned attributes <http://dicom.nema.org/medical/dicom/current/output/chtml/part18/sect_6.7.html#table_6.7.1-2a>`_)
+            (see `Series Result Attributes <http://dicom.nema.org/medical/dicom/current/output/chtml/part18/sect_6.7.html#table_6.7.1-2a>`_)
+
+        Note
+        ----
+        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.
 
         ''' # noqa
         if study_instance_uid is not None:
@@ -911,7 +930,14 @@ def search_for_instances(self, study_instance_uid=None,
         -------
         List[Dict[str, dict]]
             instance representations
-            (see `returned attributes <http://dicom.nema.org/medical/dicom/current/output/chtml/part18/sect_6.7.html#table_6.7.1-2b>`_)
+            (see `Instance Result Attributes <http://dicom.nema.org/medical/dicom/current/output/chtml/part18/sect_6.7.html#table_6.7.1-2b>`_)
+
+        Note
+        ----
+        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.
 
         ''' # noqa
         if study_instance_uid is not None: