# contracts URL: /api/directives/contracts/ Section: directives -------------------------------------------------------------------------------- contracts - Patitas window.BENGAL_THEME_DEFAULTS = { appearance: 'light', palette: 'brown-bengal' }; window.Bengal = window.Bengal || {}; window.Bengal.enhanceBaseUrl = '/patitas/assets/js/enhancements'; window.Bengal.watchDom = true; window.Bengal.debug = false; window.Bengal.enhanceUrls = { 'toc': '/patitas/assets/js/enhancements/toc.632a9783.js', 'docs-nav': '/patitas/assets/js/enhancements/docs-nav.57e4b129.js', 'tabs': '/patitas/assets/js/enhancements/tabs.aac9e817.js', 'lightbox': '/patitas/assets/js/enhancements/lightbox.1ca22aa1.js', 'interactive': '/patitas/assets/js/enhancements/interactive.fc077855.js', 'mobile-nav': '/patitas/assets/js/enhancements/mobile-nav.d991657f.js', 'action-bar': '/patitas/assets/js/enhancements/action-bar.d62417f4.js', 'copy-link': '/patitas/assets/js/enhancements/copy-link.7d9a5c29.js', 'data-table': '/patitas/assets/js/enhancements/data-table.1f5bc1eb.js', 'lazy-loaders': '/patitas/assets/js/enhancements/lazy-loaders.a5c38245.js', 'holo': '/patitas/assets/js/enhancements/holo.ee13c841.js', 'link-previews': '/patitas/assets/js/enhancements/link-previews.8d906535.js' }; (function () { try { var defaults = window.BENGAL_THEME_DEFAULTS || { appearance: 'system', palette: '' }; var defaultAppearance = defaults.appearance; if (defaultAppearance === 'system') { defaultAppearance = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'; } var storedTheme = localStorage.getItem('bengal-theme'); var storedPalette = localStorage.getItem('bengal-palette'); var theme = storedTheme ? (storedTheme === 'system' ? defaultAppearance : storedTheme) : defaultAppearance; var palette = storedPalette ?? defaults.palette; document.documentElement.setAttribute('data-theme', theme); if (palette) { document.documentElement.setAttribute('data-palette', palette); } } catch (e) { document.documentElement.setAttribute('data-theme', 'light'); } })(); { "prerender": [ { "where": { "and": [ { "href_matches": "/docs/*" }, { "not": { "selector_matches": "[data-external], [target=_blank], .external" } } ] }, "eagerness": "conservative" } ], "prefetch": [ { "where": { "and": [ { "href_matches": "/*" }, { "not": { "selector_matches": "[data-external], [target=_blank], .external" } } ] }, "eagerness": "conservative" } ] } Skip to main content Magnifying Glass ESC Recent Clear Magnifying Glass No results for "" Start typing to search... ↑↓ Navigate ↵ Open ESC Close Powered by Lunr ฅᨐฅ DocumentationArrow ClockwiseGet StartedCodeSyntaxDirectivesStarburstExtendingBookmarkReferenceInfoAboutTroubleshootingReleasesDevGitHubPatitas API Reference Magnifying Glass Search ⌘K Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal List ฅᨐฅ Magnifying Glass Search X Close Documentation Caret Down Arrow Clockwise Get Started Code Syntax Directives Starburst Extending Bookmark Reference Info About Troubleshooting Releases Dev Caret Down GitHub Patitas API Reference Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal Patitas API Reference Caret Right Directives Caret Right Builtins admonition container dropdown tabs contracts decorator options protocol registry Caret Right Lexer Caret Right Classifiers directive fence footnote heading html link_ref list quote thematic Caret Right Scanners block directive fence html core modes Caret Right Parsing Caret Right Blocks Caret Right List blank_line indent item_blocks marker mixin nested trace types core directive footnote table Caret Right Inline core emphasis links match_registry special tokens charsets containers token_nav Caret Right Plugins autolinks footnotes math strikethrough table task_lists Caret Right Renderers html Caret Right Roles Caret Right Builtins formatting icons math reference protocol registry Caret Right Utils hashing logger text errors highlighting icons location nodes parser patitas protocols stringbuilder tokens Patitas API ReferenceDirectives ᗢ Caret Down Link Copy URL External Open LLM text Copy Copy LLM text Share with AI Ask Claude Ask ChatGPT Ask Gemini Ask Copilot 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 Next → decorator List © 2026 Patitas built in ᓚᘏᗢ { "linkPreviews": { "enabled": true, "hoverDelay": 200, "hideDelay": 150, "showSection": true, "showReadingTime": true, "showWordCount": true, "showDate": true, "showTags": true, "maxTags": 3, "includeSelectors": [".prose"], "excludeSelectors": ["nav", ".toc", ".breadcrumb", ".pagination", ".card", "[class*='-card']", ".tab-nav", "[class*='-widget']", ".child-items", ".content-tiles"], "allowedHosts": [], "allowedSchemes": ["https"], "hostFailureThreshold": 3 } } window.BENGAL_LAZY_ASSETS = { tabulator: '/patitas/assets/js/tabulator.min.js', dataTable: '/patitas/assets/js/data-table.js', mermaidToolbar: '/patitas/assets/js/mermaid-toolbar.9de5abba.js', mermaidTheme: '/patitas/assets/js/mermaid-theme.344822c5.js', graphMinimap: '/patitas/assets/js/graph-minimap.ff04e939.js', graphContextual: '/patitas/assets/js/graph-contextual.355458ba.js' }; window.BENGAL_ICONS = { close: '/patitas/assets/icons/close.911d4fe1.svg', enlarge: '/patitas/assets/icons/enlarge.652035e5.svg', copy: '/patitas/assets/icons/copy.3d56e945.svg', 'download-svg': '/patitas/assets/icons/download.04f07e1b.svg', 'download-png': '/patitas/assets/icons/image.c34dfd40.svg', 'zoom-in': '/patitas/assets/icons/zoom-in.237b4a83.svg', 'zoom-out': '/patitas/assets/icons/zoom-out.38857c77.svg', reset: '/patitas/assets/icons/reset.d26dba29.svg' }; Arrow Up -------------------------------------------------------------------------------- Metadata: - Word Count: 945 - Reading Time: 5 minutes