Merge pull request #45 from techouse/chore/optimize-encoder-some-more

* [CHORE] optimize `encode` hot paths with lower-overhead iterative traversal, cheaper container checks, and deep linear mapping fast paths
* [CHORE] optimize `EncodeUtils` ASCII/BMP handling and `KeyPathNode` path materialization caching for repeated encode workloads
* [FIX] preserve legacy `max_depth` vs circular-reference error precedence in both generic and fast-path encoding
* [FIX] keep `EncodeOptions` free of encode-time mutable cache state while preserving encoder/equality behavior
* [CHORE] expand encode regression coverage for deep nesting, cycle handling, key-path caching, and `EncodeOptions` semantics

Author: techouse

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.4.5-wip
+
+* [CHORE] optimize `encode` hot paths with lower-overhead iterative traversal, cheaper container checks, and deep linear mapping fast paths
+* [CHORE] optimize `EncodeUtils` ASCII/BMP handling and `KeyPathNode` path materialization caching for repeated encode workloads
+* [FIX] preserve legacy `max_depth` vs circular-reference error precedence in both generic and fast-path encoding
+* [FIX] keep `EncodeOptions` free of encode-time mutable cache state while preserving encoder/equality behavior
+* [CHORE] expand encode regression coverage for deep nesting, cycle handling, key-path caching, and `EncodeOptions` semantics
+
 ## 1.4.4
 
 * [CHORE] optimize `decode` hot paths via structured-key pre-scan/bypass logic and lower-overhead default decoder dispatch

src/qs_codec/decode.py

@@ -435,7 +435,7 @@ def _parse_object(
       ``raise_on_limit_exceeded`` is True; with ``raise_on_limit_exceeded=True``, any list-growth operation
       (empty brackets, comma-split, nested pushes) raises immediately.
     - Inside bracket segments, a custom key decoder may leave percent-encoded dots (``%2E/%2e``). When
-      ``decode_dot_in_keys`` is True, these are normalized to ``.`` here. Top‑level dot splitting is already
+      ``decode_dot_in_keys`` is True, these are normalized to ``.`` here. Top-level dot splitting is already
       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.
     """
@@ -489,10 +489,10 @@ def _parse_object(
 
             # Map `%2E`/`%2e` to a literal dot *inside bracket segments* when
             # `decode_dot_in_keys` is enabled. Even though `_parse_query_string_values`
-            # typically percent‑decodes the key (default decoder), a custom
+            # typically percent-decodes the key (default decoder), a custom
             # `DecodeOptions.decoder` may return the raw token. In that case, `%2E` can
             # still appear here and must be normalized for parity with the Kotlin/C#/Swift/Dart ports.
-            # (Top‑level dot splitting is performed earlier by the key splitter.)
+            # (Top-level dot splitting is performed earlier by the key splitter.)
             clean_root: str = root[1:-1] if root.startswith("[") and root.endswith("]") else root
 
             if options.decode_dot_in_keys and "%2" in clean_root:

src/qs_codec/encode.py

@@ -1,4 +1,4 @@
-"""List formatting strategies for query‑string arrays.
+"""List formatting strategies for query-string arrays.
 
 This module defines small generator functions and an enum that the encoder
 uses to format list (array) keys, e.g., ``foo[]=1``, ``foo[0]=1``, ``foo=1,2``,
@@ -36,7 +36,7 @@ def brackets(prefix: str, key: t.Optional[str] = None) -> str:  # pylint: disabl
 
     @staticmethod
     def comma(prefix: str, key: t.Optional[str] = None) -> str:  # pylint: disable=W0613
-        """Return the key for comma‑separated lists (no change).
+        """Return the key for comma-separated lists (no change).
 
         The encoder will join values with commas instead of repeating the key.
 
@@ -104,7 +104,7 @@ class ListFormat(_ListFormatDataMixin, Enum):
     - ``BRACKETS``: ``foo[]`` for each element.
     - ``INDICES``: ``foo[0]``, ``foo[1]``, …
     - ``REPEAT``: repeat the key per value (``foo=1&foo=2``).
-    - ``COMMA``: single key with comma‑joined values (``foo=1,2``).
+    - ``COMMA``: single key with comma-joined values (``foo=1,2``).
 
     These options control only how keys are produced; value encoding and
     delimiter handling are governed by other options.

src/qs_codec/enums/list_format.py

@@ -35,16 +35,16 @@ class Sentinel(_SentinelDataMixin, Enum):
     """
 
     ISO = r"✓", r"utf8=%26%2310003%3B"
-    """HTML‑entity sentinel used by non‑UTF‑8 submissions.
+    """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``.
+    (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.
+    """UTF-8 sentinel indicating the request is UTF-8 encoded.
 
-    This is the percent‑encoded UTF‑8 sequence for ✓, yielding the fragment
+    This is the percent-encoded UTF-8 sequence for ✓, yielding the fragment
     ``utf8=%E2%9C%93``.
     """

src/qs_codec/enums/sentinel.py

@@ -25,13 +25,13 @@ class DecodeOptions:
     When ``None`` (default), it inherits the value of ``decode_dot_in_keys``."""
 
     decode_dot_in_keys: t.Optional[bool] = None
-    """Set to ``True`` to decode percent‑encoded dots in keys (e.g., ``%2E`` → ``.``).
+    """Set to ``True`` to decode percent-encoded dots in keys (e.g., ``%2E`` → ``.``).
     Note: it implies ``allow_dots``, so ``decode`` will error if you set ``decode_dot_in_keys`` to ``True``, and
     ``allow_dots`` to ``False``.
     When ``None`` (default), it defaults to ``False``.
 
     Inside bracket segments, percent-decoding naturally yields ``.`` from ``%2E/%2e``. This option controls whether
-    **top‑level** encoded dots are treated as additional split points; it does **not** affect the literal ``.`` produced
+    **top-level** encoded dots are treated as additional split points; it does **not** affect the literal ``.`` produced
     by percent-decoding inside bracket segments."""
 
     allow_empty_lists: bool = False
@@ -136,7 +136,7 @@ class DecodeOptions:
     """
 
     legacy_decoder: t.Optional[t.Callable[..., t.Optional[t.Any]]] = None
-    """Back‑compat adapter for legacy decoders of the form ``decoder(value, charset)``.
+    """Back-compat adapter for legacy decoders of the form ``decoder(value, charset)``.
     Prefer ``decoder`` which may optionally accept a ``kind`` argument. When both are supplied,
     ``decoder`` takes precedence (mirroring Kotlin/C#/Swift/Dart behavior)."""
 

src/qs_codec/models/decode_options.py

@@ -84,7 +84,7 @@ class EncodeFrame:
     is_sequence: bool
     step: int
     obj_keys: t.List[t.Any]
-    values: t.List[t.Any]
+    values: t.Optional[t.List[t.Any]]
     index: int
     adjusted_path: t.Optional[KeyPathNode]
     cycle_state: t.Optional[CycleState]
@@ -152,7 +152,7 @@ def __init__(
         self.is_sequence = False
         self.step = 0
         self.obj_keys = []
-        self.values = []
+        self.values = None
         self.index = 0
         self.adjusted_path = None
         self.cycle_state = cycle_state

src/qs_codec/models/encode_frame.py

@@ -46,7 +46,7 @@ class EncodeOptions:
     """Controls how lists are encoded (indices/brackets/repeat/comma). See `ListFormat`."""
 
     charset: Charset = Charset.UTF8
-    """Character encoding used by the encoder (defaults to UTF‑8)."""
+    """Character encoding used by the encoder (defaults to UTF-8)."""
 
     charset_sentinel: bool = False
     """When `True`, include a sentinel parameter announcing the charset (e.g. `utf8=✓`)."""
@@ -55,7 +55,7 @@ class EncodeOptions:
     """Pair delimiter between tokens (typically `&`; `;` and others are allowed)."""
 
     encode: bool = True
-    """Master switch. When `False`, values/keys are not percent‑encoded (joined as-is)."""
+    """Master switch. When `False`, values/keys are not percent-encoded (joined as-is)."""
 
     encode_dot_in_keys: bool = field(default=None)  # type: ignore [assignment]
     """When `True`, encode dots in keys literally. With `encode_values_only=True`, only key dots are encoded while values remain untouched."""
@@ -64,7 +64,7 @@ class EncodeOptions:
     """When `True`, the encoder is applied to values only; keys are left unencoded."""
 
     format: Format = Format.RFC3986
-    """Space handling and percent‑encoding style. `RFC3986` encodes spaces as `%20`, while
+    """Space handling and percent-encoding style. `RFC3986` encodes spaces as `%20`, while
     `RFC1738` uses `+`."""
 
     filter: t.Optional[t.Union[t.Callable, t.Sequence[t.Union[str, int]]]] = field(default=None)
@@ -86,7 +86,7 @@ class EncodeOptions:
     )
     """Custom scalar encoder. Signature: `(value, charset|None, format|None) -> str`.
     Note: when `encode=False`, this is bypassed and values are joined without
-    percent‑encoding."""
+    percent-encoding."""
 
     _encoder: t.Callable[[t.Any, t.Optional[Charset], t.Optional[Format]], str] = field(init=False, repr=False)
 
@@ -97,18 +97,30 @@ def encoder(self) -> t.Callable[[t.Any, t.Optional[Charset], t.Optional[Format]]
         The returned callable has signature `(value) -> str` and internally calls the
         underlying `_encoder(value, self.charset, self.format)`.
         """
-        return lambda v, c=self.charset, f=self.format: self._encoder(v, c, f)  # type: ignore [misc]
+        raw_encoder = self._encoder
+        charset = self.charset
+        format_ = self.format
+
+        def bound_encoder(
+            value: t.Any,
+            c: t.Optional[Charset] = charset,
+            f: t.Optional[Format] = format_,
+            _encoder: t.Callable[[t.Any, t.Optional[Charset], t.Optional[Format]], str] = raw_encoder,
+        ) -> str:
+            return _encoder(value, c, f)
+
+        return bound_encoder
 
     @encoder.setter
     def encoder(self, value: t.Optional[t.Callable[[t.Any, t.Optional[Charset], t.Optional[Format]], str]]) -> None:
-        """Set the underlying encoder, falling back to `EncodeUtils.encode` when `None` or non‑callable."""
+        """Set the underlying encoder, falling back to `EncodeUtils.encode` when `None` or non-callable."""
         self._encoder = value if callable(value) else EncodeUtils.encode
 
     strict_null_handling: bool = False
     """When `True`, distinguish empty strings from `None`: `None` → `a` (no `=`), empty string → `a=`."""
 
     comma_round_trip: t.Optional[bool] = None
-    """Only used with `ListFormat.COMMA`. When `True`, single‑item lists append `[]` so they round‑trip back to a list on decode."""
+    """Only used with `ListFormat.COMMA`. When `True`, single-item lists append `[]` so they round-trip back to a list on decode."""
 
     comma_compact_nulls: bool = False
     """Only with `ListFormat.COMMA`. When `True`, omit `None` entries inside lists instead of emitting empty positions
@@ -127,7 +139,7 @@ def encoder(self, value: t.Optional[t.Callable[[t.Any, t.Optional[Charset], t.Op
     def __post_init__(self) -> None:
         """Normalize interdependent options.
 
-        - If `allow_dots` is `None`, mirror `encode_dot_in_keys` (treating non‑`True` as `False`).
+        - If `allow_dots` is `None`, mirror `encode_dot_in_keys` (treating non-`True` as `False`).
         - Default `encode_dot_in_keys` to `False` when unset.
         - Map deprecated `indices` to `list_format` for backward compatibility.
         """
@@ -146,20 +158,14 @@ def __post_init__(self) -> None:
             self.list_format = ListFormat.INDICES if self.indices else ListFormat.REPEAT
 
     def __eq__(self, other: object) -> bool:
-        """Structural equality that treats the bound encoder consistently.
-
-        `dataclasses.asdict` would serialize the `encoder` property (a lambda bound to
-        charset/format) differently on each instance. To compare meaningfully, we swap in
-        `_encoder` (the raw callable) on both sides before comparing dictionaries.
-        """
+        """Structural equality that ignores the property wrapper for `encoder`."""
         if not isinstance(other, EncodeOptions):
             return False
 
         for f in fields(EncodeOptions):
             name = f.name
             if name == "encoder":
-                v1 = self._encoder
-                v2 = other._encoder
+                continue
             else:
                 v1 = getattr(self, name)
                 v2 = getattr(other, name)

src/qs_codec/models/encode_options.py

@@ -14,6 +14,8 @@ class KeyPathNode:
     path semantics.
     """
 
+    _MATERIALIZE_CACHE_NODE_LIMIT: t.ClassVar[int] = 8
+
     __slots__ = ("depth", "dot_encoded", "materialized", "parent", "segment")
     parent: t.Optional["KeyPathNode"]
     segment: str
@@ -87,14 +89,49 @@ def materialize(self) -> str:
             self.materialized = value
             return value
 
-        parts = [""] * self.depth
-        node: t.Optional["KeyPathNode"] = self
-        index = self.depth - 1
-        while node is not None:
-            parts[index] = node.segment
-            node = node.parent
-            index -= 1
+        suffix_nodes: t.List["KeyPathNode"] = []
+        current: t.Optional["KeyPathNode"] = self
+        base = ""
+        while current is not None:
+            cached_current = current.materialized
+            if cached_current is not None:
+                base = cached_current
+                break
+            suffix_nodes.append(current)
+            current = current.parent
+
+        suffix_count = len(suffix_nodes)
+        prefix_lengths: t.List[int] = [0] * suffix_count
+        parts: t.List[str] = [base] if base else []
+        prefix_length = len(base)
+        forward_index = 0
+        for index in range(suffix_count - 1, -1, -1):
+            node = suffix_nodes[index]
+            parts.append(node.segment)
+            prefix_length += len(node.segment)
+            prefix_lengths[forward_index] = prefix_length
+            forward_index += 1
 
         value = "".join(parts)
         self.materialized = value
-        return value
+
+        def cache_forward_index(index: int) -> None:
+            node = suffix_nodes[suffix_count - 1 - index]
+            if node.materialized is None:
+                node.materialized = value[: prefix_lengths[index]]
+
+        # `self.materialized` is already populated above, so count the leaf
+        # toward the cache budget without performing a redundant write.
+        cached_nodes = 1
+
+        if suffix_count > 1 and cached_nodes < self._MATERIALIZE_CACHE_NODE_LIMIT:
+            cache_forward_index(0)
+            cached_nodes += 1
+
+        for index in range(suffix_count - 2, 0, -1):
+            if cached_nodes >= self._MATERIALIZE_CACHE_NODE_LIMIT:
+                break
+            cache_forward_index(index)
+            cached_nodes += 1
+
+        return self.materialized if self.materialized is not None else value

src/qs_codec/models/key_path_node.py

@@ -1,10 +1,10 @@
-"""Utilities for decoding percent‑encoded query strings and splitting composite keys into bracketed path segments.
+"""Utilities for decoding percent-encoded query strings and splitting composite keys into bracketed path segments.
 
 This mirrors the semantics of the Node `qs` library:
 
-- Decoding handles both UTF‑8 and Latin‑1 code paths.
+- Decoding handles both UTF-8 and Latin-1 code paths.
 - Key splitting keeps bracket groups *balanced* and optionally treats dots as path separators when ``allow_dots=True``.
-- Top‑level dot splitting uses a character‑scanner that handles degenerate cases (leading '.' starts a bracket segment; '.[' is skipped; double dots preserve the first; trailing '.' is preserved) and never treats literal percent‑encoded sequences (e.g., '%2E') as split points; only actual '.' characters at depth 0 are split.
+- Top-level dot splitting uses a character-scanner that handles degenerate cases (leading '.' starts a bracket segment; '.[' is skipped; double dots preserve the first; trailing '.' is preserved) and never treats literal percent-encoded sequences (e.g., '%2E') as split points; only actual '.' characters at depth 0 are split.
 """
 
 import re
@@ -22,7 +22,7 @@ class DecodeUtils:
     the compiled regular expressions are created once per interpreter session.
     """
 
-    # Matches either a 16‑bit JavaScript-style %uXXXX sequence or a single‑byte
+    # Matches either a 16-bit JavaScript-style %uXXXX sequence or a single-byte
     # %XX sequence. Used by `unescape` to emulate legacy browser behavior.
     UNESCAPE_PATTERN: t.Pattern[str] = re.compile(
         r"%u(?P<unicode>[0-9A-Fa-f]{4})|%(?P<hex>[0-9A-Fa-f]{2})",
@@ -136,8 +136,8 @@ def unescape(cls, string: str) -> str:
 
         Replaces both ``%XX`` and ``%uXXXX`` escape sequences with the
         corresponding code points. This function is intentionally permissive
-        and does not validate UTF‑8; it is used to model historical behavior
-        in Latin‑1 mode.
+        and does not validate UTF-8; it is used to model historical behavior
+        in Latin-1 mode.
 
         Examples
         --------
@@ -166,7 +166,7 @@ def decode(
         charset: t.Optional[Charset] = Charset.UTF8,
         kind: DecodeKind = DecodeKind.VALUE,  # pylint: disable=unused-argument
     ) -> t.Optional[str]:
-        """Decode a URL‑encoded scalar.
+        """Decode a URL-encoded scalar.
 
         Notes
         -----
@@ -176,9 +176,9 @@ def decode(
 
         Behavior:
         - Replace ``+`` with a literal space *before* decoding.
-        - If ``charset`` is :data:`~qs_codec.enums.charset.Charset.LATIN1`, decode only ``%XX`` byte sequences (no ``%uXXXX``). ``%uXXXX`` sequences are left as‑is to mimic older browser/JS behavior.
-        - Otherwise (UTF‑8), defer to :func:`urllib.parse.unquote`.
-        - Keys and values are decoded identically; whether a literal ``.`` acts as a key separator is decided later by the key‑splitting logic.
+        - If ``charset`` is :data:`~qs_codec.enums.charset.Charset.LATIN1`, decode only ``%XX`` byte sequences (no ``%uXXXX``). ``%uXXXX`` sequences are left as-is to mimic older browser/JS behavior.
+        - Otherwise (UTF-8), defer to :func:`urllib.parse.unquote`.
+        - Keys and values are decoded identically; whether a literal ``.`` acts as a key separator is decided later by the key-splitting logic.
 
         Returns
         -------
@@ -212,8 +212,8 @@ def split_key_into_segments(
     ) -> t.List[str]:
         """Split a composite key into *balanced* bracket segments.
 
-        - If ``allow_dots`` is True, convert **top‑level** dots to bracket groups using a character‑scanner (``a.b[c]`` → ``a[b][c]``), preserving dots inside brackets and degenerate cases.
-        - The *parent* (non‑bracket) prefix becomes the first segment, e.g. ``"a[b][c]"`` → ``["a", "[b]", "[c]"]``.
+        - If ``allow_dots`` is True, convert **top-level** dots to bracket groups using a character-scanner (``a.b[c]`` → ``a[b][c]``), preserving dots inside brackets and degenerate cases.
+        - The *parent* (non-bracket) prefix becomes the first segment, e.g. ``"a[b][c]"`` → ``["a", "[b]", "[c]"]``.
         - Bracket groups are *balanced* using a counter so nested brackets within a single group (e.g. ``"[with[inner]]"``) are treated as one segment.
         - When ``max_depth <= 0``, no splitting occurs; the key is returned as a single segment (qs semantics).
         - If there are more groups beyond ``max_depth`` and ``strict_depth`` is True, an ``IndexError`` is raised. Otherwise, the remainder is added as one final segment (again mirroring qs).