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

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

@@ -1,3 +1,13 @@
+## 1.6.1
+
+* [FIX] match Node `qs` 6.15.3 cumulative list-limit enforcement across duplicate-key combinations and mixed list merges
+* [FIX] reject oversized flat comma values before allocating their split lists or decoding their values when `raise_on_limit_exceeded` is enabled
+* [CHORE] add Node `qs` 6.15.3 regression coverage for unbalanced bracket keys and cyclic compaction
+
+## 1.6.0
+
+* [CHORE] make `Undefined` internal by removing `qs_codec.Undefined` and its public documentation
+
 ## 1.5.2
 
 * [CHORE] simplify mapping and key-iteration checks in encode/decode internals

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qs-codec
-Version: 1.5.2
+Version: 1.6.1
 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/
@@ -88,7 +88,7 @@ Highlights
 - Pluggable hooks: custom ``encoder``/``decoder`` callables; options to sort keys, filter output, and control percent-encoding (keys-only, values-only).
 - Nulls & empties: ``strict_null_handling`` and ``skip_nulls``; support for empty lists/arrays when desired.
 - Dates: ``serialize_date`` for ISO 8601 or custom (e.g., UNIX timestamp).
-- Safety limits: configurable decode depth and encode max depth, parameter limit, and list index limit; optional strict-depth errors; duplicate-key strategies (combine/first/last).
+- Safety limits: configurable decode depth and encode max depth, parameter limit, and list element limit; optional strict-depth errors; duplicate-key strategies (combine/first/last).
 - Extras: numeric entity decoding (e.g. ``☺`` → ☺), alternate delimiters/regex, and query-prefix helpers.
 
 Compatibility
@@ -112,6 +112,157 @@ A simple usage example:
    # Decoding
    assert qs.decode('a=b') == {'a': 'b'}
 
+Compared with ``urllib.parse``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The standard library's
+`urlencode <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlencode>`__,
+`parse_qs <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.parse_qs>`__,
+and
+`parse_qsl <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.parse_qsl>`__
+are designed for conventional flat ``application/x-www-form-urlencoded``
+data. Use ``qs_codec`` when the query represents nested dictionaries or lists,
+must interoperate with Node ``qs``, or needs configurable list, duplicate, null,
+or resource-limit behavior.
+
+``urlencode`` can expand a flat sequence into repeated keys with
+``doseq=True``, which corresponds to ``ListFormat.REPEAT``. It does not
+recursively encode nested mappings; ``qs.encode`` uses bracket or dot paths
+instead:
+
+.. code:: python
+
+   from urllib.parse import urlencode
+
+   import qs_codec as qs
+
+   assert urlencode({'tags': ['a', 'b']}, doseq=True) == 'tags=a&tags=b'
+   assert qs.encode(
+       {'tags': ['a', 'b']},
+       qs.EncodeOptions(list_format=qs.ListFormat.REPEAT),
+   ) == 'tags=a&tags=b'
+   assert qs.encode(
+       {'filter': {'name': 'Jane'}},
+   ) == 'filter%5Bname%5D=Jane'
+
+The encoding defaults also differ: ``urlencode`` emits spaces as ``+`` and
+uses Python scalar spellings such as ``True`` and ``None``; ``qs.encode`` uses
+``%20``, lowercase booleans, and an empty value for ``None`` by default.
+
+On decode, ``parse_qs`` returns a dictionary whose values are always lists,
+while ``parse_qsl`` returns an ordered list of name/value pairs and preserves
+interleaved duplicate keys. Both treat bracket expressions as literal key
+names, drop blank values unless ``keep_blank_values=True``, and collapse a
+name-only token and an explicit empty value to the same empty string.
+``qs.decode`` normally returns a scalar for one value, reconstructs bracket
+paths, and can preserve that null distinction:
+
+.. code:: python
+
+   from urllib.parse import parse_qs, parse_qsl
+
+   import qs_codec as qs
+
+   query = 'a=1&b=2&a=3&filter%5Bname%5D=Jane&flag&empty='
+
+   assert parse_qs(query, keep_blank_values=True) == {
+       'a': ['1', '3'],
+       'b': ['2'],
+       'filter[name]': ['Jane'],
+       'flag': [''],
+       'empty': [''],
+   }
+   assert parse_qsl(query, keep_blank_values=True) == [
+       ('a', '1'),
+       ('b', '2'),
+       ('a', '3'),
+       ('filter[name]', 'Jane'),
+       ('flag', ''),
+       ('empty', ''),
+   ]
+   assert qs.decode(
+       query,
+       qs.DecodeOptions(strict_null_handling=True),
+   ) == {
+       'a': ['1', '3'],
+       'b': '2',
+       'filter': {'name': 'Jane'},
+       'flag': None,
+       'empty': '',
+   }
+
+All three decoders leave primitive values as strings. ``parse_qs`` and
+``qs.decode`` combine repeated flat keys under their default behavior;
+``parse_qsl`` instead retains each pair in input order. The standard-library
+parsers offer ``max_num_fields``; ``qs.decode`` additionally provides default
+parameter, nesting-depth, and list limits plus configurable duplicate handling.
+
+Use ``parse_qsl`` when flat pair order or duplicate interleaving matters, but
+not as a raw-query round-trip format: it percent-decodes names and values,
+normalizes ``+`` and ``%20`` to the same space, and cannot retain the distinction
+between a name-only token and an explicit empty value.
+
+Working with URLs
+~~~~~~~~~~~~~~~~~
+
+Use `urllib.parse.urlsplit <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlsplit>`__
+to keep URL parsing separate from query-string decoding. Pass the encoded
+``query`` component directly to ``qs.decode`` without calling ``unquote``,
+``unquote_plus``, ``parse_qs``, or ``parse_qsl`` first:
+
+.. code:: python
+
+   from urllib.parse import urlsplit
+
+   import qs_codec as qs
+
+   parts = urlsplit(
+       'https://example.com/search?filter%5Bname%5D=Jane%20Doe&flag#results'
+   )
+   params = qs.decode(
+       parts.query,
+       qs.DecodeOptions(strict_null_handling=True),
+   )
+
+   assert params == {
+       'filter': {'name': 'Jane Doe'},
+       'flag': None,
+   }
+
+Passing the encoded component unchanged ensures that escaped delimiters such as
+``%26``, escaped percent signs such as ``%2525``, and encoded bracket syntax
+reach ``qs.decode`` without being decoded twice.
+
+To replace a URL query, encode fresh data and assign it to the split result's
+``query`` component:
+
+.. code:: python
+
+   updated = parts._replace(
+       query=qs.encode({
+           'filter': {'name': 'John Doe'},
+           'tags': ['a', 'b'],
+       }),
+   ).geturl()
+
+   assert updated == (
+       'https://example.com/search?'
+       'filter%5Bname%5D=John%20Doe&tags%5B0%5D=a&tags%5B1%5D=b'
+       '#results'
+   )
+
+Keep `EncodeOptions.add_query_prefix <https://techouse.github.io/qs_codec/qs_codec.models.html#qs_codec.models.encode_options.EncodeOptions.add_query_prefix>`__
+set to ``False`` (the default) when assigning to ``SplitResult.query``. Options
+such as ``encode=False``, ``encode_values_only=True``, or a custom encoder can
+emit raw URL-structural characters, so callers using them must ensure the result
+is safe query-component text.
+
+This pattern replaces the existing query; it does not append or merge it.
+Appending or decoding and re-encoding an arbitrary query can change delimiter,
+duplicate-key, name-only, list-format, ordering, and percent-encoding semantics.
+``SplitResult.geturl()`` may also normalize URL spelling and removes an explicit
+empty ``?`` delimiter.
+
 Decoding
 ~~~~~~~~
 
@@ -409,12 +560,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']}
 
-`decode <https://techouse.github.io/qs_codec/qs_codec.html#module-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``.
+`decode <https://techouse.github.io/qs_codec/qs_codec.html#module-qs_codec.decode>`__ also limits each ``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 prevents inputs such as ``a[999999999]`` from
+creating massive sparse lists.
 
 .. code:: python
 
@@ -434,6 +584,24 @@ option:
        qs.DecodeOptions(list_limit=0),
    ) == {'a': {'1': 'b'}}
 
+The same limit is enforced cumulatively when duplicate keys, mixed list
+notation, or comma-separated values grow a list. A result exactly at the limit
+remains a ``list``. Above the limit, decoding uses a numeric-keyed ``dict`` by
+default, or raises ``ValueError`` when ``raise_on_limit_exceeded=True``.
+
+.. code:: python
+
+   import qs_codec as qs
+
+   assert qs.decode(
+       'a=x&a=y',
+       qs.DecodeOptions(list_limit=1),
+   ) == {'a': {'0': 'x', '1': 'y'}}
+
+With ``comma=True``, a flat comma value is subject to the same limit. A value
+assigned through ``[]=`` counts as one outer list element, so its inner
+comma-separated group may contain more values than ``list_limit``.
+
 To disable ``list`` parsing entirely, set `parse_lists <https://techouse.github.io/qs_codec/qs_codec.models.html#qs_codec.models.decode_options.DecodeOptions.parse_lists>`__
 to ``False``.
 
@@ -752,14 +920,6 @@ Keys with no values (such as an empty ``dict`` or ``list``) will return nothing:
 
    assert qs.encode({'a': {'b': {}}}) == ''
 
-`Undefined <https://techouse.github.io/qs_codec/qs_codec.models.html#qs_codec.models.undefined.Undefined>`__ properties will be omitted entirely:
-
-.. code:: python
-
-   import qs_codec as qs
-
-   assert qs.encode({'a': None, 'b': qs.Undefined()}) == 'a='
-
 The query string may optionally be prepended with a question mark (``?``) by setting
 `add_query_prefix <https://techouse.github.io/qs_codec/qs_codec.models.html#qs_codec.models.encode_options.EncodeOptions.add_query_prefix>`__ to ``True``:
 

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

@@ -25,7 +25,7 @@ Highlights
 - Pluggable hooks: custom ``encoder``/``decoder`` callables; options to sort keys, filter output, and control percent-encoding (keys-only, values-only).
 - Nulls & empties: ``strict_null_handling`` and ``skip_nulls``; support for empty lists/arrays when desired.
 - Dates: ``serialize_date`` for ISO 8601 or custom (e.g., UNIX timestamp).
-- Safety limits: configurable decode depth and encode max depth, parameter limit, and list index limit; optional strict-depth errors; duplicate-key strategies (combine/first/last).
+- Safety limits: configurable decode depth and encode max depth, parameter limit, and list element limit; optional strict-depth errors; duplicate-key strategies (combine/first/last).
 - Extras: numeric entity decoding (e.g. ``☺`` → ☺), alternate delimiters/regex, and query-prefix helpers.
 
 Compatibility
@@ -49,6 +49,157 @@ A simple usage example:
    # Decoding
    assert qs.decode('a=b') == {'a': 'b'}
 
+Compared with ``urllib.parse``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The standard library's
+`urlencode <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlencode>`__,
+`parse_qs <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.parse_qs>`__,
+and
+`parse_qsl <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.parse_qsl>`__
+are designed for conventional flat ``application/x-www-form-urlencoded``
+data. Use ``qs_codec`` when the query represents nested dictionaries or lists,
+must interoperate with Node ``qs``, or needs configurable list, duplicate, null,
+or resource-limit behavior.
+
+``urlencode`` can expand a flat sequence into repeated keys with
+``doseq=True``, which corresponds to ``ListFormat.REPEAT``. It does not
+recursively encode nested mappings; ``qs.encode`` uses bracket or dot paths
+instead:
+
+.. code:: python
+
+   from urllib.parse import urlencode
+
+   import qs_codec as qs
+
+   assert urlencode({'tags': ['a', 'b']}, doseq=True) == 'tags=a&tags=b'
+   assert qs.encode(
+       {'tags': ['a', 'b']},
+       qs.EncodeOptions(list_format=qs.ListFormat.REPEAT),
+   ) == 'tags=a&tags=b'
+   assert qs.encode(
+       {'filter': {'name': 'Jane'}},
+   ) == 'filter%5Bname%5D=Jane'
+
+The encoding defaults also differ: ``urlencode`` emits spaces as ``+`` and
+uses Python scalar spellings such as ``True`` and ``None``; ``qs.encode`` uses
+``%20``, lowercase booleans, and an empty value for ``None`` by default.
+
+On decode, ``parse_qs`` returns a dictionary whose values are always lists,
+while ``parse_qsl`` returns an ordered list of name/value pairs and preserves
+interleaved duplicate keys. Both treat bracket expressions as literal key
+names, drop blank values unless ``keep_blank_values=True``, and collapse a
+name-only token and an explicit empty value to the same empty string.
+``qs.decode`` normally returns a scalar for one value, reconstructs bracket
+paths, and can preserve that null distinction:
+
+.. code:: python
+
+   from urllib.parse import parse_qs, parse_qsl
+
+   import qs_codec as qs
+
+   query = 'a=1&b=2&a=3&filter%5Bname%5D=Jane&flag&empty='
+
+   assert parse_qs(query, keep_blank_values=True) == {
+       'a': ['1', '3'],
+       'b': ['2'],
+       'filter[name]': ['Jane'],
+       'flag': [''],
+       'empty': [''],
+   }
+   assert parse_qsl(query, keep_blank_values=True) == [
+       ('a', '1'),
+       ('b', '2'),
+       ('a', '3'),
+       ('filter[name]', 'Jane'),
+       ('flag', ''),
+       ('empty', ''),
+   ]
+   assert qs.decode(
+       query,
+       qs.DecodeOptions(strict_null_handling=True),
+   ) == {
+       'a': ['1', '3'],
+       'b': '2',
+       'filter': {'name': 'Jane'},
+       'flag': None,
+       'empty': '',
+   }
+
+All three decoders leave primitive values as strings. ``parse_qs`` and
+``qs.decode`` combine repeated flat keys under their default behavior;
+``parse_qsl`` instead retains each pair in input order. The standard-library
+parsers offer ``max_num_fields``; ``qs.decode`` additionally provides default
+parameter, nesting-depth, and list limits plus configurable duplicate handling.
+
+Use ``parse_qsl`` when flat pair order or duplicate interleaving matters, but
+not as a raw-query round-trip format: it percent-decodes names and values,
+normalizes ``+`` and ``%20`` to the same space, and cannot retain the distinction
+between a name-only token and an explicit empty value.
+
+Working with URLs
+~~~~~~~~~~~~~~~~~
+
+Use `urllib.parse.urlsplit <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlsplit>`__
+to keep URL parsing separate from query-string decoding. Pass the encoded
+``query`` component directly to ``qs.decode`` without calling ``unquote``,
+``unquote_plus``, ``parse_qs``, or ``parse_qsl`` first:
+
+.. code:: python
+
+   from urllib.parse import urlsplit
+
+   import qs_codec as qs
+
+   parts = urlsplit(
+       'https://example.com/search?filter%5Bname%5D=Jane%20Doe&flag#results'
+   )
+   params = qs.decode(
+       parts.query,
+       qs.DecodeOptions(strict_null_handling=True),
+   )
+
+   assert params == {
+       'filter': {'name': 'Jane Doe'},
+       'flag': None,
+   }
+
+Passing the encoded component unchanged ensures that escaped delimiters such as
+``%26``, escaped percent signs such as ``%2525``, and encoded bracket syntax
+reach ``qs.decode`` without being decoded twice.
+
+To replace a URL query, encode fresh data and assign it to the split result's
+``query`` component:
+
+.. code:: python
+
+   updated = parts._replace(
+       query=qs.encode({
+           'filter': {'name': 'John Doe'},
+           'tags': ['a', 'b'],
+       }),
+   ).geturl()
+
+   assert updated == (
+       'https://example.com/search?'
+       'filter%5Bname%5D=John%20Doe&tags%5B0%5D=a&tags%5B1%5D=b'
+       '#results'
+   )
+
+Keep `EncodeOptions.add_query_prefix <https://techouse.github.io/qs_codec/qs_codec.models.html#qs_codec.models.encode_options.EncodeOptions.add_query_prefix>`__
+set to ``False`` (the default) when assigning to ``SplitResult.query``. Options
+such as ``encode=False``, ``encode_values_only=True``, or a custom encoder can
+emit raw URL-structural characters, so callers using them must ensure the result
+is safe query-component text.
+
+This pattern replaces the existing query; it does not append or merge it.
+Appending or decoding and re-encoding an arbitrary query can change delimiter,
+duplicate-key, name-only, list-format, ordering, and percent-encoding semantics.
+``SplitResult.geturl()`` may also normalize URL spelling and removes an explicit
+empty ``?`` delimiter.
+
 Decoding
 ~~~~~~~~
 
@@ -346,12 +497,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']}
 
-`decode <https://techouse.github.io/qs_codec/qs_codec.html#module-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``.
+`decode <https://techouse.github.io/qs_codec/qs_codec.html#module-qs_codec.decode>`__ also limits each ``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 prevents inputs such as ``a[999999999]`` from
+creating massive sparse lists.
 
 .. code:: python
 
@@ -371,6 +521,24 @@ option:
        qs.DecodeOptions(list_limit=0),
    ) == {'a': {'1': 'b'}}
 
+The same limit is enforced cumulatively when duplicate keys, mixed list
+notation, or comma-separated values grow a list. A result exactly at the limit
+remains a ``list``. Above the limit, decoding uses a numeric-keyed ``dict`` by
+default, or raises ``ValueError`` when ``raise_on_limit_exceeded=True``.
+
+.. code:: python
+
+   import qs_codec as qs
+
+   assert qs.decode(
+       'a=x&a=y',
+       qs.DecodeOptions(list_limit=1),
+   ) == {'a': {'0': 'x', '1': 'y'}}
+
+With ``comma=True``, a flat comma value is subject to the same limit. A value
+assigned through ``[]=`` counts as one outer list element, so its inner
+comma-separated group may contain more values than ``list_limit``.
+
 To disable ``list`` parsing entirely, set `parse_lists <https://techouse.github.io/qs_codec/qs_codec.models.html#qs_codec.models.decode_options.DecodeOptions.parse_lists>`__
 to ``False``.
 
@@ -689,14 +857,6 @@ Keys with no values (such as an empty ``dict`` or ``list``) will return nothing:
 
    assert qs.encode({'a': {'b': {}}}) == ''
 
-`Undefined <https://techouse.github.io/qs_codec/qs_codec.models.html#qs_codec.models.undefined.Undefined>`__ properties will be omitted entirely:
-
-.. code:: python
-
-   import qs_codec as qs
-
-   assert qs.encode({'a': None, 'b': qs.Undefined()}) == 'a='
-
 The query string may optionally be prepended with a question mark (``?``) by setting
 `add_query_prefix <https://techouse.github.io/qs_codec/qs_codec.models.html#qs_codec.models.encode_options.EncodeOptions.add_query_prefix>`__ to ``True``:
 

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

@@ -10,6 +10,67 @@ Do not mutate caller-owned input containers or shared callback state while an
 free-threaded CPython build, which is supported and covered by the thread-safety
 test suite without changing these mutation guarantees.
 
+Working with URLs
+~~~~~~~~~~~~~~~~~
+
+Use `urllib.parse.urlsplit <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlsplit>`_
+to keep URL parsing separate from query-string decoding. Pass the encoded
+``query`` component directly to :py:attr:`qs_codec.decode` without calling
+``unquote``, ``unquote_plus``, ``parse_qs``, or ``parse_qsl`` first:
+
+.. code:: python
+
+   from urllib.parse import urlsplit
+
+   import qs_codec as qs
+
+   parts = urlsplit(
+       'https://example.com/search?filter%5Bname%5D=Jane%20Doe&flag#results'
+   )
+   params = qs.decode(
+       parts.query,
+       qs.DecodeOptions(strict_null_handling=True),
+   )
+
+   assert params == {
+       'filter': {'name': 'Jane Doe'},
+       'flag': None,
+   }
+
+Passing the encoded component unchanged ensures that escaped delimiters such as
+``%26``, escaped percent signs such as ``%2525``, and encoded bracket syntax
+reach :py:attr:`qs_codec.decode` without being decoded twice.
+
+To replace a URL query, encode fresh data and assign it to the split result's
+``query`` component:
+
+.. code:: python
+
+   updated = parts._replace(
+       query=qs.encode({
+           'filter': {'name': 'John Doe'},
+           'tags': ['a', 'b'],
+       }),
+   ).geturl()
+
+   assert updated == (
+       'https://example.com/search?'
+       'filter%5Bname%5D=John%20Doe&tags%5B0%5D=a&tags%5B1%5D=b'
+       '#results'
+   )
+
+Keep :py:attr:`add_query_prefix <qs_codec.models.encode_options.EncodeOptions.add_query_prefix>`
+set to ``False`` (the default) when assigning to ``SplitResult.query``. Options
+such as ``encode=False``, ``encode_values_only=True``, or a custom encoder can
+emit raw URL-structural characters, so callers using them must ensure the result
+is safe query-component text.
+
+This pattern replaces the existing query; it does not append or merge it.
+Appending or decoding and re-encoding an arbitrary query can change delimiter,
+duplicate-key, name-only, list-format, ordering, and percent-encoding semantics.
+``SplitResult.geturl()`` may also normalize URL spelling and removes an explicit
+empty ``?`` delimiter.
+
 Decoding
 ~~~~~~~~
 
@@ -366,6 +427,25 @@ option:
        qs.DecodeOptions(list_limit=0),
    ) == {'a': {'1': 'b'}}
 
+The same limit is enforced cumulatively when duplicate keys, mixed list
+notation, or comma-separated values grow a list. A result exactly at the limit
+remains a ``list``. Above the limit, decoding uses a numeric-keyed ``dict`` by
+default, or raises ``ValueError`` when
+:py:attr:`raise_on_limit_exceeded <qs_codec.models.decode_options.DecodeOptions.raise_on_limit_exceeded>` is ``True``.
+
+.. code:: python
+
+   import qs_codec as qs
+
+   assert qs.decode(
+       'a=x&a=y',
+       qs.DecodeOptions(list_limit=1),
+   ) == {'a': {'0': 'x', '1': 'y'}}
+
+With ``comma=True``, a flat comma value is subject to the same limit. A value
+assigned through ``[]=`` counts as one outer list element, so its inner
+comma-separated group may contain more values than ``list_limit``.
+
 To disable ``list`` parsing entirely, set :py:attr:`parse_lists <qs_codec.models.decode_options.DecodeOptions.parse_lists>`
 to ``False``.
 
@@ -683,14 +763,6 @@ Keys with no values (such as an empty ``dict`` or ``list``) will return nothing:
 
    assert qs.encode({'a': {'b': {}}}) == ''
 
-:py:attr:`Undefined <qs_codec.models.undefined.Undefined>` properties will be omitted entirely:
-
-.. code:: python
-
-   import qs_codec as qs
-
-   assert qs.encode({'a': None, 'b': qs.Undefined()}) == 'a='
-
 The query string may optionally be prepended with a question mark (``?``) by setting
 :py:attr:`add_query_prefix <qs_codec.models.encode_options.EncodeOptions.add_query_prefix>` to ``True``:
 

{qs_codec-1.5.2 → qs_codec-1.6.1}/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.2"
+__version__ = "1.6.1"
 
 # Public API surface re-exported at the package root.
 __all__ = [
@@ -31,7 +31,6 @@ __all__ = [
     "Sentinel",
     "DecodeOptions",
     "EncodeOptions",
-    "Undefined",
 ]
 
 from .decode import decode, load, loads
@@ -44,4 +43,3 @@ from .enums.list_format import ListFormat
 from .enums.sentinel import Sentinel
 from .models.decode_options import DecodeOptions
 from .models.encode_options import EncodeOptions
-from .models.undefined import Undefined

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

@@ -63,7 +63,8 @@ def decode(
     Notes
     -----
     - Empty/falsey ``value`` returns an empty dict.
-    - When the *number of top-level tokens* exceeds ``list_limit`` and ``parse_lists`` is enabled, the parser temporarily **disables list parsing** for this invocation to avoid quadratic work. This mirrors the behavior of other ports and keeps large flat query strings efficient.
+    - ``parse_lists`` is honored directly throughout decoding. ``list_limit`` is enforced while constructing and
+      merging lists without changing the configured list-parsing mode.
     """
     obj: t.Dict[str, t.Any] = {}
 
@@ -78,17 +79,6 @@ def decode(
     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: 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
-        if isinstance(opts.delimiter, re.Pattern):
-            parts_count = len(re.split(opts.delimiter, query)) if query else 0
-        else:
-            parts_count = (query.count(opts.delimiter) + 1) if query else 0
-        if 0 < opts.list_limit < parts_count:
-            parse_lists_effective = False
-
     if decode_from_string:
         temp_obj: t.Optional[t.Dict[str, t.Any]] = _parse_query_string_values(str_value, opts)
     else:
@@ -118,7 +108,7 @@ def decode(
                 obj[key] = val
             continue
 
-        new_obj: t.Any = _parse_keys(key, val, opts, decode_from_string, parse_lists=parse_lists_effective)
+        new_obj: t.Any = _parse_keys(key, val, opts, decode_from_string, parse_lists=opts.parse_lists)
 
         if not obj and isinstance(new_obj, dict):
             obj = new_obj
@@ -253,10 +243,17 @@ def _parse_array_value(
         Either the original value or a list of values, without decoding (that happens later).
     """
     if isinstance(value, str) and value and options.comma and "," in value:
+        if enforce_comma_limit and options.raise_on_limit_exceeded:
+            comma_count = 0
+            comma_index = value.find(",")
+            while comma_index >= 0:
+                comma_count += 1
+                if comma_count >= options.list_limit:
+                    raise ValueError(_list_limit_exceeded_message(options.list_limit))
+                comma_index = value.find(",", comma_index + 1)
+
         split_val: t.List[str] = value.split(",")
         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
 
@@ -384,7 +381,7 @@ def _parse_query_string_values(value: str, options: DecodeOptions) -> t.Dict[str
                 part[pos + 1 :],
                 options,
                 len(obj[key]) if key in obj and isinstance(obj[key], (list, tuple)) else 0,
-                enforce_comma_limit=False,
+                enforce_comma_limit=not bracket_array_assignment,
             )
             list_limit_exceeded = isinstance(parsed_value, (list, tuple)) and len(parsed_value) > options.list_limit
             if isinstance(parsed_value, (list, tuple)):