Module

environment.loaders

Template loaders for Kida environment.

Loaders provide template source to the Environment. They implement get_source(name)returning(source, filename).

Built-in Loaders:

  • FileSystemLoader: Load from filesystem directories
  • DictLoader: Load from in-memory dictionary (testing/embedded)

Custom Loaders:

Implement the Loader protocol:

```python
class DatabaseLoader:
    def get_source(self, name: str) -> tuple[str, str | None]:
        row = db.query("SELECT source FROM templates WHERE name = ?", name)
        if not row:
            raise TemplateNotFoundError(f"Template '{name}' not found")
        return row.source, f"db://{name}"

    def list_templates(self) -> list[str]:
        return [r.name for r in db.query("SELECT name FROM templates")]
```

Thread-Safety: Loaders should be thread-safe for concurrentget_source()calls. Both built-in loaders are safe (FileSystemLoader reads files atomically, DictLoader uses immutable dict lookup).

2Classes

Classes

FileSystemLoader 5 ▼
Load templates from filesystem directories. Searches one or more directories for templates by name…

Load templates from filesystem directories.

Searches one or more directories for templates by name. The first matching file is returned. Supports arbitrary directory structures and file nesting.

Methods: get_source(name): Return (source, filename) for template list_templates(): Return sorted list of all template names

Search Order: Directories are searched in order. First match wins: python loader = FileSystemLoader(["themes/custom/", "themes/default/"]) # Looks in themes/custom/ first, then themes/default/

Attributes

Name Type Description
_paths —

List of Path objects to search
_encoding —

File encoding (default: utf-8)

Methods

get_source 1 tuple[str, str] ▼
Load template source from filesystem.
def get_source(self, name: str) -> tuple[str, str]
Parameters
Name Type Description
name —
Returns
tuple[str, str]
list_templates 0 list[str] ▼
List all templates in search paths.
def list_templates(self) -> list[str]
Returns
list[str]
Internal Methods 1 ▼
__init__ 2 ▼
def __init__(self, paths: str | Path | list[str | Path], encoding: str = 'utf-8')
Parameters
Name Type Description
paths —
encoding — Default:'utf-8'
DictLoader 4 ▼
Load templates from an in-memory dictionary. Maps template names to source strings. Useful for tes…

Load templates from an in-memory dictionary.

Maps template names to source strings. Useful for testing, embedded templates, or dynamically generated templates.

Methods: get_source(name): Return (source, None) for template list_templates(): Return sorted list of template names

Testing:

>>> loader = DictLoader({"test.html": "{{ x * 2 }}"})

    >>> env = Environment(loader=loader)
    >>> assert env.render("test.html", x=21) == "42"

Attributes

Name Type Description
_mapping —

Dict mapping template name → source string

Methods

get_source 1 tuple[str, None] ▼
def get_source(self, name: str) -> tuple[str, None]
Parameters
Name Type Description
name —
Returns
tuple[str, None]
list_templates 0 list[str] ▼
def list_templates(self) -> list[str]
Returns
list[str]
Internal Methods 1 ▼
__init__ 1 ▼
def __init__(self, mapping: dict[str, str])
Parameters
Name Type Description
mapping —