Fields and Multipart Forms#

Fields#

class urllib3.fields.RequestField(name, data, filename=None, headers=None, header_formatter=<function format_header_param_html5>)#

Bases: object

A data container for request body parameters.

Parameters

  • name – The name of this request field. Must be unicode.

  • data – The data/value body.

  • filename – An optional filename of the request field. Must be unicode.

  • headers – An optional dict-like object of headers to initially use for the field.

  • header_formatter – An optional callable that is used to encode and format the headers. By default, this is format_header_param_html5().

classmethod from_tuples(fieldname, value, header_formatter=<function format_header_param_html5>)#

A RequestField factory from old-style tuple parameters.

Supports constructing RequestField from parameter of key/value strings AND key/filetuple. A filetuple is a (filename, data, MIME type) tuple where the MIME type is optional. For example:

'foo': 'bar',
'fakefile': ('foofile.txt', 'contents of foofile'),
'realfile': ('barfile.txt', open('realfile').read()),
'typedfile': ('bazfile.bin', open('bazfile').read(), 'image/jpeg'),
'nonamefile': 'contents of nonamefile field',

Field names and filenames must be unicode.

make_multipart(content_disposition=None, content_type=None, content_location=None)#

Makes this request field into a multipart request field.

This method overrides “Content-Disposition”, “Content-Type” and “Content-Location” headers to the request parameter.

Parameters

  • content_type – The ‘Content-Type’ of the request body.

  • content_location – The ‘Content-Location’ of the request body.

render_headers()#

Renders the headers for this request field.

urllib3.fields.format_header_param(name, value)#

Helper function to format and quote a single header parameter using the HTML5 strategy.

Particularly useful for header parameters which might contain non-ASCII values, like file names. This follows the HTML5 Working Draft Section 4.10.22.7 and matches the behavior of curl and modern browsers.

Parameters

  • name – The name of the parameter, a string expected to be ASCII only.

  • value – The value of the parameter, provided as bytes or str`.

Ret

A unicode string, stripped of troublesome characters.

urllib3.fields.format_header_param_html5(name, value)#

Helper function to format and quote a single header parameter using the HTML5 strategy.

Particularly useful for header parameters which might contain non-ASCII values, like file names. This follows the HTML5 Working Draft Section 4.10.22.7 and matches the behavior of curl and modern browsers.

Parameters

  • name – The name of the parameter, a string expected to be ASCII only.

  • value – The value of the parameter, provided as bytes or str`.

Ret

A unicode string, stripped of troublesome characters.

urllib3.fields.format_header_param_rfc2231(name, value)#

Helper function to format and quote a single header parameter using the strategy defined in RFC 2231.

Particularly useful for header parameters which might contain non-ASCII values, like file names. This follows RFC 2388 Section 4.4.

Parameters

  • name – The name of the parameter, a string expected to be ASCII only.

  • value – The value of the parameter, provided as bytes or str`.

Ret

An RFC-2231-formatted unicode string.

urllib3.fields.guess_content_type(filename, default='application/octet-stream')#

Guess the “Content-Type” of a file.

Parameters

  • filename – The filename to guess the “Content-Type” of using mimetypes.

  • default – If no “Content-Type” can be guessed, default to default.

Multipart Forms#

urllib3.encode_multipart_formdata(fields, boundary=None)#

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

Parameters
urllib3.filepost.choose_boundary()#

Our embarrassingly-simple replacement for mimetools.choose_boundary.

urllib3.filepost.iter_field_objects(fields)#

Iterate over fields.

Supports list of (k, v) tuples and dicts, and lists of RequestField.