refactor: build search params through the URLSearchParams layer

The serialization defines the name and value of each search param, where
every value is a string, and leaves rendering the query string to
URLSearchParams. UrlSearchParams is that layer here, so hand the query it
renders to httpx as params, the way the reference implementation hands it to
axios as a paramsSerializer.

httpx re-encodes the query it is given, escaping "*" and unescaping "~", so
the earlier commit set the query on the URL to keep those bytes. That was
unnecessary: re-encoding changes no param. Across the 3141 query strings of
the randomized corpus, 1714 differ from ours in bytes and none differ in
decoded name-value pairs.

The README said to avoid a client's params for that reason, which was wrong.
Describe the pairs and the layer that renders them instead.

Narrow the null module to NULL and the Null type it instantiates. Whether a
value is the sentinel, and replacing it for JSON serialization, are internal
concerns of this SDK: a caller building their own request body writes None,
which already serializes to null.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PpqwDhZmyikGbjmCPqFW2A

Author: claude

README.rst

@@ -565,20 +565,39 @@ If you call the Seam API with your own HTTP client,
   import httpx
   from seam import serialize_url_search_params
 
-  query = serialize_url_search_params({"device_ids": ["device1", "device2"]})
-
   httpx.get(
-      f"https://connect.getseam.com/devices/list?{query}",
+      "https://connect.getseam.com/devices/list",
+      params=serialize_url_search_params({"device_ids": ["device1", "device2"]}),
       headers={"Authorization": "Bearer your-api-key"},
   )
 
-It returns a query string, so it works with any HTTP client.
-Put it on the URL as above rather than handing it to the client as params:
-clients re-encode a query string they are given, e.g. httpx escapes ``*``
-and unescapes ``~``, which this serialization does not.
+The serialization defines the name and value of each search param,
+where every value is a string.
+``UrlSearchParams`` holds those pairs and renders the query string,
+as `URLSearchParams`_ does for the `reference implementation`_:
+
+.. code-block:: python
+
+  from seam import UrlSearchParams, update_url_search_params
+
+  search_params = UrlSearchParams()
+
+  update_url_search_params(search_params, {"device_ids": ["device1", "device2"]})
+
+  list(search_params)
+  # => [('device_ids', 'device1'), ('device_ids', 'device2')]
+
+  str(search_params)
+  # => 'device_ids=device1&device_ids=device2'
+
+Pass either the query string or the pairs to your HTTP client.
+A client may percent-encode a few characters differently than
+``URLSearchParams`` does, e.g. httpx escapes ``*`` and unescapes ``~``,
+which the Seam API reads as the same params either way.
+
+The Seam API parses these params with the corresponding `parser`_.
 
-The `reference implementation`_ defines this serialization,
-and the Seam API parses it with the corresponding `parser`_.
+.. _URLSearchParams: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
 
 .. _reference implementation: https://github.com/seamapi/url-search-params-serializer
 .. _parser: https://github.com/seamapi/url-search-params-parser

seam/client.py

@@ -13,7 +13,7 @@
     SeamHttpInvalidInputError,
     SeamHttpUnauthorizedError,
 )
-from .null import replace_null
+from .null import _replace_null
 from .utils.url_search_params_serializer import serialize_url_search_params
 
 SDK_HEADERS = {
@@ -97,17 +97,14 @@ def request(self, method, url, *args, **kwargs) -> Any:
         # Route methods omit params set to None, so any remaining NULL sentinel
         # is an explicit null and becomes None for JSON serialization.
         if "json" in kwargs:
-            kwargs["json"] = replace_null(kwargs["json"])
+            kwargs["json"] = _replace_null(kwargs["json"])
 
         # Search params are serialized to the Seam API standard, which httpx
         # does not implement. The NULL sentinel is serialized to an empty value.
-        # The query is set on the URL rather than passed to httpx as params,
-        # because httpx re-encodes a query string it is given, e.g. it escapes
-        # "*" and unescapes "~", which the standard does not.
+        # httpx percent-encodes a few characters differently than the standard
+        # when it re-encodes the query, which the Seam API reads the same way.
         if isinstance(kwargs.get("params"), Mapping):
-            query = serialize_url_search_params(kwargs.pop("params"))
-            if query:
-                url = httpx.URL(url, query=query.encode())
+            kwargs["params"] = serialize_url_search_params(kwargs["params"])
 
         response = super().request(method, url, *args, **kwargs)
 

seam/null.py

@@ -13,6 +13,8 @@
 from collections.abc import Mapping
 from typing import Any
 
+__all__ = ["NULL", "Null"]
+
 
 class Null:
     """Type of the :data:`NULL` sentinel."""
@@ -57,7 +59,7 @@ def __bool__(self):
 """
 
 
-def is_null(value: Any) -> bool:
+def _is_null(value: Any) -> bool:
     """Returns whether a value is the :data:`NULL` sentinel.
 
     :param value: The value to check
@@ -68,7 +70,7 @@ def is_null(value: Any) -> bool:
     return isinstance(value, Null)
 
 
-def replace_null(value: Any) -> Any:
+def _replace_null(value: Any) -> Any:
     """Recursively replaces the :data:`NULL` sentinel with ``None``.
 
     Returns a copy, so the given value is never modified.
@@ -80,16 +82,16 @@ def replace_null(value: Any) -> Any:
 
     :returns: A copy of the value with every ``NULL`` sentinel replaced"""
 
-    if is_null(value):
+    if _is_null(value):
         return None
 
     if isinstance(value, Mapping):
-        return {key: replace_null(item) for key, item in value.items()}
+        return {key: _replace_null(item) for key, item in value.items()}
 
     if isinstance(value, list):
-        return [replace_null(item) for item in value]
+        return [_replace_null(item) for item in value]
 
     if isinstance(value, tuple):
-        return tuple(replace_null(item) for item in value)
+        return tuple(_replace_null(item) for item in value)
 
     return value

seam/utils/url_search_params_serializer.py

@@ -40,7 +40,7 @@
 from typing import Any, Iterator, List, Optional, Sequence, Tuple, Union
 from urllib.parse import parse_qsl
 
-from ..null import is_null
+from ..null import _is_null
 
 Params = Mapping[str, Any]
 
@@ -307,7 +307,7 @@ def _update_url_search_params_from_array(
             "is an array containing the empty string which is unsupported",
         )
 
-    if any(value is None or is_null(value) for value in values):
+    if any(value is None or _is_null(value) for value in values):
         raise UnserializableParamError(
             name,
             "is an array containing null or undefined values which is unsupported",
@@ -318,7 +318,7 @@ def _update_url_search_params_from_array(
 
 
 def _serialize(name: str, value: Any) -> str:
-    if is_null(value):
+    if _is_null(value):
         return ""
 
     if isinstance(value, str):

test/null_test.py

@@ -1,20 +1,20 @@
 from collections import OrderedDict
 
 from seam.client import SeamHttpClient
-from seam.null import NULL, Null, is_null, replace_null
+from seam.null import NULL, Null, _is_null, _replace_null
 
 
 def test_null_is_a_singleton():
     assert Null() is NULL
-    assert is_null(NULL)
-    assert is_null(Null())
+    assert _is_null(NULL)
+    assert _is_null(Null())
 
 
 def test_null_is_not_none():
     assert NULL is not None
-    assert not is_null(None)
-    assert not is_null("")
-    assert not is_null(0)
+    assert not _is_null(None)
+    assert not _is_null("")
+    assert not _is_null(0)
 
 
 def test_null_is_falsy():
@@ -26,40 +26,40 @@ def test_null_repr():
 
 
 def test_replace_null():
-    assert replace_null(NULL) is None
-    assert replace_null(None) is None
-    assert replace_null("a") == "a"
-    assert replace_null(0) == 0
-    assert replace_null(False) is False
+    assert _replace_null(NULL) is None
+    assert _replace_null(None) is None
+    assert _replace_null("a") == "a"
+    assert _replace_null(0) == 0
+    assert _replace_null(False) is False
 
 
 def test_replace_null_in_dict():
-    assert replace_null({"a": NULL, "b": 1, "c": None}) == {
+    assert _replace_null({"a": NULL, "b": 1, "c": None}) == {
         "a": None,
         "b": 1,
         "c": None,
     }
 
 
 def test_replace_null_in_nested_dict():
-    assert replace_null({"a": {"b": {"c": NULL}}}) == {"a": {"b": {"c": None}}}
+    assert _replace_null({"a": {"b": {"c": NULL}}}) == {"a": {"b": {"c": None}}}
 
 
 def test_replace_null_in_lists_and_tuples():
-    assert replace_null(["a", NULL]) == ["a", None]
-    assert replace_null(("a", NULL)) == ("a", None)
-    assert replace_null({"a": [{"b": NULL}]}) == {"a": [{"b": None}]}
+    assert _replace_null(["a", NULL]) == ["a", None]
+    assert _replace_null(("a", NULL)) == ("a", None)
+    assert _replace_null({"a": [{"b": NULL}]}) == {"a": [{"b": None}]}
 
 
 def test_replace_null_does_not_modify_the_given_value():
     params = {"a": NULL, "b": [NULL]}
-    replace_null(params)
+    _replace_null(params)
 
     assert params == {"a": NULL, "b": [NULL]}
 
 
 def test_replace_null_normalizes_mappings_to_dicts():
-    result = replace_null(OrderedDict([("a", NULL)]))
+    result = _replace_null(OrderedDict([("a", NULL)]))
 
     assert result == {"a": None}