piecutter¶
piecutter is a template rendering framework, written in Python [1].
Leitmotiv: render templates against context, wherever the templates, whatever the template engine.
Project status¶
piecutter is under active development.
Yesterday, piecutter was the core of diecutter [2].
As diecutter‘s authors, we think diecutter has great features related to templates and file generation. We wanted to share it with a larger audience. So we just packaged it as a standalone library. And we are planning to make it better as soon as possible. Join us [3] if you like the features ;)
Here are some of our motivations:
- third-party projects can use piecutter. They do not have to depend on diecutter, which embeds some specific code related to its web service.
- as a standalone library, piecutter should be easier to maintain and improve.
- piecutter is more open than diecutter. It can have a larger community. It also may converge with similar tools.
Today, piecutter is tied to diecutter implementation. The API reflects diecutter‘s architecture and concepts, which may sound obscure for other usage.
Tomorrow, we are planning to improve piecutter. As an example, we think the API should be refactored, with simplicity in mind.
Example¶
Here is a simple demo of piecutter‘s API:
>>> import piecutter
>>> cutter = piecutter.Cutter(engine=piecutter.PythonFormatEngine())
>>> print(cutter.render("Hello {who}!", {'who': 'world'}))
Hello world!
Here is another setup, where several template engines are registered:
>>> cutter = piecutter.Cutter(
... engine=piecutter.GuessEngine(
... engines=[
... piecutter.Jinja2Engine(),
... piecutter.DjangoEngine(),
... piecutter.PythonFormatEngine(),
... ],
... )
... )
Then we can use the cutter to render various templates:
>>> cutter.render("{# Jinja2 #}Hello {{ who }}!", {'who': 'world'})
'Hello world!'
>>> cutter.render("{# Django #}Hello {{ who }}!", {'who': 'world'})
'Hello world!'
>>> cutter.render("Hello {who}!", {'who': 'world'})
'Hello world!'
Key features¶
- Simple API: render templates against context.
- Support multiple template engines: Jinja2 [4] and Django [5] for now. Later: Cheetah [6] and even non-Python template engines such as Ruby’s ERB [7].
- Render files and directories.
- Load templates from almost everywhere: local filesystem and github.com for now. Later: Django storages...
- Do what you want with generated content: write to local filesystem, generate an archive...
Resources¶
- Documentation: https://piecutter.readthedocs.io
- PyPI page: http://pypi.python.org/pypi/piecutter
- Bugtracker: https://github.com/diecutter/piecutter/issues
- Changelog: https://piecutter.readthedocs.io/en/latest/about/changelog.html
- Roadmap: https://github.com/diecutter/piecutter/issues/milestones
- Code repository: https://github.com/diecutter/piecutter
- Continuous integration: https://travis-ci.org/diecutter/piecutter
Contents¶
Install¶
piecutter is open-source software, published under BSD license. See License for details.
If you want to install a development environment, you should go to Contributing documentation.
As a library¶
In most cases, you will use piecutter as a dependency of another project.
In such a case, you should add piecutter
in your main project’s
requirements. Typically in setup.py
:
from setuptools import setup
setup(
install_requires=[
'piecutter',
#...
]
# ...
)
Then when you install your main project with your favorite package manager (like pip [2]), piecutter will automatically installed.
Standalone¶
You can install piecutter with your favorite Python package manager. As an example with pip [2]:
pip install piecutter
Check¶
Check piecutter has been installed:
python -c "import piecutter;print(piecutter.__version__)"
You should get piecutter‘s version.
References
[1] | http://python.org |
[2] | (1, 2) https://pypi.python.org/pypi/pip/ |
About piecutter¶
This section is about piecutter project itself.
Vision¶
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 supports neither loading of various data formats nor loading from various locations. The Python [1] language has nice libraries for that purpose.
piecutter expects a structured data input, i.e. a dictionary-like object. That’s enough.
A framework¶
piecutter is a framework. It is built with flexibility in mind. It is a library to build other software. It provides material to connect to third-party tools. It is easy to extend.
Notes & references
[1] | http://python.org |
License¶
Copyright (c) 2014, Rémy Hubscher. See Authors & contributors. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the piecutter software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Authors & contributors¶
Development lead¶
- Rémy Hubscher <hubscher.remy@gmail.com>
- Benoît Bryon <benoit@marmelune.net>
Contributors¶
Developers: https://github.com/diecutter/piecutter/graphs/contributors
Changelog¶
This document describes changes between each past release. For information about future releases, check milestones [1] and Vision.
0.2 (unreleased)¶
API simplification.
- Feature #9 -
piecutter.Cutter
class encapsulates template rendering process. Setup a cutter as you like, then use it to render templates. - Bug #11 - On PyPI, README is rendered as HTML (was not, because of some raw HTML). Badges were removed from PyPI page.
0.1.1 (2014-04-09)¶
Fixes around distribution of release 0.1.
- Bug #12 - piecutter archive on PyPI was missing many files.
0.1 (2014-04-08)¶
Initial release.
- Feature #6 - Imported stuff from diecutter: loaders, writers, resources and engines.
Notes & references
[1] | https://github.com/diecutter/piecutter/issues/milestones |
Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
This document provides guidelines for people who want to contribute to the project.
Resources¶
- Code repository: https://github.com/diecutter/piecutter
- Bugtracker: https://github.com/diecutter/piecutter/issues
- Continuous integration: https://travis-ci.org/diecutter/piecutter
Create tickets: bugs, features, feedback...¶
The best way to send feedback is to file an issue in the bugtracker [1].
Please use the bugtracker [1] before starting some work:
- check if the bug or feature request has already been filed. It may have been answered too!
- else create a new ticket.
- if you plan to contribute, tell us, so that we are given an opportunity to give feedback as soon as possible.
- in your commit messages, reference the ticket with some
refs #TICKET-ID
syntax.
Use topic branches¶
- Work in branches.
- Prefix your branch with the ticket ID corresponding to the issue. As an
example, if you are working on ticket #23 which is about contribute
documentation, name your branch like
23-contribute-doc
. - If you work in a development branch and want to refresh it with changes from master, please rebase [2] or merge-based rebase [3], i.e. do not merge master.
Fork, clone¶
Clone piecutter repository (adapt to use your own fork):
git clone git@github.com:<your-github-username-here>/piecutter.git
cd piecutter/
Setup a development environment¶
System requirements:
- Python [4] version 2.7 (in a virtualenv [5] if you like).
- make and wget to use the provided Makefile.
Execute:
make develop
Usual actions¶
The Makefile is the reference card for usual actions in development environment:
- Install development toolkit with pip [6]:
make develop
. - Run tests with tox [7]:
make test
. - Build documentation:
make documentation
. It builds Sphinx [8] documentation in var/docs/html/index.html. - Release piecutter project with zest.releaser [9]:
make release
. - Cleanup local repository:
make clean
,make distclean
andmake maintainer-clean
.
Notes & references
[1] | (1, 2) https://github.com/diecutter/piecutter/issues |
[2] | http://git-scm.com/book/en/Git-Branching-Rebasing |
[3] | http://tech.novapost.fr/psycho-rebasing-en.html |
[4] | http://python.org |
[5] | http://virtualenv.org |
[6] | https://pypi.python.org/pypi/pip/ |
[7] | https://pypi.python.org/pypi/tox/ |
[8] | https://pypi.python.org/pypi/Sphinx/ |
[9] | https://pypi.python.org/pypi/zest.releaser/ |