Feature: add httpx2 support with httpx fallback

.github/workflows/codecov.yml

@@ -20,18 +20,25 @@ jobs:
     name: Test Coverage
     runs-on: ${{ matrix.os }}
     concurrency:
-      group: test-coverage-${{ github.ref }}-${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.env }}
+      group: test-coverage-${{ github.ref }}-${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.env }}-${{ matrix.http-client }}
       cancel-in-progress: true
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
         os: [ubuntu-latest, windows-latest, macos-latest]
         env: [pydantic-v1, pydantic-v2]
+        http-client: [httpx2]
+        include:
+          - python-version: "3.14"
+            os: ubuntu-latest
+            env: pydantic-v2
+            http-client: httpx
       fail-fast: false
     env:
       OS: ${{ matrix.os }}
       PYTHON_VERSION: ${{ matrix.python-version }}
       PYDANTIC_VERSION: ${{ matrix.env }}
+      GITHUBKIT_HTTPX2_DISABLE_FLAG: ${{ matrix.http-client == 'httpx' && '1' || '' }}
 
     steps:
       - uses: actions/checkout@v7

codegen/parser/__init__.py

@@ -1,7 +1,7 @@
 from contextvars import ContextVar
 from typing import TYPE_CHECKING, Optional
 
-import httpx
+import httpx2 as httpx
 from openapi_pydantic import OpenAPI
 
 from ..log import logger

codegen/source.py

@@ -3,7 +3,7 @@
 import os
 from typing import Any
 
-import httpx
+import httpx2 as httpx
 from jsonpointer import JsonPointer
 
 GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")

docs/index.md

@@ -49,7 +49,7 @@ githubkit provides several features including:
 - :material-tag-multiple: REST API versioning, including GHEC
 - :material-page-next: Built-in pagination support
 - :material-database-check: Optional data validation with [Pydantic](https://docs.pydantic.dev/latest/), for both webhook events and REST API responses
-- :material-cached: Built-in http cache (powered by [Hishel](https://hishel.com/) for HTTPX) and auto retry
+- :material-cached: Built-in http cache (powered by [Hishel](https://hishel.com/) for HTTPX and HTTPX2) and auto retry
 - :material-lightning-bolt: Lazy loading of APIs and models
 - :material-check-circle: Fully typed APIs
 

docs/usage/getting-started/configuration.md

@@ -2,6 +2,14 @@
 
 githubkit is highly configurable. You can customize its behavior by passing keyword arguments directly to the `GitHub` constructor:
 
+!!! note "HTTPX and HTTPX2 compatibility"
+
+    githubkit installs HTTPX by default to preserve compatibility with existing transports. It prefers [HTTPX2](https://pydantic.dev/docs/httpx2/) when you install it separately. The default HTTPX path remains supported, but emits a `DeprecationWarning`. To opt in, run `pip install httpx2`, then use `import httpx2` and `httpx2.*` as in the examples below. If you remain on HTTPX, use `import httpx` and `httpx.*` instead.
+
+    To force HTTPX even when HTTPX2 is installed, set the environment variable `GITHUBKIT_HTTPX2_DISABLE_FLAG=1` before importing githubkit. Any non-empty value (including `0` or `false`) disables the feature.
+
+    Custom timeouts, URLs, proxies, transports, and responses must come from the selected package: HTTPX2 when installed, or HTTPX on the deprecated fallback path. Objects from the two packages are not interchangeable. HTTPX2 uses the operating system's trust store by default instead of HTTPX's bundled CA certificates; its logger names are `httpx2` and `httpcore2.*`.
+
 ```python
 from githubkit import GitHub
 
@@ -30,7 +38,7 @@ github = GitHub(
 Alternatively, you can build a `Config` object and pass it via the `config` parameter. This is useful when you want to share the same configuration across multiple `GitHub` instances:
 
 ```python
-import httpx
+import httpx2
 from githubkit import GitHub, Config
 from githubkit.retry import RETRY_DEFAULT
 from githubkit.cache import DEFAULT_CACHE_STRATEGY
@@ -40,7 +48,7 @@ config = Config(
     accept="application/vnd.github+json",
     user_agent="GitHubKit/Python",
     follow_redirects=True,
-    timeout=httpx.Timeout(None),
+    timeout=httpx2.Timeout(None),
     ssl_verify=True,
     trust_env=True,
     proxy=None,
@@ -103,16 +111,16 @@ Whether to automatically follow HTTP redirects (3xx responses). Enabled by defau
 
 ### `timeout`
 
-The request timeout. Accepts a `float` (seconds), an `httpx.Timeout` object for fine-grained control, or `None` for no timeout (default). See [HTTPX Timeouts](https://www.python-httpx.org/advanced/timeouts/) for details.
+The request timeout. Accepts a `float` (seconds), an `httpx2.Timeout` object for fine-grained control, or `None` for no timeout (default). See [HTTPX2 Timeouts](https://pydantic.dev/docs/httpx2/advanced/timeouts/) for details.
 
 ```python
-import httpx
+import httpx2
 
 # Simple: 10 second timeout for all operations
 github = GitHub(timeout=10.0)
 
 # Fine-grained: different timeouts for connect vs. read
-github = GitHub(timeout=httpx.Timeout(5.0, read=30.0))
+github = GitHub(timeout=httpx2.Timeout(5.0, read=30.0))
 ```
 
 ### `ssl_verify`
@@ -123,76 +131,76 @@ Controls SSL certificate verification. Defaults to `True`.
 - `False` — **disable** SSL verification (not recommended for production).
 - `ssl.SSLContext` — provide a custom SSL context for advanced use cases.
 
-See [HTTPX SSL](https://www.python-httpx.org/advanced/ssl/) for details.
+See [HTTPX2 SSL](https://pydantic.dev/docs/httpx2/advanced/ssl/) for details.
 
 ### `trust_env`
 
-When `True` (default), githubkit (via HTTPX) reads environment variables such as `HTTP_PROXY`, `HTTPS_PROXY`, and `SSL_CERT_FILE` to configure proxies and SSL. Set to `False` to ignore these variables.
+When `True` (default), githubkit (via HTTPX2) reads environment variables such as `HTTP_PROXY`, `HTTPS_PROXY`, and `SSL_CERT_FILE` to configure proxies and SSL. Set to `False` to ignore these variables.
 
 ### `proxy`
 
-Sets a proxy URL for all requests. Accepts a string, `httpx.URL`, or `httpx.Proxy` object.
+Sets a proxy URL for all requests. Accepts a string, `httpx2.URL`, or `httpx2.Proxy` object.
 
 ```python
 github = GitHub(proxy="http://proxy.example.com:8080")
 ```
 
-See [HTTPX Proxies](https://www.python-httpx.org/advanced/proxies/) for more details.
+See [HTTPX2 Proxies](https://pydantic.dev/docs/httpx2/advanced/proxies/) for more details.
 
 !!! note
 
     If `trust_env` is `True` and no `proxy` is set, githubkit respects the `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` environment variables.
 
 ### `transport`, `async_transport`
 
-Provide custom [HTTPX transports](https://www.python-httpx.org/advanced/transports/) to replace the default networking layer. This is useful for:
+Provide custom [HTTPX2 transports](https://pydantic.dev/docs/httpx2/advanced/transports/) to replace the default networking layer. This is useful for:
 
-- **Unit testing** — inject `httpx.MockTransport` to stub API responses without making real HTTP calls.
+- **Unit testing** — inject `httpx2.MockTransport` to stub API responses without making real HTTP calls.
 - **Custom networking** — use alternative transport implementations (e.g., HTTP/3, Unix sockets).
 
 | Option            | Type                       | Used for       |
 | ----------------- | -------------------------- | -------------- |
-| `transport`       | `httpx.BaseTransport`      | Sync requests  |
-| `async_transport` | `httpx.AsyncBaseTransport` | Async requests |
+| `transport`       | `httpx2.BaseTransport`      | Sync requests  |
+| `async_transport` | `httpx2.AsyncBaseTransport` | Async requests |
 
 ```python
-import httpx
+import httpx2
 
 
-def mock_handler(request: httpx.Request) -> httpx.Response:
-    return httpx.Response(200, json={"login": "octocat"})
+def mock_handler(request: httpx2.Request) -> httpx2.Response:
+    return httpx2.Response(200, json={"login": "octocat"})
 
 
-github = GitHub(transport=httpx.MockTransport(mock_handler))
+github = GitHub(transport=httpx2.MockTransport(mock_handler))
 ```
 
 !!! warning
 
-    When a custom transport is provided, proxy-related environment variables (`HTTP_PROXY`, etc.) have no effect. Set `transport` / `async_transport` to `None` (default) to use HTTPX's built-in transport.
+    When a custom transport is provided, proxy-related environment variables (`HTTP_PROXY`, etc.) have no effect. Set `transport` / `async_transport` to `None` (default) to use HTTPX2's built-in transport.
 
 ### `event_hooks`, `async_event_hooks`
 
-Register [HTTPX event hooks](https://www.python-httpx.org/advanced/event-hooks/) that run on every request and/or response. This is useful for logging, injecting headers, collecting metrics, or raising on error status codes — without modifying your business logic.
+Register [HTTPX2 event hooks](https://pydantic.dev/docs/httpx2/advanced/event-hooks/) that run on every request and/or response. This is useful for logging, injecting headers, collecting metrics, or raising on error status codes — without modifying your business logic.
 
 | Option              | Hook signatures                                        | Used for       |
 | ------------------- | ------------------------------------------------------ | -------------- |
 | `event_hooks`       | `def hook(request)` / `def hook(response)`             | Sync requests  |
 | `async_event_hooks` | `async def hook(request)` / `async def hook(response)` | Async requests |
 
-Both options accept a dictionary mapping event names (`"request"`, `"response"`) to a list of callables. Each callable receives an `httpx.Request` or `httpx.Response` object respectively.
+Both options accept a dictionary mapping event names (`"request"`, `"response"`) to a list of callables. Each callable receives an `httpx2.Request` or `httpx2.Response` object respectively.
 
 === "Sync"
 
     ```python
-    import httpx
+    import httpx2
     from githubkit import GitHub
 
 
-    def log_request(request: httpx.Request) -> None:
+    def log_request(request: httpx2.Request) -> None:
         print(f"-> {request.method} {request.url}")
 
 
-    def log_response(response: httpx.Response) -> None:
+    def log_response(response: httpx2.Response) -> None:
         print(f"<- {response.status_code}")
 
 
@@ -207,15 +215,15 @@ Both options accept a dictionary mapping event names (`"request"`, `"response"`)
 === "Async"
 
     ```python
-    import httpx
+    import httpx2
     from githubkit import GitHub
 
 
-    async def log_request(request: httpx.Request) -> None:
+    async def log_request(request: httpx2.Request) -> None:
         print(f"-> {request.method} {request.url}")
 
 
-    async def log_response(response: httpx.Response) -> None:
+    async def log_response(response: httpx2.Response) -> None:
         print(f"<- {response.status_code}")
 
 

docs/usage/getting-started/reusing-client.md

@@ -1,6 +1,6 @@
 # Reusing Client
 
-githubkit manages an underlying [HTTPX](https://www.python-httpx.org/) client for making HTTP requests. You can use a **context manager** to ensure the HTTP client is properly created, reused, and closed when you're done.
+githubkit manages an underlying HTTPX client by default, preferring [HTTPX2](https://pydantic.dev/docs/httpx2/) when you install it separately. You can use a **context manager** to ensure the HTTP client is properly created, reused, and closed when you're done.
 
 <!-- https://github.com/yanyongyu/githubkit/issues/285 -->
 

docs/usage/unit-test.md

@@ -2,6 +2,8 @@
 
 If you are using githubkit in your business logic, you may want to mock the github API in your unit tests. There are two ways to reach this.
 
+These examples use HTTPX2, the preferred opt-in backend. Run `pip install httpx2` to use it. githubkit installs HTTPX by default; if you use that deprecated fallback, use `import httpx` and replace `httpx2.*` with `httpx.*` instead. Mock requests, responses, and transports must use the same package as githubkit; HTTPX and HTTPX2 objects are not interchangeable.
+
 ## Mocking the API Calls
 
 If you can't provide a githubkit test client to your business logic, you can mock the `request`/`arequest` method of the `GitHub` class to custom the response. Here is an example of how to mock githubkit's API calls:
@@ -13,7 +15,7 @@ If you can't provide a githubkit test client to your business logic, you can moc
     from pathlib import Path
     from typing import Any, Type
 
-    import httpx
+    import httpx2
     import pytest
 
     from githubkit import GitHub
@@ -41,7 +43,7 @@ If you can't provide a githubkit test client to your business logic, you can moc
     ) -> Response[Any]:
         if method == "GET" and url == "/repos/owner/repo":  # (3)!
             return Response(
-                httpx.Response(status_code=200, json=FAKE_RESPONSE),
+                httpx2.Response(status_code=200, json=FAKE_RESPONSE),
                 Any if response_model is UNSET else response_model,
             )
         raise RuntimeError(f"Unexpected request: {method} {url}")
@@ -68,7 +70,7 @@ If you can't provide a githubkit test client to your business logic, you can moc
     from pathlib import Path
     from typing import Any, Type
 
-    import httpx
+    import httpx2
     import pytest
 
     from githubkit import GitHub
@@ -96,7 +98,7 @@ If you can't provide a githubkit test client to your business logic, you can moc
     ) -> Response[Any]:
         if method == "GET" and url == "/repos/owner/repo":  # (3)!
             return Response(
-                httpx.Response(status_code=200, json=FAKE_RESPONSE),
+                httpx2.Response(status_code=200, json=FAKE_RESPONSE),
                 Any if response_model is UNSET else response_model,
             )
         raise RuntimeError(f"Unexpected request: {method} {url}")
@@ -127,7 +129,7 @@ You can also create a test client with mock transport and provide it to your bus
     import json
     from pathlib import Path
 
-    import httpx
+    import httpx2
     import pytest
 
     from githubkit import GitHub
@@ -141,14 +143,14 @@ You can also create a test client with mock transport and provide it to your bus
         return resp.parsed_data
 
 
-    def mock_transport_handler(request: httpx.Request) -> httpx.Response:
+    def mock_transport_handler(request: httpx2.Request) -> httpx2.Response:
         if request.method == "GET" and request.url.path == "/repos/owner/repo":
-            return httpx.Response(status_code=200, json=FAKE_RESPONSE)
+            return httpx2.Response(status_code=200, json=FAKE_RESPONSE)
         raise RuntimeError(f"Unexpected request: {request.method} {request.url.path}")
 
 
     def test_sync_mock():
-        g = GitHub("xxxxx", transport=httpx.MockTransport(mock_transport_handler))
+        g = GitHub("xxxxx", transport=httpx2.MockTransport(mock_transport_handler))
         repo = target_sync_func(g)
         assert isinstance(repo, FullRepository)
     ```
@@ -159,7 +161,7 @@ You can also create a test client with mock transport and provide it to your bus
     import json
     from pathlib import Path
 
-    import httpx
+    import httpx2
     import pytest
 
     from githubkit import GitHub
@@ -173,15 +175,15 @@ You can also create a test client with mock transport and provide it to your bus
         return resp.parsed_data
 
 
-    def mock_transport_handler(request: httpx.Request) -> httpx.Response:
+    def mock_transport_handler(request: httpx2.Request) -> httpx2.Response:
         if request.method == "GET" and request.url.path == "/repos/owner/repo":
-            return httpx.Response(status_code=200, json=FAKE_RESPONSE)
+            return httpx2.Response(status_code=200, json=FAKE_RESPONSE)
         raise RuntimeError(f"Unexpected request: {request.method} {request.url.path}")
 
 
     @pytest.mark.anyio
     async def test_async_mock():
-        g = GitHub("xxxxx", async_transport=httpx.MockTransport(mock_transport_handler))
+        g = GitHub("xxxxx", async_transport=httpx2.MockTransport(mock_transport_handler))
         repo = await target_async_func(g)
         assert isinstance(repo, FullRepository)
     ```

githubkit/_httpx.py

@@ -0,0 +1,39 @@
+import os
+from typing import TYPE_CHECKING
+import warnings
+
+GITHUBKIT_HTTPX2_DISABLE_FLAG = "GITHUBKIT_HTTPX2_DISABLE_FLAG"
+
+if TYPE_CHECKING:
+    from hishel.httpx2 import AsyncCacheTransport as AsyncCacheTransport
+    from hishel.httpx2 import SyncCacheTransport as SyncCacheTransport
+    import httpx2 as httpx
+else:
+    httpx = None
+    if not os.getenv(GITHUBKIT_HTTPX2_DISABLE_FLAG):
+        try:
+            from hishel.httpx2 import AsyncCacheTransport, SyncCacheTransport
+            import httpx2 as httpx
+        except ImportError:
+            # Hishel wraps a missing HTTP client in ImportError.
+            pass
+
+    if httpx is None:
+        try:
+            from hishel.httpx import AsyncCacheTransport as AsyncCacheTransport
+            from hishel.httpx import SyncCacheTransport as SyncCacheTransport
+            import httpx as httpx
+        except ImportError:
+            raise RuntimeError(
+                "GitHubKit requires httpx2 and its Hishel integration "
+                "to be installed.\n"
+                "You can install them with:\n"
+                '    $ pip install httpx2 "hishel[async,httpx2]>=1.4.0"\n'
+            ) from None
+        else:
+            warnings.warn(
+                "Using `httpx` with GitHubKit is deprecated; install `httpx2` "
+                "and `hishel[async,httpx2]>=1.4.0` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )

githubkit/auth/_url.py

@@ -1,6 +1,6 @@
 import re
 
-import httpx
+from githubkit._httpx import httpx
 
 APP_ROUTES = {
     r"/app",

githubkit/auth/action.py

@@ -2,8 +2,7 @@
 import os
 from typing import TYPE_CHECKING
 
-import httpx
-
+from githubkit._httpx import httpx
 from githubkit.exception import AuthCredentialError
 
 from .base import BaseAuthStrategy

githubkit/auth/app.py

@@ -4,8 +4,7 @@
 from typing import TYPE_CHECKING, ClassVar
 from typing_extensions import LiteralString
 
-import httpx
-
+from githubkit._httpx import httpx
 from githubkit.compat import model_dump, type_validate_python
 from githubkit.exception import AuthCredentialError
 from githubkit.utils import UNSET, Unset, exclude_unset