Skip to content
Skills Library
Programming · Building & coding

flet-validation

/flet-validation

Use whenever editing validation for Python controls in sdk/python/packages/: adding/changing constrained properties, `Raises: ValueError` docstrings, `before_update()` checks, `raise ValueError`, Annotated/V rules, or __validation_rules__.

Repository
flet ↗
Licence
Apache-2.0
Last repository change
21.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use whenever editing validation for Python controls in sdk/python/packages/: adding/changing constrained properties, `Raises: ValueError` docstrings, `before_update()` checks, `raise ValueError`, Annotated/V rules, or __validation_rules__.

Original author description

Use whenever editing validation for Python controls in sdk/python/packages/: adding/changing constrained properties, `Raises: ValueError` docstrings, `before_update()` checks, `raise ValueError`, Annotated/V rules, or __validation_rules__.

How it works

  1. When To Use
  2. Source Of Truth
  3. Validation Decision Order
  4. Validation Authoring Rules
  5. Typing Style
  6. Property Docstring Style
  7. Cross-Referencing Conventions
  8. Required Test Matrix
  9. Common Pitfalls
Original SKILL.md headings · 189 lines, 925 words
SKILL.md preview
---
name: flet-validation
description: Use whenever editing validation for Python controls in sdk/python/packages/: adding/changing constrained properties, `Raises: ValueError` docstrings, `before_update()` checks, `raise ValueError`, Annotated/V rules, or __validation_rules__.
---

## 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`](../flet-deprecation/SKILL.md).

## 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.

## Property Docstring Style

When a property has validation, document it in that property’s docstring (google style).

1. Add a `Raises:` block under the property docstring.

2. Use one `ValueError` entry per logical rule, except `between(...)`.
   - For `V.between(a, b)`, use one entry:
     `ValueError: If it is not between \`a\` and \`b\`, inclusive.`

3. Start each entry with `If it ...`, where 'it' refers to the property name.

4. Use canonical wording from validation helper docstrings.
   - The source of truth is
     `sdk/python/packages/flet/src/flet/utils/validation.py`.
   - Each `V.*` helper includes `Property docstring Raises wording`.
   - Keep property `Raises` entries as negations of the annotation rule.
   - For strict inequalities, say `"strictly"`.
     For example: `V.gt(x)` -> `ValueError: If it is not strictly greater than \`x\`.`
   - For sign-neutral divisibility helpers (`factor_of`, `multiple_of`), add
     explicit sign rules (`V.gt(0)` or `V.lt(0)`) when direction matters, and
     include separate `Raises` entries for those sign rules.

5. Mention conditional applicability when needed.
   - Example (for `min`/`max` checks against optional `value`):
     ```
     Raises:
         ValueError: If it is not less than or equal to [`value`][(c).],
             when [`value`][(c).] is set.
     ```

6. Keep examples and wording aligned with real control files.
   - Prefer concrete property names such as `min`, `max`, `value`,
     `start_value`, `end_value`, `min_lines`, `max_lines`.
   - For cross-field rules, use same-class links: [`min`][(c).], [`max`][(c).].

## Cross-Referencing Conventions

Follow the cross-reference guidance in:
[`docs-conventions`](../docs-conventions/SKILL.md).

Most common pattern to use in control property docstrings:
- same-class properties: `[\`prop\`][(c).]`

Keep symbol labels wrapped in backticks.

## Required Test Matrix

When adding/changing validation, include tests that cover:
- one valid case and one invalid case per new logical rule;
- boundary values (`==`, min/max edges) where applicable;
- cross-field set/unset combinations when optional values are involved;
- effective-default behavior when Dart applies defaults but Python value is
  omitted.

Prefer placing tests in:
- `sdk/python/packages/flet/tests/test_validation.py` for validation runtime;
- control-specific tests when behavior is tied to one control.

## Common Pitfalls

- Keeping stale manual `before_update()` validations after migration.
- Missing `Raises` entries on validated properties.
- Combining multiple non-between rules into one ambiguous `ValueError` sentence.
- Forgetting Dart defaults that still apply when Python property is omitted.
- Forcing complex `V.ensure(lambda ...)` expressions when `before_update()` would be cleaner.

Versions

The database has no other skills named flet-validation.

Database snapshot: 13.11.2026 · package version d9bee52f33b3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100create-flet-control-integration-tests
    Use when asked to create or update integration tests for any Flet control in sdk/python/packages/flet/integration_tests, including visual goldens and interactive behavior tests.
  • 100flet-deprecation
    Use when adding or changing deprecations for Python controls/APIs in sdk/python/packages/, including V.deprecated fields, deprecated decorators, version lifecycle, and docs admonitions/labels.
  • 100python-docstring-style
    Write Python docstrings and inline comments matching the flashdreams house style — SPDX header, one-line module docstring, Google-style function docstrings (Args/Returns/Raises), PEP 257 attribute docstrings on dataclass/class fields *and on module-level constants*,…
  • 100write-docstrings
    Writes and reviews docstrings in this repo. Use when writing new docstrings, reviewing existing docstrings, or editing docstrings.
  • 86cleanup-code
    Polishes recently written or modified Python code for style, dead code, docstrings, type annotations, and checks. Use when coding task is completed.
  • 91nimbus-backend
    Use when writing or modifying Python code in the Girder backend plugin (devops/girder/plugins/AnnotationPlugin/), creating REST API endpoints, writing database queries with MongoDB, implementing access control and sharing, running backend tests with tox/pytest, or debugging…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.