Template Loaders

CachingFileSystemLoader

CachingFileSystemLoader(
    search_path: Union[
        str, Path, Iterable[Union[str, Path]]
    ],
    encoding: str = "utf-8",
    ext: str = ".liquid",
    *,
    auto_reload: bool = True,
    namespace_key: str = "",
    cache_size: int = 300
)

Bases: CachingLoaderMixin, FileExtensionLoader

A file system loader that caches parsed templates in memory.

PARAMETER	DESCRIPTION
`search_path`	One or more paths to search. TYPE: `Union[str, Path, Iterable[Union[str, Path]]]`
`encoding`	Open template files with the given encoding. TYPE: `str` DEFAULT: `'utf-8'`
`ext`	A default file extension. Should include a leading period. TYPE: `str` DEFAULT: `'.liquid'`
`auto_reload`	If `True`, automatically reload a cached template if it has been updated. TYPE: `bool` DEFAULT: `True`
`namespace_key`	The name of a global render context variable or loader keyword argument that resolves to the current loader "namespace" or "scope". If you're developing a multi-user application, a good namespace might be `uid`, where `uid` is a unique identifier for a user and templates are arranged in folders named for each `uid` inside the search path. TYPE: `str` DEFAULT: `''`
`cache_size`	The maximum number of templates to hold in the cache before removing the least recently used template. TYPE: `int` DEFAULT: `300`

FileSystemLoader

FileSystemLoader(
    search_path: Union[
        str, Path, Iterable[Union[str, Path]]
    ],
    encoding: str = "utf-8",
)

Bases: BaseLoader

A loader that loads templates from one or more directories on the file system.

PARAMETER	DESCRIPTION
`search_path`	One or more paths to search. TYPE: `Union[str, Path, Iterable[Union[str, Path]]]`
`encoding`	Open template files with the given encoding. TYPE: `str` DEFAULT: `'utf-8'`

resolve_path

resolve_path(template_name: str) -> Path

Return a path to the template template_name.

If the search path is a list of paths, returns the first path where template_name exists. If none of the search paths contain template_name, a TemplateNotFound exception is raised.

FileExtensionLoader

FileExtensionLoader(
    search_path: Union[
        str, Path, Iterable[Union[str, Path]]
    ],
    encoding: str = "utf-8",
    ext: str = ".liquid",
)

Bases: FileSystemLoader

A file system loader that adds a file name extension if one is missing.

PARAMETER	DESCRIPTION
`search_path`	One or more paths to search. TYPE: `Union[str, Path, Iterable[Union[str, Path]]]`
`encoding`	Open template files with the given encoding. TYPE: `str` DEFAULT: `'utf-8'`
`ext`	A default file extension. Should include a leading period. TYPE: `str` DEFAULT: `'.liquid'`

DictLoader

DictLoader(templates: Dict[str, str])

Bases: BaseLoader

A loader that loads templates from a dictionary.

PARAMETER	DESCRIPTION
`templates`	A dictionary mapping template names to template source strings. TYPE: `Dict[str, str]`

ChoiceLoader

ChoiceLoader(loaders: List[BaseLoader])

Bases: BaseLoader

A template loader that will try each of a list of loaders in turn.

PARAMETER	DESCRIPTION
`loaders`	A list of loaders implementing `liquid.loaders.BaseLoader`. TYPE: `List[BaseLoader]`

get_source

get_source(
    env: Environment, template_name: str
) -> TemplateSource

Get source code for a template from one of the configured loaders.

get_source_async `async`

get_source_async(
    env: Environment, template_name: str
) -> TemplateSource

An async version of get_source.

get_source_with_args

get_source_with_args(
    env: Environment, template_name: str, **kwargs: object
) -> TemplateSource

Get source code for a template from one of the configured loaders.

get_source_with_args_async `async`

get_source_with_args_async(
    env: Environment, template_name: str, **kwargs: object
) -> TemplateSource

An async version of get_source_with_args.

get_source_with_context

get_source_with_context(
    context: Context, template_name: str, **kwargs: str
) -> TemplateSource

Get source code for a template from one of the configured loaders.

get_source_with_context_async `async`

get_source_with_context_async(
    context: Context, template_name: str, **kwargs: str
) -> TemplateSource

Get source code for a template from one of the configured loaders.

CachingChoiceLoader

CachingChoiceLoader(
    loaders: List[BaseLoader],
    *,
    auto_reload: bool = True,
    namespace_key: str = "",
    cache_size: int = 300
)

Bases: CachingLoaderMixin, ChoiceLoader

A ChoiceLoader that caches parsed templates in memory.

PARAMETER	DESCRIPTION
`loaders`	A list of loaders implementing `liquid.loaders.BaseLoader`. TYPE: `List[BaseLoader]`
`auto_reload`	If `True`, automatically reload a cached template if it has been updated. TYPE: `bool` DEFAULT: `True`
`namespace_key`	The name of a global render context variable or loader keyword argument that resolves to the current loader "namespace" or "scope". TYPE: `str` DEFAULT: `''`
`cache_size`	The maximum number of templates to hold in the cache before removing the least recently used template. TYPE: `int` DEFAULT: `300`

New in version 1.11.0.

PackageLoader

PackageLoader(
    package: Union[str, ModuleType],
    *,
    package_path: Union[str, Iterable[str]] = "templates",
    encoding: str = "utf-8",
    ext: str = ".liquid"
)

Bases: BaseLoader

A template loader that reads templates from Python packages.

PARAMETER	DESCRIPTION
`package`	Import name of a package containing Liquid templates. TYPE: `Union[str, ModuleType]`
`package_path`	One or more directories in the package containing Liquid templates. TYPE: `Union[str, Iterable[str]]` DEFAULT: `'templates'`
`encoding`	Encoding of template files. TYPE: `str` DEFAULT: `'utf-8'`
`ext`	A default file extension to use if one is not provided. Should include a leading period. TYPE: `str` DEFAULT: `'.liquid'`

New in version 1.11.0.

BaseLoader

Bases: ABC

Base template loader from which all template loaders are derived.

ATTRIBUTE	DESCRIPTION
`caching_loader`	Indicates if this loader implements its own cache. Setting this sto `True` will cause the `Environment` to disable its cache when initialized with a caching loader. TYPE: `bool`

get_source

get_source(
    env: Environment, template_name: str
) -> TemplateSource

Get the template source, filename and reload helper for a template.

PARAMETER	DESCRIPTION
`env`	The `Environment` attempting to load the template source text. TYPE: `Environment`
`template_name`	A name or identifier for a template's source text. TYPE: `str`

get_source_async `async`

get_source_async(
    env: Environment, template_name: str
) -> TemplateSource

An async version of get_source.

The default implementation delegates to get_source().

get_source_with_args

get_source_with_args(
    env: Environment, template_name: str, **kwargs: object
) -> TemplateSource

Get template source text, optionally referencing arbitrary keyword arguments.

Keyword arguments can be useful for multi-user environments where you need to modify a template loader's search space for a given user.

By default, this method delegates to get_source, ignoring any keyword arguments.

New in version 1.9.0.

get_source_with_args_async `async`

get_source_with_args_async(
    env: Environment, template_name: str, **kwargs: object
) -> TemplateSource

An async version of get_source_with_args.

New in version 1.9.0.

get_source_with_context

get_source_with_context(
    context: Context, template_name: str, **kwargs: str
) -> TemplateSource

Get a template's source, optionally referencing a render context.

get_source_with_context_async `async`

get_source_with_context_async(
    context: Context, template_name: str, **kwargs: str
) -> TemplateSource

An async version of get_source_with_context.

load

load(
    env: Environment,
    name: str,
    globals: TemplateNamespace = None,
) -> BoundTemplate

Find and parse template source code.

This is used internally by liquid.Environment to load template source text. load() delegates to BaseLoader.get_source(). Custom loaders would typically implement get_source() rather than overriding load().

load_async `async`

load_async(
    env: Environment,
    name: str,
    globals: TemplateNamespace = None,
) -> BoundTemplate

An async version of load().

load_with_args

load_with_args(
    env: Environment,
    name: str,
    globals: TemplateNamespace = None,
    **kwargs: object
) -> BoundTemplate

Load template source text, optionally referencing extra keyword arguments.

Most custom loaders will want to override get_source_with_args() rather than this method. For example, you might want to override load_with_args() and get_source_with_args() when implementing a custom caching loader. Where cache handling happens in load_* methods.

load_with_args_async `async`

load_with_args_async(
    env: Environment,
    name: str,
    globals: TemplateNamespace = None,
    **kwargs: object
) -> BoundTemplate

An async version of load_with_args().

load_with_context

load_with_context(
    context: Context, name: str, **kwargs: str
) -> BoundTemplate

Load and parse a template, optionally referencing a render context.

load_with_context_async `async`

load_with_context_async(
    context: Context, name: str, **kwargs: str
) -> BoundTemplate

An async version of load_with_context.

TemplateSource

Bases: NamedTuple

A Liquid template source as returned by the get_source method of a loader.

ATTRIBUTE	DESCRIPTION
`source`	The liquid template source code. TYPE: `str`
`filename`	The liquid template file name or other string identifying its origin. TYPE: `str`
`uptodate`	Optional callable that will return `True` if the template is up to date, or `False` if it needs to be reloaded. TYPE: `UpToDate`
`matter`	Optional mapping containing variables associated with the template. Could be "front matter" or other meta data. TYPE: `TemplateNamespace`

make_choice_loader

make_choice_loader(
    loaders: List[BaseLoader],
    *,
    auto_reload: bool = True,
    namespace_key: str = "",
    cache_size: int = 300
) -> BaseLoader

A choice loader factory.

Returns one of CachingChoiceLoader or ChoiceLoader depending on the given arguments.

A CachingChoiceLoader is returned if cache_size > 0, otherwise a ChoiceLoader is returned.

auto_reload and namespace_key are ignored if cache_key is less than 1.

PARAMETER	DESCRIPTION
`loaders`	A list of loaders implementing `liquid.loaders.BaseLoader`. TYPE: `List[BaseLoader]`
`auto_reload`	If `True`, automatically reload a cached template if it has been updated. TYPE: `bool` DEFAULT: `True`
`namespace_key`	The name of a global render context variable or loader keyword argument that resolves to the current loader "namespace" or "scope". TYPE: `str` DEFAULT: `''`
`cache_size`	The maximum number of templates to hold in the cache before removing the least recently used template. TYPE: `int` DEFAULT: `300`

New in version 1.12.0

make_file_system_loader

make_file_system_loader(
    search_path: Union[
        str, Path, Iterable[Union[str, Path]]
    ],
    *,
    encoding: str = "utf-8",
    ext: str = ".liquid",
    auto_reload: bool = True,
    namespace_key: str = "",
    cache_size: int = 300
) -> BaseLoader

A file system template loader factory.

Returns one of CachingFileSystemLoader, FileExtensionLoader or FileSystemLoader depending in the given arguments.

A CachingFileSystemLoader is returned if cache_size is greater than 0. Otherwise a FileExtensionLoader is returned if ext is not empty. If ext is empty, a FileSystemLoader is returned.

auto_reload and namespace_key are ignored if cache_key is less than 1.

PARAMETER	DESCRIPTION
`search_path`	One or more paths to search. TYPE: `Union[str, Path, Iterable[Union[str, Path]]]`
`encoding`	Open template files with the given encoding. TYPE: `str` DEFAULT: `'utf-8'`
`ext`	A default file extension. Should include a leading period. TYPE: `str` DEFAULT: `'.liquid'`
`auto_reload`	If `True`, automatically reload a cached template if it has been updated. TYPE: `bool` DEFAULT: `True`
`namespace_key`	The name of a global render context variable or loader keyword argument that resolves to the current loader "namespace" or "scope". If you're developing a multi-user application, a good namespace might be `uid`, where `uid` is a unique identifier for a user and templates are arranged in folders named for each `uid` inside the search path. TYPE: `str` DEFAULT: `''`
`cache_size`	The maximum number of templates to hold in the cache before removing the least recently used template. TYPE: `int` DEFAULT: `300`

New in version 1.12.0

Template Loaders

CachingFileSystemLoader

FileSystemLoader

resolve_path

FileExtensionLoader

DictLoader

ChoiceLoader

get_source

get_source_async async

get_source_with_args

get_source_with_args_async async

get_source_with_context

get_source_with_context_async async

CachingChoiceLoader

PackageLoader

BaseLoader

get_source

get_source_async async

get_source_with_args

get_source_with_args_async async

get_source_with_context

get_source_with_context_async async

load

load_async async

load_with_args

load_with_args_async async

load_with_context

load_with_context_async async

TemplateSource

make_choice_loader

make_file_system_loader

get_source_async `async`

get_source_with_args_async `async`

get_source_with_context_async `async`

get_source_async `async`

get_source_with_args_async `async`

get_source_with_context_async `async`

load_async `async`

load_with_args_async `async`

load_with_context_async `async`