PY-TYPE0002 · nullable_boolean_annotation
Find Boolean annotations that use None as a third state.
This is a deterministic rule for python. Read its implementation.
Definition
Section titled “Definition”Inspect parameter, return, variable, and type-alias annotations. Report an exact union of
bool and None, including bool | None, None | bool, Optional[bool], and
Union[bool, None]. A Boolean should represent two states. A real third state should use a
named enum or a separate presence model whose meaning is explicit.
Evidence
Section titled “Evidence”Each finding points to the nullable Boolean union. Broader JSON or scalar unions that happen to
contain both bool and None are not treated as three-state Booleans. The value is the number
of nullable Boolean annotations.
Exceptions
Section titled “Exceptions”External protocol signatures may require a nullable Boolean. Such adapters can disable the rule at that boundary while keeping the internal domain explicit.
Examples
Section titled “Examples”approved: bool | None is ambiguous because None could mean unknown, absent, or not yet
evaluated. approved: bool is two-state. status: ApprovalStatus names the third state.
References
Section titled “References”- Cites “Python typing specification”, optional types. Open reference
- Cites “Python typing specification”, enum literal states. Open reference