System settings

`proxylib.system`

This machine's proxy settings.

:func:auto_proxy -- the proxy map a program should use: the proxy environment variables when any is set, else the OS's own resolver backed by the OS settings.
:func:system_config -- the OS or desktop settings, as a :class:ProxyConfig.
:class:WinHTTPProxyMap, :class:CFNetworkProxyMap, :class:LibProxyMap -- the OS resolvers (Windows, macOS, libproxy).

`all = ('CFNetworkProxyMap', 'LibProxyMap', 'ProxyConfig', 'WinHTTPProxyMap', 'auto_proxy', 'system_config')` `module-attribute`

`CFNetworkProxyMap(deadline=5.0)`

Bases: ProxyMap

A proxy map answered by macOS's resolver (CFNetworkCopyProxiesForURL).

CFNetwork applies the system's bypass list itself and runs a configured PAC (CFNetworkExecuteProxyAutoConfigurationURL), so no JS engine is needed. A PAC run is bounded by deadline seconds; when it overruns, or CFNetwork cannot answer, the lookup has no opinion (KeyError) rather than DIRECT, so a chain can ask the next map. macOS only: off it, every lookup raises KeyError.

Source code in src/proxylib/system/_darwin.py

def __init__(self, deadline: float = 5.0) -> None:
    self.deadline = deadline

`slots = ('deadline',)` `class-attribute` `instance-attribute`

`deadline = deadline` `instance-attribute`

`getitem(url)`

Source code in src/proxylib/system/_darwin.py

def __getitem__(self, url: str) -> "Tuple[Optional[Proxy], ...]":
    entries = _resolve_proxies_for_url(url, self.deadline)
    if entries is None:
        raise KeyError(url)
    return tuple(Proxy.parse(entry) if entry else None for entry in entries) or (None,)

`repr()`

Source code in src/proxylib/system/_darwin.py

def __repr__(self) -> str:
    return f"CFNetworkProxyMap(deadline={self.deadline!r})"

`close()`

Nothing to free: CFNetwork state is per lookup.

Source code in src/proxylib/system/_darwin.py

def close(self) -> None:
    """Nothing to free: CFNetwork state is per lookup."""

`LibProxyMap(lib=None)`

Bases: ProxyMap

A proxy map answered by libproxy (px_proxy_factory_get_proxies).

lib is the loaded library; by default it is found on the linker path. When libproxy is not installed, or cannot answer, a lookup has no opinion (KeyError) rather than DIRECT.

One libproxy factory, made on the first lookup, serves every lookup so its PAC and settings caches are reused; :meth:close releases it (garbage collection does too).

Source code in src/proxylib/system/_posix/_libproxy.py

def __init__(self, lib: "Optional[ctypes.CDLL]" = None) -> None:
    self._lib = lib if lib is not None else _get_libproxy()
    self._factory = None
    self._lock = threading.Lock()

`slots = ('_lib', '_factory', '_lock')` `class-attribute` `instance-attribute`

`del()`

Source code in src/proxylib/system/_posix/_libproxy.py

def __del__(self) -> None:
    try:
        self.close()
    except AttributeError:  # __init__ did not finish
        pass

`getitem(uri)`

Source code in src/proxylib/system/_posix/_libproxy.py

def __getitem__(self, uri: str) -> "Tuple[Optional[Proxy], ...]":
    lib = self._lib
    if lib is None:
        raise KeyError(uri)

    with self._lock:
        if not self._factory:
            self._factory = lib.px_proxy_factory_new()
        if not self._factory:
            raise KeyError(uri)
        proxies_array = lib.px_proxy_factory_get_proxies(self._factory, uri.encode("utf-8"))
    if not proxies_array:
        # libproxy failed to answer, which is not a DIRECT decision.
        raise KeyError(uri)
    try:
        results: "list[Optional[Proxy]]" = []
        i = 0
        while proxies_array[i] is not None:
            entry = proxies_array[i].decode("utf-8")
            results.append(None if entry.startswith("direct://") else Proxy.parse(entry))
            i += 1
        return tuple(results) or (None,)
    finally:
        lib.px_proxy_factory_free_proxies(proxies_array)

`close()`

Source code in src/proxylib/system/_posix/_libproxy.py

def close(self) -> None:
    with self._lock:
        factory, self._factory = self._factory, None
    if factory and self._lib is not None:
        self._lib.px_proxy_factory_free(factory)

`ProxyConfig(source='none', state='unset', auto_detect=False, pac_url=None, pac_script=None, proxies=dict(), bypass=BypassRules.NONE)` `dataclass`

This machine's proxy settings, as one OS or desktop stores them.

source names where they were read: "windows", "macos", "gnome", "mate", "kde", "networkmanager", or "none". state is "direct" when the settings say to use no proxy, "configured" when they name auto-detection, a PAC or a proxy, and "unset" when there were no settings to read.

proxies maps a request scheme (http, https, ftp) to the proxy for it, and "socks" to the proxy for every scheme without its own entry; a string value is parsed with :meth:Proxy.parse. bypass applies to those proxies only, as it does on every OS.

`auto_detect = False` `class-attribute` `instance-attribute`

`bypass = BypassRules.NONE` `class-attribute` `instance-attribute`

`pac_script = None` `class-attribute` `instance-attribute`

`pac_url = None` `class-attribute` `instance-attribute`

`proxies = field(default_factory=dict)` `class-attribute` `instance-attribute`

`source = 'none'` `class-attribute` `instance-attribute`

`state = 'unset'` `class-attribute` `instance-attribute`

`__post_init__()`

Source code in src/proxylib/system/_config.py

def __post_init__(self) -> None:
    if self.state not in _STATES:
        raise ValueError(f"state must be one of {_STATES}, not {self.state!r}")
    proxies = {
        key.lower(): value if isinstance(value, Proxy) else Proxy.parse(value)
        for key, value in self.proxies.items()
    }
    object.__setattr__(self, "proxies", MappingProxyType(proxies))

`to_proxymap(*, wpad=False, timeout=10.0, on_missing_engine='raise')`

The proxy map these settings describe.

Sources are asked in the order browsers use: auto-detection (WPAD), the PAC, then the proxies. A source that fails -- no WPAD server, a PAC that does not download or run -- passes to the next and is tried again after 30 s; when none answers, the answer is DIRECT. WPAD runs only when auto_detect is set, or when wpad is true and the state is "unset"; a "direct" state is DIRECT for every URL. Nothing is fetched until the first lookup.

timeout bounds each WPAD probe and PAC download. on_missing_engine is as for :class:~proxylib.PacScript.

Source code in src/proxylib/system/_config.py

def to_proxymap(
    self, *, wpad: bool = False, timeout: float = 10.0, on_missing_engine: str = "raise"
) -> ProxyMap:
    """The proxy map these settings describe.

    Sources are asked in the order browsers use: auto-detection (WPAD),
    the PAC, then the proxies. A source that fails -- no WPAD server, a
    PAC that does not download or run -- passes to the next and is tried
    again after 30 s; when none answers, the answer is DIRECT. WPAD runs
    only when ``auto_detect`` is set, or when ``wpad`` is true and the
    state is ``"unset"``; a ``"direct"`` state is DIRECT for every URL.
    Nothing is fetched until the first lookup.

    ``timeout`` bounds each WPAD probe and PAC download.
    ``on_missing_engine`` is as for :class:`~proxylib.PacScript`.
    """
    if self.state == "direct":
        return SimpleProxyMap()
    maps: "List[ProxyMap]" = []
    if self.auto_detect or (wpad and self.state == "unset"):
        from ..pac import wpad as _wpad

        maps.append(
            _Deferred(
                "WPAD",
                functools.partial(_wpad.discover, timeout=timeout, on_missing_engine=on_missing_engine),
            )
        )
    if self.pac_url:
        from .. import pac

        maps.append(
            _Deferred(
                self.pac_url,
                functools.partial(pac.load, self.pac_url, timeout=timeout, on_missing_engine=on_missing_engine),
            )
        )
    if self.pac_script:
        from .. import pac

        maps.append(
            _Deferred(
                "the PAC script", functools.partial(pac.loads, self.pac_script, on_missing_engine=on_missing_engine)
            )
        )
    maps.append(manual_map(self.proxies, self.bypass))
    return maps[0] if len(maps) == 1 else ChainProxyMap(*maps)

`WinHTTPProxyMap()`

Bases: ProxyMap

A proxy map answered by WinHTTP's resolver (WinHttpGetProxyForUrl).

WinHTTP does the WPAD discovery (DHCP and DNS), fetches the PAC with the user's NTLM/Kerberos credentials when challenged, and runs it, so no JS engine is needed. When the settings name neither auto-detection nor a PAC, or WinHTTP fails, the manual proxy settings answer; with none, DIRECT.

One WinHTTP session serves every lookup, and WinHTTP caches PAC results per session; :meth:close releases it (garbage collection does too). After close a lookup has no opinion (KeyError). Windows only: construction raises OSError elsewhere.