Useful methods for working with httplib, completely decoupled from code specific to urllib3.


urllib3.filepost.encode_multipart_formdata(fields, boundary=None)

Encode a dictionary of fields using the multipart/form-data mime format.

  • fields – Dictionary of fields. The key is treated as the field name, and the value as the body of the form-data. If the value is a tuple of two elements, then the first element is treated as the filename of the form-data section.
  • boundary – If not specified, then a random boundary will be generated using mimetools.choose_boundary().


class urllib3.request.RequestMethods

Convenience mixin for classes who implement a urlopen() method, such as HTTPConnectionPool and PoolManager.

Provides behavior for making common types of HTTP request methods and decides which type of request field encoding to use.


request_encode_url() is for sending requests whose fields are encoded in the URL (such as GET, HEAD, DELETE).

request_encode_body() is for sending requests whose fields are encoded in the body of the request using multipart or www-orm-urlencoded (such as for POST, PUT, PATCH).

request() is for making any kind of request, it will look up the appropriate encoding format and use one of the above two methods to make the request.

get_url(url, fields=None, **urlopen_kw)

Deprecated since version 1.0.

Use request() instead.

post_url(url, fields=None, headers=None, **urlopen_kw)

Deprecated since version 1.0.

Use request() instead.

request(method, url, fields=None, headers=None, **urlopen_kw)

Make a request using urlopen() with the appropriate encoding of fields based on the method used.

This is a convenience method that requires the least amount of manual effort. It can be used in most situations, while still having the option to drop down to more specific methods when necessary, such as request_encode_url(), request_encode_body(), or even the lowest level urlopen().

request_encode_body(method, url, fields=None, headers=None, encode_multipart=True, multipart_boundary=None, **urlopen_kw)

Make a request using urlopen() with the fields encoded in the body. This is useful for request methods like POST, PUT, PATCH, etc.

When encode_multipart=True (default), then urllib3.filepost.encode_multipart_formdata() is used to encode the payload with the appropriate content type. Otherwise urllib.urlencode() is used with the ‘application/x-www-form-urlencoded’ content type.

Multipart encoding must be used when posting files, and it’s reasonably safe to use it in other times too. However, it may break request signing, such as with OAuth.

Supports an optional fields parameter of key/value strings AND key/filetuple. A filetuple is a (filename, data) tuple. For example:

fields = {
    'foo': 'bar',
    'fakefile': ('foofile.txt', 'contents of foofile'),
    'realfile': ('barfile.txt', open('realfile').read()),
    'nonamefile': ('contents of nonamefile field'),

When uploading a file, providing a filename (the first parameter of the tuple) is optional but recommended to best mimick behavior of browsers.

Note that if headers are supplied, the ‘Content-Type’ header will be overwritten because it depends on the dynamic random boundary string which is used to compose the body of the request. The random boundary string can be explicitly set with the multipart_boundary parameter.

request_encode_url(method, url, fields=None, **urlopen_kw)

Make a request using urlopen() with the fields encoded in the url. This is useful for request methods like GET, HEAD, DELETE, etc.


class urllib3.response.HTTPResponse(body='', headers=None, status=0, version=0, reason=None, strict=0, preload_content=True, decode_content=True, original_response=None, pool=None, connection=None)

HTTP Response container.

Backwards-compatible to httplib’s HTTPResponse but the response body is loaded and decoded on-demand when the data property is accessed.

Extra parameters for behaviour not present in httplib.HTTPResponse:

  • preload_content – If True, the response’s body will be preloaded during construction.
  • decode_content – If True, attempts to decode specific content-encoding’s based on headers (like ‘gzip’ and ‘deflate’) will be skipped and raw data will be used instead.
  • original_response – When this HTTPResponse wrapper is generated from an httplib.HTTPResponse object, it’s convenient to include the original for debug purposes. It’s otherwise unused.
CONTENT_DECODERS = {'gzip': <function decode_gzip at 0x13eb488>, 'deflate': <function decode_deflate at 0x13eb500>}
static from_httplib(r, **response_kw)

Given an httplib.HTTPResponse instance r, return a corresponding urllib3.response.HTTPResponse object.

Remaining parameters are passed to the HTTPResponse constructor, along with original_response=r.

getheader(name, default=None)
read(amt=None, decode_content=True, cache_content=False)

Similar to, but with two additional parameters: decode_content and cache_content.

  • amt – How much of the content to read. If specified, decoding and caching is skipped because we can’t decode partial content nor does it make sense to cache partial content as the full response.
  • decode_content – If True, will attempt to decode the body based on the ‘content-encoding’ header. (Overridden if amt is set.)
  • cache_content – If True, will save the returned data such that the same result is returned despite of the state of the underlying file object. This is useful if you want the .data property to continue working after having .read() the file object. (Overridden if amt is set.)

Table Of Contents

Previous topic


This Page