Merge pull request #331 from zero-sum-seattle/fix/324-async-proxy-support

fix: honor environment proxies for library-created async clients

Author: Mattsface

docs/async.md

@@ -207,6 +207,22 @@ real application the client is typically created once, reused across calls,
 and closed by whatever code owns its lifecycle — the examples above show a
 few ways to run this, not the required shape of your application.
 
+## Environment proxies
+
+A library-created client (the default — no `client=` passed) honors
+`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` from the environment,
+the same variables a plain `httpx.AsyncClient()` discovers on its own.
+
+An injected client keeps whatever proxy configuration its caller gave it —
+`httpx.AsyncClient()` reads those variables itself by default, or a caller
+may pass `trust_env=False` or an explicit `proxy=`/`mounts=` to opt out or
+override. The library does not add or remove proxy configuration on an
+injected client.
+
+See [HTTP transport: async client environment
+proxies](http-transport.md#async-client-environment-proxies) for the full
+behavior.
+
 ## Documentation boundaries
 
 - [README](../README.md) — installation and quick-start examples

docs/http-transport.md

@@ -710,8 +710,31 @@ bodies.
 
 The client has no default response cache.
 
-## No async support
+## Async client environment proxies
 
-The client remains synchronous.
+Library-created `AsyncMlb` / `AsyncMlbDataAdapter` clients honor
+`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` (any case), the same
+environment variables HTTPX itself discovers for a plain `httpx.AsyncClient()`.
 
-Async support is not part of version 1.0.0.
+```text
+Library-created async client
+    Reads HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY from the environment
+    Routes matching requests through the proxy
+    Applies the library retry policy to proxied and direct requests alike
+
+Caller-injected async client
+    Keeps exactly whatever transport and mounts its caller configured
+    The library never reads proxy environment variables for it
+```
+
+This mirrors [Session ownership](#session-ownership) on the sync side: the
+library only ever configures a client it created itself. See
+[async.md](async.md#custom-httpx-client) for injecting a client, including one
+configured with its own proxy settings.
+
+## Scope of this document
+
+The retry, timeout, User-Agent, and strict-HTTP behavior documented above
+apply to the synchronous `Mlb` client. For the asynchronous client, see
+[async.md](async.md); it shares this document's retry, timeout, and
+error-handling contract except where noted above.

mlbstatsapi/_async_transport.py

@@ -25,6 +25,7 @@
 import asyncio
 
 from ._async_support import import_httpx
+from ._env_proxies import environment_proxy_map
 from .mlb_dataadapter import _build_user_agent, create_retry_policy
 
 httpx = import_httpx()
@@ -158,8 +159,51 @@ def create_library_async_client() -> httpx.AsyncClient:
     library defaults are applied here, at creation, and only to clients the
     library creates. Passing headers to the constructor replaces just the
     User-Agent, so HTTPX's other default headers survive.
+
+    HTTPX only builds its own environment-proxy mounts when the caller leaves
+    ``transport=None`` (``allow_env_proxies = trust_env and transport is
+    None`` in ``httpx.Client.__init__``). Passing ``transport=`` here, which
+    is required to install the retry transport, would otherwise silently
+    disable ``HTTP_PROXY`` / ``HTTPS_PROXY`` / ``ALL_PROXY`` / ``NO_PROXY``
+    support for every library-created async client (issue #324). This
+    rebuilds that discovery from the stdlib (see ``_env_proxies.py``) and
+    passes it through HTTPX's public ``mounts=`` argument instead, wrapping
+    every proxy transport in the same retry transport the direct path uses,
+    so a request routed through a proxy still gets library retries.
+
+    Environment discovery always runs here, matching the ``trust_env=True``
+    default a caller gets from a plain ``httpx.AsyncClient()``. Neither
+    ``AsyncMlb`` nor ``AsyncMlbDataAdapter`` exposes a ``trust_env`` toggle;
+    a caller who needs one injects their own client instead, the same way
+    they would opt into any other HTTPX-level setting this factory does not
+    surface.
+
+    One retry policy instance is shared by the direct transport and every
+    proxy transport, mirroring the sync side sharing one Session across the
+    v1 and v1.1 adapters: retries are a property of the client, not of any
+    one transport within it.
     """
+    retry_policy = create_retry_policy()
+    direct = MlbAsyncRetryTransport(
+        httpx.AsyncHTTPTransport(), retry_policy=retry_policy
+    )
+
+    mounts: dict[str, httpx.AsyncBaseTransport | None] = {}
+    for pattern, proxy in environment_proxy_map().items():
+        if proxy is None:
+            # None tells HTTPX to fall back to client._transport for this
+            # pattern (see AsyncClient._transport_for_url), i.e. bypass the
+            # proxy rather than route through a second transport instance.
+            # aclose() also skips a None mount, so this never gets closed
+            # twice via both the direct transport and a mount entry.
+            mounts[pattern] = None
+        else:
+            mounts[pattern] = MlbAsyncRetryTransport(
+                httpx.AsyncHTTPTransport(proxy=proxy), retry_policy=retry_policy
+            )
+
     return httpx.AsyncClient(
         headers={"User-Agent": _build_user_agent()},
-        transport=MlbAsyncRetryTransport(),
+        transport=direct,
+        mounts=mounts,
     )

mlbstatsapi/_env_proxies.py

@@ -0,0 +1,81 @@
+"""Build an HTTPX-compatible proxy mount map from the environment.
+
+HTTPX only discovers ``HTTP_PROXY`` / ``HTTPS_PROXY`` / ``ALL_PROXY`` /
+``NO_PROXY`` for itself when it builds its own transport, which happens only
+when the caller does not pass ``transport=`` (see ``allow_env_proxies =
+trust_env and transport is None`` in ``httpx.Client.__init__``). The async
+retry transport (``_async_transport.py``) always passes ``transport=``, so
+that discovery never runs, and environment proxy support silently disappears
+for library-created async clients (issue #324).
+
+This module reimplements that discovery from the stdlib and hands the result
+to HTTPX's public ``mounts=`` argument instead, so the library stays off
+HTTPX's private ``httpx._utils.get_environment_proxies``. The parsing here
+intentionally mirrors that private function's semantics, verified against
+installed httpx 0.28.1. The differential test in
+``tests/test_async_env_proxies.py`` (``test_matches_stock_httpx_env_proxy_resolution``)
+is the drift alarm: it resolves the same URLs against a stock
+``httpx.AsyncClient()`` and against this module's output on every run, so a
+future httpx release changing ``NO_PROXY`` or proxy semantics fails that test
+instead of silently diverging.
+
+No httpx import here: environment variables in, a plain ``dict`` out.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from urllib.request import getproxies
+
+
+def environment_proxy_map(*, trust_env: bool = True) -> dict[str, str | None]:
+    """Return an HTTPX ``mounts=``-shaped map of proxies from the environment.
+
+    Keys are URL patterns such as ``"https://"`` or ``"all://*mlb.com"``; a
+    ``None`` value means "bypass the proxy for this pattern" and is meaningful
+    only when a broader pattern (from ``ALL_PROXY``) would otherwise match.
+    """
+    if not trust_env:
+        return {}
+
+    proxy_info = getproxies()
+    mounts: dict[str, str | None] = {}
+
+    for scheme in ("http", "https", "all"):
+        value = proxy_info.get(scheme)
+        if value:
+            mounts[f"{scheme}://"] = value if "://" in value else f"http://{value}"
+
+    no_proxy_hosts = [host.strip() for host in proxy_info.get("no", "").split(",")]
+    for hostname in no_proxy_hosts:
+        if hostname == "*":
+            return {}
+        elif hostname:
+            if "://" in hostname:
+                mounts[hostname] = None
+            elif _is_ipv4(hostname):
+                mounts[f"all://{hostname}"] = None
+            elif _is_ipv6(hostname):
+                mounts[f"all://[{hostname}]"] = None
+            elif hostname.lower() == "localhost":
+                mounts[f"all://{hostname}"] = None
+            else:
+                mounts[f"all://*{hostname}"] = None
+
+    return mounts
+
+
+def _is_ipv4(hostname: str) -> bool:
+    try:
+        ipaddress.IPv4Address(hostname.split("/")[0])
+    except ValueError:
+        return False
+    return True
+
+
+def _is_ipv6(hostname: str) -> bool:
+    try:
+        ipaddress.IPv6Address(hostname.split("/")[0])
+    except ValueError:
+        return False
+    return True