Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

flet-validation

/flet-validation

Pomaga edytować walidację kontrolek Pythona we Flet: właściwości z ograniczeniami, docstringi Raises: ValueError, sprawdzenia before_update() i reguły Annotated lub __validation_rules__.

Repozytorium
flet ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
21.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 21.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

Co robi i kiedy

Pomaga edytować walidację kontrolek Pythona we Flet: właściwości z ograniczeniami, docstringi Raises: ValueError, sprawdzenia before_update() i reguły Annotated lub __validation_rules__.

Oryginalny opis (EN)

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

Jak działa

  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
Sekcje z nagłówków SKILL.md, w oryginale · 189 linii, 925 słów
Podgląd SKILL.md
---
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.

Wersje

W bazie nie ma innych skilli o nazwie flet-validation.

Migawka bazy z 13.11.2026 · wersja paczki d9bee52f33b3 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100create-flet-control-integration-tests
    Tworzy lub aktualizuje testy integracyjne kontrolek Flet w katalogu integration_tests, w tym wizualne wzorce golden i testy zachowań interaktywnych.
  • 100flet-deprecation
    Pomaga dodawać i zmieniać deprecjacje kontrolek i API Pythona we Flet w sdk/python/packages/: pola V.deprecated, dekoratory deprecated, cykl wersji i oznaczenia w dokumentacji.
  • 100python-docstring-style
    Pisze docstringi i komentarze Pythona w stylu flashdreams: nagłówek SPDX, docstring modułu, Google-style Args/Returns/Raises, docstringi atrybutów PEP 257 i komentarze blokowe.
  • 100write-docstrings
    Pisze i sprawdza docstringi w repozytorium, gdy trzeba dodać nowe, przejrzeć istniejące albo je zmienić.
  • 86cleanup-code
    Porządkuje świeżo napisany kod Pythona: styl, martwy kod, docstringi, adnotacje typów i sprawdzenia.
  • 91nimbus-backend
    Pomaga pisać i zmieniać kod backendu Python w pluginie Girder: endpointy REST, zapytania MongoDB, dostęp i testy.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.