Warn on server warning 'X-HF-Warning' (#3589)

* Warn on server warning 'X-HF-Warning'

* add awrn

Author: Wauplin

src/huggingface_hub/utils/_cache_assets.py

@@ -24,7 +24,7 @@ def cached_assets_path(
     subfolder: str = "default",
     *,
     assets_dir: Union[str, Path, None] = None,
-):
+) -> Path:
     """Return a folder path to cache arbitrary files.
 
     `huggingface_hub` provides a canonical folder path to store assets. This is the

src/huggingface_hub/utils/_http.py

@@ -647,6 +647,12 @@ def hf_raise_for_status(response: httpx.Response, endpoint_name: Optional[str] =
     >     - [`~utils.HfHubHTTPError`]
     >         If request failed for a reason not listed above.
     """
+    try:
+        _warn_on_warning_headers(response)
+    except Exception:
+        # Never raise on warning parsing
+        logger.debug("Failed to parse warning headers", exc_info=True)
+
     try:
         response.raise_for_status()
     except httpx.HTTPStatusError as e:
@@ -746,6 +752,33 @@ def hf_raise_for_status(response: httpx.Response, endpoint_name: Optional[str] =
         raise _format(HfHubHTTPError, str(e), response) from e
 
 
+_WARNED_TOPICS = set()
+
+
+def _warn_on_warning_headers(response: httpx.Response) -> None:
+    """
+    Emit warnings if warning headers are present in the HTTP response.
+
+    Expected header format: 'X-HF-Warning: topic; message'
+
+    Only the first warning for each topic will be shown. Topic is optional and can be empty. Note that several warning
+    headers can be present in a single response.
+
+    Args:
+        response (`httpx.Response`):
+            The HTTP response to check for warning headers.
+    """
+    server_warnings = response.headers.get_list("X-HF-Warning")
+    for server_warning in server_warnings:
+        topic, message = server_warning.split(";", 1) if ";" in server_warning else ("", server_warning)
+        topic = topic.strip()
+        if topic not in _WARNED_TOPICS:
+            message = message.strip()
+            if message:
+                _WARNED_TOPICS.add(topic)
+                logger.warning("WARNING: %s", message)
+
+
 def _format(error_type: type[HfHubHTTPError], custom_message: str, response: httpx.Response) -> HfHubHTTPError:
     server_errors = []
 

tests/test_utils_http.py

@@ -14,8 +14,10 @@
 from huggingface_hub.constants import ENDPOINT
 from huggingface_hub.errors import HfHubHTTPError, OfflineModeIsEnabled
 from huggingface_hub.utils._http import (
+    _WARNED_TOPICS,
     RateLimitInfo,
     _adjust_range_header,
+    _warn_on_warning_headers,
     default_client_factory,
     fix_hf_endpoint_in_url,
     get_async_session,
@@ -560,3 +562,45 @@ def test_429_without_ratelimit_headers(self):
 
         assert "429 Too Many Requests" in str(exc_info.value)
         assert "api/models" in str(exc_info.value)
+
+
+class TestWarnOnWarningHeaders:
+    def test_warn_on_warning_headers(self, caplog):
+        # Request #1 (multiple warnings)
+        response = Mock(spec=httpx.Response)
+        response.headers = httpx.Headers(
+            [
+                ("X-HF-Warning", "Topic1; This is the first warning message."),
+                ("X-HF-Warning", "Topic2; This is the second warning message."),
+                ("X-HF-Warning", "Topic1; This is a repeated warning message for Topic1."),
+                ("X-HF-Warning", "This is a warning without a topic."),
+                ("X-HF-Warning", "This is another warning without a topic."),
+            ]
+        )
+
+        with caplog.at_level("WARNING"):
+            _warn_on_warning_headers(response)
+
+        assert _WARNED_TOPICS == {"Topic1", "Topic2", ""}
+        warnings = [record.message for record in caplog.records if record.levelname == "WARNING"]
+        assert "WARNING: This is the first warning message." in warnings
+        assert "WARNING: This is the second warning message." in warnings
+        assert "WARNING: This is a repeated warning message for Topic1." not in warnings
+        assert "WARNING: This is a warning without a topic." in warnings
+        assert "WARNING: This is another warning without a topic." not in warnings
+        # Request #2 (exact same warnings, should not warn again)
+        caplog.clear()
+        with caplog.at_level("WARNING"):
+            _warn_on_warning_headers(response)
+        warnings = [record.message for record in caplog.records if record.levelname == "WARNING"]
+        assert len(warnings) == 0  # No new warnings should be added
+
+        # Request #3 (single warning with new topic, should warn)
+        response.headers = httpx.Headers({"X-HF-Warning": "Topic4; Another warning."})
+        caplog.clear()
+        with caplog.at_level("WARNING"):
+            _warn_on_warning_headers(response)
+        warnings = [record.message for record in caplog.records if record.levelname == "WARNING"]
+        assert len(warnings) == 1
+        assert warnings == ["WARNING: Another warning."]
+        assert "Topic4" in _WARNED_TOPICS