engine

class render_static.engine.StaticTemplateEngine[source]

Bases: object

An engine for rendering static templates to disk based on a standard STATIC_TEMPLATES configuration either passed in at construction or obtained from settings. Static templates are most usually generated by a run of renderstatic preceding collectstatic, but this class encapsulates all the behavior of the static engine, may be used independently and can override configured parameters including contexts and render destinations:

from render_static.engine import StaticTemplateEngine
from django.conf import settings
from pathlib import Path

# This engine uses the settings.STATIC_TEMPLATE config
engine = StaticTemplateEngine()

# This engine uses a custom configuration
engine = StaticTemplateEngine({
    'ENGINES': [{
        'BACKEND': 'render_static.backends.jinja2.StaticJinja2Templates',
        'APP_DIRS': True
    }],
    'context': {
        'var1': 'value1'
    },
    'templates': {
        'app/html/my_template.html': {
            'context': {
                'var1': 'value2'
            }
        }
    }
})

# this will render the my_template.html template to
# app/static/app/html/my_template.html with the context:
# { 'settings': settings, 'var1': 'value2' }
engine.render_to_disk('app/html/my_template.html')

# using the engine directly we can override configuration directives,
# this will render the template with the context:
# { 'settings': settings, 'var1': 'value3' } @ the custom location
# 'static_dir/rendered.html'
engine.render_to_disk(
    'app/html/my_template.html',
    context={'var1': 'value3'},
    destination=Path(settings.BASE_DIR) / 'static_dir/rendered.html'
)
class TemplateConfig[source]

Bases: object

Container for template specific configuration parameters.

__init__(name, dest=None, context=None)[source]
Parameters:

  • name (str) – The name of the template

  • dest (Path | str | None) – The absolute destination directory where the template will be written. May be None which indicates the template will be written to its owning app’s static directory if it was loaded with an app directory loader

  • context (Dict | Callable | str | None) – A specific dictionary context to use for this template, may also be an import string to a callable or a callable that generates a dictionary. This may override global context parameters.

Raises:

ImproperlyConfigured If there are any unexpected or misconfigured parameters

Return type:

None

property context: Dict

The context specific to this template. This will not include global parameters only the context as specified in the template configuration.

property dest: Path | None

The location this template should be saved to, if specified.

__init__(config=None)[source]
Parameters:

config (Dict | None) – If provided use this configuration instead of the one from settings

Raises:

ImproperlyConfigured: If there are any errors in the configuration passed in or specified in settings.

Return type:

None

config

Lazy configuration property. Fetch the STATIC_TEMPLATES configuration dictionary which will either be the configuration passed in on initialization or the config specified in the STATIC_TEMPLATES setting.

Returns:

The STATIC_TEMPLATES configuration this engine has initialized from

Raises:

ImproperlyConfigured If there are any terminal errors with the configurations

context

Lazy context property. Fetch the global context that will be fed to all templates. This includes the settings object and anything listed in the context dictionary in the STATIC_TEMPLATES configuration.

Returns:

A dictionary containing the global template context

Raises:

ImproperlyConfigured If the template context is specified and is not a dictionary.

templates

Lazy template property Fetch the dictionary mapping template names to TemplateConfig objects initializing them if necessary. This function transforms all acceptable template specifications into the canonical type as a list of name, config pairs.

Returns:

A dictionary mapping template names to configurations

Raises:

ImproperlyConfigured If there are any configuration issues with the templates

get_templates(name)[source]

Get a list of registered template configurations that belong to the given template name.

Parameters:

name (str) – The name of the template

Returns:

A list of TemplateConfig objects that are configured in the settings for rendering that correspond to a template of the given name or an empty list if no configurations match the name.

Return type:

List[TemplateConfig]

engines

Lazy engines property. Fetch the dictionary of engine names to engine instances based on the configuration, initializing said entities if necessary.

Returns:

A dictionary mapping engine names to instances

Raises:

ImproperlyConfigured If there are configuration problems with the engine backends.

__getitem__(alias)[source]

Accessor for backend instances indexed by name.

Parameters:

alias (str) – The name of the backend to fetch

Returns:

The backend instance

Raises:

InvalidTemplateEngineError If a backend of the given alias does not exist

Return type:

StaticEngine

all()[source]

Get a list of all registered engines in order of precedence. :return: A list of engine instances in order of precedence

Return type:

List[StaticEngine]

static resolve_destination(config, template, batch, dest=None)[source]

Resolve the destination for a template, given all present configuration parameters for it and arguments passed in.

Parameters:

  • config (TemplateConfig) – The template configuration

  • template (Template) – The template object created by the backend, could be a Jinja2 or Django template

  • batch (bool) – True if this is part of a batch render, false otherwise

  • dest (Path | str | None) – The destination passed in from the command line

Returns:

An absolute destination path

Raises:

ImproperlyConfigured – if a render destination cannot be determined

Return type:

Path

render_to_disk(selector, context=None, dest=None, first_engine=False, first_loader=False, first_preference=False, exclude=None, render_contents=True)[source]

Wrap render_each generator function and return the whole list of rendered templates for the given selector.

Parameters:

  • selector (str) – The name of the template to render to disk

  • context (Dict | None) – Additional context parameters that will override configured context parameters

  • dest (Path | str | None) – Override the configured path to render the template at this path, either a string path, or Path like object. If the selector resolves to multiple templates, dest will be considered a directory. If the the selector resolves to a single template, dest will be considered the final file path, unless it already exists as a directory.

  • first_engine (bool) – If true, render only the set of template names that match the selector that are found by the first rendering engine. By default (False) any templates that match the selector from any engine will be rendered.

  • first_loader (bool) – If True, render only the set of template names from the first loader that matches any part of the selector. By default (False) any template name that matches the selector from any loader will be rendered.

  • first_preference (bool) – If true, render only the templates that match the first preference for each loader. When combined with first_loader will render only the first preference(s) of the first loader. Preferences are loader specific and documented on the loader.

  • exclude (List[Path] | None) – A list of template paths to exclude. If the path is a directory, any template below that directory will be excluded. This parameter only makes sense to use if your selector is a glob pattern.

  • render_contents (bool) – If False, do not render the contents of the template. If the destination path is a template it will still be rendered against the context to produce the final path.

Returns:

Render object for all the template(s) rendered to disk

Raises:

  • TemplateDoesNotExist – if no template by the given name is found

  • ImproperlyConfigured – if not enough information was given to render and write the template

Return type:

List[Render]

find(*selectors, dest=None, first_engine=False, first_loader=False, first_preference=False, exclude=None)[source]

Search for all templates that match the given selectors and yield Render objects for each one.

Parameters:

  • selectors (str) – The name(s) of the template(s) to render to disk

  • dest (Path | str | None) – see render_each

  • first_engine (bool) – See render_each

  • first_loader (bool) – See render_each

  • first_preference (bool) – See render_each

  • exclude (List[Path] | None) – A list of template paths to exclude. If the path is a directory, any template below that directory will be excluded. This parameter only makes sense to use if your selector is a glob pattern.

Yield:

Render objects for each template to disk

Raises:

TemplateDoesNotExist – if no template by the given name is found

Return type:

Generator[Render, None, None]

search(prefix, first_engine=False, first_loader=False)[source]

Search for all templates that match the given selectors and yield Render objects for each one.

Parameters:

  • prefix (str) – The name(s) of the template(s) to render to disk

  • dest – see render_each

  • first_engine (bool) – See render_each

  • first_loader (bool) – See render_each

Yield:

Templates found that start with the given prefix.

Return type:

Generator[Template, None, None]

render_each(*selectors, context=None, dest=None, first_engine=False, first_loader=False, first_preference=False, exclude=None, render_contents=True)[source]

A generator function that renders all selected templates of the highest precedence for each matching template name to disk.

The location of the directory of the rendered template will either be based on the dest configuration parameter for the template or the app the template was found in.

Parameters:

  • selectors (str) – The name(s) of the template(s) to render to disk

  • context (Dict | Callable | str | Path | None) – Additional context parameters that will override configured context parameters

  • dest (Path | str | None) – Override the configured path to render the template at this path, either a string path, or Path like object. If the selector(s) resolve to multiple templates, dest will be considered a directory. If the the selector(s) resolve to a single template, dest will be considered the final file path, unless it already exists as a directory.

  • first_engine (bool) – If true, render only the set of template names that match the selector that are found by the first rendering engine. By default (False) any templates that match the selector from any engine will be rendered.

  • first_loader (bool) – If True, render only the set of template names from the first loader that matches any part of the selector. By default (False) any template name that matches the selector from any loader will be rendered.

  • first_preference (bool) – If true, render only the templates that match the first preference for each loader. When combined with first_loader will render only the first preference(s) of the first loader. Preferences are loader specific and documented on the loader.

  • exclude (List[Path] | None) – A list of template paths to exclude. If the path is a directory, any template below that directory will be excluded. This parameter only makes sense to use if your selector is a glob pattern.

  • render_contents (bool) – If False, do not render the contents of the template. If the destination path is a template it will still be rendered against the context to produce the final path.

Yield:

Render objects for each template to disk

Raises:

  • TemplateDoesNotExist – if no template by the given name is found

  • ImproperlyConfigured – if not enough information was given to render and write the template

Return type:

Generator[Render, None, None]

resolve_renderings(selector, config, batch, exclude=None, **kwargs)[source]

Resolve the given parameters to a or a set of Render objects containing all the information necessary to render a template to disk.

Parameters:

  • selector (str) – The template selector (name string)

  • config (TemplateConfig) – The TemplateConfig to apply to the selector.

  • batch (bool) – True if this is a batch rendering, false otherwise.

  • exclude (List[Path] | None) – A list of template paths to exclude. If the path is a directory, any template below that directory will be excluded. This parameter only makes sense to use if your selector is a glob pattern.

  • kwargs – Pass through parameters from render_each

Yield:

Render objects

Return type:

Generator[Render, None, None]