Developer Interface¶
This part of the documentation covers staticjinja’s API.
Most of staticjinja’s functionality can be accessed with
Site.make_site()
, so pay particular attention to that.
Classes¶
-
class
staticjinja.
Site
(environment, searchpath, outpath='.', encoding='utf8', logger=None, contexts=None, rules=None, staticpaths=None, mergecontexts=False)¶ The Site object.
Parameters: - environment – A
jinja2.Environment
. - searchpath – A string representing the name of the directory to search for templates.
- contexts – A list of regex, context pairs. Each context is either a dictionary or a function that takes either no argument or or the current template as its sole argument and returns a dictionary. The regex, if matched against a filename, will cause the context to be used.
- rules – A list of (regex, function) pairs. The Site will delegate
rendering to function if regex matches the name of a template
during rendering. function must take a
staticjinja.Site
object, ajinja2.Template
, and a context dictionary as parameters and render the template. Defaults to[]
. - encoding – The encoding of templates to use.
- logger – A logging.Logger object used to log events. Defaults to
logging.getLogger(__name__)
- staticpaths –
Deprecated since version 0.3.4.
List of directory names to get static files from (relative to searchpath).
- mergecontexts – A boolean value. If set to
True
, then all matching regex from the contexts list will be merged (in order) to get the final context. Otherwise, only the first matching regex is used. Defaults toFalse
.
-
get_context
(template)¶ Get the context for a template.
If no matching value is found, an empty context is returned. Otherwise, this returns either the matching value if the value is dictionary-like or the dictionary returned by calling it with template if the value is a function.
If several matching values are found, the resulting dictionaries will be merged before being returned if mergecontexts is True. Otherwise, only the first matching value is returned.
Parameters: template – the template to get the context for
-
get_dependencies
(filename)¶ Get a list of files that depends on the file named filename.
Parameters: filename – the name of the file to find dependencies of
-
get_rule
(template_name)¶ Find a matching compilation rule for a function.
Raises a
ValueError
if no matching rule can be found.Parameters: template_name – the name of the template
-
get_template
(template_name)¶ Get a
jinja2.Template
from the environment.Parameters: template_name – A string representing the name of the template.
-
is_ignored
(template_name)¶ Check if a template is an ignored template. Ignored templates are neither rendered nor used in rendering templates.
A template is considered ignored if it or any of its parent directories are prefixed with an
'.'
.Parameters: template_name – the name of the template to check
-
is_partial
(template_name)¶ Check if a template is a partial template. Partial templates are not rendered, but they are used in rendering templates.
A template is considered a partial if it or any of its parent directories are prefixed with an
'_'
.Parameters: template_name – the name of the template to check
-
is_static
(template_name)¶ Check if a template is a static template. Static template are copied, rather than compiled using Jinja2.
Deprecated since version 0.3.4.
A template is considered static if it lives in any of the directories specified in
staticpaths
.Parameters: template_name – the name of the template to check
-
is_template
(filename)¶ Check if a file is a template.
A file is a considered a template if it is not partial, ignored, or static.
Parameters: filename – the name of the file to check
-
classmethod
make_site
(searchpath='templates', outpath='.', contexts=None, rules=None, encoding='utf8', followlinks=True, extensions=None, staticpaths=None, filters={}, env_globals={}, env_kwargs=None, mergecontexts=False)¶ Create a
Site
object.Parameters: - searchpath –
A string representing the absolute path to the directory that the Site should search to discover templates. Defaults to
'templates'
.If a relative path is provided, it will be coerced to an absolute path by prepending the directory name of the calling module. For example, if you invoke staticjinja using
python build.py
in directory/foo
, then searchpath will be/foo/templates
. - outpath – A string representing the name of the directory that the Site
should store rendered files in. Defaults to
'.'
. - contexts – A list of (regex, context) pairs. The Site will render templates
whose name match regex using context. context must be either
a dictionary-like object or a function that takes either no
arguments or a single
jinja2.Template
as an argument and returns a dictionary representing the context. Defaults to[]
. - rules – A list of (regex, function) pairs. The Site will delegate
rendering to function if regex matches the name of a template
during rendering. function must take a
staticjinja.Site
object, ajinja2.Template
, and a context dictionary as parameters and render the template. Defaults to[]
. - encoding – A string representing the encoding that the Site should use when
rendering templates. Defaults to
'utf8'
. - followlinks – A boolean describing whether symlinks in searchpath should be
followed or not. Defaults to
True
. - extensions – A list of Jinja extensions that the
jinja2.Environment
should use. Defaults to[]
. - staticpaths –
Deprecated since version 0.3.4.
List of directories to get static files from (relative to searchpath). Defaults to
None
. - filters – A dictionary of Jinja2 filters to add to the Environment. Defaults
to
{}
. - env_globals – A mapping from variable names that should be available all the time
to their values. Defaults to
{}
. - env_kwargs – A dictionary that will be passed as keyword arguments to the
jinja2 Environment. Defaults to
{}
. - mergecontexts – A boolean value. If set to
True
, then all matching regex from the contexts list will be merged (in order) to get the final context. Otherwise, only the first matching regex is used. Defaults toFalse
.
- searchpath –
-
render
(use_reloader=False)¶ Generate the site.
Parameters: use_reloader – if given, reload templates on modification
-
render_template
(template, context=None, filepath=None)¶ Render a single
jinja2.Template
object.If a Rule matching the template is found, the rendering task is delegated to the rule.
Parameters: - template – A
jinja2.Template
to render. - context – Optional. A dictionary representing the context to render
template with. If no context is provided,
get_context()
is used to provide a context. - filepath – Optional. A file or file-like object to dump the complete template
stream into. Defaults to to
os.path.join(self.outpath, template.name)
.
- template – A
-
render_templates
(templates)¶ Render a collection of
jinja2.Template
objects.Parameters: templates – A collection of jinja2.Template
objects to render.
-
templates
¶ Generator for templates.
- environment – A
-
class
staticjinja.
Reloader
(site)¶ Watches
site.searchpath
for changes and re-renders any changed Templates.Parameters: site – A Site
object.-
event_handler
(event_type, src_path)¶ Re-render templates if they are modified.
Parameters: - event_type – a string, representing the type of event
- src_path – the path to the file that triggered the event.
-
should_handle
(event_type, filename)¶ Check if an event should be handled.
An event should be handled if a file in the searchpath was modified.
Parameters: - event_type – a string, representing the type of event
- filename – the path to the file that triggered the event.
-
watch
()¶ Watch and reload modified templates.
-