Fields¶

classurllib3.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:Theheader_formatter parameter is deprecated and willbe removed in urllib3 v2.1.0.

_render_part(name,value)¶

Override this method to change how each multipart headerparameter is formatted. By default, this callsformat_multipart_header_param().

Parameters:

• name (str) – The name of the parameter, an ASCII-onlystr.

• value (str |bytes) – The value of the parameter, astr or UTF-8 encodedbytes.

Return type:

str

classmethodfrom_tuples(fieldname,value,header_formatter=None)¶

ARequestField factory from old-style tuple parameters.

Supports constructingRequestField fromparameter 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 toformat_multipart_header_param(). Will beremoved 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 toformat_multipart_header_param(). Will beremoved 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 thestrategy defined in RFC 2231.

Particularly useful for header parameters which might containnon-ASCII values, like file names. This followsRFC 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 asbytes orstr`.

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 formultipart/form-data header parameters.

urllib3.fields.format_multipart_header_param(name,value)¶

Format and quote a single multipart header parameter.

This follows theWHATWG HTML Standard as of 2021/06/10, matchingthe behavior of current browser and curl versions. Values areassumed to be UTF-8. The\n,\r, and" characters arepercent encoded.

Parameters:

• name (str) – The name of the parameter, an ASCII-onlystr.

• value (str |bytes) – The value of the parameter, astr or UTF-8 encodedbytes.

Returns:

A stringname="value" with the escaped value.

Return type:

str

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

Changed in version 2.0.0:Renamed fromformat_header_param_html5 andformat_header_param. The old names will be removed inurllib3 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 usingmimetypes.

• default (str) – If no “Content-Type” can be guessed, default todefault.

Return type:

str

Multipart Forms¶

urllib3.encode_multipart_formdata(fields,boundary=None)¶

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

Parameters:

• fields (Sequence[tuple[str,str |bytes |tuple[str,str |bytes]|tuple[str,str |bytes,str]]|RequestField]|Mapping[str,str |bytes |tuple[str,str |bytes]|tuple[str,str |bytes,str]]) – Dictionary of fields or list of (key,RequestField).Values are processed byurllib3.fields.RequestField.from_tuples().

• boundary (str |None) – If not specified, then a random boundary will be generated usingurllib3.filepost.choose_boundary().

Return type:

tuple[bytes,str]

urllib3.filepost.choose_boundary()¶

Our embarrassingly-simple replacement for mimetools.choose_boundary.

Return type:

str

urllib3.filepost.iter_field_objects(fields)¶

Iterate over fields.

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

Parameters:

fields (Sequence[tuple[str,str |bytes |tuple[str,str |bytes]|tuple[str,str |bytes,str]]|RequestField]|Mapping[str,str |bytes |tuple[str,str |bytes]|tuple[str,str |bytes,str]])

Return type:

Iterable[RequestField]