Skip to main content

A Requests-compatible interface for pycURL

Project description

PycURL Requests <pycurl://☤>

PycURL Requests is a Requests-compatible interface for PycURL.




Latest release via pip:

pip install pycurl-requests [--user]

via Git:

git clone; cd pycurl-requests
python3 install [--user]


>>> import pycurl_requests as requests
>>> r = requests.get('')
>>> r.status_code
>>> r.headers['content-type']
'application/json; charset=utf-8'
>>> r.encoding
>>> r.text
'{\n  "id": 236427187,\n...'
>>> data = r.json()
>>> data['name']
>>> data['html_url']
>>> data['description']
'A Requests-compatible interface for pycURL'

The library can also be used to run existing Python scripts that import the requests module. By running the script through the pycurl_requests helper, any use of the requests module will be automatically redirected to pycurl_requests.

python3 -m pycurl_requests -- arg arg...

request tool

A basic curl-like command-line utility is included:

usage: [-h] [-d DATA] [-H HEADER] [--json JSON] [-L] [-o OUTPUT]
                  [-X REQUEST] [-v]

A basic `curl`-like command-line HTTP utility

positional arguments:
  url                   URL of resource to connect to

optional arguments:
  -h, --help            show this help message and exit
  -d DATA, --data DATA  Add POST data
  -H HEADER, --header HEADER
                        Add custom request header (format: `Header: Value`)
  --json JSON           Add JSON POST data
  -L, --location        Follow redirects
  -o OUTPUT, --output OUTPUT
                        Write to file instead of stdout
  -X REQUEST, --request REQUEST
                        Request command to use (e.g. HTTP method)
  -v, --verbose         Verbose logging

This can also be used with the Requests library if PYCURLREQUESTS_REQUESTS environment variable is set to a non-null value.


This library aims to be API compatible with Requests, thus the Requests documentation should be mostly applicable.

cURL options

It is possible customize cURL's behaviour using the curl attribute on a Session object.

For example, to make a request without requesting the body:

import pycurl
import pycurl_requests as requests

with requests.Session() as session:
    session.curl.setopt(pycurl.NOBODY, 1)
    response = session.get('')

See the pycurl.Curl object documentation for all possible curl attribute methods.

cURL exceptions

All pycurl.error exceptions are mapped to a requests.RequestException (or one of its subclasses).

For convenience, the original pycurl.error error message and cURL error code will be set on the exception object as the curl_message and curl_code attributes.

import pycurl_requests as requests

except requests.RequestException as e:
    print('ERROR: {} (cURL error: {})'.format(e.curl_message, e.curl_code))

It is also possible to obtain the original pycurl.error using the __cause__ attribute.


Detailed log records from libcurl, including informational text and HTTP headers, can be shown by setting the curl logger (or sub-loggers) to DEBUG level:

import logging


Log records are split into dedicated sub-loggers for each type of record:

  • curl.text — Informational text
  • curl.header_in — Header data received from the peer
  • curl.header_out — Header data sent to the peer

Known limitations

Most of these features should be supported in the near future.


Licensed under the MIT License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pycurl-requests-0.2.1.tar.gz (24.8 kB view hashes)

Uploaded source

Built Distribution

pycurl_requests-0.2.1-py3-none-any.whl (28.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page