Overview¶
This document quickly describes piecutter‘s core concepts and components.
See also Vision about motivations. See also Quickstart tutorial for a tutorial.
Cutters¶
Cutters are highest-level components in piecutter. They are the glue around all the features of piecutter. They orchestrate full template rendering workflow:
- cutters are callables that take
template
(template object or location) anddata
as input - they use loaders [1] to fetch templates and distinguish files from directories
- they use engines to render templates against data
- they run writers to post-process output.
Learn more in Cutters.
Engines¶
Engines are the core components of piecutter. They use third-party template engines to generate output using templates and context data.
Engines are callables that accept template (template object only) and data as input then return generated output as an iterable file-like object.
piecutter‘s initial concept is to provide a single API to handle multiple template engines. piecutter‘s core currently supports the following third-party engines:
Of course, you can implement custom engines.
piecutter also provides a special ProxyEngine
that tries to guess the
best engine to use depending on template.
Learn more in Engines.
Loaders¶
Loaders load templates from Python objects or from locations.
Loaders are callables that accept location as input argument then return a template object.
piecutter provides builtin support for various locations:
- Python builtins (text and file-like objects)
- files on local filesystem
- remote files over HTTP
- remote files on Github.
Of course, you can write your own loaders!
See loaders for details.
Templates¶
piecutter handles template objects. They are, basically, Python objects whose content can be read.
Templates can represent either single units (files) or collections (directories).
Single units rendered as file-like object.
Collections are rendered as generator of file-like objects.
Loaders make the difference between single units and collections.
Learn more at Template objects.
Data¶
piecutter uses mappings as context data. Any dictionary-like object can be used.
During rendering, additional contextual data is added to the original, such as
piecutter.engine
, which represents template engine name.
See Context data for details.
Dispatchers¶
piecutter renders templates using processing pipelines. As an example, writers can be chained to perform several operations. Everywhere processing could be done by either one or several functions, you can use dispatchers: they look like one function but encapsulate several calls.
Note
piecutter‘s initial scope doesn’t include dispatchers. So this feature may be moved to a third-party library.
See loaders for details.
Notes & references
[1] | loaders |
[2] | https://docs.python.org/2.7/library/string.html#formatstrings |
[3] | http://jinja.pocoo.org/ |
[4] | https://docs.djangoproject.com/en/1.8/topics/templates/ |