Module

directives.contracts

Nesting validation contracts for directives.

Contracts define valid nesting relationships between directives, catching structural errors at parse time rather than runtime.

Thread Safety:

Contract is frozen (immutable). Safe to share across threads.

Example:

>>> STEPS_CONTRACT = DirectiveContract(
...     requires_children=("step",),
...     allows_children=("step",),
... )
>>> STEP_CONTRACT = DirectiveContract(
...     requires_parent=("steps",),
... )
2Classes

Classes

DirectiveContract 10 ▼
Validation rules for directive nesting. Use contracts to enforce structural requirements like "ste…

Validation rules for directive nesting.

Use contracts to enforce structural requirements like "step must be inside steps" or "tab-item can only contain certain content".

Violations emit warnings rather than raising exceptions, allowing graceful degradation of invalid markup.

Attributes

Name Type Description
requires_parent tuple[str, ...] | None

This directive must be inside one of these parents.
allows_parent tuple[str, ...] | None —
requires_children tuple[str, ...] | None

This directive must contain at least one of these.
allows_children tuple[str, ...] | None

Only these child directive types are allowed.
max_children int | None

Maximum number of children allowed.
forbids_children tuple[str, ...] | None

These directive types are forbidden as children.

Methods

has_parent_requirement 0 bool ▼
Check if this contract has parent requirements.
property
def has_parent_requirement(self) -> bool
Returns
bool
has_child_requirement 0 bool ▼
Check if this contract has child requirements.
property
def has_child_requirement(self) -> bool
Returns
bool
validate_parent 2 ContractViolation | None ▼
Validate that directive has required or allowed parent.
def validate_parent(self, directive_name: str, parent_name: str | None) -> ContractViolation | None
Parameters
Name Type Description
directive_name —

Name of the directive being validated
parent_name —

Name of parent directive (None if no parent)
Returns
ContractViolation | None ContractViolation if invalid, None if valid
validate_children 2 list[ContractViolation] ▼
Validate directive children against contract.
def validate_children(self, directive_name: str, children: Sequence[Directive]) -> list[ContractViolation]
Parameters
Name Type Description
directive_name —

Name of the directive being validated
children —

Sequence of child Directive nodes
Returns
list[ContractViolation] List of violations (empty if valid)
ContractViolation 6 ▼
Record of a contract violation. Contains information about what went wrong and suggestions for fix…

Record of a contract violation.

Contains information about what went wrong and suggestions for fixes.

Attributes

Name Type Description
directive str —
violation_type str —
message str —
expected tuple[str, ...] | str | int | None —
actual tuple[str, ...] | str | int | None —

Methods

suggestion 0 str | None ▼
Generate a fix suggestion based on violation type.
property
def suggestion(self) -> str | None
Returns
str | None