more urllib3 docs

Author: proxymesh

docs/urllib3.rst

@@ -36,7 +36,7 @@ The ``proxy_headers`` parameter allows you to send custom headers to the proxy s
 
 .. note::
 
-   When using this method, if you keep reusing the same ``ProxyManager`` instance, you may be re-using the proxy connection, which may have different behavior than if you create a new proxy connection for each request. For example, with ProxyMesh you may keep getting the same IP address if you reuse the proxy connection.
+   When using this method, if you keep reusing the same ``ProxyManager`` instance, you may be re-using the proxy connection, which may have different behavior than if you create a new proxy connection for each request. For example, with `ProxyMesh <https://proxymesh.com>`_ you may keep getting the same IP address if you reuse the proxy connection.
 
 Receiving Proxy Response Headers
 ---------------------------------
@@ -66,6 +66,21 @@ You can also pass ``proxy_headers`` into our ``ProxyHeaderManager`` as well. For
 
 This allows you to both send custom headers to the proxy and receive proxy response headers in a single request.
 
+Helper Function
+~~~~~~~~~~~~~~~
+
+The module also provides a convenience function for creating a ``ProxyHeaderManager``:
+
+.. code-block:: python
+
+   from python_proxy_headers.urllib3_proxy_manager import proxy_from_url
+   
+   proxy = proxy_from_url('http://PROXYHOST:PORT', proxy_headers={'X-ProxyMesh-Country': 'US'})
+   r = proxy.request('GET', 'https://api.ipify.org?format=json')
+   r.headers['X-ProxyMesh-IP']
+
+The ``proxy_from_url()`` function is a convenience wrapper around ``ProxyHeaderManager`` that creates a proxy manager from a URL string, similar to urllib3's standard ``proxy_from_url()`` function.
+
 Proxy Headers Overview
 ----------------------
 
@@ -77,3 +92,36 @@ Proxy headers are custom HTTP headers that can be used to communicate with proxy
 
 The exact headers available depend on your proxy provider. Check your proxy provider's documentation for the specific headers they support.
 
+Internal Classes
+----------------
+
+The ``ProxyHeaderManager`` internally uses extension classes that extend urllib3's connection and connection pool classes:
+
+* ``HTTPSProxyConnection`` - Extends ``urllib3.connection.HTTPSConnection`` to capture proxy response headers from the CONNECT response
+* ``HTTPSProxyConnectionPool`` - Extends ``urllib3.connectionpool.HTTPSConnectionPool`` to merge proxy response headers into the final HTTP response
+
+These classes work together to make proxy response headers available in your application's response object.
+
+HTTPSProxyConnection
+~~~~~~~~~~~~~~~~~~~~
+
+The ``HTTPSProxyConnection`` class extends the standard ``HTTPSConnection`` to capture proxy response headers during tunnel establishment. When a CONNECT request is made to establish the tunnel, it:
+
+1. Sends the CONNECT request with any custom proxy headers
+2. Reads the CONNECT response from the proxy server
+3. Captures the proxy response headers (e.g., ``X-ProxyMesh-IP``)
+4. Stores them for later retrieval via ``get_proxy_response_headers()``
+
+The ``get_proxy_response_headers()`` method returns a dictionary containing the headers from the proxy's CONNECT response, or ``None`` if the CONNECT request hasn't been sent yet.
+
+HTTPSProxyConnectionPool
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``HTTPSProxyConnectionPool`` class extends ``HTTPSConnectionPool`` to automatically merge proxy response headers into the final HTTP response. It:
+
+1. Uses ``HTTPSProxyConnection`` as its connection class
+2. Captures proxy response headers after preparing the proxy connection
+3. Merges these headers into the response headers when ``urlopen()`` is called
+
+This ensures that proxy response headers are automatically available in the response object returned to your application.
+