Package: as.recipe.filetemplate
Basic UsageWith theas.recipe.filetemplatebuildout recipe you can automate
the generation of text files from templates.  Upon execution, the
recipe will read a number of template files, perform variable
substitution and write the result to the corresponding output files.The recipe has several features, but it always takes template files with a.insuffix, processes the template, and writes out the file to the desired
location with the same file mode, and the same name but without the.insuffix.For example, consider this simple template for a text file:>>> write(sample_buildout, 'helloworld.txt.in',
... """
... Hello ${world}!
... """)Now let’s create a buildout configuration so that we can substitute
the values in this file.  All we have to do is define a part that uses
theas.recipe.filetemplaterecipe.  With thefilesparameter
we specify one or more files that need substitution (separated by
whitespace).  Then we can add arbitrary parameters to the section.
Those will be used to fill the variables in the template:>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.recipe.filetemplate
... files = helloworld.txt
... world = Philipp
... """)After executing buildout, we can see that${world}has indeed been
replaced byPhilipp:>>> print system(buildout)
Installing message.>>> cat(sample_buildout, 'helloworld.txt')
Hello Philipp!If you need to escape the ${…} pattern, you can do so by repeating the dollar
sign.>>> update_file(sample_buildout, 'helloworld.txt.in',
... """
... Hello world! The double $${dollar-sign} escapes!
... """)>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'helloworld.txt')
Hello world! The double ${dollar-sign} escapes!Note that dollar signs alone, without curly braces, are not parsed.>>> update_file(sample_buildout, 'helloworld.txt.in',
... """
... $Hello $$world! $$$profit!
... """)>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'helloworld.txt')
$Hello $$world! $$$profit!Note that the output file uses the same permission bits as found on the input
file.>>> import stat
>>> import os
>>> input = os.path.join(sample_buildout, 'helloworld.txt.in')
>>> output = input[:-3]
>>> os.chmod(input, 0755)
>>> stat.S_IMODE(os.stat(input).st_mode) == 0755
True
>>> stat.S_IMODE(os.stat(output).st_mode) == 0755
False
>>> print system(buildout)
Uninstalling message.
Installing message.
>>> stat.S_IMODE(os.stat(output).st_mode) == 0755
TrueSource Folders and GlobsBy default, the recipe looks for a.infile 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 asource-directoryin the buildout.  You can specifyfilesas a filter if desired, but by default it will find any file (ending
with “.in”). You can also specifyexclude-directoriesoption if you want
to exclude some paths from thesource-directorysearch path.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.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, thehelloworld.txtfile is still
around, we don’t have an etc directory, and the bin directory doesn’t have ourhelloworld.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')
-  buildoutNow 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  templateThe 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 thefilesoption along withsource-directory, it becomes a
filter.  Every target file must match at least one of the names infiles.
Therefore, if we only build .sh files, the etc directory will disappear.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.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.shAlso note that, if you use a source directory and yourfilesspecify a
directory, the directory must match precisely.With theexclude-directoriesparameter, we specify one or more directories
(separated by whitespace) in which the recipe will not look for template
files. Theexclude-directoriesoption should be used along with thesource-directoryoption.
Therefore, if we setexclude-directoriestobin, thebin/helloworld.shfile will disappear.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.recipe.filetemplate
... source-directory = template
... exclude-directories = bin
... world = Philipp
... """)>>> 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>>> ls(sample_buildout, 'etc')
- helloworld.conf>>> ls(sample_buildout, 'bin')
- buildout>>> # 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'))Advanced UsageSubstituting from Other SectionsSubstitutions 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 = as.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 ExtensionsSubstitutions 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.txtFiltersYou 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 inHELLO 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.  SeeWorking with Pathsfor 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 theWorking with Pathssection.>>> 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 = as.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 VariablesThe recipe allows extending one or more sections, to decrease
repetition, using theextendsoption.  For instance, consider the
following buildout.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [template_defaults]
... mygreeting = Hi
... myaudience = World
...
... [message]
... recipe = as.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 inHi, everybody!.>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'helloworld.txt')
Hi, everybody!Defining options in PythonYou can specify that certain variables should be interpreted as Python usinginterpreted-options.  This takes zero or more lines.  Each line should
specify an option.  It can define immediately (seesilly-rangein
the example below) or point to an option to be interepreted, which can
be useful if you want to define a multi-line expression (seefirst-interpreted-optionandmessage-reversed-is-egassem).>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.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: egassemWorking with PathsWe’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.Demonstration ofpath-reprLet’s say we want to make a custom Python script in the bin directory.
It will print some information from a file in adatadirectory
within the buildout root.  Here’s the template.>>> write(sample_buildout, 'template', 'bin', 'dosomething.py.in', '''\
... #!${buildout:executable}
... ${python-relative-path-setup}
... f = open(${buildout:directory/data/info.csv|path-repr})
... print f.read()
... ''')
>>> os.chmod(
...     os.path.join(
...         sample_buildout, 'template', 'bin', 'dosomething.py.in'),
...     0711)If we evaluate that template with relative-paths set to false, the results
shouldn’t be too surprising.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.recipe.filetemplate
... source-directory = template
... """)>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'bin', 'dosomething.py') # doctest: +ELLIPSIS
#!...
<BLANKLINE>
f = open('/.../sample-buildout/data/info.csv')
print f.read()${python-relative-path-setup}evaluated to an empty string.  The path
is absolute and quoted.If we evaluate it with relative-paths set to true, the results are much…
bigger.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
... relative-paths = true
...
... [message]
... recipe = as.recipe.filetemplate
... source-directory = template
... """)>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'bin', 'dosomething.py') # doctest: +ELLIPSIS
#!...
import os, imp
# Get path to this file.
if __name__ == '__main__':
    _z3c_recipe_filetemplate_filename = __file__
else:
    # If this is an imported module, we want the location of the .py
    # file, not the .pyc, because the .py file may have been symlinked.
    _z3c_recipe_filetemplate_filename = imp.find_module(__name__)[1]
# Get the full, non-symbolic-link directory for this file.
_z3c_recipe_filetemplate_base = os.path.dirname(
    os.path.abspath(os.path.realpath(_z3c_recipe_filetemplate_filename)))
# Ascend to buildout root.
_z3c_recipe_filetemplate_base = os.path.dirname(
    _z3c_recipe_filetemplate_base)
def _z3c_recipe_filetemplate_path_repr(path):
    "Return absolute version of buildout-relative path."
    return os.path.join(_z3c_recipe_filetemplate_base, path)
<BLANKLINE>
f = open(_z3c_recipe_filetemplate_path_repr('data/info.csv'))
print f.read()That’s quite a bit of code.  You might wonder why we don’t just use ‘..’ for
parent directories.  The reason is that we want our scripts to be usable
from any place on the filesystem.  If we used ‘..’ to construct paths
relative to the generated file, then the paths would only work from
certain directories.So that’s how path-repr works.  It can really come in handy if you want
to support relative paths in buildout.  Now let’s look at the shell-path
filter.Demonstration ofshell-pathMaybe you want to write some shell scripts.  The shell-path filter will help
you support buildout relative-paths fairly painlessly.Right now, only POSIX is supported with the shell-path filter, as mentioned
before.Usage is very similar to thepath-reprfilter.  You need to include${shell-relative-path-setup}before you use it, just as you include${python-relative-path-setup}before usingpath-repr.Let’s say we want to make a custom shell script in the bin directory.
It will print some information from a file in adatadirectory
within the buildout root.  Here’s the template.>>> write(sample_buildout, 'template', 'bin', 'dosomething.sh.in', '''\
... #!/bin/sh
... ${shell-relative-path-setup}
... cat ${buildout:directory/data/info.csv|shell-path}
... ''')
>>> os.chmod(
...     os.path.join(
...         sample_buildout, 'template', 'bin', 'dosomething.sh.in'),
...     0711)If relative-paths is set to false (the default), the results are simple.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.recipe.filetemplate
... source-directory = template
... """)>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'bin', 'dosomething.sh') # doctest: +ELLIPSIS
#!/bin/sh
<BLANKLINE>
cat /.../sample-buildout/data/info.csv${shell-relative-path-setup}evaluated to an empty string.  The path
is absolute.Now let’s look at the larger code when relative-paths is set to true.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
... relative-paths = true
...
... [message]
... recipe = as.recipe.filetemplate
... source-directory = template
... """)>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'bin', 'dosomething.sh') # doctest: +ELLIPSIS
#!/bin/sh
# Get full, non-symbolic-link path to this file.
Z3C_RECIPE_FILETEMPLATE_FILENAME=`\
    readlink -f "$0" 2>/dev/null || \
    realpath "$0" 2>/dev/null || \
    type -P "$0" 2>/dev/null`
# Get directory of file.
Z3C_RECIPE_FILETEMPLATE_BASE=`dirname ${Z3C_RECIPE_FILETEMPLATE_FILENAME}`
# Ascend to buildout root.
Z3C_RECIPE_FILETEMPLATE_BASE=`dirname ${Z3C_RECIPE_FILETEMPLATE_BASE}`
<BLANKLINE>
cat "$Z3C_RECIPE_FILETEMPLATE_BASE"/data/info.csvAs with the Python code, we don’t just use ‘..’ for
parent directories because we want our scripts to be usable
from any place on the filesystem.Getting Arbitrary Dependency PathsYou can specifyeggsandextra-pathsin the recipe.  The
mechanism is the same as the one provided by the zc.recipe.egg, so
pertinent options such as find-links and index are available.If you do, the paths for the dependencies will be calculated.  They will
be available as a list in the namespace of the interpreted options aspaths.  Also, three predefined options will be available in the
recipe’s options for the template.Ifpathsare the paths,shell_pathis theshell-pathfilter, andpath_repris thepath-reprfilter, then the pre-defined options
would be defined roughly as given here:os-paths(for shell scripts)(os.pathsep).join(shell_path(path)for path in paths)string-paths(for Python scripts)',\n'.join(path_repr(path) for path in paths)space-paths(for shell scripts)' '.join(shell_path(path) for path in paths)Therefore, if you want to support the relative-paths option, you should
include${shell-relative-path-setup}(foros-pathsandspace-paths) or${python-relative-path-setup}(forstring-paths)
as appropriate at the top of your template.Let’s consider a simple example.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.recipe.filetemplate
... files = helloworld.txt
... eggs = demo<0.3
...
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))The relative-paths option is false, the default.>>> write(sample_buildout, 'helloworld.txt.in',
... """
... Hello!  Here are the paths for the ${eggs} eggs.
... OS paths:
... ${os-paths}
... ---
... String paths:
... ${string-paths}
... ---
... Space paths:
... ${space-paths}
... """)>>> print system(buildout)
Getting distribution for 'demo<0.3'.
Got demo 0.2.
Getting distribution for 'demoneeded'.
Got demoneeded 1.2c1.
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'helloworld.txt') # doctest:+ELLIPSIS
Hello!  Here are the paths for the demo<0.3 eggs.
OS paths:
/.../eggs/demo-0.2...egg:/.../eggs/demoneeded-1.2c1...egg
---
String paths:
'/.../eggs/demo-0.2...egg',
'/.../eggs/demoneeded-1.2c1...egg'
---
Space paths:
/.../eggs/demo-0.2...egg /.../eggs/demoneeded-1.2c1...eggYou can specify extra-paths as well, which will go at the end of the egg
paths.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
...
... [message]
... recipe = as.recipe.filetemplate
... files = helloworld.txt
... eggs = demo<0.3
... extra-paths = ${buildout:directory}/foo
...
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'helloworld.txt') # doctest:+ELLIPSIS
Hello!  Here are the paths for the demo<0.3 eggs.
OS paths:
/...demo...:/...demoneeded...:/.../sample-buildout/foo
---
String paths:
'/...demo...',
'/...demoneeded...',
'/.../sample-buildout/foo'
---
Space paths:
/...demo... /...demoneeded... .../sample-buildout/fooTo emphasize the effect of the relative-paths option, let’s see what it looks
like when we set relative-paths to True.>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = message
... relative-paths = true
...
... [message]
... recipe = as.recipe.filetemplate
... files = helloworld.txt
... eggs = demo<0.3
... extra-paths = ${buildout:directory}/foo
...
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))>>> print system(buildout)
Uninstalling message.
Installing message.>>> cat(sample_buildout, 'helloworld.txt') # doctest:+ELLIPSIS
Hello!  Here are the paths for the demo<0.3 eggs.
OS paths:
"$Z3C_RECIPE_FILETEMPLATE_BASE"/eggs/demo-0.2-py...egg:"$Z3C_RECIPE_FILETEMPLATE_BASE"/eggs/demoneeded-1.2c1-py...egg:"$Z3C_RECIPE_FILETEMPLATE_BASE"/foo
---
String paths:
_z3c_recipe_filetemplate_path_repr('eggs/demo-0.2-py...egg'),
_z3c_recipe_filetemplate_path_repr('eggs/demoneeded-1.2c1-py...egg'),
_z3c_recipe_filetemplate_path_repr('foo')
---
Space paths:
"$Z3C_RECIPE_FILETEMPLATE_BASE"/eggs/demo-0.2-py...egg "$Z3C_RECIPE_FILETEMPLATE_BASE"/eggs/demoneeded-1.2c1-py...egg "$Z3C_RECIPE_FILETEMPLATE_BASE"/fooRemember, your script won’t really work unless you include${shell-relative-path-setup}(foros-pathsandspace-paths)
or${python-relative-path-setup}(forstring-paths) as
appropriate at the top of your template.Getting Dependency Paths fromzc.recipe.eggYou can get theeggsandextra-pathsfrom another section using
zc.recipe.egg by using theextendsoption from theSharing Variablessection above.  Then you can use the template options described above to
build your paths in your templates.Getting Dependency Paths fromz3c.recipe.scriptsIf, like the Launchpad project, you are using Gary Poster’s unreleased
packagez3c.recipe.scriptsto generate your scripts, and you want to
have your scripts use the same Python environment as generated by that
recipe, you can just use the path-repr and shell-path filters with standard
buildout directories.  Here is an example buildout.cfg.[buildout]
parts = scripts message
relative-paths = true

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

[message]
recipe = as.recipe.filetemplate
files = helloworld.pyThen the template to use this would want to simply put${scripts:parts-directory|path-repr}at the beginning of Python’s path.You can do this for subprocesses with PYTHONPATH.${python-relative-path-setup}
import os
import subprocess
env = os.environ.copy()
env[‘PYTHONPATH’] = ${scripts:parts-directory|path-repr}
subprocess.call(‘myscript’, env=env)That’s it.Similarly, here’s an approach to making a script that will have the
right environment.  You want to put the parts directory of the
z3c.recipe.scripts section in the sys.path before site.py is loaded.
This is usually handled by z3c.recipe.scripts itself, but sometimes you
may want to write Python scripts in your template for some reason.#!/usr/bin/env python -S
${python-relative-path-setup}
import sys
sys.path.insert(0, ${scripts:parts-directory|path-repr})
import site
# do stuff…If you do this for many scripts, put this entire snippet in an option in the
recipe and use this snippet as a single substitution in the top of your
scripts.Changes2.2.0 (2011-09-01)FeaturesAdd support for excluding some subdirectories of thesource-directorywith theexclude-directoriesoption.  [Bruno Binet]FixesAdded undeclared but necessary test dependency onzope.testingin a
test extra.Added test dependency onz3c.recipe.scriptsas it is required by newerzc.buildoutversions.Using python’sdoctestmodule instead of deprecatedzope.testing.doctest.2.1.0 (2010-04-21)FeaturesEnable cross-platform paths by allowing an extended syntax for path
suffixes. Example: If${buildout:directory}resolves to/sample_buildouton a POSIX system andC:\sample_buildoutin
Windows,${buildout:directory/foo.txt}will resolve to/sample_buildout/foo.txtandC:\sample_buildout\foo.txt,
respectively.Add filters via a pipe syntax, reminiscent of UNIX pipes or Django template
filters. Simple example: if${name}resolves toharrythen${name|upper}resolves toHARRY.  Simple string filters are
upper, lower, title, and capitalize, just like the Python string
methods.  Also see the next bullet.Added support for the buildout relative-paths option.  Shell scripts should
include${shell-relative-path-setup}before commands with
buildout-generated paths are executed.  Python scripts should use${python-relative-path-setup}similarly.${os-paths}(shell),${space-paths}(shell), and${string-paths}(Python) will have
relative paths if the buildout relative-paths option is used.  To convert
individual absolute paths to relative paths, use thepath-reprfilter
in Python scripts and theshell-pathfilter in shell scripts.  Path
suffixes can be combined with these filters, so, if buildout’s
relative-paths option is true,${buildout:directory/foo.txt|path-repr}will produce a buildout-relative, platform appropriate path to
foo.txt.  Note that for shell scripts, Windows is not supported at
this time.Support escaping${...}with$${...}in templates.  This is
particularly useful for UNIX shell scripts.FixesMake tests less susceptible to timing errors.Changes${os-paths}and${space-paths}no longer filter out .zip paths.The entries in${string-paths}now are separated by newlines. Each
entry is indented to the level of the initial placement of the marker.2.0.3 (2009-07-02)FixesUserealpathhelper 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)FixesTurns 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 themlessdeterministic in practice, across machines.2.0.1 (2009-04-30)FixesCorrect sdist generation to include all necessary files.Doc formatting fixes.Correct “Destinations already exist” message to list destinations without.insuffix.2.0 (2009-04-30)FeaturesStore your template files in a separate directory structure, using thesource-directoryoption.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 typicalextendsoption.Create destination directories automatically.Define option values for templates dynamically in Python with theinterpreted-optionsoption.Get paths for eggs by specifyingeggsandextra-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 theinterpreted-optionsfeature.Templates are not processed if there are no changes to them or the buildout.1.0 (2007-09-30)Initial release.