https://github.com/python/cpython/commit/03b2b51afdcd02442973e5b922951a696d441fc0
commit: 03b2b51afdcd02442973e5b922951a696d441fc0
branch: 3.15
author: Miss Islington (bot) <[email protected]>
committer: orsenthil <[email protected]>
date: 2026-11-11T05:35:23Z
summary:

[3.15] gh-52330 Document how a proxy auto-config (PAC) file can be used with 
urllib.request.ProxyHandler (GH-161729) (#161795)

gh-52330 Document how a proxy auto-config (PAC) file can be used with 
urllib.request.ProxyHandler (GH-161729)

We will point to the pypi package pypac which supports PAC discovery and
can be extended as a custom ProxyHandler to be used with urllib.request.

The documentation will point to the pypi package and share high-level
example of using this.
(cherry picked from commit 3cf810dc084b64b4d6a78bde02ed19d3f4015ab3)

Co-authored-by: Senthil Kumaran <[email protected]>

files:
M Doc/library/urllib.request.rst

diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 2f942ed9439b32..4de3876080c958 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -378,6 +378,11 @@ The following classes are provided:
       ``HTTP_PROXY`` will be ignored if a variable ``REQUEST_METHOD`` is set;
       see the documentation on :func:`~urllib.request.getproxies`.
 
+   Because *proxies* holds at most one proxy for each protocol, it cannot
+   use a proxy auto-config (PAC) file, which selects a proxy for each
+   URL.  See :ref:`this example <urllib-request-pac>` for one way to use a
+   PAC file.
+
 
 .. class:: HTTPPasswordMgr()
 
@@ -1382,6 +1387,51 @@ programmatically supplied proxy URLs, and adds proxy 
authorization support with
    with opener.open('http://www.example.com/login.html') as f:
       print(f.read().decode('utf-8'))
 
+.. _urllib-request-pac:
+
+Proxy auto-config (PAC) files select a proxy for each URL, so they cannot be
+described by the *proxies* mapping that :class:`ProxyHandler` expects.  The
+:pypi:`pypac` package finds and evaluates PAC files; its ``ProxyResolver``
+can be used to write a handler that consults the PAC file once per request::
+
+   import urllib.error
+   import urllib.request
+   from pypac import get_pac
+   from pypac.resolver import ProxyResolver
+
+   class PACProxyHandler(urllib.request.ProxyHandler):
+
+       def __init__(self, resolver):
+           self.resolver = resolver
+           # An empty mapping suppresses the <protocol>_open methods that
+           # ProxyHandler would make from a static proxies mapping.
+           super().__init__({})
+
+       def _pac_open(self, req, protocol):
+           proxy = self.resolver.get_proxy(req.full_url)
+           if proxy is None:
+               raise urllib.error.URLError('no proxy available')
+           if proxy == 'DIRECT':
+               return None  # continue with the remaining handlers
+           if proxy.startswith('socks'):
+               raise urllib.error.URLError('SOCKS proxies are not supported')
+           return self.proxy_open(req, proxy, protocol)
+
+       def http_open(self, req):
+           return self._pac_open(req, 'http')
+
+       def https_open(self, req):
+           return self._pac_open(req, 'https')
+
+   opener = 
urllib.request.build_opener(PACProxyHandler(ProxyResolver(get_pac())))
+   with opener.open('http://www.example.com/') as f:
+       print(f.read().decode('utf-8'))
+
+Note that a PAC file may also select a SOCKS proxy, which :mod:`urllib.request`
+cannot use, and that the :envvar:`no_proxy` environment variable and the
+operating system's proxy bypass list still apply to requests the PAC file
+assigned to a proxy.
+
 Adding HTTP headers:
 
 Use the *headers* argument to the :class:`Request` constructor, or::

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]

Reply via email to