API Reference

Core API

Main API entry point for the Escapist library.

This module exposes the Escapist class, which serves as the primary interface for rendering templates based on user-defined settings.

Usage

from escapist import Escapist

renderer = Escapist(settings="path/to/settings.yaml")

Classes

Escapist

Escapist(
    settings: dict[str, Any] | str | Path | None = None,
)

A class for rendering Jinja2 templates from various sources with configurable settings.

The environment is configured and created on initialization. The template can then be loaded via a public method and rendered using a separate public method.

Parameters:

Name	Type	Description	Default
settings	dict[str, Any] | str | Path | None	The Jinja environment settings, which can be a dict, a JSON string, or a file path to a JSON file.	None

Raises:

Type	Description
DataLoadError	If settings loading fails.

Attributes

is_template_loaded property

is_template_loaded: bool

Check if a template has been loaded.

template_source property

template_source: str | None

Get the source of the currently loaded template.

Functions

load_template

load_template(template_source: str | Path) -> None

Loads and compiles the Jinja template based on its source.

Parameters:

Name	Type	Description	Default
template_source	str | Path	The template source, either a file path or a string.	required

Raises:

Type	Description
InvalidTemplateError	If the source path is invalid.
InvalidTemplateSyntaxError	If the the jinja syntax is wrong.
DataLoadError	If settings loading fails.

render

render(
    data: dict[str, Any] | str | Path | None = None,
    output_file: str | Path | None = None,
) -> str

Renders the currently loaded template with the provided data.

Parameters:

Name	Type	Description	Default
data	dict[str, Any] | str | Path | None	The data to use for rendering, which can be a dict, a JSON string, or a file path to a JSON file.	None
output_file	str | Path | None	Optional path to a file where the rendered output will be saved.	None

Returns:

Type	Description
str	The rendered template as a string.

Raises:

Type	Description
RuntimeError	If no template has been loaded before rendering.
DataLoadError	If data loading from JSON fails.
FileWriteError	If fails to write rendered template to file
UndefinedError	If missing any variables

Exceptions

Exception definitions for the Escapist library.

This module defines a set of custom exceptions used throughout the Escapist template rendering and data processing system. All exceptions inherit from EscapistError, allowing for broad or fine-grained error handling.

Usage

You can catch specific exceptions to handle known issues gracefully:

from escapist.exceptions import (
    EscapistError,
    DataLoadError,
    FileWriteError,
    InvalidTemplateError,
    InvalidTemplateSyntaxError,
)

try:
    ....
except DataLoadError as e:
    print(f"Failed to load data: {e}")
except FileWriteError as e:
    print(f"Could not write to output file: {e}")
except InvalidTemplateSyntaxError as e:
    print(f"Template syntax error: {e}")
except EscapistError as e:
    # Generic catch-all for any Escapist-related error
    print(f"An unknown Escapist error occurred: {e}")

These exceptions are designed to clearly communicate the source of errors during common operations like data loading, template parsing, and file output.

Classes

EscapistError

Bases: Exception

Base exception for all Escapist-related errors.

Catching this exception will handle any error raised by the library, allowing for broad error handling when the specific cause is not important.

DataLoadError

Bases: EscapistError

Raised when an error occurs during data loading or parsing.

This includes issues with loading JSON from a file or string, or encountering an unsupported data type for the input.

FileWriteError

Bases: EscapistError

Raised when an error occurs while writing rendered output to a file.

This may happen due to issues such as insufficient file system permissions, invalid file paths, missing directories, or other I/O-related errors that prevent successful writing of the output content.

InvalidTemplateError

Bases: EscapistError

Raised when a template path is invalid.

This exception is raised when the template source is a path that exists but is not a file (e.g., it is a directory), or when a template string is ambiguous with a file path.

InvalidTemplateSyntaxError

Bases: EscapistError

Raised when a template contains invalid Jinja syntax.

This exception is triggered when the Jinja2 engine encounters a syntax error while parsing the template string or file. Common causes include unmatched tags, invalid expressions, or unsupported Jinja constructs.