gc3libs.template

Support and expansion of programmatic templates.

The module gc3libs.template allows creation of textual templates with a simple object-oriented programming interface: given a string with a list of substitutions (using the syntax of Python’s standard substitute module), a set of replacements can be specified, and the gc3libs.template.expansions function will generate all possible texts coming from the same template. Templates can be nested, and expansions generated recursviely.

class gc3libs.template.Template(template, validator=<function <lambda> at 0x4b11230>, **extra_args)

A template object is a pair (obj, keywords). Methods are provided to substitute the keyword values into obj, and to iterate over expansions of the given keywords (optionally filtering the allowed combination of keyword values).

Second optional argument validator must be a function that accepts a set of keyword arguments, and returns True if the keyword combination is valid (can be expanded/substituted back into the template) or False if it should be discarded. The default validator passes any combination of keywords/values.

expansions(**keywords)

Iterate over all valid expansions of the templated object and the template keywords. Returned items are Template instances constucted with the expanded template object and a valid combination of keyword values.

substitute(**extra_args)

Return result of interpolating the value of keywords into the template. Keyword arguments extra_args can be used to override keyword values passed to the constructor.

If the templated object provides a substitute method, then return the result of invoking it with the template keywords as keyword arguments. Otherwise, return the result of applying Python standard library’s string.Template.safe_substitute() on the string representation of the templated object.

Raise ValueError if the set of keywords/values is not valid according to the validator specified in the constructor.

gc3libs.template.expansions(obj, **extra_args)

Iterate over all expansions of a given object, recursively expanding all templates found. How the expansions are actually computed, depends on the type of object being passed in the first argument obj:

• If obj is a list, iterate over expansions of items in obj. (In particular, this flattens out nested lists.)

  Example:

  >>> L = [0, [2, 3]]
  >>> list(expansions(L))
  [0, 2, 3]
  

• If obj is a dictionary, return dictionary formed by all combinations of a key k in obj with an expansion of the corresponding value obj[k]. Expansions are computed by recursively calling expansions(obj[k], **extra_args).

  Example:

  >>> D = {'a':1, 'b':[2,3]}
  >>> list(expansions(D))
  [{'a': 1, 'b': 2}, {'a': 1, 'b': 3}]
  

• If obj is a tuple, iterate over all tuples formed by the expansion of every item in obj. (Each item t[i] is expanded by calling expansions(t[i], **extra_args).)

  Example:

  >>> T = (1, [2, 3])
  >>> list(expansions(T))
  [(1, 2), (1, 3)]
  

• If obj is a Template class instance, then the returned values are the result of applying the template to the expansion of each of its keywords.

  Example:

  >>> T1 = Template("a=${n}", n=[0,1])
  >>> list(expansions(T1))
  [Template('a=${n}', n=0), Template('a=${n}', n=1)]
  

  Note that keywords passed to the expand invocation override the ones used in template construction:

  >>> T2 = Template("a=${n}")
  >>> list(expansions(T2, n=[1,3]))
  [Template('a=${n}', n=1), Template('a=${n}', n=3)]
  
  >>> T3 = Template("a=${n}", n=[0,1])
  >>> list(expansions(T3, n=[2,3]))
  [Template('a=${n}', n=2), Template('a=${n}', n=3)]
  

• Any other value is returned unchanged.

  Example:

  >>> V = 42
  >>> list(expansions(V))
  [42]