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 by XDG_DATA_DIRS
  • The versionah package’s templates 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 reading versionah files
  • major, minor, micro and patch for the version components
  • tuple all version components as a tuple
  • resolution number of components used by version
  • name for the package name
  • dateobj for release date as a datetime.date object
  • now and utcnow for template creation timestamps, refer to the datetime documentation for information on now() and utcnow()
  • The output file’s name as filename
  • All supported display methods [1], for example dotted and libtool

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]", "_") %}