Validation Rules

The erbsland.conf.vr package provides ELCL rule loading, a Python keyword builder and read-only rule metadata. See Validation Rules for examples.

Rules and Builder

class Rules

An immutable schema. Each validation has its own indexes and traversal state.

property root: Rule

Read-only root rule metadata.

classmethod from_document(document: Document) → Rules

Compile a parsed rules document, raising ConfValidationError for invalid definitions.

classmethod loads(text: str) → Rules

Parse and compile rules from ELCL text using the standard parser.

classmethod load(path: str | Path) → Rules

Parse and compile an ELCL rules file using the standard parser.

validate(value: Value, version: int) → None

Validate a document or section in place.

Insert defaults and attach metadata. The version must be a nonnegative integer. Raise ConfValidationError on the first failure; partial updates are possible on failure. Revalidation refreshes defaults and metadata only inside the supplied subtree.

class RulesBuilder

Build a schema with native values and ordered keyword constraints.

Declare parent rules before their children. Returned branch views share this builder. Only the original builder can build or reset; reset invalidates old branch views. Building leaves the builder available for further editing.

add_rule(path: str | Name | NamePath, type_: RuleType | Type[Any] | str, **options: Unpack[RuleOptions]) → RulesBuilder

Declare a literal named rule and return its branch view.

add_alternative(path: str | Name | NamePath, type_: RuleType | Type[Any] | str, **options: Unpack[RuleOptions]) → RulesBuilder

Append an alternative and return a view for that alternative’s children.

add_entry(type_: RuleType | Type[Any] | str, **options: Unpack[RuleOptions]) → RulesBuilder

Declare the entry rule of this list.

add_entry_alternative(type_: RuleType | Type[Any] | str, **options: Unpack[RuleOptions]) → RulesBuilder

Append an alternative entry definition for this list.

add_any(type_: RuleType | Type[Any] | str, **options: Unpack[RuleOptions]) → RulesBuilder

Declare a wildcard for otherwise unmatched child names.

add_any_alternative(type_: RuleType | Type[Any] | str, **options: Unpack[RuleOptions]) → RulesBuilder

Append an alternative for otherwise unmatched child names.

configure_name(**options: Unpack[RuleOptions]) → None

Configure text constraints on this named rule or wildcard’s names.

branch(path: str | Name | NamePath) → RulesBuilder

Return a view of an existing literal named rule.

configure_root(**options: Unpack[RuleOptions]) → None

Configure this view’s root rule, preserving existing children.

add_key(*paths: str | Name | NamePath, name: str | None = None, case_sensitive: bool = False) → None

Declare a scoped unique index; multiple paths form a composite key.

add_dependency(mode: DependencyMode | str, *, source: str | Name | NamePath | list[str | Name | NamePath] | tuple[str | Name | NamePath, ...], target: str | Name | NamePath | list[str | Name | NamePath] | tuple[str | Name | NamePath, ...], error: str = '') → None

Require a relationship between explicitly configured relative paths.

build() → Rules

Validate and return an independent immutable rules snapshot.

reset() → None

Clear the original builder and invalidate previously returned branches.

Metadata and Types

class Rule

Read-only rule metadata. Name paths are returned as independent copies.

property name_path: NamePath

Symbolic configuration path, with declaration escapes decoded.

property has_custom_error: bool

Whether a nonempty node-level error message was provided.

property default: Any

The default payload, or None if absent; sequences are immutable tuples.

property version_constraints: Mapping[str, int | tuple[int, ...]]

Read-only version restrictions, separate from value constraints.

class Constraint

A compiled constraint, in declaration order; sequences are immutable tuples.

property value: Any

The immutable operand, with independent copies of date/time wrappers.

property is_negated: bool

Whether this is the negative form of the constraint.

property kind: str

The constraint identifier without the negation prefix.

class RuleType(*values)

ELCL validation types, including collection and unrestricted types.

classmethod from_type(value: RuleType | Type[Any] | str) → RuleType

Resolve a native scalar type, enum, or ELCL type identifier.

is_scalar() → bool

Return whether this rule accepts scalar values.

matches(value_type: ValueType) → bool

Test the stored type without converting the value.

class DependencyMode(*values)

The six ELCL dependency modes.

classmethod from_text(value: str) → DependencyMode

Parse a case-insensitive ELCL mode identifier.

accepts(source: bool, target: bool) → bool

Evaluate the two presence flags.

Keyword Options

class RuleOptions

ELCL attributes as Python keywords, in evaluation order.