models

This module contains the primary objects that power Requests.

Module Contents

Classes

RequestEncodingMixin()
RequestHooksMixin()
Request(self,method=None,url=None,headers=None,files=None,data=None,params=None,auth=None,cookies=None,hooks=None,json=None) A user-created Request object.
PreparedRequest(self) The fully mutable PreparedRequest object,
Response(self) The Response object, which contains a
class RequestEncodingMixin
path_url()

Build the path URL to use.

_encode_params()

Encode parameters in a piece of data.

Will successfully encode parameters when passed as a dict or a list of 2-tuples. Order is retained if data is a list of 2-tuples but arbitrary if parameters are supplied as a dict.

_encode_files(data)

Build the body for a multipart/form-data request.

Will successfully encode files when passed as a dict or a list of tuples. Order is retained if data is a list of tuples but arbitrary if parameters are supplied as a dict. The tuples may be 2-tuples (filename, fileobj), 3-tuples (filename, fileobj, contentype) or 4-tuples (filename, fileobj, contentype, custom_headers).

class RequestHooksMixin
register_hook(event, hook)

Properly register a hook.

deregister_hook(event, hook)

Deregister a previously registered hook. Returns True if the hook existed, False if not.

class Request(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)

A user-created Request object.

Used to prepare a PreparedRequest, which is sent to the server.

Parameters:
  • method – HTTP method to use.
  • url – URL to send.
  • headers – dictionary of headers to send.
  • files – dictionary of {filename: fileobject} files to multipart upload.
  • data – the body to attach to the request. If a dictionary is provided, form-encoding will take place.
  • json – json for the body to attach to the request (if files or data is not specified).
  • params – dictionary of URL parameters to append to the URL.
  • auth – Auth handler or (user, pass) tuple.
  • cookies – dictionary or CookieJar of cookies to attach to this request.
  • hooks – dictionary of callback hooks, for internal usage.

Usage:

>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>
__init__(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)
__repr__()
prepare()

Constructs a PreparedRequest for transmission and returns it.

class PreparedRequest

The fully mutable PreparedRequest object, containing the exact bytes that will be sent to the server.

Generated from either a Request object or manually.

Usage:

>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> r = req.prepare()
<PreparedRequest [GET]>

>>> s = requests.Session()
>>> s.send(r)
<Response [200]>
__init__()
prepare(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)

Prepares the entire request with the given parameters.

__repr__()
copy()
prepare_method(method)

Prepares the given HTTP method.

prepare_url(url, params)

Prepares the given HTTP URL.

prepare_headers(headers)

Prepares the given HTTP headers.

prepare_body(data, files, json=None)

Prepares the given HTTP body data.

prepare_content_length(body)
prepare_auth(auth, url="")

Prepares the given HTTP auth data.

prepare_cookies(cookies)

Prepares the given HTTP cookie data.

This function eventually generates a Cookie header from the given cookies using cookielib. Due to cookielib’s design, the header will not be regenerated if it already exists, meaning this function can only be called once for the life of the PreparedRequest object. Any subsequent calls to prepare_cookies will have no actual effect, unless the “Cookie” header is removed beforehand.

prepare_hooks(hooks)

Prepares the given hooks.

class Response

The Response object, which contains a server’s response to an HTTP request.

__init__()
__getstate__()
__setstate__(state)
__repr__()
__bool__()

Returns true if status_code is ‘OK’.

__nonzero__()

Returns true if status_code is ‘OK’.

__iter__()

Allows you to use a response as an iterator.

ok()
is_redirect()

True if this Response is a well-formed HTTP redirect that could have been processed automatically (by Session.resolve_redirects()).

is_permanent_redirect()

True if this Response one of the permanent versions of redirect

apparent_encoding()

The apparent encoding, provided by the chardet library

iter_content(chunk_size=1, decode_unicode=False)

Iterates over the response data. When stream=True is set on the request, this avoids reading the content at once into memory for large responses. The chunk size is the number of bytes it should read into memory. This is not necessarily the length of each item returned as decoding can take place.

If decode_unicode is True, content will be decoded using the best available encoding based on the response.

iter_lines(chunk_size=ITER_CHUNK_SIZE, decode_unicode=None, delimiter=None)

Iterates over the response data, one line at a time. When stream=True is set on the request, this avoids reading the content at once into memory for large responses.

Note

This method is not reentrant safe.

content()

Content of the response, in bytes.

text()

Content of the response, in unicode.

If Response.encoding is None, encoding will be guessed using chardet.

The encoding of the response content is determined based solely on HTTP headers, following RFC 2616 to the letter. If you can take advantage of non-HTTP knowledge to make a better guess at the encoding, you should set r.encoding appropriately before accessing this property.

json(**kwargs)

Returns the json-encoded content of a response, if any.

Parameters:**kwargs – Optional arguments that json.loads takes.

Returns the parsed header links of the response, if any.

raise_for_status()

Raises stored HTTPError, if one occurred.

close()

Releases the connection back to the pool. Once this method has been called the underlying raw object must not be accessed again.

Note: Should not normally need to be called explicitly.