qs-codec 1.5.0__tar.gz → 1.5.2__tar.gz

{qs_codec-1.5.0 → qs_codec-1.5.2}/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 1.5.2
+
+* [CHORE] simplify mapping and key-iteration checks in encode/decode internals
+* [CHORE] improve readability in `EncodeOptions`, `Utils`, `DecodeUtils`, and `EncodeUtils` helper code
+* [CHORE] expand internal type annotations across encode, decode, utils, and weak-wrapper helpers
+
+## 1.5.1
+
+* [FEAT] add `DecodeOptions.strict_merge` for Node `qs` 6.15 `strictMerge` parity
+* [FIX] align `decode` `list_limit` semantics with Node `qs` `arrayLimit` as a maximum element count
+* [FIX] combine bracket-array duplicate assignments regardless of `DecodeOptions.duplicates`
+* [FIX] align `decode` with Node `qs` 6.15.2 by normalizing dotted keys before preserving `depth=0` input
+* [FIX] align `encode` with Node `qs` 6.15.2 by using the configured delimiter after `charset_sentinel`
+
 ## 1.5.0
 
 * [FEAT] add the `Programming Language :: Python :: Free Threading :: 3 - Stable` classifier

{qs_codec-1.5.0 → qs_codec-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qs-codec
-Version: 1.5.0
+Version: 1.5.2
 Summary: A query string encoding and decoding library for Python. Ported from qs for JavaScript.
 Project-URL: Homepage, https://techouse.github.io/qs_codec/
 Project-URL: Documentation, https://techouse.github.io/qs_codec/
@@ -1097,6 +1097,8 @@ Other ports
 +----------------------------+---------------------------------------------------------------+-----------------+
 | .NET / C#                  | `techouse/qs-net <https://github.com/techouse/qs-net>`__      | |nuget|         |
 +----------------------------+---------------------------------------------------------------+-----------------+
+| Rust                       | `techouse/qs_rust <https://github.com/techouse/qs_rust>`__    | |crates.io|     |
++----------------------------+---------------------------------------------------------------+-----------------+
 | Node.js (original)         | `ljharb/qs <https://github.com/ljharb/qs>`__                  | |npm|           |
 +----------------------------+---------------------------------------------------------------+-----------------+
 
@@ -1188,6 +1190,9 @@ Holowaychuk <https://github.com/visionmedia/node-querystring>`__
 .. |nuget| image:: https://img.shields.io/nuget/v/QsNet?logo=dotnet&label=NuGet
    :target: https://www.nuget.org/packages/QsNet
    :alt: NuGet version
+.. |crates.io| image:: https://img.shields.io/crates/v/qs_rust?logo=rust&label=crates.io
+   :target: https://crates.io/crates/qs_rust
+   :alt: crates.io version
 .. |npm| image:: https://img.shields.io/npm/v/qs?logo=javascript&label=npm
    :target: https://www.npmjs.com/package/qs
    :alt: npm version

{qs_codec-1.5.0 → qs_codec-1.5.2}/README.rst

@@ -1034,6 +1034,8 @@ Other ports
 +----------------------------+---------------------------------------------------------------+-----------------+
 | .NET / C#                  | `techouse/qs-net <https://github.com/techouse/qs-net>`__      | |nuget|         |
 +----------------------------+---------------------------------------------------------------+-----------------+
+| Rust                       | `techouse/qs_rust <https://github.com/techouse/qs_rust>`__    | |crates.io|     |
++----------------------------+---------------------------------------------------------------+-----------------+
 | Node.js (original)         | `ljharb/qs <https://github.com/ljharb/qs>`__                  | |npm|           |
 +----------------------------+---------------------------------------------------------------+-----------------+
 
@@ -1125,6 +1127,9 @@ Holowaychuk <https://github.com/visionmedia/node-querystring>`__
 .. |nuget| image:: https://img.shields.io/nuget/v/QsNet?logo=dotnet&label=NuGet
    :target: https://www.nuget.org/packages/QsNet
    :alt: NuGet version
+.. |crates.io| image:: https://img.shields.io/crates/v/qs_rust?logo=rust&label=crates.io
+   :target: https://crates.io/crates/qs_rust
+   :alt: crates.io version
 .. |npm| image:: https://img.shields.io/npm/v/qs?logo=javascript&label=npm
    :target: https://www.npmjs.com/package/qs
    :alt: npm version

{qs_codec-1.5.0 → qs_codec-1.5.2}/docs/README.rst

@@ -196,6 +196,38 @@ change the behavior when duplicate keys are encountered
        qs.DecodeOptions(duplicates=qs.Duplicates.LAST),
    ) == {'foo': 'baz'}
 
+Bracket-array keys always combine, regardless of the duplicate strategy:
+
+.. code:: python
+
+   import qs_codec as qs
+
+   assert qs.decode(
+       'a=1&a=2&b[]=1&b[]=2',
+       qs.DecodeOptions(duplicates=qs.Duplicates.LAST),
+   ) == {'a': '2', 'b': ['1', '2']}
+
+When a key appears as both an object and a scalar,
+:py:attr:`strict_merge <qs_codec.models.decode_options.DecodeOptions.strict_merge>` wraps the conflicting values in a
+``list`` by default:
+
+.. code:: python
+
+   import qs_codec as qs
+
+   assert qs.decode('a[b]=c&a=d') == {'a': [{'b': 'c'}, 'd']}
+
+Set ``strict_merge`` to ``False`` to restore the legacy behavior, where non-empty string scalars become object keys:
+
+.. code:: python
+
+   import qs_codec as qs
+
+   assert qs.decode(
+       'a[b]=c&a=d',
+       qs.DecodeOptions(strict_merge=False),
+   ) == {'a': {'b': 'c', 'd': True}}
+
 If you have to deal with legacy browsers or services, there’s also
 support for decoding percent-encoded octets as :py:attr:`LATIN1 <qs_codec.enums.charset.Charset.LATIN1>`:
 
@@ -310,11 +342,11 @@ Note that an empty ``str``\ing is also a value and will be preserved:
    assert qs.decode('a[0]=b&a[1]=&a[2]=c') == {'a': ['b', '', 'c']}
 
 :py:attr:`decode <qs_codec.decode>` will also limit specifying indices
-in a ``list`` to a maximum index of ``20``. Any ``list`` members with an
-index of greater than ``20`` will instead be converted to a ``dict`` with
-the index as the key. This is needed to handle cases when someone sent,
-for example, ``a[999999999]`` and it will take significant time to iterate
-over this huge ``list``.
+in a ``list`` to a maximum element count of ``20``. Index ``19`` is the
+last index that can create a default ``list``; index ``20`` and higher
+are converted to a ``dict`` with the index as the key. This is needed to
+handle cases when someone sent, for example, ``a[999999999]`` and it
+would take significant time to iterate over this huge ``list``.
 
 .. code:: python
 

{qs_codec-1.5.0 → qs_codec-1.5.2}/src/qs_codec/__init__.py

@@ -14,7 +14,7 @@ The package root re-exports the most commonly used functions and enums so you ca
 """
 
 # Package version (PEP 440). Bump in lockstep with distribution metadata.
-__version__ = "1.5.0"
+__version__ = "1.5.2"
 
 # Public API surface re-exported at the package root.
 __all__ = [

{qs_codec-1.5.0 → qs_codec-1.5.2}/src/qs_codec/decode.py

@@ -24,13 +24,17 @@ from .enums.decode_kind import DecodeKind
 from .enums.duplicates import Duplicates
 from .enums.sentinel import Sentinel
 from .models.decode_options import DecodeOptions
-from .models.overflow_dict import OverflowDict
+from .models.overflow_dict import CommaOverflowDict, OverflowDict
 from .models.structured_key_scan import StructuredKeyScan
 from .models.undefined import UNDEFINED
 from .utils.decode_utils import DecodeUtils
 from .utils.utils import Utils
 
 
+def _list_limit_exceeded_message(limit: int) -> str:
+    return f"List limit exceeded: Only {limit} element{'' if limit == 1 else 's'} allowed in a list."
+
+
 def decode(
     value: t.Optional[t.Union[str, Mapping[str, t.Any]]],
     options: t.Optional[DecodeOptions] = None,
@@ -69,12 +73,12 @@ def decode(
     if not isinstance(value, (str, Mapping)):
         raise ValueError("value must be a str or a Mapping[str, Any]")
 
-    opts = options if options is not None else DecodeOptions()
-    decode_from_string = isinstance(value, str)
+    opts: DecodeOptions = options if options is not None else DecodeOptions()
+    decode_from_string: bool = isinstance(value, str)
     str_value: str = t.cast(str, value) if decode_from_string else ""
     mapping_value: t.Mapping[str, t.Any] = t.cast(t.Mapping[str, t.Any], value) if not decode_from_string else {}
 
-    parse_lists_effective = opts.parse_lists
+    parse_lists_effective: bool = opts.parse_lists
     if decode_from_string and parse_lists_effective:
         # Keep caller options immutable: compute a local parse_lists switch only for this invocation.
         query = str_value.replace("?", "", 1) if opts.ignore_query_prefix else str_value
@@ -86,15 +90,15 @@ def decode(
             parse_lists_effective = False
 
     if decode_from_string:
-        temp_obj: t.Optional[t.Dict[str, t.Any]] = _parse_query_string_values(
-            str_value, opts, parse_lists=parse_lists_effective
-        )
+        temp_obj: t.Optional[t.Dict[str, t.Any]] = _parse_query_string_values(str_value, opts)
     else:
         temp_obj = dict(mapping_value)
     if not temp_obj:
         return obj
 
-    structured_scan = _scan_structured_keys(temp_obj, opts) if decode_from_string else StructuredKeyScan.empty()
+    structured_scan: StructuredKeyScan = (
+        _scan_structured_keys(temp_obj, opts) if decode_from_string else StructuredKeyScan.empty()
+    )
     if decode_from_string and not structured_scan.has_any_structured_syntax:
         return Utils.compact(temp_obj)
 
@@ -140,18 +144,18 @@ def loads(value: t.Optional[str], options: t.Optional[DecodeOptions] = None) ->
 
 def _first_structured_split_index(key: str, allow_dots: bool) -> int:
     """Return the earliest index that indicates structured syntax in ``key``."""
-    split_at = key.find("[")
+    split_at: int = key.find("[")
     if not allow_dots:
         return split_at
 
-    dot_index = key.find(".")
+    dot_index: int = key.find(".")
     if dot_index >= 0 and (split_at < 0 or dot_index < split_at):
         split_at = dot_index
 
-    encoded_dot_index = -1
+    encoded_dot_index: int = -1
     if "%" in key:
-        upper = key.find("%2E")
-        lower = key.find("%2e")
+        upper: int = key.find("%2E")
+        lower: int = key.find("%2e")
         if upper >= 0 and lower >= 0:
             encoded_dot_index = upper if upper < lower else lower
         else:
@@ -165,7 +169,7 @@ def _first_structured_split_index(key: str, allow_dots: bool) -> int:
 
 def _leading_structured_root(key: str, options: DecodeOptions) -> str:
     """Extract root key for leading-bracket structured keys (``[]`` normalizes to ``"0"``)."""
-    segments = DecodeUtils.split_key_into_segments(
+    segments: t.List[str] = DecodeUtils.split_key_into_segments(
         original_key=key,
         allow_dots=t.cast(bool, options.allow_dots),
         max_depth=options.depth,
@@ -188,12 +192,12 @@ def _scan_structured_keys(temp_obj: Mapping[str, t.Any], options: DecodeOptions)
     if not temp_obj:
         return StructuredKeyScan.empty()
 
-    allow_dots = t.cast(bool, options.allow_dots)
+    allow_dots: bool = t.cast(bool, options.allow_dots)
     structured_roots: t.Set[str] = set()
     structured_keys: t.Set[str] = set()
 
-    for key in temp_obj.keys():
-        split_at = _first_structured_split_index(key, allow_dots)
+    for key in temp_obj:
+        split_at: int = _first_structured_split_index(key, allow_dots)
         if split_at < 0:
             continue
         structured_keys.add(key)
@@ -221,20 +225,27 @@ def _interpret_numeric_entities(value: str) -> str:
     return re.sub(r"&#(\d+);", lambda match: chr(int(match.group(1))), value)
 
 
-def _parse_array_value(value: t.Any, options: DecodeOptions, current_list_length: int) -> t.Any:
+def _parse_array_value(
+    value: t.Any,
+    options: DecodeOptions,
+    current_list_length: int,
+    *,
+    enforce_comma_limit: bool = True,
+) -> t.Any:
     """Post-process a raw scalar for list semantics and enforce ``list_limit``.
 
     Behavior
     --------
     - If ``comma=True`` and ``value`` is a string that contains commas, split into a list.
+      When ``enforce_comma_limit`` is ``True``, over-limit comma values raise or degrade to an ``OverflowDict`` here.
+      Raw query-string parsing and mapping key paths ending in ``[]`` pass ``False`` so the caller can account for
+      bracket-array key context first.
     - Otherwise, enforce the per-list length limit by comparing ``current_list_length`` to ``options.list_limit``.
       When ``raise_on_limit_exceeded=True``, violations raise ``ValueError``.
-    - When ``list_limit`` is negative:
-        * if ``raise_on_limit_exceeded=True``, **any** list-growth operation here (e.g., comma-splitting)
-          raises immediately;
-        * if ``raise_on_limit_exceeded=False`` (default), comma-splitting still returns a list; numeric
-          bracket indices are handled later by ``_parse_object`` (where negative ``list_limit`` disables
-          numeric-index parsing only).
+    - When ``list_limit`` is negative, any non-empty comma split exceeds the limit: raising mode raises,
+      while non-raising mode degrades to an ``OverflowDict``/``CommaOverflowDict``. Raw query-string
+      parsing temporarily returns the split list when ``enforce_comma_limit=False`` so the caller can
+      apply bracket-array wrapping before the final limit check.
 
     Returns
     -------
@@ -243,23 +254,19 @@ def _parse_array_value(value: t.Any, options: DecodeOptions, current_list_length
     """
     if isinstance(value, str) and value and options.comma and "," in value:
         split_val: t.List[str] = value.split(",")
-        if options.raise_on_limit_exceeded and len(split_val) > options.list_limit:
-            raise ValueError(
-                f"List limit exceeded: Only {options.list_limit} element{'' if options.list_limit == 1 else 's'} allowed in a list."
-            )
+        if enforce_comma_limit and len(split_val) > options.list_limit:
+            if options.raise_on_limit_exceeded:
+                raise ValueError(_list_limit_exceeded_message(options.list_limit))
+            return CommaOverflowDict({str(i): item for i, item in enumerate(split_val)})
         return split_val
 
     if options.raise_on_limit_exceeded and current_list_length >= options.list_limit:
-        raise ValueError(
-            f"List limit exceeded: Only {options.list_limit} element{'' if options.list_limit == 1 else 's'} allowed in a list."
-        )
+        raise ValueError(_list_limit_exceeded_message(options.list_limit))
 
     return value
 
 
-def _parse_query_string_values(
-    value: str, options: DecodeOptions, *, parse_lists: t.Optional[bool] = None
-) -> t.Dict[str, t.Any]:
+def _parse_query_string_values(value: str, options: DecodeOptions) -> t.Dict[str, t.Any]:
     """Tokenize a raw query string into a flat ``Dict[str, Any]``.
 
     Responsibilities
@@ -273,7 +280,7 @@ def _parse_query_string_values(
         * Decode key/value via ``options.decoder`` (default: percent-decoding using the selected ``charset``).
           Keys are passed with ``kind=DecodeKind.KEY`` and values with ``kind=DecodeKind.VALUE``; a custom decoder
           may return the raw token or ``None``.
-        * Apply comma-split list logic to values (handled here). Index-based list growth from bracket segments is applied later in ``_parse_object``. When ``list_limit < 0`` and ``raise_on_limit_exceeded=True``, any comma-split that would increase the list length raises immediately; otherwise the split proceeds.
+        * Apply comma-split list logic to values (handled here). Index-based list growth from bracket segments is applied later in ``_parse_object``. When ``list_limit < 0``, comma-split values always exceed the limit: they raise under ``raise_on_limit_exceeded=True`` and degrade to overflow dictionaries otherwise.
         * Interpret numeric entities for Latin-1 when requested.
         * Handle empty brackets ``[]`` as list markers (wrapping exactly once).
         * Merge duplicate keys according to ``duplicates`` policy.
@@ -282,7 +289,6 @@ def _parse_query_string_values(
     ``_parse_keys`` / ``_parse_object``.
     """
     obj: t.Dict[str, t.Any] = {}
-    parse_lists_enabled = options.parse_lists if parse_lists is None else parse_lists
 
     clean_str: str = value.replace("?", "", 1) if options.ignore_query_prefix else value
     # Normalize %5B/%5D to literal brackets before splitting (case-insensitive).
@@ -342,21 +348,22 @@ def _parse_query_string_values(
 
     # Local, non-optional decoder reference for type-checkers
     decoder_fn: t.Callable[..., t.Optional[str]] = options.decoder or DecodeUtils.decode
-    duplicates = options.duplicates
+    duplicates: Duplicates = options.duplicates
 
     # Iterate over parts and decode each key/value pair.
-    for i, _ in enumerate(parts):
+    for i, part in enumerate(parts):
         if i == skip_index:
             continue
 
-        part: str = parts[i]
         if not part:
             continue
         bracket_equals_pos: int = part.find("]=")
         pos: int = part.find("=") if bracket_equals_pos == -1 else (bracket_equals_pos + 1)
+        bracket_array_assignment: bool = pos != -1 and "[]=" in part
 
         # Decode key and value with a key-aware decoder; skip pairs whose key decodes to None
-        raw_key = ""
+        raw_key: str = ""
+        list_limit_exceeded: bool = False
         if pos == -1:
             key_decoded = decoder_fn(part, charset, kind=DecodeKind.KEY)
             if key_decoded is None:
@@ -377,7 +384,9 @@ def _parse_query_string_values(
                 part[pos + 1 :],
                 options,
                 len(obj[key]) if key in obj and isinstance(obj[key], (list, tuple)) else 0,
+                enforce_comma_limit=False,
             )
+            list_limit_exceeded = isinstance(parsed_value, (list, tuple)) and len(parsed_value) > options.list_limit
             if isinstance(parsed_value, (list, tuple)):
                 val = [decoder_fn(v, charset, kind=DecodeKind.VALUE) for v in parsed_value]
             else:
@@ -390,15 +399,21 @@ def _parse_query_string_values(
 
         # Upstream parity: if token contains "[]=", only wrap values that are already arrays
         # (typically produced by comma splitting), preserving list-of-lists semantics.
-        if parse_lists_enabled and pos != -1 and "[]=" in part and isinstance(val, (list, tuple)):
+        if bracket_array_assignment and isinstance(val, (list, tuple)):
             val = [val]
+            list_limit_exceeded = len(val) > options.list_limit
+        if list_limit_exceeded and isinstance(val, (list, tuple)):
+            if options.raise_on_limit_exceeded:
+                raise ValueError(_list_limit_exceeded_message(options.list_limit))
+            val = CommaOverflowDict({str(i): item for i, item in enumerate(val)})
 
         existing: bool = key in obj
+        part_duplicates = Duplicates.COMBINE if bracket_array_assignment else duplicates
 
         # Combine/overwrite according to the configured duplicates policy.
-        if existing and duplicates == Duplicates.COMBINE:
+        if existing and part_duplicates == Duplicates.COMBINE:
             obj[key] = Utils.combine(obj[key], val, options)
-        elif not existing or duplicates == Duplicates.LAST:
+        elif not existing or part_duplicates == Duplicates.LAST:
             obj[key] = val
 
     return obj
@@ -439,7 +454,7 @@ def _parse_object(
       handled by the splitter.
     - When list parsing is disabled and an empty segment is encountered, coerces to ``{"0": leaf}`` to preserve round-trippability with other ports.
     """
-    parse_lists_enabled = options.parse_lists if parse_lists is None else parse_lists
+    parse_lists_enabled: bool = options.parse_lists if parse_lists is None else parse_lists
     current_list_length: int = 0
 
     # If the chain ends with an empty list marker, compute current list length for limit checks.
@@ -467,7 +482,31 @@ def _parse_object(
         if parent_key is not None and isinstance(val, (list, tuple)) and parent_key in dict(enumerate(val)):
             current_list_length = len(val[parent_key])
 
-    leaf: t.Any = val if values_parsed else _parse_array_value(val, options, current_list_length)
+    bracket_array_comma_value: bool = (
+        not values_parsed
+        and bool(chain)
+        and chain[-1] == "[]"
+        and isinstance(val, str)
+        and bool(val)
+        and options.comma
+        and "," in val
+    )
+    leaf: t.Any = (
+        val
+        if values_parsed
+        else _parse_array_value(
+            val,
+            options,
+            current_list_length,
+            enforce_comma_limit=not bracket_array_comma_value,
+        )
+    )
+    if bracket_array_comma_value and isinstance(leaf, (list, tuple)):
+        leaf = [leaf]
+        if len(leaf) > options.list_limit:
+            if options.raise_on_limit_exceeded:
+                raise ValueError(_list_limit_exceeded_message(options.list_limit))
+            leaf = CommaOverflowDict({str(i): item for i, item in enumerate(leaf)})
 
     # Walk the chain from the leaf to the root, building nested containers on the way out.
     i: int
@@ -518,10 +557,14 @@ def _parse_object(
                 and root != decoded_root
                 and str(index) == decoded_root
                 and parse_lists_enabled
-                and index <= options.list_limit
             ):
-                obj = [UNDEFINED for _ in range(index + 1)]
-                obj[index] = leaf
+                if index < options.list_limit:
+                    obj = [UNDEFINED for _ in range(index + 1)]
+                    obj[index] = leaf
+                elif options.raise_on_limit_exceeded:
+                    raise ValueError(_list_limit_exceeded_message(options.list_limit))
+                else:
+                    obj[decoded_root] = leaf
             else:
                 # Preserve the literal decoded key for non-array roots (e.g. "[01]" -> "01"),
                 # matching Node `qs` behavior for leading-zero numeric-like segments.