Fields and Multipart Forms¶

Fields¶

class urllib3.fields.RequestField(name, data, filename=None, headers=None, header_formatter=None)¶

Bases: object

A data container for request body parameters.

Parameters:

name (str) – The name of this request field. Must be unicode.
data (_TYPE_FIELD_VALUE) – The data/value body.
filename (str | None) – An optional filename of the request field. Must be unicode.
headers (Mapping[str, str] | None) – An optional dict-like object of headers to initially use for the field.
header_formatter (Callable[[str, _TYPE_FIELD_VALUE], str] | None)

Changed in version 2.0.0: The header_formatter parameter is deprecated and will be removed in urllib3 v2.1.0.

_render_part(name, value)¶

Override this method to change how each multipart header parameter is formatted. By default, this calls format_multipart_header_param().

Parameters:

name (str) – The name of the parameter, an ASCII-only str.
value (str | bytes) – The value of the parameter, a str or UTF-8 encoded bytes.

Return type:

str

classmethod from_tuples(fieldname, value, header_formatter=None)¶

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.

Parameters:

fieldname (str)
value (str | bytes | tuple[str, str | bytes] | tuple[str, str | bytes, str])
header_formatter (Callable[[str, str | bytes], str] | None)

Return type:

RequestField

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_disposition (str | None) – The ‘Content-Disposition’ of the request body. Defaults to ‘form-data’
content_type (str | None) – The ‘Content-Type’ of the request body.
content_location (str | None) – The ‘Content-Location’ of the request body.

Return type:

None

render_headers()¶

Renders the headers for this request field.

Return type:: str

urllib3.fields.format_header_param(name, value)¶

Deprecated since version 2.0.0: Renamed to format_multipart_header_param(). Will be removed in urllib3 v2.1.0.

Parameters:

name (str)
value (str | bytes)

Return type:

str

urllib3.fields.format_header_param_html5(name, value)¶

Deprecated since version 2.0.0: Renamed to format_multipart_header_param(). Will be removed in urllib3 v2.1.0.

Parameters:

name (str)
value (str | bytes)

Return type:

str

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 (str) – The name of the parameter, a string expected to be ASCII only.
value (str | bytes) – The value of the parameter, provided as bytes or str`.

Returns:

An RFC-2231-formatted unicode string.

Return type:

str

Deprecated since version 2.0.0: Will be removed in urllib3 v2.1.0. This is not valid for multipart/form-data header parameters.

urllib3.fields.format_multipart_header_param(name, value)¶

Format and quote a single multipart header parameter.

This follows the WHATWG HTML Standard as of 2021/06/10, matching the behavior of current browser and curl versions. Values are assumed to be UTF-8. The \n, \r, and " characters are percent encoded.

Parameters:

name (str) – The name of the parameter, an ASCII-only str.
value (str | bytes) – The value of the parameter, a str or UTF-8 encoded bytes.

Returns:

A string name="value" with the escaped value.

Return type:

str

Changed in version 2.0.0: Matches the WHATWG HTML Standard as of 2021/06/10. Control characters are no longer percent encoded.

Changed in version 2.0.0: Renamed from format_header_param_html5 and format_header_param. The old names will be removed in urllib3 v2.1.0.

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

Guess the “Content-Type” of a file.

Parameters:

filename (str | None) – The filename to guess the “Content-Type” of using mimetypes.
default (str) – If no “Content-Type” can be guessed, default to default.

Return type: