Typing stubs for pycurl

Warnings

• gotcha PycURL expects byte strings for non-ASCII data in many options (e.g., URL, POSTFIELDS). Passing Unicode strings with non-ASCII characters directly can lead to `UnicodeEncodeError` or `pycurl.error` (e.g., 'read function error/data error') if PycURL cannot encode them to ASCII.
  Fix: Explicitly encode Unicode strings to bytes (e.g., `.encode('utf-8')`) before passing them to pycurl methods or options that expect binary data.
• gotcha When `pycurl` encounters an error from the underlying `libcurl` library, it raises `pycurl.error`. The exception message may contain a numeric error code from `libcurl` (e.g., `(1, '')` for `CURLE_UNSUPPORTED_PROTOCOL`). The generic message might not immediately indicate the root cause.
  Fix: For detailed debugging, set `c.setopt(pycurl.VERBOSE, True)` before `c.perform()`. This will print extensive `libcurl` debugging information to stderr, which can help diagnose connection, SSL, or protocol-related issues.
• gotcha Passing an argument of an incorrect type to `c.setopt()` (e.g., an integer where a string is expected) will raise a `TypeError: invalid arguments to setopt`. Carefully check the `libcurl` documentation for the expected argument type of each option.
  Fix: Consult the PycURL documentation or `libcurl`'s `curl_easy_setopt` page for the specific option to ensure the correct Python type is used (e.g., `str` vs. `bytes`, `int`, `list`, `tuple`).
• breaking The `DEBUGFUNCTION` callback on Python 3 changed to take `bytes` rather than (Unicode) `str` as its argument. Code expecting `str` will need to decode the input.
  Fix: Ensure `DEBUGFUNCTION` callbacks are prepared to handle `bytes` objects on Python 3 by decoding them if string manipulation is required (e.g., `data.decode('utf-8')`).
• gotcha On Windows, an `ImportError` related to `libcurl` or `OpenSSL` can occur if the compile-time and runtime SSL backends do not match, or if `OpenSSL` headers are missing.
  Fix: Ensure OpenSSL is correctly installed on your system. For `pycurl` builds, it might be necessary to specify the SSL backend to `setup.py` (e.g., `--with-openssl`) or set environment variables like `PYCURL_SSL_LIBRARY` on Windows to point to your OpenSSL installation. Refer to `pycurl`'s installation documentation for platform-specific details.

Install

• pip install pycurl types-pycurl Install pycurl and its type stubs

Imports

• Curl

  import pycurl
  from io import BytesIO
  
  c = pycurl.Curl()

• pycurl.error

  import pycurl
  
  try:
      # pycurl operations
      pass
  except pycurl.error as e:
      print(f"PycURL error: {e}")

Quickstart

This quickstart demonstrates how to make a basic HTTPS GET request using pycurl, capture the response body into a BytesIO object, and handle potential errors. It includes the recommended practice of using the `certifi` package to specify an up-to-date CA certificate bundle for secure connections. The `types-pycurl` package, when installed, provides type checking for `pycurl` usage in this code.

import pycurl
from io import BytesIO
import certifi
import os

buffer = BytesIO()
c = pycurl.Curl()

# Set the URL and write data to the buffer
c.setopt(pycurl.URL, 'https://example.com')
c.setopt(pycurl.WRITEDATA, buffer)

# Configure SSL certificates using certifi for secure connections
# (optional, but recommended for HTTPS)
if os.environ.get('PYCURL_CA_BUNDLE_PATH'):
    c.setopt(pycurl.CAINFO, os.environ.get('PYCURL_CA_BUNDLE_PATH'))
elif os.path.exists(certifi.where()):
    c.setopt(pycurl.CAINFO, certifi.where())

try:
    c.perform()
    body = buffer.getvalue().decode('utf-8')
    print(f"HTTP Status Code: {c.getinfo(pycurl.HTTP_CODE)}")
    print(f"Response body length: {len(body)} characters")
    # print(body[:500]) # Print first 500 characters of the body
except pycurl.error as e:
    # Troubleshooting tip: Enable verbose logging for more details
    # c.setopt(pycurl.VERBOSE, True)
    print(f"An error occurred: {e}")
finally:
    c.close()