ADD: Client library support for backend warnings

Author: nmacholl

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Changed `Live` callbacks to no longer yield DBN metadata
 - Added `metadata` property to `Live`
 - Added `DatatbentoLiveProtocol` class
+- Added support for emitting warnings in API response headers
 - Upgraded `aiohttp` to 3.8.3
 - Upgraded `numpy` to to 1.23.5
 - Upgraded `pandas` to to 1.5.3

databento/common/error.py

@@ -103,3 +103,8 @@ class BentoWarning(Warning):
     """
     Represents a Databento specific warning.
     """
+
+class BentoDeprecationWarning(BentoWarning):
+    """
+    Represents a Databento deprecation warning.
+    """

databento/historical/http.py

@@ -1,18 +1,26 @@
+import json
 import sys
+import warnings
 from io import BufferedIOBase
 from json.decoder import JSONDecodeError
-from typing import Any, List, Optional, Tuple
+from typing import Any, List, Optional, Tuple, Union
 
 import aiohttp
 import requests
-from aiohttp import ClientResponse, ContentTypeError
-from databento.common.error import BentoClientError, BentoServerError
-from databento.version import __version__
+from aiohttp import ClientResponse
+from aiohttp import ContentTypeError
 from requests import Response
 from requests.auth import HTTPBasicAuth
 
+from databento.common.error import BentoClientError
+from databento.common.error import BentoDeprecationWarning
+from databento.common.error import BentoServerError
+from databento.common.error import BentoWarning
+from databento.version import __version__
+
 
 _32KB = 1024 * 32  # 32_768
+WARNING_HEADER_FIELD: str = "X-Warning"
 
 
 class BentoHttpAPI:
@@ -51,6 +59,7 @@ def _get(
             auth=HTTPBasicAuth(username=self._key, password="") if basic_auth else None,
             timeout=(self.TIMEOUT, self.TIMEOUT),
         ) as response:
+            check_backend_warnings(response)
             check_http_error(response)
             return response
 
@@ -71,6 +80,7 @@ async def _get_json_async(
                 else None,
                 timeout=self.TIMEOUT,
             ) as response:
+                check_backend_warnings(response)
                 await check_http_error_async(response)
                 return await response.json()
 
@@ -89,6 +99,7 @@ def _post(
             auth=HTTPBasicAuth(username=self._key, password="") if basic_auth else None,
             timeout=(self.TIMEOUT, self.TIMEOUT),
         ) as response:
+            check_backend_warnings(response)
             check_http_error(response)
             return response
 
@@ -109,6 +120,7 @@ def _stream(
             timeout=(self.TIMEOUT, self.TIMEOUT),
             stream=True,
         ) as response:
+            check_backend_warnings(response)
             check_http_error(response)
 
             for chunk in response.iter_content(chunk_size=_32KB):
@@ -133,6 +145,7 @@ async def _stream_async(
                 else None,
                 timeout=self.TIMEOUT,
             ) as response:
+                check_backend_warnings(response)
                 await check_http_error_async(response)
 
                 async for chunk in response.content.iter_chunks():
@@ -147,6 +160,24 @@ def is_500_series_error(status: int) -> bool:
     return status // 100 == 5
 
 
+def check_backend_warnings(response: Union[Response, ClientResponse]) -> None:
+    if WARNING_HEADER_FIELD not in response.headers:  # type: ignore [arg-type]
+        return
+
+    backend_warnings = json.loads(
+        response.headers[WARNING_HEADER_FIELD],  # type: ignore [arg-type]
+    )
+
+    for bw in backend_warnings:
+        type_, _, message = bw.partition(": ")
+        if type_ == "DeprecationWarning":
+            category = BentoDeprecationWarning
+        else:
+            category = BentoWarning  # type: ignore [assignment]
+
+        warnings.warn(message, category=category, stacklevel=4)
+
+
 def check_http_error(response: Response) -> None:
     if is_500_series_error(response.status_code):
         try:

tests/test_historical_warnings.py

@@ -0,0 +1,78 @@
+import json
+
+import pytest
+from databento.historical.http import check_backend_warnings
+from requests import Response
+
+
+@pytest.mark.parametrize(
+    "header_field",
+    [
+        "X-Warning",
+        "x-warning",
+    ],
+)
+@pytest.mark.parametrize(
+    "category, message, expected_category",
+    [
+        pytest.param("Warning", "this is a test", "BentoWarning"),
+        pytest.param(
+            "DeprecationWarning",
+            "you're too old!",
+            "BentoDeprecationWarning",
+        ),
+        pytest.param("Warning", "edge: case", "BentoWarning"),
+        pytest.param("UnknownWarning", "", "BentoWarning"),
+    ],
+)
+def test_backend_warning(
+    header_field: str,
+    category: str,
+    message: str,
+    expected_category: str,
+) -> None:
+    """
+    Test that a backend warning in a response header is correctly
+    parsed as a type of BentoWarning.
+    """
+    response = Response()
+    expected = f'["{category}: {message}"]'
+    response.headers[header_field] = expected
+
+    with pytest.warns() as warnings:
+        check_backend_warnings(response)
+
+    assert len(warnings) == 1
+    assert warnings.list[0].category.__name__ == expected_category
+    assert str(warnings.list[0].message) == message
+
+
+@pytest.mark.parametrize(
+    "header_field",
+    [
+        "X-Warning",
+        "x-warning",
+    ],
+)
+def test_multiple_backend_warning(
+    header_field: str,
+) -> None:
+    """
+    Test that multiple backend warnings in a response header are
+    supported.
+    """
+    response = Response()
+    backend_warnings = [
+        "Warning: this is a test",
+        "DeprecationWarning: you're too old!",
+    ]
+    response.headers[header_field] = json.dumps(backend_warnings)
+
+    with pytest.warns() as warnings:
+        check_backend_warnings(response)
+
+    assert len(warnings) == len(backend_warnings)
+    assert warnings.list[0].category.__name__ == "BentoWarning"
+    assert str(warnings.list[0].message) == "this is a test"
+    assert warnings.list[1].category.__name__ == "BentoDeprecationWarning"
+    assert str(warnings.list[1].message) == "you're too old!"