python-multipart

python-multipart is an Apache2-licensed, dependency-free streaming parser for multipart/form-data, URL-encoded querystrings, and raw octet streams. It processes uploads incrementally as bytes arrive rather than buffering entire request bodies in memory, making it well suited for large file uploads and high-throughput web servers.

The library is the parsing engine behind Starlette and FastAPI’s request-form handling, and it exposes callback-driven parsers plus a convenient high-level parse_form helper. With 100% test coverage and continuous fuzzing, it is a battle-tested, production-grade component used across the Python web ecosystem.

What You Get

• A streaming multipart/form-data parser that emits fields and file chunks via callbacks without buffering the full request body
• Dedicated parsers for querystrings and raw octet streams alongside the multipart parser
• A high-level parse_form / create_form_parser API plus Field and File abstractions that spool large uploads to disk
• Base64 and quoted-printable stream decoders for transfer-encoded content
• Typed exceptions (MultipartParseError, QuerystringParseError, DecodeError) with byte-offset error reporting

Common Use Cases

• Handling file uploads in ASGI/WSGI web frameworks such as FastAPI and Starlette
• Parsing form submissions in a custom Python web server or middleware layer
• Streaming very large uploads to disk with a bounded memory footprint
• Decoding Base64 or quoted-printable encoded form parts

Under The Hood

Architecture - The core is a hand-written, callback-driven state machine in python_multipart/multipart.py (~1,900 lines). BaseParser defines the callback dispatch, and MultipartParser, QuerystringParser, and OctetStreamParser each advance through explicit IntEnum states (MultipartState, QuerystringState) byte by byte as write() is fed chunks, invoking on_field_data, on_part_begin, and similar callbacks rather than materializing the full body. The high-level FormParser plus create_form_parser/parse_form wire these low-level parsers to Field and File objects that spool oversized parts to temporary files. parse_options_header handles Content-Type/Content-Disposition header parsing.

Tech Stack - Pure Python (>=3.10) with zero runtime dependencies, built with the Hatchling backend and versioned from __init__.py. Development tooling uses uv for locking, pytest with pytest-cov and pytest-codspeed for benchmarks, ruff and mypy for lint/types, nox for task orchestration, and atheris for fuzzing. Docs are built with MkDocs Material.

Code Quality - Exceptionally high. The project advertises 100% test coverage, and the tests/ directory (test_multipart.py, test_file.py, test_benchmarks.py) plus a dedicated fuzz/ suite exercise the parsers extensively. The codebase is fully type-annotated, uses a clean exception hierarchy in exceptions.py (FormParserError -> ParseError -> specific errors) with byte-offset reporting, and keeps a legacy multipart/ shim alongside the canonical python_multipart/ package for import-compatibility.

API Design - The public surface is small and well-documented via docstrings and a hosted docs site. Low-level parsers require wiring callbacks, which is powerful but verbose; the parse_form and create_form_parser helpers give a much simpler entry point for common cases. Naming is consistent and the Field/File abstractions map cleanly onto form semantics, so most users get started with a single high-level call.