Import z3c.recipe.filetemplate package + egg

git-svn-id: svn://svn.zope.org/repos/main/z3c.recipe.filetemplate/trunk@80419 62d5b8a3-27da-0310-9561-8e5933582275

CHANGES.txt

@@ -0,0 +1,7 @@
+Changes
+=======
+
+1.0 (2007-09-30)
+----------------
+
+Initial release.

README.txt

@@ -0,0 +1 @@
+Please refer to z3c/recipe/filetemplate/README.txt

buildout.cfg

@@ -0,0 +1,7 @@
+[buildout]
+develop = .
+parts = test
+
+[test]
+recipe = zc.recipe.testrunner
+eggs = z3c.recipe.filetemplate

setup.py

@@ -0,0 +1,36 @@
+import os
+from setuptools import setup, find_packages
+
+def read(*rnames):
+    return open(os.path.join(os.path.dirname(__file__), *rnames)).read()
+
+setup(name='z3c.recipe.filetemplate',
+      version = '1.0',
+      license='ZPL 2.1',
+      description="zc.buildout recipe for creating files from file templates",
+      author='Philipp von Weitershausen',
+      author_email='philipp@weitershausen.de',
+      long_description=(read('z3c', 'recipe', 'filetemplate', 'README.txt')
+                        + '\n\n' +
+                        read('CHANGES.txt')),
+      classifiers = ['Development Status :: 5 - Production/Stable',
+                     'Intended Audience :: Developers',
+                     'License :: OSI Approved :: Zope Public License',
+                     'Programming Language :: Python',
+                     'Operating System :: OS Independent',
+                     'Topic :: Software Development :: Build Tools',
+                     'Framework :: Buildout',
+                     ],
+
+      packages=find_packages(),
+      namespace_packages=['z3c', 'z3c.recipe'],
+      install_requires=['setuptools',
+                        'zc.buildout',
+                        'zope.testing',
+                        ],
+      zip_safe=True,
+      entry_points="""
+      [zc.buildout]
+      default = z3c.recipe.filetemplate:FileTemplate
+      """
+      )

z3c/__init__.py

@@ -0,0 +1,7 @@
+# this is a namespace package
+try:
+    import pkg_resources
+    pkg_resources.declare_namespace(__name__)
+except ImportError:
+    import pkgutil
+    __path__ = pkgutil.extend_path(__path__, __name__)

z3c/recipe/__init__.py

@@ -0,0 +1,7 @@
+# this is a namespace package
+try:
+    import pkg_resources
+    pkg_resources.declare_namespace(__name__)
+except ImportError:
+    import pkgutil
+    __path__ = pkgutil.extend_path(__path__, __name__)

z3c/recipe/filetemplate/README.txt

@@ -0,0 +1,38 @@
+With the ``z3c.recipe.filetemplate`` buildout recipe you can automate
+the generation of text files from templates.  Upon execution, the
+recipe will read a number of template files, perform a simple variable
+substitution and write the result to the corresponding output files.
+
+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
+the ``z3c.recipe.filetemplate`` recipe.  With the ``files`` parameter
+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 = file
+  ...
+  ... [file]
+  ... recipe = z3c.recipe.filetemplate
+  ... files = helloworld.txt
+  ... world = Philipp
+  ... """)
+
+After executing buildout, we can see that ``$world`` has indeed been
+replaced by ``Philipp``:
+
+  >>> print system(buildout)
+  Installing file.
+
+  >>> cat(sample_buildout, 'helloworld.txt')
+  Hello Philipp!

z3c/recipe/filetemplate/__init__.py

@@ -0,0 +1,46 @@
+import os
+import string
+import logging
+import zc.buildout
+
+class FileTemplate(object):
+
+    def __init__(self, buildout, name, options):
+        self.buildout = buildout
+        self.name = name
+        self.options = options
+
+    def install(self, update=False):
+        here = self.buildout['buildout']['directory']
+        filenames = self.options['files'].split()
+        logger = logging.getLogger(self.name)
+
+        for filename in filenames:
+            if os.path.isabs(filename):
+                msg = ('%s is an absolute path. File paths must be '
+                       'relative to the buildout directory.' % filename)
+                logger.error(msg)
+                raise zc.buildout.UserError(msg)
+
+            absname = os.path.join(here, filename)
+
+            if not os.path.exists(absname + '.in'):
+                msg = 'No template found at %s.in.' % filename
+                logger.error(msg)
+                raise zc.buildout.UserError(msg)
+
+            if not update and os.path.exists(absname):
+                msg = ('File %s already exists. Please make sure that you '
+                       'really want to have it generated automatically.  Then '
+                       'move it away.' % filename)
+                logger.error(msg)
+                raise zc.buildout.UserError(msg)
+
+            templ = string.Template(open(absname + '.in').read())
+            outfile = open(absname, 'w')
+            outfile.write(templ.substitute(self.options))
+            outfile.close()
+        return filenames
+
+    def update(self):
+        return self.install(update=True)

z3c/recipe/filetemplate/tests.py

@@ -0,0 +1,14 @@
+import zc.buildout.testing
+from zope.testing import doctest
+
+def setUp(test):
+    zc.buildout.testing.buildoutSetUp(test)
+    zc.buildout.testing.install_develop('z3c.recipe.filetemplate', test)
+
+def test_suite():
+    return doctest.DocFileSuite(
+        'README.txt', 'tests.txt',
+        setUp=setUp,
+        tearDown=zc.buildout.testing.buildoutTearDown,
+        optionflags=doctest.NORMALIZE_WHITESPACE,
+        )

z3c/recipe/filetemplate/tests.txt

@@ -0,0 +1,158 @@
+Tests
+=====
+
+This file contains doctests that are mainly test rather than
+documentation.  The documentation doctests can be found in README.txt
+
+Multiple files
+--------------
+
+The recipe can subsitute the same set of variables on several files at
+the same time:
+
+  >>> write(sample_buildout, 'helloworld.txt.in',
+  ... """
+  ... Hello ${world}!
+  ... """)
+
+  >>> write(sample_buildout, 'goodbyeworld.txt.in',
+  ... """
+  ... Goodbye ${world}!
+  ... """)
+
+File names are separated by any kind of whitespace:
+
+  >>> write(sample_buildout, 'buildout.cfg',
+  ... """
+  ... [buildout]
+  ... parts = multiple
+  ...
+  ... [multiple]
+  ... recipe = z3c.recipe.filetemplate
+  ... files = helloworld.txt
+  ...         goodbyeworld.txt
+  ... world = Philipp
+  ... """)
+
+After executing buildout, we can see that ``$world`` has indeed been
+replaced by ``Philipp``:
+
+  >>> print system(buildout)
+  Installing multiple.
+
+Absolute paths
+--------------
+
+The recipe only accepts relative file paths.  For example, consider
+this invalid buildout configuration:
+
+  >>> write(sample_buildout, 'buildout.cfg',
+  ... """
+  ... [buildout]
+  ... parts = evil
+  ...
+  ... [evil]
+  ... recipe = z3c.recipe.filetemplate
+  ... files = /etc/passwd.in
+  ... root = me
+  ... """)
+
+  >>> print system(buildout)
+  Uninstalling multiple.
+  Installing evil.
+  evil: /etc/passwd.in is an absolute path. File paths must be
+        relative to the buildout directory.
+  While:
+    Installing evil.
+  Error: /etc/passwd.in is an absolute path. File paths must be
+         relative to the buildout directory.
+
+
+Missing template
+----------------
+
+The recipe will also complain with an error if you specify a file name
+for which no template can be found:
+
+  >>> write(sample_buildout, 'buildout.cfg',
+  ... """
+  ... [buildout]
+  ... parts = notthere
+  ...
+  ... [notthere]
+  ... recipe = z3c.recipe.filetemplate
+  ... files = doesntexist
+  ... """)
+
+  >>> print system(buildout)
+  Installing notthere.
+  notthere: No template found at doesntexist.in.
+  While:
+    Installing notthere.
+  Error: No template found at doesntexist.in.
+
+
+Already existing file
+---------------------
+
+Another case where the recipe will complain is when you're trying to
+replace a file that's already there:
+
+  >>> write(sample_buildout, 'alreadyhere.txt',
+  ... """
+  ... I'm already here
+  ... """)
+
+  >>> write(sample_buildout, 'alreadyhere.txt.in',
+  ... """
+  ... I'm the template that's supposed to replace the file above.
+  ... """)
+
+  >>> write(sample_buildout, 'buildout.cfg',
+  ... """
+  ... [buildout]
+  ... parts = alreadythere
+  ...
+  ... [alreadythere]
+  ... recipe = z3c.recipe.filetemplate
+  ... files = alreadyhere.txt
+  ... """)
+
+  >>> print system(buildout)
+  Installing alreadythere.
+  alreadythere: File alreadyhere.txt already exists. Please make sure
+                that you really want to have it generated automatically.
+                Then move it away.
+  While:
+    Installing alreadythere.
+  Error: File alreadyhere.txt already exists. Please make sure
+         that you really want to have it generated automatically.
+         Then move it away.
+
+
+Missing variables
+-----------------
+
+The recipe will also fail to execute if a template refers to variables
+that aren't defined in ``buildout.cfg``:
+
+  >>> write(sample_buildout, 'missing.txt.in',
+  ... """
+  ... Hello ${world}!
+  ... """)
+
+  >>> write(sample_buildout, 'buildout.cfg',
+  ... """
+  ... [buildout]
+  ... parts = missing
+  ...
+  ... [missing]
+  ... recipe = z3c.recipe.filetemplate
+  ... files = missing.txt
+  ... """)
+
+  >>> print system(buildout)
+  Installing missing.
+  While:
+    Installing missing.
+  Error: Missing option: missing:world