PycURL - A Python Interface To The cURL library

Warnings

• gotcha PycURL is a wrapper around `libcurl`, a system library. Installing PycURL via pip often requires `libcurl` and its development headers (e.g., `libcurl4-openssl-dev` on Debian/Ubuntu, `curl` on macOS via Homebrew) to be present on your system. Without these, installation may fail or lead to runtime errors, especially when building from source.
  Fix: Ensure `libcurl` and its development packages are installed on your system before `pip install pycurl`.
• gotcha SSL backend mismatches can cause runtime `ImportError` (e.g., `pycurl: libcurl link-time ssl backend (...) is different from compile-time ssl backend (...)`). This occurs if PycURL is built against a different SSL library than what `libcurl` uses at runtime.
  Fix: During installation, explicitly tell `setup.py` which SSL backend to use via the `PYCURL_SSL_LIBRARY` environment variable (e.g., `export PYCURL_SSL_LIBRARY=openssl pip install pycurl`) or `setup.py` command-line options.
• gotcha PycURL returns all network data as `bytes` objects. For text content, you must explicitly decode these `bytes` to `str` (e.g., using `.decode('utf-8')`). Conversely, when passing non-ASCII Unicode strings to `setopt` or `READFUNCTION`, they must first be encoded into `bytes` to avoid `UnicodeEncodeError` or `pycurl.error` (e.g., 'read function error/data error').
  Fix: Always decode received `bytes` to `str` for text, and encode `str` to `bytes` when sending non-ASCII data to PycURL. Use `errors='ignore'` or `errors='replace'` during decoding if dealing with unknown/malformed encodings.
• deprecated While `c.setopt(c.WRITEFUNCTION, buffer.write)` still works, as of PycURL 7.19.3, `c.setopt(c.WRITEDATA, buffer)` is generally preferred and simpler as it accepts any Python object with a `write` method (like `io.BytesIO`).
  Fix: Prefer `c.setopt(c.WRITEDATA, buffer)` over `WRITEFUNCTION` when providing a simple writeable object to capture response data.
• breaking The `DEBUGFUNCTION` callback on Python 3 now expects its argument to be `bytes` instead of a (Unicode) `string`.
  Fix: Update `DEBUGFUNCTION` implementations on Python 3 to handle `bytes` arguments.
• breaking The `CURLMOPT_*` option constants, related to the multi interface, were moved from the `Easy` class to the `Multi` class. They remain available in the top-level `pycurl` module for backward compatibility.
  Fix: Access `CURLMOPT_*` constants either directly from the `pycurl` module (e.g., `pycurl.CURLMOPT_PIPELINING`) or from a `CurlMulti` instance (e.g., `multi_handle.CURLMOPT_PIPELINING`).

Install

• pip install pycurl Install PycURL via pip
• sudo apt-get install libcurl4-openssl-dev python3-pycurl Debian/Ubuntu (including libcurl-dev)
• brew install curl macOS (Homebrew, then pip install)

Imports

• pycurl

  import pycurl

• Curl

  import pycurl
  c = pycurl.Curl()

• BytesIO

  from io import BytesIO

  Commonly used with pycurl.WRITEDATA to capture response body in memory.

Quickstart

This quickstart demonstrates how to perform a basic GET request using PycURL. It initializes a Curl object, sets the URL, and uses `io.BytesIO` to capture the response body. Error handling for PycURL specific errors is included. It also highlights an optional step for using `certifi` for robust HTTPS certificate verification.

import pycurl
from io import BytesIO

def fetch_url(url):
    buffer = BytesIO()
    c = pycurl.Curl()
    c.setopt(c.URL, url)
    c.setopt(c.WRITEDATA, buffer)
    # Optional: For HTTPS, use certifi for certificate bundle
    # import certifi
    # c.setopt(c.CAINFO, certifi.where())
    
    try:
        c.perform()
        status_code = c.getinfo(pycurl.RESPONSE_CODE)
        response_body = buffer.getvalue().decode('utf-8', errors='ignore')
        print(f"Status Code: {status_code}")
        print(f"Response Body (first 200 chars):\n{response_body[:200]}")
    except pycurl.error as e:
        print(f"PycURL error: {e}")
    finally:
        c.close()

# Example usage
fetch_url('https://httpbin.org/get')