STRUCTURES.txt

.. contents::

Structures
==========

Structures are a new feature added to the templer system that goes a bit
beyond what normal Paster templates offer. The Structures system was added to
templer in order to solve a particular problem. What follows is a description
of the problem as well as a brief outline of the Structures solution.

The Problem
-----------

There are three design choices that Paster makes about its templates that can
cause problems in a complex package generating system like templer:

# In Paster, each template is registered in setup.py as an entry point in the
  'paste.paster_create_template' category. This means that each template you
  create in a package like templer is always found as a 'runnable' template by
  paste when it looks to see what template commands are available from 
  installed packages.

# In Paster, each paster template can have one and only one 'template'
  directory which holds the source files to be generated when the paster 
  template is run.

# In Paster, when a template is run, *all* the source files in its template
  directory are generated. If you wish to end up with only some of them, you
  must act *after* running the template to delete unwanted files. You cannot
  prevent them from being written before you run them.

In a package generating system like templer, these choices become problematic
because there is a high degree of redundancy across the available package
templates. The purpose of templer is to help encourage best-practice package
layout, and so common elements like top-level package documentation are shared
across all the available templates. We'd like to be able to ensure that any
package generated by the templer system has the following top-level
structure::

  namespace.package
   |
   - CHANGES.txt
   - CONTRIBUTORS.txt
   - README.txt
   - setup.py
   - docs
      |
      - LICENSE.txt
      - LICENSE.GPL
   - src
      |
      - namespace
         |
         - package
            |
            - <package code ...>

Given the paster template system, we have two choices to help us achieve this
goal.

* create a basic template that holds only the CHANGES.txt, CONTRIBUTORS.txt
  and README.txt files and ensure that all our other templates inherit from
  that one.

* include these three source files in *each* of our package templates
  separately.

In the first case, we end up with a runnable template registered in paster
that we really don't ever want to be able to run separately. In the second
case we end up with a maintenance nightmare as every time we update the format
for one of our source files, or change something about how that base structure
is set up we have to change it for all the templates we have.

Let's look at another example to further illustrate this point. In the templar
system, we'd like to be able to offer a user his or her choice of licenses for
their package. There are many license options out there, and we do not wish to
dictate which one our users choose for their package.

The ZopeSkel package, from which templer is descended, actually offers the
choice of license as an option for most of its packages. However, due to the
third limitation in paster listed above we cannot actually give them the
license they ask for. No matter what choice they make, the license they end up
with is the GPL.

To solve this problem in paster, we'd need to add all the possible licenses to
our template package, render them all using the appropriate values from the
interactive portion of the template run, and then after rendering them all,
delete the ones we do not want. This is obviously inefficient.

The Structures Solution
-----------------------

In templer, we've chosen to solve this problem by creating 'structures', a
close parallel to paster templates, but with some key differences.

* structures cannot be 'run' like templates, they do not define questions to
  be answered interactively by the user. Instead, templates which rely on a
  given structure are responsible for gathering the answers to any questions
  on which the structure will rely.

* structures are registered in a separate category of entry points. This way,
  they do not end up being listed alongside our actual templates as
  individually usable.

* structures provide an additional var type, the structure_select, which
  allows a user to choose from a number of options at template runtime. The
  selected structure is then injected into the template's required_structures
  list before the rendering phase of the template run.

These changes allow us to solve the problems above in a clean, efficient
manner.