pycurl-requests 0.0.3

A Requests-compatible interface for pycURL

PycURL Requests <pycurl://☤>

PycURL Requests is a Requests-compatible interface for PycURL.

Requirements

• Python 3.5+
• 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] [-o OUTPUT] [-X REQUEST] [-H HEADER] [-d DATA]
                  [--json JSON]
                  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
  -o OUTPUT, --output OUTPUT
                        Write to file instead of stdout
  -X REQUEST, --request REQUEST
                        Request command to use (e.g. HTTP method)
  -H HEADER, --header HEADER
                        Add custom request header (format: `Header: Value`)
  -d DATA, --data DATA  Add POST data
  --json JSON           Add JSON POST data

This can also be used with the Requests library if REQUEST_REQUESTS environment variable is set to a non-zero 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 the behaviour of cURL by passing a custom pycurl.Curl handle into the request-like functions.

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

import pycurl
import pycurl_requests as requests

c = pycurl.Curl()
c.setopt(c.NOBODY, 1)
response = requests.get('http://example.com', curl=c)

cURL exceptions

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

For convenience, the original pycurl.error's error string and cURL error code will be set on the exception object as the curl_error 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_error, 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 Cookies
• No support for timeouts
• No support for Session objects (e.g. requests.Session)
• No support for client-side certificates
• No support for proxies
• No support for link headers (e.g. Response.links)
• No support for authentication
• No support for sending multi-part encoded files)

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

License

Licensed under the MIT License.