feat: serialize request params with the URL search params standard

The Seam API parses URL search params as complex types, so the SDK has to
build the query string itself. Serialize any mapping passed as params and
set the result on the url, rather than letting httpx encode the params with
its own rules, which represent arrays and nested objects differently.

Replace the NULL sentinel with null in request bodies as well, so a param
set to NULL is sent as null on either transport, and document how NULL
tells an explicitly null param apart from an omitted one.

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

Author: claude

README.rst

@@ -47,6 +47,8 @@ Contents
 
   * `Action Attempts`_
 
+  * `Setting a Param to Null`_
+
   * `Pagination`_
 
     * `Manually fetch pages with the next_page_cursor`_
@@ -280,6 +282,49 @@ For example:
   except SeamActionAttemptTimeoutError as e:
       print("Door took too long to unlock")
 
+Setting a Param to Null
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The Seam API tells an omitted param apart from one explicitly set to null.
+In an update request, an omitted param leaves the current value unchanged,
+while a null param unsets it.
+
+Python has a single absence value, so this SDK spells the two apart.
+A param set to ``None`` is omitted, and a param set to ``NULL`` is sent as null:
+
+.. code-block:: python
+
+  from seam import NULL, Seam
+
+  seam = Seam()
+
+  # Leaves the name unchanged.
+  seam.devices.update(device_id="your-device-id", name=None)
+
+  # Unsets the name.
+  seam.devices.update(device_id="your-device-id", name=NULL)
+
+Because unsetting a value cannot be undone, ``None`` means the safe option of
+omitting the param, and sending null is always explicit.
+This is why a param is never sent as null by default,
+even though ``None`` is the natural way to spell null in Python.
+
+``NULL`` behaves the same way in a request body and in a URL search param.
+Its type is exported as ``Null`` for annotating your own code:
+
+.. code-block:: python
+
+  from typing import Optional, Union
+
+  from seam import NULL, Null
+
+  name: Optional[Union[str, Null]] = NULL
+
+Only use ``NULL`` where the Seam API documents null as a meaningful value,
+e.g., to unset a value in an update request.
+The generated method signatures do not yet say which params those are,
+so a type checker reports ``NULL`` as an invalid argument until they do.
+
 Pagination
 ~~~~~~~~~~
 
@@ -562,8 +607,9 @@ 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.
 
-A param set to ``None`` is omitted, while a param set to ``seam.NULL``
-is serialized to an empty value, which the Seam API reads as null.
+A param set to ``None`` is omitted, while a param set to ``NULL``
+is serialized to an empty value, which the Seam API reads as null,
+as described in `Setting a Param to Null`_.
 A param that cannot be represented raises a ``seam.UnserializableParamError``.
 
 The Seam API parses these params with the corresponding `parser`_.

seam/client.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from typing import Any, Dict, Optional
 from importlib.metadata import version
 import abc
@@ -12,6 +13,8 @@
     SeamHttpInvalidInputError,
     SeamHttpUnauthorizedError,
 )
+from .null import replace_null
+from .url_search_params_serializer import serialize_url_search_params
 
 SDK_HEADERS = {
     "seam-sdk-name": "seamapi/python",
@@ -102,6 +105,12 @@ def delete(self, url, json=None, **kwargs) -> Any:
         return self.request("DELETE", url, json=json, **kwargs)
 
     def request(self, method, url, *args, **kwargs) -> Any:
+        if isinstance(kwargs.get("params"), Mapping):
+            url = with_search_params(url, kwargs.pop("params"))
+
+        if "json" in kwargs:
+            kwargs["json"] = replace_null(kwargs["json"])
+
         response = super().request(method, url, *args, **kwargs)
 
         return self._handle_response(response)
@@ -142,6 +151,29 @@ def _handle_error_response(self, response: Response):
         raise SeamHttpApiError(error_details, status_code, request_id)
 
 
+def with_search_params(url: Any, params: Mapping[str, Any]) -> Any:
+    """Returns the url with the params serialized into its query string.
+
+    The Seam API parses URL search params as complex types, so the query
+    string is built here and set on the url as-is. Handing the params to
+    httpx instead would encode them with its own rules.
+
+    :param url: The url of the request
+    :type url: Any
+
+    :param params: The search params of the request
+    :type params: Mapping[str, Any]
+
+    :returns: The url carrying the serialized params"""
+
+    query = serialize_url_search_params(params)
+
+    if not query:
+        return url
+
+    return httpx.URL(url, query=query.encode())
+
+
 def is_api_error_response(response: Response) -> bool:
     try:
         content_type = response.headers.get("content-type", "")

seam/null.py

@@ -10,6 +10,7 @@
 Sending null is explicit and always spelled :data:`NULL`.
 """
 
+from collections.abc import Mapping, Sequence
 from typing import Any
 
 
@@ -60,3 +61,27 @@ def is_null(value: Any) -> bool:
     :returns: Whether the value is the ``NULL`` sentinel"""
 
     return isinstance(value, Null)
+
+
+def replace_null(value: Any) -> Any:
+    """Returns a copy of a value with every :data:`NULL` sentinel replaced by ``None``.
+
+    The sentinel only distinguishes an explicit null from an omitted param
+    within this SDK. Once a request body is being serialized, the param is
+    known to be present, so the sentinel becomes the null that JSON has.
+
+    :param value: The value to copy
+    :type value: Any
+
+    :returns: The value with each ``NULL`` sentinel replaced by ``None``"""
+
+    if is_null(value):
+        return None
+
+    if isinstance(value, Mapping):
+        return {key: replace_null(item) for key, item in value.items()}
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        return [replace_null(item) for item in value]
+
+    return value

test/conftest.py

@@ -62,6 +62,8 @@ def recording_server(responses):
     content type inferred from the body, e.g. to serve malformed JSON.
 
     Yields the endpoint along with the list of requests received so far.
+    Each request records the ``method``, the raw request ``target``, the
+    ``path`` and ``query`` it splits into, the ``headers``, and the ``body``.
     """
 
     requests = []
@@ -70,21 +72,17 @@ def recording_server(responses):
     class Handler(BaseHTTPRequestHandler):
         protocol_version = "HTTP/1.1"
 
-        # pylint: disable-next=invalid-name
-        def do_GET(self):
-            self._handle_request()
-
-        # pylint: disable-next=invalid-name
-        def do_POST(self):
-            self._handle_request()
-
         def _handle_request(self):
             content_length = int(self.headers.get("content-length", 0))
             raw_body = self.rfile.read(content_length)
+            path, _, query = self.path.partition("?")
 
             requests.append(
                 {
-                    "path": self.path,
+                    "method": self.command,
+                    "target": self.path,
+                    "path": path,
+                    "query": query,
                     "headers": {k.lower(): v for k, v in self.headers.items()},
                     "body": json.loads(raw_body) if raw_body else None,
                 }
@@ -112,6 +110,14 @@ def _handle_request(self):
         def log_message(self, *args):
             pass
 
+        # Every verb the SDK sends is recorded and answered the same way.
+        # pylint: disable=invalid-name
+        do_GET = _handle_request
+        do_POST = _handle_request
+        do_PUT = _handle_request
+        do_PATCH = _handle_request
+        do_DELETE = _handle_request
+
     server = ThreadingHTTPServer(("localhost", 0), Handler)
     thread = threading.Thread(target=server.serve_forever, daemon=True)
     thread.start()

test/headers_test.py

@@ -17,7 +17,8 @@ def test_seam_sends_default_headers(recording_server):
     assert len(requests) == 1
     [request] = requests
 
-    assert request["path"] == f"/devices/get?device_id={device_id}"
+    assert request["path"] == "/devices/get"
+    assert request["query"] == f"device_id={device_id}"
     assert request["body"] is None
 
     assert request["headers"]["seam-sdk-name"] == "seamapi/python"

test/null_test.py

@@ -1,4 +1,4 @@
-from seam.null import NULL, Null, is_null
+from seam.null import NULL, Null, is_null, replace_null
 
 
 def test_null_is_a_singleton():
@@ -20,3 +20,37 @@ def test_null_is_falsy():
 
 def test_null_repr():
     assert repr(NULL) == "NULL"
+
+
+def test_replace_null_replaces_the_sentinel_with_none():
+    assert replace_null(NULL) is None
+
+
+def test_replace_null_recurses_into_dicts_and_lists():
+    assert replace_null(
+        {
+            "name": NULL,
+            "properties": {"code": NULL, "kind": "lock"},
+            "codes": [NULL, "1234", [NULL]],
+            "pairs": (NULL, "1234"),
+        }
+    ) == {
+        "name": None,
+        "properties": {"code": None, "kind": "lock"},
+        "codes": [None, "1234", [None]],
+        "pairs": [None, "1234"],
+    }
+
+
+def test_replace_null_leaves_other_values_alone():
+    values = [None, "", 0, False, "NULL", {"a": 1}, ["b"]]
+
+    assert replace_null(values) == values
+
+
+def test_replace_null_does_not_mutate_its_argument():
+    body = {"name": NULL, "codes": [NULL]}
+
+    replace_null(body)
+
+    assert body == {"name": NULL, "codes": [NULL]}