Add offline mode helper

Author: Wauplin

docs/source/en/package_reference/utilities.md

@@ -184,6 +184,12 @@ except HfHubHTTPError as e:
 
 [[autodoc]] huggingface_hub.utils.hf_raise_for_status
 
+### Check offline mode
+
+You can programmatically check if offline mode is enabled using `offline_mode`. Offline mode is enabled by setting `HF_HUB_OFFLINE=1` as environment variable.
+
+[[autodoc]] offline_mode
+
 ### HTTP errors
 
 Here is a list of HTTP errors thrown in `huggingface_hub`.

src/huggingface_hub/__init__.py

@@ -134,6 +134,7 @@
         "REPO_TYPE_SPACE",
         "TF2_WEIGHTS_NAME",
         "TF_WEIGHTS_NAME",
+        "offline_mode",
     ],
     "fastai_utils": [
         "_save_pretrained_fastai",
@@ -930,6 +931,7 @@
     "model_info",
     "move_repo",
     "notebook_login",
+    "offline_mode",
     "paper_info",
     "parse_huggingface_oauth",
     "parse_safetensors_file_metadata",
@@ -1158,6 +1160,7 @@ def __dir__():
         REPO_TYPE_SPACE,  # noqa: F401
         TF2_WEIGHTS_NAME,  # noqa: F401
         TF_WEIGHTS_NAME,  # noqa: F401
+        offline_mode,  # noqa: F401
     )
     from .fastai_utils import (
         _save_pretrained_fastai,  # noqa: F401

src/huggingface_hub/constants.py

@@ -162,6 +162,15 @@ def _as_int(value: Optional[str]) -> Optional[int]:
 
 HF_HUB_OFFLINE = _is_true(os.environ.get("HF_HUB_OFFLINE") or os.environ.get("TRANSFORMERS_OFFLINE"))
 
+
+def offline_mode() -> bool:
+    """Returns whether we are in offline mode for the Hub.
+
+    When offline mode is enabled, all HTTP requests made with `get_session` will raise an `OfflineModeIsEnabled` exception.
+    """
+    return HF_HUB_OFFLINE
+
+
 # File created to mark that the version check has been done.
 # Check is performed once per 24 hours at most.
 CHECK_FOR_UPDATE_DONE_PATH = os.path.join(HF_HOME, ".check_for_update_done")

src/huggingface_hub/utils/_http.py

@@ -167,7 +167,7 @@ def hf_request_event_hook(request: httpx.Request) -> None:
     - Add a request ID to the request headers
     - Log the request if debug mode is enabled
     """
-    if constants.HF_HUB_OFFLINE:
+    if constants.offline_mode():
         raise OfflineModeIsEnabled(
             f"Cannot reach {request.url}: offline mode is enabled. To disable it, please unset the `HF_HUB_OFFLINE` environment variable."
         )

src/huggingface_hub/utils/_telemetry.py

@@ -64,7 +64,7 @@ def send_telemetry(
     ... )
     ```
     """
-    if constants.HF_HUB_OFFLINE or constants.HF_HUB_DISABLE_TELEMETRY:
+    if constants.offline_mode() or constants.HF_HUB_DISABLE_TELEMETRY:
         return
 
     _start_telemetry_thread()  # starts thread only if doesn't exist yet