Version templates

Version files are created from templates using Armin Ronacher’s excellent 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 may benefit.

Template locations

Templates are loaded from directories in the following order:

• If it exists, ${XDG_DATA_HOME:~/.local/share}/versionah/templates

• Any versionah/templates directory in the directories specified by XDG_DATA_DIRS

• The versionah package’s templates directory

Note

For OS X users versionah will 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.

Nevertheless, 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 among a set of projects, 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:

Variable	Content
magic	Magic string to support re-reading versionah files
major / minor / micro / patch	Individual component parts
tuple	Version components as a tuple of integers
resolution	The number of components used by the version object, mainly useful for advanced template logic
name	The package name
dateobj	Release date as a datetime.date object
now	File creation timestamp in the local timezone
utcnow	File creation timestamp in UTC
filename	Output file’s name

In addition to the above list variables, all of the supported display methods1 — for example dotted and libtool — are available for use too.

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 stamp2.

The text display’s template is simply:

{{ magic }}

which results in output such as:

This is mypkg version 2.2.4 (2011-02-19)

Note

If you’re authoring your own templates and you find that you need extra data for use in their generation open an issue.

Filters

versionah defines various filters beyond the huge range of built-in filters in Jinja, please refer to the jnrbase.template documentation for more information.

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 may benefit from your work.

For example, the regexp filter is used in the C template to make valid identifiers from filename by replacing characters that are invalid in identifiers with underscores:

{% set escaped_name = filename|upper|regexp("[^A-Z]", "_") %}

Footnotes

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.