feat(request): add delimiter support to get_param_as_list

docs/_newsfragments/2538.newandimproved.rst

@@ -0,0 +1 @@
+req.get_param_as_list() now supports a delimiter argument for splitting values.

falcon/request.py

@@ -1943,6 +1943,7 @@ def get_param_as_list(
         *,
         required: Literal[True],
         store: StoreArg = ...,
+        delimiter: str | None = None,
         default: list[str] | None = ...,
     ) -> list[str]: ...
 
@@ -1953,6 +1954,7 @@ def get_param_as_list(
         transform: Callable[[str], _T],
         required: Literal[True],
         store: StoreArg = ...,
+        delimiter: str | None = None,
         default: list[_T] | None = ...,
     ) -> list[_T]: ...
 
@@ -1963,6 +1965,7 @@ def get_param_as_list(
         transform: None = ...,
         required: bool = ...,
         store: StoreArg = ...,
+        delimiter: str | None = None,
         *,
         default: list[str],
     ) -> list[str]: ...
@@ -1974,6 +1977,7 @@ def get_param_as_list(
         transform: Callable[[str], _T],
         required: bool = ...,
         store: StoreArg = ...,
+        delimiter: str | None = None,
         *,
         default: list[_T],
     ) -> list[_T]: ...
@@ -1985,6 +1989,7 @@ def get_param_as_list(
         transform: None = ...,
         required: bool = ...,
         store: StoreArg = ...,
+        delimiter: str | None = None,
         default: list[str] | None = ...,
     ) -> list[str] | None: ...
 
@@ -1995,6 +2000,7 @@ def get_param_as_list(
         transform: Callable[[str], _T],
         required: bool = ...,
         store: StoreArg = ...,
+        delimiter: str | None = None,
         default: list[_T] | None = ...,
     ) -> list[_T] | None: ...
 
@@ -2004,6 +2010,7 @@ def get_param_as_list(
         transform: Callable[[str], _T] | None = None,
         required: bool = False,
         store: StoreArg = None,
+        delimiter: str | None = None,
         default: list[_T] | None = None,
     ) -> list[_T] | list[str] | None:
         """Return the value of a query string parameter as a list.
@@ -2021,6 +2028,10 @@ def get_param_as_list(
             name (str): Parameter name, case-sensitive (e.g., 'ids').
 
         Keyword Args:
+            delimiter(str): An optional character for splitting a parameter
+                value into a list. Useful for styles like ``spaceDelimited``
+                or ``pipeDelimited``. If not provided, default list parsing
+                applies.
             transform (callable): An optional transform function
                 that takes as input each element in the list as a ``str`` and
                 outputs a transformed element for inclusion in the list that
@@ -2066,6 +2077,16 @@ def get_param_as_list(
         if name in params:
             items = params[name]
 
+            # If a delimiter is specified AND the param is a single string, split it.
+            if delimiter and isinstance(items, str):
+                if delimiter == ' ':
+                    items = items.split(' ')
+                elif delimiter == '|':
+                    items = items.split('|')
+                else:
+                    # For commas and others, also strip whitespace for convenience.
+                    items = [v.strip() for v in items.split(delimiter)]
+
             # NOTE(warsaw): When a key appears multiple times in the request
             # query, it will already be represented internally as a list.
             # NOTE(kgriffs): Likewise for comma-delimited values.

tests/test_request_attrs.py

@@ -1012,6 +1012,35 @@ def test_etag_parsing_helper(self, asgi, header_value):
 
         assert _parse_etags(header_value) is None
 
+    @pytest.mark.parametrize('asgi', [False, True])
+    def test_get_param_as_list_space_delimited(self, asgi):
+        req = create_req(asgi, query_string='names=Luke%20Leia%20Han')
+        result = req.get_param_as_list('names', delimiter=' ')
+        assert result == ['Luke', 'Leia', 'Han']
+
+    @pytest.mark.parametrize('asgi', [False, True])
+    def test_get_param_as_list_pipe_delimited(self, asgi):
+        req = create_req(asgi, query_string='names=Luke|Leia|Han')
+        result = req.get_param_as_list('names', delimiter='|')
+        assert result == ['Luke', 'Leia', 'Han']
+
+    @pytest.mark.parametrize('asgi', [False, True])
+    def test_get_param_as_list_custom_delimiter(self, asgi):
+        req = create_req(asgi, query_string='names=Luke;Leia;Han')
+        result = req.get_param_as_list('names', delimiter=';')
+        assert result == ['Luke', 'Leia', 'Han']
+
+    @pytest.mark.parametrize('asgi', [False, True])
+    def test_get_param_as_list_no_delimiter_still_defaults_to_comma(self, asgi):
+        options = falcon.RequestOptions()
+        options.auto_parse_qs_csv = True
+
+        req = create_req(asgi, query_string='names=Luke,Leia,Han', options=options)
+
+        result = req.get_param_as_list('names', delimiter=None)
+
+        assert result == ['Luke', 'Leia', 'Han']
+
     # -------------------------------------------------------------------------
     # Helpers
     # -------------------------------------------------------------------------