-
Notifications
You must be signed in to change notification settings - Fork 4
Config API
Templar's configuration options are stored in a Config
object. However, you won't usually be dealing with Config
s 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 Rule
s 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.
A ConfigBuilder
is a mutable object that is the primary way to build Config
s. 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 thetemplate_dirs
list. -
clear_template_dirs()
: removes all paths from the list oftemplate_dirs
.
-
- Variables:
-
add_variable(variable, value)
: setsvariable
tovalue
in the dictionary of variables.variable
must be a string, butvalue
can be any object. -
add_variables(variable_map)
: a convenience method that takes a dictionary that maps variables to values. Seeadd_variable
for constraints. -
clear_variables()
: removes all variables from the dictionary of variables.
-
- Preprocess rules:
-
append_preprocess_rules(*rules)
: takes an arbitrary number ofRule
s and appends them to the end of thepreprocess_rules
list. -
prepend_preprocess_rules(*rules)
: takes an arbitrary number ofRule
s and prepends them to the front of thepreprocess_rules
list. -
clear_preprocess_rules()
: removes allRule
s from the list ofpreprocess_rules
.
-
- Compiler rules
-
append_compiler_rules(*rules)
: takes an arbitrary number ofRule
s and appends them to the end of thecompiler_rules
list. -
prepend_compiler_rules(*rules)
: takes an arbitrary number ofRule
s and prepends them to the front of thecompiler_rules
list. -
clear_compiler_rules()
: removes allRule
s from the list ofcompiler_rules
.
-
- Postprocess rules
-
append_postprocess_rules(*rules)
: takes an arbitrary number ofRule
s and appends them to the end of thepostprocess_rules
list. -
prepend_postprocess_rules(*rules)
: takes an arbitrary number ofRule
s and prepends them to the front of thepostprocess_rules
list. -
clear_postprocess_rules()
: removes allRule
s from the list ofpostprocess_rules
.
-
- Building
Config
s:-
build()
: builds and returns aConfig
object.
-
Config
s 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 Rule
s in preprocess_rules
, compiler_rules
, and postprocess_rules
are mutable, so any mutations applied to Rule
s will be reflected in all Config
s.
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 newConfigBuilder
that is populated with the options in thisConfig
.
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()
See Rules for details.
As mentioned above, there is technically nothing different about the Rule
s 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.