💡 reformat and condense docstrings for improved readability across modules

Author: techouse

docs/index.rst

@@ -11,7 +11,7 @@ A query string encoding and decoding library for Python.
 Ported from `qs <https://www.npmjs.com/package/qs>`__ for JavaScript.
 
 |PyPI - Version| |PyPI - Downloads| |PyPI - Status| |PyPI - Python Version| |PyPI - Format| |Black|
-|Test| |CodeQL| |Publish| |Docs| |codecov| |Codacy| |Black| |flake8| |mypy| |pylint| |isort| |bandit|
+|Test| |CodeQL| |Publish| |Docs| |codecov| |Codacy| |flake8| |mypy| |pylint| |isort| |bandit|
 |License| |Contributor Covenant| |GitHub Sponsors| |GitHub Repo stars|
 
 Usage

docs/qs_codec.rst

@@ -21,6 +21,7 @@ qs\_codec.decode module
    :members:
    :undoc-members:
    :show-inheritance:
+   :noindex:
 
 qs\_codec.encode module
 -----------------------
@@ -29,6 +30,7 @@ qs\_codec.encode module
    :members:
    :undoc-members:
    :show-inheritance:
+   :noindex:
 
 Module contents
 ---------------

docs/qs_codec.utils.rst

@@ -20,14 +20,6 @@ qs\_codec.utils.encode\_utils module
    :undoc-members:
    :show-inheritance:
 
-qs\_codec.utils.str\_utils module
----------------------------------
-
-.. automodule:: qs_codec.utils.str_utils
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 qs\_codec.utils.utils module
 ----------------------------
 

src/qs_codec/__init__.py

@@ -1,5 +1,5 @@
 """
-qs_codec — Query string encoding/decoding for Python.
+Query string encoding/decoding for Python.
 
 This package is a Python port of the popular `qs` library for JavaScript/Node.js.
 It strives to match `qs` semantics and edge cases — including list/array formats,

src/qs_codec/decode.py

@@ -38,8 +38,7 @@ def decode(
         Either a raw query string (``str``) or an already-parsed mapping (``Mapping[str, Any]``).
         Passing a mapping is useful in tests or when a custom tokenizer is used upstream.
     options:
-        ``DecodeOptions`` controlling delimiter, duplicates policy, list & depth limits,
-        dot-notation, decoding charset, and more.
+        ``DecodeOptions`` controlling delimiter, duplicates policy, list & depth limits, dot-notation, decoding charset, and more.
 
     Returns
     -------
@@ -49,15 +48,12 @@ def decode(
     Raises
     ------
     ValueError
-        If ``value`` is neither ``str`` nor ``Mapping``, or when limits are violated under
-        ``raise_on_limit_exceeded=True``.
+        If ``value`` is neither ``str`` nor ``Mapping``, or when limits are violated under ``raise_on_limit_exceeded=True``.
 
     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.
+    - 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.
     """
     obj: t.Dict[str, t.Any] = {}
 
@@ -120,8 +116,7 @@ def _parse_array_value(value: t.Any, options: DecodeOptions, current_list_length
     Behavior
     --------
     - If `comma=True` and `value` is a string that contains commas, split into a list.
-    - Otherwise, enforce the per-list length limit by comparing `current_list_length` to
-      `options.list_limit`. When `raise_on_limit_exceeded=True`, violations raise `ValueError`.
+    - Otherwise, enforce the per-list length limit by comparing `current_list_length` to `options.list_limit`. When `raise_on_limit_exceeded=True`, violations raise `ValueError`.
 
     Returns either the original value or a list of values, without decoding (that happens later).
     """
@@ -158,8 +153,7 @@ def _parse_query_string_values(value: str, options: DecodeOptions) -> t.Dict[str
         * Handle empty brackets ``[]`` as list markers.
         * Merge duplicate keys according to ``duplicates`` policy.
 
-    The output is a *flat* dict (keys are full key-path strings). Higher-level structure is
-    constructed later by ``_parse_keys`` / ``_parse_object``.
+    The output is a *flat* dict (keys are full key-path strings). Higher-level structure is constructed later by ``_parse_keys`` / ``_parse_object``.
     """
     obj: t.Dict[str, t.Any] = {}
 
@@ -274,8 +268,7 @@ def _parse_object(
     -----
     - Builds lists when encountering ``[]`` (respecting ``allow_empty_lists`` and null handling).
     - Converts bracketed numeric segments into list indices when allowed and within ``list_limit``.
-    - When list parsing is disabled and an empty segment is encountered, coerces to ``{"0": leaf}``
-      to preserve round-trippability with other ports.
+    - When list parsing is disabled and an empty segment is encountered, coerces to ``{"0": leaf}`` to preserve round-trippability with other ports.
     """
     current_list_length: int = 0
 

src/qs_codec/encode.py

@@ -1,19 +1,16 @@
 """Query‑string *encoder* (stringifier).
 
-This module converts Python mappings and sequences into a percent‑encoded
-query string with feature parity to the Node.js `qs` package where it makes
-sense for Python. It supports:
+This module converts Python mappings and sequences into a percent‑encoded query string with feature parity to the
+Node.js `qs` package where it makes sense for Python. It supports:
 
 - Stable, deterministic key ordering with an optional custom comparator.
-- Multiple list encodings (indices, brackets, repeat key, comma) including the
-  "comma round‑trip" behavior to preserve single‑element lists.
+- Multiple list encodings (indices, brackets, repeat key, comma) including the "comma round‑trip" behavior to preserve single‑element lists.
 - Custom per‑scalar encoder and `datetime` serializer hooks.
 - RFC 3986 vs RFC 1738 formatting and optional charset sentinels.
 - Dots vs brackets in key paths (`allow_dots`, `encode_dot_in_keys`).
 - Strict/null handling, empty‑list emission, and cycle detection.
 
-Nothing in this module mutates caller objects: inputs are shallow‑normalized
-and deep‑copied only where safe/necessary to honor options.
+Nothing in this module mutates caller objects: inputs are shallow‑normalized and deep‑copied only where safe/necessary to honor options.
 """
 
 import typing as t
@@ -44,14 +41,12 @@ def encode(value: t.Any, options: EncodeOptions = EncodeOptions()) -> str:
         options: Encoding behavior (parity with the Node.js `qs` API).
 
     Returns:
-        The encoded query string (possibly prefixed with "?" if requested),
-        or an empty string when there is nothing to encode.
+        The encoded query string (possibly prefixed with "?" if requested), or an empty string when there is nothing to encode.
 
     Notes:
-        - Caller input is not mutated. When a mapping is provided it is
-          deep-copied; sequences are projected to a temporary mapping.
+        - Caller input is not mutated. When a mapping is provided it is deep-copied; sequences are projected to a temporary mapping.
         - If a callable `filter` is provided, it can transform the root object.
-          If an iterable filter is provided, it selects which *root* keys to emit.
+        - If an iterable filter is provided, it selects which *root* keys to emit.
     """
     # Treat `None` as "nothing to encode".
     if value is None:
@@ -190,8 +185,7 @@ def _encode(
       * a list/tuple of tokens (strings) to be appended to the parent list, or
       * a single token string (when a scalar is reached).
 
-    It threads a *side-channel* (a chained `WeakKeyDictionary`) through recursion
-    to detect cycles by remembering where each visited object last appeared.
+    It threads a *side-channel* (a chained `WeakKeyDictionary`) through recursion to detect cycles by remembering where each visited object last appeared.
 
     Args:
         value: Current subtree value.

src/qs_codec/models/encode_options.py

@@ -1,18 +1,14 @@
 """Configuration object for `encode`.
 
-`EncodeOptions` mirrors the behavior and defaults of the reference `qs` implementation
-(ported across Techouse repos). It controls how Python values (dicts/lists/scalars)
-are turned into a URL-encoded query string. The options here are intentionally
-close to the Node.js library so behavior is predictable across languages.
+`EncodeOptions` mirrors the behavior and defaults of the reference `qs` implementation. It controls how Python values
+(dicts/lists/scalars) are turned into a URL-encoded query string. The options here are intentionally close to the Node.js
+library so behavior is predictable across languages.
 
 Key interactions to be aware of:
-- `allow_dots` vs `encode_dot_in_keys`: when unspecified, `allow_dots` mirrors the
-  value of `encode_dot_in_keys` (see `__post_init__`).
+- `allow_dots` vs `encode_dot_in_keys`: when unspecified, `allow_dots` mirrors the value of `encode_dot_in_keys` (see `__post_init__`).
 - `indices` is deprecated and mapped to `list_format` for parity with newer ports.
-- `encoder` and `serialize_date` let you customize scalar/date serialization,
-  while `encode=False` short-circuits the encoder entirely.
-- `sort` may return -1/0/+1 (like `strcmp`/`NSComparisonResult.rawValue`) to
-  deterministically order keys.
+- `encoder` and `serialize_date` let you customize scalar/date serialization, while `encode=False` short-circuits the encoder entirely.
+- `sort` may return -1/0/+1 (like `strcmp`/`NSComparisonResult.rawValue`) to deterministically order keys.
 """
 
 import typing as t
@@ -74,7 +70,7 @@ class EncodeOptions:
     filter: t.Optional[t.Union[t.Callable, t.List[t.Union[str, int]]]] = field(default=None)
     """Restrict which keys get included.
     - If a callable is provided, it is invoked for each key and should return the
-      replacement value (or `None` to drop when `skip_nulls` applies).
+    replacement value (or `None` to drop when `skip_nulls` applies).
     - If a list is provided, only those keys/indices are retained.
     """
 

src/qs_codec/models/undefined.py

@@ -1,14 +1,13 @@
 """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`.
+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.
+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()`).
+The sentinel is identity-based: every construction returns the same instance, so `is` comparisons are reliable
+(e.g., `value is Undefined()`).
 """
 
 import typing as t
@@ -18,10 +17,8 @@ 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.
+        * 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
@@ -40,8 +37,7 @@ class Undefined:
     def __new__(cls: t.Type["Undefined"]) -> "Undefined":
         """Return the singleton instance.
 
-        Creating `Undefined()` multiple times always returns the same object
-        reference. This ensures identity checks (``is``) are stable.
+        Creating `Undefined()` multiple times always returns the same object reference. This ensures identity checks (``is``) are stable.
         """
         if cls._instance is None:
             cls._instance = super().__new__(cls)

src/qs_codec/models/weak_wrapper.py

@@ -17,8 +17,7 @@
 class _Proxy:
     """Container for the original object.
 
-    NOTE: Proxies must be weak-referenceable because the cache holds them
-    in a WeakValueDictionary. That requires "__weakref__" in __slots__.
+    NOTE: Proxies must be weak-referenceable because the cache holds them in a WeakValueDictionary. That requires "__weakref__" in __slots__.
     """
 
     __slots__ = ("value", "__weakref__")

src/qs_codec/utils/decode_utils.py

@@ -3,8 +3,7 @@
 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``.
+- Key splitting keeps bracket groups *balanced* and optionally treats dots as path separators when ``allow_dots=True``.
 """
 
 import re
@@ -68,13 +67,16 @@ def decode(
         """Decode a URL‑encoded scalar.
 
         Behavior:
-        - Always replace ``+`` with a literal space *before* decoding.
-        - For ``Charset.LATIN1``: unescape only ``%XX`` byte sequences using
-          :meth:`unescape` (to mimic older browser/JS behavior). ``%uXXXX``
-          sequences are left untouched here.
-        - For UTF‑8 (default): defer to :func:`urllib.parse.unquote`.
-
-        Returns ``None`` when the input is ``None``.
+        - Replace ``+`` with a literal space *before* decoding.
+        - If ``charset`` is :data:`~qs_codec.enums.charset.Charset.LATIN1`,
+        replace only ``%XX`` byte sequences using :meth:`DecodeUtils.unescape`.
+        ``%uXXXX`` sequences are left as‑is here to mimic older browser/JS behavior.
+        - Otherwise (UTF‑8), defer to :func:`urllib.parse.unquote`.
+
+        Returns
+        -------
+        Optional[str]
+            ``None`` when the input is ``None``.
         """
         if string is None:
             return None
@@ -103,18 +105,11 @@ def split_key_into_segments(
         """
         Split a composite key into *balanced* bracket segments.
 
-        - If ``allow_dots`` is True, convert dots to bracket groups first
-          (``a.b[c]`` → ``a[b][c]``) while leaving existing brackets intact.
-        - 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).
+        - If ``allow_dots`` is True, convert dots to bracket groups first (``a.b[c]`` → ``a[b][c]``) while leaving existing brackets intact.
+        - 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).
 
         This runs in O(n) time over the key string.
         """