diff --git a/docs/source/en/package_reference/utilities.md b/docs/source/en/package_reference/utilities.md index 61f2dd1cfb0..10eb648d1d9 100644 --- a/docs/source/en/package_reference/utilities.md +++ b/docs/source/en/package_reference/utilities.md @@ -122,11 +122,9 @@ You can also enable or disable progress bars for specific groups. This allows yo ## Configuring the HTTP Backend - +> [!TIP] +> In `huggingface_hub` v0.x, HTTP requests were handled with `requests`, and configuration was done via `configure_http_backend`. Since we now use `httpx`, configuration works differently: you must provide a factory function that takes no arguments and returns an `httpx.Client`. You can review the [default implementation here](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py) to see which parameters are used by default. -In `huggingface_hub` v0.x, HTTP requests were handled with `requests`, and configuration was done via `configure_http_backend`. Since we now use `httpx`, configuration works differently: you must provide a factory function that takes no arguments and returns an `httpx.Client`. You can review the [default implementation here](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py) to see which parameters are used by default. - - In some setups, you may need to control how HTTP requests are made, for example when working behind a proxy. The `huggingface_hub` library allows you to configure this globally with [`set_client_factory`]. After configuration, all requests to the Hub will use your custom settings. Since `huggingface_hub` relies on `httpx.Client` under the hood, you can check the [`httpx` documentation](https://www.python-httpx.org/advanced/clients/) for details on available parameters. @@ -149,11 +147,27 @@ For async code, use [`set_async_client_factory`] to configure an `httpx.AsyncCli [[autodoc]] get_async_session - +> [!TIP] +> Unlike the synchronous client, the lifecycle of the async client is not managed automatically. Use an async context manager to handle it properly. + +### The `httpx` module + +`huggingface_hub` re-exports the HTTP library it uses under the hood as `huggingface_hub.utils.httpx`: + +```py +from huggingface_hub.utils import httpx + +try: + ... +except httpx.HTTPError: + ... +``` + +This is mostly useful for third-party libraries built on top of `huggingface_hub`. `huggingface_hub` v1.x is built on [`httpx`](https://www.python-httpx.org/), while v2.x will be built on [`httpx2`](https://httpx2.pydantic.dev/) (its successor, distributed as a separate package). Importing the module from `huggingface_hub.utils` instead of importing `httpx` directly means you always get the version that `huggingface_hub` actually uses, and your library stays compatible with both major versions. See [this issue](https://github.com/huggingface/huggingface_hub/issues/4802) for more details about the migration plan. -Unlike the synchronous client, the lifecycle of the async client is not managed automatically. Use an async context manager to handle it properly. +> [!WARNING] +> Only use this if you need `httpx` types or exceptions (e.g. to catch errors). To make requests to the Hub, use [`get_session`] as described above. - ## Handle HTTP errors diff --git a/src/huggingface_hub/utils/__init__.py b/src/huggingface_hub/utils/__init__.py index d9b96202748..4e4274d1862 100644 --- a/src/huggingface_hub/utils/__init__.py +++ b/src/huggingface_hub/utils/__init__.py @@ -13,6 +13,8 @@ # limitations under the License # ruff: noqa: F401 +import httpx # for forward compatibility - will be httpx2 in huggingface_hub v2.x + from huggingface_hub.errors import ( BadRequestError, BucketNotFoundError,