feat(python): add aiohttp auto-detection to Python SDK generator (#14469)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: jsklan

generators/python-v2/sdk/src/wire-tests/WireTestSetupGenerator.ts

@@ -466,6 +466,26 @@ def _is_xdist_worker(config: pytest.Config) -> bool:
     return hasattr(config, "workerinput")
 
 
+def _has_httpx_aiohttp() -> bool:
+    """Check if httpx_aiohttp is importable."""
+    try:
+        import httpx_aiohttp  # type: ignore[import-not-found]  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def pytest_collection_modifyitems(config: pytest.Config, items: list) -> None:
+    """Auto-skip @pytest.mark.aiohttp tests when httpx_aiohttp is not installed."""
+    if _has_httpx_aiohttp():
+        return
+    skip_aiohttp = pytest.mark.skip(reason="httpx_aiohttp not installed")
+    for item in items:
+        if "aiohttp" in item.keywords:
+            item.add_marker(skip_aiohttp)
+
+
 def pytest_configure(config: pytest.Config) -> None:
     """
     Pytest hook that runs during test session setup.

generators/python/sdk/versions.yml

@@ -1,5 +1,17 @@
 # yaml-language-server: $schema=../../../fern-versions-yml.schema.json
 # For unreleased changes, use unreleased.yml
+- version: 5.3.0
+  changelogEntry:
+    - summary: |
+        Add aiohttp auto-detection for async HTTP client. When `httpx_aiohttp` is installed,
+        the generated SDK automatically uses `HttpxAiohttpClient` for async operations instead
+        of the default `httpx.AsyncClient`. Adds `DefaultAioHttpClient` and `DefaultAsyncHttpxClient`
+        convenience classes, optional `[aiohttp]` extra in pyproject.toml, pytest markers for
+        aiohttp-specific tests, and two-pass CI testing (standard + aiohttp).
+      type: feat
+  createdAt: "2026-04-01"
+  irVersion: 65
+
 - version: 5.2.0
   changelogEntry:
     - summary: |

generators/python/src/fern_python/cli/abstract_generator.py

@@ -385,6 +385,14 @@ def _get_github_workflow_legacy(
             workflow_yaml += """
       - name: Test
         run: poetry run pytest -rP -n auto .
+"""
+        # Add aiohttp extra install and test steps
+        workflow_yaml += """
+      - name: Install aiohttp extra
+        run: poetry install --extras aiohttp
+
+      - name: Test (aiohttp)
+        run: poetry run pytest -rP -n auto -m aiohttp .
 """
         if output_mode.publish_info is not None:
             publish_info_union = output_mode.publish_info.get_as_union()
@@ -477,6 +485,14 @@ def _get_github_workflow(
             workflow_yaml += """
       - name: Test
         run: poetry run pytest -rP -n auto .
+"""
+        # Add aiohttp extra install and test steps
+        workflow_yaml += """
+      - name: Install aiohttp extra
+        run: poetry install --extras aiohttp
+
+      - name: Test (aiohttp)
+        run: poetry run pytest -rP -n auto -m aiohttp .
 """
         if output_mode.publish_info is not None:
             publish_info_union = output_mode.publish_info.get_as_union()

generators/python/src/fern_python/codegen/pyproject_toml.py

@@ -271,6 +271,9 @@ def to_string(self) -> str:
 [tool.pytest.ini_options]
 testpaths = [ "tests" ]
 asyncio_mode = "auto"
+markers = [
+    "aiohttp: tests that require httpx_aiohttp to be installed",
+]
 
 [tool.mypy]
 plugins = ["pydantic.mypy"]{mypy_exclude_config}

generators/python/src/fern_python/generators/sdk/client_generator/root_client_generator.py

@@ -205,6 +205,7 @@ def generate(self, source_file: SourceFile) -> None:
             declaration=class_declaration,
             should_export=False,
         )
+        source_file.add_arbitrary_code(AST.CodeWriter(self._write_make_default_async_client))
         source_file.add_class_declaration(
             declaration=async_class_declaration,
             should_export=False,
@@ -1431,6 +1432,23 @@ def _get_client_wrapper_kwargs(
                     ),
                 ),
             )
+        elif is_async:
+            client_wrapper_constructor_kwargs.append(
+                (
+                    ClientWrapperGenerator.HTTPX_CLIENT_MEMBER_NAME,
+                    AST.Expression(
+                        AST.ConditionalExpression(
+                            left=AST.Expression(f"{RootClientGenerator.HTTPX_CLIENT_CONSTRUCTOR_PARAMETER_NAME}"),
+                            right=AST.Expression(
+                                f"_make_default_async_client(timeout={timeout_local_variable}, follow_redirects={self.FOLLOW_REDIRECTS_CONSTRUCTOR_PARAMETER_NAME})"
+                            ),
+                            test=AST.Expression(
+                                f"{RootClientGenerator.HTTPX_CLIENT_CONSTRUCTOR_PARAMETER_NAME} is not None"
+                            ),
+                        ),
+                    ),
+                )
+            )
         else:
             client_wrapper_constructor_kwargs.append(
                 (
@@ -1440,11 +1458,11 @@ def _get_client_wrapper_kwargs(
                             left=AST.Expression(f"{RootClientGenerator.HTTPX_CLIENT_CONSTRUCTOR_PARAMETER_NAME}"),
                             right=AST.ConditionalExpression(
                                 left=AST.ClassInstantiation(
-                                    HttpX.ASYNC_CLIENT if is_async else HttpX.CLIENT,
+                                    HttpX.CLIENT,
                                     kwargs=httpx_client_kwargs_with_redirects,
                                 ),
                                 right=AST.ClassInstantiation(
-                                    HttpX.ASYNC_CLIENT if is_async else HttpX.CLIENT,
+                                    HttpX.CLIENT,
                                     kwargs=httpx_client_kwargs_without_redirects,
                                 ),
                                 test=AST.Expression(f"{self.FOLLOW_REDIRECTS_CONSTRUCTOR_PARAMETER_NAME} is not None"),
@@ -1480,6 +1498,35 @@ def _get_client_wrapper_kwargs(
 
         return client_wrapper_constructor_kwargs
 
+    def _write_make_default_async_client(self, writer: AST.NodeWriter) -> None:
+        writer.write_line("")
+        writer.write_line("def _make_default_async_client(")
+        with writer.indent():
+            writer.write_line("timeout: typing.Optional[float],")
+            writer.write_line("follow_redirects: typing.Optional[bool],")
+        writer.write_line(") -> httpx.AsyncClient:")
+        with writer.indent():
+            writer.write_line("try:")
+            with writer.indent():
+                writer.write_line("import httpx_aiohttp  # type: ignore[import-not-found]")
+            writer.write_line("except ImportError:")
+            with writer.indent():
+                writer.write_line("pass")
+            writer.write_line("else:")
+            with writer.indent():
+                writer.write_line("if follow_redirects is not None:")
+                with writer.indent():
+                    writer.write_line(
+                        "return httpx_aiohttp.HttpxAiohttpClient(timeout=timeout, follow_redirects=follow_redirects)"
+                    )
+                writer.write_line("return httpx_aiohttp.HttpxAiohttpClient(timeout=timeout)")
+            writer.write_line("")
+            writer.write_line("if follow_redirects is not None:")
+            with writer.indent():
+                writer.write_line("return httpx.AsyncClient(timeout=timeout, follow_redirects=follow_redirects)")
+            writer.write_line("return httpx.AsyncClient(timeout=timeout)")
+        writer.write_line("")
+
     def _write_get_base_url_function(self, writer: AST.NodeWriter) -> None:
         writer.write_line(f"if {RootClientGenerator.BASE_URL_CONSTRUCTOR_PARAMETER_NAME} is not None:")
         with writer.indent():

generators/python/src/fern_python/generators/sdk/sdk_generator.py

@@ -118,7 +118,14 @@ def run(
                     )
                 )
 
-        project.add_extra(custom_config.extras)
+        # Merge user-defined extras with the built-in aiohttp extra
+        extras = dict(custom_config.extras)
+        extras["aiohttp"] = ["aiohttp", "httpx-aiohttp"]
+        project.add_extra(extras)
+
+        # Add optional dependencies for aiohttp support
+        project.add_dependency(dependency=AST.Dependency(name="httpx-aiohttp", version="0.1.8", optional=True))
+        project.add_dependency(dependency=AST.Dependency(name="aiohttp", version="3.0", optional=True))
 
         for dep, bas_dep_value in custom_config.extra_dev_dependencies.items():
             if type(bas_dep_value) is str:
@@ -280,6 +287,18 @@ def run(
             ],
         )
 
+        # Generate _default_clients.py with aiohttp auto-detection convenience classes
+        self._generate_default_clients(
+            context=context,
+            project=project,
+        )
+
+        # Generate test_aiohttp_autodetect.py test file
+        self._generate_aiohttp_test(
+            context=context,
+            project=project,
+        )
+
         for subpackage_id in ir.subpackages.keys():
             subpackage = ir.subpackages[subpackage_id]
             if subpackage.has_endpoints_in_tree or (
@@ -688,6 +707,179 @@ def _generate_error(
         ErrorGenerator(context=context, error=error).generate(source_file=source_file)
         project.write_source_file(source_file=source_file, filepath=filepath)
 
+    def _generate_aiohttp_test(
+        self,
+        context: SdkGeneratorContext,
+        project: Project,
+    ) -> None:
+        package_name = project._project_config.package_name if project._project_config is not None else "package"
+        contents = f'''import importlib
+import sys
+import unittest
+from unittest import mock
+
+import httpx
+import pytest
+
+
+class TestMakeDefaultAsyncClientWithoutAiohttp(unittest.TestCase):
+    """Tests for _make_default_async_client when httpx_aiohttp is NOT installed."""
+
+    def test_returns_httpx_async_client(self) -> None:
+        """When httpx_aiohttp is not installed, returns plain httpx.AsyncClient."""
+        with mock.patch.dict(sys.modules, {{"httpx_aiohttp": None}}):
+            from {package_name}.client import _make_default_async_client
+
+            client = _make_default_async_client(timeout=60, follow_redirects=True)
+            self.assertIsInstance(client, httpx.AsyncClient)
+            self.assertEqual(client.timeout.read, 60)
+            self.assertTrue(client.follow_redirects)
+
+    def test_follow_redirects_none(self) -> None:
+        """When follow_redirects is None, omits it from httpx.AsyncClient."""
+        with mock.patch.dict(sys.modules, {{"httpx_aiohttp": None}}):
+            from {package_name}.client import _make_default_async_client
+
+            client = _make_default_async_client(timeout=60, follow_redirects=None)
+            self.assertIsInstance(client, httpx.AsyncClient)
+            self.assertFalse(client.follow_redirects)
+
+    def test_explicit_httpx_client_bypasses_autodetect(self) -> None:
+        """When user passes httpx_client explicitly, auto-detect is not used."""
+        explicit_client = httpx.AsyncClient(timeout=60)
+        result = explicit_client if explicit_client is not None else None
+        self.assertIs(result, explicit_client)
+        self.assertEqual(result.timeout.read, 60)
+
+
+@pytest.mark.aiohttp
+class TestMakeDefaultAsyncClientWithAiohttp(unittest.TestCase):
+    """Tests for _make_default_async_client when httpx_aiohttp IS installed."""
+
+    def test_returns_aiohttp_client(self) -> None:
+        """When httpx_aiohttp is installed, returns HttpxAiohttpClient."""
+        import httpx_aiohttp  # type: ignore[import-not-found]
+
+        from {package_name}.client import _make_default_async_client
+
+        client = _make_default_async_client(timeout=60, follow_redirects=True)
+        self.assertIsInstance(client, httpx_aiohttp.HttpxAiohttpClient)
+        self.assertEqual(client.timeout.read, 60)
+        self.assertTrue(client.follow_redirects)
+
+    def test_follow_redirects_none(self) -> None:
+        """When httpx_aiohttp is installed and follow_redirects is None, omits it."""
+        import httpx_aiohttp  # type: ignore[import-not-found]
+
+        from {package_name}.client import _make_default_async_client
+
+        client = _make_default_async_client(timeout=60, follow_redirects=None)
+        self.assertIsInstance(client, httpx_aiohttp.HttpxAiohttpClient)
+        self.assertFalse(client.follow_redirects)
+
+
+class TestDefaultClientsWithoutAiohttp(unittest.TestCase):
+    """Tests for _default_clients.py convenience classes (no aiohttp)."""
+
+    def test_default_async_httpx_client_defaults(self) -> None:
+        """DefaultAsyncHttpxClient applies SDK defaults."""
+        from {package_name}._default_clients import SDK_DEFAULT_TIMEOUT, DefaultAsyncHttpxClient
+
+        client = DefaultAsyncHttpxClient()
+        self.assertIsInstance(client, httpx.AsyncClient)
+        self.assertEqual(client.timeout.read, SDK_DEFAULT_TIMEOUT)
+        self.assertTrue(client.follow_redirects)
+
+    def test_default_async_httpx_client_overrides(self) -> None:
+        """DefaultAsyncHttpxClient allows overriding defaults."""
+        from {package_name}._default_clients import DefaultAsyncHttpxClient
+
+        client = DefaultAsyncHttpxClient(timeout=30, follow_redirects=False)
+        self.assertEqual(client.timeout.read, 30)
+        self.assertFalse(client.follow_redirects)
+
+    def test_default_aiohttp_client_raises_without_package(self) -> None:
+        """DefaultAioHttpClient raises RuntimeError when httpx_aiohttp not installed."""
+        import {package_name}._default_clients
+
+        with mock.patch.dict(sys.modules, {{"httpx_aiohttp": None}}):
+            importlib.reload({package_name}._default_clients)
+
+            with self.assertRaises(RuntimeError) as ctx:
+                {package_name}._default_clients.DefaultAioHttpClient()
+            self.assertIn("pip install {package_name}[aiohttp]", str(ctx.exception))
+
+        importlib.reload({package_name}._default_clients)
+
+
+@pytest.mark.aiohttp
+class TestDefaultClientsWithAiohttp(unittest.TestCase):
+    """Tests for _default_clients.py when httpx_aiohttp IS installed."""
+
+    def test_default_aiohttp_client_defaults(self) -> None:
+        """DefaultAioHttpClient works when httpx_aiohttp is installed."""
+        import httpx_aiohttp  # type: ignore[import-not-found]
+
+        from {package_name}._default_clients import SDK_DEFAULT_TIMEOUT, DefaultAioHttpClient
+
+        client = DefaultAioHttpClient()
+        self.assertIsInstance(client, httpx_aiohttp.HttpxAiohttpClient)
+        self.assertEqual(client.timeout.read, SDK_DEFAULT_TIMEOUT)
+        self.assertTrue(client.follow_redirects)
+'''
+        project.add_source_file("tests/test_aiohttp_autodetect.py", contents)
+
+    def _generate_default_clients(
+        self,
+        context: SdkGeneratorContext,
+        project: Project,
+    ) -> None:
+        package_name = project._project_config.package_name if project._project_config is not None else "package"
+        filepath = Filepath(
+            directories=(),
+            file=Filepath.FilepathPart(module_name="_default_clients"),
+        )
+        filepath_nested = project.get_source_file_filepath(filepath, include_src_root=True)
+        contents = f"""# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import httpx
+
+SDK_DEFAULT_TIMEOUT = 60
+
+try:
+    import httpx_aiohttp  # type: ignore[import-not-found]
+except ImportError:
+
+    class DefaultAioHttpClient(httpx.AsyncClient):  # type: ignore
+        def __init__(self, **kwargs: typing.Any) -> None:
+            raise RuntimeError(
+                "To use the aiohttp client, install the aiohttp extra: "
+                "pip install {package_name}[aiohttp]"
+            )
+
+else:
+
+    class DefaultAioHttpClient(httpx_aiohttp.HttpxAiohttpClient):  # type: ignore
+        def __init__(self, **kwargs: typing.Any) -> None:
+            kwargs.setdefault("timeout", SDK_DEFAULT_TIMEOUT)
+            kwargs.setdefault("follow_redirects", True)
+            super().__init__(**kwargs)
+
+
+class DefaultAsyncHttpxClient(httpx.AsyncClient):
+    def __init__(self, **kwargs: typing.Any) -> None:
+        kwargs.setdefault("timeout", SDK_DEFAULT_TIMEOUT)
+        kwargs.setdefault("follow_redirects", True)
+        super().__init__(**kwargs)
+"""
+        project.add_file(filepath_nested, contents)
+        project.register_export_in_project(
+            filepath_in_project=filepath,
+            exports={"DefaultAioHttpClient", "DefaultAsyncHttpxClient"},
+        )
+
     def _generate_version(
         self,
         project: Project,