Загрузка файлов через POST запросы в Python: полный разбор

Расширенные примеры отправки файлов через POST

Ниже приведены более сложные сценарии, которые встречаются в реальных проектах.

Отправка файла с прогресс-баром (tqdm)

Для отслеживания прогресса загрузки большого файла можно использовать библиотеку tqdm. Устанавливается она отдельно (pip install tqdm). Ниже пример с собственной функцией генерации данных из файла:

import requests
from tqdm import tqdm

class FileWithProgress:
    def __init__(self, filename, mode='rb'):
        self.file = open(filename, mode)
        self.file_size = os.path.getsize(filename)
        self.progress = tqdm(total=self.file_size, unit='B', unit_scale=True)

    def __iter__(self):
        return self

    def __next__(self):
        chunk = self.file.read(1048576)  # 1 MB
        if not chunk:
            self.progress.close()
            self.file.close()
            raise StopIteration
        self.progress.update(len(chunk))
        return chunk

url = 'https://httpbin.org/post'
files = {'file': ('bigfile.iso', FileWithProgress('bigfile.iso'), 'application/octet-stream')}
response = requests.post(url, files=files)
print(response.status_code)

Предполагаемый вывод (прогресс-бар):
1.24GB [00:45, 28.2MB/s]

Важно: при таком подходе запрос не использует Content-Length, а применяется chunked transfer encoding. Сервер должен поддерживать такую передачу.

Использование сессии для нескольких файлов с авторизацией

При отправке файлов на защищённый ресурс удобно создать сессионный объект, который сохраняет куки и заголовки:

import requests

session = requests.Session()
session.auth = ('user', 'pass')  # базовая аутентификация
session.headers.update({'X-Custom': 'value'})

url = 'https://example.com/api/upload'
with open('file.txt', 'rb') as f:
    response = session.post(url, files={'file': f})
print(response.json())

Ответ сервера (пример):
{"status": "ok", "filename": "file.txt"}

Отправка файла вместе с JSON-данными

Иногда требуется передать и файл, и JSON-структуру в одном запросе. Для этого JSON-данные помещаются в параметр data в виде строки, а файл - в files:

import json

url = 'https://httpbin.org/post'
metadata = {
    'description': 'photo from vacation',
    'tags': ['sunset', 'beach']
}
with open('sunset.jpg', 'rb') as f:
    response = requests.post(
        url,
        data={'json': json.dumps(metadata)},
        files={'image': ('sunset.jpg', f, 'image/jpeg')}
    )
print(response.request.body)  # видно, как смешиваются части

Часть вывода (отладочная информация) может выглядеть как:
b'--...\r\nContent-Disposition: form-data...'

Отправка файла с использованием параметра params

Если сервер ожидает дополнительные URL-параметры при загрузке, они передаются через params. Пример с указанием версии API:

url = 'https://example.com/upload'
params = {'api_version': '2.0'}
with open('data.json', 'rb') as f:
    response = requests.post(url, files={'file': f}, params=params)
print(response.url) # https://example.com/upload?api_version=2.0

Отправка файла через потоковую передачу (stream=True)

Для больших файлов полезно установить stream=True, чтобы не загружать ответ целиком в память. Однако это не влияет на отправку, только на получение:

with open('large_file.mp4', 'rb') as f:
    response = requests.post(url, files={'video': f}, stream=True)
    # Читаем ответ порциями
    for chunk in response.iter_content(chunk_size=8192):
        if chunk:
            print('.', end='')  # имитация обработки ответа

Вывод: точки печатаются по мере поступления чанков.

Использование кастомных заголовков для multipart/form-data

Можно явно задать заголовок Content-Type с границей, но библиотека делает это автоматически. Пример, когда нужно изменить только код формы:

headers = {'Accept': 'application/json'}
response = requests.post(url, files={'file': open('doc.pdf', 'rb')}, headers=headers)

Асинхронная отправка файлов (aiohttp)

Хотя основная статья посвящена requests, стоит упомянуть асинхронный аналог. Пример с aiohttp для отправки нескольких файлов параллельно:

import aiohttp
import asyncio

async def upload_file(session, url, path):
    with open(path, 'rb') as f:
        data = aiohttp.FormData()
        data.add_field('file', f, filename=path.name)
        async with session.post(url, data=data) as resp:
            return await resp.json()

async def main():
    async with aiohttp.ClientSession() as session:
        results = await asyncio.gather(
            upload_file(session, 'https://httpbin.org/post', 'file1.txt'),
            upload_file(session, 'https://httpbin.org/post', 'file2.txt')
        )
        print(results)

asyncio.run(main())

Результат - список ответов от сервера для каждого файла.