Module

errors.suggestions

Actionable error suggestions for user-facing messages.

This module provides a centralized registry of actionable suggestions for common errors across Bengal. Each suggestion includes:

  • Fix: Short one-line fix description
  • Explanation: What went wrong and why
  • Code Snippets: Before/after examples showing the fix
  • Documentation Link: URL to relevant documentation
  • Files to Check: Source files to investigate
  • Grep Patterns: Search patterns for codebase investigation
  • Related Codes: Associated error codes

Suggestion Categories

  • directive: Version directives (since, deprecated, changed), glossary, include
  • config: Configuration errors (YAML, missing keys, environments)
  • template: Rendering errors (not found, syntax, undefined variables)
  • attribute: Attribute errors (URL model migration helpers)
  • asset: Asset errors (not found, invalid path, processing)
  • content: Content errors (frontmatter, dates, encoding)
  • parsing: Parse errors (markdown, TOC extraction)
  • cache: Cache errors (corruption, version mismatch)
  • server: Server errors (port in use)

Functions

get_suggestion(category, error_key) Get anActionableSuggestionfor a specific error pattern.

format_suggestion(category, error_key) Format a suggestion as a string for logging.

format_suggestion_full(category, error_key) Format a complete suggestion with all details.

get_attribute_error_suggestion(error_msg) Pattern-match AttributeError messages to URL model migrations.

search_suggestions(query) Search suggestions by keyword across all categories.

Usage

Get a suggestion::

from bengal.errors import get_suggestion

suggestion = get_suggestion("template", "not_found")

print(suggestion.fix) print(suggestion.after_snippet)

Format for logging::

from bengal.errors import format_suggestion

formatted = format_suggestion("directive", "since_empty")

logger.info(formatted)

Search for suggestions::

from bengal.errors import search_suggestions

results = search_suggestions("template")

for category, key, suggestion in results: print(f"{category}.{key}: {suggestion.fix}")

See Also

  • bengal/errors/exceptions.py- Exception classes using suggestions
  • bengal/errors/handlers.py- Runtime error handlers
1Class8Functions

Classes

ActionableSuggestion 9 ▼
A structured, actionable suggestion for fixing an error.

A structured, actionable suggestion for fixing an error.

Attributes

Name Type Description
fix str

Short one-line fix description
explanation str

Longer explanation of what went wrong
docs_url str | None

Link to documentation
before_snippet str | None

Example of broken code
after_snippet str | None

Example of fixed code
check_files list[str]

Files to investigate for this error
related_codes list[str]

Related error codes
grep_patterns list[str]

Patterns to search for in codebase

Methods

to_dict 0 dict[str, Any] ▼
Convert to dictionary.
def to_dict(self) -> dict[str, Any]
Returns
dict[str, Any]

Functions

get_suggestion 2 ActionableSuggestion | N… ▼
Get actionable suggestion for an error.
def get_suggestion(category: str, error_key: str) -> ActionableSuggestion | None
Parameters
Name Type Description
category str

Error category (directive, config, template, etc.)
error_key str

Specific error identifier
Returns
ActionableSuggestion | None
get_suggestion_dict 2 dict[str, Any] | None ▼
Get suggestion as dictionary.
def get_suggestion_dict(category: str, error_key: str) -> dict[str, Any] | None
Parameters
Name Type Description
category str

Error category
error_key str

Specific error identifier
Returns
dict[str, Any] | None
enhance_error_context 3 dict[str, Any] ▼
Enhance error context dict with actionable suggestion.
def enhance_error_context(context: dict[str, Any], category: str, error_key: str) -> dict[str, Any]
Parameters
Name Type Description
context dict[str, Any]

Existing error context dict
category str

Error category
error_key str

Specific error identifier
Returns
dict[str, Any]
format_suggestion 3 str | None ▼
Format suggestion as a string for logging.
def format_suggestion(category: str, error_key: str, *, include_snippets: bool = False) -> str | None
Parameters
Name Type Description
category str

Error category
error_key str

Specific error identifier
include_snippets bool

Whether to include code snippets

Default:False
Returns
str | None
format_suggestion_full 2 str | None ▼
Format full suggestion with all details.
def format_suggestion_full(category: str, error_key: str) -> str | None
Parameters
Name Type Description
category str

Error category
error_key str

Specific error identifier
Returns
str | None
get_attribute_error_suggestion 1 str | None ▼
Get actionable suggestion for AttributeError based on error message. Pattern-m…
def get_attribute_error_suggestion(error_msg: str) -> str | None

Get actionable suggestion for AttributeError based on error message.

Pattern-matches the error message against known migrations and returns a formatted suggestion string.

Parameters
Name Type Description
error_msg str

The error message from AttributeError
Returns
str | None
get_all_suggestions_for_category 1 dict[str, ActionableSugg… ▼
Get all suggestions for a category.
def get_all_suggestions_for_category(category: str) -> dict[str, ActionableSuggestion]
Parameters
Name Type Description
category str

Error category
Returns
dict[str, ActionableSuggestion]
search_suggestions 1 list[tuple[str, str, Act… ▼
Search suggestions by keyword.
def search_suggestions(query: str) -> list[tuple[str, str, ActionableSuggestion]]
Parameters
Name Type Description
query str

Search query (searches fix, explanation, and patterns)
Returns
list[tuple[str, str, ActionableSuggestion]]