piecutter is about file generation. Its primary goal is to provide a generic API to render templates against data.
Render template against data¶
piecutter has been created for the following pattern:
- you have a template. To its simplest expression, it is content with placeholders ;
- you have data ;
- you want to render the template against the data.
The important point here is that, as an user, you handle templates and data, whereas you do not want to bother with the rendering process. You expect piecutter to generate the content, whatever the template and the data you provide.
Wherever the templates¶
Templates can theorically live anywhere: on local filesystem, on remote places, or they could be generated in some way... As a user, I do not want to bother with template loading, I just want templates to be loaded and rendered against data.
One could say templates are just strings and loading could be done by the user, i.e. the feature could be simplified to “render string against data”. But templates often take advantage of features like “includes” or “extends”. Such features require loaders.
Of course piecutter cannot implement all template storages. It provides implementation for simplest ones (string, local filesystem) and an API for third-parties to implement additional loaders.
Whatever the template engine¶
As a matter of fact, templates are written using the syntax of one template engine. But whatever this syntax, you basically want it rendered.
Data is dictionary-like¶
piecutter expects a structured data input, i.e. a dictionary-like object. That’s enough.