{"id":5537,"library":"types-pycurl","title":"Typing stubs for pycurl","description":"types-pycurl provides static type annotations (stubs) for the pycurl library, enabling static type checkers like MyPy and PyRight to analyze code that uses pycurl for network operations. It is part of the typeshed project, which centrally maintains type stubs for Python's standard library and many third-party packages. This package is automatically released, typically on a daily basis, to ensure compatibility with the corresponding pycurl runtime versions.","status":"active","version":"7.45.7.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed/tree/main/stubs/pycurl","tags":["typing","stubs","pycurl","typeshed","type-checking","network","http"],"install":[{"cmd":"pip install pycurl types-pycurl","lang":"bash","label":"Install pycurl and its type stubs"}],"dependencies":[{"reason":"This package provides type stubs for the runtime library `pycurl`.","package":"pycurl"},{"reason":"Commonly used with pycurl for up-to-date SSL certificate bundles, especially for HTTPS requests.","package":"certifi","optional":true}],"imports":[{"symbol":"Curl","correct":"import pycurl\nfrom io import BytesIO\n\nc = pycurl.Curl()"},{"symbol":"pycurl.error","correct":"import pycurl\n\ntry:\n    # pycurl operations\n    pass\nexcept pycurl.error as e:\n    print(f\"PycURL error: {e}\")"}],"quickstart":{"code":"import pycurl\nfrom io import BytesIO\nimport certifi\nimport os\n\nbuffer = BytesIO()\nc = pycurl.Curl()\n\n# Set the URL and write data to the buffer\nc.setopt(pycurl.URL, 'https://example.com')\nc.setopt(pycurl.WRITEDATA, buffer)\n\n# Configure SSL certificates using certifi for secure connections\n# (optional, but recommended for HTTPS)\nif os.environ.get('PYCURL_CA_BUNDLE_PATH'):\n    c.setopt(pycurl.CAINFO, os.environ.get('PYCURL_CA_BUNDLE_PATH'))\nelif os.path.exists(certifi.where()):\n    c.setopt(pycurl.CAINFO, certifi.where())\n\ntry:\n    c.perform()\n    body = buffer.getvalue().decode('utf-8')\n    print(f\"HTTP Status Code: {c.getinfo(pycurl.HTTP_CODE)}\")\n    print(f\"Response body length: {len(body)} characters\")\n    # print(body[:500]) # Print first 500 characters of the body\nexcept pycurl.error as e:\n    # Troubleshooting tip: Enable verbose logging for more details\n    # c.setopt(pycurl.VERBOSE, True)\n    print(f\"An error occurred: {e}\")\nfinally:\n    c.close()\n","lang":"python","description":"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."},"warnings":[{"fix":"Explicitly encode Unicode strings to bytes (e.g., `.encode('utf-8')`) before passing them to pycurl methods or options that expect binary data.","message":"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.","severity":"gotcha","affected_versions":"All Python 3 versions of pycurl"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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')`).","message":"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.","severity":"breaking","affected_versions":"PycURL versions < 7.19.0 (introduced in 7.19.0)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions on Windows"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}