distutils-extend

Last modified 4 years ago Last modified on 03/19/2014 02:15:49 PM

A test distribution to demonstrate a custom distutils command.

git clone https://chrisarndt.de/git/distutils-extend.git

What is this?

The fill_template module provides a custom distutils command via the FillTemplate class. The setup.py file of this distribution makes this available under the setup command name filltmpl.

The filltmpl command reads text file templates and replaces place-holders for distribution meta-data with their actual values, which are provided by the arguments to the setup(...) call. The template files must have a special filename extension, which marks them as such (default .in). The filled templates are then written to new files, with the file name extension stripped off.

There are three ways to specify the template files:

  • with the templates option in section filltmpl of setup.cfg.

    You must pass the template paths as a single string where paths are separated by whitespace. Paths with whitespace in them can be quoted.

  • with the command line option --templates.

    The format is the same as the setup.cfg option and the command line option takes precedence over the former.

  • With the templates keyword argument to setup().

    The value must a list of strings in this case and the template path specified this way are added to the templates named in setup.cfg or via the command line.

Place-holders in template files take the form $placeholder or ${placeholder} since template files are treated as input to string.Template. Valid place-holder names correspond to the attributes of the DistributionMetadata class in the distutils.dist module.

Usage

To use the custom distutils command run:

$ python setup.py filltmpl

To get a list of options run:

$ python setup.py filltmpl --help

Example

If you have a file README.txt.in in your project folder, next to your setup.py file with the following contents:

Welcome to $name version ${version}!

And your setup.py has the following call to setup():

setup(
    name="mypackage"
    version="1.0."
    ...
)

Then you can run:

$ python setup.py filltmpl --templates README.txt.in

and you'll get a new README.txt file with this content:

Welcome to mypackage version 1.0!