# contracts

URL: /patitas/api/directives/contracts/
Section: directives
Description: 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",),
    ... )

---

> For a complete page index, fetch /patitas/llms.txt.

Open LLM text
(/patitas/api/directives/contracts/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fcontracts%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fcontracts%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fcontracts%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fcontracts%2Findex.txt)

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 (/patitas/api/directives/contracts/#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 (/patitas/api/directives/contracts/#ContractViolation) | None`

ContractViolation if invalid, None if valid

`validate_children`

2

`list[ContractViolation (/patitas/api/directives/contracts/#ContractViolation)]`

▼

Validate directive children against contract.

`def validate_children(self, directive_name: str, children: Sequence[Directive[Any]]) -> list[ContractViolation]`

##### Parameters

Name
Type
Description

`directive_name`
`—`

Name of the directive being validated

`children`
`—`

Sequence of child Directive nodes

##### Returns

`list[ContractViolation (/patitas/api/directives/contracts/#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`