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.
filename (Optional[str]) – An optional filename of the request field. Must be unicode.
headers (Optional[Mapping[str, str]]) – An optional dict-like object of headers to initially use for the field.
header_formatter (Optional[Callable[[str, Union[str, bytes]], str]]) –
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()
.
- 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.
- 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.
- 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.
- 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.
- 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
- Returns
An RFC-2231-formatted unicode string.
- Return type
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
- Returns
A string
name="value"
with the escaped value.- Return type
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
andformat_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.
Multipart Forms#
- urllib3.encode_multipart_formdata(fields, boundary=None)#
Encode a dictionary of
fields
using the multipart/form-data MIME format.- Parameters
fields (Union[Sequence[Union[Tuple[str, Union[str, bytes, Tuple[str, Union[str, bytes]], Tuple[str, Union[str, bytes], str]]], RequestField]], Mapping[str, Union[str, bytes, Tuple[str, Union[str, bytes]], Tuple[str, Union[str, bytes], str]]]]) – Dictionary of fields or list of (key,
RequestField
). Values are processed byurllib3.fields.RequestField.from_tuples()
.boundary (Optional[str]) – If not specified, then a random boundary will be generated using
urllib3.filepost.choose_boundary()
.
- Return type
- urllib3.filepost.choose_boundary()#
Our embarrassingly-simple replacement for mimetools.choose_boundary.
- Return type
- urllib3.filepost.iter_field_objects(fields)#
Iterate over fields.
Supports list of (k, v) tuples and dicts, and lists of
RequestField
.