Registry / http-networking / streaming-form-data

streaming-form-data

JSON →
library2.1.0pypypi✓ verified 85d ago

streaming-form-data is a Python library designed for parsing `multipart/form-data` HTTP requests in a streaming fashion, making it suitable for handling large file uploads and form submissions without loading the entire request body into memory. The current version is 2.0.0, and it follows an active maintenance release cadence, with major versions introducing significant changes.

pip install streaming-form-data
INSTALL
IMPORT
SIG · STREAMING-FORM-DAT
S
streaming-form-data
http-networkingpythonv2.1.0
Install
2.1s avg
Import
421ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 0.450s · 21.5MB
glibc
py 3.103.940 runs
installs and imports cleanly · install 2.1s · import 0.391s · 23MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

StreamingFormDataParser
from streaming_form_data import StreamingFormDataParser
from streaming_form_data import MultipartFormParser
Class was renamed from `MultipartFormParser` to `StreamingFormDataParser` in v2.0.0.
ParseFailed
from streaming_form_data.exceptions import ParseFailed
from streaming_form_data import ParseFailed
`ParseFailed` exception was moved to the `exceptions` submodule in v2.0.0.
FileTarget
from streaming_form_data.targets import FileTarget
from streaming_form_data.targets import File
`File` target was renamed to `FileTarget` in v2.0.0.
ValueTarget
from streaming_form_data.targets import ValueTarget

This quickstart demonstrates how to parse a `multipart/form-data` payload containing both a text field and a file upload. It simulates an incoming HTTP stream using `io.BytesIO`, registers `ValueTarget` for text fields and `FileTarget` for files, and processes the stream in chunks.

import io from streaming_form_data import StreamingFormDataParser from streaming_form_data.targets import ValueTarget, FileTarget # Simulate an incoming HTTP request body and headers boundary = b'----WebKitFormBoundary7MA4YWxkTrZu0gW' content_type = b'multipart/form-data; boundary=' + boundary payload = ( b'--' + boundary + b'\r\n' b'Content-Disposition: form-data; name="text_field"\r\n' b'\r\n' b'Hello Streaming World!' b'\r\n' b'--' + boundary + b'\r\n' b'Content-Disposition: form-data; name="file_upload"; filename="message.txt"\r\n' b'Content-Type: text/plain\r\n' b'\r\n' b'This is a test file content.\nLine two.\n' b'\r\n' b'--' + boundary + b'--\r\n' ) headers = {b'Content-Type': content_type} parser = StreamingFormDataParser(headers=headers) text_field = ValueTarget() file_target = FileTarget(file_path='/tmp/uploaded_message.txt') # Path where the file will be saved parser.register('text_field', text_field) parser.register('file_upload', file_target) # In a real web application, `request.body` would be streamed here # For this example, we use a BytesIO object to simulate the stream stream = io.BytesIO(payload) while True: chunk = stream.read(8192) # Read in chunks if not chunk: break parser.data_received(chunk) print(f"Text field value: '{text_field.value.decode()}'") print(f"File saved to: '{file_target.file_path}'") # Verify content (optional, for demonstration) with open(file_target.file_path, 'rb') as f: print(f"File content: '{f.read().decode()}'")
Debug
Known issues
breakingVersion 2.0.0 introduced significant breaking changes. Key classes were renamed (`MultipartFormParser` to `StreamingFormDataParser`, `File` to `FileStream`), constructor arguments for `Field` and `FileStream` were modified, and `ParseFailed` exception was moved. Python 3.10 or newer is now required.
fix
Update all class names, import paths, and constructor calls according to the v2.0.0 changelog. Ensure your environment uses Python 3.10+.
affects: >=2.0.0 (from 1.x.x)
gotchaThe `streaming_form_data.exceptions.ParseFailed` exception is raised for any malformed `multipart/form-data` payload. This includes incorrect `Content-Type` headers (missing boundary, wrong media type), or an invalid structure within the payload itself.
fix
Always wrap parser operations in a `try...except ParseFailed:` block. Thoroughly validate incoming `Content-Type` headers and ensure client-side form data generation adheres to RFC 7578. Double-check the boundary string.
affects: All
gotchaBy default, `streaming-form-data` assumes UTF-8 encoding for text fields. If you need robust detection for other charsets (e.g., ISO-8859-1), you must install the optional `cchardet` dependency.
fix
Install `cchardet` via `pip install streaming-form-data[charset_detection]`. The library will then automatically use `cchardet` for charset detection if available.
affects: All
gotchaThis library is designed for streaming. Failing to feed data to the parser in chunks (e.g., trying to read an entire large request body into memory before passing it to `parser.data_received`) defeats its purpose and can lead to memory exhaustion.
fix
Ensure you are reading from the incoming stream (e.g., `request.body` in a web framework) in small chunks (e.g., 8192 bytes) within a loop and passing each chunk to `parser.data_received(chunk)`.
affects: All
Errors
Common errors & fixes
NameError: name 'MultipartFormParser' is not defined
You are using a class name from version 1.x.x of the library, which was renamed in v2.0.0.
fix
Change `MultipartFormParser` to `StreamingFormDataParser`.
AttributeError: type object 'ParseFailed' has no attribute '__module__'
The `ParseFailed` exception was moved to a specific submodule in v2.0.0.
fix
Update the import statement: `from streaming_form_data.exceptions import ParseFailed`.
streaming_form_data.exceptions.ParseFailed: Malformed multipart body
The incoming `multipart/form-data` payload is structurally incorrect, or the `Content-Type` header (especially the `boundary` parameter) does not match the actual boundary strings in the request body.
fix
Verify that the `Content-Type` header passed to `StreamingFormDataParser` exactly matches the client's header, particularly the `boundary`. Also, check that the payload is well-formed with correct boundary markers (`--boundary\r\n` and `--boundary--\r\n` at the end).
TypeError: FileTarget() got an unexpected keyword argument 'filename'
The `FileTarget` class (previously `File`) in v2.0.0 no longer accepts a `filename` argument directly in its constructor. It expects `file_path` for a path or `target` for a file-like object.
fix
Replace `filename='your_file.txt'` with `file_path='/path/to/save/your_file.txt'` when instantiating `FileTarget`.
Upgrade
Version history
2.1.0latest on PyPI · released Jun 10, 2026
Audit
Dependencies
cchardetoptionalOptional dependency for more robust charset detection; without it, UTF-8 is assumed for field values.
Agent activity
12 hits · last 30 days
node
8
OpenAI (training)
2
Resources
streaming-form-data — pip install streaming-form-data · libregistry