PycURL¶

The pycurl_proxy module provides proxy header support for PycURL.

Installation¶

First, install PycURL:

pip install pycurl

Then you can use the proxy header extension.

Usage¶

Low-Level Helpers (for existing pycurl code)¶

If you already have pycurl code, you can add proxy header support with minimal changes:

import pycurl
from python_proxy_headers.pycurl_proxy import set_proxy_headers, HeaderCapture

c = pycurl.Curl()
c.setopt(pycurl.URL, 'https://httpbin.org/ip')
c.setopt(pycurl.PROXY, 'http://proxy.example.com:8080')

# Add custom headers to send to the proxy
set_proxy_headers(c, {'X-ProxyMesh-Country': 'US'})

# Capture response headers (installs HEADERFUNCTION callback)
capture = HeaderCapture(c)

c.perform()

# Access headers from the proxy's CONNECT response
print(capture.proxy_headers)   # {'X-ProxyMesh-IP': '1.2.3.4', ...}
print(capture.proxy_status)    # 200

# Access headers from the origin server
print(capture.origin_headers)  # {'Content-Type': 'application/json', ...}

c.close()

High-Level Convenience Functions¶

For simpler use cases, use the module-level functions:

from python_proxy_headers.pycurl_proxy import get

response = get(
    'https://httpbin.org/ip',
    proxy='http://proxy.example.com:8080',
    proxy_headers={'X-ProxyMesh-Country': 'US'}
)

print(response.status_code)
print(response.text)
print(response.proxy_headers)

API Reference¶

Low-Level Functions¶

set_proxy_headers(curl, headers)¶

Set custom headers to send to the proxy server during CONNECT.

Parameters:

curl – A pycurl.Curl instance
headers – Dict of headers to send to the proxy

class HeaderCapture(curl=None)¶

Captures and parses HTTP response headers from pycurl requests.

Parameters:: curl – Optional pycurl.Curl instance. If provided, automatically installs the HEADERFUNCTION callback.

install(curl)¶

Install the header callback on a pycurl.Curl instance.

Parameters:: curl – A pycurl.Curl instance
Returns:: self, for chaining

reset()¶: Clear captured headers for reuse.

proxy_headers: dict¶: Headers from the proxy’s CONNECT response.

proxy_status: int or None¶: Status code from the proxy’s CONNECT response.

origin_headers: dict¶: Headers from the origin server’s response.

origin_status: int or None¶: Status code from the origin server’s response.

all_headers: dict¶: All headers merged (proxy headers first, then origin).

High-Level Functions¶

request(method, url, proxy=None, proxy_headers=None, headers=None, data=None, timeout=None, verify=True)¶

Make an HTTP request with proxy header support.

Parameters:

method – HTTP method (GET, POST, etc.)
url – Target URL
proxy – Proxy URL (e.g., ‘http://user:pass@proxy:8080’)
proxy_headers – Headers to send to the proxy
headers – Headers to send to the origin server
data – Request body for POST/PUT/PATCH
timeout – Request timeout in seconds
verify – Whether to verify SSL certificates

Returns:

Response object

get(url, **kwargs)¶

post(url, **kwargs)¶

put(url, **kwargs)¶

delete(url, **kwargs)¶

head(url, **kwargs)¶

patch(url, **kwargs)¶

Response Class¶

class Response¶

Response object from high-level API.

status_code: int¶: HTTP status code from the origin server.

headers: dict¶: Headers from the origin server response.

content: bytes¶: Response body as bytes.

proxy_headers: dict¶: Headers from the proxy’s CONNECT response (HTTPS only).

proxy_status: int or None¶: Status code from the proxy’s CONNECT response (HTTPS only).

text: str¶: Response body decoded as UTF-8.

raise_for_status()¶: Raise an exception if the status code indicates an error.