Flet Validation

When To Use

Use this skill when you:

• add validation to a control property,
• migrate manual before_update() checks to V rules,
• update Raises sections tied to validation,
• align Python validation with Dart-side control behavior.

Do not use this skill for unrelated doc-only edits outside control validation. Do not use this skill for deprecation authoring conventions; use flet-deprecation.

Source Of Truth

• Validation runtime API lives in: sdk/python/packages/flet/src/flet/utils/validation.py
• The same runtime can validate regular dataclass models via validate(instance); this skill focuses on the control-specific authoring conventions.
• Import from public path only: from flet.utils.validation import V and when needed from flet.utils.validation import ValidationRules

Validation Decision Order

Use this order and stop at the first option that keeps logic clear:

1. Annotated[..., V.*] field rules (default).
2. __validation_rules__: ValidationRules for cross-field invariants that do not map cleanly to one field.
3. before_update() only for normalization/mutation, or for truly non-ruleable invariants.

Never duplicate the same invariant in more than one layer.

Validation Authoring Rules

1. Prefer field-level validation with Annotated[...] metadata.

   • Example (close to current slider controls):

     @dataclass
     class Sample:
         opacity: Annotated[
                Optional[Number],
                V.between(0.0, 1.0),
            ] = None
     
         value: Annotated[
             Optional[Number],
             V.ge_field("min"),
             V.le_field("max"),
         ] = None
     
         min: Annotated[
             Number,
             V.le_field("max"),
             V.le_field("value"),
         ] = 0.0
     
         max: Annotated[
             Number,
             V.ge_field("min"),
             V.ge_field("value"),
         ] = 1.0

2. Use class-level __validation_rules__ only for invariants that cannot be expressed cleanly with field rules.

   • Type: __validation_rules__: ValidationRules = (...)
   • Use V.ensure(...) with an explicit message only when the predicate is short and readable.
   • If V.ensure(lambda ...) becomes hard to read, prefer either:
     1. a named predicate function passed to V.ensure(...), or
     2. a clear before_update() check when it cannot be represented well with existing V.* rules.

3. Keep the before_update() override for normalization/mutation first.

   • Remove validation checks duplicated by V rules.
   • Prefer raising validation errors from rule evaluation (validate()), not from ad-hoc before_update() checks, unless the invariant is genuinely non-ruleable with current validation primitives.

4. Cross-field comparisons use field rules only.

   • Use: V.gt_field, V.ge_field, V.lt_field, V.le_field

5. None handling is inferred from type hints.

   • If a field is annotated as optional (for example Optional[T]), None is allowed.
   • If a field is not optional, None fails validation.
   • For *_field comparisons, if either side is optional and currently None, the comparison is skipped; if a non-optional side is None, validation fails.

6. Match Dart effective behavior.

   • Review both:
     1. Flet Dart wrapper (packages/flet/lib/src/controls/<control>.dart or extension wrapper),
     2. wrapped Flutter widget source assertions/invariants.
   • Mirror those constraints in Python so invalid payloads fail before crossing to Dart.
   • Validate against effective defaults applied on Dart side (for example min/max).
   • Include wrapper-imposed constraints when relevant (for example bounds/rounding/division logic in wrapper formatting code).

7. For new properties, validate against base widget assertions before wiring.

   • When adding a Python property to a Flet control, confirm whether the mapped Dart wrapper and underlying widget both enforce constraints for that property.
   • Add equivalent Python-side validation (Annotated[...], __validation_rules__, or readable before_update()) to prevent Dart assertions from being the first failure point.

8. Keep error ownership clear.

   • Runtime outbound value failures should raise ValueError.
   • Validation declaration/build errors (invalid V.* arguments) should raise ValidationDeclarationError.

Typing Style

• Follow the codebase typing style:
  • prefer Optional[T] over T | None,
  • use Union[...] when needed.