Unirest for Python Build Status

Unirest is a set of lightweight HTTP libraries available in multiple languages, ideal for most applications:

Created with love by thefosk @ mashape.com

Installing

To utilize Unirest, install it using pip:

$ pip install unirest

After installing the pip package, you can now begin simplifying requests by importing unirest:

import unirest

Creating Requests

So you're probably wondering how using Unirest makes creating requests in Python easier, let's start with a working example:

response = unirest.post("http://httpbin.org/post", headers={ "Accept": "application/json" }, params={ "parameter": 23, "foo": "bar" })

response.code # The HTTP status code
response.headers # The HTTP headers
response.body # The parsed response
response.raw_body # The unparsed response

Asynchronous Requests

Python also supports asynchronous requests in which you can define a callback function to be passed along and invoked when Unirest receives the response:

def callback_function(response):
  response.code # The HTTP status code
  response.headers # The HTTP headers
  response.body # The parsed response
  response.raw_body # The unparsed response

thread = unirest.post("http://httpbin.org/post", headers={ "Accept": "application/json" }, params={ "parameter": 23, "foo": "bar" }, callback=callback_function)

File Uploads

Transferring file data requires that you open the file in a readable r mode:

response = unirest.post("http://httpbin.org/post", headers={"Accept": "application/json"},
  params={
    "parameter": "value",
    "file": open("/tmp/file", mode="r")
  }
)

Custom Entity Body

import json

response = unirest.post("http://httpbin.org/post", headers={ "Accept": "application/json" },
  params=json.dumps({
    "parameter": "value",
    "foo": "bar"
  })
)

Note: For the sake of semplicity, even with custom entities in the body, the keyword argument is still params (instead of data for example). I'm looking for feedback on this.

Basic Authentication

Authenticating the request with basic authentication can be done by providing an auth array like:

response = unirest.get("http://httpbin.org/get", auth=('username', 'password'))

Request

unirest.get(url, headers = {}, params = {}, auth = (), callback = None)
unirest.post(url, headers = {}, params = {}, auth = (), callback = None)
unirest.put(url, headers = {}, params = {}, auth = (), callback = None)
unirest.patch(url, headers = {}, params = {}, auth = (), callback = None)    
unirest.delete(url, headers = {}, params = {}, auth = (), callback = None)

Response

Upon receiving a response, Unirest returns the result in the form of an Object. This object should always have the same keys for each language regarding to the response details.

Advanced Configuration

You can set some advanced configuration to tune Unirest-Python:

Timeout

You can set a custom timeout value (in seconds):

unirest.timeout(5) # 5s timeout

Default Request Headers

You can set default headers that will be sent on every request:

unirest.default_header('Header1','Value1')
unirest.default_header('Header2','Value2')

You can clear the default headers anytime with:

unirest.clear_default_headers()