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

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

@@ -1,3 +1,9 @@
+## 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qs-codec
-Version: 1.5.1
+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/

{qs_codec-1.5.1 → 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.1"
+__version__ = "1.5.2"
 
 # Public API surface re-exported at the package root.
 __all__ = [

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

@@ -73,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
@@ -96,7 +96,9 @@ def decode(
     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)
 
@@ -142,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:
@@ -167,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,
@@ -190,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)
@@ -346,23 +348,22 @@ def _parse_query_string_values(value: str, options: DecodeOptions) -> t.Dict[str
 
     # 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 = pos != -1 and "[]=" in part
+        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 = ""
-        list_limit_exceeded = False
+        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:
@@ -453,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.
@@ -481,12 +482,12 @@ 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])
 
-    bracket_array_comma_value = (
+    bracket_array_comma_value: bool = (
         not values_parsed
         and bool(chain)
         and chain[-1] == "[]"
         and isinstance(val, str)
-        and val
+        and bool(val)
         and options.comma
         and "," in val
     )

{qs_codec-1.5.1 → qs_codec-1.5.2}/src/qs_codec/encode.py

@@ -64,28 +64,28 @@ def encode(value: t.Any, options: t.Optional[EncodeOptions] = None) -> str:
     if value is None:
         return ""
 
-    opts = options if options is not None else EncodeOptions()
+    opts: EncodeOptions = options if options is not None else EncodeOptions()
 
-    filter_opt = opts.filter
-    filter_is_callable = callable(filter_opt)
-    filter_is_sequence = (
+    filter_opt: t.Optional[t.Union[t.Callable, t.Sequence[t.Union[str, int]]]] = opts.filter
+    filter_is_callable: bool = callable(filter_opt)
+    filter_is_sequence: bool = (
         filter_opt is not None
         and isinstance(filter_opt, ABCSequence)
         and not isinstance(filter_opt, (str, bytes, bytearray))
     )
-    list_format = opts.list_format
-    sort_opt = opts.sort if callable(opts.sort) else None
-    encoder = opts.encoder if opts.encode else None
-    formatter = opts.format.formatter
+    list_format: ListFormat = opts.list_format
+    sort_opt: t.Optional[t.Callable[[t.Any, t.Any], int]] = opts.sort if callable(opts.sort) else None
+    encoder: t.Optional[t.Callable[[t.Any, t.Optional[Charset], t.Optional[Format]], str]] = (
+        opts.encoder if opts.encode else None
+    )
+    formatter: t.Optional[t.Callable[[str], str]] = opts.format.formatter
 
     # Normalize the root into a mapping we can traverse deterministically:
     # - Mapping  -> shallow copy (deep-copy only when a callable filter may mutate)
     # - Sequence -> optionally deep-copy for callable filters, then promote to {"0": v0, "1": v1, ...}
     # - Other    -> empty (encodes to "")
     obj: t.Mapping[str, t.Any]
-    if isinstance(value, dict):
-        obj = deepcopy(value) if filter_is_callable else dict(value)
-    elif isinstance(value, ABCMapping):
+    if isinstance(value, ABCMapping):
         obj = deepcopy(value) if filter_is_callable else dict(value)
     elif isinstance(value, (list, tuple)):
         sequence = deepcopy(value) if filter_is_callable else value
@@ -123,17 +123,17 @@ def encode(value: t.Any, options: t.Optional[EncodeOptions] = None) -> str:
 
     # Side channel seed for legacy `_encode` compatibility (and cycle-state bootstrap when provided).
     side_channel: WeakKeyDictionary = WeakKeyDictionary()
-    max_depth = _get_max_encode_depth(opts.max_depth)
+    max_depth: int = _get_max_encode_depth(opts.max_depth)
 
     # Encode each selected root key.
-    missing = _MISSING
+    missing: t.Any = _MISSING
     for _key in obj_keys:
         if not isinstance(_key, str):
             # Skip non-string keys; parity with ports that stringify key paths.
             continue
 
-        obj_value = obj.get(_key, missing)
-        key_is_undefined = obj_value is missing
+        obj_value: t.Any = obj.get(_key, missing)
+        key_is_undefined: bool = obj_value is missing
 
         # Optionally drop explicit nulls at the root.
         if opts.skip_nulls and obj_value is None:
@@ -232,12 +232,12 @@ def _bootstrap_cycle_state_from_side_channel(side_channel: WeakKeyDictionary) ->
         from the current frame to the top-most side-channel mapping.
     """
     chain: t.List[WeakKeyDictionary] = []
-    tmp_sc = side_channel.get(_sentinel)
+    tmp_sc: t.Any = side_channel.get(_sentinel)
     while isinstance(tmp_sc, WeakKeyDictionary):
         chain.append(tmp_sc)
         tmp_sc = tmp_sc.get(_sentinel)  # type: ignore[assignment]
 
-    state = CycleState()
+    state: CycleState = CycleState()
     for level, ancestor in enumerate(reversed(chain)):
         is_top = ancestor.get(_sentinel) is None
         for key, pos in ancestor.items():
@@ -257,8 +257,8 @@ def _compute_step_and_check_cycle(state: CycleState, node_key: t.Any, current_le
       * raise when ancestor_pos == distance
       * return 0 when no match or when nearest match is the top-most side-channel
     """
-    key_id = node_key if isinstance(node_key, int) else _identity_key(node_key)
-    entries = state.entries.get(key_id)
+    key_id: int = node_key if isinstance(node_key, int) else _identity_key(node_key)
+    entries: t.Optional[t.List[t.Tuple[int, int, bool]]] = state.entries.get(key_id)
     if not entries:
         return 0
 
@@ -271,13 +271,13 @@ def _compute_step_and_check_cycle(state: CycleState, node_key: t.Any, current_le
 
 
 def _push_current_node(state: CycleState, node_key: t.Any, current_level: int, pos: int, is_top: bool) -> None:
-    key_id = node_key if isinstance(node_key, int) else _identity_key(node_key)
+    key_id: int = node_key if isinstance(node_key, int) else _identity_key(node_key)
     state.entries.setdefault(key_id, []).append((current_level, pos, is_top))
 
 
 def _pop_current_node(state: CycleState, node_key: t.Any) -> None:
-    key_id = node_key if isinstance(node_key, int) else _identity_key(node_key)
-    entries = state.entries.get(key_id)
+    key_id: int = node_key if isinstance(node_key, int) else _identity_key(node_key)
+    entries: t.Optional[t.List[t.Tuple[int, int, bool]]] = state.entries.get(key_id)
     if not entries:
         return
 
@@ -286,10 +286,10 @@ def _pop_current_node(state: CycleState, node_key: t.Any) -> None:
         del state.entries[key_id]
 
 
-_INDICES_GENERATOR = ListFormat.INDICES.generator
-_BRACKETS_GENERATOR = ListFormat.BRACKETS.generator
-_REPEAT_GENERATOR = ListFormat.REPEAT.generator
-_COMMA_GENERATOR = ListFormat.COMMA.generator
+_INDICES_GENERATOR: t.Callable[[str, t.Optional[str]], str] = ListFormat.INDICES.generator
+_BRACKETS_GENERATOR: t.Callable[[str, t.Optional[str]], str] = ListFormat.BRACKETS.generator
+_REPEAT_GENERATOR: t.Callable[[str, t.Optional[str]], str] = ListFormat.REPEAT.generator
+_COMMA_GENERATOR: t.Callable[[str, t.Optional[str]], str] = ListFormat.COMMA.generator
 
 
 def _uses_legacy_cycle_state(side_channel: WeakKeyDictionary) -> bool:
@@ -380,19 +380,19 @@ def _try_encode_linear_chain_plain_dict(
     ):
         return None
 
-    current = value
+    current: t.Any = value
     if type(current) is not dict:  # pylint: disable=unidiomatic-typecheck
         return None
 
-    current_depth = _depth
-    max_depth = _get_max_encode_depth(_max_depth)
-    formatter_fn = formatter if formatter is not None else format.formatter
-    prefix_value = prefix if prefix is not None else ("?" if add_query_prefix else "")
+    current_depth: int = _depth
+    max_depth: int = _get_max_encode_depth(_max_depth)
+    formatter_fn: t.Callable[[str], str] = formatter if formatter is not None else format.formatter
+    prefix_value: str = prefix if prefix is not None else ("?" if add_query_prefix else "")
     path_parts: t.List[str] = [prefix_value]
     # Match the generic walker so bounded cyclic payloads still let `max_depth`
     # win before the eventual cycle error on the same shapes.
-    cycle_state = CycleState()
-    root_level = _depth
+    cycle_state: CycleState = CycleState()
+    root_level: int = _depth
 
     while True:
         if current_depth > max_depth:
@@ -416,11 +416,11 @@ def _try_encode_linear_chain_plain_dict(
             continue
 
         if current is None:
-            path = formatter_fn("".join(path_parts))
+            path: str = formatter_fn("".join(path_parts))
             return [f"{path}="]
 
         if current_type is bool:
-            value_str = "true" if current else "false"
+            value_str: str = "true" if current else "false"
             path = formatter_fn("".join(path_parts))
             return [f"{path}={formatter_fn(value_str)}"]
 
@@ -429,7 +429,7 @@ def _try_encode_linear_chain_plain_dict(
             return [f"{path}={formatter_fn(str(current))}"]
 
         if current_type is datetime:
-            date_value = t.cast(datetime, current)
+            date_value: datetime = t.cast(datetime, current)
             current = serialize_date(date_value) if callable(serialize_date) else date_value.isoformat()
             continue
 
@@ -489,19 +489,19 @@ def _try_encode_linear_chain(
     ):
         return None
 
-    current = value
+    current: t.Any = value
     if type(current) is not dict and not isinstance(current, ABCMapping):  # pylint: disable=unidiomatic-typecheck
         return None
 
-    current_depth = _depth
-    max_depth = _get_max_encode_depth(_max_depth)
-    formatter_fn = formatter if formatter is not None else format.formatter
-    prefix_value = prefix if prefix is not None else ("?" if add_query_prefix else "")
+    current_depth: int = _depth
+    max_depth: int = _get_max_encode_depth(_max_depth)
+    formatter_fn: t.Callable[[str], str] = formatter if formatter is not None else format.formatter
+    prefix_value: str = prefix if prefix is not None else ("?" if add_query_prefix else "")
     path_segments: t.List[str] = []
     # Match the generic walker so bounded cyclic payloads still let `max_depth`
     # win before the eventual cycle error on the same shapes.
-    cycle_state = CycleState()
-    root_level = _depth
+    cycle_state: CycleState = CycleState()
+    root_level: int = _depth
 
     while True:
         if current_depth > max_depth:
@@ -510,11 +510,11 @@ def _try_encode_linear_chain(
         current_type = type(current)
 
         if current is None:
-            path = prefix_value + "".join(path_segments)
+            path: str = prefix_value + "".join(path_segments)
             return [f"{formatter_fn(path)}="]
 
         if current_type is bool:
-            value_str = "true" if current else "false"
+            value_str: str = "true" if current else "false"
             path = prefix_value + "".join(path_segments)
             return [f"{formatter_fn(path)}={formatter_fn(value_str)}"]
 
@@ -524,7 +524,7 @@ def _try_encode_linear_chain(
             return [f"{formatter_fn(path)}={formatter_fn(value_str)}"]
 
         if current_type is datetime:
-            date_value = t.cast(datetime, current)
+            date_value: datetime = t.cast(datetime, current)
             current = serialize_date(date_value) if callable(serialize_date) else date_value.isoformat()
             continue
 
@@ -546,8 +546,8 @@ def _try_encode_linear_chain(
         else:
             return None
 
-        current_id = id(mapping)
-        step = _compute_step_and_check_cycle(cycle_state, current_id, current_depth)
+        current_id: int = id(mapping)
+        step: int = _compute_step_and_check_cycle(cycle_state, current_id, current_depth)
 
         if len(mapping) != 1:
             return None
@@ -576,8 +576,8 @@ def _next_path_for_sequence(
     if generator is _REPEAT_GENERATOR or generator is _COMMA_GENERATOR:
         return path
 
-    parent = path.materialize()
-    child = generator(parent, encoded_key)
+    parent: str = path.materialize()
+    child: str = generator(parent, encoded_key)
     if child.startswith(parent):
         return path.append(child[len(parent) :])
 
@@ -649,7 +649,7 @@ def _encode(
     Returns:
         Either a list/tuple of tokens or a single token string.
     """
-    fast_path_result = _try_encode_linear_chain_plain_dict(
+    fast_path_result: t.Optional[t.List[t.Any]] = _try_encode_linear_chain_plain_dict(
         value=value,
         is_undefined=is_undefined,
         side_channel=side_channel,
@@ -716,7 +716,7 @@ def _encode(
         if last_bracket_key == encoded_key and last_bracket_segment is not None:
             return last_bracket_segment
 
-        segment = f"[{encoded_key}]"
+        segment: str = f"[{encoded_key}]"
         last_bracket_key = encoded_key
         last_bracket_segment = segment
         return segment
@@ -779,7 +779,7 @@ def _encode(
     ]
 
     while stack:
-        frame = stack[-1]
+        frame: EncodeFrame = stack[-1]
 
         if frame.phase == PHASE_START:
             if frame.max_depth is None:
@@ -791,7 +791,7 @@ def _encode(
                 if frame.prefix is None:
                     frame.prefix = "?" if frame.add_query_prefix else ""
                 frame.path = KeyPathNode.from_materialized(frame.prefix)
-            current_path = frame.path
+            current_path: KeyPathNode = frame.path
             if current_path is None:  # pragma: no cover - internal invariant
                 raise RuntimeError("path is not initialized")  # noqa: TRY003
             if frame.comma_round_trip is None:
@@ -800,8 +800,8 @@ def _encode(
                 frame.formatter = frame.format.formatter
 
             obj: t.Any = frame.value
-            filter_opt = frame.filter_
-            filter_is_sequence = (
+            filter_opt: t.Optional[t.Union[t.Callable, t.Sequence[t.Union[str, int]]]] = frame.filter_
+            filter_is_sequence: bool = (
                 filter_opt is not None
                 and isinstance(filter_opt, ABCSequence)
                 and not isinstance(filter_opt, (str, bytes, bytearray))
@@ -820,13 +820,13 @@ def _encode(
 
             if not frame.is_undefined and obj is None:
                 if frame.strict_null_handling:
-                    key_text = current_path.materialize()
-                    key_value = (
+                    key_text: str = current_path.materialize()
+                    key_value: str = (
                         frame.encoder(key_text, frame.charset, frame.format)
                         if callable(frame.encoder) and not frame.encode_values_only
                         else key_text
                     )
-                    result_token = frame.formatter(key_value) if frame.formatter is not None else key_value
+                    result_token: str = frame.formatter(key_value) if frame.formatter is not None else key_value
                     stack.pop()
                     last_result = result_token
                     continue
@@ -863,7 +863,7 @@ def _encode(
                 last_result = []
                 continue
 
-            obj_id = id(obj)
+            obj_id: int = id(frame.obj)
             frame.obj_id = obj_id
             if use_legacy_cycle_state:
                 if frame.cycle_state is None or frame.cycle_level is None:
@@ -884,7 +884,7 @@ def _encode(
 
                 if frame.encode_values_only and callable(frame.encoder):
                     encoded_items = [frame.encoder(item, frame.charset, frame.format) for item in comma_items]
-                    obj_keys_value = ",".join("" if e is None else str(e) for e in encoded_items)
+                    obj_keys_value: str = ",".join("" if e is None else str(e) for e in encoded_items)
                 else:
                     obj_keys_value = ",".join(Utils.normalize_comma_elem(e) for e in comma_items)
 
@@ -893,20 +893,20 @@ def _encode(
                 else:
                     frame.obj_keys = [{"value": UNDEFINED}]
             elif filter_is_sequence:
-                filter_keys = t.cast(t.Sequence[t.Union[str, int]], filter_opt)
+                filter_keys: t.Sequence[t.Union[str, int]] = t.cast(t.Sequence[t.Union[str, int]], filter_opt)
                 frame.obj_keys = list(filter_keys)
             else:
                 if frame.is_mapping:
-                    keys = list(obj) if isinstance(obj, dict) else list(obj.keys())
+                    keys: t.List[t.Any] = list(obj) if isinstance(obj, dict) else list(obj.keys())
                 elif frame.is_sequence:
                     keys = list(range(len(obj)))
                 else:
                     keys = []
                 frame.obj_keys = sorted(keys, key=cmp_to_key(frame.sort)) if frame.sort is not None else keys
 
-            path_for_children = current_path.as_dot_encoded() if frame.encode_dot_in_keys else current_path
+            path_for_children: KeyPathNode = current_path.as_dot_encoded() if frame.encode_dot_in_keys else current_path
 
-            single_item_for_round_trip = False
+            single_item_for_round_trip: bool = False
             if frame.comma_round_trip and frame.is_sequence:
                 if frame.generate_array_prefix is _COMMA_GENERATOR and comma_effective_length is not None:
                     single_item_for_round_trip = comma_effective_length == 1
@@ -952,7 +952,7 @@ def _encode(
                     _push_current_node(public_cycle_state, frame.obj_id, frame.depth, frame.step, frame.depth == 0)
                 frame.cycle_pushed = True
 
-            _key = frame.obj_keys[frame.index]
+            _key: t.Any = frame.obj_keys[frame.index]
             frame.index += 1
 
             _value: t.Any
@@ -988,13 +988,15 @@ def _encode(
                 continue
 
             key_text = str(_key)
-            encoded_key = key_text.replace(".", "%2E") if frame.allow_dots and frame.encode_dot_in_keys else key_text
+            encoded_key: str = (
+                key_text.replace(".", "%2E") if frame.allow_dots and frame.encode_dot_in_keys else key_text
+            )
             if frame.path is None:  # pragma: no cover - internal invariant
                 raise RuntimeError("path is not initialized")  # noqa: TRY003
-            adjusted_path = frame.adjusted_path if frame.adjusted_path is not None else frame.path
+            adjusted_path: KeyPathNode = frame.adjusted_path if frame.adjusted_path is not None else frame.path
 
             if frame.is_sequence:
-                child_path = _next_path_for_sequence(
+                child_path: KeyPathNode = _next_path_for_sequence(
                     adjusted_path,
                     frame.generate_array_prefix,
                     encoded_key,

{qs_codec-1.5.1 → qs_codec-1.5.2}/src/qs_codec/models/encode_options.py

@@ -166,9 +166,8 @@ class EncodeOptions:
             name = f.name
             if name == "encoder":
                 continue
-            else:
-                v1 = getattr(self, name)
-                v2 = getattr(other, name)
+            v1 = getattr(self, name)
+            v2 = getattr(other, name)
             if v1 != v2:
                 return False
         return True

{qs_codec-1.5.1 → qs_codec-1.5.2}/src/qs_codec/models/weak_wrapper.py

@@ -31,9 +31,9 @@ _proxy_cache_lock = RLock()
 
 def _get_proxy(value: t.Any) -> "_Proxy":
     """Return a per-object proxy, cached by id(value)."""
-    key = id(value)
+    key: int = id(value)
     with _proxy_cache_lock:
-        proxy = _proxy_cache.get(key)
+        proxy: t.Optional[_Proxy] = _proxy_cache.get(key)
         if proxy is None:
             proxy = _Proxy(value)
             _proxy_cache[key] = proxy
@@ -54,7 +54,7 @@ class WeakWrapper:
 
     def __init__(self, value: t.Any) -> None:
         """Initialize the wrapper with a value."""
-        proxy = _get_proxy(value)
+        proxy: _Proxy = _get_proxy(value)
         # Strong edge: wrapper -> proxy
         object.__setattr__(self, "_proxy", proxy)
         # Weak edge so tests can observe GC of the proxy

{qs_codec-1.5.1 → qs_codec-1.5.2}/src/qs_codec/utils/decode_utils.py

@@ -4,7 +4,11 @@ This mirrors the semantics of the Node `qs` library:
 
 - 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
@@ -62,70 +66,70 @@ class DecodeUtils:
         """
         if "." not in s:
             return s
-        sb: t.List[str] = []
-        depth = 0
-        i = 0
-        n = len(s)
+        buffer: t.List[str] = []
+        depth: int = 0
+        i: int = 0
+        n: int = len(s)
         while i < n:
-            ch = s[i]
+            ch: str = s[i]
             if ch == "[":
                 depth += 1
-                sb.append(ch)
+                buffer.append(ch)
                 i += 1
             elif ch == "]":
                 if depth > 0:
                     depth -= 1
-                sb.append(ch)
+                buffer.append(ch)
                 i += 1
             elif ch == ".":
                 if depth == 0:
-                    has_next = i + 1 < n
-                    next_ch = s[i + 1] if has_next else "\0"
+                    has_next: bool = i + 1 < n
+                    next_ch: str = s[i + 1] if has_next else "\0"
                     if next_ch == "[":
                         # skip the dot so 'a.[b]' acts like 'a[b]'
                         i += 1
                     elif next_ch == "]":
                         # preserve ambiguous '.]' as a literal to avoid constructing '[]]'
-                        sb.append(".")
+                        buffer.append(".")
                         i += 1
                     elif i == 0:
                         # If input starts with '..', preserve the first dot like the 'a..b' case.
                         if has_next and next_ch == ".":
-                            sb.append(".")
+                            buffer.append(".")
                             i += 1
                             continue
                         # leading '.' starts a bracket segment: ".a" -> "[a]"
                         start = i + 1
-                        j = start
-                        while j < n and s[j] != "." and s[j] != "[" and s[j] != "]":
+                        j: int = start
+                        while j < n and s[j] not in ".[]":
                             j += 1
-                        sb.append("[")
-                        sb.append(s[start:j])
-                        sb.append("]")
+                        buffer.append("[")
+                        buffer.append(s[start:j])
+                        buffer.append("]")
                         i = j
                     elif (not has_next) or next_ch == ".":
                         # trailing dot, or first of a double dot
-                        sb.append(".")
+                        buffer.append(".")
                         i += 1
                     else:
                         # normal split at top level: convert a.b → a[b]
                         start = i + 1
                         j = start
-                        while j < n and s[j] != "." and s[j] != "[" and s[j] != "]":
+                        while j < n and s[j] not in ".[]":
                             j += 1
-                        sb.append("[")
-                        sb.append(s[start:j])
-                        sb.append("]")
+                        buffer.append("[")
+                        buffer.append(s[start:j])
+                        buffer.append("]")
                         i = j
                 else:
-                    sb.append(".")
+                    buffer.append(".")
                     i += 1
             else:
                 # No special handling for percent sequences here; characters are appended as-is.
                 # We never split on '%2E' at this stage.
-                sb.append(ch)
+                buffer.append(ch)
                 i += 1
-        return "".join(sb)
+        return "".join(buffer)
 
     # Precompiled pattern for %XX hex bytes (Latin-1 path fast path)
     HEX2_PATTERN: t.Pattern[str] = re.compile(r"%([0-9A-Fa-f]{2})")
@@ -153,7 +157,7 @@ class DecodeUtils:
         def replacer(match: t.Match[str]) -> str:
             if (unicode_val := match.group("unicode")) is not None:
                 return chr(int(unicode_val, 16))
-            elif (hex_val := match.group("hex")) is not None:
+            if (hex_val := match.group("hex")) is not None:
                 return chr(int(hex_val, 16))
             return match.group(0)
 
@@ -199,8 +203,7 @@ class DecodeUtils:
             _int, _chr = int, chr
             return cls.HEX2_PATTERN.sub(lambda m: _chr(_int(m.group(1), 16)), s)
 
-        s = string_without_plus
-        return s if "%" not in s else unquote(s)
+        return string_without_plus if "%" not in string_without_plus else unquote(string_without_plus)
 
     @classmethod
     def split_key_into_segments(

{qs_codec-1.5.1 → qs_codec-1.5.2}/src/qs_codec/utils/encode_utils.py

@@ -46,24 +46,28 @@ class EncodeUtils:
     ) -> str:
         """Emulate the legacy JavaScript escaping behavior.
 
-        This function operates on UTF-16 *code units* to emulate JavaScript's legacy `%uXXXX` behavior. Non-BMP code
-        points are first expanded into surrogate pairs via `_to_surrogates`, then each code unit is processed.
+        This function operates on UTF-16 *code units* to emulate JavaScript's legacy `%uXXXX` behavior.
+        Non-BMP code points are first expanded into surrogate pairs via `_to_surrogates`, then each code unit is
+        processed.
 
-        - Safe set: when `format == Format.RFC1738`, the characters `(` and `)` are additionally treated as safe. Otherwise, the RFC3986 safe set is used.
+        - Safe set: when `format == Format.RFC1738`, the characters `(` and `)` are additionally treated as safe.
+          Otherwise, the RFC3986 safe set is used.
         - ASCII characters in the safe set are emitted unchanged.
         - Code units < 256 are emitted as `%XX`.
         - Other code units are emitted as `%uXXXX`.
 
         Reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/escape
         """
-        safe_points_ascii = cls.RFC1738_SAFE_POINTS_ASCII if format == Format.RFC1738 else cls.SAFE_POINTS_ASCII
+        safe_points_ascii: t.Tuple[bool, ...] = (
+            cls.RFC1738_SAFE_POINTS_ASCII if format == Format.RFC1738 else cls.SAFE_POINTS_ASCII
+        )
         if string.isascii() and cls._all_ascii_safe(string, safe_points_ascii):
             return string
 
         if not string.isascii():
             string = cls._to_surrogates(string)
 
-        hex_table = cls.HEX_TABLE
+        hex_table: t.Tuple[str, ...] = cls.HEX_TABLE
 
         buffer: t.List[str] = []
 
@@ -112,9 +116,9 @@ class EncodeUtils:
             return ""
 
         if charset == Charset.LATIN1:
-            _pat = cls._RE_UXXXX
-            _esc = cls.escape(string, format)
-            return _pat.sub(lambda m: f"%26%23{int(m.group(1), 16)}%3B", _esc)
+            u_escape_pattern: t.Pattern[str] = cls._RE_UXXXX
+            escaped: str = cls.escape(string, format)
+            return u_escape_pattern.sub(lambda m: f"%26%23{int(m.group(1), 16)}%3B", escaped)
 
         return cls._encode_string(string, format)
 
@@ -129,20 +133,19 @@ class EncodeUtils:
         """
         if isinstance(value, bytes):
             return value.decode("utf-8")
-        elif isinstance(value, bool):
+        if isinstance(value, bool):
             return str(value).lower()
-        elif isinstance(value, str):
+        if isinstance(value, str):
             return value
-        else:
-            return str(value)
+        return str(value)
 
     @classmethod
     def _encode_string(cls, string: str, format: t.Optional[Format]) -> str:
         """Percent-encode `string` per RFC3986 or RFC1738, operating on UTF-16 code units.
 
-        We first expand non-BMP code points into surrogate pairs so that indexing and length checks are done in *code units*,
-        matching JavaScript semantics. We then walk the string with a manual index, skipping the low surrogate when we emit a
-        surrogate pair.
+        We first expand non-BMP code points into surrogate pairs so that indexing and length checks are done in
+        *code units*, matching JavaScript semantics. We then walk the string with a manual index, skipping the low
+        surrogate when we emit a surrogate pair.
         """
         safe_chars_ascii = cls.RFC1738_SAFE_CHARS_ASCII if format == Format.RFC1738 else cls.SAFE_CHARS_ASCII
         if string.isascii():
@@ -152,7 +155,7 @@ class EncodeUtils:
         else:
             s = cls._to_surrogates(string)
 
-        hex_table = cls.HEX_TABLE
+        hex_table: t.Tuple[str, ...] = cls.HEX_TABLE
         buffer: t.List[str] = []
 
         i = 0
@@ -214,48 +217,43 @@ class EncodeUtils:
         """
         if c < 0x80:  # ASCII
             return [cls.HEX_TABLE[c]]
-        elif c < 0x800:  # 2 bytes
+        if c < 0x800:  # 2 bytes
             return [
                 cls.HEX_TABLE[0xC0 | (c >> 6)],
                 cls.HEX_TABLE[0x80 | (c & 0x3F)],
             ]
-        elif c < 0xD800 or c >= 0xE000:  # 3 bytes
+        if c < 0xD800 or c >= 0xE000:  # 3 bytes
             return [
                 cls.HEX_TABLE[0xE0 | (c >> 12)],
                 cls.HEX_TABLE[0x80 | ((c >> 6) & 0x3F)],
                 cls.HEX_TABLE[0x80 | (c & 0x3F)],
             ]
-        else:
-            return cls._encode_surrogate_pair(string, i, c)
+        return cls._encode_surrogate_pair(string, i, c)
 
     @classmethod
     def _encode_surrogate_pair(cls, string: str, i: int, c: int) -> t.List[str]:
         """Encode a surrogate pair starting at `i` as a 4-byte UTF-8 sequence."""
-        buffer: t.List[str] = []
         low = ord(string[i + 1])
         c = 0x10000 + (((c & 0x3FF) << 10) | (low & 0x3FF))
-        buffer.extend(
-            [
-                cls.HEX_TABLE[0xF0 | (c >> 18)],
-                cls.HEX_TABLE[0x80 | ((c >> 12) & 0x3F)],
-                cls.HEX_TABLE[0x80 | ((c >> 6) & 0x3F)],
-                cls.HEX_TABLE[0x80 | (c & 0x3F)],
-            ],
-        )
-        return buffer
+        return [
+            cls.HEX_TABLE[0xF0 | (c >> 18)],
+            cls.HEX_TABLE[0x80 | ((c >> 12) & 0x3F)],
+            cls.HEX_TABLE[0x80 | ((c >> 6) & 0x3F)],
+            cls.HEX_TABLE[0x80 | (c & 0x3F)],
+        ]
 
     @staticmethod
     def _to_surrogates(string: str) -> str:
         """Expand non-BMP code points (code point &gt; 0xFFFF) into UTF-16 surrogate pairs.
 
         This mirrors how JavaScript strings store characters, allowing compatibility with legacy `%uXXXX` encoding paths
-        and consistent behavior with the Node `qs` implementation. If no non-BMP
-        code point is present, the original string is returned unchanged.
+        and consistent behavior with the Node `qs` implementation. If no non-BMP code point is present, the original
+        string is returned unchanged.
         """
         buffer: t.Optional[t.List[str]] = None
 
         for index, ch in enumerate(string):
-            cp = ord(ch)
+            cp: int = ord(ch)
             if cp <= 0xFFFF:
                 if buffer is not None:
                     buffer.append(ch)
@@ -266,8 +264,8 @@ class EncodeUtils:
 
             # Convert to surrogate pair.
             cp -= 0x10000
-            high = 0xD800 + (cp >> 10)
-            low = 0xDC00 + (cp & 0x3FF)
+            high: int = 0xD800 + (cp >> 10)
+            low: int = 0xDC00 + (cp & 0x3FF)
             buffer.append(chr(high))
             buffer.append(chr(low))
 

{qs_codec-1.5.1 → qs_codec-1.5.2}/src/qs_codec/utils/utils.py

@@ -38,7 +38,7 @@ def _numeric_key_pairs(mapping: t.Mapping[t.Any, t.Any]) -> t.List[t.Tuple[int,
     may overwrite earlier values when materializing numeric-keyed dicts.
     """
     pairs: t.List[t.Tuple[int, t.Any]] = []
-    for key in mapping.keys():
+    for key in mapping:
         try:
             numeric_key = int(key)
         except (TypeError, ValueError):
@@ -125,17 +125,17 @@ class Utils:
             The merged structure. May be the original `target` object when
             `source` is ``None``.
         """
-        opts = options if options is not None else DecodeOptions()
+        opts: DecodeOptions = options if options is not None else DecodeOptions()
         last_result: t.Any = None
 
         stack: t.List[_MergeFrame] = [_MergeFrame(target=target, source=source, options=opts)]
 
         while stack:
-            frame = stack[-1]
+            frame: _MergeFrame = stack[-1]
 
             if frame.phase == "start":
-                current_target = frame.target
-                current_source = frame.source
+                current_target: t.Any = frame.target
+                current_source: t.Any = frame.source
 
                 if current_source is None:
                     stack.pop()
@@ -148,24 +148,26 @@ class Utils:
                         # If the target sequence contains `Undefined`, we may need to promote it
                         # to a dict keyed by indices for stable writes.
                         if any(isinstance(el, Undefined) for el in current_target):
-                            target_: t.Dict[int, t.Any] = dict(enumerate(current_target))
+                            target_by_index: t.Dict[int, t.Any] = dict(enumerate(current_target))
 
                             if isinstance(current_source, (list, tuple)):
                                 for i, item in enumerate(current_source):
                                     if not isinstance(item, Undefined):
-                                        target_[i] = item
+                                        target_by_index[i] = item
                             else:
-                                target_[len(target_)] = current_source
+                                target_by_index[len(target_by_index)] = current_source
 
                             # When list parsing is disabled, collapse to a string-keyed dict and drop sentinels.
                             if not frame.options.parse_lists and any(
-                                isinstance(value, Undefined) for value in target_.values()
+                                isinstance(value, Undefined) for value in target_by_index.values()
                             ):
                                 result: t.Any = {
-                                    str(i): target_[i] for i in target_ if not isinstance(target_[i], Undefined)
+                                    str(i): target_by_index[i]
+                                    for i in target_by_index
+                                    if not isinstance(target_by_index[i], Undefined)
                                 }
                             else:
-                                result = [el for el in target_.values() if not isinstance(el, Undefined)]
+                                result = [el for el in target_by_index.values() if not isinstance(el, Undefined)]
                             stack.pop()
                             last_result = result
                             continue
@@ -182,7 +184,7 @@ class Utils:
                                 frame.phase = "list_iter"
                                 continue
 
-                            mutable_target = (
+                            mutable_target: t.List[t.Any] = (
                                 list(current_target) if isinstance(current_target, tuple) else current_target
                             )
                             # Mutates in-place by design for list targets to preserve merge performance.
@@ -260,16 +262,18 @@ class Utils:
                         continue
 
                     if Utils.is_overflow(current_source):
-                        source_of = t.cast(OverflowDict, current_source)
-                        sorted_pairs = sorted(_numeric_key_pairs(source_of), key=lambda item: item[0])
-                        numeric_keys = {key for _, key in sorted_pairs}
+                        source_of: OverflowDict = t.cast(OverflowDict, current_source)
+                        sorted_pairs: t.List[t.Tuple[int, t.Any]] = sorted(
+                            _numeric_key_pairs(source_of), key=lambda item: item[0]
+                        )
+                        numeric_keys: t.Set[str] = {key for _, key in sorted_pairs}
                         result = OverflowDict()
-                        offset = 0
+                        offset: int = 0
                         if not isinstance(current_target, Undefined):
                             result["0"] = current_target
                             offset = 1
                         for numeric_key, key in sorted_pairs:
-                            val = source_of[key]
+                            val: t.Any = source_of[key]
                             if not isinstance(val, Undefined):
                                 # Offset ensures target occupies index "0"; source indices shift up by 1.
                                 result[str(numeric_key + offset)] = val
@@ -283,19 +287,17 @@ class Utils:
                         continue
 
                     result_list: t.List[t.Any] = []
-                    for element in (current_target,):
-                        if not isinstance(element, Undefined):
-                            result_list.append(element)
-                    for element in (current_source,):
-                        if not isinstance(element, Undefined):
-                            result_list.append(element)
+                    if not isinstance(current_target, Undefined):
+                        result_list.append(current_target)
+                    if not isinstance(current_source, Undefined):
+                        result_list.append(current_source)
                     stack.pop()
                     last_result = result_list
                     continue
 
                 # Prepare a mutable target we can merge into; reuse dict targets for performance.
                 frame.merge_target = current_target if isinstance(current_target, dict) else dict(current_target)
-                frame.merge_existing_keys = set(frame.merge_target.keys())
+                frame.merge_existing_keys = set(frame.merge_target)
                 frame.pending_updates = {}
                 frame.source_items = list(current_source.items())
                 frame.entry_index = 0
@@ -304,7 +306,7 @@ class Utils:
                 continue
 
             if frame.phase == "map_iter":
-                merge_target = frame.merge_target
+                merge_target: t.Optional[t.MutableMapping[t.Any, t.Any]] = frame.merge_target
                 if merge_target is None:  # pragma: no cover - internal invariant
                     raise RuntimeError("merge target is not initialized")  # noqa: TRY003
 
@@ -441,7 +443,7 @@ class Utils:
         """
         i: int = len(value) - 1
         while i >= 0:
-            item = value[i]
+            item: t.Any = value[i]
             if isinstance(item, Undefined):
                 value.pop(i)
             elif isinstance(item, dict):
@@ -462,9 +464,9 @@ class Utils:
         `_dicts_are_equal` to avoid descending into the same mapping from itself.
         """
         # Snapshot keys so we can delete while iterating.
-        keys: t.List[t.Any] = list(obj.keys())
+        keys: t.List[t.Any] = list(obj)
         for key in keys:
-            val = obj[key]
+            val: t.Any = obj[key]
             if isinstance(val, Undefined):
                 obj.pop(key)
             elif isinstance(val, dict) and not Utils._dicts_are_equal(val, obj):
@@ -514,8 +516,7 @@ class Utils:
                 if not Utils._dicts_are_equal(v, d2[k], path):
                     return False
             return True
-        else:
-            return d1 == d2
+        return d1 == d2
 
     @staticmethod
     def is_overflow(obj: t.Any) -> bool:
@@ -554,11 +555,11 @@ class Utils:
         """
         if Utils.is_overflow(a):
             # a is already an OverflowDict. Append b as one value at the next numeric index.
-            orig_a = t.cast(OverflowDict, a)
-            a_copy = orig_a.__class__({k: v for k, v in orig_a.items() if not isinstance(v, Undefined)})
+            orig_a: OverflowDict = t.cast(OverflowDict, a)
+            a_copy: OverflowDict = orig_a.__class__({k: v for k, v in orig_a.items() if not isinstance(v, Undefined)})
             # Use max key + 1 to handle sparse dicts safely, rather than len(a)
-            key_pairs = _numeric_key_pairs(a_copy)
-            idx = (max(key for key, _ in key_pairs) + 1) if key_pairs else 0
+            key_pairs: t.List[t.Tuple[int, str]] = _numeric_key_pairs(a_copy)
+            idx: int = (max(key for key, _ in key_pairs) + 1) if key_pairs else 0
 
             if not isinstance(b, Undefined):
                 a_copy[str(idx)] = _copy_overflow_append_value(b)
@@ -567,17 +568,17 @@ class Utils:
         # Normal combination: flatten lists/tuples
         # Flatten a
         if isinstance(a, (list, tuple)):
-            list_a = [x for x in a if not isinstance(x, Undefined)]
+            list_a: t.List[t.Any] = [x for x in a if not isinstance(x, Undefined)]
         else:
             list_a = [a] if not isinstance(a, Undefined) else []
 
         # Flatten b, handling OverflowDict as a list source
         if isinstance(b, (list, tuple)):
-            list_b = [x for x in b if not isinstance(x, Undefined)]
+            list_b: t.List[t.Any] = [x for x in b if not isinstance(x, Undefined)]
         elif isinstance(b, CommaOverflowDict):
             list_b = [b]
         elif Utils.is_overflow(b):
-            b_of = t.cast(OverflowDict, b)
+            b_of: OverflowDict = t.cast(OverflowDict, b)
             list_b = [
                 b_of[k]
                 for _, k in sorted(_numeric_key_pairs(b_of), key=lambda item: item[0])
@@ -586,9 +587,9 @@ class Utils:
         else:
             list_b = [b] if not isinstance(b, Undefined) else []
 
-        res = [*list_a, *list_b]
+        res: t.List[t.Any] = [*list_a, *list_b]
 
-        list_limit = options.list_limit if options else DecodeOptions().list_limit
+        list_limit: int = options.list_limit if options else DecodeOptions().list_limit
         if list_limit < 0:
             return OverflowDict({str(i): x for i, x in enumerate(res)}) if res else res
         if len(res) > list_limit: