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__.
- Author
- flet-dev ↗
- Repository
- flet ↗
- Licence
- Apache-2.0
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
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
- When To Use
- Source Of Truth
- Validation Decision Order
- Validation Authoring Rules
- Typing Style
- Property Docstring Style
- Cross-Referencing Conventions
- Required Test Matrix
- Common Pitfalls
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…