z3c.recipe.filetemplate 2.1.0

Source Folders and Globs

By default, the recipe looks for a .in file relative to the buildout root, and places it in the same folder relative to the buildout root. However, if you don’t want to clutter up the destination folder, you can add a prefix to the source folder. Here is an example.

First, we specify a source-directory in the buildout. You can specify files as a filter if desired, but by default it will find any file (ending with “.in”).

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = z3c.recipe.filetemplate
... source-directory = template
... world = Philipp
... """)

Now we’ll make a “template” directory, as listed in the buildout configuration above, and populate it for our example.

>>> mkdir(sample_buildout, 'template')
>>> mkdir(sample_buildout, 'template', 'etc')
>>> mkdir(sample_buildout, 'template', 'bin')
>>> write(sample_buildout, 'template', 'etc', 'helloworld.conf.in',
... """
... Hello ${world} from the etc dir!
... """)
>>> write(sample_buildout, 'template', 'bin', 'helloworld.sh.in',
... """
... Hello ${world} from the bin dir!
... """)
>>> os.chmod(
...     os.path.join(
...         sample_buildout, 'template', 'bin', 'helloworld.sh.in'),
...     0711)

Notice that, before running buildout, the helloworld.txt file is still around, we don’t have an etc directory, and the bin directory doesn’t have our helloworld.sh.

>>> ls(sample_buildout)
-  .installed.cfg
d  bin
-  buildout.cfg
d  develop-eggs
d  eggs
-  helloworld.txt
-  helloworld.txt.in
d  parts
d  template
>>> ls(sample_buildout, 'bin')
-  buildout

Now we install. The old “helloworld.txt” is gone, and we now see etc. Note that, for the destination, intermediate folders are created if they do not exist.

>>> print system(buildout)
Uninstalling message.
Installing message.
>>> ls(sample_buildout)
-  .installed.cfg
d  bin
-  buildout.cfg
d  develop-eggs
d  eggs
d  etc
-  helloworld.txt.in
d  parts
d  template

The files exist and have the content we expect.

>>> ls(sample_buildout, 'bin')
- buildout
- helloworld.sh
>>> cat(sample_buildout, 'bin', 'helloworld.sh')
Hello Philipp from the bin dir!
>>> stat.S_IMODE(os.stat(os.path.join(
...     sample_buildout, 'bin', 'helloworld.sh')).st_mode) == 0711
True
>>> ls(sample_buildout, 'etc')
- helloworld.conf
>>> cat(sample_buildout, 'etc', 'helloworld.conf')
Hello Philipp from the etc dir!

If you use the files option along with source-directory, it becomes a filter. Every target file must match at least one of the names in files. Therefore, if we only build .sh files, the etc directory will disappear.

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = z3c.recipe.filetemplate
... source-directory = template
... files = *.sh
... world = Philipp
... """)

>>> print system(buildout)
Uninstalling message.
Installing message.
>>> ls(sample_buildout)
-  .installed.cfg
d  bin
-  buildout.cfg
d  develop-eggs
d  eggs
-  helloworld.txt.in
d  parts
d  template

>>> ls(sample_buildout, 'bin')
- buildout
- helloworld.sh

Also note that, if you use a source directory and your files specify a directory, the directory must match precisely.

>>> # Clean up for later test.
>>> import shutil
>>> shutil.rmtree(os.path.join(sample_buildout, 'template', 'etc'))
>>> os.remove(os.path.join(
...     sample_buildout, 'template', 'bin', 'helloworld.sh.in'))

Substituting from Other Sections

Substitutions can also come from other sections in the buildout, using the standard buildout syntax, but used in the template. Notice ${buildout:parts} in the template below.

>>> update_file(sample_buildout, 'helloworld.txt.in',
... """
... Hello ${world}.  I used these parts: ${buildout:parts}.
... """)
>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = z3c.recipe.filetemplate
... files = helloworld.txt
... world = Philipp
... """)

>>> print system(buildout)
Uninstalling message.
Installing message.

>>> cat(sample_buildout, 'helloworld.txt')
Hello Philipp.  I used these parts: message.

Path Extensions

Substitutions can have path suffixes using the POSIX “/” path separator. The template will convert these to the proper path separator for the current OS. They also then are part of the value passed to filters, the feature described next. Notice ${buildout:directory/foo/bar.txt} in the template below.

>>> update_file(sample_buildout, 'helloworld.txt.in',
... """
... Here's foo/bar.txt in the buildout:
... ${buildout:directory/foo/bar.txt}
... """)

>>> print system(buildout)
Uninstalling message.
Installing message.

>>> cat(sample_buildout, 'helloworld.txt') # doctest: +ELLIPSIS
Here's foo/bar.txt in the buildout:
/.../sample-buildout/foo/bar.txt

Filters

You can use pipes within a substitution to filter the original value. This recipe provides several filters for you to use. The syntax is reminiscent of (and inspired by) POSIX pipes and Django template filters. For example, if world = Philipp, HELLO ${world|upper}! would result in HELLO PHILIPP!.

A few simple Python string methods are exposed as filters right now:

• capitalize: First letter in string is capitalized.

• lower: All letters in string are lowercase.

• title: First letter of each word in string is capitalized.

• upper: All letters in string are uppercase.

Other filters are important for handling paths if buildout’s relative-paths option is true. See Working with Paths for more details.

• path-repr: Converts the path to a Python expression for the path. If buildout’s relative-paths option is false, this will simply be a repr of the absolute path. If relative-paths is true, this will be a function call to convert a buildout-relative path to an absolute path; it requires that ${python-relative-path-setup} be included earlier in the template.

• shell-path: Converts the path to a shell expression for the path. Only POSIX is supported at this time. If buildout’s relative-paths option is false, this will simply be the absolute path. If relative-paths is true, this will be an expression to convert a buildout-relative path to an absolute path; it requires that ${shell-relative-path-setup} be included earlier in the template.

Combining the three advanced features described so far, then, if the buildout relative-paths option were false, we were in a POSIX system, and the sample buildout were in the root of the system, the template expression ${buildout:bin-directory/data/initial.csv|path-repr} would result in '/sample-buildout/bin/data/initial.csv'.

Here’s a real, working example of the string method filters. We’ll have examples of the path filters in the Working with Paths section.

>>> update_file(sample_buildout, 'helloworld.txt.in',
... """
... HELLO ${world|upper}!
... hello ${world|lower}.
... ${name|title} and the Chocolate Factory
... ${sentence|capitalize}
... """)

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = z3c.recipe.filetemplate
... files = helloworld.txt
... world = Philipp
... name = willy wonka
... sentence = that is a good book.
... """)

>>> print system(buildout)
Uninstalling message.
Installing message.

>>> cat(sample_buildout, 'helloworld.txt') # doctest: +ELLIPSIS
HELLO PHILIPP!
hello philipp.
Willy Wonka and the Chocolate Factory
That is a good book.

Sharing Variables

The recipe allows extending one or more sections, to decrease repetition, using the extends option. For instance, consider the following buildout.

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [template_defaults]
... mygreeting = Hi
... myaudience = World
...
... [message]
... recipe = z3c.recipe.filetemplate
... files = helloworld.txt
... extends = template_defaults
...
... myaudience = everybody
... """)

The “message” section now has values extended from the “template_defaults” section, and overwritten locally. A template of ${mygreeting}, ${myaudience}!…

>>> update_file(sample_buildout, 'helloworld.txt.in',
... """
... ${mygreeting}, ${myaudience}!
... """)

…would thus result in Hi, everybody!.

>>> print system(buildout)
Uninstalling message.
Installing message.

>>> cat(sample_buildout, 'helloworld.txt')
Hi, everybody!

Defining options in Python

You can specify that certain variables should be interpreted as Python using interpreted-options. This takes zero or more lines. Each line should specify an option. It can define immediately (see silly-range in the example below) or point to an option to be interepreted, which can be useful if you want to define a multi-line expression (see first-interpreted-option and message-reversed-is-egassem).

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = z3c.recipe.filetemplate
... files = helloworld.txt
... interpreted-options = silly-range = repr(range(5))
...                       first-interpreted-option
...                       message-reversed-is-egassem
... first-interpreted-option =
...     options['interpreted-options'].splitlines()[0].strip()
... message-reversed-is-egassem=
...     ''.join(
...         reversed(
...             buildout['buildout']['parts']))
... not-interpreted=hello world
... """)

>>> update_file(sample_buildout, 'helloworld.txt.in', """\
... ${not-interpreted}!
... silly-range: ${silly-range}
... first-interpreted-option: ${first-interpreted-option}
... message-reversed-is-egassem: ${message-reversed-is-egassem}
... """)

>>> print system(buildout)
Uninstalling message.
Installing message.

>>> cat(sample_buildout, 'helloworld.txt') # doctest:+ELLIPSIS
hello world!
silly-range: [0, 1, 2, 3, 4]
first-interpreted-option: silly-range = repr(range(5))
message-reversed-is-egassem: egassem

Working with Paths

We’ve already mentioned how to handle buildout’s relative-paths option in the discussion of filters. This section has some concrete examples and discussion of that. It also introduces how to get a set of paths from specifying dependencies.

Here are concrete examples of the path-repr and shell-path filters. We’ll show results when relative-paths is true and when it is false.

[buildout]
parts = scripts message
relative-paths = true

[scripts]
recipe = z3c.recipe.scripts
eggs = demo<0.3

[message]
recipe = z3c.recipe.filetemplate
files = helloworld.py

2.1.0 (2010-04-21)

2.0.3 (2009-07-02)

Fixes

• Use realpath helper function from zc.buildout on the buildout directory too, such that it goes through the same normalization as the path being compared and stands a chance of working on Windows, due to possible drive letter case differences.

2.0.2 (2009-05-04)

Fixes

• Turns out sorting paths was a bad idea. They are already in a deterministic order, AFAICT, because of the order or processing dependencies. Sorting them makes them less deterministic in practice, across machines.

2.0.1 (2009-04-30)

Fixes

• Correct sdist generation to include all necessary files.

• Doc formatting fixes.

• Correct “Destinations already exist” message to list destinations without .in suffix.

2.0 (2009-04-30)

Features

• Store your template files in a separate directory structure, using the source-directory option.

• Specify multiple files automatically with globs.

• Templates can reference other buildout sections using the usual syntax, e.g. ${buildout:parts}

• Share options with other sections using the typical extends option.

• Create destination directories automatically.

• Define option values for templates dynamically in Python with the interpreted-options option.

• Get paths for eggs by specifying eggs and extra-paths, just like zc.recipe.egg script recipe. These are available in template options in colon-delimited, space-delimited, and quoted variants. You can also build your own using the interpreted-options feature.

• Templates are not processed if there are no changes to them or the buildout.

1.0 (2007-09-30)

Initial release.