feat(types): add assert_given for narrowing store-mode settings reads

In store-mode settings objects, _NotGiven should never appear (the
invariant enforced by validate_complete). But the declared field types
still include _NotGiven because the same class doubles as delta mode,
so every field read is typed X | None | _NotGiven and pyright flags
operations that assume X | None.

assert_given is a one-line extractor that narrows away _NotGiven and
raises loudly if the invariant is violated — preferable to scattering
is_given guards that defend against something that can't occur in
practice.

    resolved_model = assert_given(self._settings.model)  # str | None
This commit is contained in:
Paul Kompfner
2026-04-23 16:40:07 -04:00
parent 356618b448
commit 70f3d32734

View File

@@ -117,6 +117,31 @@ def is_given(value: _T | _NotGiven) -> TypeGuard[_T]:
return not isinstance(value, _NotGiven)
def assert_given(value: _T | _NotGiven) -> _T:
"""Extract a store-mode settings field, asserting it isn't ``NOT_GIVEN``.
Intended for reads from a store-mode settings object, where
``_NotGiven`` should never appear (see ``validate_complete``). Narrows
away ``_NotGiven`` at the type level and raises at runtime if the
invariant is violated::
resolved_model = assert_given(self._settings.model) # narrowed str | None
Args:
value: The store-mode field value to extract.
Returns:
The value, narrowed to exclude ``_NotGiven``.
Raises:
RuntimeError: If *value* is ``NOT_GIVEN`` (a store-mode invariant
violation).
"""
if not is_given(value):
raise RuntimeError("Store-mode settings field is NOT_GIVEN (invariant violated)")
return value
# ---------------------------------------------------------------------------
# Base ServiceSettings
# ---------------------------------------------------------------------------