Metadata-Version: 1.0
Name: slapos.recipe.template
Version: 2.3
Summary: Templating recipe with remote resource support.
Home-page: UNKNOWN
Author: UNKNOWN
Author-email: UNKNOWN
License: GPLv3
Description: ======================
        slapos.recipe.template
        ======================
        
        Template recipe which supports remote resource.
        
        Inspired by collective.recipe.template, with minimum set of features, but with
        (hopefully) safer buildout-based templating.
        
        "jinja2" entry point allows rendering jinja2 templates.
        
        Usage
        =====
        
        Getting started
        ---------------
        
        You can start by a simple buildout::
        
            >>> write('buildout.cfg',
            ... '''
            ... [buildout]
            ... parts = template
            ...
            ... [template]
            ... recipe = slapos.recipe.template
            ... url = template.in
            ... output = template.out
            ...
            ... [section]
            ... option = value
            ... ''')
        
        And a simple template::
        
            >>> write('template.in', '${section:option}')
        
        We run buildout::
        
            >>> print system(join('bin', 'buildout')),
            Installing template.
        
        And the output file has been parsed by buildout itself::
        
            >>> cat('template.out')
            value
        
        Full options
        ------------
        
        There is two non required options:
        
        ``md5sum``
          Check the integrity of the input file.
        
        ``mode``
          Specify the filesystem permissions in octal notation.
        
        Check file integrity
        ~~~~~~~~~~~~~~~~~~~~
        
        Let's write a file template::
        
            >>> write('template.in', '${buildout:parts}')
        
        Compute its MD5 sum::
        
            >>> import md5
            >>> md5sum = md5.new(open('template.in', 'r').read()).hexdigest()
        
        Write the ``buildout.cfg`` using slapos.recipe.template::
        
            >>> write('buildout.cfg',
            ... '''
            ... [buildout]
            ... parts = template
            ...
            ... [template]
            ... recipe = slapos.recipe.template
            ... url = template.in
            ... output = template.out
            ... md5sum = ''' + md5sum + '''
            ... ''')
        
        And run buildout, and see the result::
        
            >>> print system(join('bin', 'buildout')),
            Uninstalling template.
            Installing template.
        
            >>> cat('template.out')
            template
        
        If the md5sum doesn't match, the buildout fail::
        
            >>> write('buildout.cfg',
            ... '''
            ... [buildout]
            ... parts = template
            ...
            ... [template]
            ... recipe = slapos.recipe.template
            ... url = template.in
            ... output = template.out
            ... md5sum = 0123456789abcdef0123456789abcdef
            ... ''')
            >>> print system(join('bin', 'buildout')),
            While:
              Installing.
              Getting section template.
              Initializing part template.
            Error: MD5 checksum mismatch for local resource at 'template.in'.
        
        
        Specify filesystem permissions
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        You can specify the mode of the written file::
        
            >>> write('template.in', '${buildout:installed}')
        
            >>> write('buildout.cfg',
            ... '''
            ... [buildout]
            ... parts = template
            ...
            ... [template]
            ... recipe = slapos.recipe.template
            ... url = template.in
            ... output = template.out
            ... mode = 0627
            ... ''')
        
            >>> print system(join('bin', 'buildout')),
            Uninstalling template.
            Installing template.
        
        And the generated file with have the right permissions::
        
            >>> import stat
            >>> import os
            >>> print oct(stat.S_IMODE(os.stat('template.out').st_mode))
            0627
        
        Section dependency
        ------------------
        
        You can use other part of buildout in the template. This way this parts
        will be installed as dependency::
        
            >>> write('template.in', '${dependency:foobar}')
            >>> write('buildout.cfg', '''
            ... [buildout]
            ... parts = template
            ...
            ... [template]
            ... recipe = slapos.recipe.template
            ... url = template.in
            ... output = template.out
            ...
            ... [dependency]
            ... foobar = dependency content
            ... recipe = zc.buildout:debug
            ... ''')
        
            >>> print system(join('bin', 'buildout')),
            Uninstalling template.
            Installing dependency.
              foobar='dependency content'
              recipe='zc.buildout:debug'
            Installing template.
        
        This way you can get options which are computed in the ``__init__`` of
        the dependent recipe.
        
        Let's create a sample recipe modifying its option dict::
        
            >>> write('setup.py',
            ... '''
            ... from setuptools import setup
            ...
            ... setup(name='samplerecipe',
            ...       entry_points = {
            ...           'zc.buildout': [
            ...                'default = main:Recipe',
            ...           ],
            ...       }
            ...      )
            ... ''')
            >>> write('main.py',
            ... '''
            ... class Recipe(object):
            ...
            ...     def __init__(self, buildout, name, options):
            ...         options['data'] = 'foobar'
            ...
            ...     def install(self):
            ...         return []
            ... ''')
        
        Let's just use ``buildout.cfg`` using this egg::
        
            >>> write('template.in', '${sample:data}')
            >>> write('buildout.cfg',
            ... '''
            ... [buildout]
            ... develop = .
            ... parts = template
            ...
            ... [template]
            ... recipe = slapos.recipe.template
            ... url = template.in
            ... output = template.out
            ...
            ... [sample]
            ... recipe = samplerecipe
            ... ''')
            >>> print system(join('bin', 'buildout')),
            Develop: ...
            Uninstalling template.
            Uninstalling dependency.
            Installing sample.
            Installing template.
            >>> cat('template.out')
            foobar
        
        2.3 (2012-03-29)
        ================
        
         * Add jinja2 entry point with jinja2 template support. [Vincent Pelletier]
        
        2.2 (2011-10-12)
        ================
        
         * Include missing files in package. [Łukasz Nowak]
        
        2.1 (2011-10-12)
        ================
        
         * Description update. [Łukasz Nowak]
        
        2.0 (2011-10-12)
        ================
        
         * Dropping collective.recipe.template dependency. [Romain Courteaud, Antoine
           Catton]
        
        1.1 (2011-05-30)
        ================
        
         * Moved out from slapos.cookbook in order to minimise depenencies [Łukasz
           Nowak]
        
        
Keywords: slapos recipe
Platform: UNKNOWN
Classifier: Framework :: Buildout :: Recipe
Classifier: Programming Language :: Python
