Config API

Templar's configuration options are stored in a Config object. However, you won't usually be dealing with Configs directly. Instead, use a ConfigBuilder to incrementally build up configuration options.

Templar configs have the following fields:

• template_dirs: a list of relative paths to template directories.
• variables: a dictionary of variables that can be accessed in Jinja templates.
• preprocess_rules: a list of Rules that will be applied to source content before compiler rules are applied.
• compiler_rules: a list of Rules that will be applied to compile source content (e.g. Markdown to HTML).
• postprocess_rules a list of Rules that will be applied to source content after compiler rules are applied.

There is technically nothing different about the Rules contained in preprocess_rules, compiler_rules, and postprocess_rules; they are all instances of Rule (and its subclasses). The only distinction between preprocess, compiler, and postprocess rules is the order in which they are applied. This gives the user better control over the ordering of rules.

Here's an example of how to build a config:

from templar.api.config import ConfigBuilder
from templar.api.rules.compiler_rules import MarkdownToHtml

config = ConfigBuilder().add_template_dirs(
    'blog/templates',
    'blog/food/templates'
).add_variables({
    'author': 'Jane Smith',
}).append_compiler_rules(
    MarkdownToHtml()
).build()

See the ConfigBuilder section for more details.

ConfigBuilder

A ConfigBuilder is a mutable object that is the primary way to build Configs. The add_* and clear_* methods mirror the fields found in Config. All methods return the ConfigBuilder object itself so that you can use the builder patter.

• Template directories:
  • add_template_dirs(*paths): takes an arbitrary number of strings (paths) and appends them to the end of the template_dirs list.
  • clear_template_dirs(): removes all paths from the list of template_dirs.
• Variables:
  • add_variable(variable, value): sets variable to value in the dictionary of variables. variable must be a string, but value can be any object.
  • add_variables(variable_map): a convenience method that takes a dictionary that maps variables to values. See add_variable for constraints.
  • clear_variables(): removes all variables from the dictionary of variables.
• Preprocess rules:
  • append_preprocess_rules(*rules): takes an arbitrary number of Rules and appends them to the end of the preprocess_rules list.
  • prepend_preprocess_rules(*rules): takes an arbitrary number of Rules and prepends them to the front of the preprocess_rules list.
  • clear_preprocess_rules(): removes all Rules from the list of preprocess_rules.
• Compiler rules
  • append_compiler_rules(*rules): takes an arbitrary number of Rules and appends them to the end of the compiler_rules list.
  • prepend_compiler_rules(*rules): takes an arbitrary number of Rules and prepends them to the front of the compiler_rules list.
  • clear_compiler_rules(): removes all Rules from the list of compiler_rules.
• Postprocess rules
  • append_postprocess_rules(*rules): takes an arbitrary number of Rules and appends them to the end of the postprocess_rules list.
  • prepend_postprocess_rules(*rules): takes an arbitrary number of Rules and prepends them to the front of the postprocess_rules list.
  • clear_postprocess_rules(): removes all Rules from the list of postprocess_rules.
• Building Configs:
  • build(): builds and returns a Config object.

Config

Configs are immutable objects used to store the configuration options for Templar. That being said, you usually won't create Config objects directly; instead, use a ConfigBuilder.

A Config object is shallowly immutable, so you can reuse the same Config object in many places without worrying about mutation. However, remember that the Rules in preprocess_rules, compiler_rules, and postprocess_rules are mutable, so any mutations applied to Rules will be reflected in all Configs.

You can access a Config's fields with the following instance variables:

• template_dirs: a list of relative paths to template directories.
• variables: a dictionary of variables that can be accessed in Jinja templates.
• preprocess_rules: a list of Rules that will be applied to source content before compiler rules are applied.
• compiler_rules: a list of Rules that will be applied to compile source content (e.g. Markdown to HTML).
• postprocess_rules a list of Rules that will be applied to source content after compiler rules are applied.

You also convert from a Config to ConfigBuilder with the to_builder method:

• to_builder(): creates a new ConfigBuilder that is populated with the options in this Config.

This is useful if you want to have a base Config that stores commonly used configuration options:

# In base_config.py
from templar.api.config import ConfigBuilder
from templar.api.rules.compiler_rules import MarkdownToHtml

config = ConfigBuilder().append_compiler_rules(
    MarkdownToHtml()
).build()

# In blog/config.py
from base_config import config as base_config

config = base_config.to_builder().add_variables({
    'title': 'My recipes',
}).build()

Rules

See Rules for details.

As mentioned above, there is technically nothing different about the Rules contained in preprocess_rules, compiler_rules, and postprocess_rules; they are all instances of Rule (and its subclasses). The only distinction between preprocess, compiler, and postprocess rules is the order in which they are applied. This gives the user better control over the ordering of rules.