PAC support

`proxylib.pac`

PAC (Proxy Auto-Config) support: the standard Netscape utility functions a PAC script's FindProxyForURL relies on, plus the common Microsoft *Ex/IPv6-aware extensions, and loading PAC scripts (as plain Python via subclassing, or as real JS via the optional dukpy backend).

`all = ('PAC', 'load', 'clear_download_cache', 'clear_dns_cache')` `module-attribute`

`JSProxyAutoConfig(js, overrides=None)`

Bases: PAC, JSContext

A PAC whose FindProxyForURL (and the utility functions above) run as real JS.

Source code in src/proxylib/pac/javascript.py

def __init__(self, js: str, overrides: "Optional[Dict[str, Callable]]" = None) -> None:
    context: dict = object.__getattribute__(self, "_JSCONTEXT")
    if overrides:
        context = dict(context)
        # Wrapped as staticmethod so the binding loop below treats them
        # exactly like the class's own PAC utility functions (unwrapped
        # via val.__func__, no `self` bound) -- overrides are plain
        # standalone callables (e.g. `lambda host: "10.0.0.1"`), not
        # instance methods, so val.__get__(self) below would wrongly
        # bind `self` as an implicit first argument otherwise.
        context.update({key: staticmethod(fn) for key, fn in overrides.items()})
        # Stored per-instance, not mutated on the shared class-level
        # _JSCONTEXT, so overrides from one instance don't leak into
        # another's -- __getattribute__ below picks this up too, so an
        # override key that isn't one of the base PAC methods is still
        # recognized as exported.
        object.__setattr__(self, "_JSCONTEXT", context)
    engine_cls = get_engine_class()
    if engine_cls is None:
        raise ImportError(
            "No PAC JS engine is installed -- install one of the optional "
            "extras: proxylib[jspac] (dukpy) or proxylib[quickjs]."
        )
    engine = engine_cls()
    for key, val in context.items():
        if isinstance(val, staticmethod):
            val = val.__func__
        elif isinstance(val, classmethod):
            val = val.__get__(self.__class__)
        elif isinstance(val, property):
            raise NotImplementedError("JSContext does not support property exports yet")
        else:
            val = val.__get__(self)

        engine.export_function(key, val)
    engine.eval(js)

    # Pre-bind one callable per exported name now, instead of allocating
    # a fresh closure on every attribute access. Each one still calls
    # engine.call(key, ...), which resolves `key` fresh in the JS
    # engine's *global scope* at call time (not at bind time) -- that's
    # what actually implements "JS override wins": if `js` redefined
    # `key`, the engine resolves to that redefinition regardless of
    # when this Python-side wrapper was created. A naive
    # `object.__setattr__(self, key, jsFunction)` here would never be
    # reached, though -- __getattribute__ below checks membership in
    # `context` *before* ever falling through to instance-attribute
    # lookup, so the bound callables live in their own dict instead.
    bound: "Dict[str, object]" = {}
    for key in context:

        def _make_js_function(key=key):
            def jsFunction(*args):
                return engine.call(key, *args)

            return jsFunction

        bound[key] = _make_js_function()

    object.__setattr__(self, "_jsengine", engine)
    object.__setattr__(self, "_bound_js_functions", bound)

`PAC`

Bases: object

Base implementation of the PAC utility-function namespace.

FindProxyForURL here always returns "DIRECT"; subclass and override it (or use :class:JSProxyAutoConfig to run a real PAC script) to actually select proxies.