Version templates¶
Version files are created from templates using Jinja. Before writing your own templates you should read the splendid Jinja template designer documentation.
Note
If you create some cool templates of your own please consider posting them in an issue or pushing them to a fork on GitHub, so that others can benefit.
Template locations¶
Templates are loaded from directories in the following order:
- If it exists,
${XDG_DATA_HOME:~/.local}/versionah/templates
- Any
versionah/templates
directory in the directories specified byXDG_DATA_DIRS
- The
versionah
package’stemplates
directory
Note
For OS X users there is a fallback to ~/Library/Application Support
,
if XDG_DATA_HOME
is unset.
Precedence¶
The first name match in the order specified above selects the template, so a py.jinja
file in
$XDG_DATA_HOME/versionah/templates
overrides the py.jinja
template provided with versionah
.
Naming¶
Templates should be named after the common type suffix if possible, doing so
allows versionah
to guess an appropriate template from a supplied file. For
example, py.jinja
will apply by default to all files ending in .py
.
However, templates can be given any name you wish. This makes it simple to have project specific templates, should the need arise. This functionality is especially useful if you have shared data as you can use Jinja’s Template Inheritance support to reduce the duplication needed in each template.
Data¶
Each template is provided with the following variables for use in the output:
magic
for the magic string to support readingversionah
filesmajor
,minor
,micro
andpatch
for the version componentstuple
all version components as a tupleresolution
number of components used by versionname
for the package namedateobj
for release date as adatetime.date
objectnow
andutcnow
for template creation timestamps, refer to thedatetime
documentation for information onnow()
andutcnow()
- The output file’s name as
filename
- All supported display methods [1], for example
dotted
andlibtool
Jinja templates support object attribute and method access, so the utcnow
object can be called with the strftime()
method for
custom timestamp output. For example, {{ utcnow.strftime("%a, %e %b %Y
%H:%M:%S %z") }}
could be used to output an RFC 2822 date stamp [2].
The text
display’s template is simply:
{{ magic }}
which results in output such as:
This is mypkg version 2.2.4 (2011-02-19)
If you’re authoring your own templates and you find you need extra data for use in their generation open an issue.
[1] | Technically the result of any Version method beginning with as_
is passed along to the template, with the as_ prefixes removed. |
[2] | But don’t do that, as strftime() is locale
dependent ;) |
Filters¶
versionah
defines the following filters beyond the huge range of built-in
filters in Jinja:
Note
If you write extra filters and believe they could be of use to other
versionah
users please consider posting them in an issue or pushing them
to a fork on GitHub, so that others can benefit from your work.
regexp
¶
This filter applies a regular expression to a value, it is a thin wrapper around
re.sub()
and takes the same arguments.
For example, it is used in the C template to make valid identifiers from
filename
by replacing invalid characters with underscores:
{% set escaped_name = filename|upper|regexp("[^A-Z]", "_") %}