Fields and Multipart Forms - urllib3 1.26.2 documentation

Support urllib3 on GitHub Sponsors

# 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

    - fields – Dictionary of fields or list of (key, `RequestField`).

    - boundary – If not specified, then a random boundary will be generated using `urllib3.filepost.choose_boundary()`.

`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`.