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) and data 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.

Writers

piecutter uses writers to post-process template rendering output.

Learn more at Writers.

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/