System proxy detection

`proxylib.os`

Platform-agnostic system proxy detection.

Dispatches to a per-OS backend (:mod:.nt on Windows, :mod:.darwin on macOS, :mod:.posix elsewhere) and, via :func:auto_proxy, falls back to WPAD discovery (:mod:proxylib.pac.wpad) when the OS/env has no explicit proxy configured.

Both :func:system_proxy and :func:auto_proxy take a provider:

"python" (default): proxylib's own detection + PAC-via-dukpy path -- works everywhere, including sandboxes/testing.
"system": outsources resolution to the OS's native proxy engine (WinHttpProxyMap on Windows, CFNetworkProxyMap on macOS, LibProxyMap on POSIX if its shared library is loadable -- falls back to "python" there if not). These already do their own WPAD/PAC, so :func:auto_proxy doesn't run its own WPAD fallback on top of them.

`all = ('system_proxy', 'auto_proxy')` `module-attribute`

`auto_proxy(provider='python', **urlopen_kwargs)`

Resolve the effective ProxyMap for this machine.

Order: OS-native settings / env vars (:func:system_proxy) → if that yields a PAC URL, load it → if it yields no usable config at all (the "python" provider's own signal for "OS has nothing configured"), try WPAD discovery → otherwise DIRECT.

Source code in src/proxylib/os/__init__.py

def auto_proxy(provider: str = "python", **urlopen_kwargs) -> ProxyMap:
    """Resolve the effective ``ProxyMap`` for this machine.

    Order: OS-native settings / env vars (:func:`system_proxy`) → if that
    yields a PAC URL, load it → if it yields no usable config at all (the
    ``"python"`` provider's own signal for "OS has nothing configured"),
    try WPAD discovery → otherwise DIRECT.
    """
    proxy = system_proxy(provider)
    if isinstance(proxy, str):
        return load_pac(proxy, **urlopen_kwargs)
    if isinstance(proxy, SimpleProxyMap) and proxy[""] == (None,):
        from ..pac.wpad import discover

        discovered = discover(**urlopen_kwargs)
        if discovered is not None:
            return discovered
    return proxy

`system_proxy(provider='python')`

Read this machine's proxy configuration. See the module docstring for what provider means.

Source code in src/proxylib/os/__init__.py

def system_proxy(provider: str = "python") -> "ProxyMap|str":
    """Read this machine's proxy configuration. See the module docstring
    for what ``provider`` means."""
    if provider == "system":
        native = _native_system_provider()
        if native is not None:
            return native
    return _python_system_proxy()

`proxylib.os.nt`

Windows system proxy detection via the WinHTTP "IE proxy config" API.

Uses WinHttpGetIEProxyConfigForCurrentUser (stdlib ctypes, no extra dependency) rather than hand-parsing the registry's undocumented Connections\DefaultConnectionSettings/SavedLegacySettings binary blob. That blob is the underlying data source (its flags DWORD at offset 8 has bit 0x08 set when "Automatically detect settings" is on — verified empirically), but its trailing layout has known version differences across Windows releases; the WinHTTP API is Microsoft's supported way to read the same data without guessing byte offsets. This mirrors what Chromium does.

`all = ('system_proxy', 'WinHttpProxyMap')` `module-attribute`

`WinHttpProxyMap()`

Bases: ProxyMap

A ProxyMap backed by WinHTTP's own autoproxy engine (WinHttpGetProxyForUrl).

Unlike :func:system_proxy's Python-side WPAD/PAC path, this outsources WPAD/DHCP-252 discovery, NTLM/Kerberos SSO for fetching the PAC script, and PAC JS execution itself to WinHTTP -- no dukpy needed on Windows. Falls back to the static manual proxy (from WinHttpGetIEProxyConfigForCurrentUser) when autoproxy isn't configured, or when WinHttpGetProxyForUrl fails; DIRECT if nothing at all is configured.

Reuses one WinHttpOpen session handle for its lifetime (release it with :meth:close, or let garbage collection do it) -- opening a session per lookup would be wasteful, and WinHTTP's own autoproxy result caching is scoped to the session.