Native multipart in contrib (#288)

- Add contrib multipart

Author: tarsil

docs/en/docs/release-notes.md

@@ -19,6 +19,9 @@ hide:
 ### Changed
 
 - Added `python-multipart` as part of the `all` and `standard` Lilya packages.
+- Replaced `python-multipart` with a fully native multipart, urlencoded, and octet-stream form parser.
+- Improved RFC 5987 parameter decoding for proper handling of UTF-8 filenames and headers.
+
 
 ## 0.20.5
 

docs_src/routing/routes/routes_fall_through_sniff.py

@@ -12,7 +12,7 @@ async def user_state_update(request):
         raise ContinueRouting()
     try:
         jsonob = await request.json()
-    except Exception:
+    except Exception: # noqa
         raise ContinueRouting()
     if jsonob.get("type") != "update_state":
         raise ContinueRouting()

lilya/_internal/_parsers.py

@@ -11,21 +11,11 @@
 import anyio
 from anyio import SpooledTemporaryFile
 
+from lilya.contrib.multipart import parsers as multipart
+from lilya.contrib.multipart.utils import _decode_rfc5987, parse_options_header
 from lilya.datastructures import DataUpload, FormData, Header
 from lilya.enums import FormMessage
 
-try:
-    import python_multipart as multipart
-    from python_multipart.multipart import parse_options_header
-except ModuleNotFoundError:  # pragma: nocover
-    # old import name
-    try:
-        import multipart  # type: ignore[no-redef]
-        from multipart.multipart import parse_options_header  # type: ignore[no-redef]
-    except ModuleNotFoundError:  # pragma: nocover
-        parse_options_header = None
-        multipart = None
-
 
 @lru_cache(1024)
 def cookie_parser(cookie_string: str | bytes) -> dict[str, str]:
@@ -160,7 +150,17 @@ async def parse(self) -> FormData:
             "on_end": self.on_end,
         }
 
-        parser = multipart.QuerystringParser(callbacks)
+        parser = multipart.QuerystringParser()
+        if hasattr(parser, "set_callback"):
+            for cb_name, func in callbacks.items():
+                name = cb_name[3:] if cb_name.startswith("on_") else cb_name
+                try:
+                    parser.set_callback(name, func)
+                except Exception:  # noqa
+                    pass
+        elif hasattr(parser, "callbacks") and isinstance(parser.callbacks, dict):
+            parser.callbacks.update(callbacks)
+
         field_name = b""
         field_value = b""
         items: list[tuple[str, str | DataUpload]] = []
@@ -319,30 +319,31 @@ def on_headers_finished(self) -> None:
             self._handle_no_filename()
 
     def _set_field_name(self, options: dict[bytes, bytes]) -> None:
-        """
-        Set the field name based on options in Content-Disposition header.
-
-        Args:
-            options (Dict[bytes, bytes]): Parsed options from the Content-Disposition header.
-        """
-        try:
+        """Set the field name based on options; support RFC5987 name*."""
+        if b"name" in options:
             self._current_part.field_name = _user_safe_decode(options[b"name"], self._charset)
-        except KeyError:
-            raise MultiPartException(
-                'The Content-Disposition header field "name" must be provided.'
-            ) from None
+            return
+        # RFC5987 name*
+        raw = options.get(b"name*")
+        if raw is not None:
+            decoded = _decode_rfc5987(raw, self._charset)
+            self._current_part.field_name = decoded
+            return
+        raise MultiPartException(
+            'The Content-Disposition header field "name" must be provided.'
+        ) from None
 
     def _handle_filename(self, options: dict[bytes, bytes]) -> None:
-        """
-        Handle the case when the part has a filename.
-
-        Args:
-            options (Dict[bytes, bytes]): Parsed options from the Content-Disposition header.
-        """
+        """Handle the case when the part has a filename. Support RFC5987 filename*."""
         self._current_files += 1
         self._validate_files_count()
 
-        filename = _user_safe_decode(options[b"filename"], self._charset)
+        filename = ""
+        if b"filename" in options:
+            filename = _user_safe_decode(options[b"filename"], self._charset)
+        elif b"filename*" in options:
+            filename = _decode_rfc5987(options[b"filename*"], self._charset)
+
         tempfile = self._create_temp_file()
         self._current_part.file = self._create_upload_file(filename, tempfile)
 
@@ -483,15 +484,26 @@ def _create_multipart_parser(
     ) -> multipart.MultipartParser:
         """
         Create the multipart parser with the specified boundary and callbacks.
-
-        Args:
-            boundary (bytes): Multipart boundary.
-            callbacks (Dict[str, Callable]): Callbacks dictionary.
-
-        Returns:
-            multipart.MultipartParser: Created multipart parser.
-        """
-        return multipart.MultipartParser(boundary, cast(Any, callbacks))
+        Works with lilya.contrib.multipart (preferred).
+        """
+        # Our contrib parser signature is MultipartParser(boundary, *[, max_size=...])
+        mp = multipart.MultipartParser(boundary)
+        # If it exposes set_callback(name, func) use that, stripping 'on_'
+        if hasattr(mp, "set_callback"):
+            for cb_name, func in callbacks.items():
+                name = cb_name[3:] if cb_name.startswith("on_") else cb_name
+                try:
+                    mp.set_callback(name, func)
+                except Exception:  # noqa
+                    pass
+        # Or store into callbacks dict if present
+        if hasattr(mp, "callbacks") and isinstance(mp.callbacks, dict):
+            for cb_name, func in callbacks.items():
+                try:
+                    mp.callbacks[cb_name] = func
+                except Exception:  # noqa
+                    pass
+        return mp
 
     async def _write_file_data(self) -> None:
         """

lilya/_internal/_responses.py

@@ -390,7 +390,7 @@ def _structure_to_annotation(self, annotation: Any, value: Any) -> Any:
             for a in non_none:
                 try:
                     return self._structure_to_annotation(a, value)
-                except Exception:
+                except Exception:  # noqa
                     continue
             return value  # fallback
 
@@ -430,8 +430,8 @@ def _structure_to_annotation(self, annotation: Any, value: Any) -> Any:
             # Best-effort fast path when annotation is a runtime class/type
             if isinstance(annotation, type) and isinstance(value, annotation):
                 return value
-        except Exception:
-            pass
+        except Exception:  # noqa
+            ...
 
         return apply_structure(structure=annotation, value=value)
 

lilya/conf/global_settings.py

@@ -41,7 +41,7 @@ def safe_get_type_hints(cls: type) -> dict[str, Any]:
     """
     try:
         return get_type_hints(cls, include_extras=True)
-    except Exception:
+    except Exception:  # noqa
         return cls.__annotations__
 
 
@@ -124,7 +124,7 @@ def _cast(self, value: str, typ: type[Any]) -> Any:
             if typ is bool or str(typ) == "bool":
                 return value.lower() in self.__truthy__
             return typ(value)
-        except Exception:
+        except Exception:  # noqa
             if get_origin(typ) is Union or get_origin(UnionType):
                 type_name = " | ".join(
                     t.__name__ if hasattr(t, "__name__") else str(t) for t in get_args(typ)
@@ -171,7 +171,7 @@ def dict(
                         continue
                     result_key = name.upper() if upper else name
                     result[result_key] = value
-                except Exception:
+                except Exception:  # noqa
                     # Skip properties that raise errors
                     continue
 

lilya/contrib/mail/backends/smtp.py

@@ -162,7 +162,7 @@ def _quit(client: smtplib.SMTP) -> None:
                 finally:
                     try:
                         client.close()
-                    except Exception:
+                    except Exception:  # noqa
                         ...
 
             await anyio.to_thread.run_sync(_quit, self._client)

lilya/contrib/multipart/__init__.py

@@ -0,0 +1,42 @@
+from .exceptions import (
+    DecodeError,
+    FileError,
+    FormParserError,
+    MultipartParseError,
+    ParseError,
+    QuerystringParseError,
+)
+from .form import (
+    Field,
+    File,
+    FormParser,
+    create_form_parser,
+    parse_form,
+)
+from .parsers import (
+    BaseParser,
+    MultipartParser,
+    OctetStreamParser,
+    QuerystringParser,
+)
+
+__all__ = [
+    # exceptions
+    "ParseError",
+    "DecodeError",
+    "FileError",
+    "FormParserError",
+    "MultipartParseError",
+    "QuerystringParseError",
+    # parsers
+    "BaseParser",
+    "MultipartParser",
+    "QuerystringParser",
+    "OctetStreamParser",
+    # form helpers
+    "File",
+    "Field",
+    "FormParser",
+    "create_form_parser",
+    "parse_form",
+]

lilya/contrib/multipart/exceptions.py

@@ -0,0 +1,72 @@
+class ParseError(Exception):
+    """
+    Base class for all parsing-related errors in Lilya’s multipart/querystring
+    handling system.
+
+    This should not be raised directly; instead, raise one of the more specific
+    subclasses depending on the context (decoding, multipart, querystring, etc.).
+    """
+
+    ...
+
+
+class DecodeError(ParseError):
+    """
+    Raised when a header, parameter, or field value cannot be decoded properly.
+
+    Typical causes:
+    - Invalid character encoding in a multipart header (e.g. malformed UTF-8).
+    - Unsupported or malformed Content-Transfer-Encoding.
+    """
+
+    ...
+
+
+class FileError(ParseError):
+    """
+    Raised when an error occurs while handling uploaded file data.
+
+    Examples:
+    - Failure to create or write to a temporary file.
+    - Exceeding file size limits while streaming data.
+    """
+
+    ...
+
+
+class FormParserError(ParseError):
+    """
+    Raised when the high-level FormParser cannot be created or executed.
+
+    Examples:
+    - Invalid or missing Content-Type headers.
+    - Unsupported form encoding (not multipart, urlencoded, or octet-stream).
+    """
+
+    ...
+
+
+class MultipartParseError(ParseError):
+    """
+    Raised when a multipart/form-data body cannot be parsed successfully.
+
+    Examples:
+    - Missing or invalid boundary parameter.
+    - Truncated or malformed multipart segments.
+    - Exceeding the maximum allowed number of parts or fields.
+    """
+
+    ...
+
+
+class QuerystringParseError(ParseError):
+    """
+    Raised when a query string or `application/x-www-form-urlencoded`
+    body cannot be parsed successfully.
+
+    Examples:
+    - Invalid percent-encoding in keys or values.
+    - Malformed key/value pairs (missing '=' separator).
+    """
+
+    ...