python-requests Getting started with python-requests
Remarks
HTTP for Humans
Requests is the only Non-GMO HTTP library for Python, safe for human consumption.
Requests allows you to send organic, grass-fed HTTP/1.1 requests, without the need for manual labor. There's no need to manually add query strings to your URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, powered by urllib3, which is embedded within Requests.
The power of Requests:
>>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
u'{"type":"User"...'
>>> r.json()
{u'private_gists': 419, u'total_private_repos': 77, ...}
Reading the response
response = requests.get("https://api.github.com/events")
text_resp = response.text
JSON response: for json-formatted responses the package provides a built-in decoder
response = requests.get('https://api.github.com/events')
json_resp = response.json()
This method will raise a ValueError in case of empty response or unparseable content.
GET requests
requests.get() creates a GET request:
response = requests.get('https://example.com/')
Pass in query parameters as a dictionary to the params argument:
response = requests.get('https://example.com/', params={"a": 1, "b": 2})
For GET requests that might require basic authentication, you can include the auth paramter as follows:
response = requests.get('https://api.github.com/user', auth=('user', 'pass'))
Installation or Setup
python-requests is available on PyPI, the Python Package Index, which means it can be installed through pip:
pip install requests
Up-to-date source code can be found on the requests GitHub repository
If you wish to install it from source, you can do this by either cloning the GitHub repository:
git clone git://github.com/kennethreitz/requests.git
Or by getting the tarball (-O writes the output to file; -L follows redirects):
curl -OL https://github.com/kennethreitz/requests/tarball/master
Then you can install it by executing the setup.py
python setup.py install
However you installed it, you can start using it by importing the usual way
>>> import requests
>>> requests.get('http://stackoverflow.com')
Other request methods
The requests module has top-level functions for most HTTP methods:
r = requests.put('https://example.com/', data=put_body)
r = requests.delete('https://example.com/')
r = requests.head('https://example.com/')
r = requests.options('https://example.com/')
r = requests.patch('https://example.com/', data=patch_update)
POST requests
POST requests are made with the request.post() method.
If you need to send a web form request as a POST body, pass in a dictionary with key-value pairs as the data argument; requests will encode these to a application/x-www-form-urlencoded mimetype body:
r = requests.post('https://github.com/', data={"a": 1, "b": 2})
If you need to POST a json payload, you can use json= . This will automatically set the Content-Type header to application/json
r = requests.post('https://github.com/', data={"a": 1, "b": 2})
Reading status codes
The attribute status_code contains the status code of the response
good_req = requests.get('https://api.github.com/events')
code_200 = good_req.status_code
notfound_req = requests.get('https://api.github.com/not_found')
code_404 = notfound_req.status_code
requests.codes.__dict__ will provide a list of available http status codes.
It is possible to user raise_for_status to check if the status_code was 4xx or 5xx and raise a corresponding exception in that case.
good_req = requests.get('https://api.github.com/events')
good_req.raise_for_status()
# is a 200 status code so nothing happens
notfound_req = requests.get('https://api.github.com/not_found')
notfound_req.raise_for_status()
# raises requests.exceptions.HTTPError: 404 Client Error
