Add offline_mode helper (#3593)

* Add offline mode helper

* add example

Author: Wauplin

docs/source/en/package_reference/environment_variables.md

@@ -119,10 +119,12 @@ If set, the log level for the `huggingface_hub` logger is set to DEBUG. Addition
 
 If set, no HTTP calls will be made to the Hugging Face Hub. If you try to download files, only the cached files will be accessed. If no cache file is detected, an error is raised This is useful in case your network is slow and you don't care about having the latest version of a file.
 
-If `HF_HUB_OFFLINE=1` is set as environment variable and you call any method of [`HfApi`], an [`~huggingface_hub.utils.OfflineModeIsEnabled`] exception will be raised.
+If `HF_HUB_OFFLINE=1` is set as environment variable and you call any method of [`HfApi`], an [`~huggingface_hub.errors.OfflineModeIsEnabled`] exception will be raised.
 
 **Note:** even if the latest version of a file is cached, calling `hf_hub_download` still triggers a HTTP request to check that a new version is not available. Setting `HF_HUB_OFFLINE=1` will skip this call which speeds up your loading time.
 
+If you want to check if offline mode is enabled or not, you can use the [`offline_mode`] helper.
+
 ### HF_HUB_DISABLE_IMPLICIT_TOKEN
 
 Authentication is not mandatory for every request to the Hub. For instance, requesting

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,26 @@ 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.
+
+    Example:
+        ```py
+        from huggingface_hub import offline_mode
+
+        def list_files(repo_id: str):
+            if offline_mode():
+                ... # list files from local cache (degraded experience but still functional)
+            else:
+                ... # list files from Hub (complete experience)
+        ```
+    """
+    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