API

This part of the documentation covers all the interfaces of Requests. For parts where Requests depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Main Interface

All of Request’s functionality can be accessed by these 5 methods. They all return a Response object.

requests.head(url, params=None, headers=None, cookies=None, auth=None, timeout=None, proxies=None)

Sends a HEAD request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • params – (optional) Dictionary of parameters, or bytes, to be sent in the query string for the Request.
  • headers – (optional) Dictionary of HTTP Headers to sent with the Request.
  • cookies – (optional) CookieJar object to send with the Request.
  • auth – (optional) AuthObject to enable Basic HTTP Auth.
  • timeout – (optional) Float describing the timeout of the request.
  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
requests.get(url, params=None, headers=None, cookies=None, auth=None, timeout=None, proxies=None)

Sends a GET request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • params – (optional) Dictionary of parameters, or bytes, to be sent in the query string for the Request.
  • headers – (optional) Dictionary of HTTP Headers to send with the Request.
  • cookies – (optional) CookieJar object to send with the Request.
  • auth – (optional) AuthObject to enable Basic HTTP Auth.
  • timeout – (optional) Float describing the timeout of the request.
  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
requests.post(url, data='', headers=None, files=None, cookies=None, auth=None, timeout=None, allow_redirects=False, params=None, proxies=None)

Sends a POST request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • data – (optional) Dictionary or bytes to send in the body of the Request.
  • headers – (optional) Dictionary of HTTP Headers to sent with the Request.
  • files – (optional) Dictionary of ‘filename’: file-like-objects for multipart encoding upload.
  • cookies – (optional) CookieJar object to send with the Request.
  • auth – (optional) AuthObject to enable Basic HTTP Auth.
  • timeout – (optional) Float describing the timeout of the request.
  • allow_redirects – (optional) Boolean. Set to True if redirect following is allowed.
  • params – (optional) Dictionary of parameters, or bytes, to be sent in the query string for the Request.
  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
requests.put(url, data='', headers=None, files=None, cookies=None, auth=None, timeout=None, allow_redirects=False, params=None, proxies=None)

Sends a PUT request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • data – (optional) Dictionary or bytes to send in the body of the Request.
  • headers – (optional) Dictionary of HTTP Headers to sent with the Request.
  • files – (optional) Dictionary of ‘filename’: file-like-objects for multipart encoding upload.
  • cookies – (optional) CookieJar object to send with the Request.
  • auth – (optional) AuthObject to enable Basic HTTP Auth.
  • timeout – (optional) Float describing the timeout of the request.
  • allow_redirects – (optional) Boolean. Set to True if redirect following is allowed.
  • params – (optional) Dictionary of parameters, or bytes, to be sent in the query string for the Request.
  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
requests.patch(url, data='', headers=None, files=None, cookies=None, auth=None, timeout=None, allow_redirects=False, params=None, proxies=None)

Sends a PATCH request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • data – (optional) Dictionary or bytes to send in the body of the Request.
  • headers – (optional) Dictionary of HTTP Headers to sent with the Request.
  • files – (optional) Dictionary of ‘filename’: file-like-objects for multipart encoding upload.
  • cookies – (optional) CookieJar object to send with the Request.
  • auth – (optional) AuthObject to enable Basic HTTP Auth.
  • timeout – (optional) Float describing the timeout of the request.
  • allow_redirects – (optional) Boolean. Set to True if redirect following is allowed.
  • params – (optional) Dictionary of parameters, or bytes, to be sent in the query string for the Request.
  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
requests.delete(url, params=None, headers=None, cookies=None, auth=None, timeout=None, allow_redirects=False, proxies=None)

Sends a DELETE request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • params – (optional) Dictionary of parameters, or bytes, to be sent in the query string for the Request.
  • headers – (optional) Dictionary of HTTP Headers to sent with the Request.
  • cookies – (optional) CookieJar object to send with the Request.
  • auth – (optional) AuthObject to enable Basic HTTP Auth.
  • timeout – (optional) Float describing the timeout of the request.
  • allow_redirects – (optional) Boolean. Set to True if redirect following is allowed.
  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.

class requests.models.Response

The core Response object. All Request objects contain a response attribute, which is an instance of this class.

cached

True, if the response content is cached locally.

content

Raw content of the response, in bytes. If content-encoding of response was set to gzip, the response data will be automatically deflated.

error

Resulting HTTPError of request, if one occured.

headers

Case-insensitive Dictionary of Response Headers. For example, headers['content-encoding'] will return the value of a 'Content-Encoding' response header.

history

A list of Response objects from the history of the Request. Any redirect responses will end up here.

ok

True if no error occured.

raise_for_status()

Raises stored HTTPError, if one occured.

read(*args)

Returns content. Used for file-like object compatiblity.

status_code

Integer Code of responded HTTP Status.

url

Final URL location of Response.

Exceptions

exception requests.HTTPError(url, code, msg, hdrs, fp)

Raised when HTTP error occurs, but also acts like non-error return

exception requests.RequestException

There was an ambiguous exception that occured while handling your request.

exception requests.models.AuthenticationError

The authentication credentials provided were invalid.

exception requests.models.URLRequired

A valid URL is required to make a request.

exception requests.models.InvalidMethod

An inappropriate method was attempted.

Internals

These items are an internal component to Requests, and should never be seen by the end user (developer). This part of the API documentation exists for those who are extending the functionality of Requests.

Functions

requests.request(method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=False, proxies=None)

Constructs and sends a Request. Returns Response object.

Parameters:
  • method – method for the new Request object.
  • url – URL for the new Request object.
  • params – (optional) Dictionary or bytes to be sent in the query string for the Request.
  • data – (optional) Dictionary or bytes to send in the body of the Request.
  • headers – (optional) Dictionary of HTTP Headers to send with the Request.
  • cookies – (optional) CookieJar object to send with the Request.
  • files – (optional) Dictionary of ‘filename’: file-like-objects for multipart encoding upload.
  • auth – (optional) AuthObject to enable Basic HTTP Auth.
  • timeout – (optional) Float describing the timeout of the request.
  • allow_redirects – (optional) Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.

Classes

class requests.models.Request(url=None, headers={}, files=None, method=None, data={}, params={}, auth=None, cookiejar=None, timeout=None, redirect=False, allow_redirects=False, proxies=None)

The Request object. It carries out all functionality of Requests. Recommended interface is with the Requests functions.

allow_redirects

Set to True if full redirects are allowed (e.g. re-POST-ing of data at new Location)

auth

AuthObject to attach to Request.

cookiejar

CookieJar to attach to Request.

data

Dictionary or byte of request body data to attach to the Request.

files

Dictionary of files to multipart upload ({filename: content}).

headers

Dictonary of HTTP Headers to attach to the Request.

method

HTTP Method to use. Available: GET, HEAD, PUT, POST, DELETE.

params

Dictionary or byte of querystring data to attach to the Request.

redirect

True if Request is part of a redirect chain (disables history and HTTPError storage).

response

Response instance, containing content and metadata of HTTP Response, once sent.

send(anyway=False)

Sends the request. Returns True of successful, false if not. If there was an HTTPError during transmission, self.response.status_code will contain the HTTPError code.

Once a request is successfully sent, sent will equal True.

Parameters:anyway – If True, request will be sent, even if it has

already been sent.

sent

True if Request has been sent.

url

Request URL.

Structures

class requests.structures.CaseInsensitiveDict

Case-insensitive Dictionary for Response Headers.

For example, headers['content-encoding'] will return the value of a 'Content-Encoding' response header.

clear

D.clear() -> None. Remove all items from D.

copy

D.copy() -> a shallow copy of D

static fromkeys()

dict.fromkeys(S[,v]) -> New dict with keys from S and values equal to v. v defaults to None.

get

D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.

has_key

D.has_key(k) -> True if D has a key k, else False

items

D.items() -> list of D’s (key, value) pairs, as 2-tuples

iteritems

D.iteritems() -> an iterator over the (key, value) items of D

iterkeys

D.iterkeys() -> an iterator over the keys of D

itervalues

D.itervalues() -> an iterator over the values of D

keys

D.keys() -> list of D’s keys

pop

D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised

popitem

D.popitem() -> (k, v), remove and return some (key, value) pair as a 2-tuple; but raise KeyError if D is empty.

setdefault

D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D

update

D.update(E, **F) -> None. Update D from dict/iterable E and F. If E has a .keys() method, does: for k in E: D[k] = E[k] If E lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values

D.values() -> list of D’s values

About Requests

Requests is an elegant and simple HTTP library for Python, built for human beings. You are currently looking at the documentation of the development release.

Table Of Contents

Related Topics

This Page

Fork me on GitHub