Python Multipart

0.0.22 · active · verified Sat Mar 28

python-multipart is an Apache2-licensed streaming multipart parser for Python. It is designed for handling `multipart/form-data` POST requests, typically used in web servers for file uploads and complex form data. The library is actively maintained with frequent releases, currently at version 0.0.22, and supports modern Python versions (>=3.10).

Warnings

breaking The import name was changed from `multipart` to `python_multipart` in version 0.0.13. Direct imports using `import multipart` will no longer work and may lead to `ModuleNotFoundError` or unexpected behavior if another `multipart` package is installed. Versions 0.0.13 and 0.0.14 were temporarily yanked due to breakage related to this change.
Fix: Update all import statements from `import multipart` or `from multipart import ...` to `from python_multipart import ...`.
breaking Support for Python 3.8 and 3.9 was dropped in version 0.0.21. The library now requires Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or a newer supported version (e.g., 3.11, 3.12, 3.13, 3.14).
gotcha A separate, unrelated package on PyPI is also named `multipart`. Installing `pip install multipart` instead of `pip install python-multipart` will install the wrong library, leading to `ModuleNotFoundError` if `from python_multipart import ...` is used, or unexpected behavior if `import multipart` is still in your code.
Fix: Always use `pip install python-multipart` to ensure the correct library is installed.
gotcha In version 0.0.22, the `File` object produced by the parser will no longer include directory paths in its `filename` attribute. It will only contain the base filename.
Fix: If your application relied on `File.filename` containing a path, adjust your logic to expect only the base name. If paths are critical, you may need to implement custom logic to extract them from the `Content-Disposition` header directly (if present and needed).
gotcha Version 0.0.18 introduced a 'hard break' if data is found after the last boundary in `MultipartParser`. This means the parser will now strictly enforce the end of the multipart body, potentially raising errors for malformed requests that previously might have been partially processed.
Fix: Ensure that clients sending multipart data adhere strictly to the `multipart/form-data` specification, particularly regarding the final boundary and any subsequent data.
deprecated In version 0.0.15, `FutureWarning` messages were replaced with `PendingDeprecationWarning`. While not a breaking change, it indicates that certain behaviors or features are slated for deprecation or removal in future major releases.
Fix: Monitor the project's changelog and documentation for details on upcoming deprecations. Address any `PendingDeprecationWarning` messages in your code to prepare for future breaking changes.

Install

pip install python-multipart Install latest version

Imports

MultipartParser
```
from python_multipart import MultipartParser
```
The package to install is `python-multipart`, but the module to import is `python_multipart`. The old import path `import multipart` was changed in version 0.0.13 and conflicts with a separate, different PyPI package named `multipart`.

Quickstart

This quickstart demonstrates how to parse a `multipart/form-data` request body using `MultipartParser`. It simulates an incoming HTTP request with form fields and a file, processing them using event-like iteration.

import io
from python_multipart import MultipartParser

# Simulate an HTTP request body with multipart/form-data
boundary = b"----WebKitFormBoundary7MA4YWxkTrZu0gW"
body_data = (
    b"--" + boundary + b"\r\n"
    b'Content-Disposition: form-data; name="username"\r\n'
    b'\r\n'
    b'testuser\r\n'
    b"--" + boundary + b"\r\n"
    b'Content-Disposition: form-data; name="upload_file"; filename="hello.txt"\r\n'
    b'Content-Type: text/plain\r\n'
    b'\r\n'
    b'Hello, World!\nThis is a test file.\r\n'
    b"--" + boundary + b"--\r\n"
)

# Simulate HTTP headers
headers = {
    "Content-Type": f"multipart/form-data; boundary={boundary.decode()}",
    "Content-Length": str(len(body_data)),
}

# Use BytesIO to simulate a file-like object for the body stream
body_stream = io.BytesIO(body_data)

# Create a parser instance
parser = MultipartParser(headers)

# Iterate through parts and process them
print("Parsing multipart data:")
for part in parser.parse(body_stream):
    if hasattr(part, 'field_name'): # It's a form field
        print(f"  Field: name={part.field_name.decode()}, value={part.value.decode()}")
    elif hasattr(part, 'file_name'): # It's an uploaded file
        print(f"  File: name={part.field_name.decode()}, filename={part.file_name.decode()}, content_type={part.content_type.decode()}")
        file_content = part.value # The file content is available as bytes
        print(f"  File content length: {len(file_content)} bytes")
        # In a real application, you would typically save or process file_content

print("\nParsing complete.")

view raw JSON →