refactor: Rename the HTTPX extra and clients to httpx2 (#1048)

Renames the optional extra `httpx` to `httpx2`, and `HttpxHttpClient` /
`HttpxHttpClientAsync` to `Httpx2HttpClient` / `Httpx2HttpClientAsync`,
along with the private module, the docs examples, and the test ids. Once
httpx releases 1.0 with a new API, an extra named `httpx` that installs
`httpx2` would confuse users (see
#1046 (comment)).

Neither name has shipped in a stable release, so nothing is breaking.
Kept as is: the `import httpx2 as httpx` alias inside the module,
"HTTPX" as the library name in prose, and the historical v2 upgrade
note.

Follows up on #1046.

*✍️ Drafted by Claude Code*

Author: vdusek

.rules.md

@@ -63,7 +63,7 @@ Docstrings are written on sync clients and **automatically copied** to async cli
 - `HttpClient`/`HttpClientAsync` — base classes in `http_clients/_base.py` holding the shared request pipeline (retries,
   timeouts, API errors); transports implement the `send_request`, error-classification, and lifecycle hooks
 - `ImpitHttpClient`/`ImpitHttpClientAsync` — default implementation (Rust-based Impit)
-- `HttpxHttpClient`/`HttpxHttpClientAsync` — built-in alternative behind the `httpx` optional extra
+- `Httpx2HttpClient`/`Httpx2HttpClientAsync` — built-in alternative behind the `httpx2` optional extra
 - `HttpResponse` — Protocol (not a concrete class) for response objects
 - Users can plug in custom HTTP clients via `ApifyClient.with_custom_http_client()`
 

README.md

@@ -58,14 +58,14 @@
     ```
 
     [Impit](https://github.com/apify/impit) is the default HTTP client and is installed automatically. To use the
-    built-in [HTTPX](https://github.com/pydantic/httpx2) client instead, install its optional extra and pass
-    `http_client=HttpxHttpClient()` to `ApifyClient.with_custom_http_client()`. The extra installs `httpx2`,
-    Pydantic's maintained continuation of HTTPX:
+    built-in [HTTPX](https://github.com/pydantic/httpx2) client instead, install the optional `httpx2` extra, which
+    provides Pydantic's maintained continuation of HTTPX, and pass `http_client=Httpx2HttpClient()` to
+    `ApifyClient.with_custom_http_client()`:
 
     ```bash
-    pip install "apify-client[httpx]"
+    pip install "apify-client[httpx2]"
     # or
-    uv add "apify-client[httpx]"
+    uv add "apify-client[httpx2]"
     ```
 
 - From [conda-forge](https://anaconda.org/conda-forge/apify-client), it can be installed with [conda](https://docs.conda.io/en/latest/):

docs/01_introduction/index.mdx

@@ -63,12 +63,12 @@ For better request-body compression, opt in to `brotli`, which compresses better
 
 For details, see [HTTP compression](../02_concepts/13_http_compression.mdx).
 
-The client uses [Impit](https://github.com/apify/impit) as its default HTTP transport. To use the built-in [HTTPX](https://github.com/pydantic/httpx2) transport, install the optional `httpx` extra. The extra installs `httpx2`, Pydantic's maintained continuation of HTTPX:
+The client uses [Impit](https://github.com/apify/impit) as its default HTTP transport. To use the built-in [HTTPX](https://github.com/pydantic/httpx2) transport, install the optional `httpx2` extra, which provides Pydantic's maintained continuation of HTTPX:
 
 <Tabs>
     <TabItem value="PyPI" label="PyPI" default>
         ```bash
-        pip install "apify-client[httpx]"
+        pip install "apify-client[httpx2]"
         ```
     </TabItem>
     <TabItem value="conda-forge" label="conda-forge">

docs/02_concepts/10_custom_http_clients.mdx

@@ -11,8 +11,8 @@ import ApiLink from '@theme/ApiLink';
 
 import DefaultHttpClientAsyncExample from '!!raw-loader!./code/10_default_http_client_async.py';
 import DefaultHttpClientSyncExample from '!!raw-loader!./code/10_default_http_client_sync.py';
-import HttpxHttpClientAsyncExample from '!!raw-loader!./code/10_httpx_client_async.py';
-import HttpxHttpClientSyncExample from '!!raw-loader!./code/10_httpx_client_sync.py';
+import Httpx2HttpClientAsyncExample from '!!raw-loader!./code/10_httpx2_client_async.py';
+import Httpx2HttpClientSyncExample from '!!raw-loader!./code/10_httpx2_client_sync.py';
 
 import ArchitectureImportsExample from '!!raw-loader!./code/10_architecture_imports.py';
 
@@ -47,30 +47,30 @@ You can configure the default client through the <ApiLink to="class/ApifyClient"
 
 ## Built-in HTTPX client
 
-The package also provides <ApiLink to="class/HttpxHttpClient">`HttpxHttpClient`</ApiLink> and <ApiLink to="class/HttpxHttpClientAsync">`HttpxHttpClientAsync`</ApiLink>. They use the same request preparation, compression, retry policy, timeout tiers and growth, error handling, logging, and statistics as the default Impit clients, with [HTTPX](https://github.com/pydantic/httpx2) as the transport.
+The package also provides <ApiLink to="class/Httpx2HttpClient">`Httpx2HttpClient`</ApiLink> and <ApiLink to="class/Httpx2HttpClientAsync">`Httpx2HttpClientAsync`</ApiLink>. They use the same request preparation, compression, retry policy, timeout tiers and growth, error handling, logging, and statistics as the default Impit clients, with [HTTPX](https://github.com/pydantic/httpx2) as the transport.
 
-HTTPX is an optional dependency. Install `apify-client[httpx]`, then pass the appropriate client to <ApiLink to="class/ApifyClient#with_custom_http_client">`ApifyClient.with_custom_http_client`</ApiLink>. The extra installs `httpx2`, Pydantic's maintained continuation of HTTPX. Impit remains the default even when the HTTPX extra is installed.
+HTTPX is an optional dependency provided by the `httpx2` package, Pydantic's maintained continuation of HTTPX. Install `apify-client[httpx2]`, then pass the appropriate client to <ApiLink to="class/ApifyClient#with_custom_http_client">`ApifyClient.with_custom_http_client`</ApiLink>. Impit remains the default even when the extra is installed.
 
 ```bash
-pip install "apify-client[httpx]"
+pip install "apify-client[httpx2]"
 # or
-uv add "apify-client[httpx]"
+uv add "apify-client[httpx2]"
 ```
 
 <Tabs>
-    <TabItem value="HttpxAsyncExample" label="Async client" default>
+    <TabItem value="Httpx2AsyncExample" label="Async client" default>
         <CodeBlock className="language-python">
-            {HttpxHttpClientAsyncExample}
+            {Httpx2HttpClientAsyncExample}
         </CodeBlock>
     </TabItem>
-    <TabItem value="HttpxSyncExample" label="Sync client">
+    <TabItem value="Httpx2SyncExample" label="Sync client">
         <CodeBlock className="language-python">
-            {HttpxHttpClientSyncExample}
+            {Httpx2HttpClientSyncExample}
         </CodeBlock>
     </TabItem>
 </Tabs>
 
-Configure retries, timeout tiers, default headers, and compression on the HTTPX client instance. The token passed to `with_custom_http_client` is applied automatically unless the HTTP client already has an `Authorization` header. The examples use the clients as context managers so their connection pools are closed deterministically. If a context manager doesn't fit your application's lifecycle, call `close()` on `HttpxHttpClient` or `await aclose()` on `HttpxHttpClientAsync` during shutdown.
+Configure retries, timeout tiers, default headers, and compression on the HTTPX client instance. The token passed to `with_custom_http_client` is applied automatically unless the HTTP client already has an `Authorization` header. The examples use the clients as context managers so their connection pools are closed deterministically. If a context manager doesn't fit your application's lifecycle, call `close()` on `Httpx2HttpClient` or `await aclose()` on `Httpx2HttpClientAsync` during shutdown.
 
 Timeout values are passed to the selected transport. Impit enforces them as a deadline for the whole request, body included. HTTPX applies them to each socket operation instead, so a response whose body arrives slowly keeps resetting the timeout and can outlast both the requested timeout and `timeout_max`. The `no_timeout` option disables HTTPX's timeouts.
 

…2_concepts/code/10_httpx_client_async.py …_concepts/code/10_httpx2_client_async.pydocs/02_concepts/code/10_httpx_client_async.py renamed to docs/02_concepts/code/10_httpx2_client_async.py docs/02_concepts/code/10_httpx_client_async.py renamed to docs/02_concepts/code/10_httpx2_client_async.py

@@ -1,13 +1,13 @@
 import asyncio
 
 from apify_client import ApifyClientAsync
-from apify_client.http_clients import HttpxHttpClientAsync
+from apify_client.http_clients import Httpx2HttpClientAsync
 
 TOKEN = 'MY-APIFY-TOKEN'
 
 
 async def main() -> None:
-    async with HttpxHttpClientAsync() as http_client:
+    async with Httpx2HttpClientAsync() as http_client:
         client = ApifyClientAsync.with_custom_http_client(
             token=TOKEN,
             http_client=http_client,

…02_concepts/code/10_httpx_client_sync.py …2_concepts/code/10_httpx2_client_sync.pydocs/02_concepts/code/10_httpx_client_sync.py renamed to docs/02_concepts/code/10_httpx2_client_sync.py docs/02_concepts/code/10_httpx_client_sync.py renamed to docs/02_concepts/code/10_httpx2_client_sync.py

@@ -1,11 +1,11 @@
 from apify_client import ApifyClient
-from apify_client.http_clients import HttpxHttpClient
+from apify_client.http_clients import Httpx2HttpClient
 
 TOKEN = 'MY-APIFY-TOKEN'
 
 
 def main() -> None:
-    with HttpxHttpClient() as http_client:
+    with Httpx2HttpClient() as http_client:
         client = ApifyClient.with_custom_http_client(
             token=TOKEN,
             http_client=http_client,

pyproject.toml

@@ -34,7 +34,7 @@ dependencies = [
 
 [project.optional-dependencies]
 brotli = ["brotli>=1.0.9"]
-httpx = ["httpx2>=2.0.0"]
+httpx2 = ["httpx2>=2.0.0"]
 
 [project.urls]
 "Apify Homepage" = "https://apify.com"

src/apify_client/http_clients/__init__.py

@@ -5,17 +5,16 @@
 
 _install_import_hook(__name__)
 
-# The HTTPX clients depend on `httpx2`, installed by the optional `httpx` extra, so the import is wrapped in
-# try_import. Accessing them without the extra installed raises a clear ImportError instead of failing at package
-# import time.
+# `httpx2` is an optional extra, so the import is wrapped in try_import. Accessing the HTTPX clients without the
+# extra installed raises a clear ImportError instead of failing at package import time.
 with _try_import(
     __name__,
-    'HttpxHttpClient',
-    'HttpxHttpClientAsync',
+    'Httpx2HttpClient',
+    'Httpx2HttpClientAsync',
     dependency_name='httpx2',
-    extra_name='httpx',
-) as _httpx_import:
-    from apify_client.http_clients._httpx import HttpxHttpClient, HttpxHttpClientAsync
+    extra_name='httpx2',
+) as _httpx2_import:
+    from apify_client.http_clients._httpx2 import Httpx2HttpClient, Httpx2HttpClientAsync
 
 __all__ = [
     'HttpClient',
@@ -25,8 +24,8 @@
     'ImpitHttpClientAsync',
 ]
 
-if _httpx_import.available:
+if _httpx2_import.available:
     __all__ += [
-        'HttpxHttpClient',
-        'HttpxHttpClientAsync',
+        'Httpx2HttpClient',
+        'Httpx2HttpClientAsync',
     ]

src/apify_client/http_clients/_httpx.py src/apify_client/http_clients/_httpx2.pysrc/apify_client/http_clients/_httpx.py renamed to src/apify_client/http_clients/_httpx2.py

@@ -38,7 +38,7 @@
 
 
 @docs_group('HTTP clients')
-class HttpxHttpClient(HttpClient):
+class Httpx2HttpClient(HttpClient):
     """Synchronous HTTP client for the Apify API built on top of [HTTPX](https://github.com/pydantic/httpx2).
 
     This client wraps `httpx.Client` and adds automatic retries with exponential backoff for rate-limited
@@ -48,8 +48,8 @@ class HttpxHttpClient(HttpClient):
     whose body arrives slowly keeps resetting it and can outlast both the requested timeout and `timeout_max`. The
     default Impit client enforces the same value as a deadline for the whole request, body included.
 
-    Requires the `httpx` extra: `pip install "apify-client[httpx]"`. That extra installs `httpx2`, Pydantic's
-    maintained continuation of HTTPX, which this module imports under the `httpx` name.
+    Requires the `httpx2` extra: `pip install "apify-client[httpx2]"`. The `httpx2` package is Pydantic's maintained
+    continuation of HTTPX, which this module imports under the `httpx` name.
     """
 
     def __init__(
@@ -142,7 +142,7 @@ def _clear_response_cookies(self, _response: httpx.Response) -> None:
 
 
 @docs_group('HTTP clients')
-class HttpxHttpClientAsync(HttpClientAsync):
+class Httpx2HttpClientAsync(HttpClientAsync):
     """Asynchronous HTTP client for the Apify API built on top of [HTTPX](https://github.com/pydantic/httpx2).
 
     This client wraps `httpx.AsyncClient` and adds automatic retries with exponential backoff for rate-limited
@@ -152,8 +152,8 @@ class HttpxHttpClientAsync(HttpClientAsync):
     whose body arrives slowly keeps resetting it and can outlast both the requested timeout and `timeout_max`. The
     default Impit client enforces the same value as a deadline for the whole request, body included.
 
-    Requires the `httpx` extra: `pip install "apify-client[httpx]"`. That extra installs `httpx2`, Pydantic's
-    maintained continuation of HTTPX, which this module imports under the `httpx` name.
+    Requires the `httpx2` extra: `pip install "apify-client[httpx2]"`. The `httpx2` package is Pydantic's maintained
+    continuation of HTTPX, which this module imports under the `httpx` name.
     """
 
     def __init__(

tests/integration/conftest.py

@@ -19,8 +19,8 @@
 from apify_client._consts import DEFAULT_API_URL
 from apify_client._utils.crypto import create_hmac_signature, create_storage_content_signature
 from apify_client.http_clients import (
-    HttpxHttpClient,
-    HttpxHttpClientAsync,
+    Httpx2HttpClient,
+    Httpx2HttpClientAsync,
     ImpitHttpClient,
     ImpitHttpClientAsync,
 )
@@ -109,7 +109,7 @@ def test_kvs_of_another_user(api_token_2: str) -> Generator[KvsFixture]:
 @pytest.fixture(
     params=[
         pytest.param(HttpClientClasses(sync=ImpitHttpClient, async_=ImpitHttpClientAsync), id='impit'),
-        pytest.param(HttpClientClasses(sync=HttpxHttpClient, async_=HttpxHttpClientAsync), id='httpx'),
+        pytest.param(HttpClientClasses(sync=Httpx2HttpClient, async_=Httpx2HttpClientAsync), id='httpx2'),
     ]
 )
 def http_client_classes(request: pytest.FixtureRequest) -> HttpClientClasses: