Sending Multipart Form Data with Python Requests

In this tutorial, we will cover how to send multipart form data using the popular Python requests library. This is a common requirement when interacting with web servers that expect form data, such as file uploads or text fields.

Introduction to Multipart Form Data

Multipart form data is a type of HTTP request body that allows you to send multiple types of data in a single request. This can include files, text fields, and other types of data. The requests library provides built-in support for sending multipart form data using the files parameter.

Using the files Parameter

The files parameter is a dictionary where the keys are the names of the form fields and the values are the corresponding values. For file uploads, the value should be a tuple containing the filename, the file object, and optionally the content type and custom headers.

Here’s an example of sending a multipart form request with a file upload:

import requests

url = 'http://httpbin.org/post'
files = {'file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel')}
response = requests.post(url, files=files)

In this example, we’re sending a file named report.xls with the content type application/vnd.ms-excel.

For text fields, you can pass a string as the value:

files = {'field': 'value'}

You can also use tuples to specify custom headers or content types for text fields:

files = {'field': (None, 'value')}

Note that when using tuples, the first element is the filename, which should be None for text fields.

Sending Multiple Fields with the Same Name

If you need to send multiple fields with the same name, you can pass a list of tuples instead of a dictionary:

files = (
    ('field', (None, 'value1')),
    ('field', (None, 'value2')),
    ('field', (None, 'value3')),
)

Using the MultipartEncoder from Requests Toolbelt

The requests library also provides an alternative way to send multipart form data using the MultipartEncoder class from the requests toolbelt library. This class allows you to define the payload as a dictionary, tuple, or list.

Here’s an example of sending a multipart form request with a file upload and text fields:

import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder

url = 'http://httpbin.org/post'
multipart_data = MultipartEncoder(
    fields={
        'file': ('file.zip', open('file.zip', 'rb'), 'text/plain'),
        'field0': 'value0',
        'field1': 'value1',
    }
)
response = requests.post(url, data=multipart_data, headers={'Content-Type': multipart_data.content_type})

Note that when using the MultipartEncoder, you need to pass the content_type header manually.

Best Practices

• Always use the files parameter or the MultipartEncoder class to send multipart form data.
• Use tuples to specify custom headers or content types for text fields.
• Pass a list of tuples instead of a dictionary when sending multiple fields with the same name.
• Use the requests toolbelt library for more advanced features, such as file upload streaming.

By following these best practices and examples, you should be able to send multipart form data using the Python requests library with ease.