Model Development Guide

This guide documents the modeling conventions of flync.core and flync.model — what makes a new class, field, or validator feel native to FLYNC. Nearly every rule here is enforced somewhere — by mypy with the pydantic plugin, by scripts/ci/check_lazy_typing.py, by the model docstring check, by the error catalog tooling, or by SonarQube — and each page names the gate that backs it, so you can tell a checked rule from a convention.

Model patterns

Anatomy of a model: base class, fields, docstrings, private attributes, typing rules.

Structure & polymorphism

How fields map to the repository layout, and how variant types are discriminated.

Validators & errors

Choosing a validator, raising cataloged errors, pinning them in tests.

Rules at a glance

  • Every model extends FLYNCBaseModel — extra="forbid" and the dump behavior come with it.

  • Every field is documented in the class docstring’s NumPy Parameters section, with a :class: cross-reference for its type and the default stated — as a ", optional" suffix or in the description. Literal tags and default_factory collections are exempt.

  • Variant types carry a Literal tag field and are referenced with Field(discriminator=...) — never branched on with if/else over dict keys.

  • Private attributes are written _name: T | None = None; PrivateAttr(default=...) is no longer used anywhere in src/.

  • New code uses PEP 604 unions (A | B, X | None) — a convention SonarQube checks, not something the tree already satisfies everywhere. Annotations are not quoted unless the name is genuinely unbound at that point, which check_lazy_typing.py does gate.

  • @model_validator(mode="after") methods return typing.Self.

  • Validation failures raise err_minor / err_major / err_fatal from flync.core.utils.exceptions with a Category and a globally unique error_number; warnings use warn and are not raised. New ids come from flync errors get-next-number, the catalog is brought in step with flync errors sync.

  • Negative tests pin the exact id with assert_single_error and assert_single_warning from tests/error_assertions.py.

Further reading in the SDK reference: Field Annotations, Error Propagation.