Module

environment.exceptions

Exceptions for Kida template system.

Exception Hierarchy:

TemplateError (base) ├── TemplateNotFoundError # Template not found by loader ├── TemplateSyntaxError # Parse-time syntax error ├── TemplateRuntimeError # Render-time error with context │ ├── RequiredValueError # Required value was None/missing │ └── NoneComparisonError # Attempted None comparison (sorting) └── UndefinedError # Undefined variable access

Error Messages:

All exceptions provide rich error messages with:

  • Source location (template name, line number)
  • Expression context where error occurred
  • Actual values and their types
  • Actionable suggestions for fixing

Example:

```
UndefinedError: Undefined variable 'titl' in article.html:5
Suggestion: Did you mean 'title'? Or use {{ titl | default('') }}
```
7Classes

Classes

TemplateError 0 ▼
Base exception for all Kida template errors. All template-related exceptions inherit from this cla…

Base exception for all Kida template errors.

All template-related exceptions inherit from this class, enabling broad exception handling:

>>> try:
...     template.render()
... except TemplateError as e:
...     log.error(f"Template error: {e}")
TemplateNotFoundError 0 ▼
Template not found by any configured loader. Raised when `Environment.get_template(name)` cannot l…

Template not found by any configured loader.

Raised whenEnvironment.get_template(name)cannot locate the template in any of the loader's search paths.

TemplateSyntaxError 1 ▼
Parse-time syntax error in template source. Raised by the Parser when template syntax is invalid. …

Parse-time syntax error in template source.

Raised by the Parser when template syntax is invalid. Includes source location for error reporting.

Methods

Internal Methods 1 ▼
__init__ 4 ▼
def __init__(self, message: str, lineno: int | None = None, name: str | None = None, filename: str | None = None)
Parameters
Name Type Description
message —
lineno — Default:None
name — Default:None
filename — Default:None
TemplateRuntimeError 7 ▼
Render-time error with rich debugging context. Raised during template rendering when an operation …

Render-time error with rich debugging context.

Raised during template rendering when an operation fails. Provides detailed information to help diagnose the issue:

  • Template name and line number
  • The expression that caused the error
  • Actual values and their types
  • Actionable suggestion for fixing

Output Format:

        Runtime Error: 'NoneType' object has no attribute 'title'
          Location: article.html:15
          Expression: {{ post.title }}
          Values:
            post = None (NoneType)
          Suggestion: Check if 'post' is defined, or use {{ post.title | default('') }}
        ```

Attributes

Name Type Description
message —

Error description
expression —

Template expression that failed
values —

Dict of variable names → values for context
template_name —

Name of the template
lineno —

Line number in template source
suggestion —

Actionable fix suggestion

Methods

Internal Methods 1 ▼
__init__ 1 ▼
def __init__(self, message: str)
Parameters
Name Type Description
message —
RequiredValueError 1 ▼
A required value was None or missing. Raised by the `| require` filter when a value that must be p…

A required value was None or missing.

Raised by the| requirefilter when a value that must be present is None or missing. Useful for validating required context variables.

Methods

Internal Methods 1 ▼
__init__ 2 ▼
def __init__(self, field_name: str, message: str | None = None, **kwargs: Any)
Parameters
Name Type Description
field_name —
message — Default:None
NoneComparisonError 1 ▼
Attempted to compare None values, typically during sorting. Raised when `| sort` or similar operat…

Attempted to compare None values, typically during sorting.

Raised when| sortor similar operations encounter None values that cannot be compared. Provides information about which items have None values for the sort attribute.

Methods

Internal Methods 1 ▼
__init__ 3 ▼
def __init__(self, left_value: Any, right_value: Any, attribute: str | None = None, **kwargs: Any)
Parameters
Name Type Description
left_value —
right_value —
attribute — Default:None
UndefinedError 1 ▼
Raised when accessing an undefined variable. Strict mode is enabled by default in Kida. When a tem…

Raised when accessing an undefined variable.

Strict mode is enabled by default in Kida. When a template references a variable that doesn't exist in the context, this error is raised instead of silently returning None.

To fix:

  • Pass the variable in render(): template.render(undefined_var="value")
  • Use the default filter: {{ undefined_var | default("fallback") }}

Methods

Internal Methods 1 ▼
__init__ 3 ▼
def __init__(self, name: str, template: str | None = None, lineno: int | None = None)
Parameters
Name Type Description
name —
template — Default:None
lineno — Default:None