parse-multipart-form-data 0.1.0a0__tar.gz

parse_multipart_form_data-0.1.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jifeng Wu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parse_multipart_form_data-0.1.0a0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: parse-multipart-form-data
+Version: 0.1.0a0
+Summary: A streaming parser for multipart/form-data request bodies.
+Author-email: Jifeng Wu <jifengwu2k@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jifengwu2k/parse-multipart-form-data
+Project-URL: Bug Tracker, https://github.com/jifengwu2k/parse-multipart-form-data/issues
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=2
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: enum34; python_version < "3.4"
+Requires-Dist: parse-http-header-line
+Requires-Dist: put-back-iterator
+Requires-Dist: typing; python_version < "3.5"
+Dynamic: license-file
+
+# parse-multipart-form-data
+
+A small, streaming parser for HTTP `multipart/form-data` request bodies.
+
+The parser consumes an iterable of byte chunks and yields a streaming event
+sequence for each uploaded file. It does not depend on a web framework or read
+from sockets itself, so callers control request-body I/O and where uploaded
+content is stored.
+
+## Installation
+
+```bash
+pip install parse-multipart-form-data
+```
+
+For local development from this checkout:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from parse_multipart_form_data import (
+    PartBegin,
+    PartData,
+    PartEnd,
+    parse_multipart_form_data,
+)
+
+body_chunks = [
+    b"--BOUNDARY\r\n",
+    b'Content-Disposition: form-data; name="file"; filename="hello.txt"\r\n',
+    b"\r\n",
+    b"hello world\r\n",
+    b"--BOUNDARY--\r\n",
+]
+
+output = None
+for event in parse_multipart_form_data(
+        "multipart/form-data; boundary=BOUNDARY", body_chunks):
+    if isinstance(event, PartBegin):
+        output = open(event.filename, "wb")
+    elif isinstance(event, PartData):
+        output.write(event.data)
+    else:  # PartEnd
+        output.close()
+```
+
+The event stream is:
+
+- `PartBegin(filename)` at the beginning of a file part;
+- `PartData(bytes_chunk)` for each file-content chunk; and
+- `PartEnd(is_final)` after its delimiter has been consumed.
+
+Only parts with a `filename` or `filename*` parameter produce events; ordinary
+form fields are consumed and skipped. A valid RFC 6266 `filename*` (UTF-8 or
+ISO-8859-1) takes precedence over `filename`.
+
+## Delimiter compatibility
+
+Only exact delimiter lines are supported:
+
+```text
+--BOUNDARY\r\n
+--BOUNDARY--\r\n
+```
+
+MIME transport padding (spaces or tabs after a delimiter) is not supported.
+Supporting arbitrary transport padding requires byte-by-byte input reading,
+which is inefficient in Python and rare in real-world multipart form uploads.
+
+Boundary values may be quoted or unquoted, including RFC 2046 boundary
+characters such as `=`, `:`, `/`, `?`, `(`, `)`, and `,`. Preamble and
+part-header lines are limited to 8192 bytes of content.
+
+## Parser states
+
+The parser has one `MultipartState` vocabulary. Its transitions are:
+
+```text
+SEEK_OPENING_BOUNDARY -> READ_HEADERS | DONE
+READ_HEADERS          -> MAYBE_BOUNDARY
+READ_PART_BODY        -> READ_PART_BODY | MAYBE_BOUNDARY
+MAYBE_BOUNDARY        -> MAYBE_BOUNDARY | READ_PART_BODY | READ_HEADERS | DONE
+```
+
+### Minimal wire-format machine
+
+For the multipart example in the module documentation, the parser's essential
+wire-level transitions are (`CRLF` denotes the literal `\r\n` byte pair):
+
+```mermaid
+stateDiagram-v2
+    [*] --> SEEK_OPENING_BOUNDARY
+    SEEK_OPENING_BOUNDARY --> READ_HEADERS: --BOUNDARY CRLF
+    SEEK_OPENING_BOUNDARY --> DONE: --BOUNDARY-- CRLF
+    READ_HEADERS --> READ_HEADERS: header CRLF
+    READ_HEADERS --> MAYBE_BOUNDARY: blank CRLF / empty part check
+    READ_PART_BODY --> READ_PART_BODY: not *.CRLF
+    READ_PART_BODY --> MAYBE_BOUNDARY: *.CRLF
+    MAYBE_BOUNDARY --> MAYBE_BOUNDARY: non-boundary line ending CRLF
+    MAYBE_BOUNDARY --> READ_PART_BODY: non-boundary prefix
+    MAYBE_BOUNDARY --> READ_HEADERS: --BOUNDARY CRLF
+    MAYBE_BOUNDARY --> DONE: --BOUNDARY-- CRLF
+    DONE --> [*]
+```
+
+The single parser generator holds its state across every event. A boundary
+suffix is consumed before it emits `PartEnd`, so the next event always starts
+a well-defined next transition.
+
+## Testing
+
+```bash
+python -m unittest discover -s tests
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

parse_multipart_form_data-0.1.0a0/README.md

@@ -0,0 +1,122 @@
+# parse-multipart-form-data
+
+A small, streaming parser for HTTP `multipart/form-data` request bodies.
+
+The parser consumes an iterable of byte chunks and yields a streaming event
+sequence for each uploaded file. It does not depend on a web framework or read
+from sockets itself, so callers control request-body I/O and where uploaded
+content is stored.
+
+## Installation
+
+```bash
+pip install parse-multipart-form-data
+```
+
+For local development from this checkout:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from parse_multipart_form_data import (
+    PartBegin,
+    PartData,
+    PartEnd,
+    parse_multipart_form_data,
+)
+
+body_chunks = [
+    b"--BOUNDARY\r\n",
+    b'Content-Disposition: form-data; name="file"; filename="hello.txt"\r\n',
+    b"\r\n",
+    b"hello world\r\n",
+    b"--BOUNDARY--\r\n",
+]
+
+output = None
+for event in parse_multipart_form_data(
+        "multipart/form-data; boundary=BOUNDARY", body_chunks):
+    if isinstance(event, PartBegin):
+        output = open(event.filename, "wb")
+    elif isinstance(event, PartData):
+        output.write(event.data)
+    else:  # PartEnd
+        output.close()
+```
+
+The event stream is:
+
+- `PartBegin(filename)` at the beginning of a file part;
+- `PartData(bytes_chunk)` for each file-content chunk; and
+- `PartEnd(is_final)` after its delimiter has been consumed.
+
+Only parts with a `filename` or `filename*` parameter produce events; ordinary
+form fields are consumed and skipped. A valid RFC 6266 `filename*` (UTF-8 or
+ISO-8859-1) takes precedence over `filename`.
+
+## Delimiter compatibility
+
+Only exact delimiter lines are supported:
+
+```text
+--BOUNDARY\r\n
+--BOUNDARY--\r\n
+```
+
+MIME transport padding (spaces or tabs after a delimiter) is not supported.
+Supporting arbitrary transport padding requires byte-by-byte input reading,
+which is inefficient in Python and rare in real-world multipart form uploads.
+
+Boundary values may be quoted or unquoted, including RFC 2046 boundary
+characters such as `=`, `:`, `/`, `?`, `(`, `)`, and `,`. Preamble and
+part-header lines are limited to 8192 bytes of content.
+
+## Parser states
+
+The parser has one `MultipartState` vocabulary. Its transitions are:
+
+```text
+SEEK_OPENING_BOUNDARY -> READ_HEADERS | DONE
+READ_HEADERS          -> MAYBE_BOUNDARY
+READ_PART_BODY        -> READ_PART_BODY | MAYBE_BOUNDARY
+MAYBE_BOUNDARY        -> MAYBE_BOUNDARY | READ_PART_BODY | READ_HEADERS | DONE
+```
+
+### Minimal wire-format machine
+
+For the multipart example in the module documentation, the parser's essential
+wire-level transitions are (`CRLF` denotes the literal `\r\n` byte pair):
+
+```mermaid
+stateDiagram-v2
+    [*] --> SEEK_OPENING_BOUNDARY
+    SEEK_OPENING_BOUNDARY --> READ_HEADERS: --BOUNDARY CRLF
+    SEEK_OPENING_BOUNDARY --> DONE: --BOUNDARY-- CRLF
+    READ_HEADERS --> READ_HEADERS: header CRLF
+    READ_HEADERS --> MAYBE_BOUNDARY: blank CRLF / empty part check
+    READ_PART_BODY --> READ_PART_BODY: not *.CRLF
+    READ_PART_BODY --> MAYBE_BOUNDARY: *.CRLF
+    MAYBE_BOUNDARY --> MAYBE_BOUNDARY: non-boundary line ending CRLF
+    MAYBE_BOUNDARY --> READ_PART_BODY: non-boundary prefix
+    MAYBE_BOUNDARY --> READ_HEADERS: --BOUNDARY CRLF
+    MAYBE_BOUNDARY --> DONE: --BOUNDARY-- CRLF
+    DONE --> [*]
+```
+
+The single parser generator holds its state across every event. A boundary
+suffix is consumed before it emits `PartEnd`, so the next event always starts
+a well-defined next transition.
+
+## Testing
+
+```bash
+python -m unittest discover -s tests
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

parse_multipart_form_data-0.1.0a0/parse_multipart_form_data.egg-info/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: parse-multipart-form-data
+Version: 0.1.0a0
+Summary: A streaming parser for multipart/form-data request bodies.
+Author-email: Jifeng Wu <jifengwu2k@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jifengwu2k/parse-multipart-form-data
+Project-URL: Bug Tracker, https://github.com/jifengwu2k/parse-multipart-form-data/issues
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=2
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: enum34; python_version < "3.4"
+Requires-Dist: parse-http-header-line
+Requires-Dist: put-back-iterator
+Requires-Dist: typing; python_version < "3.5"
+Dynamic: license-file
+
+# parse-multipart-form-data
+
+A small, streaming parser for HTTP `multipart/form-data` request bodies.
+
+The parser consumes an iterable of byte chunks and yields a streaming event
+sequence for each uploaded file. It does not depend on a web framework or read
+from sockets itself, so callers control request-body I/O and where uploaded
+content is stored.
+
+## Installation
+
+```bash
+pip install parse-multipart-form-data
+```
+
+For local development from this checkout:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from parse_multipart_form_data import (
+    PartBegin,
+    PartData,
+    PartEnd,
+    parse_multipart_form_data,
+)
+
+body_chunks = [
+    b"--BOUNDARY\r\n",
+    b'Content-Disposition: form-data; name="file"; filename="hello.txt"\r\n',
+    b"\r\n",
+    b"hello world\r\n",
+    b"--BOUNDARY--\r\n",
+]
+
+output = None
+for event in parse_multipart_form_data(
+        "multipart/form-data; boundary=BOUNDARY", body_chunks):
+    if isinstance(event, PartBegin):
+        output = open(event.filename, "wb")
+    elif isinstance(event, PartData):
+        output.write(event.data)
+    else:  # PartEnd
+        output.close()
+```
+
+The event stream is:
+
+- `PartBegin(filename)` at the beginning of a file part;
+- `PartData(bytes_chunk)` for each file-content chunk; and
+- `PartEnd(is_final)` after its delimiter has been consumed.
+
+Only parts with a `filename` or `filename*` parameter produce events; ordinary
+form fields are consumed and skipped. A valid RFC 6266 `filename*` (UTF-8 or
+ISO-8859-1) takes precedence over `filename`.
+
+## Delimiter compatibility
+
+Only exact delimiter lines are supported:
+
+```text
+--BOUNDARY\r\n
+--BOUNDARY--\r\n
+```
+
+MIME transport padding (spaces or tabs after a delimiter) is not supported.
+Supporting arbitrary transport padding requires byte-by-byte input reading,
+which is inefficient in Python and rare in real-world multipart form uploads.
+
+Boundary values may be quoted or unquoted, including RFC 2046 boundary
+characters such as `=`, `:`, `/`, `?`, `(`, `)`, and `,`. Preamble and
+part-header lines are limited to 8192 bytes of content.
+
+## Parser states
+
+The parser has one `MultipartState` vocabulary. Its transitions are:
+
+```text
+SEEK_OPENING_BOUNDARY -> READ_HEADERS | DONE
+READ_HEADERS          -> MAYBE_BOUNDARY
+READ_PART_BODY        -> READ_PART_BODY | MAYBE_BOUNDARY
+MAYBE_BOUNDARY        -> MAYBE_BOUNDARY | READ_PART_BODY | READ_HEADERS | DONE
+```
+
+### Minimal wire-format machine
+
+For the multipart example in the module documentation, the parser's essential
+wire-level transitions are (`CRLF` denotes the literal `\r\n` byte pair):
+
+```mermaid
+stateDiagram-v2
+    [*] --> SEEK_OPENING_BOUNDARY
+    SEEK_OPENING_BOUNDARY --> READ_HEADERS: --BOUNDARY CRLF
+    SEEK_OPENING_BOUNDARY --> DONE: --BOUNDARY-- CRLF
+    READ_HEADERS --> READ_HEADERS: header CRLF
+    READ_HEADERS --> MAYBE_BOUNDARY: blank CRLF / empty part check
+    READ_PART_BODY --> READ_PART_BODY: not *.CRLF
+    READ_PART_BODY --> MAYBE_BOUNDARY: *.CRLF
+    MAYBE_BOUNDARY --> MAYBE_BOUNDARY: non-boundary line ending CRLF
+    MAYBE_BOUNDARY --> READ_PART_BODY: non-boundary prefix
+    MAYBE_BOUNDARY --> READ_HEADERS: --BOUNDARY CRLF
+    MAYBE_BOUNDARY --> DONE: --BOUNDARY-- CRLF
+    DONE --> [*]
+```
+
+The single parser generator holds its state across every event. A boundary
+suffix is consumed before it emits `PartEnd`, so the next event always starts
+a well-defined next transition.
+
+## Testing
+
+```bash
+python -m unittest discover -s tests
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

parse_multipart_form_data-0.1.0a0/parse_multipart_form_data.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+parse_multipart_form_data.py
+pyproject.toml
+setup.cfg
+parse_multipart_form_data.egg-info/PKG-INFO
+parse_multipart_form_data.egg-info/SOURCES.txt
+parse_multipart_form_data.egg-info/dependency_links.txt
+parse_multipart_form_data.egg-info/requires.txt
+parse_multipart_form_data.egg-info/top_level.txt
+tests/test_parse_multipart_form_data.py

parse_multipart_form_data-0.1.0a0/parse_multipart_form_data.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

parse_multipart_form_data-0.1.0a0/parse_multipart_form_data.egg-info/requires.txt

@@ -0,0 +1,8 @@
+parse-http-header-line
+put-back-iterator
+
+[:python_version < "3.4"]
+enum34
+
+[:python_version < "3.5"]
+typing

parse_multipart_form_data-0.1.0a0/parse_multipart_form_data.egg-info/top_level.txt

@@ -0,0 +1 @@
+parse_multipart_form_data

parse_multipart_form_data-0.1.0a0/parse_multipart_form_data.py

@@ -0,0 +1,386 @@
+# Copyright (c) 2026 Jifeng Wu
+# Licensed under the MIT License. See LICENSE file in the project root
+# for full license information.
+"""Streaming parser for ``multipart/form-data`` request bodies.
+
+The parser is one explicit generator state machine. It emits a flat event
+stream for file-part starts, content chunks, and ends; it does not create a
+separate part object or nested content iterator.
+"""
+from __future__ import unicode_literals
+from enum import Enum
+from typing import Iterable, Iterator, List, Optional, Text, Tuple
+from parse_http_header_line import (
+    MalformedHeaderLineError,
+    MalformedParameterListError,
+    parse_name_value,
+    parse_parameters,
+)
+from put_back_iterator import PutBackIterator
+
+
+class MultipartState(Enum):
+    """The semantic states of ``parse_multipart_form_data``."""
+
+    SEEK_OPENING_BOUNDARY = 1
+    READ_HEADERS = 2
+    READ_PART_BODY = 3
+    MAYBE_BOUNDARY = 4
+    DONE = 5
+
+
+# Maximum content length of one preamble or part-header line. 8192 bytes is
+# the de facto per-line limit used by Apache, nginx, Tomcat, and Jetty.
+MAX_MULTIPART_HEADER_LINE = 8192
+
+
+class MultipartEvent(object):
+    """Base class for the events yielded by :func:`parse_multipart_form_data`."""
+
+    __slots__ = ()
+
+
+class PartBegin(MultipartEvent):
+    """A file part began with the decoded *filename*."""
+
+    __slots__ = ("filename",)
+
+    def __init__(self, filename):
+        # type: (Text) -> None
+        self.filename = filename
+
+
+class PartData(MultipartEvent):
+    """A chunk of file-part content."""
+
+    __slots__ = ("data",)
+
+    def __init__(self, data):
+        # type: (bytes) -> None
+        self.data = data
+
+
+class PartEnd(MultipartEvent):
+    """A file part ended; *is_final* marks the closing boundary."""
+
+    __slots__ = ("is_final",)
+
+    def __init__(self, is_final):
+        # type: (bool) -> None
+        self.is_final = is_final
+
+
+def read_crlf_chunk(stream):
+    # type: (PutBackIterator[bytes]) -> Tuple[Optional[bytes], bool]
+    """Read one CRLF-terminated chunk of bytes from *stream*.
+
+    Returns ``(chunk, True)`` when *chunk* ends with CRLF. Returns
+    ``(chunk, False)`` when *chunk* does not end with CRLF. A ``False``
+    result guarantees there is no CRLF straddling the chunk boundary: any
+    trailing CR has already been checked and is not followed by LF.
+
+    Returns ``(None, False)`` at end of stream.
+
+    The returned bytes are never modified: a terminating CRLF is included,
+    and any CR or CRLF in the middle of *chunk* is preserved verbatim.
+    """
+    while stream.has_next():
+        chunk = next(stream)
+        if not chunk:
+            continue
+
+        crlf_index = chunk.find(b"\r\n")
+        if crlf_index != -1:
+            first = chunk[: crlf_index + 2]
+            rest = chunk[crlf_index + 2 :]
+            if rest:
+                stream.put_back(rest)
+            return first, True
+
+        if not chunk.endswith(b"\r"):
+            return chunk, False
+
+        # The chunk ends with CR; look ahead for the matching LF. Empty
+        # chunks are skipped so the CR pairs with the next real byte.
+        next_chunk = b""
+        while stream.has_next():
+            next_chunk = next(stream)
+            if next_chunk:
+                break
+        else:
+            return chunk, False
+
+        if next_chunk[:1] == b"\n":
+            if len(next_chunk) > 1:
+                stream.put_back(next_chunk[1:])
+            return chunk + b"\n", True
+
+        stream.put_back(next_chunk)
+        return chunk, False
+
+    return None, False
+
+
+def read_crlf_line(stream, n=None):
+    # type: (PutBackIterator[bytes], Optional[int]) -> Tuple[Optional[bytes], bool]
+    """Read through one CRLF or at most *n* bytes when *n* is provided.
+
+    Returns ``(line, True)`` when *line* ends in CRLF. Returns ``(line,
+    False)`` when the optional limit is reached first or when end of stream
+    follows a non-terminated line. Returns ``(None, False)`` only when the
+    stream is already exhausted. The returned line includes its CRLF when
+    present.
+
+    Like :func:`read_crlf_chunk`, this function never splits a CRLF across a
+    returned non-terminated prefix and the unread stream. If *n* would cut
+    between CR and LF, it returns the shorter prefix and leaves the whole CRLF
+    unread.
+    """
+    fragments = []  # type: List[bytes]
+    remaining = n
+    while True:
+        if remaining == 0:
+            return b"".join(fragments), False
+        chunk, terminated = read_crlf_chunk(stream)
+        if chunk is None:
+            if fragments:
+                return b"".join(fragments), False
+            return None, False
+        if remaining is not None and len(chunk) > remaining:
+            length = remaining
+            if (
+                chunk[length - 1 : length] == b"\r"
+                and chunk[length : length + 1] == b"\n"
+            ):
+                length -= 1
+            fragments.append(chunk[:length])
+            stream.put_back(chunk[length:])
+            return b"".join(fragments), False
+        fragments.append(chunk)
+        if remaining is not None:
+            remaining -= len(chunk)
+        if terminated:
+            return b"".join(fragments), True
+
+
+def boundary_from_content_type(content_type):
+    # type: (Text) -> Optional[Text]
+    """Return the usable boundary from a ``multipart/form-data`` value."""
+    try:
+        type_text, parameters = parse_parameters(content_type)
+    except MalformedParameterListError:
+        return None
+
+    if type_text != "multipart/form-data":
+        return None
+
+    for name, value in parameters:
+        if name == "boundary":
+            return value or None
+    return None
+
+
+def filename_from_ext_value(value):
+    # type: (Text) -> Optional[Text]
+    """Decode an RFC 6266 ``filename*`` ext-value to a filename.
+
+    The ext-value is ``charset ' language ' percent-encoded-bytes``. UTF-8
+    and ISO-8859-1/Latin-1 charsets are supported; any other charset, a
+    malformed value, or bytes that do not decode are rejected by returning
+    ``None`` so the caller can fall back to a plain ``filename``.
+    """
+    parts = value.split("'", 2)
+    if len(parts) != 3:
+        return None
+    charset, language, encoded = parts
+    if not charset or not encoded:
+        return None
+
+    charset_lower = charset.lower()
+    if charset_lower in ("utf-8", "utf8"):
+        codec = "utf-8"
+    elif charset_lower in ("iso-8859-1", "latin-1", "latin1"):
+        codec = "latin-1"
+    else:
+        return None
+
+    data = encoded.encode("latin-1")
+    result = bytearray()
+    index = 0
+    length = len(data)
+    while index < length:
+        if data[index : index + 1] == b"%" and index + 2 < length:
+            try:
+                result.append(int(data[index + 1 : index + 3], 16))
+                index += 3
+                continue
+            except ValueError:
+                pass
+        result.append(data[index])
+        index += 1
+
+    try:
+        return bytes(result).decode(codec)
+    except UnicodeDecodeError:
+        return None
+
+
+def filename_from_header_line(header_line):
+    # type: (Text) -> Optional[Text]
+    """Return a UTF-8 (or Latin-1 fallback) filename from one header line.
+
+    A valid ``filename*`` parameter takes precedence over ``filename``.
+    """
+    try:
+        name, value = parse_name_value(header_line)
+    except MalformedHeaderLineError:
+        return None
+
+    if name != "content-disposition":
+        return None
+
+    try:
+        disposition, parameters = parse_parameters(value)
+    except MalformedParameterListError:
+        return None
+
+    if disposition != "form-data":
+        return None
+
+    filename = None
+    extended_filename = None
+    has_name = False
+    for parameter_name, parameter_value in parameters:
+        if parameter_name == "name":
+            has_name = True
+        elif parameter_name == "filename" and filename is None:
+            filename_bytes = parameter_value.encode("latin-1")
+            try:
+                filename = filename_bytes.decode("utf-8")
+            except UnicodeDecodeError:
+                filename = filename_bytes.decode("latin-1")
+        elif parameter_name == "filename*" and extended_filename is None:
+            extended_filename = filename_from_ext_value(parameter_value)
+
+    if has_name:
+        if extended_filename is not None:
+            return extended_filename
+        return filename
+    return None
+
+
+def read_header_line(stream):
+    # type: (PutBackIterator[bytes]) -> Text
+    """Read one CRLF-terminated part-header line as Latin-1 text.
+
+    The line's content is bounded by :data:`MAX_MULTIPART_HEADER_LINE` so a
+    malicious or corrupt body cannot force unbounded buffering.
+    """
+    line, terminated = read_crlf_line(stream, MAX_MULTIPART_HEADER_LINE)
+    if line is None or not terminated:
+        raise ValueError("multipart header line is not terminated or is too long")
+    return line[:-2].decode("latin-1")
+
+
+def parse_multipart_form_data(content_type, body_chunks):
+    # type: (Text, Iterable[bytes]) -> Iterator[MultipartEvent]
+    """Yield file lifecycle events from one explicit multipart state machine.
+
+    Events are :class:`PartBegin`, :class:`PartData`, and :class:`PartEnd`.
+    Non-file fields are consumed without events.
+    """
+    boundary_text = boundary_from_content_type(content_type)
+    if boundary_text is None:
+        raise ValueError("Invalid Content-Type for multipart/form-data")
+
+    stream = PutBackIterator(body_chunks)  # type: PutBackIterator[bytes]
+    boundary = b"--" + boundary_text.encode("utf-8")
+    next_boundary = boundary + b"\r\n"
+    final_boundary = boundary + b"--\r\n"
+    state = MultipartState.SEEK_OPENING_BOUNDARY
+    filename = None
+    held_chunk = b""
+
+    while state is not MultipartState.DONE:
+        if state is MultipartState.SEEK_OPENING_BOUNDARY:
+            # The opening delimiter is the first complete delimiter line; all
+            # preceding CRLF lines are the optional MIME preamble.
+            while True:
+                line, terminated = read_crlf_line(stream, MAX_MULTIPART_HEADER_LINE)
+                if line is None:
+                    raise ValueError("multipart body ended before its boundary")
+                if terminated and line == next_boundary:
+                    state = MultipartState.READ_HEADERS
+                    break
+                if terminated and line == final_boundary:
+                    state = MultipartState.DONE
+                    break
+                if not terminated:
+                    raise ValueError(
+                        "multipart body ended before its boundary or "
+                        "preamble line is too long"
+                    )
+
+        elif state is MultipartState.READ_HEADERS:
+            filename = None
+            while True:
+                header_line = read_header_line(stream)
+                if not header_line:
+                    if filename is not None:
+                        yield PartBegin(filename)
+                    held_chunk = b""
+                    state = MultipartState.MAYBE_BOUNDARY
+                    break
+                parsed_filename = filename_from_header_line(header_line)
+                if parsed_filename is not None:
+                    filename = parsed_filename
+
+        elif state is MultipartState.MAYBE_BOUNDARY:
+            delimiter, terminated = read_crlf_line(stream, len(final_boundary))
+            is_final = terminated and delimiter == final_boundary
+            if terminated and delimiter == next_boundary:
+                if len(held_chunk) > 2 and filename is not None:
+                    yield PartData(held_chunk[:-2])
+                held_chunk = b""
+                if filename is not None:
+                    yield PartEnd(False)
+                state = MultipartState.READ_HEADERS
+            elif is_final:
+                if len(held_chunk) > 2 and filename is not None:
+                    yield PartData(held_chunk[:-2])
+                held_chunk = b""
+                if filename is not None:
+                    yield PartEnd(True)
+                state = MultipartState.DONE
+            else:
+                # The candidate was not a delimiter, so the held complete
+                # line is ordinary body content, including its CRLF.
+                if held_chunk and filename is not None:
+                    yield PartData(held_chunk)
+                if terminated and delimiter:
+                    # Hold this complete non-delimiter line while checking the
+                    # bytes after its CRLF on the next MAYBE_BOUNDARY step.
+                    held_chunk = delimiter
+                    state = MultipartState.MAYBE_BOUNDARY
+                else:
+                    if delimiter and filename is not None:
+                        yield PartData(delimiter)
+                    held_chunk = b""
+                    state = MultipartState.READ_PART_BODY
+
+        elif state is MultipartState.READ_PART_BODY:
+            chunk, terminated = read_crlf_chunk(stream)
+            if chunk is None:
+                raise ValueError("multipart body ended before its boundary")
+            if terminated:
+                # Keep this complete line until MAYBE_BOUNDARY determines
+                # whether its trailing CRLF introduces a delimiter.
+                held_chunk = chunk
+                state = MultipartState.MAYBE_BOUNDARY
+            else:
+                if chunk and filename is not None:
+                    yield PartData(chunk)
+                state = MultipartState.READ_PART_BODY
+
+        else:
+            raise ValueError("invalid multipart parser state")

parse_multipart_form_data-0.1.0a0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "parse-multipart-form-data"
+version = "0.1.0a0"
+description = "A streaming parser for multipart/form-data request bodies."
+readme = "README.md"
+requires-python = ">=2"
+license = "MIT"
+authors = [
+  { name="Jifeng Wu", email="jifengwu2k@gmail.com" }
+]
+classifiers = [
+    "Programming Language :: Python :: 2",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "enum34; python_version < '3.4'",
+    "parse-http-header-line",
+    "put-back-iterator",
+    "typing; python_version < '3.5'",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/jifengwu2k/parse-multipart-form-data"
+"Bug Tracker" = "https://github.com/jifengwu2k/parse-multipart-form-data/issues"
+
+[tool.setuptools]
+py-modules = ["parse_multipart_form_data"]

parse_multipart_form_data-0.1.0a0/setup.cfg

@@ -0,0 +1,7 @@
+[bdist_wheel]
+universal = 1
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

parse_multipart_form_data-0.1.0a0/tests/test_parse_multipart_form_data.py

@@ -0,0 +1,435 @@
+# Copyright (c) 2026 Jifeng Wu
+# Licensed under the MIT License. See LICENSE in the project root.
+from __future__ import print_function
+
+import unittest
+from types import GeneratorType
+from typing import List, Optional, Text, Tuple
+
+from put_back_iterator import PutBackIterator
+
+from parse_multipart_form_data import (
+    PartBegin,
+    PartData,
+    PartEnd,
+    boundary_from_content_type,
+    filename_from_header_line,
+    parse_multipart_form_data,
+    read_crlf_chunk,
+    read_crlf_line,
+)
+
+
+def collect(data, chunk_size):
+    # type: (bytes, int) -> List[Tuple[Optional[bytes], bool]]
+    chunks = (
+        data[offset:offset + chunk_size]
+        for offset in range(0, len(data), chunk_size)
+    )
+    stream = PutBackIterator(chunks)
+    result = []
+    while True:
+        chunk, terminated = read_crlf_chunk(stream)
+        if chunk is None:
+            result.append((None, terminated))
+            return result
+        result.append((chunk, terminated))
+
+
+def event_summary(event):
+    # type: (object) -> Tuple[Text, object]
+    """Return a comparable ``(kind, value)`` shape for one multipart event."""
+    if isinstance(event, PartBegin):
+        return (u"begin", event.filename)
+    if isinstance(event, PartData):
+        return (u"data", event.data)
+    if isinstance(event, PartEnd):
+        return (u"end", event.is_final)
+    raise AssertionError(u"unexpected multipart event: %s" % (type(event).__name__,))
+
+
+class MultipartFormDataTests(unittest.TestCase):
+    def collect_events(self, body, chunk_size=None):
+        if chunk_size is None:
+            chunks = [body]
+        else:
+            chunks = (
+                body[offset:offset + chunk_size]
+                for offset in range(0, len(body), chunk_size)
+            )
+        return list(parse_multipart_form_data(
+            u"multipart/form-data; boundary=BOUNDARY", chunks
+        ))
+
+    def test_yields_file_lifecycle_events_from_chunk_iterable(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="hello.txt"\r\n',
+            b"\r\n",
+            b"hello world\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+
+        events = self.collect_events(body, 3)
+        self.assertIsInstance(events[0], PartBegin)
+        self.assertEqual(u"hello.txt", events[0].filename)
+        self.assertIsInstance(events[-1], PartEnd)
+        self.assertTrue(events[-1].is_final)
+        self.assertEqual(
+            b"hello world",
+            b"".join(event.data for event in events if isinstance(event, PartData)),
+        )
+
+    def test_skips_non_file_fields_and_emits_each_file(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="note"\r\n',
+            b"\r\n",
+            b"ignored\r\n",
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="a.txt"\r\n',
+            b"\r\n",
+            b"A\r\n",
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="b.txt"\r\n',
+            b"\r\n",
+            b"B\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+
+        self.assertEqual(
+            [
+                (u"begin", u"a.txt"),
+                (u"data", b"A"),
+                (u"end", False),
+                (u"begin", u"b.txt"),
+                (u"data", b"B"),
+                (u"end", True),
+            ],
+            [event_summary(event) for event in self.collect_events(body)],
+        )
+
+    def test_ignores_marker_in_middle_of_preamble(self):
+        body = b"".join((
+            b"preamble--BOUNDARY\r\n",
+            b"\r\n",
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="ok.txt"\r\n',
+            b"\r\n",
+            b"ok\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+
+        self.assertEqual(
+            [
+                (u"begin", u"ok.txt"),
+                (u"data", b"ok"),
+                (u"end", True),
+            ],
+            [event_summary(event) for event in self.collect_events(body)],
+        )
+
+    def test_emits_empty_file_part(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="empty.txt"\r\n',
+            b"\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+
+        self.assertEqual(
+            [(u"begin", u"empty.txt"), (u"end", True)],
+            [event_summary(event) for event in self.collect_events(body)],
+        )
+
+    def test_keeps_boundary_like_body_lines_as_content(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="body.txt"\r\n',
+            b"\r\n",
+            b"first\r\n",
+            b"--BOUNDARY-not-a-delimiter\r\n",
+            b"last\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+
+        events = self.collect_events(body)
+        self.assertIsInstance(events[0], PartBegin)
+        self.assertEqual(u"body.txt", events[0].filename)
+        self.assertIsInstance(events[-1], PartEnd)
+        self.assertTrue(events[-1].is_final)
+        self.assertEqual(
+            b"first\r\n--BOUNDARY-not-a-delimiter\r\nlast",
+            b"".join(event.data for event in events if isinstance(event, PartData)),
+        )
+
+    def test_rejects_transport_padding(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="one.txt"\r\n',
+            b"\r\n",
+            b"one\r\n",
+            b"--BOUNDARY-- \t\r\n",
+        ))
+
+        with self.assertRaises(ValueError):
+            self.collect_events(body)
+
+    def test_skips_non_form_data_content_disposition(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: attachment; name="file"; filename="not-upload.txt"\r\n',
+            b"\r\n",
+            b"ignored\r\n",
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; filename="missing-name.txt"\r\n',
+            b"\r\n",
+            b"ignored\r\n",
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="upload.txt"\r\n',
+            b"\r\n",
+            b"uploaded\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+
+        self.assertEqual(
+            [
+                (u"begin", u"upload.txt"),
+                (u"data", b"uploaded"),
+                (u"end", True),
+            ],
+            [event_summary(event) for event in self.collect_events(body)],
+        )
+
+    def test_parser_is_the_single_event_generator(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="state.txt"\r\n',
+            b"\r\n",
+            b"stateful\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+        events = parse_multipart_form_data(
+            u"multipart/form-data; boundary=BOUNDARY", [body]
+        )
+
+        self.assertTrue(isinstance(events, GeneratorType))
+        first = next(events)
+        self.assertIsInstance(first, PartBegin)
+        self.assertEqual(u"state.txt", first.filename)
+        second = next(events)
+        self.assertIsInstance(second, PartData)
+        self.assertEqual(b"stateful", second.data)
+        third = next(events)
+        self.assertIsInstance(third, PartEnd)
+        self.assertTrue(third.is_final)
+        with self.assertRaises(StopIteration):
+            next(events)
+
+    def test_rejects_invalid_content_type(self):
+        with self.assertRaises(ValueError):
+            list(parse_multipart_form_data(u"text/plain", [b"body"]))
+
+    def test_rejects_truncated_body(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="partial.txt"\r\n',
+            b"\r\n",
+            b"partial",
+        ))
+
+        with self.assertRaises(ValueError):
+            self.collect_events(body)
+
+    def test_boundary_from_content_type_accepts_rfc2046_boundary_chars(self):
+        self.assertEqual(
+            u"abc=def",
+            boundary_from_content_type(u"multipart/form-data; boundary=abc=def"),
+        )
+        self.assertEqual(
+            u"abc:def/ghi?jkl(1,2)",
+            boundary_from_content_type(
+                u"multipart/form-data; boundary=abc:def/ghi?jkl(1,2)"
+            ),
+        )
+        self.assertEqual(
+            u"abc=def",
+            boundary_from_content_type(u"multipart/form-data; boundary = \"abc=def\""),
+        )
+        self.assertEqual(
+            u"abc=def",
+            boundary_from_content_type(u"multipart/form-data; BOUNDARY=abc=def"),
+        )
+        self.assertEqual(
+            u"x=y",
+            boundary_from_content_type(
+                u"multipart/form-data; charset=utf-8; boundary=x=y"
+            ),
+        )
+
+    def test_parses_parts_with_equals_boundary(self):
+        body = b"".join((
+            b"--abc=def\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="ok.txt"\r\n',
+            b"\r\n",
+            b"data\r\n",
+            b"--abc=def--\r\n",
+        ))
+        events = list(parse_multipart_form_data(
+            u"multipart/form-data; boundary=abc=def", [body]
+        ))
+        self.assertIsInstance(events[0], PartBegin)
+        self.assertEqual(u"ok.txt", events[0].filename)
+        self.assertIsInstance(events[1], PartData)
+        self.assertEqual(b"data", events[1].data)
+        self.assertIsInstance(events[2], PartEnd)
+        self.assertTrue(events[2].is_final)
+
+    def test_filename_star_utf8_is_decoded(self):
+        header = (
+            u"Content-Disposition: form-data; name=\"file\"; "
+            u"filename*=UTF-8''caf%C3%A9.txt"
+        )
+        self.assertEqual(u"caf\u00e9.txt", filename_from_header_line(header))
+
+    def test_filename_star_iso8859_1_is_decoded(self):
+        header = (
+            u"Content-Disposition: form-data; name=\"file\"; "
+            u"filename*=ISO-8859-1''caf%E9.txt"
+        )
+        self.assertEqual(u"caf\u00e9.txt", filename_from_header_line(header))
+
+    def test_filename_star_takes_precedence_over_filename(self):
+        header = (
+            u"Content-Disposition: form-data; name=\"file\"; "
+            u"filename=\"fallback.txt\"; filename*=UTF-8''real%C3%A9.txt"
+        )
+        self.assertEqual(u"real\u00e9.txt", filename_from_header_line(header))
+
+    def test_filename_star_unknown_charset_falls_back_to_filename(self):
+        header = (
+            u"Content-Disposition: form-data; name=\"file\"; "
+            u"filename=\"fallback.txt\"; filename*=bogus''abc"
+        )
+        self.assertEqual(u"fallback.txt", filename_from_header_line(header))
+
+    def test_filename_star_malformed_is_ignored(self):
+        header = (
+            u"Content-Disposition: form-data; name=\"file\"; "
+            u"filename*=no-apostrophe"
+        )
+        self.assertIsNone(filename_from_header_line(header))
+
+    def test_emits_part_for_filename_star(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b"Content-Disposition: form-data; name=\"file\"; "
+            b"filename*=UTF-8''caf%C3%A9.txt\r\n",
+            b"\r\n",
+            b"data\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+        events = self.collect_events(body)
+        self.assertIsInstance(events[0], PartBegin)
+        self.assertEqual(u"caf\u00e9.txt", events[0].filename)
+
+    def test_rejects_overlong_header_line(self):
+        body = b"".join((
+            b"--BOUNDARY\r\n",
+            b"Content-Disposition: form-data; name=\"file\"; filename=\"x.txt\"; ",
+            b"x" * 9000,
+            b"\r\n",
+            b"\r\n",
+            b"data\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+        with self.assertRaises(ValueError):
+            self.collect_events(body)
+
+    def test_rejects_overlong_preamble_line(self):
+        body = b"".join((
+            b"preamble",
+            b"x" * 9000,
+            b"\r\n",
+            b"--BOUNDARY\r\n",
+            b'Content-Disposition: form-data; name="file"; filename="x.txt"\r\n',
+            b"\r\n",
+            b"data\r\n",
+            b"--BOUNDARY--\r\n",
+        ))
+        with self.assertRaises(ValueError):
+            self.collect_events(body)
+
+
+class ReadCrlfChunkTests(unittest.TestCase):
+    def test_returns_none_at_end_of_stream(self):
+        self.assertEqual([(None, False)], collect(b"", 1))
+
+    def test_splits_at_first_crlf_and_pushes_back_remainder(self):
+        self.assertEqual(
+            [(b"abc\r\n", True), (b"def\r\n", True), (None, False)],
+            collect(b"abc\r\ndef\r\n", 100),
+        )
+
+    def test_preserves_bytes_across_chunk_sizes(self):
+        data = b"a\rb\r\nc\r\n"
+        for chunk_size in (1, 2, 3, 5, 100):
+            result = collect(data, chunk_size)
+            joined = b"".join(chunk for chunk, _ in result if chunk is not None)
+            self.assertEqual(data, joined, "chunk size %s" % (chunk_size,))
+
+    def test_detects_crlf_split_across_chunks(self):
+        self.assertEqual(
+            [(b"ab\r\n", True), (b"cd", False), (None, False)],
+            collect(b"ab\r\ncd", 3),
+        )
+
+    def test_keeps_lone_cr_when_not_followed_by_lf(self):
+        self.assertEqual(
+            [(b"ab\r", False), (b"cd", False), (None, False)],
+            collect(b"ab\rcd", 3),
+        )
+
+    def test_limits_line_length_and_puts_back_remainder(self):
+        stream = PutBackIterator(iter([b"abc", b"def"]))
+
+        self.assertEqual((b"abcd", False), read_crlf_line(stream, 4))
+        self.assertEqual((b"ef", False), read_crlf_line(stream, 4))
+        self.assertEqual((None, False), read_crlf_line(stream, 4))
+
+    def test_line_limit_does_not_split_crlf(self):
+        stream = PutBackIterator(iter([b"abc\r\n"]))
+
+        self.assertEqual((b"abc", False), read_crlf_line(stream, 4))
+        self.assertEqual((b"\r\n", True), read_crlf_line(stream))
+
+    def test_reads_one_complete_line_across_input_chunks(self):
+        stream = PutBackIterator(iter([b"abc", b"\r", b"\ndef\r\n"]))
+
+        self.assertEqual((b"abc\r\n", True), read_crlf_line(stream))
+        self.assertEqual((b"def\r\n", True), read_crlf_line(stream))
+        self.assertEqual((None, False), read_crlf_line(stream))
+
+    def test_returns_partial_line_at_end_of_stream(self):
+        stream = PutBackIterator(iter([b"partial", b" line"]))
+
+        self.assertEqual((b"partial line", False), read_crlf_line(stream))
+        self.assertEqual((None, False), read_crlf_line(stream))
+
+    def test_skips_empty_chunks(self):
+        stream = PutBackIterator(iter([b"", b"", b"a\r\n", b"", b"b"]))
+        result = []
+        while True:
+            chunk, terminated = read_crlf_chunk(stream)
+            if chunk is None:
+                result.append((None, terminated))
+                break
+            result.append((chunk, terminated))
+        self.assertEqual(
+            [(b"a\r\n", True), (b"b", False), (None, False)],
+            result,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()