PyPAC 0.17.2
Proxy auto-config and auto-discovery for Python.
License: Apache-2.0
Requires Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7
Keywords: pypac, pac, proxy, autoconfig, requests

PyPAC: Proxy auto-config for Python
===================================

.. image:: https://img.shields.io/pypi/v/pypac.svg?maxAge=2592000
    :target: https://pypi.python.org/pypi/pypac
.. image:: https://img.shields.io/pypi/pyversions/pypac.svg
    :target: https://pypi.python.org/pypi/pypac
.. image:: https://readthedocs.org/projects/pypac/badge/?version=latest
    :target: https://pypac.readthedocs.io/en/latest/?badge=latest
.. image:: https://github.com/carsonyl/pypac/actions/workflows/tests.yml/badge.svg
    :target: https://github.com/carsonyl/pypac/actions/workflows/tests.yml

PyPAC is a Python library for finding `proxy auto-config (PAC)`_ files and making HTTP requests
that respect them. PAC files are often used in organizations that need fine-grained and centralized control
of proxy settings.

PyPAC can find PAC files according to the DNS portion of the `Web Proxy Auto-Discovery (WPAD)`_ protocol.
On Windows, PyPAC will automatically get the PAC file URL from the Internet Options dialog.
On macOS, PyPAC will automatically get the PAC file URL from System Preferences.

.. _proxy auto-config (PAC): https://en.wikipedia.org/wiki/Proxy_auto-config

PyPAC provides a subclass of a `Requests <https://docs.python-requests.org/en/latest/>`_ ``Session``,
so you can start using it immediately, with any PAC file transparently discovered and honoured:

.. code-block:: python

    >>> from pypac import PACSession
    >>> session = PACSession()
    >>> session.get('http://example.org')
    ...

If a PAC file isn't found, then ``PACSession`` behaves like a regular ``Session``.

.. _Web Proxy Auto-Discovery (WPAD): https://en.wikipedia.org/wiki/Web_Proxy_Autodiscovery_Protocol

If you're looking to add *basic* PAC functionality to a library that you're using,
try the ``pac_context_for_url()`` context manager:

.. code-block:: python

   from pypac import pac_context_for_url
   import boto3

   with pac_context_for_url('https://example.amazonaws.com'):
       client = boto3.client('sqs')
       client.list_queues()

This sets up proxy environment variables at the start of the scope, based on any auto-discovered PAC and the given URL.
``pac_context_for_url()`` should work for any library
that honours proxy environment variables.


Features
--------

* The same Requests API that you already know and love
* Honour PAC setting from Windows Internet Options and macOS System Preferences
* Follow DNS Web Proxy Auto-Discovery protocol
* Proxy authentication pass-through
* Proxy failover and load balancing
* Generic components for adding PAC support to other code

PyPAC supports Python 2.7 and 3.5+.


Installation
------------

Install PyPAC using `pip <https://pip.pypa.io>`_::

    $ python -m pip install pypac


Documentation
-------------

PyPAC's documentation is available at https://pypac.readthedocs.io/.

0.17.2 (2025-10-11)
-------------------

- Fix URL encoding mismatch in proxy authentication. (#84) Thanks @l4u23n7p.
- Add Python 3.14 to CIB test matrix.

0.17.1 (2025-08-27)
-------------------

- Make ``socks_scheme`` arguments case-insensitive. (#82)
- Avoid DeprecationWarning when using GMT times on Python 3.12+.

0.17.0 (2025-05-31)
-------------------

- Add support for Microsoft IPv6 extension functions in PAC files.
- Fix DeprecationWarning under tldextract >= 5.3.0.

0.16.5 (2024-12-24)
-------------------

- Log warning for rejected PAC content-type. (#79) Thanks @jmkerloch.
- Remove Python 2.7, 3.7 from CIB test matrix.

0.16.4 (2023-04-24)
-------------------

- Release using `Trusted Publishing <https://blog.pypi.org/posts/2023-04-20-introducing-trusted-publishers/>`_.

0.16.3 (2023-03-31)
-------------------

- ``isInNet()``: Return False immediately for invalid host arg. (#71)

0.16.2 (2023-03-26)
-------------------

- Handle boolean args to ``isInNet()``. (#69)
- Remove Python 3.5, 3.6 from CIB test matrix.
- Windows Python 2.7 CIB: Pin to dukpy 0.2.3.


0.16.1 (2022-11-08)
-------------------

- Disable ``tldextract`` caching. (#64) Thanks @mpkuth.


0.16.0 (2022-01-01)
-------------------

- Change ``tld`` dependency to ``tldextract``. (#61)


0.15.0 (2021-02-27)
-------------------

- Drop support for Python 3.4. (#48)
- Support more proxy keywords: HTTP, HTTPS, SOCKS4, SOCKS5. (#41)
- Absorb any exception from ``tld.get_tld()``, not just TldDomainNotFound. (#30) Thanks @santiavenda2.
- Reimplement ``dnsDomainIs(host, domain)`` as case-insensitive 'host ends with domain'. (#42, #57)


0.14.0 (2020-12-05)
-------------------

- Add ability to supply ``PACFile`` to ``pac_context_for_url()``. (#52) Thanks @alexrohvarger.


0.13.0 (2019-09-16)
-------------------

- Make it possible to configure the request for the PAC file. (#44) Thanks @SeyfSV.
- urlencode proxy username and password. (#46) Thanks @aslafy-z.


0.12.0 (2018-09-11)
-------------------

- Fix possible error when ``dnsResolve()`` fails. (#34) Thanks @maximinus.


0.11.0 (2018-09-08)
-------------------

- Require dukpy 0.2.2, to fix memory leak. (#32) Thanks @maximinus.
- Change Mac environment marker. (#30)
- Support Python 3.7.


0.10.1 (2018-08-26)
-------------------

- Require tld 0.9.x. (#29)


0.10.0 (2018-08-26)
-------------------

- Switch JavaScript interpreter to dukpy. (#24)
- Fix ``pac_context_for_url()`` erroring with ``DIRECT`` PAC setting. (#27)
- Fix warning about invalid escape sequence (#26). Thanks @BoboTiG.


0.9.0 (2018-06-02)
------------------

- Add macOS support for PAC in System Preferences (#23). Thanks @LKleinNux.
- The `from_registry` argument on `pypac.get_pac()` and `pypac.collect_pac_urls()`
  is now deprecated and will be removed in 1.0.0. Use `from_os_settings` instead.


0.8.1 (2018-03-01)
------------------

- Defer Js2Py import until it's needed. It uses a lot of memory.
  See #20 for details.


0.8.0 (2018-02-28)
------------------

- Add support for ``file://`` PAC URLs on Windows.


0.7.0 (2018-02-21)
------------------

- Drop support for Python 3.3.
- Add doc explaining how to use ``pac_context_for_url()``.
- Internal changes to dev and test processes.


0.6.0 (2018-01-28)
------------------

- Add ``pac_context_for_url()``, a context manager that adds basic PAC functionality
  through proxy environment variables.


0.5.0 (2018-01-18)
------------------

- Accept PAC files served with no ``Content-Type`` header.


0.4.0 (2017-11-07)
------------------

- Add ``recursion_limit`` keyword argument to ``PACSession`` and ``PACFile``.
  The default is an arbitrarily high value (10000), which should cover most applications.
- Exclude port numbers from ``host`` passed to ``FindProxyForURL(url, host)``.


0.3.1 (2017-06-23)
------------------

- Update GitHub username.


0.3.0 (2017-04-12)
------------------
- Windows: Get system auto-proxy config setting using ``winreg`` module.
- Windows: Accept local filesystem paths from system proxy auto-config setting.
- Raise ``PacComplexityError`` when recursion limit is hit while parsing PAC file.
- Support setting ``PACSession.proxy_auth`` and ``ProxyResolver.proxy_auth`` after constructing an instance.
- Narrative docs.


0.2.1 (2017-01-19)
------------------

- Require Js2Py >= 0.43 for Python 3.6 support, and to avoid needing to monkeypatch out ``pyimport``.


0.1.0 (2016-06-12)
------------------

- First release.