{ "$schema": "https://sci-d-vis.com/schema/wtrl-json-0.1.0.schema.json", "$id": "urn:waterlint:wtrl-json:0.19.3:core:rfc-2119:ed01ab3f22080c8f80adc12a3660a50463faaf3ef304cb2b5dac27db1f6885c0", "__WTRL_VERSION__": { "waterloo": "0.10.8", "schema": "0.1.0" }, "__WTRL_META__": { "generated_at": "2026-07-01T22:09:18+02:00", "generator": "waterlint", "scope": "core", "flavour": "rfc-2119" }, "__WTRL_ROLES__": { "attr": "Attribute name", "cmd": "Shell or CLI command", "dfn": "Definition of a term", "file": "File or path", "func": "Function or callable", "key": "Key on the keyboard", "label": "Section/Subsection label", "lit": "Literal text or code", "mod": "Module name", "op": "Operator symbol", "opt": "Command-line option or flag", "tag": "Tag or marker", "term": "Domain-specific term", "type": "Type name or annotation", "value": "Concrete value", "var": "Variable name", "var_type": "Variable and type, like 'var:type'" }, "__WTRL_SCOPES__": { "public": { "value": 10, "description": "" }, "extension": { "value": 20, "description": "" }, "core": { "value": 30, "description": "" } }, "__WTRL_TOC_MODULES__": { "sdv.doc.waterloo.docitem_helper": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper" }, "__WTRL_TOC_CLASSES__": { "sdv.doc.waterloo.docitem_helper.WhitelistReason": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason", "sdv.doc.waterloo.docitem_helper.Trait": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Trait", "sdv.doc.waterloo.docitem_helper.Scope": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Scope", "sdv.doc.waterloo.docitem_helper.Flavour": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Flavour", "sdv.doc.waterloo.docitem_helper.Format": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Format", "sdv.doc.waterloo.docitem_helper.Status": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Status", "sdv.doc.waterloo.docitem_helper.ConfigTraversal": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.ConfigTraversal", "sdv.doc.waterloo.docitem_helper.tracer": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.tracer", "sdv.doc.waterloo.docitem_helper.tracer.Severity": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.tracer.Severity", "sdv.doc.waterloo.docitem_helper.DocSession": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.DocSession", "sdv.doc.waterloo.docitem_helper.ResolveObjectError": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.ResolveObjectError" }, "__WTRL_TOC_CALLABLES__": { "sdv.doc.waterloo.docitem_helper.get_source_docstring": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_source_docstring", "sdv.doc.waterloo.docitem_helper.is_obj_annotatable": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_obj_annotatable", "sdv.doc.waterloo.docitem_helper.is_attr_annotated": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_attr_annotated", "sdv.doc.waterloo.docitem_helper.is_attr_final": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_attr_final", "sdv.doc.waterloo.docitem_helper.is_list_of_str": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_list_of_str", "sdv.doc.waterloo.docitem_helper.is_obj_module": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_obj_module", "sdv.doc.waterloo.docitem_helper.is_obj_class": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_obj_class", "sdv.doc.waterloo.docitem_helper.is_obj_function": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_obj_function", "sdv.doc.waterloo.docitem_helper.is_obj_method_like": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_obj_method_like", "sdv.doc.waterloo.docitem_helper.is_obj_named_value": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_obj_named_value", "sdv.doc.waterloo.docitem_helper.is_obj_documentable": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.is_obj_documentable", "sdv.doc.waterloo.docitem_helper.get_obj_direct_module": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_obj_direct_module", "sdv.doc.waterloo.docitem_helper.get_obj_name": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_obj_name", "sdv.doc.waterloo.docitem_helper.get_obj_fully_qualified_name": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_obj_fully_qualified_name", "sdv.doc.waterloo.docitem_helper.get_obj_path": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_obj_path", "sdv.doc.waterloo.docitem_helper.build_anchor": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.build_anchor", "sdv.doc.waterloo.docitem_helper.get_func_obj_from_callable": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_func_obj_from_callable", "sdv.doc.waterloo.docitem_helper.get_obj_docstring": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_obj_docstring", "sdv.doc.waterloo.docitem_helper.get_obj_annotations": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_obj_annotations", "sdv.doc.waterloo.docitem_helper.get_obj_decorators": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_obj_decorators", "sdv.doc.waterloo.docitem_helper.gen_documentable_objects": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.gen_documentable_objects", "sdv.doc.waterloo.docitem_helper.tracer.str_by_severity": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.tracer.str_by_severity", "sdv.doc.waterloo.docitem_helper.tracer.build_json": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.tracer.build_json", "sdv.doc.waterloo.docitem_helper.traced_section": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.traced_section", "sdv.doc.waterloo.docitem_helper.rule_on_fail": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.rule_on_fail", "sdv.doc.waterloo.docitem_helper.raise_has_no_docstring": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.raise_has_no_docstring", "sdv.doc.waterloo.docitem_helper.raise_parsing_error": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.raise_parsing_error", "sdv.doc.waterloo.docitem_helper.raise_parsing_error_expected_but_got": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.raise_parsing_error_expected_but_got", "sdv.doc.waterloo.docitem_helper.raise_validation_error": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.raise_validation_error", "sdv.doc.waterloo.docitem_helper.raise_validation_error_expected_but_got": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.raise_validation_error_expected_but_got", "sdv.doc.waterloo.docitem_helper.get_allowed_sections_for_profile": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.get_allowed_sections_for_profile", "sdv.doc.waterloo.docitem_helper.raise_validation_error_invalid_normative_section": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.raise_validation_error_invalid_normative_section", "sdv.doc.waterloo.docitem_helper.warn_parsing": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.warn_parsing", "sdv.doc.waterloo.docitem_helper.warn_validation": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.warn_validation" }, "__WTRL_TOC_TYPES__": { "sdv.doc.waterloo.docitem_helper.Profile": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Profile", "sdv.doc.waterloo.docitem_helper.DocstringSubtree": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.DocstringSubtree", "sdv.doc.waterloo.docitem_helper.DocstringTree": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.DocstringTree", "sdv.doc.waterloo.docitem_helper.AnnotatableObject": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.AnnotatableObject", "sdv.doc.waterloo.docitem_helper.RuleId": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RuleId", "sdv.doc.waterloo.docitem_helper.Origin": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Origin", "sdv.doc.waterloo.docitem_helper.Details": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Details", "sdv.doc.waterloo.docitem_helper.Scopes": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Scopes", "sdv.doc.waterloo.docitem_helper.Documentable": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Documentable", "sdv.doc.waterloo.docitem_helper.AstDocNode": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.AstDocNode", "sdv.doc.waterloo.docitem_helper.tracer.Context": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.tracer.Context", "sdv.doc.waterloo.docitem_helper.DocSession.Seen": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.DocSession.Seen", "sdv.doc.waterloo.docitem_helper.DocSession.Validated": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.DocSession.Validated" }, "__WTRL_TOC_VARIABLES__": { "sdv.doc.waterloo.docitem_helper.SOURCE_DOCSTRING_CACHE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.SOURCE_DOCSTRING_CACHE", "sdv.doc.waterloo.docitem_helper.OBJ_DOCSTRING_CACHE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.OBJ_DOCSTRING_CACHE" }, "__WTRL_TOC_CONSTANTS__": { "sdv.doc.waterloo.docitem_helper.RE_RULE_ID": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RE_RULE_ID", "sdv.doc.waterloo.docitem_helper.RE_IDENTIFIER": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RE_IDENTIFIER", "sdv.doc.waterloo.docitem_helper.RE_QUALIFIED_IDENTIFIER": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RE_QUALIFIED_IDENTIFIER", "sdv.doc.waterloo.docitem_helper.RE_CSV_IDENTIFIERS": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RE_CSV_IDENTIFIERS", "sdv.doc.waterloo.docitem_helper.WTRL_MARKUP_ROLES": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WTRL_MARKUP_ROLES", "sdv.doc.waterloo.docitem_helper.RE_WTRL_MARKUP_BACKTICK": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RE_WTRL_MARKUP_BACKTICK", "sdv.doc.waterloo.docitem_helper.RE_WTRL_ANGLE_HTTPS_REF": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RE_WTRL_ANGLE_HTTPS_REF", "sdv.doc.waterloo.docitem_helper.RE_WTRL_ANGLE_WTRL_REF": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RE_WTRL_ANGLE_WTRL_REF", "sdv.doc.waterloo.docitem_helper.RE_WTRL_JSON_SCHEMA_NAME": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RE_WTRL_JSON_SCHEMA_NAME", "sdv.doc.waterloo.docitem_helper.RULE_ID_WHITELIST": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.RULE_ID_WHITELIST", "sdv.doc.waterloo.docitem_helper.CANONICAL_ORDER_OF_SECTIONS": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.CANONICAL_ORDER_OF_SECTIONS", "sdv.doc.waterloo.docitem_helper.CANONICAL_ORDER_OF_PROFILES": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.CANONICAL_ORDER_OF_PROFILES", "sdv.doc.waterloo.docitem_helper.TRAIT_TAG_MAP": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.TRAIT_TAG_MAP", "sdv.doc.waterloo.docitem_helper.SCOPE_TAG_MAP": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.SCOPE_TAG_MAP", "sdv.doc.waterloo.docitem_helper.FLAVOUR_TAG_MAP": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.FLAVOUR_TAG_MAP", "sdv.doc.waterloo.docitem_helper.FORMAT_TAG_MAP": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.FORMAT_TAG_MAP", "sdv.doc.waterloo.docitem_helper.STATUS_TAG_MAP": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.STATUS_TAG_MAP", "sdv.doc.waterloo.docitem_helper.SECTION_PROPERTIES": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.SECTION_PROPERTIES", "sdv.doc.waterloo.docitem_helper.WhitelistReason.UNSPECIFIED_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.UNSPECIFIED_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.MAY_EXIST_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.MAY_EXIST_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.STRUCTURE_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.STRUCTURE_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.SEMANTIC_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.SEMANTIC_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.UNRELATED_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.UNRELATED_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.ANTICIPATED_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.ANTICIPATED_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.FALLBACK_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.FALLBACK_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.RELAY_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.RELAY_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.BAD_IMPLEMENTATION_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.BAD_IMPLEMENTATION_RULE", "sdv.doc.waterloo.docitem_helper.WhitelistReason.EXISTS_AS_COMMENT_RULE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.WhitelistReason.EXISTS_AS_COMMENT_RULE", "sdv.doc.waterloo.docitem_helper.Trait.ABSTRACT": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Trait.ABSTRACT", "sdv.doc.waterloo.docitem_helper.Trait.FINAL": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Trait.FINAL", "sdv.doc.waterloo.docitem_helper.Scope.PUBLIC": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Scope.PUBLIC", "sdv.doc.waterloo.docitem_helper.Scope.EXTENSION": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Scope.EXTENSION", "sdv.doc.waterloo.docitem_helper.Scope.CORE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Scope.CORE", "sdv.doc.waterloo.docitem_helper.Flavour.RAW": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Flavour.RAW", "sdv.doc.waterloo.docitem_helper.Flavour.RFC_2119": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Flavour.RFC_2119", "sdv.doc.waterloo.docitem_helper.Flavour.MARKDOWN": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Flavour.MARKDOWN", "sdv.doc.waterloo.docitem_helper.Format.JSON": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Format.JSON", "sdv.doc.waterloo.docitem_helper.Format.MD": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Format.MD", "sdv.doc.waterloo.docitem_helper.Status.EXPERIMENTAL": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Status.EXPERIMENTAL", "sdv.doc.waterloo.docitem_helper.Status.STABLE": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Status.STABLE", "sdv.doc.waterloo.docitem_helper.Status.FROZEN": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Status.FROZEN", "sdv.doc.waterloo.docitem_helper.Status.DEPRECATED": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Status.DEPRECATED", "sdv.doc.waterloo.docitem_helper.Status.DRAFT": "/__WTRL_OBJECTS__/sdv.doc.waterloo.docitem_helper.Status.DRAFT" }, "__WTRL_OBJECTS__": { "sdv.doc.waterloo.docitem_helper.Profile": { "doc": {}, "doc_lines": [ "Supported profile labels for the helper layer." ], "annotation": "Literal['module', 'class', 'function', 'method', 'inherited_method']", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.DocstringSubtree": { "doc": {}, "doc_lines": [ "Recursive docstring tree node type." ], "annotation": "str | List[ForwardRef('DocstringSubtree')]", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.DocstringTree": { "doc": {}, "doc_lines": [ "A full docstring tree represented as a list of subtree values." ], "annotation": "List[str | List[ForwardRef('DocstringSubtree')]]", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.AnnotatableObject": { "doc": {}, "doc_lines": [ "Objects that can be annotated by the helper layer." ], "annotation": "type | module | function | method", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.RuleId": { "doc": {}, "doc_lines": [ "Rule identifier type alias." ], "annotation": "str", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.Origin": { "doc": {}, "doc_lines": [ "Tracer origin labels." ], "annotation": "Literal['parsing', 'validation', 'tool', 'extension']", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.Details": { "doc": {}, "doc_lines": [ "Tracer details payload." ], "annotation": "Dict[str, str | list[str]]", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.Scopes": { "doc": {}, "doc_lines": [ "A set of scope values." ], "annotation": "Set[sdv.doc.waterloo.docitem_helper.Scope]", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.Documentable": { "doc": {}, "doc_lines": [ "Objects that can be traversed by the helper functions." ], "annotation": "module | type[object] | Callable[..., Any]", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.AstDocNode": { "doc": {}, "doc_lines": [ "An AST node type relevant for docstring extraction." ], "annotation": "ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.SOURCE_DOCSTRING_CACHE": { "doc": {}, "doc_lines": [ "A cache for storing source docstrings of objects to avoid redundant retrievals." ], "annotation": "Dict[int, str]", "doc_lines_kind": "variable" }, "sdv.doc.waterloo.docitem_helper.OBJ_DOCSTRING_CACHE": { "doc": {}, "doc_lines": [ "A cache for storing resolved docstring text by object identity.", "This cache is intentionally public so callers may inspect, clear, or replace it during a process lifetime." ], "annotation": "Dict[int, str]", "doc_lines_kind": "variable" }, "sdv.doc.waterloo.docitem_helper.RE_RULE_ID": { "doc": {}, "doc_lines": [ "Regular expression for rule IDs. Undocumented: RE_RULE_ID_COMPILED, the precompiled version for performance." ], "annotation": "Final[str]", "doc_lines_kind": "constant", "examples": [ "/__WTRL_EXAMPLES__/sha256_134892e694d296399fc3eea2716c5fca17c523cc0ec2d116575bdc8e7480e5c3" ] }, "sdv.doc.waterloo.docitem_helper.RE_IDENTIFIER": { "doc": {}, "doc_lines": [ "Regular expression for identifiers. Undocumented: RE_IDENTIFIER_COMPILED, the precompiled version for performance." ], "annotation": "Final[str]", "doc_lines_kind": "constant", "examples": [ "/__WTRL_EXAMPLES__/sha256_068c6155177172c3f292e2d499e111022b8688e8133c82812182b0f442214084" ] }, "sdv.doc.waterloo.docitem_helper.RE_QUALIFIED_IDENTIFIER": { "doc": {}, "doc_lines": [ "Regular expression for qualified identifiers. Undocumented: RE_QUALIFIED_IDENTIFIER_COMPILED, the precompiled version for performance." ], "annotation": "Final[str]", "doc_lines_kind": "constant", "examples": [ "/__WTRL_EXAMPLES__/sha256_068c6155177172c3f292e2d499e111022b8688e8133c82812182b0f442214084" ] }, "sdv.doc.waterloo.docitem_helper.RE_CSV_IDENTIFIERS": { "doc": {}, "doc_lines": [ "Regular expression for comma-separated identifiers. Undocumented: RE_CSV_IDENTIFIERS_COMPILED, the precompiled version for performance." ], "doc_lines_kind": "constant", "examples": [ "/__WTRL_EXAMPLES__/sha256_6d6be44016303793d2d91cde29e1a0a9dead9555b84f9616bf215b1c33aff749" ] }, "sdv.doc.waterloo.docitem_helper.WTRL_MARKUP_ROLES": { "doc": {}, "doc_lines": [ "Regular expression for Waterloo markup roles in backtick markup." ], "annotation": "Final[str]", "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.RE_WTRL_MARKUP_BACKTICK": { "doc": {}, "doc_lines": [ "Regular expression for matching Waterloo backtick markup with roles. Undocumented: RE_WTRL_MARKUP_BACKTICK_COMPILED, the precompiled version for performance." ], "annotation": "Final[str]", "doc_lines_kind": "constant", "examples": [ "/__WTRL_EXAMPLES__/sha256_769b2f56a62fd91ab8b4846412903f1862986aff74bc286fd13ed63a5fe16225" ] }, "sdv.doc.waterloo.docitem_helper.RE_WTRL_ANGLE_HTTPS_REF": { "doc": {}, "doc_lines": [ "Regular expression for matching Waterloo angle bracket HTTPS references. Undocumented: RE_WTRL_ANGLE_HTTPS_REF_COMPILED, the precompiled version for performance.", "References consist of two parts: clear text and , optionally separated by whitespace." ], "annotation": "Final[str]", "doc_lines_kind": "constant", "examples": [ "/__WTRL_EXAMPLES__/sha256_1578269401876a2fc905574d4853cb14ee3efbe6c7bdc71bb34eb9b270380e70" ] }, "sdv.doc.waterloo.docitem_helper.RE_WTRL_ANGLE_WTRL_REF": { "doc": {}, "doc_lines": [ "Regular expression for matching Waterloo angle bracket wtrl references. Undocumented: RE_WTRL_ANGLE_WTRL_REF_COMPILED, the precompiled version for performance.", "References consist of two parts: clear text and , optionally separated by whitespace." ], "annotation": "Final[str]", "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.RE_WTRL_JSON_SCHEMA_NAME": { "doc": {}, "doc_lines": [ "Regular expression for matching Waterloo JSON Schema filenames. Undocumented: RE_WTRL_JSON_SCHEMA_NAME_COMPILED, the precompiled version for performance." ], "annotation": "Final[str]", "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.RULE_ID_WHITELIST": { "doc": {}, "doc_lines": [ "Whitelist reasons for legacy rule identifiers used by the helper layer." ], "annotation": "Final[Dict[str, WhitelistReason]]", "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.CANONICAL_ORDER_OF_SECTIONS": { "doc": {}, "doc_lines": [ "Canonical subsection ordering for section snippets and expected snippets." ], "annotation": "Final[Dict[str, None | Sequence[str]]]", "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.CANONICAL_ORDER_OF_PROFILES": { "doc": {}, "doc_lines": [ "Canonical profile ordering for CLI help and documentation." ], "annotation": "Final[list[Profile_t]]", "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.TRAIT_TAG_MAP": { "doc": {}, "doc_lines": [ "Trait tag mapping for trait labels." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.SCOPE_TAG_MAP": { "doc": {}, "doc_lines": [ "Scope tag mapping for visibility selection." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.FLAVOUR_TAG_MAP": { "doc": {}, "doc_lines": [ "Flavour tag mapping for normativity keyword rendering." ], "annotation": "Final[Mapping[str, Flavour]]", "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.FORMAT_TAG_MAP": { "doc": {}, "doc_lines": [ "Output format tag mapping for string-related output." ], "annotation": "Final[Mapping[str, Format]]", "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.STATUS_TAG_MAP": { "doc": {}, "doc_lines": [ "Status tag mapping for Preamble.status." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.SECTION_PROPERTIES": { "doc": {}, "doc_lines": [ "MUST be a mapping from section and subsection labels to their properties relevant for explanation and validation,", "for example body category, normativity, and profile applicability.", "Informative: This is a carefully distilled machine-readable representation of the relevant rules", "from the documentation standard, but the documentation remains the Single Source of Truth for the standard." ], "annotation": "Final[dict[str, SectionProperty_t]]", "doc_lines_kind": "constant", "examples": [ "/__WTRL_EXAMPLES__/sha256_777b32bdb96bdcef4ecebd399607674893cc0d508a6a9563b6d31b6ecf2e8c75" ] }, "sdv.doc.waterloo.docitem_helper": { "doc": { "Preamble": { "profile": "module", "normative_sections": [ "Contract", "Public_classes", "Public_functions", "Public_types", "Public_constants", "Public_variables" ] }, "Contract": { "general": [ "MUST provide shared helper functions, constants, and type aliases for Waterloo docstring validation and explanation." ] }, "Public_classes": [ "Trait", "Scope", "Flavour", "Format", "Status", "ConfigTraversal", "DocSession", "tracer", "ResolveObjectError", "WhitelistReason" ], "Public_functions": [ "get_source_docstring", "is_obj_annotatable", "is_attr_annotated", "is_attr_final", "is_list_of_str", "is_obj_module", "is_obj_class", "is_obj_function", "is_obj_method_like", "is_obj_named_value", "is_obj_documentable", "get_obj_direct_module", "get_obj_name", "get_obj_fully_qualified_name", "get_obj_path", "build_anchor", "get_func_obj_from_callable", "get_obj_docstring", "get_obj_annotations", "get_obj_decorators", "gen_documentable_objects", "traced_section", "rule_on_fail", "raise_has_no_docstring", "raise_parsing_error", "raise_parsing_error_expected_but_got", "raise_validation_error", "raise_validation_error_expected_but_got", "raise_validation_error_invalid_normative_section", "get_allowed_sections_for_profile", "warn_parsing", "warn_validation" ], "Public_types": { "Profile": [ "Supported profile labels for the helper layer." ], "DocstringSubtree": [ "Recursive docstring tree node type." ], "DocstringTree": [ "A full docstring tree represented as a list of subtree values." ], "AnnotatableObject": [ "Objects that can be annotated by the helper layer." ], "RuleId": [ "Rule identifier type alias." ], "Origin": [ "Tracer origin labels." ], "Details": [ "Tracer details payload." ], "Scopes": [ "A set of scope values." ], "Documentable": [ "Objects that can be traversed by the helper functions." ], "AstDocNode": [ "An AST node type relevant for docstring extraction." ] }, "Public_constants": { "RE_RULE_ID": [ "Regular expression for rule IDs. Undocumented: RE_RULE_ID_COMPILED, the precompiled version for performance." ], "RE_IDENTIFIER": [ "Regular expression for identifiers. Undocumented: RE_IDENTIFIER_COMPILED, the precompiled version for performance." ], "RE_QUALIFIED_IDENTIFIER": [ "Regular expression for qualified identifiers. Undocumented: RE_QUALIFIED_IDENTIFIER_COMPILED, the precompiled version for performance." ], "RE_CSV_IDENTIFIERS": [ "Regular expression for comma-separated identifiers. Undocumented: RE_CSV_IDENTIFIERS_COMPILED, the precompiled version for performance." ], "WTRL_MARKUP_ROLES": [ "Regular expression for Waterloo markup roles in backtick markup." ], "RE_WTRL_MARKUP_BACKTICK": [ "Regular expression for matching Waterloo backtick markup with roles. Undocumented: RE_WTRL_MARKUP_BACKTICK_COMPILED, the precompiled version for performance." ], "RE_WTRL_ANGLE_HTTPS_REF": [ "Regular expression for matching Waterloo angle bracket HTTPS references. Undocumented: RE_WTRL_ANGLE_HTTPS_REF_COMPILED, the precompiled version for performance.", "References consist of two parts: clear text and , optionally separated by whitespace." ], "RE_WTRL_ANGLE_WTRL_REF": [ "Regular expression for matching Waterloo angle bracket wtrl references. Undocumented: RE_WTRL_ANGLE_WTRL_REF_COMPILED, the precompiled version for performance.", "References consist of two parts: clear text and , optionally separated by whitespace." ], "RE_WTRL_JSON_SCHEMA_NAME": [ "Regular expression for matching Waterloo JSON Schema filenames. Undocumented: RE_WTRL_JSON_SCHEMA_NAME_COMPILED, the precompiled version for performance." ], "RULE_ID_WHITELIST": [ "Whitelist reasons for legacy rule identifiers used by the helper layer." ], "CANONICAL_ORDER_OF_SECTIONS": [ "Canonical subsection ordering for section snippets and expected snippets." ], "CANONICAL_ORDER_OF_PROFILES": [ "Canonical profile ordering for CLI help and documentation." ], "TRAIT_TAG_MAP": [ "Trait tag mapping for trait labels." ], "SCOPE_TAG_MAP": [ "Scope tag mapping for visibility selection." ], "FLAVOUR_TAG_MAP": [ "Flavour tag mapping for normativity keyword rendering." ], "FORMAT_TAG_MAP": [ "Output format tag mapping for string-related output." ], "STATUS_TAG_MAP": [ "Status tag mapping for Preamble.status." ], "SECTION_PROPERTIES": [ "MUST be a mapping from section and subsection labels to their properties relevant for explanation and validation,", "for example body category, normativity, and profile applicability.", "Informative: This is a carefully distilled machine-readable representation of the relevant rules", "from the documentation standard, but the documentation remains the Single Source of Truth for the standard." ] }, "Public_variables": { "SOURCE_DOCSTRING_CACHE": [ "A cache for storing source docstrings of objects to avoid redundant retrievals." ], "OBJ_DOCSTRING_CACHE": [ "A cache for storing resolved docstring text by object identity.", "This cache is intentionally public so callers may inspect, clear, or replace it during a process lifetime." ] }, "Notes": { "Render functions": [ "The render functions in this module are intended for building", "verbose diagnostic messages that include source and expected snippets", "along with suggestions on how to fix the docstring." ] } } }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.UNSPECIFIED_RULE": { "doc": {}, "doc_lines": [ "No explicit reason was recorded." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.MAY_EXIST_RULE": { "doc": {}, "doc_lines": [ "The rule may exist in the corpus." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.STRUCTURE_RULE": { "doc": {}, "doc_lines": [ "The rule is a structural rule." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.SEMANTIC_RULE": { "doc": {}, "doc_lines": [ "The rule is a semantic rule." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.UNRELATED_RULE": { "doc": {}, "doc_lines": [ "The rule is unrelated to the current module." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.ANTICIPATED_RULE": { "doc": {}, "doc_lines": [ "The rule is expected to appear later." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.FALLBACK_RULE": { "doc": {}, "doc_lines": [ "The rule acts as a fallback." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.RELAY_RULE": { "doc": {}, "doc_lines": [ "The rule is relayed to another rule." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.BAD_IMPLEMENTATION_RULE": { "doc": {}, "doc_lines": [ "The rule is a placeholder for a bad implementation case." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason.EXISTS_AS_COMMENT_RULE": { "doc": {}, "doc_lines": [ "The rule exists only as a comment-level trace." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.WhitelistReason": { "signature": { "text": "object.__init__(self, /, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Public_constants", "Derived_from" ] }, "Contract": { "general": [ "MUST enumerate the legacy rule-whitelist reasons used by this helper layer." ], "constructor": [ "Inherit from |type|`IntEnum`." ] }, "Derived_from": [ "IntEnum" ], "Public_constants": { "UNSPECIFIED_RULE": [ "No explicit reason was recorded." ], "MAY_EXIST_RULE": [ "The rule may exist in the corpus." ], "STRUCTURE_RULE": [ "The rule is a structural rule." ], "SEMANTIC_RULE": [ "The rule is a semantic rule." ], "UNRELATED_RULE": [ "The rule is unrelated to the current module." ], "ANTICIPATED_RULE": [ "The rule is expected to appear later." ], "FALLBACK_RULE": [ "The rule acts as a fallback." ], "RELAY_RULE": [ "The rule is relayed to another rule." ], "BAD_IMPLEMENTATION_RULE": [ "The rule is a placeholder for a bad implementation case." ], "EXISTS_AS_COMMENT_RULE": [ "The rule exists only as a comment-level trace." ] } } }, "sdv.doc.waterloo.docitem_helper.Trait.ABSTRACT": { "doc": {}, "doc_lines": [ "The class is abstract, i.e. it cannot be instantiated directly and is not a complete specification of the concept." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Trait.FINAL": { "doc": {}, "doc_lines": [ "The class is final, i.e. it cannot be subclassed and is a complete specification of the concept." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Trait": { "signature": { "text": "object.__init__(self, /, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Public_constants", "Derived_from" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST provide constants representing the traits of a class." ], "constructor": [ "Inherit from |type|`StrEnum`." ] }, "Derived_from": [ "StrEnum" ], "Public_constants": { "ABSTRACT": [ "The class is abstract, i.e. it cannot be instantiated directly and is not a complete specification of the concept." ], "FINAL": [ "The class is final, i.e. it cannot be subclassed and is a complete specification of the concept." ] } } }, "sdv.doc.waterloo.docitem_helper.Scope.PUBLIC": { "doc": {}, "doc_lines": [ "Selects the public API." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Scope.EXTENSION": { "doc": {}, "doc_lines": [ "Selects the API for developers of plugin and extensions." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Scope.CORE": { "doc": {}, "doc_lines": [ "Selects the API for core developers." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Scope": { "signature": { "text": "object.__init__(self, /, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Public_constants", "Derived_from" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST provide constants representing available scopes.", "MUST provide a time-stable partial order for the constants." ], "constructor": [ "Inherit from |type|`int`." ] }, "Derived_from": [ "IntEnum" ], "Public_constants": { "PUBLIC": [ "Selects the public API." ], "EXTENSION": [ "Selects the API for developers of plugin and extensions." ], "CORE": [ "Selects the API for core developers." ] }, "Notes": { "Purpose": [ "The scope is an optional parameter for rendering functions. It allows to restrict the set of rendered objects to a well-defined audience." ], "Values": [ "The class only ensures the partial order but does not ensure particular values for the constants." ] } } }, "sdv.doc.waterloo.docitem_helper.Flavour.RAW": { "doc": {}, "doc_lines": [ "Example: | + Must + |" ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Flavour.RFC_2119": { "doc": {}, "doc_lines": [ "Example: |lit|`MUST`" ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Flavour.MARKDOWN": { "doc": {}, "doc_lines": [ "Example: |lit|`**MUST**`" ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Flavour": { "signature": { "text": "object.__init__(self, /, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Public_constants", "Derived_from" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST provide constants representing available flavours for rendering Normativity Keywords." ], "constructor": [ "Inherit from |type|`int`." ] }, "Derived_from": [ "IntEnum" ], "Public_constants": { "RAW": [ "Example: | + Must + |" ], "RFC_2119": [ "Example: |lit|`MUST`" ], "MARKDOWN": [ "Example: |lit|`**MUST**`" ] } } }, "sdv.doc.waterloo.docitem_helper.Format.JSON": { "doc": {}, "doc_lines": [ "Javascript Object Notation" ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Format.MD": { "doc": {}, "doc_lines": [ "Markdown." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Format": { "signature": { "text": "object.__init__(self, /, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Public_constants", "Derived_from" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST provide constants representing available output formats for string rendering." ], "constructor": [ "Inherit from |type|`int`." ] }, "Derived_from": [ "IntEnum" ], "Public_constants": { "JSON": [ "Javascript Object Notation" ], "MD": [ "Markdown." ] } } }, "sdv.doc.waterloo.docitem_helper.Status.EXPERIMENTAL": { "doc": {}, "doc_lines": [ "See rule |ref|`STA-004 `." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Status.STABLE": { "doc": {}, "doc_lines": [ "See rule |ref|`STA-004 `." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Status.FROZEN": { "doc": {}, "doc_lines": [ "See rule |ref|`STA-004 `." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Status.DEPRECATED": { "doc": {}, "doc_lines": [ "See rule |ref|`STA-004 `." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Status.DRAFT": { "doc": {}, "doc_lines": [ "See rule |ref|`STA-004 `." ], "doc_lines_kind": "constant" }, "sdv.doc.waterloo.docitem_helper.Status": { "signature": { "text": "object.__init__(self, /, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Public_constants", "Derived_from" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST provide constants representing the values of subsection |label|`Preamble.status`." ], "constructor": [ "Inherit from |type|`StrEnum`." ] }, "Derived_from": [ "StrEnum" ], "Public_constants": { "EXPERIMENTAL": [ "See rule |ref|`STA-004 `." ], "STABLE": [ "See rule |ref|`STA-004 `." ], "FROZEN": [ "See rule |ref|`STA-004 `." ], "DEPRECATED": [ "See rule |ref|`STA-004 `." ], "DRAFT": [ "See rule |ref|`STA-004 `." ] }, "Notes": { "LoII": [ "This docstring violates LoII in order to preserve SSoT,", "see |label|`Public_constants`." ] } } }, "sdv.doc.waterloo.docitem_helper.get_source_docstring": { "signature": { "text": "get_source_docstring(o: 'object') -> 'str'", "parameters": [ { "name": "o", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "str" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST return a raw source docstring for |var|`o` if the defining source text can be obtained.", "MUST support modules, classes, functions, methods, and routine-like objects for which source text is available.", "MUST prefer the source docstring over any runtime |value|`__doc__` representation.", "MUST cache the extracted result globally by object identity to avoid repeated source parsing.", "MUST cache one parsed AST per module and reuse it for subsequent lookups.", "MUST preserve original indentation and tabs in order to remain compatible with Waterloo parsing under Python 3.13+.", "SHOULD fall back to a direct source snippet parse when the object is a decorated or wrapper-like callable that cannot be resolved reliably through the module AST. The AST-based source lookup is intentionally slower than direct runtime docstring access and is therefore implemented with caching as a first-order mitigation, not as a full performance optimization.", "MUST return the empty string if no source docstring can be determined." ] }, "Parameters": { "o": [ "Any documentable object whose defining source docstring should be extracted." ] }, "Returns": [ "MUST return the raw source docstring text, or the empty string if none is available." ], "Raises": {}, "Notes": { "Implementation": [ "The helper uses a source-first strategy to preserve original indentation and tab characters in Python 3.13+.", "Docstrings are cached by object identity, while parsed module ASTs are cached separately by module object.", "The AST path is slower than runtime |var|`__doc__` access, but caching keeps the repeated cost manageable.", "Further performance improvements can be added later by caching validation results for repeated objects." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_602a470e833e907c43808fab7db1d2d9c489ac3eba11ba56d99de7e17163dd2f" ] }, "sdv.doc.waterloo.docitem_helper.ConfigTraversal": { "signature": { "text": "ConfigTraversal.__init__(self) -> 'None'", "parameters": [], "returns": "None" }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST provide public methods to configure object traversal for functions like |func|`gen_documentable_objects`.", "MUST provide (internal) boolean methods which accept or refuse traversal at a given node in the object tree." ], "constructor": [ "MUST be default-constructible" ] }, "Notes": { "Experimental": [ "This class will likely be expanded in the future, and we are postponing the normative documentation for now." ], "Configure": [ "Use |func|`enable_include_imported` to allow descending into imported modules." ], "Future": [ "Possible extensions include acceptance/refusal by regular expressions." ], "Example": [ "|ref|`gen_documentable_objects `" ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_5b8bafdfe320f94e617fe049cc57f150754e08afdcba39aa223c9f6213b9bdce" ] }, "sdv.doc.waterloo.docitem_helper.is_obj_annotatable": { "signature": { "text": "is_obj_annotatable(obj: 'Any') -> 'TypeGuard[AnnotatableObject]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Any", "default": null } ], "returns": "TypeGuard[AnnotatableObject]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST relay to |mod|`inspect.get_annotations`-compatible object kinds." ] }, "Parameters": { "obj": [ "The object to inspect." ] }, "Returns": [ "|True| if |var|`obj` is annotatable, else |False|." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |mod|`inspect`." ] }, "Notes": { "Purpose": [ "Uniform wrapper, allows us to add debugging output or hooks in case of trouble." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5" ] }, "sdv.doc.waterloo.docitem_helper.is_attr_annotated": { "signature": { "text": "is_attr_annotated(obj: 'AnnotatableObject', attr: 'str') -> 'bool'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "AnnotatableObject", "default": null }, { "name": "attr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "bool" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST find out whether the requested name is annotated on the object." ] }, "Parameters": { "obj": [ "The annotatable object to inspect, for example a module, class,", "function, or method." ], "attr": [ "The attribute or annotation name to be tested. For functions and", "methods this includes parameter names and the return annotation." ] }, "Returns": [ "MUST return |True| if the attribute is annotated, else |False|." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |func|`getattr`." ] }, "Notes": { "Last review": [ "2026-02-04" ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_1f77d8b5ff9b65debb0fa04da3a9425c125f61dea821c67c5ed4a4841f4111e2" ] }, "sdv.doc.waterloo.docitem_helper.is_attr_final": { "signature": { "text": "is_attr_final(obj: 'AnnotatableObject', attr: 'str') -> 'bool'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "AnnotatableObject", "default": null }, { "name": "attr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "bool" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST find out whether the attribute passed is annotated as |type|`Final`." ] }, "Parameters": { "obj": [ "The class or module containing the attribute." ], "attr": [ "The name of the attribute to be tested." ] }, "Returns": [ "MUST return |True| if the attribute is annotated as |type|`Final`, else |False|." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |func|`get_type_hints`." ] }, "Notes": { "Last review": [ "2026-02-04" ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_1f77d8b5ff9b65debb0fa04da3a9425c125f61dea821c67c5ed4a4841f4111e2" ] }, "sdv.doc.waterloo.docitem_helper.is_list_of_str": { "signature": { "text": "is_list_of_str(val: 'Any') -> 'TypeGuard[List[str]]'", "parameters": [ { "name": "val", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Any", "default": null } ], "returns": "TypeGuard[List[str]]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST decide whether |var|`val` is a list whose items are all strings." ] }, "Parameters": { "val": [ "The value to test." ] }, "Returns": [ "|True| if |var|`val` is a list of strings, else |False|." ], "Raises": {} }, "examples": [ "/__WTRL_EXAMPLES__/sha256_7c28b6182c139a657bab51b3d9e573953cd4603d8aff3d13d0e2ab23d4d0624f" ] }, "sdv.doc.waterloo.docitem_helper.is_obj_module": { "signature": { "text": "is_obj_module(obj: 'object') -> 'TypeIs[ModuleType]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "TypeIs[ModuleType]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST relay to |func|`inspect.ismodule`" ] }, "Parameters": { "obj": [ "The object to inspect." ] }, "Returns": [ "|True| if |var|`obj` is a module." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |mod|`inspect`." ] }, "Notes": { "Purpose": [ "Uniform wrapper, allows us to add debugging output or hooks in case of trouble." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5" ] }, "sdv.doc.waterloo.docitem_helper.is_obj_class": { "signature": { "text": "is_obj_class(obj: 'object') -> 'TypeIs[type[object]]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "TypeIs[type[object]]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST relay to |func|`inspect.isclass`" ] }, "Parameters": { "obj": [ "The object to inspect." ] }, "Returns": [ "|True| if |var|`obj` is a class." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |mod|`inspect`." ] }, "Notes": { "Purpose": [ "Uniform wrapper, allows us to add debugging output or hooks in case of trouble." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5" ] }, "sdv.doc.waterloo.docitem_helper.is_obj_function": { "signature": { "text": "is_obj_function(obj: 'object') -> 'TypeIs[Callable[..., Any]]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "TypeIs[Callable[..., Any]]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST relay to |func|`inspect.isroutine`" ] }, "Parameters": { "obj": [ "The object to inspect." ] }, "Returns": [ "|True| if |var|`obj` is a routine, which is a pretty general concept for \"something that can be called\", but excludes callable classes." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |mod|`inspect`." ] }, "Notes": { "Purpose": [ "Uniform wrapper, allows us to add debugging output or hooks in case of trouble." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5" ] }, "sdv.doc.waterloo.docitem_helper.is_obj_method_like": { "signature": { "text": "is_obj_method_like(obj: 'object') -> 'TypeIs[Callable[..., Any]]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "TypeIs[Callable[..., Any]]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST detect callables which should be treated as \"method-like\" for Waterloo profile heuristics.", "MUST return |False| for non-routines.", "MUST treat callables with class-like |value|`__qualname__` (`A.f`) as method-like.", "SHOULD additionally use decorators |lit|`@staticmethod`, |lit|`@classmethod`, |lit|`@abstractmethod`, |lit|`@abc.abstractmethod` as hints." ] }, "Parameters": { "obj": [ "Object to inspect." ] }, "Returns": [ "|True| if |var|`obj` is callable and method-like by heuristic." ], "Raises": {} }, "examples": [ "/__WTRL_EXAMPLES__/sha256_28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5" ] }, "sdv.doc.waterloo.docitem_helper.is_obj_named_value": { "signature": { "text": "is_obj_named_value(obj: 'object') -> 'TypeIs[Callable[..., Any]]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "TypeIs[Callable[..., Any]]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST be equivalent to not |func|`is_obj_module` and not |func|`is_obj_class` and not |func|`is_obj_function`." ], "requires": [ "The caller MUST ensure that the object exists." ] }, "Parameters": { "obj": [ "The object to inspect." ] }, "Returns": [ "|True| if |var|`obj` is a named value" ], "Raises": { "BaseException": [ "MAY propagate exceptions from |mod|`inspect`." ] }, "Notes": { "Purpose": [ "Uniform wrapper, allows us to add debugging output or hooks in case of trouble." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5" ] }, "sdv.doc.waterloo.docitem_helper.is_obj_documentable": { "signature": { "text": "is_obj_documentable(obj: 'object') -> 'TypeIs[Documentable]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "TypeIs[Documentable]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST find out if the object passed can have a docstring." ] }, "Parameters": { "obj": [ "The object to examine." ] }, "Returns": [ "|True| if |var|`obj` is a module, class or function, else |False|." ], "Raises": {}, "Notes": { "Last review": [ "2026-06-22" ], "Documentable vs. non-documentable objects": [ "Only modules, classes, and functions are considered documentable", "for Waterloo docstring generation and validation.", "Accordingly, sections like |label|`Public_types`,", "|label|`Public_constants`, and |label|`Public_variables`", "in module and class docstrings document named values", "that are not documentable objects themselves." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5" ] }, "sdv.doc.waterloo.docitem_helper.get_obj_direct_module": { "signature": { "text": "get_obj_direct_module(obj: 'object') -> 'ModuleType | None'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "ModuleType | None" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST return the direct owner module of |var|`obj`.", "MUST return |var|`obj` unchanged if |var|`obj` is a module.", "MUST try to resolve the module named by |var|`obj.__module__` for classes and callables.", "MUST return |None| if no direct module can be resolved.", "MUST avoid deep traversal (e.g. not resolve enclosing module hierarchies recursively)." ] }, "Parameters": { "obj": [ "The object to inspect." ] }, "Returns": [ "The direct module object, or |None| if unavailable." ], "Raises": { "ImportError": [ "MAY be raised by module import helpers if implementation chooses to import by name." ], "ValueError": [ "MAY be raised by import helpers for malformed module names." ], "AttributeError": [ "MAY be raised by low-level inspection for malformed objects." ] }, "Notes": { "Boundary": [ "\"Direct module\" is defined by immediate metadata (`__module__`) only.", "Nested ownership (class-inside-class, closures, descriptors) is out of scope." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_3a34ca6470361aaea2fe620809e836bd00fcfb83d9c0687e65b1174b039cf3e7" ] }, "sdv.doc.waterloo.docitem_helper.get_obj_name": { "signature": { "text": "get_obj_name(obj: 'object') -> 'str'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "str" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises", "See_also" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST employ reasonable heuristics to extract a representative name.", "MUST return string objects as-is.", "MUST prioritize `__qualname__` over `__name__` for types/functions.", "MUST resolve to the name of the underlying class for object instances.", "MUST provide the string representation as a terminal fallback." ] }, "Parameters": { "obj": [ "The object to inspect." ] }, "Returns": [ "The resolved name according to the defined hierarchy." ], "Raises": {}, "Notes": { "Last review": [ "2026-06-22" ], "Limitations": [ "This helper is best-effort and object-local.", "It does not reconstruct containment context for nested instances.", "Behavior for property-like descriptors such as |type|`property` and |type|`cached_property` is undefined.", "If you need a more precise identifier, prefer |func|`get_obj_fully_qualified_name`." ] }, "See_also": [ "get_obj_fully_qualified_name" ] }, "examples": [ "/__WTRL_EXAMPLES__/sha256_811282620191ed177eb3e85f6d15efb0cfa9d7a5982d4259cc77463cbdc0ac83" ] }, "sdv.doc.waterloo.docitem_helper.get_obj_fully_qualified_name": { "signature": { "text": "get_obj_fully_qualified_name(obj: 'object') -> 'str'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "str" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST return a fully qualified object name where possible.", "MUST return module objects as their module name.", "MUST return callable/class/object names as |mod|`` . |lit|`` when both parts are available.", "MUST fall back to |func|`get_obj_name` if no module prefix can be determined.", "MUST return input strings unchanged.", "MUST resolve class instances to their class name, prefixed by the module name when available." ] }, "Parameters": { "obj": [ "The object to inspect." ] }, "Returns": [ "Best-effort fully qualified object name." ], "Raises": {}, "Notes": { "Last review": [ "2026-06-23" ], "Limitations": [ "Behavior for property-like descriptors such as |type|`property` and |type|`cached_property` is undefined." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_1430a8f116b0fa6e3670f59c04d646f41b25fded4a0320f30bba38dab49a8239", "/__WTRL_EXAMPLES__/sha256_4b683772b0a0b115616e98c77b6586f229e04c469e8fdebe5d18f7d69fc79b22", "/__WTRL_EXAMPLES__/sha256_ff67bb22509a88a9560af9d3c18742210d3cb38ab23c9f38e7f72e3856ff1c0d" ] }, "sdv.doc.waterloo.docitem_helper.get_obj_path": { "signature": { "text": "get_obj_path(obj: 'object') -> 'str | None'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "str | None" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST return an absolute filesystem path to the module that defines |var|`obj`, if determinable.", "MUST return |None| if the path cannot be determined (e.g. builtins, C-extensions, interactive objects)." ] }, "Parameters": { "obj": [ "The object whose defining module path is requested." ] }, "Returns": [ "Absolute path string or |None|." ], "Raises": {}, "Notes": { "Last review": [ "2026-02-05" ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_51367d261eb1a4f032df6518aa4b5635980be001494fd5068011e170647147f8" ] }, "sdv.doc.waterloo.docitem_helper.build_anchor": { "signature": { "text": "build_anchor(obj: 'object', kind: 'str | None' = None) -> 'str'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null }, { "name": "kind", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str | None", "default": "None" } ], "returns": "str" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ] }, "Contract": { "general": [ "MUST build a deterministic anchor string from an object.", "MUST use the fully qualified name as source.", "MUST encode each qualified-name segment as |lit|`:`.", "MUST prefix the anchor by |lit|`wtrl--`.", "MUST infer kind as one of |lit|`mod`, |lit|`cls`, |lit|`func`, |lit|`obj` if not passed explicitly." ] }, "Parameters": { "obj": [ "Object for which the anchor shall be generated." ], "kind": [ "Optional explicit kind tag." ] }, "Returns": [ "Deterministic anchor string suitable for doc-internal links." ], "Raises": {}, "Notes": { "Last review": [ "2026-06-22" ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_4492b7b0c534e25149d57bd029f106019dbac863464599cd59cd5a43b7218aa0" ] }, "sdv.doc.waterloo.docitem_helper.get_func_obj_from_callable": { "signature": { "text": "get_func_obj_from_callable(obj: 'object') -> 'Callable[..., Any] | None'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "Callable[..., Any] | None" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "extension" ], "status": "stable" }, "Contract": { "general": [ "MUST return the function object assigned to the object for a wide class of cases.", "MUST handle functions in classes without decorators.", "MUST handle functions in classes with decorator |attr|`@staticmethod`.", "MUST handle functions in classes with decorator |attr|`@classmethod`.", "MUST handle callable classes.", "MUST handle instances of callable classes.", "MUST handle functions at module level.", "MUST handle generators.", "SHOULD be able to handle built-ins." ] }, "Parameters": { "obj": [ "The object to analyze." ] }, "Returns": [ "The function object (or built-in) assigned to |var|`obj`." ], "Raises": {}, "Notes": { "API": [ "The signature is stable, but we might add cases to the implementation." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_ff67bb22509a88a9560af9d3c18742210d3cb38ab23c9f38e7f72e3856ff1c0d" ] }, "sdv.doc.waterloo.docitem_helper.get_obj_docstring": { "signature": { "text": "get_obj_docstring(obj: 'object') -> 'str'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "str" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST return the best available docstring text for |var|`obj`.", "MUST prefer the raw source docstring obtained by |func|`get_source_docstring`.", "MUST support modules, classes, functions/methods, descriptors (|type|`staticmethod`, |type|`classmethod`, |type|`property` / |type|`cached_property`), partial/partialmethod objects, and callable instances via |func|`__call__`.", "MUST follow |type|`__wrapped__` chains created by |func|`functools.wraps`.", "MUST return the empty string if no docstring is available." ] }, "Parameters": { "obj": [ "Any python object that might carry a docstring." ] }, "Returns": [ "MUST return the best available docstring text, or the empty string if none exists." ], "Raises": {}, "Notes": { "Last review": [ "2026-05-15" ], "General": [ "The object-level cache avoids repeating the wrapper walk for the same object." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_294ad917b357529f361ff629b3f0ba3c230afc966e738122ea903d1b4a23c379" ] }, "sdv.doc.waterloo.docitem_helper.get_obj_annotations": { "signature": { "text": "get_obj_annotations(obj: 'object') -> 'dict[str, Any]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "dict[str, Any]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST build a |type|`dict` (the |dfn|`result`) as follows:", "MUST analyse the object's annotations by means of |mod|`inspect`.", "On success, MUST add the annotations to the result.", "MUST check for an attribute |attr|`__type_params__` in the object.", "If it exists (as of Python 3.12), MUST iterate over the |type|`tuple` |var|`obj.__type_params__` and add pairs consisting of |var|`param.__name__` and |value|`type(param)` to the result." ] }, "Parameters": { "obj": [ "The object to be inspected." ] }, "Returns": [ "A |type|`dict` representing the object's annotations." ], "Raises": { "BaseException": [ "MAY propagate exceptions other than |type|`TypeError` and |type|`ValueError` from module |mod|`inspect`." ] }, "Notes": { "Result": [ "The returned object mostly results from |func|`inspect.get_annotations`,", "but may be extended with type parameters for Python 3.12+." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_773fff84b12e2cae6b8bd52e9a9bf7f8fcd3c1390bb6ea2269437f4ce6853ec8" ] }, "sdv.doc.waterloo.docitem_helper.get_obj_decorators": { "signature": { "text": "get_obj_decorators(obj: 'object') -> 'List[str]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "List[str]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST return the decorator lines from the source text of a callable object, if available." ] }, "Parameters": { "obj": [ "The callable object whose decorator lines should be extracted." ] }, "Returns": [ "A list of source lines that start with |lit|`@`." ], "Raises": { "BaseException": [ "MAY propagate exceptions from |func|`inspect.getsource` or source retrieval." ] }, "Notes": { "Implementation": [ "This is a best-effort implementation that may fail for built-ins, C-extensions,", "or dynamically generated callables, in which case it returns an empty list.", "It is based on |func|`inspect.getsource` and reading the source lines." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_a2ef5f2d8798e9f71a33671d17e91a885197cca3f11c2211871ab30105fbe480" ] }, "sdv.doc.waterloo.docitem_helper.gen_documentable_objects": { "signature": { "text": "gen_documentable_objects(obj: 'Documentable', config: 'ConfigTraversal' = ConfigTraversal()) -> 'Generator[Documentable, None, None]'", "parameters": [ { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Documentable", "default": null }, { "name": "config", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "ConfigTraversal", "default": "ConfigTraversal()" } ], "returns": "Generator[Documentable, None, None]" }, "traits": [ "generator" ], "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST create a generator object which allows depth-first tree traversal of objects in |var|`obj`.", "MUST first yield object |var|`obj` itself.", "MUST yield all objects and only objects which can have a docstring." ] }, "Parameters": { "obj": [ "The object (module, class, function, method) to examine." ], "config": [ "Controls acceptance or refusal of objects during traversal." ] }, "Returns": [ "MUST return a Generator which yields objects from tree traversal of |var|`obj`" ], "Raises": {} }, "examples": [ "/__WTRL_EXAMPLES__/sha256_5b8bafdfe320f94e617fe049cc57f150754e08afdcba39aa223c9f6213b9bdce" ] }, "sdv.doc.waterloo.docitem_helper.tracer.Context": { "doc": {}, "doc_lines": [ "A list of strings built per context manager during parsing and validation. Entries can be module, class or function names, or labels." ], "annotation": "List[str]", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.tracer": { "signature": { "text": "tracer.__init__(self) -> 'None'", "parameters": [], "returns": "None" }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Public_types", "Public_classes", "Public_methods" ] }, "Terminology": { "rules on fail": [ "Low-level functions may find a parsing or validation warning or error,", "but have no clue which rule has been violated. The |dfn|`rules on fail`", "mechanism allows the caller to pass the set of rules in question.", "The tracer provides a stack and api for these rule sets." ] }, "Contract": { "general": [ "MUST provide a string-valued stack API for storing context data, like \"which object/section/subsection are we in?\".", "MUST provide a to-string method for rendering the context.", "MUST maintain a list of infos, where each entry is a tuple consisting of context, origin, and a free-form message.", "MUST provide a method for adding such a info entry.", "MUST allow to query if infos have been added.", "MUST provide a method for clearing the list of infos.", "MUST provide a method for rendering the list of infos as a string.", "MUST provide a generator which allows iterating over the list of infos.", "MUST maintain a list of warnings, where each entry is a tuple consisting of context, one Rule-ID, origin, a free-form message, and optional details.", "MUST provide a method for adding such a warning entry.", "MUST allow to query if warnings have been added.", "MUST provide a method for clearing the list of warnings.", "MUST provide a method for rendering the list of warnings as a string.", "MUST provide a generator which allows iterating over the list of warnings.", "MUST maintain a list of errors, where each entry is a tuple consisting of context, one Rule-ID, origin, a free-form message, and optional details.", "MUST provide a method for adding such a error entry.", "MUST allow to query if errors have been added.", "MUST provide a method for clearing the list of errors.", "MUST provide a method for rendering the list of errors as a string.", "MUST provide a generator which allows iterating over the list of errors.", "MUST manage a set of ignore-rule instructions", "MUST provide a stack containing the current |dfn|`rule on fail` being validated against.", "MUST provide an api like |func|`push...`, |func|`pop...`, |func|`get...` for the |dfn|`rule on fail` stack.", "MUST provide a stack containing the current set of |dfn|`scopes` being validated against.", "MUST provide an api like |func|`push...`, |func|`pop...`, |func|`get...` for the |dfn|`scopes` stack." ], "constructor": [ "MUST be default-constructible." ] }, "Public_types": { "Context": [ "A list of strings built per context manager during parsing and validation. Entries can be module, class or function names, or labels." ] }, "Public_classes": [ "Severity" ], "Class_overview": { "Severity": [ "An enum with values DEBUG, INFO, WARNING, ERROR for filtering the output of the tracer." ] }, "Public_methods": [ "build_json", "str_by_severity" ], "Method_overview": { "build_json": [ "Build a JSON-serializable |type|`dict` containing the", "information in the tracer, filtered by severity and optionally enriched by metadata." ] }, "Notes": { "Last review": [ "2026-06-21" ], "Parameter 'details'": [ "The details payload is important for the MCP server, because it gives the LLM enough debugging context to interpret tracer output and decide how to react to it.", "It usually is a dict with keys \"found\", \"expected\", and \"hint\"; \"hint\" typically contains a waterlint call for retrieving more information about the affected section or subsection." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_72d5c54eee565eb6c0d4cb56cc742b09f5936b5ddae1c1beca8cf0c7ac0ed6af" ] }, "sdv.doc.waterloo.docitem_helper.tracer.Severity": { "signature": { "text": "object.__init__(self, /, *args, **kwargs)", "parameters": [ { "name": "args", "kind": "VAR_POSITIONAL", "annotation": null, "default": null }, { "name": "kwargs", "kind": "VAR_KEYWORD", "annotation": null, "default": null } ], "returns": null }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Derived_from" ] }, "Contract": { "general": [ "MUST define the following severity levels for filtering the tracer's output:", "|value|`DEBUG`: for debugging notes, not relevant for end-users.", "|value|`INFO`: for informational messages that are relevant for end-users but do not indicate any problems.", "|value|`WARNING`: for potential issues that should be looked at but do not necessarily indicate a failure.", "|value|`ERROR`: for definite problems that indicate a failure to meet a requirement or rule.", "MUST assign integer values to these levels in increasing order of severity, starting with 0 for DEBUG." ], "constructor": [ "MUST inherit from |type|`IntEnum`." ] }, "Derived_from": [ "IntEnum" ] } }, "sdv.doc.waterloo.docitem_helper.tracer.str_by_severity": { "signature": { "text": "tracer.str_by_severity(self, severity: 'Severity') -> 'str'", "parameters": [ { "name": "severity", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Severity", "default": null } ], "returns": "str" }, "doc": { "Preamble": { "profile": "method", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST render the tracer's content as a human-readable string, filtered by severity level.", "MUST include entries with severity level equal to or higher than the specified level.", "MUST format entries with clear labels and context for easy understanding." ] }, "Parameters": { "severity": [ "Only include entries with this severity level or higher.", "Levels are ordered as DEBUG < INFO < WARNING < ERROR." ] }, "Returns": [ "A string representation of the tracer's content, including entries", "up to the specified severity level, formatted for human readability." ], "Raises": {}, "Notes": { "Called by": [ "This method is invoked by the __str__ method, which defaults to showing all entries (DEBUG level),", "so generally you simply call |func|`str`(tracer_instance) to get the full content", "or |func|`print`(tracer_instance) to display it." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_56211f2efa6fd6d425503e0c1875f7acf1707da7d1bdf7c70a5169b9e4082c49" ] }, "sdv.doc.waterloo.docitem_helper.tracer.build_json": { "signature": { "text": "tracer.build_json(self, severity: 'Severity', *, schema_version: 'str | None' = None, waterloo_version: 'str | None' = None, id_prefix: 'str | None' = None, include_debug: 'bool' = True) -> 'dict[str, Any]'", "parameters": [ { "name": "severity", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Severity", "default": null }, { "name": "schema_version", "kind": "KEYWORD_ONLY", "annotation": "str | None", "default": "None" }, { "name": "waterloo_version", "kind": "KEYWORD_ONLY", "annotation": "str | None", "default": "None" }, { "name": "id_prefix", "kind": "KEYWORD_ONLY", "annotation": "str | None", "default": "None" }, { "name": "include_debug", "kind": "KEYWORD_ONLY", "annotation": "bool", "default": "True" } ], "returns": "dict[str, Any]" }, "doc": { "Preamble": { "profile": "method", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST build a JSON-serializable |type|`dict` containing the tracer's data, following the WTRL Tracer JSON Schema.", "MUST include entries up to the specified severity level.", "MUST allow including debug notes optionally, as they may contain sensitive or verbose information.", "MUST include schema version and optionally Waterloo version in the metadata section." ] }, "Parameters": { "severity": [ "Only include entries with this severity level or higher.", "Levels are ordered as DEBUG < INFO < WARNING < ERROR." ], "schema_version": [ "Specify the WTRL Tracer JSON Schema version to declare in the output. Defaults to the current version if not provided.", "This does not affect the structure of the output, which always follows the current schema.", "Including the schema version allows consumers to validate against the correct schema and maintain compatibility as the schema evolves.", "* MUST be a string in the format |lit|`X.Y.Z` where X, Y, and Z are non-negative integers.", "* MUST default to the current schema version if not provided.", "* MUST be included in the output under the `__WTRL_VERSION__` metadata section.", "* MUST NOT affect the actual structure of the output, which always follows the current schema." ], "waterloo_version": [ "Optionally include the version of the Waterloo tool that generated the tracer data.", "* MUST be a string in the format |lit|`X.Y.Z` where X, Y, and Z are non-negative integers." ], "id_prefix": [ "Optionally include a prefix for the `$id` field in the output JSON.", "* MUST be a string if provided.", "* MAY be omitted, in which case the `$id` field will not include a prefix." ], "include_debug": [ "Optionally include debug notes in the output JSON." ] }, "Returns": [ "A JSON-serializable |type|`dict` containing the tracer's data structured according to the WTRL Tracer JSON Schema,", "including entries up to the specified severity level and metadata about the schema and optionally the Waterloo version.", "The return value MUST conform to JSON Schema :file:`wtrl-tracer-json-X.Y.Z.schema.json` where X.Y.Z is the declared schema version." ], "Raises": {} }, "examples": [ "/__WTRL_EXAMPLES__/sha256_72d5c54eee565eb6c0d4cb56cc742b09f5936b5ddae1c1beca8cf0c7ac0ed6af" ] }, "sdv.doc.waterloo.docitem_helper.traced_section": { "signature": { "text": "traced_section(tr: 'tracer', name: 'str') -> 'Generator[None, None, None]'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "name", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "Generator[None, None, None]" }, "decorators": [ "@contextmanager" ], "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST temporarily push |var|`name` onto the tracer context unless it is already on top." ] }, "Parameters": { "tr": [ "The tracer whose context stack should be managed." ], "name": [ "The context name to push." ] }, "Returns": [ "A context manager yielding nothing." ], "Raises": {} }, "examples": [ "/__WTRL_EXAMPLES__/sha256_7248e61dd3fdaf5e0aacdd245b5ae5a8a8dfeb46031f847e56061ae47aa71fe2" ] }, "sdv.doc.waterloo.docitem_helper.rule_on_fail": { "signature": { "text": "rule_on_fail(tr: 'tracer', rule_id: 'RuleId') -> 'Generator[None, None, None]'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId", "default": null } ], "returns": "Generator[None, None, None]" }, "decorators": [ "@contextmanager" ], "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST temporarily push the given rule identifier onto the tracer's rule-on-fail stack." ] }, "Parameters": { "tr": [ "The tracer whose failure-rule stack should be managed." ], "rule_id": [ "The rule identifier to push for the duration of the context." ] }, "Returns": [ "A context manager yielding nothing." ], "Raises": {} }, "examples": [ "/__WTRL_EXAMPLES__/sha256_b55749001e6c78aa3a23329f9c18e39d017399a71fbdb0d129168407025d2e03" ] }, "sdv.doc.waterloo.docitem_helper.DocSession.Seen": { "doc": {}, "doc_lines": [ "Objects already processed in the current run." ], "annotation": "dict[object, Any]", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.DocSession.Validated": { "doc": {}, "doc_lines": [ "Objects successfully validated in the current run." ], "annotation": "dict[object, Any]", "doc_lines_kind": "type" }, "sdv.doc.waterloo.docitem_helper.DocSession": { "signature": { "text": "DocSession.__init__(self) -> 'None'", "parameters": [], "returns": "None" }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract", "Public_types" ] }, "Contract": { "general": [ "MUST provide per-run state for validation and parsing operations.", "MUST remember already validated objects in order to avoid recursion divergence.", "MUST offer a stable place for future per-run caches and statistics data." ], "constructor": [ "MUST be default-constructible." ] }, "Public_types": { "Seen": [ "Objects already processed in the current run." ], "Validated": [ "Objects successfully validated in the current run." ] } } }, "sdv.doc.waterloo.docitem_helper.ResolveObjectError": { "signature": { "text": "ResolveObjectError.__init__(self, ref: 'str', current_obj: 'object', candidates: 'Sequence[str] | None' = None, last_candidate: 'str | None' = None, last_error: 'Exception | None' = None, msg: 'str | None' = None) -> 'None'", "parameters": [ { "name": "ref", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "current_obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null }, { "name": "candidates", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Sequence[str] | None", "default": "None" }, { "name": "last_candidate", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str | None", "default": "None" }, { "name": "last_error", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Exception | None", "default": "None" }, { "name": "msg", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str | None", "default": "None" } ], "returns": "None" }, "doc": { "Preamble": { "profile": "class", "normative_sections": [ "Contract" ] }, "Contract": { "general": [ "MUST be an exception class for errors during reference resolution." ], "constructor": [ "MUST accept the following positional parameters:", "* |var|`ref`: the reference string that was attempted to resolve.", "* |var|`current_obj`: the object from which the reference was being resolved.", "* |var|`candidates`: an optional list of candidate strings that were considered during resolution.", "* |var|`last_candidate`: an optional string representing the last candidate that was attempted before failure.", "* |var|`last_error`: an optional exception representing the last error encountered during resolution attempts.", "* |var|`msg`: an optional custom error message. If not provided, a default message should be constructed using |var|`ref` and |var|`current_obj`." ] }, "Notes": { "Callsites": [ "Various waterlint components." ] } } }, "sdv.doc.waterloo.docitem_helper.raise_has_no_docstring": { "signature": { "text": "raise_has_no_docstring(tr: 'tracer', rule_id: 'RuleId', obj: 'object') -> 'NoReturn'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId", "default": null }, { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null } ], "returns": "NoReturn" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST raise a parsing error that states that the object has no docstring." ] }, "Parameters": { "tr": [ "The tracer that should receive the error." ], "rule_id": [ "The rule identifier to report." ], "obj": [ "The object whose missing docstring should be reported." ] }, "Returns": [ "Never returns." ], "Raises": { "ParseError": [ "Always raised." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_acf076f743f65d019f80602ae5b7d6e7a150265594e37d57d9dca1ee6dfe92fc" ] }, "sdv.doc.waterloo.docitem_helper.raise_parsing_error": { "signature": { "text": "raise_parsing_error(tr: 'tracer', rule_id: 'RuleId', msg: 'str', details: 'Details | None' = None) -> 'NoReturn'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId", "default": null }, { "name": "msg", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "details", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Details | None", "default": "None" } ], "returns": "NoReturn" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST raise a parsing error with the given message and optional diagnostic details." ] }, "Parameters": { "tr": [ "The tracer that should receive the error." ], "rule_id": [ "The rule identifier to report." ], "msg": [ "The parsing error message." ], "details": [ "Additional diagnostic details." ] }, "Returns": [ "Never returns." ], "Raises": { "ParseError": [ "Always raised." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_acf076f743f65d019f80602ae5b7d6e7a150265594e37d57d9dca1ee6dfe92fc" ] }, "sdv.doc.waterloo.docitem_helper.raise_parsing_error_expected_but_got": { "signature": { "text": "raise_parsing_error_expected_but_got(tr: 'tracer', rule_id: 'RuleId', expected: 'str', got: 'str', details: 'dict[str, Any] | None' = None) -> 'NoReturn'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId", "default": null }, { "name": "expected", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "got", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "details", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "dict[str, Any] | None", "default": "None" } ], "returns": "NoReturn" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST raise a parsing error that compares the expected and actual values." ] }, "Parameters": { "tr": [ "The tracer that should receive the error." ], "rule_id": [ "The rule identifier to report." ], "expected": [ "The expected textual value." ], "got": [ "The actual textual value." ], "details": [ "Optional diagnostic details to attach to the tracer error." ] }, "Returns": [ "Never returns." ], "Raises": { "ParseError": [ "Always raised." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_acf076f743f65d019f80602ae5b7d6e7a150265594e37d57d9dca1ee6dfe92fc" ] }, "sdv.doc.waterloo.docitem_helper.raise_validation_error": { "signature": { "text": "raise_validation_error(tr: 'tracer', obj: 'object', rule_id: 'RuleId', msg: 'str', details: 'Details | None' = None) -> 'NoReturn'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId", "default": null }, { "name": "msg", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "details", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Details | None", "default": "None" } ], "returns": "NoReturn" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST raise a validation error with the given message and optional diagnostic details." ] }, "Parameters": { "tr": [ "The tracer that should receive the error." ], "obj": [ "The object being validated." ], "rule_id": [ "The rule identifier to report." ], "msg": [ "The validation error message." ], "details": [ "Additional diagnostic details." ] }, "Returns": [ "Never returns." ], "Raises": { "ValidationError": [ "Always raised." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_acf076f743f65d019f80602ae5b7d6e7a150265594e37d57d9dca1ee6dfe92fc" ] }, "sdv.doc.waterloo.docitem_helper.raise_validation_error_expected_but_got": { "signature": { "text": "raise_validation_error_expected_but_got(tr: 'tracer', obj: 'object', rule_id: 'RuleId', expected: 'str', got: 'str') -> 'NoReturn'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId", "default": null }, { "name": "expected", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "got", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "NoReturn" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST raise a validation error that compares the expected and actual values." ] }, "Parameters": { "tr": [ "The tracer that should receive the error." ], "obj": [ "The object being validated." ], "rule_id": [ "The rule identifier to report." ], "expected": [ "The expected textual value." ], "got": [ "The actual textual value." ] }, "Returns": [ "Never returns." ], "Raises": { "ValidationError": [ "Always raised." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_acf076f743f65d019f80602ae5b7d6e7a150265594e37d57d9dca1ee6dfe92fc" ] }, "sdv.doc.waterloo.docitem_helper.get_allowed_sections_for_profile": { "signature": { "text": "get_allowed_sections_for_profile(profile: 'str') -> 'list[str]'", "parameters": [ { "name": "profile", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "list[str]" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST return the list of section labels that are allowed for the given profile." ] }, "Parameters": { "profile": "The docstring profile label." }, "Returns": [ "The allowed top-level section labels for the profile." ], "Raises": {} } }, "sdv.doc.waterloo.docitem_helper.raise_validation_error_invalid_normative_section": { "signature": { "text": "raise_validation_error_invalid_normative_section(tr: 'tracer', obj: 'object', rule_id: 'RuleId | None', sec: 'str', normative_sections: 'Iterable[str]', profile: 'str') -> 'NoReturn'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "obj", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "object", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId | None", "default": null }, { "name": "sec", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "normative_sections", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Iterable[str]", "default": null }, { "name": "profile", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "NoReturn" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ] }, "Contract": { "general": [ "MUST raise a validation error for a normative section that is not allowed in the current profile." ] }, "Parameters": { "tr": [ "The tracer that should receive the error." ], "obj": [ "The object whose docstring should be validated." ], "rule_id": [ "An optional explicit rule identifier. If omitted, a profile-specific DOC rule is used." ], "sec": [ "The section label that is not allowed for the profile." ], "normative_sections": [ "The current normative section labels." ], "profile": "The docstring profile used to determine the allowed sections and hint." }, "Returns": [ "Never returns." ], "Raises": { "ValidationError": [ "Always raised." ] } } }, "sdv.doc.waterloo.docitem_helper.warn_parsing": { "signature": { "text": "warn_parsing(tr: 'tracer', rule_id: 'RuleId', msg: 'str') -> 'None'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId", "default": null }, { "name": "msg", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null } ], "returns": "None" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST record a parsing warning unless the rule is ignored." ] }, "Parameters": { "tr": [ "The tracer that should receive the warning." ], "rule_id": [ "The rule identifier to report." ], "msg": [ "The warning message." ] }, "Returns": [ "|None|" ], "Raises": {}, "Notes": { "Implementation": [ "This is a thin wrapper around |func|`tracer.add_warning` with origin set to |value|`\"parsing\"` and", "that checks if the rule is ignored before adding the warning." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_7248e61dd3fdaf5e0aacdd245b5ae5a8a8dfeb46031f847e56061ae47aa71fe2" ] }, "sdv.doc.waterloo.docitem_helper.warn_validation": { "signature": { "text": "warn_validation(tr: 'tracer', rule_id: 'RuleId', msg: 'str', details: 'Details | None' = None) -> 'None'", "parameters": [ { "name": "tr", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "tracer", "default": null }, { "name": "rule_id", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "RuleId", "default": null }, { "name": "msg", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "str", "default": null }, { "name": "details", "kind": "POSITIONAL_OR_KEYWORD", "annotation": "Details | None", "default": "None" } ], "returns": "None" }, "doc": { "Preamble": { "profile": "function", "normative_sections": [ "Contract", "Parameters", "Returns", "Raises" ], "scope": [ "public" ] }, "Contract": { "general": [ "MUST record a validation warning unless the rule is ignored." ] }, "Parameters": { "tr": [ "The tracer that should receive the warning." ], "rule_id": [ "The rule identifier to report." ], "msg": [ "The warning message." ], "details": [ "Optional structured diagnostics payload for the warning." ] }, "Returns": [ "|None|" ], "Raises": {}, "Notes": { "Implementation": [ "This is a thin wrapper around |func|`tracer.add_warning` with origin set to |value|`\"validation\"` and", "that checks if the rule is ignored before adding the warning." ] } }, "examples": [ "/__WTRL_EXAMPLES__/sha256_7248e61dd3fdaf5e0aacdd245b5ae5a8a8dfeb46031f847e56061ae47aa71fe2" ] } }, "__WTRL_EXAMPLES__": { "sha256_134892e694d296399fc3eea2716c5fca17c523cc0ec2d116575bdc8e7480e5c3": { "lang": "python", "hash": "134892e694d296399fc3eea2716c5fca17c523cc0ec2d116575bdc8e7480e5c3", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef test_regex() -> None:\n#----- Rule IDs -----------------------------------------------#\n\tprint(\"Regex RE_RULE_ID:\", h.RE_RULE_ID)\n\trule_ids_bad = [\n\t\t\"AB-12\", \"AB-123\", \"AB-1234\",\n\t\t\"ABC-12\", \"ABCD-12\",\n\t]\n\trule_ids_good = [\n\t\t\"ABC-123\", \"ABC-1234\",\n\t\t\"ABCD-123\", \"ABCD-1234\",\n\t\t\"ABCDE-123\", \"ABCDE-1234\",\n\t]\n\ttry:\n\t\tfor rule_id in rule_ids_bad:\n\t\t\tassert not h.RE_RULE_ID_COMPILED.match(rule_id), f\"Rule ID {rule_id} should not match the regex\"\n\t\t\t# print(f\"Match {rule_id}:\", h.RE_RULE_ID_COMPILED.match(rule_id))\n\t\tfor rule_id in rule_ids_good:\n\t\t\tassert h.RE_RULE_ID_COMPILED.match(rule_id), f\"Rule ID {rule_id} did not match the regex\"\n\texcept AssertionError as e:\n\t\tprint(\"Failed test:\", rule_id)\n\t\traise e\n\ntest_regex()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.RE_RULE_ID" ] }, "sha256_068c6155177172c3f292e2d499e111022b8688e8133c82812182b0f442214084": { "lang": "python", "hash": "068c6155177172c3f292e2d499e111022b8688e8133c82812182b0f442214084", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef test_regex() -> None:\n#----- [Qualified] Identifier ---------------------------------#\n\tprint(\"Regex RE_IDENTIFIER:\",h.RE_IDENTIFIER)\n\tprint(\"Regex RE_QUALIFIED_IDENTIFIER:\",h.RE_QUALIFIED_IDENTIFIER)\n\tidentifiers_bad = [\n\t\t\"a@b.c\", \"1abc\", \"abc-1\",\n\t\t\"abc.1\", \"abc..def\", \".abc\",\n\t\t\"abc.\", \"abc.def.\", \"abc..def\",\n\t\t\"abc.def..ghi\", \"abc.def.ghi.\"\n\t]\n\tidentifiers_good = [\n\t\t\"uvw_xyz\",\n\t\t\"_sdv_doc_item\",\n\t\t\"a_b_c_d\"\n\t]\n\tqualified_identifiers_good = [\n\t\t\"uvw_xyz\",\n\t\t\"sdv.doc.item\",\n\t\t\"a_b.c_d\",\n\t\t\"_._._\"\n\t]\n\ttry:\n\t\tfor i in identifiers_bad:\n\t\t\tassert not h.RE_IDENTIFIER_COMPILED.fullmatch(i), f\"Identifier {i} should not match the regex\"\n\t\t\tassert not h.RE_QUALIFIED_IDENTIFIER_COMPILED.fullmatch(i), f\"Qualified identifier {i} should not match the regex\"\n\t\tfor i in identifiers_good:\n\t\t\tassert h.RE_IDENTIFIER_COMPILED.fullmatch(i), f\"Identifier {i} did not match the regex\"\n\t\tfor i in qualified_identifiers_good:\n\t\t\tassert h.RE_QUALIFIED_IDENTIFIER_COMPILED.fullmatch(i), f\"Qualified identifier {i} did not match the regex\"\n\texcept AssertionError as e:\n\t\tprint(\"Failed test:\", i)\n\t\traise e\n\ntest_regex()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.RE_IDENTIFIER", "sdv.doc.waterloo.docitem_helper.RE_QUALIFIED_IDENTIFIER" ] }, "sha256_6d6be44016303793d2d91cde29e1a0a9dead9555b84f9616bf215b1c33aff749": { "lang": "python", "hash": "6d6be44016303793d2d91cde29e1a0a9dead9555b84f9616bf215b1c33aff749", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef test_regex() -> None:\n#----- CSV Identifiers ---------------------------------------#\n\tprint(\"Regex RE_CSV_IDENTIFIERS:\", h.RE_CSV_IDENTIFIERS)\n\tcsv_identifiers_bad = [\n\t\t\"abc,,def\", \"abc, ,def\", \"abc,def,\", \",abc,def\",\n\t\t\"abc,def,123\", \"abc,def,ghi!\", \"abc,def,ghi jkl\"\n\t]\n\tcsv_identifiers_good = [\n\t\t\"uvw_xyz\",\n\t\t\"uvw_xyz,abc_def\",\n\t\t\"uvw_xyz,abc_def,ghi_jkl\"\n\t]\n\ttry:\n\t\tfor i in csv_identifiers_bad:\n\t\t\tassert not h.RE_CSV_IDENTIFIERS_COMPILED.fullmatch(i), f\"CSV Identifiers {i} should not match the regex\"\n\t\tfor i in csv_identifiers_good:\n\t\t\tassert h.RE_CSV_IDENTIFIERS_COMPILED.fullmatch(i), f\"CSV Identifiers {i} did not match the regex\"\n\texcept AssertionError as e:\n\t\tprint(\"Failed test:\", i)\n\t\traise e\n\ntest_regex()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.RE_CSV_IDENTIFIERS" ] }, "sha256_769b2f56a62fd91ab8b4846412903f1862986aff74bc286fd13ed63a5fe16225": { "lang": "python", "hash": "769b2f56a62fd91ab8b4846412903f1862986aff74bc286fd13ed63a5fe16225", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef test_regex() -> None:\n#----- Markup with backticks ---------------------------------#\n\tprint(\"Regex RE_WTRL_MARKUP_BACKTICK:\", h.RE_WTRL_MARKUP_BACKTICK)\n\tmarkup_bad = [\n\t\t\"|unknown|`text`\", \"|type|text\", \"type|`text`\",\n\t\t\"|type|`text\", \"|type|text`\", \"type|text`\",\n\t\t\"|type|`text` more text\", \"more text |type|`text`\",\n\t\t\"|type|`text`|type|`text`\",\"|type| `text`\",\n\t\t\"|type |`text`\",\"| type|`text`\"\n\t]\n\tmarkup_good = [\n\t\t\"|type|`int`\", \"|func|`my_function`\", \"|var|`my_variable`\",\n\t\t\"|attr|`my_attribute`\", \"|cmd|`my_command`\", \"|dfn|`my_definition`\",\n\t\t\"|file|`my_file`\", \"|key|`my_key`\", \"|label|`my_label`\", \"|lit|`my_literal`\",\n\t\t\"|mod|`my_module`\", \"|norm|`my_norm`\", \"|op|`my_operator`\", \"|opt|`my_option`\",\n\t\t\"|ref|`my_reference`\", \"|tag|`my_tag`\", \"|term|`my_term`\", \"|type|`my_type`\",\n\t\t\"|var_type|`myvar:mytype`\"\n\t]\n\ttry:\n\t\tfor i in markup_bad:\n\t\t\tassert not h.RE_WTRL_MARKUP_BACKTICK_COMPILED.fullmatch(i), f\"Markup {i} should not match the regex\"\n\t\tfor i in markup_good:\n\t\t\tassert h.RE_WTRL_MARKUP_BACKTICK_COMPILED.fullmatch(i), f\"Markup {i} did not match the regex\"\n\texcept AssertionError as e:\n\t\tprint(\"Failed test:\", i)\n\t\traise e\n\ntest_regex()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.RE_WTRL_MARKUP_BACKTICK" ] }, "sha256_1578269401876a2fc905574d4853cb14ee3efbe6c7bdc71bb34eb9b270380e70": { "lang": "python", "hash": "1578269401876a2fc905574d4853cb14ee3efbe6c7bdc71bb34eb9b270380e70", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef test_regex() -> None:\n#----- References --------------------------------------------#\n\tprint(\"Regex RE_WTRL_ANGLE_HTTPS_REF:\", h.RE_WTRL_ANGLE_HTTPS_REF)\n\twtrl_angle_https_refs_bad = [\n\t\t\"\", \"\", \"\",\n\t\t\"\", \"\", \"\",\n\t\t\"\", \"\"\n\t]\n\twtrl_angle_https_refs_good = [\n\t\t\"label \", \"label \",\n\t\t\"label \", \"label\",\n\t\t\"label \", \"label \"\n\t]\n\ttry: \n\t\tfor i in wtrl_angle_https_refs_bad:\n\t\t\tassert not h.RE_WTRL_ANGLE_HTTPS_REF_COMPILED.fullmatch(i), f\"Angle HTTPS reference {i} should not match the regex\"\n\t\tfor i in wtrl_angle_https_refs_good:\n\t\t\tassert h.RE_WTRL_ANGLE_HTTPS_REF_COMPILED.fullmatch(i), f\"Angle HTTPS reference {i} did not match the regex\"\n\texcept AssertionError as e:\n\t\tprint(\"Failed test:\", i)\n\t\traise e\n\ntest_regex()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.RE_WTRL_ANGLE_HTTPS_REF" ] }, "sha256_777b32bdb96bdcef4ecebd399607674893cc0d508a6a9563b6d31b6ecf2e8c75": { "lang": "python", "hash": "777b32bdb96bdcef4ecebd399607674893cc0d508a6a9563b6d31b6ecf2e8c75", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\n#----- Tabular representation of SECTION_PROPERTIES -----------#\ndef render_as_table() -> None:\n\t# Measure column widths first so the output stays aligned.\n\tcolw = {}\n\t# Gap between columns.\n\tgap = 2\n\t# Build table head.\n\tthead = {\n\t\t\"category\": \"Category\",\n\t\t\"normativity\": \"Normativity\",\n\t\t\"label_kind\": \"Label kind\",\n\t\t\"profile\": \"Profile\",\n\t\t\"must_exist\": \"Must exist\",\n\t\t\"hint\": \"Hint\",\n\t\t}\n\t# Merge the artificial header row with the actual data rows.\n\trows = {\"Label\": thead} | h.SECTION_PROPERTIES\n\tfor label, line in rows.items():\n\t\tcolw[\"label\"] = max(colw[\"label\"] if \"label\" in colw else 0, len(str(label)))\n\t\tfor key in line:\n\t\t\tcolw[key] = max(colw[key] if key in colw else 0, len(str(line[key])))\n\t# Render table.\n\tstart = True\n\tfor label, line in rows.items():\n\t\tif start:\n\t\t\tstart = False\n\t\tprint(label + \" \" * (colw[\"label\"] - len(label) + gap), end=\"\")\n\t\tfor key in line:\n\t\t\ttd = str(line[key])\n\t\t\tprint(td + \" \" * (colw[key] - len(td) + gap), end=\"\")\n\t\tprint()\n\nrender_as_table()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.SECTION_PROPERTIES" ] }, "sha256_602a470e833e907c43808fab7db1d2d9c489ac3eba11ba56d99de7e17163dd2f": { "lang": "python", "hash": "602a470e833e907c43808fab7db1d2d9c489ac3eba11ba56d99de7e17163dd2f", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\n#----- Simple example, function exploring itself --------------#\ndef test_get_source_docstring() -> None:\n\t\"\"\"A simple docstring.\"\"\"\n\tprint(\"source docstring:\", h.get_source_docstring(test_get_source_docstring))\n\ntest_get_source_docstring()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_source_docstring" ] }, "sha256_72d5c54eee565eb6c0d4cb56cc742b09f5936b5ddae1c1beca8cf0c7ac0ed6af": { "lang": "python", "hash": "72d5c54eee565eb6c0d4cb56cc742b09f5936b5ddae1c1beca8cf0c7ac0ed6af", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\nimport sys,json\n\n# Dump a tracer as JSON for demonstration purposes.\ndef test_tracer() -> None:\n\ttr = h.tracer()\n# The tracer collects messages from deep inside\n# the docitem parsing or validation process.\n# Make sure to provide a meaningful tag at each scope.\n\twith h.traced_section(tr,\"Path\"):\n\t\twith h.traced_section(tr,\"To\"):\n# Demonstrate the context stack.\n\t\t\twith h.traced_section(tr,\"Context1\"):\n\t\t\t\ttr.add_debug_note(\"A debug entry\",\"test\")\n\n\t\t\twith h.traced_section(tr,\"Context2\"):\n\t\t\t\ttr.add_info(\"An info\",\"test\")\n\n\t\t\twith h.traced_section(tr,\"Context3\"):\n\t\t\t\ttr.add_warning(\"ABC-123\",\"test\",\"A warning\")\n\n\t\t\twith h.traced_section(tr,\"Context4\"):\n\t\t\t\ttr.add_error(\"DEF-456\",\"test\",\"An error\")\n\n\t\t\tjson.dump(tr.build_json(tr.Severity.DEBUG),sys.stdout, indent=4)\n\t\t\tprint()\n\ntest_tracer()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.tracer", "sdv.doc.waterloo.docitem_helper.tracer.build_json" ] }, "sha256_56211f2efa6fd6d425503e0c1875f7acf1707da7d1bdf7c70a5169b9e4082c49": { "lang": "python", "hash": "56211f2efa6fd6d425503e0c1875f7acf1707da7d1bdf7c70a5169b9e4082c49", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef test_tracer() -> None:\n\ttr = h.tracer()\n\t# The tracer collects messages from deep inside the docitem parsing or\n\t# validation process. Provide a meaningful tag at each scope.\n\ttr.push(\"Path\")\n\ttr.push(\"To\")\n\ttr.push(\"Context\")\n\n\t# Add messages with the expected argument order.\n\ttr.add_debug_note(\"A debug entry\",\"test\")\n\ttr.add_info(\"An info\",\"test\")\n\t# Pass rule id, origin, message.\n\ttr.add_warning(\"ABC-123\",\"test\",\"A warning\")\n\ttr.add_error(\"DEF-456\",\"test\",\"An error\")\n\n\tprint(tr)\n\ntest_tracer()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.tracer.str_by_severity" ] }, "sha256_4492b7b0c534e25149d57bd029f106019dbac863464599cd59cd5a43b7218aa0": { "lang": "python", "hash": "4492b7b0c534e25149d57bd029f106019dbac863464599cd59cd5a43b7218aa0", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\n# A self-referential test.\n# It should produce the anchor for this function itself.\ndef test_build_anchor() -> None:\n\tprint(\"build_anchor:\", h.build_anchor(h.build_anchor))\n\ntest_build_anchor()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.build_anchor" ] }, "sha256_773fff84b12e2cae6b8bd52e9a9bf7f8fcd3c1390bb6ea2269437f4ce6853ec8": { "lang": "python", "hash": "773fff84b12e2cae6b8bd52e9a9bf7f8fcd3c1390bb6ea2269437f4ce6853ec8", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\nimport sys, json\n\ndef test_get_obj_annotations() -> None:\n\tprint(\"Annotations for get_obj_annotations:\")\n\tjson.dump(h.get_obj_annotations(h.get_obj_annotations), sys.stdout, indent=4)\n\tprint()\n\ntest_get_obj_annotations()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_obj_annotations" ] }, "sha256_4b683772b0a0b115616e98c77b6586f229e04c469e8fdebe5d18f7d69fc79b22": { "lang": "python", "hash": "4b683772b0a0b115616e98c77b6586f229e04c469e8fdebe5d18f7d69fc79b22", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\nclass X:\n\tclass Y:\n\t\tclass Z:\n\t\t\t@classmethod\n\t\t\tdef test(cls) -> None:\n\t\t\t\tprint(\"classmethod:\", h.get_obj_fully_qualified_name(cls.test))\n\nX.Y.Z.test()\n# Result: classmethod: __main__.X.Y.Z.test\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_obj_fully_qualified_name" ] }, "sha256_1430a8f116b0fa6e3670f59c04d646f41b25fded4a0320f30bba38dab49a8239": { "lang": "python", "hash": "1430a8f116b0fa6e3670f59c04d646f41b25fded4a0320f30bba38dab49a8239", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\nclass Z:\n\tpass\n\nclass X:\n\tdef __init__(self):\n\t\tself._p = 3\n\n\t@classmethod\n\tdef m_cls(cls) -> None:\n\t\tpass\n\t@staticmethod\n\tdef m_stat(cls) -> None:\n\t\tpass\n\tdef m(self) -> None:\n\t\tpass\n\tclass Y:\n\t\tpass\n\ty = Y()\n\tz = Z()\n\n\t@property\n\tdef p(self):\n\t\treturn self._p\n\t@p.setter\n\tdef p(self, val):\n\t\tself._p = val\n\n\ndef f() -> None:\n\tpass\n\nx = X()\nprint(\"class:\", h.get_obj_fully_qualified_name(X))\nprint(\"instance:\", h.get_obj_fully_qualified_name(x))\nprint(\"classmethod:\", h.get_obj_fully_qualified_name(X.m_cls))\nprint(\"staticmethod:\", h.get_obj_fully_qualified_name(X.m_stat))\nprint(\"bound method:\", h.get_obj_fully_qualified_name(x.m))\nprint(\"module function:\", h.get_obj_fully_qualified_name(f))\nprint(\"nested class:\", h.get_obj_fully_qualified_name(X.Y))\nprint(\"nested class via instance:\", h.get_obj_fully_qualified_name(x.Y))\n\nprint(\"nested instance via instance:\", h.get_obj_fully_qualified_name(x.y))\nprint(\"nested instance via class:\", h.get_obj_fully_qualified_name(X.y))\n\n# See limitations: nested instances should not be passed.\nprint(\"nested class attr via class:\", h.get_obj_fully_qualified_name(X.z))\nprint(\"nested class attr via instance:\", h.get_obj_fully_qualified_name(x.z))\n\nprint(\"property instance:\", h.get_obj_fully_qualified_name(x.p))\nprint(\"property setter:\", h.get_obj_fully_qualified_name(X.p.setter))\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_obj_fully_qualified_name" ] }, "sha256_ff67bb22509a88a9560af9d3c18742210d3cb38ab23c9f38e7f72e3856ff1c0d": { "lang": "python", "hash": "ff67bb22509a88a9560af9d3c18742210d3cb38ab23c9f38e7f72e3856ff1c0d", "code": "#!/usr/bin/env python3\n\nfrom __future__ import annotations\nfrom typing import Generator\nimport math\nimport sdv.doc.waterloo.docitem_helper as h\n\n# Excerpts from the contract:\n# Must handle functions at module level.\ndef f() -> None:\n\tpass\n\n# Must handle generators\ndef g() -> Generator[int,None,None]:\n\tyield 42\n\nclass X:\n\tdef __call__(self) -> None:\n\t\tprint(\"Hello Kitty\")\n\t# Must handle functions in classes without decorators.\n\tdef m() -> None:\n\t\tpass\n\t# Must handle functions in classes with decorator `@classmethod`.\n\t@classmethod\n\tdef m_cls(cls) -> None:\n\t\tpass\n\t# Must handle functions in classes with decorator `@staticmethod`.\n\t@staticmethod\n\tdef m_stat(cls) -> None:\n\t\tpass\n\t# Must handle generators\n\tdef g() -> Generator[int,None,None]:\n\t\tyield 42\n\ndef show(label: str, obj: object) -> None:\n\tprint(f\"{label}: {h.get_obj_fully_qualified_name(h.get_func_obj_from_callable(obj))}\")\n\ndef test_get_func_obj_from_callable() -> None:\n\tx = X()\n\tshow(\"class\", X)\n\tshow(\"module function\", f)\n\tshow(\"generator function\", g)\n\tshow(\"callable instance\", x)\n\tshow(\"instance method\", X.m)\n\tshow(\"classmethod\", X.m_cls)\n\tshow(\"staticmethod\", X.m_stat)\n\tshow(\"generator method\", X.g)\n\tshow(\"function helper\", h.get_func_obj_from_callable)\n\tshow(\"builtin math.sin\", math.sin)\n\tshow(\"builtin print\", print)\n\nif __name__ == \"__main__\":\n\ttest_get_func_obj_from_callable()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_func_obj_from_callable", "sdv.doc.waterloo.docitem_helper.get_obj_fully_qualified_name" ] }, "sha256_811282620191ed177eb3e85f6d15efb0cfa9d7a5982d4259cc77463cbdc0ac83": { "lang": "python", "hash": "811282620191ed177eb3e85f6d15efb0cfa9d7a5982d4259cc77463cbdc0ac83", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\nclass X:\n\t@classmethod\n\tdef m_cls(cls) -> None:\n\t\tpass\n\t@staticmethod\n\tdef m_stat(cls) -> None:\n\t\tpass\n\tdef m(self) -> None:\n\t\tpass\n\tclass Y:\n\t\tpass\n\ty = Y()\n\ndef f() -> None:\n\tpass\n\nx = X()\nprint(\"class:\", h.get_obj_name(X))\nprint(\"instance:\", h.get_obj_name(x))\nprint(\"classmethod:\", h.get_obj_name(X.m_cls))\nprint(\"staticmethod:\", h.get_obj_name(X.m_stat))\nprint(\"bound method:\", h.get_obj_name(x.m))\nprint(\"module function:\", h.get_obj_name(f))\nprint(\"nested class:\", h.get_obj_name(X.Y))\nprint(\"nested class via instance:\", h.get_obj_name(x.Y))\n\n# These two are a bit surprising, but seem to be irrelevant for the project.\nprint(\"nested instance via instance:\", h.get_obj_name(x.y))\nprint(\"nested instance via class:\", h.get_obj_name(X.y))\n\n# Same here. See section Notes.Limitations.\nprint(\"fq name for nested instance via instance:\", h.get_obj_fully_qualified_name(x.y))\nprint(\"fq name for nested instance via class:\", h.get_obj_fully_qualified_name(X.y))\n\nprint(\"runtime class name:\", x.y.__class__.__name__)\nprint(\"declared class name:\", X.Y.__name__)\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_obj_name" ] }, "sha256_51367d261eb1a4f032df6518aa4b5635980be001494fd5068011e170647147f8": { "lang": "python", "hash": "51367d261eb1a4f032df6518aa4b5635980be001494fd5068011e170647147f8", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\nclass X:\n\t@classmethod\n\tdef m_cls(cls) -> None:\n\t\tpass\n\t@staticmethod\n\tdef m_stat(cls) -> None:\n\t\tpass\n\tdef m(self) -> None:\n\t\tpass\n\tclass Y:\n\t\tpass\n\ty = Y()\n\ndef f() -> None:\n\tpass\n\n# All ten results are the same, as it should be.\nx = X()\nprint(\"class:\", h.get_obj_path(X))\nprint(\"instance:\", h.get_obj_path(x))\nprint(\"classmethod:\", h.get_obj_path(X.m_cls))\nprint(\"staticmethod:\", h.get_obj_path(X.m_stat))\nprint(\"bound method:\", h.get_obj_path(x.m))\nprint(\"module function:\", h.get_obj_path(f))\nprint(\"nested class:\", h.get_obj_path(X.Y))\nprint(\"nested class via instance:\", h.get_obj_path(x.Y))\n\nprint(\"nested instance via instance:\", h.get_obj_path(x.y))\nprint(\"nested instance via class:\", h.get_obj_path(X.y))\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_obj_path" ] }, "sha256_294ad917b357529f361ff629b3f0ba3c230afc966e738122ea903d1b4a23c379": { "lang": "python", "hash": "294ad917b357529f361ff629b3f0ba3c230afc966e738122ea903d1b4a23c379", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\nclass X:\n\t\"\"\"\n\tPreamble:\n\t\tprofile:\n\t\t\tclass\n\t\tnormative_sections:\n\t\t\tContract\n\tContract:\n\t\tgeneral:\n\t\tconstructor:\n\t\"\"\"\n\nif __name__ == \"__main__\":\n\tprint(\"docstring:\", h.get_obj_docstring(X))\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_obj_docstring" ] }, "sha256_3a34ca6470361aaea2fe620809e836bd00fcfb83d9c0687e65b1174b039cf3e7": { "lang": "python", "hash": "3a34ca6470361aaea2fe620809e836bd00fcfb83d9c0687e65b1174b039cf3e7", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef f() -> None:\n\tpass\n\nif __name__ == \"__main__\":\n\t# Both deliver the same result, module 'sdv.doc.waterloo.docitem_helper'.\n\tprint(\"module helper:\", h.get_obj_direct_module(h))\n\tprint(\"module helper function:\", h.get_obj_direct_module(h.get_obj_direct_module))\n\t# Module __main__ seems to cause trouble, but that is a special case\n\t# not relevant in practice.\n\tprint(\"module function f:\", h.get_obj_direct_module(f))\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_obj_direct_module" ] }, "sha256_a2ef5f2d8798e9f71a33671d17e91a885197cca3f11c2211871ab30105fbe480": { "lang": "python", "hash": "a2ef5f2d8798e9f71a33671d17e91a885197cca3f11c2211871ab30105fbe480", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\nclass X:\n\t@classmethod\n\tdef m_cls(cls) -> None:\n\t\tpass\n\t@staticmethod\n\tdef m_stat(cls) -> None:\n\t\tpass\n\nprint(\"classmethod decorators:\", h.get_obj_decorators(X.m_cls))\nprint(\"staticmethod decorators:\", h.get_obj_decorators(X.m_stat))\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.get_obj_decorators" ] }, "sha256_28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5": { "lang": "python", "hash": "28945dd0612fba8d6891610a15b49001b2eaa18be8a8de4dfff6e9416b3defe5", "code": "#!/usr/bin/env python3\n\nfrom __future__ import annotations\nfrom typing import TypeAlias\nimport sdv.doc.waterloo.docitem_helper as h\n\n# This file is intentionally a human-facing demo for the HTML documentation.\n# The same matrix is covered by a pytest in package_main/pytest/.\n# Keep the structure simple so the rendered HTML stays easy to read.\n\nclass X:\n\t# Instance/class/staticmethod examples plus a typed class attribute.\n\t@classmethod\n\tdef m_cls(cls) -> None:\n\t\tpass\n\t@staticmethod\n\tdef m_stat(cls) -> None:\n\t\tpass\n\tdef m(self) -> None:\n\t\tpass\n\tv: int = 42\n\tt: TypeAlias = int | float\n\ndef f() -> None:\n\tpass\n\n# The test set mirrors the documentation examples:\n# module, class, function, bound methods, static/class methods, variable, and type alias.\nfunctions_to_test = [\n\th.is_obj_module,\n\th.is_obj_class,\n\th.is_obj_function,\n\th.is_obj_method_like,\n\th.is_obj_named_value,\n\th.is_obj_documentable,\n\th.is_obj_annotatable\n\t]\n\n# The object matrix is printed as rows of booleans.\n# That makes it easy to compare the heuristic behavior across object kinds.\nobjects_to_test = [ h,X,f,X.m,X.m_cls,X.m_stat,X.v,X.t ]\n\nif __name__ == \"__main__\":\n\t# Header row for manual inspection in the terminal.\n\tprint(\" h X f X.m X.m_cls X.m_stat X.v X.t\")\n\tfor func in functions_to_test:\n\t\t# Each row is one predicate evaluated against all sample objects.\n\t\tprint(func.__name__ + \":\" + \" \" * (20 - len(func.__name__)),end='')\n\t\tfor obj in objects_to_test:\n\t\t\tprint(\"True \" if func(obj) else \"False\",end=' ')\n\t\tprint()\n\n# Expected results, kept as comments so the file doubles as a readable demo.\n# h X f X.m X.m_cls X.m_stat X.v X.t\n# is_obj_module: True False False False False False False False \n# is_obj_class: False True False False False False False False \n# is_obj_function: False False True True True True False False \n# is_obj_method_like: False False False True True True False False \n# is_obj_named_value: False False False False False False True True \n# is_obj_documentable: True True True True True True False False \n# is_obj_annotatable: True True True True True True False False\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.is_obj_annotatable", "sdv.doc.waterloo.docitem_helper.is_obj_class", "sdv.doc.waterloo.docitem_helper.is_obj_documentable", "sdv.doc.waterloo.docitem_helper.is_obj_function", "sdv.doc.waterloo.docitem_helper.is_obj_method_like", "sdv.doc.waterloo.docitem_helper.is_obj_module", "sdv.doc.waterloo.docitem_helper.is_obj_named_value" ] }, "sha256_7248e61dd3fdaf5e0aacdd245b5ae5a8a8dfeb46031f847e56061ae47aa71fe2": { "lang": "python", "hash": "7248e61dd3fdaf5e0aacdd245b5ae5a8a8dfeb46031f847e56061ae47aa71fe2", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef test_tracer() -> None:\n\ttr = h.tracer()\n\n\twith h.traced_section(tr, \"Path\"):\n\t\twith h.traced_section(tr, \"To\"):\n\t\t\twith h.traced_section(tr, \"Context\"):\n\t\t\t\th.warn_parsing(tr, \"ABC-123\", \"A warning raised during parsing\")\n\twith h.traced_section(tr, \"Other\"):\n\t\twith h.traced_section(tr, \"Path\"):\n\t\t\th.warn_validation(tr, \"ABC-123\", \"A warning raised during validation\")\n\n\tprint(tr)\n\ntest_tracer()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.traced_section", "sdv.doc.waterloo.docitem_helper.warn_parsing", "sdv.doc.waterloo.docitem_helper.warn_validation" ] }, "sha256_acf076f743f65d019f80602ae5b7d6e7a150265594e37d57d9dca1ee6dfe92fc": { "lang": "python", "hash": "acf076f743f65d019f80602ae5b7d6e7a150265594e37d57d9dca1ee6dfe92fc", "code": "#!/usr/bin/env python3\n\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef test_tracer() -> None:\n\ttr = h.tracer()\n\n\twith h.traced_section(tr, \"Path\"):\n\t\twith h.traced_section(tr, \"To\"):\n\t\t\twith h.traced_section(tr, \"Context\"):\n\t\t\t\ttry:\n\t\t\t\t\th.raise_has_no_docstring(tr, \"ABC-123\", test_tracer)\n\t\t\t\texcept Exception:\n\t\t\t\t\tpass\n\t\t\t\ttry:\n\t\t\t\t\th.raise_parsing_error(tr, \"ABC-123\", \"A message\", {\n\t\t\t\t\t\t\"found\": \"this\",\n\t\t\t\t\t\t\"expected\": \"that\",\n\t\t\t\t\t\t\"hint\": \"consult waterlint\",\n\t\t\t\t\t\t})\n\t\t\t\texcept Exception:\n\t\t\t\t\tpass\n\t\t\t\ttry:\n\t\t\t\t\th.raise_parsing_error_expected_but_got(tr, \"ABC-123\", \"that\", \"this\")\n\t\t\t\texcept Exception:\n\t\t\t\t\tpass\n\t\t\t\ttry:\n\t\t\t\t\th.raise_parsing_error_invalid_label(tr, \"ABC-123\", \"Conforming_to:\", [\"Preamble\", \"Contract\"])\n\t\t\t\texcept Exception:\n\t\t\t\t\tpass\n\t\t\t\ttry:\n\t\t\t\t\th.raise_validation_error(tr, test_tracer, \"ABC-123\", \"A message\", {\n\t\t\t\t\t\t\"found\": \"wrong section\",\n\t\t\t\t\t\t\"expected\": \"right section\",\n\t\t\t\t\t\t\"hint\": \"waterlint explain-section --label
--profile \",\n\t\t\t\t\t\t})\n\t\t\t\texcept Exception:\n\t\t\t\t\tpass\n\t\t\t\ttry:\n\t\t\t\t\th.raise_validation_error_expected_but_got(tr, test_tracer, \"ABC-123\", \"that\", \"this\")\n\t\t\t\texcept Exception:\n\t\t\t\t\tpass\n\tprint(tr)\n\ntest_tracer()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.raise_has_no_docstring", "sdv.doc.waterloo.docitem_helper.raise_parsing_error", "sdv.doc.waterloo.docitem_helper.raise_parsing_error_expected_but_got", "sdv.doc.waterloo.docitem_helper.raise_validation_error", "sdv.doc.waterloo.docitem_helper.raise_validation_error_expected_but_got" ] }, "sha256_5b8bafdfe320f94e617fe049cc57f150754e08afdcba39aa223c9f6213b9bdce": { "lang": "python", "hash": "5b8bafdfe320f94e617fe049cc57f150754e08afdcba39aa223c9f6213b9bdce", "code": "#!/usr/bin/env python3\n\nfrom __future__ import annotations\nimport sdv.doc.waterloo.docitem_helper as h\n\nconfig = h.ConfigTraversal()\nconfig.enable_include_imported()\nn = 0\nfor obj in h.gen_documentable_objects(h,config):\n\tprint(\"included:\", h.get_obj_fully_qualified_name(obj))\n\tn += 1\nprint(f\"Grand total with include_imported : {n} objects\")\n\nconfig = h.ConfigTraversal()\nn = 0\nfor obj in h.gen_documentable_objects(h,config):\n\tn += 1\nprint(f\"Grand total without include_imported: {n} objects\")\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.ConfigTraversal", "sdv.doc.waterloo.docitem_helper.gen_documentable_objects" ] }, "sha256_7c28b6182c139a657bab51b3d9e573953cd4603d8aff3d13d0e2ab23d4d0624f": { "lang": "python", "hash": "7c28b6182c139a657bab51b3d9e573953cd4603d8aff3d13d0e2ab23d4d0624f", "code": "#!/usr/bin/env python3\n\nfrom __future__ import annotations\nfrom typing import Any, TYPE_CHECKING\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef join_strings(values: list[Any]) -> str:\n\tif h.is_list_of_str(values):\n\t\t# mypy narrows `values` to `list[str]` in this branch.\n\t\tif TYPE_CHECKING:\n\t\t\t# h.is_list_of_str returns TypeGuard by annotation.\n\t\t\t# So, here we know at type checking that values is\n\t\t\t# a list of strings. mypy output is:\n\t\t\t# `note: Revealed type is \"list[str]\"`\n\t\t\treveal_type(values)\n\t\treturn \", \".join(values)\n\treturn \"\"\n\nassert join_strings([\"a\", \"b\"]) == \"a, b\"\nassert join_strings([1, 2]) == \"\"\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.is_list_of_str" ] }, "sha256_1f77d8b5ff9b65debb0fa04da3a9425c125f61dea821c67c5ed4a4841f4111e2": { "lang": "python", "hash": "1f77d8b5ff9b65debb0fa04da3a9425c125f61dea821c67c5ed4a4841f4111e2", "code": "#!/usr/bin/env python3\n\nfrom __future__ import annotations\nfrom typing import Final\nimport sdv.doc.waterloo.docitem_helper as h\n\ndef f(a: int, b: float) -> None:\n\tpass\n\nclass X:\n\tv: int = 42\n\tc: Final[float] = 1.23\n\n\t@staticmethod\n\tdef sm(a: int, b: float) -> None:\n\t\tpass\n\t@classmethod\n\tdef cm(cls, a: int, b: float) -> None:\n\t\tpass\n\tdef m1(self):\n\t\tpass\n\tdef m2(self, a: int, b: Final[float]) -> None:\n\t\tpass\n\n# Functions and methods expose parameter and return annotations.\nassert not h.is_attr_annotated(X.m1, \"return\")\nassert h.is_attr_annotated(f, \"a\")\nassert h.is_attr_annotated(f, \"b\")\nassert h.is_attr_annotated(f, \"return\")\n\n# Static and class methods behave like plain functions for annotations.\nassert h.is_attr_annotated(X.sm, \"a\")\nassert h.is_attr_annotated(X.sm, \"b\")\nassert h.is_attr_annotated(X.sm, \"return\")\n\nassert h.is_attr_annotated(X.cm, \"a\")\nassert h.is_attr_annotated(X.cm, \"b\")\nassert h.is_attr_annotated(X.cm, \"return\")\n\n# A method with annotations on both parameters and return value.\nassert h.is_attr_annotated(X.m2, \"a\")\nassert h.is_attr_annotated(X.m2, \"b\")\nassert h.is_attr_annotated(X.m2, \"return\")\n\n# Class attributes are also supported.\nassert h.is_attr_annotated(X, \"v\")\n\n# Final annotations are a separate helper, but the same object shapes apply.\nassert h.is_attr_final(h, \"CANONICAL_ORDER_OF_PROFILES\")\nassert h.is_attr_final(X, \"c\")\nassert h.is_attr_final(X.m2, \"b\")\nassert not h.is_attr_final(X.m2, \"a\")\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.is_attr_annotated", "sdv.doc.waterloo.docitem_helper.is_attr_final" ] }, "sha256_b55749001e6c78aa3a23329f9c18e39d017399a71fbdb0d129168407025d2e03": { "lang": "python", "hash": "b55749001e6c78aa3a23329f9c18e39d017399a71fbdb0d129168407025d2e03", "code": "#!/usr/bin/env python3\n\nfrom __future__ import annotations\nfrom typing import Generator,NoReturn\nimport sdv.doc.waterloo.docitem_helper as h\n\n# The function does not know which rule is violated,\n# but the caller has pushed it to the tracer's stack.\ndef some_deeper_function(tr) -> NoReturn:\n\ttr.add_error(tr.get_rule_on_fail(), \"test\", \"An error from a deeper function has occurred\")\n\ndef test_tracer() -> None:\n\ttr = h.tracer()\n\t# The tracer collects messages from deep inside the docitem parsing or\n\t# validation process. Make sure to provide a meaningful tag at each scope.\n\ttr.push(\"Path\")\n\ttr.push(\"To\")\n\ttr.push(\"Context\")\n\n\twith h.rule_on_fail(tr, \"XYZ-123\"):\n\t\tsome_deeper_function(tr)\n\n\ttr.pop()\n\ttr.pop()\n\ttr.pop()\n\n\tprint(tr)\n\ntest_tracer()\n", "referenced_by": [ "sdv.doc.waterloo.docitem_helper.rule_on_fail" ] } } }