parse-multipart-form-data 0.1.0a0__py2.py3-none-any.whl

parse_multipart_form_data-0.1.0a0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+parse_multipart_form_data.py,sha256=7ahsPgdmTTewMd7TrPDXMBUj3IrPKDvULHZCOpQwv3g,13627
+parse_multipart_form_data-0.1.0a0.dist-info/licenses/LICENSE,sha256=hvfX-ADssuMYgrXDUAjMMut4l8W3meA31ZAYfpdlJKY,1066
+parse_multipart_form_data-0.1.0a0.dist-info/METADATA,sha256=X3m_2uPG6dMtM4aglmdgvPSElOp3JGPddXZxq1Pav3U,4303
+parse_multipart_form_data-0.1.0a0.dist-info/WHEEL,sha256=4YBfCYNH4wlLpv3pzq1hbEuIlXA4WJabKLFurZ7eTL0,109
+parse_multipart_form_data-0.1.0a0.dist-info/top_level.txt,sha256=ST9spZQ6x_5E_bOD1SjGsuSHFYd9w0mUrms0orcIYD4,26
+parse_multipart_form_data-0.1.0a0.dist-info/RECORD,,

parse_multipart_form_data-0.1.0a0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

parse_multipart_form_data-0.1.0a0.dist-info/licenses/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.dist-info/top_level.txt

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

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")