# utils URL: /api/autodoc/utils/ Section: autodoc -------------------------------------------------------------------------------- utils - Bengal window.BENGAL_THEME_DEFAULTS = { appearance: 'dark', palette: 'snow-lynx' }; // Progressive Enhancement System Configuration window.Bengal = window.Bengal || {}; window.Bengal.enhanceBaseUrl = '/bengal/assets/js/enhancements'; window.Bengal.watchDom = true; window.Bengal.debug = false; (function () { try { var defaults = window.BENGAL_THEME_DEFAULTS || { appearance: 'system', palette: '' }; var defaultAppearance = defaults.appearance; if (defaultAppearance === 'system') { defaultAppearance = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'; } var storedTheme = localStorage.getItem('bengal-theme'); var storedPalette = localStorage.getItem('bengal-palette'); var theme = storedTheme ? (storedTheme === 'system' ? defaultAppearance : storedTheme) : defaultAppearance; var palette = storedPalette ?? defaults.palette; document.documentElement.setAttribute('data-theme', theme); if (palette) { document.documentElement.setAttribute('data-palette', palette); } } catch (e) { document.documentElement.setAttribute('data-theme', 'light'); } })(); Skip to main content Magnifying Glass ESC Recent Clear Magnifying Glass No results for "" Try different keywords or check your spelling Start typing to search... ↑↓ Navigate ↵ Open ESC Close Powered by Lunr ᓚᘏᗢ Documentation Info About Arrow Clockwise Get Started Note Tutorials File Text Content Palette Theming Settings Building Starburst Extending Bookmark Reference Learning Tracks Releases Dev GitHub API Reference bengal CLI Magnifying Glass Search ⌘K Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal List ᓚᘏᗢ Magnifying Glass Search X Close Documentation Info About Arrow Clockwise Get Started Note Tutorials File Text Content Palette Theming Settings Building Starburst Extending Bookmark Reference Learning Tracks Releases Dev GitHub API Reference bengal CLI Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal API Reference __main__ bengal Caret Right Folder Analysis community_detection graph_analysis graph_reporting graph_visualizer knowledge_graph link_suggestions link_types page_rank path_analysis performance_advisor results Caret Right Folder Assets manifest pipeline Caret Right Folder Autodoc base config docstring_parser utils virtual_orchestrator Caret Right Folder Extractors cli openapi python Caret Right Folder Models cli common openapi python Caret Right Folder Cache asset_dependency_map cache_store cacheable compression dependency_tracker page_discovery_cache query_index query_index_registry taxonomy_index utils Caret Right Folder Build Cache autodoc_tracking core file_tracking fingerprint parsed_content_cache rendered_output_cache taxonomy_index_mixin validation_cache Caret Right Folder Indexes author_index category_index date_range_index section_index Caret Right Folder Cli __main__ base site_templates utils Caret Right Folder Commands assets build clean collections config debug explain fix health init perf project serve site skeleton sources theme utils validate Caret Right Folder Graph __main__ bridges communities orphans pagerank report suggest Caret Right Folder New config presets scaffolds site wizard Caret Right Folder Helpers cli_app_loader cli_output config_validation error_handling menu_config metadata progress site_loader traceback validation Caret Right Folder Skeleton hydrator schema Caret Right Folder Templates base registry Caret Right Folder Blog template Caret Right Folder Changelog template Caret Right Folder Default template Caret Right Folder Docs template Caret Right Folder Landing template Caret Right Folder Portfolio template Caret Right Folder Resume template Caret Right Folder Collections errors loader schemas validator Caret Right Folder Config defaults deprecation directory_loader env_overrides environment feature_mappings hash loader merge origin_tracker validators Caret Right Folder Content Layer entry loaders manager source Caret Right Folder Sources github local notion rest Caret Right Folder Content Types base registry strategies Caret Right Folder Core build_context cascade_engine menu section theme Caret Right Folder Asset asset_core css_transforms Caret Right Folder Page computed content metadata navigation operations page_core proxy relationships utils Caret Right Folder Site core data discovery factories page_caches properties section_registry theme Caret Right Folder Debug base config_inspector content_migrator delta_analyzer dependency_visualizer explainer incremental_debugger models reporter shortcode_sandbox Caret Right Folder Discovery asset_discovery content_discovery Caret Right Folder Fonts downloader generator Caret Right Folder Health autofix base health_check report Caret Right Folder Linkcheck async_checker ignore_policy internal_checker models orchestrator Caret Right Folder Validators anchors assets cache config connectivity cross_ref fonts links menu navigation output performance rendering rss sitemap taxonomy tracks Caret Right Folder Directives analysis checkers constants Caret Right Folder Orchestration asset content full_to_incremental incremental menu postprocess related_posts render section static streaming taxonomy Caret Right Folder Postprocess html_output redirects rss sitemap special_pages Caret Right Folder Output Formats index_generator json_generator llm_generator lunr_index_generator txt_generator utils Caret Right Folder Rendering api_doc_enhancer asset_extractor errors jinja_utils link_transformer link_validator pygments_cache renderer template_context template_profiler validator Caret Right Folder Parsers base factory mistune native_html pygments_patch python_markdown Caret Right Folder Pipeline core output thread_local toc transforms Caret Right Folder Plugins badges cross_references inline_icon term variable_substitution Caret Right Folder Directives _icons admonitions badge base button cache cards checklist code_tabs container contracts data_table dropdown embed errors example_label fenced figure glossary icon include list_table literalinclude marimo navigation options rubric steps tabs target term terminal tokens utils validator video Caret Right Folder Template Engine asset_url core environment manifest menu url_helpers Caret Right Folder Template Functions advanced_collections advanced_strings autodoc collections content crossref data dates debug files get_page i18n icons images math_functions navigation pagination_helpers seo strings tables taxonomies theme urls Caret Right Folder Server build_handler component_preview constants dev_server live_reload pid_manager reload_controller request_handler request_logger resource_manager utils Caret Right Folder Services validation Caret Right Folder Themes config Caret Right Folder Utils atomic_write autodoc build_context build_stats build_summary cli_output css_minifier dates dotdict error_handlers file_io file_lock hashing incremental_constants js_bundler live_progress logger metadata observability page_initializer pagination path_resolver paths performance_collector performance_report profile progress retry rich_console sections swizzle text theme_registry theme_resolution thread_local traceback_config traceback_renderer url_normalization url_strategy API Reference Autodoc ᗢ Caret Down Link Copy URL External Open LLM text Copy Copy LLM text Share with AI Ask Claude Ask ChatGPT Ask Gemini Ask Copilot Module autodoc.utils Utility functions for autodoc system. Provides text sanitization and common helpers for all extractors. Typed Metadata Access: Helper functions for type-safe access to DocElement.typed_metadata with fallback to untyped metadata dict. See get_* functions below. View source 21 Functions Functions _convert_sphinx_roles Convert reStructuredText-style cross-reference roles to inline code. Handles common reStructuredTe… 1 str Caret Right def _convert_sphinx_roles(text: str) -> str Convert reStructuredText-style cross-reference roles to inline code. Handles common reStructuredText roles: ClassName or ClassName → ClassName function_name() → function_name() method_name() → method_name() module_name → module_name attribute_name → attribute_name ExceptionName → ExceptionName Parameters 1 Name Type Default Description text str — Text containing reStructuredText roles Returns str — Text with roles converted to inline code sanitize_text Clean user-provided text for markdown generation. This function is the single source of truth for … 1 str Caret Right def sanitize_text(text: str | None) -> str Clean user-provided text for markdown generation. This function is the single source of truth for text cleaning across all autodoc extractors. It prevents common markdown rendering issues by: Removing leading/trailing whitespace Dedenting indented blocks (prevents accidental code blocks) Normalizing line endings Collapsing excessive blank lines Parameters 1 Name Type Default Description text str | None — Raw text from docstrings, help text, or API specs Returns str — Cleaned text safe for markdown generation truncate_text Truncate text to a maximum length, adding suffix if truncated. 3 str Caret Right def truncate_text(text: str, max_length: int = 200, suffix: str = '...') -> str Truncate text to a maximum length, adding suffix if truncated. Parameters 3 Name Type Default Description text str — Text to truncate max_length int 200 Maximum length (default: 200) suffix str '...' Suffix to add if truncated (default: '...') Returns str — Truncated text auto_detect_prefix_map Auto-detect grouping from __init__.py hierarchy. Scans source directories for packages (directorie… 2 dict[str, str] Caret Right def auto_detect_prefix_map(source_dirs: list[Path], strip_prefix: str = '') -> dict[str, str] Auto-detect grouping from init.py hierarchy. Scans source directories for packages (directories containing init.py) and builds a prefix map for every package path. Each entry maps the full dotted module path to its slash-separated path relative to the stripped prefix (e.g., "cli.templates" → "cli/templates"). Using the full path ensures nested packages stay under their parent directories (cli/templates lives under cli/). Parameters 2 Name Type Default Description source_dirs list[Path] — Directories to scan for packages strip_prefix str '' Optional dotted prefix to remove from detected modules Returns dict[str, str] — Prefix map: {"package.path": "group_path"} apply_grouping Apply grouping config to qualified module name. 2 tuple[str | None, str] Caret Right def apply_grouping(qualified_name: str, config: dict[str, Any]) -> tuple[str | None, str] Apply grouping config to qualified module name. Parameters 2 Name Type Default Description qualified_name str — Full module name (e.g., "bengal.cli.templates.blog") config dict[str, Any] — Grouping config dict with mode and prefix_map Returns tuple[str | None, str] — Tuple of (group_name, remaining_path): group_name: Top-level group (or None if no grouping) remaining_path: Path after group prefix get_python_class_bases Get class base classes with type-safe access. 1 tuple[str, ...] Caret Right def get_python_class_bases(element: DocElement) -> tuple[str, ...] Get class base classes with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "class" Returns tuple[str, ...] — Tuple of base class names (e.g., ("ABC", "Mixin")) get_python_class_decorators Get class decorators with type-safe access. 1 tuple[str, ...] Caret Right def get_python_class_decorators(element: DocElement) -> tuple[str, ...] Get class decorators with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "class" Returns tuple[str, ...] — Tuple of decorator names (e.g., ("dataclass", "frozen")) get_python_class_is_dataclass Check if class is a dataclass with type-safe access. 1 bool Caret Right def get_python_class_is_dataclass(element: DocElement) -> bool Check if class is a dataclass with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "class" Returns bool — True if class has @dataclass decorator get_python_function_decorators Get function/method decorators with type-safe access. 1 tuple[str, ...] Caret Right def get_python_function_decorators(element: DocElement) -> tuple[str, ...] Get function/method decorators with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "function" or "method" Returns tuple[str, ...] — Tuple of decorator names (e.g., ("classmethod", "override")) get_python_function_is_property Check if function is a property with type-safe access. 1 bool Caret Right def get_python_function_is_property(element: DocElement) -> bool Check if function is a property with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "function" or "method" Returns bool — True if function has @property decorator get_python_function_signature Get function signature with type-safe access. 1 str Caret Right def get_python_function_signature(element: DocElement) -> str Get function signature with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "function" or "method" Returns str — Signature string (e.g., "def build(force: bool = False) -> None") get_python_function_return_type Get function return type with type-safe access. 1 str | None Caret Right def get_python_function_return_type(element: DocElement) -> str | None Get function return type with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "function" or "method" Returns str | None — Return type string or None get_cli_command_callback Get CLI command callback name with type-safe access. 1 str | None Caret Right def get_cli_command_callback(element: DocElement) -> str | None Get CLI command callback name with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "command" Returns str | None — Callback function name or None get_cli_command_option_count Get CLI command option count with type-safe access. 1 int Caret Right def get_cli_command_option_count(element: DocElement) -> int Get CLI command option count with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "command" Returns int — Number of options get_cli_group_command_count Get CLI group command count with type-safe access. 1 int Caret Right def get_cli_group_command_count(element: DocElement) -> int Get CLI group command count with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "command-group" Returns int — Number of subcommands get_openapi_tags Get OpenAPI endpoint tags with type-safe access. 1 tuple[str, ...] Caret Right def get_openapi_tags(element: DocElement) -> tuple[str, ...] Get OpenAPI endpoint tags with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "openapi_endpoint" Returns tuple[str, ...] — Tuple of tag names (e.g., ("users", "admin")) get_openapi_method Get OpenAPI HTTP method with type-safe access. 1 str Caret Right def get_openapi_method(element: DocElement) -> str Get OpenAPI HTTP method with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "openapi_endpoint" Returns str — HTTP method string (e.g., "GET", "POST") get_openapi_path Get OpenAPI endpoint path with type-safe access. 1 str Caret Right def get_openapi_path(element: DocElement) -> str Get OpenAPI endpoint path with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "openapi_endpoint" Returns str — Path string (e.g., "/users/{id}") get_openapi_operation_id Get OpenAPI operation ID with type-safe access. 1 str | None Caret Right def get_openapi_operation_id(element: DocElement) -> str | None Get OpenAPI operation ID with type-safe access. Parameters 1 Name Type Default Description element DocElement — DocElement with element_type "openapi_endpoint" Returns str | None — Operation ID string or None get_function_parameters Get normalized function/method parameters across all extractor types. This is the canonical way to… 2 list[dict[str, Any]] Caret Right def get_function_parameters(element: DocElement, exclude_self: bool = True) -> list[dict[str, Any]] Get normalized function/method parameters across all extractor types. This is the canonical way to access parameters in templates. It handles: Python functions/methods (typed_metadata.parameters or metadata.args) CLI options (typed_metadata or metadata.options) OpenAPI endpoints (typed_metadata.parameters or metadata.parameters) Each parameter is normalized to a consistent dict format: { "name": str, # Parameter name "type": str | None, # Type annotation/schema type "default": str | None, # Default value "required": bool, # Whether required (derived from default) "description": str, # Description from docstring } Parameters 2 Name Type Default Description element DocElement — DocElement to extract parameters from exclude_self bool True If True, excludes 'self' and 'cls' parameters (default True) Returns list[dict[str, Any]] — List of normalized parameter dicts (empty list if element has no params) get_function_return_info Get normalized return type information across all extractor types. Returns a consistent dict forma… 1 dict[str, Any] Caret Right def get_function_return_info(element: DocElement) -> dict[str, Any] Get normalized return type information across all extractor types. Returns a consistent dict format: { "type": str | None, # Return type annotation "description": str | None, # Return description from docstring } Parameters 1 Name Type Default Description element DocElement — DocElement to extract return info from Returns dict[str, Any] — Dict with 'type' and 'description' keys (both None if not applicable) ← Previous docstring_parser Next → virtual_orchestrator List © 2025 Bengal ᓚᘏᗢ window.BENGAL_LAZY_ASSETS = { tabulator: '/bengal/assets/js/tabulator.min.js', dataTable: '/bengal/assets/js/data-table.js', mermaidToolbar: '/bengal/assets/js/mermaid-toolbar.9de5abba.js', mermaidTheme: '/bengal/assets/js/mermaid-theme.344822c5.js', graphMinimap: '/bengal/assets/js/graph-minimap.cc7e42e3.js', graphContextual: '/bengal/assets/js/graph-contextual.440e59c6.js' }; window.BENGAL_ICONS = { close: '/bengal/assets/icons/close.911d4fe1.svg', enlarge: '/bengal/assets/icons/enlarge.652035e5.svg', copy: '/bengal/assets/icons/copy.3d56e945.svg', 'download-svg': '/bengal/assets/icons/download.04f07e1b.svg', 'download-png': '/bengal/assets/icons/image.c34dfd40.svg', 'zoom-in': '/bengal/assets/icons/zoom-in.237b4a83.svg', 'zoom-out': '/bengal/assets/icons/zoom-out.38857c77.svg', reset: '/bengal/assets/icons/reset.d26dba29.svg' }; Arrow Up X -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 2336 - Reading Time: 12 minutes