more httpx documentation

Author: proxymesh

docs/httpx.rst

@@ -1,7 +1,7 @@
 httpx
 =====
 
-The `httpx <https://www.python-httpx.org/>`_ library is a modern HTTP client for Python with support for both sync and async requests. This page describes how to use httpx with proxies and how to interact with proxy headers.
+`HTTPX <https://www.python-httpx.org/>`_ is a fully featured HTTP client for Python 3, which provides sync and async APIs, and support for both HTTP/1.1 and HTTP/2. This page describes how to use httpx with proxies and how to interact with proxy headers.
 
 Using Proxies with httpx
 ------------------------
@@ -11,7 +11,7 @@ httpx provides built-in support for proxies through the ``httpx.Proxy`` class. Y
 Basic Proxy Usage
 ~~~~~~~~~~~~~~~~~
 
-httpx also supports proxy headers by default, though it's not documented. You can use the ``httpx.Proxy`` class with custom headers:
+httpx supports sending proxy headers by default, though it's not documented. You can use the ``httpx.Proxy`` class with custom headers:
 
 .. code-block:: python
 
@@ -27,7 +27,7 @@ This creates a proxy with custom headers and uses it with an httpx client.
 Receiving Proxy Response Headers
 ---------------------------------
 
-But to get the response headers, you need to use our extension module ``python_proxy_headers.httpx_proxy``:
+But to get response headers from a proxy server, you need to use our extension module ``python_proxy_headers.httpx_proxy``:
 
 .. code-block:: python
 
@@ -40,12 +40,12 @@ But to get the response headers, you need to use our extension module ``python_p
    
    r.headers['X-ProxyMesh-IP']
 
-The ``HTTPProxyTransport`` from our extension module extends the standard transport to make proxy response headers available in the response headers.
+The ``HTTPProxyTransport`` class from our extension module extends the standard transport to make proxy response headers available in the response headers.
 
 Helper Methods
 --------------
 
-This module also provides helper methods similar to requests for convenience:
+This module also provides helper methods similar to ``requests`` for convenience:
 
 .. code-block:: python
 
@@ -136,13 +136,50 @@ For simpler use cases, you can use the helper methods:
    # POST request
    r = httpx_proxy.post('https://api.example.com', json={'key': 'value'}, proxy=proxy)
    
+   # PUT request
+   r = httpx_proxy.put('https://api.example.com/resource/1', json={'name': 'updated'}, proxy=proxy)
+   
+   # PATCH request
+   r = httpx_proxy.patch('https://api.example.com/resource/1', json={'status': 'active'}, proxy=proxy)
+   
+   # DELETE request
+   r = httpx_proxy.delete('https://api.example.com/resource/1', proxy=proxy)
+   
+   # HEAD request
+   r = httpx_proxy.head('https://api.example.com', proxy=proxy)
+   
+   # OPTIONS request
+   r = httpx_proxy.options('https://api.example.com', proxy=proxy)
+   
    # Access proxy response headers
    proxy_ip = r.headers.get('X-ProxyMesh-IP')
 
+Streaming Responses
+~~~~~~~~~~~~~~~~~~~~
+
+For streaming large responses, you can use the ``stream`` context manager:
+
+.. code-block:: python
+
+   import httpx
+   from python_proxy_headers import httpx_proxy
+   
+   proxy = httpx.Proxy('http://PROXYHOST:PORT', headers={'X-ProxyMesh-Country': 'US'})
+   
+   with httpx_proxy.stream('GET', 'https://api.example.com/large-file', proxy=proxy) as response:
+       # Access proxy response headers
+       proxy_ip = response.headers.get('X-ProxyMesh-IP')
+       print(f"Proxy IP: {proxy_ip}")
+       
+       # Stream the response content
+       for chunk in response.iter_bytes():
+           # Process each chunk as it arrives
+           print(f"Received {len(chunk)} bytes")
+
 Proxy Headers Overview
 ----------------------
 
-Proxy headers are custom HTTP headers that can be used to communicate with proxy servers. They allow you to:
+Proxy headers are custom HTTP headers that can be used to communicate with proxy servers. They can allow you to:
 
 * **Control proxy behavior**: Send headers like ``X-ProxyMesh-Country`` to select a specific country for your proxy connection
 * **Receive proxy information**: Get headers like ``X-ProxyMesh-IP`` to know which IP address was assigned to your request
@@ -153,5 +190,39 @@ The exact headers available depend on your proxy provider. Check your proxy prov
 httpcore Integration
 --------------------
 
-Our httpx helper module internally provides extension classes for `httpcore <https://www.encode.io/httpcore/>`_, for handling proxy headers over tunnel connections. You can use those classes if you're building on top of httpcore directly.
+Our httpx helper module internally provides extension classes for `httpcore <https://www.encode.io/httpcore/>`_, for handling proxy headers over tunnel connections. These classes extend httpcore's internal proxy implementation to capture and merge proxy response headers.
+
+Extension Classes
+~~~~~~~~~~~~~~~~~
+
+The module provides four main extension classes:
+
+* ``ProxyTunnelHTTPConnection`` - Extends ``httpcore._sync.http_proxy.TunnelHTTPConnection`` to merge proxy response headers from the CONNECT response into the final HTTP response
+* ``AsyncProxyTunnelHTTPConnection`` - Async version that extends ``httpcore._async.http_proxy.AsyncTunnelHTTPConnection``
+* ``HTTPProxyHeaders`` - Extends ``httpcore._sync.http_proxy.HTTPProxy`` to use the custom tunnel connection classes for HTTPS connections
+* ``AsyncHTTPProxyHeaders`` - Async version that extends ``httpcore._async.http_proxy.AsyncHTTPProxy``
+
+These classes are used internally by ``HTTPProxyTransport`` and ``AsyncHTTPProxyTransport``. They automatically merge proxy response headers (like ``X-ProxyMesh-IP``) from the CONNECT response into the final HTTP response headers, making them accessible to your application.
+
+How It Works
+~~~~~~~~~~~~
+
+The extension classes work by intercepting the CONNECT request/response cycle during tunnel establishment:
+
+1. **CONNECT Request**: When establishing a tunnel connection through the proxy, ``ProxyTunnelHTTPConnection`` sends the CONNECT request with your custom proxy headers (e.g., ``X-ProxyMesh-Country: US``)
+
+2. **CONNECT Response**: The proxy responds with a CONNECT response (status 200) that may include proxy information headers in the response (e.g., ``X-ProxyMesh-IP: 192.168.1.1``)
+
+3. **Header Merging**: These proxy response headers are captured during the tunnel establishment and stored. When the actual HTTP request is made through the tunnel, the proxy response headers are merged into the final HTTP response headers using ``merge_headers()``
+
+4. **Access**: Your application can then access both the target server's response headers and the proxy's response headers from the same response object
+
+This is particularly useful for proxy services that provide metadata about the proxy connection (such as the assigned IP address, country, or session information) in the CONNECT response headers.
+
+Internal Usage
+~~~~~~~~~~~~~~
+
+These classes are used internally by ``HTTPProxyTransport`` and ``AsyncHTTPProxyTransport``. When you create a transport with a proxy, it automatically uses ``HTTPProxyHeaders`` (or ``AsyncHTTPProxyHeaders``) as the connection pool, which in turn uses ``ProxyTunnelHTTPConnection`` (or ``AsyncProxyTunnelHTTPConnection``) for HTTPS tunnel connections.
+
+If you're building custom functionality on top of httpcore, you can import and use these classes directly, but note that they depend on httpcore's internal APIs which may change between versions.