API — Quality¶

Status: Available in ETLantic 0.41.0 (provisional). Generated from etlantic.quality. Hub: Python API Reference.

Wire id: etlantic.quality/1. ContractModel remains the semantic authority for field and constraint meaning. This namespace owns the portable quality expression envelope used for planning and capability negotiation.

Provisional

etlantic.quality may change with migration notes in a future minor. Prefer documented helpers below; pin core to ==0.41.0 in pilots.

Behavioral contracts¶

API	Returns	Important failures / side effects
`rule_not_null` / `rule_range` / …	`QualityRule` builders	Authoring only; no I/O
`QualityRuleset` / `QualityExpression`	Envelope models	Serialize with `quality_to_dict` (`etlantic.quality/1`)
`make_quality_gate`	Gate metadata for planning	Attaches under `QUALITY_METADATA_KEY`
`analyze_quality`	`QualityAnalysis`	Capability / mapping analysis; does not execute engines
`map_rule_to_contract`	`ContractConstraintMapping`	Raises `UnmappedQualityRuleError` when no mapping exists
`evaluate_rule` / `split_by_quality`	Evaluation helpers	Engine-specific; SQL/PySpark remain fail-closed for portable quality in 0.32
`quality_from_dict` / `upgrade_quality_dict`	Codec + upgrade	Unsupported schema raises `UnsupportedQualitySchemaError`

import etlantic as etl

rule = etl.quality.rule_not_null("customer_id")
expr = etl.quality.QualityExpression(rules=[rule])
payload = etl.quality.quality_to_dict(expr)

Medallantic rules= lower onto this vocabulary — see Medallantic quality.

Generated reference¶

etlantic.quality ¶

Provisional portable quality expressions (etlantic.quality/1).

ContractModel remains the semantic authority for field and constraint meaning. This package owns the pipeline quality-expression envelope used for planning and capability negotiation.

QualityAnalysis `dataclass` ¶

QualityAnalysis(required_capabilities: frozenset[str], optional_capabilities: frozenset[str], validation_cost: int, rule_count: int, required_rule_count: int, kinds: tuple[str, ...] = (), fallback_evidence: tuple[str, ...] = ())

Plan-time analysis of a quality expression.

to_dict ¶

to_dict() -> dict[str, object]

Serialize analysis for plan metadata.

ContractConstraintMapping `dataclass` ¶

ContractConstraintMapping(field: str, nullable: bool | None = None, min_value: Any = None, max_value: Any = None, min_length: int | None = None, max_length: int | None = None, pattern: str | None = None, enum_values: list[Any] | None = None, allowed_values: list[Any] | None = None, disallowed_values: list[Any] | None = None, unique: bool = False, unique_fields: tuple[str, ...] = (), custom: tuple[dict[str, Any], ...] = (), compare_ops: tuple[dict[str, Any], ...] = ())

ContractModel-compatible constraint projection for one field.

field_constraints_dict ¶

field_constraints_dict() -> dict[str, Any]

Return a FieldConstraints-shaped mapping (ContractModel 0.2).

UnmappedQualityRuleError ¶

Bases: ValueError

Raised when a quality rule cannot map onto ContractModel surfaces.

QualityExpression `dataclass` ¶

QualityExpression(schema: str = QUALITY_SCHEMA, expression_id: str = 'quality', ruleset: QualityRuleset = QualityRuleset(), fingerprint: str | None = None, metadata: dict[str, Any] = dict())

Versioned quality-expression document (etlantic.quality/1).

to_dict ¶

to_dict() -> dict[str, Any]

Serialize the expression document.

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> QualityExpression

Deserialize an expression document (caller should upgrade first).

QualityRule `dataclass` ¶

QualityRule(kind: str, field: str, node: dict[str, Any] = field(default_factory=dict), required: bool = True, rule_id: str | None = None)

One portable quality rule attached to a field (or multi-field set).

capability ¶

capability() -> str

Return the capability vocabulary key for this rule kind.

to_dict ¶

to_dict() -> dict[str, Any]

Serialize rule to a JSON-compatible mapping.

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> QualityRule

Deserialize a rule mapping.

QualityRuleset `dataclass` ¶

QualityRuleset(rules: tuple[QualityRule, ...] = (), name: str | None = None)

Ordered collection of portable quality rules for one gate.

to_dict ¶

to_dict() -> dict[str, Any]

Serialize ruleset.

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> QualityRuleset

Deserialize a ruleset mapping.

UnsupportedQualitySchemaError ¶

Bases: ValueError

Raised when a quality expression uses an unsupported wire schema.

analyze_quality ¶

analyze_quality(expr: QualityExpression) -> QualityAnalysis

Analyze a quality expression document.

map_rule_to_contract ¶

map_rule_to_contract(rule: QualityRule) -> ContractConstraintMapping

Map a single portable rule onto ContractModel-compatible surfaces.

map_ruleset_to_contract ¶

map_ruleset_to_contract(ruleset: QualityRuleset) -> dict[str, ContractConstraintMapping]

Merge ruleset mappings by field name (later rules overlay earlier).

evaluate_rule ¶

evaluate_rule(rule: QualityRule, row: dict[str, Any]) -> str | None

Return a failure reason string, or None when the rule passes.

split_by_quality ¶

split_by_quality(records: list[Any], ruleset: QualityRuleset) -> tuple[list[Any], list[Any], list[dict[str, Any]]]

Split records into accepted/rejected using portable quality rules.

Uniqueness rules are applied after per-row checks using the first occurrence as accepted. Optional (required=False) rule failures are recorded as soft diagnostics and do not reject the row.

make_quality_gate ¶

make_quality_gate(contract_type: type[Any], ruleset: QualityRuleset, *, name: str = 'QualityGate', expression_id: str | None = None) -> type[Transformation]

Build a Transformation class that splits rows by a quality ruleset.

The class exposes result (accepted) and rejected (invalid role) outputs and stores a fingerprinted etlantic.quality/1 expression on __quality_expression__ for planning.

quality_expression_from_transform ¶

quality_expression_from_transform(transform: type[Transformation] | Any) -> dict[str, Any] | None

Return the embedded quality expression dict, if any.

rule_compare ¶

rule_compare(field: str, op: str, value: Any, *, required: bool = True, rule_id: str | None = None) -> QualityRule

Build a comparison rule (eq, ne, lt, le, gt, ge).

rule_custom_contract ¶

rule_custom_contract(name: str, *, field: str = '', expression: str | None = None, constraint_type: str | None = None, required: bool = True, rule_id: str | None = None, metadata: dict[str, Any] | None = None) -> QualityRule

Build an explicit custom-contract check.

rule_length ¶

rule_length(field: str, *, min_length: int | None = None, max_length: int | None = None, required: bool = True, rule_id: str | None = None) -> QualityRule

Build a string length rule.

rule_membership ¶

rule_membership(field: str, values: list[Any], *, allowed: bool = True, required: bool = True, rule_id: str | None = None) -> QualityRule

Build a membership (allowed/disallowed values) rule.

rule_not_null ¶

rule_not_null(field: str, *, required: bool = True, rule_id: str | None = None) -> QualityRule

Build a not_null rule.

rule_range ¶

rule_range(field: str, *, min_value: Any = None, max_value: Any = None, required: bool = True, rule_id: str | None = None) -> QualityRule

Build a numeric/string range rule.

rule_regex ¶

rule_regex(field: str, pattern: str, *, required: bool = True, rule_id: str | None = None) -> QualityRule

Build a regex/pattern rule.

rule_uniqueness ¶

rule_uniqueness(field: str, *, fields: list[str] | None = None, required: bool = True, rule_id: str | None = None) -> QualityRule

Build a uniqueness rule (single field or composite).

quality_fingerprint ¶

quality_fingerprint(expr: QualityExpression) -> str

Compute a stable SHA-256 fingerprint of the canonical expression.

quality_from_dict ¶

quality_from_dict(data: dict[str, Any], *, verify: bool = True, fingerprint: bool = True, recompute_fingerprint: bool = False) -> QualityExpression

Deserialize a quality expression, upgrading schema when needed.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	Mapping with `schema` `etlantic.quality/1`.	required
`verify`	`bool`	When True, verify embedded fingerprint if present.	`True`
`fingerprint`	`bool`	When True and fingerprint missing, compute and attach one.	`True`
`recompute_fingerprint`	`bool`	When True, always replace fingerprint with the recomputed canonical hash (plan metadata must not trust drift).	`False`

quality_to_dict ¶

quality_to_dict(expr: QualityExpression) -> dict[str, Any]

Serialize a quality expression including optional fingerprint.

verify_quality_fingerprint ¶

verify_quality_fingerprint(expr: QualityExpression) -> None

Recompute fingerprint and compare to expr.fingerprint.

upgrade_quality_dict ¶

upgrade_quality_dict(data: dict[str, Any]) -> dict[str, Any]

Upgrade a quality expression mapping to the current wire schema.

Currently only :data:QUALITY_SCHEMA (etlantic.quality/1) is accepted.

API — Quality¶

Behavioral contracts¶

Generated reference¶

etlantic.quality ¶

QualityAnalysis dataclass ¶

to_dict ¶

ContractConstraintMapping dataclass ¶

field_constraints_dict ¶

UnmappedQualityRuleError ¶

QualityExpression dataclass ¶

to_dict ¶

from_dict classmethod ¶

QualityRule dataclass ¶

capability ¶

to_dict ¶

from_dict classmethod ¶

QualityRuleset dataclass ¶

to_dict ¶

from_dict classmethod ¶

UnsupportedQualitySchemaError ¶

analyze_quality ¶

map_rule_to_contract ¶

map_ruleset_to_contract ¶

evaluate_rule ¶

split_by_quality ¶

make_quality_gate ¶

quality_expression_from_transform ¶

rule_compare ¶

rule_custom_contract ¶

rule_length ¶

rule_membership ¶

rule_not_null ¶

rule_range ¶

rule_regex ¶

rule_uniqueness ¶

quality_fingerprint ¶

quality_from_dict ¶

quality_to_dict ¶

verify_quality_fingerprint ¶

upgrade_quality_dict ¶

QualityAnalysis `dataclass` ¶

ContractConstraintMapping `dataclass` ¶

QualityExpression `dataclass` ¶

from_dict `classmethod` ¶

QualityRule `dataclass` ¶

from_dict `classmethod` ¶

QualityRuleset `dataclass` ¶

from_dict `classmethod` ¶