PycURL Requests <pycurl://☤>

PycURL Requests is a Requests-compatible interface for PycURL.

Requirements

• Python 3.6+
• PycURL
• chardet

Installation

Latest release via pip:

pip install pycurl-requests [--user]

via Git:

git clone https://github.com/dcoles/pycurl-requests.git; cd pycurl-requests
python3 setup.py install [--user]

Quick-start

>>> import pycurl_requests as requests
>>> r = requests.get('https://api.github.com/repos/dcoles/pycurl-requests')
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf-8'
>>> r.encoding
'utf-8'
>>> r.text
'{\n  "id": 236427187,\n...'
>>> data = r.json()
>>> data['name']
'pycurl-requests'
>>> data['html_url']
'https://github.com/dcoles/pycurl-requests'
>>> 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 -- script.py arg arg...

request tool

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

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

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.

Documentation

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('http://example.com')

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

try:
    requests.get('http://connect_error')
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.

Logging

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

logging.getLogger('curl').setLevel(logging.DEBUG)

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

• No support for reading Cookies
• No support for client-side certificates
• No support for proxies
• No support for link headers (e.g. Response.links)
• No support for sending multi-part encoded files)
• Basic support for Session objects (e.g. requests.Session)

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

License

Licensed under the MIT License.