Streaming Form Data Parser

Common errors

• NameError: name 'MultipartFormParser' is not defined

  cause 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__'

  cause 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

  cause 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'

  cause 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`.

Warnings

• breaking Version 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+.
• gotcha The `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.
• gotcha By 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.
• gotcha This 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)`.

Install

• pip install streaming-form-data Install base library
• pip install streaming-form-data[charset_detection] Install with optional charset detection (cchardet)

Imports

• StreamingFormDataParser
  wrong:

  from streaming_form_data import MultipartFormParser

  correct:

  from streaming_form_data import StreamingFormDataParser

  Class was renamed from `MultipartFormParser` to `StreamingFormDataParser` in v2.0.0.
• ParseFailed
  wrong:

  from streaming_form_data import ParseFailed

  correct:

  from streaming_form_data.exceptions import ParseFailed

  `ParseFailed` exception was moved to the `exceptions` submodule in v2.0.0.
• FileTarget
  wrong:

  from streaming_form_data.targets import File

  correct:

  from streaming_form_data.targets import FileTarget

  `File` target was renamed to `FileTarget` in v2.0.0.
• ValueTarget

  from streaming_form_data.targets import ValueTarget

Quickstart

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()}'")