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

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

@@ -1,3 +1,7 @@
+## 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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qs-codec
-Version: 1.5.2
+Version: 1.6.0
 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/
@@ -112,6 +112,67 @@ A simple usage example:
    # Decoding
    assert qs.decode('a=b') == {'a': 'b'}
 
+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
 ~~~~~~~~
 
@@ -752,14 +813,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.0}/README.rst

@@ -49,6 +49,67 @@ A simple usage example:
    # Decoding
    assert qs.decode('a=b') == {'a': 'b'}
 
+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
 ~~~~~~~~
 
@@ -689,14 +750,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.0}/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
 ~~~~~~~~
 
@@ -683,14 +744,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.0}/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.0"
 
 # 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.6.0/src/qs_codec/enums/sentinel.py

@@ -0,0 +1,50 @@
+"""Charset sentinel values and their percent-encoded forms.
+
+Browsers sometimes include an ``utf8=…`` sentinel in
+``application/x-www-form-urlencoded`` submissions to signal the character
+encoding that was used. This module exposes those sentinels as an enum whose
+members carry both the raw token emitted by the page and the fully URL-encoded
+fragment that appears on the wire.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+
+__all__ = ("Sentinel",)
+
+
+@dataclass(frozen=True)
+class _SentinelDataMixin:
+    """Common data carried by each charset sentinel.
+
+    Attributes:
+        raw: The unencoded token browsers start with, such as the HTML entity
+            string ``"✓"`` or the literal check mark ``"✓"``.
+        encoded: The full URL-encoded ``key=value`` fragment, such as
+            ``"utf8=%26%2310003%3B"`` or ``"utf8=%E2%9C%93"``.
+    """
+
+    raw: str
+    encoded: str
+
+
+class Sentinel(_SentinelDataMixin, Enum):
+    """Charset sentinels recognized and emitted by the codec.
+
+    Each member provides the source token through ``raw`` and the final
+    percent-encoded ``utf8=…`` fragment through ``encoded``.
+    """
+
+    ISO = r"✓", r"utf8=%26%2310003%3B"
+    """HTML-entity sentinel used by non-UTF-8 submissions.
+
+    When a check mark (✓) appears but the form encoding is ``iso-8859-1`` or
+    another charset that lacks it, browsers HTML-entity-escape the character
+    and then URL-encode it, producing ``utf8=%26%2310003%3B``.
+    """
+
+    CHARSET = r"✓", r"utf8=%E2%9C%93"
+    """UTF-8 sentinel indicating that the request is UTF-8 encoded.
+
+    The encoded form contains the percent-encoded UTF-8 sequence for ✓.
+    """

qs_codec-1.6.0/src/qs_codec/models/undefined.py

@@ -0,0 +1,62 @@
+"""Internal undefined sentinel used while building codec data structures.
+
+``Undefined`` represents a missing value that should be omitted, similar to
+JavaScript's ``undefined``. It is distinct from ``None``, which represents an
+explicit null value.
+
+The sentinel is identity-based: every construction returns the same instance,
+allowing reliable ``is`` comparisons throughout the codec internals.
+"""
+
+import threading
+import typing as t
+
+__all__ = ()
+
+
+class Undefined:
+    """Singleton sentinel representing a value that should be omitted.
+
+    This is not equivalent to ``None``. The encoder and helper utilities use it
+    temporarily to mark absent entries, then remove those entries before
+    returning public results.
+    """
+
+    __slots__ = ()
+    _lock: t.ClassVar[threading.Lock] = threading.Lock()
+    _instance: t.ClassVar[t.Optional["Undefined"]] = None
+
+    def __new__(cls):
+        """Return the singleton instance.
+
+        Repeated construction returns the same object reference so identity
+        checks remain stable.
+        """
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        """Return a string representation of the singleton."""
+        return "Undefined()"
+
+    def __copy__(self):  # pragma: no cover - trivial
+        """Preserve singleton identity when shallow-copied."""
+        return self
+
+    def __deepcopy__(self, memo):  # pragma: no cover - trivial
+        """Preserve singleton identity when deep-copied."""
+        return self
+
+    def __reduce__(self):  # pragma: no cover - trivial
+        """Reconstruct through the singleton constructor when unpickled."""
+        return Undefined, ()
+
+    def __init_subclass__(cls, **kwargs):  # pragma: no cover - defensive
+        """Prevent subclassing to preserve singleton identity."""
+        raise TypeError("Undefined cannot be subclassed")
+
+
+UNDEFINED: t.Final["Undefined"] = Undefined()

{qs_codec-1.5.2 → qs_codec-1.6.0}/tests/comparison/package.json

@@ -4,7 +4,7 @@
   "description": "A comparison of query string parsing libraries",
   "author": "Klemen Tusar",
   "license": "BSD-3-Clause",
-  "packageManager": "pnpm@11.1.3",
+  "packageManager": "pnpm@11.5.2",
   "dependencies": {
     "qs": "^6.15.2"
   }

{qs_codec-1.5.2 → qs_codec-1.6.0}/tests/unit/example_test.py

@@ -271,9 +271,6 @@ class TestEncoding:
         assert qs_codec.encode({"a": {"b": []}}) == ""
         assert qs_codec.encode({"a": {"b": {}}}) == ""
 
-        # Properties that are `Undefined` will be omitted entirely:
-        assert qs_codec.encode({"a": None, "b": qs_codec.Undefined()}) == "a="
-
         # The query string may optionally be prepended with a question mark:
         assert qs_codec.encode({"a": "b", "c": "d"}, qs_codec.EncodeOptions(add_query_prefix=True)) == "?a=b&c=d"
 

qs_codec-1.6.0/tests/unit/package_test.py

@@ -0,0 +1,18 @@
+import qs_codec
+import qs_codec.enums.sentinel as sentinel_module
+import qs_codec.models.undefined as undefined_module
+
+
+def test_sentinel_is_part_of_the_public_api():
+    assert "Sentinel" in qs_codec.__all__
+    assert qs_codec.Sentinel is sentinel_module.Sentinel
+
+
+def test_undefined_is_not_part_of_the_public_api():
+    assert "Undefined" not in qs_codec.__all__
+    assert not hasattr(qs_codec, "Undefined")
+
+
+def test_sentinel_modules_define_their_intended_exports():
+    assert sentinel_module.__all__ == ("Sentinel",)
+    assert undefined_module.__all__ == ()

qs_codec-1.5.2/src/qs_codec/enums/sentinel.py

@@ -1,50 +0,0 @@
-"""Sentinel values and their percent-encoded forms.
-
-Browsers sometimes include an ``utf8=…`` “sentinel” in
-``application/x-www-form-urlencoded`` submissions to signal the character
-encoding that was used. This module exposes those sentinels as an ``Enum``,
-where each member carries both the raw token (what the page emits) and the
-fully URL-encoded fragment (what appears on the wire).
-"""
-
-from dataclasses import dataclass
-from enum import Enum
-
-
-@dataclass(frozen=True)
-class _SentinelDataMixin:
-    """Common data carried by each sentinel.
-
-    Attributes:
-        raw: The unencoded token browsers start with. For example, the HTML
-            entity string ``"✓"`` or the literal check mark ``"✓"``.
-        encoded: The full ``key=value`` fragment after URL-encoding, e.g.
-            ``"utf8=%26%2310003%3B"`` or ``"utf8=%E2%9C%93"``.
-    """
-
-    raw: str
-    encoded: str
-
-
-class Sentinel(_SentinelDataMixin, Enum):
-    """All supported ``utf8`` sentinels.
-
-    Each enum member provides:
-        - ``raw``: the source token a browser starts with, and
-        - ``encoded``: the final, percent-encoded ``utf8=…`` fragment.
-    """
-
-    ISO = r"✓", r"utf8=%26%2310003%3B"
-    """HTML-entity sentinel used by non-UTF-8 submissions.
-
-    When a check mark (✓) appears but the page/form encoding is ``iso-8859-1``
-    (or another charset that lacks ✓), browsers first HTML-entity-escape it as
-    ``"✓"`` and then URL-encode it, producing ``utf8=%26%2310003%3B``.
-    """
-
-    CHARSET = r"✓", r"utf8=%E2%9C%93"
-    """UTF-8 sentinel indicating the request is UTF-8 encoded.
-
-    This is the percent-encoded UTF-8 sequence for ✓, yielding the fragment
-    ``utf8=%E2%9C%93``.
-    """

qs_codec-1.5.2/src/qs_codec/models/undefined.py

@@ -1,73 +0,0 @@
-"""Undefined sentinel.
-
-This module defines a tiny singleton `Undefined` used as a *sentinel* to mean “no value provided / omit this key”,
-similar to JavaScript’s `undefined`.
-
-Unlike `None` (which commonly means an explicit null), `Undefined` is used by the encoder and helper utilities to *skip*
-emitting a key or to signal that a value is intentionally absent and should not be serialized.
-
-The sentinel is identity-based: every construction returns the same instance, so `is` comparisons are reliable
-(e.g., `value is Undefined()`).
-"""
-
-import threading
-import typing as t
-
-
-class Undefined:
-    """Singleton sentinel object representing an “undefined” value.
-
-    Notes:
-        * This is **not** the same as `None`. Use `None` to represent a *null* value and `Undefined()` to represent “no value / omit”.
-        * All calls to ``Undefined()`` return the same instance. Prefer identity checks (``is``) over equality checks.
-
-    Examples:
-        >>> from qs_codec.models.undefined import Undefined
-        >>> a = Undefined()
-        >>> b = Undefined()
-        >>> a is b
-        True
-        >>> # Use it to indicate a key should be omitted when encoding:
-        >>> maybe_value = Undefined()
-        >>> if maybe_value is Undefined():
-        ...     pass  # skip emitting the key
-    """
-
-    __slots__ = ()
-    _lock: t.ClassVar[threading.Lock] = threading.Lock()
-    _instance: t.ClassVar[t.Optional["Undefined"]] = None
-
-    def __new__(cls):
-        """Return the singleton instance.
-
-        Creating `Undefined()` multiple times always returns the same object reference. This ensures identity checks (``is``) are stable.
-        """
-        if cls._instance is None:
-            with cls._lock:
-                if cls._instance is None:
-                    cls._instance = super().__new__(cls)
-        return cls._instance
-
-    def __repr__(self) -> str:  # pragma: no cover - trivial
-        """Return a string representation of the singleton."""
-        return "Undefined()"
-
-    def __copy__(self):  # pragma: no cover - trivial
-        """Ensure copies/pickles preserve the singleton identity."""
-        return self
-
-    def __deepcopy__(self, memo):  # pragma: no cover - trivial
-        """Ensure deep copies preserve the singleton identity."""
-        return self
-
-    def __reduce__(self):  # pragma: no cover - trivial
-        """Recreate via calling the constructor, which returns the singleton."""
-        return Undefined, ()
-
-    def __init_subclass__(cls, **kwargs):  # pragma: no cover - defensive
-        """Prevent subclassing of Undefined."""
-        raise TypeError("Undefined cannot be subclassed")
-
-
-UNDEFINED: t.Final["Undefined"] = Undefined()
-__all__ = ["Undefined", "UNDEFINED"]