Python Guide: Upload Files with Requests Library - Tutorial

File uploading is a common task in web development. Python's requests library makes it straightforward to upload files to web servers. This guide will show you how to handle various file upload scenarios efficiently.

Basic File Upload

The simplest way to upload a file is using the files parameter in a POST request. Here's how to upload a single file:

import requests

with open('example.txt', 'rb') as file:
    files = {'file': file}
    response = requests.post('https://httpbin.org/post', files=files)

print(response.json())

Multiple File Upload

You can upload multiple files in a single request by adding more entries to the files dictionary. Similar to how we handle form data in requests:

import requests

files = {
    'file1': open('file1.txt', 'rb'),
    'file2': open('file2.jpg', 'rb')
}

response = requests.post('https://httpbin.org/post', files=files)

Custom Filename and Content Type

Sometimes you need to specify the filename or content type. You can do this by passing a tuple containing the filename, content type, and file object:

import requests

files = {
    'file': ('report.pdf', open('document.pdf', 'rb'), 'application/pdf')
}
response = requests.post('https://httpbin.org/post', files=files)

Upload Progress Tracking

For large files, it's useful to track upload progress. You can implement a custom progress monitor by combining requests with tqdm:

from tqdm import tqdm
import requests

def upload_with_progress(filename, url):
    with open(filename, 'rb') as f:
        total_size = os.path.getsize(filename)
        with tqdm(total=total_size, unit='B', unit_scale=True) as pbar:
            requests.post(url, files={'file': f}, 
                        headers={'Content-Length': str(total_size)})

Error Handling

Always implement proper error handling when uploading files. Like with other requests operations, you should handle potential exceptions as shown in our error handling guide:

try:
    with open('file.txt', 'rb') as f:
        response = requests.post('https://httpbin.org/post', files={'file': f})
    response.raise_for_status()
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Stream Large Files

For large files, it's recommended to stream the upload to avoid memory issues. This can be combined with asynchronous requests for better performance:

def stream_file(filename):
    with open(filename, 'rb') as f:
        while True:
            chunk = f.read(8192)
            if not chunk:
                break
            yield chunk

files = {'file': stream_file('large_file.zip')}
response = requests.post('https://httpbin.org/post', files=files)

Conclusion

File uploading with Python requests is versatile and powerful. Remember to always use proper error handling and consider memory usage for large files.

For more advanced scenarios, you might want to explore session management or authentication.