"""Shared text-normalisation helpers. ``_optional_text`` was independently redefined 30 times across the codebase -- but *not* identically. Two implementations were in circulation: # 19 call sites if value is None: return None return str(value).strip() or None # 9 call sites return str(value or "").strip() or None They disagree on every falsy non-``None`` input: ``_optional_text(0)`` is ``"0"`` under the first and ``None`` under the second; likewise ``False``, ``0.0`` and ``[]``. Same name, same signature, different meaning depending on which file you happened to be reading -- the kind of duplication that is worse than the boilerplate it saves. ``optional_text`` below is the canonical form (the 19-site behaviour: only ``None`` and blank strings collapse to ``None``). The 9 divergent sites are deliberately *not* migrated here, because doing so would silently change what they accept; they need per-call-site review first. """ from __future__ import annotations from typing import Any def optional_text(value: Any) -> str | None: """Return ``value`` as trimmed text, or ``None`` when absent or blank. Only ``None`` and whitespace-only strings become ``None``. Falsy non-``None`` values such as ``0`` and ``False`` stringify normally. """ if value is None: return None text = str(value).strip() return text or None