fix(multipart): don't share MultipartParseOptions._DEFAULT_HANDLERS (#2322)

* fix(multipart): don't share MultipartParseOptions._DEFAULT_HANDLERS between instances

* fix(media): implement a proper `Handlers.copy()` method

* chore: add a versionadded docs directive

* docs(newsfragments): add a newsfragment for #2293

---------

Co-authored-by: Vytautas Liuolia <vytautas.liuolia@gmail.com>

Author: myusko

docs/_newsfragments/2293.bugfix.rst

@@ -0,0 +1,10 @@
+Customizing
+:attr:`MultipartParseOptions.media_handlers
+<falcon.media.multipart.MultipartParseOptions.media_handlers>` could previously
+lead to unintentionally modifying a shared class variable.
+This has been fixed, and the
+:attr:`~falcon.media.multipart.MultipartParseOptions.media_handlers` attribute
+is now initialized to a fresh copy of handlers for every instance of
+:class:`~falcon.media.multipart.MultipartParseOptions`. To that end, a proper
+:meth:`~falcon.media.Handlers.copy` method has been implemented for the media
+:class:`~falcon.media.Handlers` class.

falcon/media/handlers.py

@@ -164,6 +164,22 @@ def resolve(
 
         return cast(ResolverMethod, resolve)
 
+    def copy(self) -> Handlers:
+        """Create a shallow copy of this instance of handlers.
+
+        The resulting copy contains the same keys and values, but it can be
+        customized separately without affecting the original object.
+
+        Returns:
+            A shallow copy of handlers.
+
+        .. versionadded:: 4.0
+        """
+        # NOTE(vytas): In the unlikely case we are dealing with a subclass,
+        #   return the matching type.
+        handlers_cls = type(self)
+        return handlers_cls(self.data)
+
     @deprecation.deprecated(
         'This undocumented method is no longer supported as part of the public '
         'interface and will be removed in a future release.'

falcon/media/multipart.py

@@ -610,4 +610,7 @@ def __init__(self) -> None:
         self.max_body_part_buffer_size = 1024 * 1024
         self.max_body_part_count = 64
         self.max_body_part_headers_size = 8192
-        self.media_handlers = self._DEFAULT_HANDLERS
+        # NOTE(myusko,vytas): Here we create a copy of _DEFAULT_HANDLERS in
+        #   order to prevent the modification of the class variable whenever
+        #   parse_options.media_handlers are customized.
+        self.media_handlers = self._DEFAULT_HANDLERS.copy()

tests/test_media_multipart.py

@@ -8,6 +8,7 @@
 import falcon
 from falcon import media
 from falcon import testing
+from falcon.media.multipart import MultipartParseOptions
 from falcon.util import BufferedReader
 
 try:
@@ -849,3 +850,14 @@ async def deserialize_async(self, stream, content_type, content_length):
 
     assert resp.status_code == 200
     assert resp.json == ['', '0x48']
+
+
+def test_multipart_parse_options_default_handlers_unique():
+    parse_options_one = MultipartParseOptions()
+    parse_options_two = MultipartParseOptions()
+
+    parse_options_one.media_handlers.pop(falcon.MEDIA_JSON)
+
+    assert parse_options_one.media_handlers is not parse_options_two.media_handlers
+    assert len(parse_options_one.media_handlers) == 1
+    assert len(parse_options_two.media_handlers) >= 2