refactor: let the package define what the null module exports

The package __init__ is the public surface, so the helpers the SDK uses to
recognize the sentinel and replace it for JSON serialization need no
underscore to be internal: not exporting them is enough. Export NULL to pass
and Null to annotate, since generated route methods type a nullable param as
Union[T, Null].

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

Author: claude

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,7 +97,7 @@ 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.

seam/null.py

@@ -13,8 +13,6 @@
 from collections.abc import Mapping
 from typing import Any
 
-__all__ = ["NULL", "Null"]
-
 
 class Null:
     """Type of the :data:`NULL` sentinel."""
@@ -59,7 +57,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
@@ -70,7 +68,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.
@@ -82,16 +80,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}