Promote validate_positive_int_or_none to public client surface

The validator was previously exposed only as
``dqliteclient.protocol._validate_positive_int_or_none`` (leading
underscore, not in any __all__). dqlitedbapi imported it directly
across the package boundary, creating a coupling where a future
client refactor that legitimately renamed/moved the helper would
silently strand dqlitedbapi at first import — same anti-pattern that
``parse_address`` resolved by promotion.

Promote to public ``dqliteclient.validate_positive_int_or_none``,
add it to ``__all__``, and keep the leading-underscore name as a
backwards-compat alias for one release. Pin the public surface and
the alias-still-works contract.

The companion dbapi-side import is updated to consume the public
name in a separate commit; together the change closes the private-
import boundary defect.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/dqliteclient/__init__.py

@@ -23,6 +23,7 @@
 )
 from dqliteclient.node_store import MemoryNodeStore, NodeInfo, NodeStore
 from dqliteclient.pool import ConnectionPool
+from dqliteclient.protocol import validate_positive_int_or_none
 from dqlitewire import (
     DEFAULT_MAX_CONTINUATION_FRAMES as _DEFAULT_MAX_CONTINUATION_FRAMES,
 )
@@ -53,6 +54,7 @@
     "connect",
     "create_pool",
     "parse_address",
+    "validate_positive_int_or_none",
 ]
 
 

src/dqliteclient/protocol.py

@@ -79,11 +79,16 @@ def _failure_message(message: str, addr_suffix: str) -> str:
     return body + addr_suffix
 
 
-def _validate_positive_int_or_none(value: int | None, name: str) -> int | None:
+def validate_positive_int_or_none(value: int | None, name: str) -> int | None:
     """Shared validation for positive-int-or-None parameters.
 
     Used for both ``max_total_rows`` and ``max_continuation_frames``.
     None disables the cap; any int value must be > 0.
+
+    Public so downstream packages (``dqlitedbapi``, ``sqlalchemy-dqlite``)
+    can apply the same construction-time validation without reaching
+    into private symbols. Same shape as the public ``parse_address`` /
+    ``allowlist_policy`` helpers in this package.
     """
     if value is None:
         return None
@@ -94,6 +99,12 @@ def _validate_positive_int_or_none(value: int | None, name: str) -> int | None:
     return value
 
 
+# Backwards-compatibility alias for any caller that still imports the
+# leading-underscore name. Slated for removal in a future minor — the
+# public name is ``validate_positive_int_or_none``.
+_validate_positive_int_or_none = validate_positive_int_or_none
+
+
 class DqliteProtocol:
     """Low-level protocol handler for a single dqlite connection."""
 

tests/test_validate_positive_int_or_none_public.py

@@ -0,0 +1,61 @@
+"""Pin: ``dqliteclient.validate_positive_int_or_none`` is a public
+re-export so downstream packages (dqlitedbapi, sqlalchemy-dqlite) do
+not need to reach into private symbols.
+
+The validator was previously available only as
+``dqliteclient.protocol._validate_positive_int_or_none`` (leading
+underscore, not in any ``__all__``). dqlitedbapi imported it directly,
+creating a cross-package coupling that a future client refactor could
+silently break. Promote to public, mirror the ``parse_address`` /
+``allowlist_policy`` pattern, and pin the public surface so it cannot
+disappear without a breaking-change signal.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+import dqliteclient
+
+
+def test_public_validate_positive_int_or_none_callable() -> None:
+    assert callable(dqliteclient.validate_positive_int_or_none)
+
+
+def test_public_name_in_all() -> None:
+    assert "validate_positive_int_or_none" in dqliteclient.__all__
+
+
+def test_public_validator_accepts_positive_int() -> None:
+    assert dqliteclient.validate_positive_int_or_none(1, "x") == 1
+    assert dqliteclient.validate_positive_int_or_none(10**6, "x") == 10**6
+
+
+def test_public_validator_accepts_none() -> None:
+    assert dqliteclient.validate_positive_int_or_none(None, "x") is None
+
+
+def test_public_validator_rejects_zero_and_negative() -> None:
+    with pytest.raises(ValueError, match="must be > 0"):
+        dqliteclient.validate_positive_int_or_none(0, "x")
+    with pytest.raises(ValueError, match="must be > 0"):
+        dqliteclient.validate_positive_int_or_none(-1, "x")
+
+
+def test_public_validator_rejects_bool() -> None:
+    with pytest.raises(TypeError, match="must be int or None"):
+        dqliteclient.validate_positive_int_or_none(True, "x")
+
+
+def test_public_validator_rejects_non_int() -> None:
+    with pytest.raises(TypeError, match="must be int or None"):
+        dqliteclient.validate_positive_int_or_none(1.5, "x")  # type: ignore[arg-type]
+
+
+def test_legacy_underscore_alias_still_works() -> None:
+    """The leading-underscore alias is preserved for one release as a
+    deprecation cushion. Pin so a future deletion of the alias is an
+    explicit, reviewed change."""
+    from dqliteclient.protocol import _validate_positive_int_or_none
+
+    assert _validate_positive_int_or_none is dqliteclient.validate_positive_int_or_none