Template Providers#

This page documents the machinery behind template providers, the middleware that process the template files and inject template variables into them.

class prept.TemplateProvider(**options: Any)#

Base class for all template providers.

Template providers are “middleware” classes that process the content of template files at generation time and inject the values of template variables.

All template providers, external or provided by Prept, inherit from this class and implement the process_content() and process_path() methods. All providers must also set the name class attribute.

Prept provides the following built-in template providers:

Parameters:

**options –

The additional options passed to the template provider.

These options are set through the BoilerplateInfo.template_provider_params setting in preptconfig.json.

name#

Class attribute.

The name used to identify the template provider.

Type:

str

process_path(path: pathlib.Path, context: GenerationContext) → pathlib.Path#

“Processes the given path and replaces the.

This returns the pathlib.Path object representing the processed path.

Parameters:

  • path (pathlib.Path) – The path to process.

  • context (GenerationContext) – The generation context containing generation time information.

process_content(file: BoilerplateFile, context: GenerationContext) → str | bytes#

Processes the file content and inject variables into it.

This returns the processed file content generated from template in textual (string) or binary (bytes) format.

Parameters:

Built-in Providers#

Prept provides the following template providers built-in to cater common use cases. Support for more template providers will be added in future.

StringTemplateProvider#

class prept.StringTemplateProvider(**options: Any)#

$-substitutions based templates by string.Template.

This uses string.Template.safe_substitute() to ensure that any invalid or missing variables are silently ignored at generation time.

This is identified by the stringsub name.

Jinja2TemplateProvider#

class prept.Jinja2TemplateProvider(**options: Any)#

Provider based on Jinja2 templates.

This template provider requires Jinja2 to be installed.

Jinja templates are commonly used for HTML files in web frameworks such as Flask. However, it can be used for any kind of source file.

The following is an example of Jinja template HTML file (taken directly from Jinja2 documentation):

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Webpage</title>
</head>
<body>
    <ul id="navigation">
    {% for item in navigation %}
        <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
    {% endfor %}
    </ul>

    <h1>My Webpage</h1>
    {{ a_variable }}

    {# a comment #}
</body>
</html>

For more information, please refer to Jinja documentation: https://jinja.palletsprojects.com/

This is identified by the jinja2 name.

Provider Resolution#

Prept provides an interface to define custom template providers. This interface also allows third party packages and libraries to implement and distribute template providers that can be used directly by installing them and referring to them in configuration file.

prept.get_prept_template_provider(name: str) → type[TemplateProvider] | None#

Prept’s default template provider resolver.

Packages providing custom template providers should define this function at module level. Prept will call this function at generation time with the provider name from preptconfig.json.

This function should return a subclass of TemplateProvider or None if provider name is invalid.

Parameters:

name (str) – The provider’s name.

Returns:

The template provider resolved from given name.

Return type:

type[TemplateProvider]

prept.resolve_template_provider(spec: str) → type[TemplateProvider]#

Resolves a template provider from its spec.

The spec is given in one the following format:

  • provider-name

  • provider-class-name

  • module_name:provider-name

  • package:provider-class-name

If no module_name is provided, it is assumed that a built-in template provider from Prept is needed.

The provider-name is the TemplateProvider.name attribute of template provider and if provided, the provider is resolved through the get_prept_template_provider() function defined by the module_name.

If provider-name resolution fails, provider-class-name resolution is performed.

Changed in version 0.2.0: This function now takes spec in standard Python module format i.e. module_name:object instead of module_name::object.

Returns:

The resolved template provider.

Return type:

type[TemplateProvider]