text

Tools for loading and completing text files and other resources.

Parameters that are known at program start are used to initialize the classes so that, at runtime, the information only available then can flow through a preconfigured pipe of callable objects to yield the desired result.

class TextResourceLoader(package, path='resources', not_found=NotFound.RAISE, encoding='utf-8')

Bases: ArgRepr

Load text files from a resource directory within a python package.

Parameters:

• package (str) – Name of the python package under which the text file is located.

• path (str, optional) – Directory under which the text file is located within the python package or full path to the text file. If not fully specified here, the path must be completed on calling the instance. Defaults to “resources”.

• not_found (str, optional) – What to do if the specified file is not found. One of “ignore”, “warn”, or “raise”. Defaults to “raise”. Use the NotFound enum to avoid typos!

• encoding (str, optional) – Encoding of the text file. Defaults to “utf-8”.

See also

NotFound

__call__(path='')

Load text file from a directory within the specified python package.

Parameters:

path (str, optional) – Path (including file name) relative to the path specified at instantiation. Defaults to an empty string, which results in an unchanged path on concatenation.

Returns:

Decoded contents of the specified text file.

Return type:

str

class TemplateRenderer(template, mapping=None, **kwargs)

Bases: object

Substitute bash-style “${key}” placeholders in a template string.

This is a light wrapper around the standard library’s string.Template, calling its method safe_substitute upon instantiation and its method substitute when calling the (callable) instance. At first, not all keys need to be provided, but when the object is called and the substitution is finalized, all keys must have been provided.

Parameters:

• template (str) – String with bash-style “${key}” placeholders to substitute.

• mapping (dict, optional) – Dictionary-like mapping with the placeholders to substitute as keys and the values to substitute as values. Defaults to None.

• **kwargs – Keyword arguments replace respective placeholders with whatever value is passed, overwriting values in mapping.

Note

Instances evaluate to True if all keys were provided at instantiation and to False if there are still keys missing.

__call__(mapping=None, **kwargs)

Substitute bash-style “${key}” placeholders in the wrapped template.

Parameters:

• mapping (dict, optional) – Dictionary-like mapping with the placeholders to substitute as keys and the values to substitute as values. Defaults to None.

• **kwargs – Keyword arguments replace respective placeholders with whatever value is passed, overwriting values in mapping.

Returns:

String with all placeholders substituted.

Return type:

str

Raises:

• KeyError – When a value for one or more placeholders is still missing.

• ValueError – When a key is not a valid python identifier.

property identifiers

List of identifiers that still need to be interpolated.

class FormFiller(mapping=None, **kwargs)

Bases: object

Substitute bash-style “${key}” placeholders in a template string.

This is a light wrapper around the standard library’s string.Template, first caching a dictionary and optional keywords on instantiation, and then calling its method substitute with these cached values when calling the (callable) object with the template string.

Parameters:

• mapping (dict, optional) – Dictionary-like mapping with the placeholders to substitute as keys and the values to substitute as values. Defaults to None.

• **kwargs – Keyword arguments replace respective placeholders with whatever value is passed, overwriting respective values in mapping.

Note

Instances evaluate to False if no keys were provided at instantiation and to True if there are any keys cached.

__call__(template, mapping=None, **kwargs)

Substitute bash-style “${key}” placeholders in a string template.

Parameters:

• template (str) – String with bash-style “${key}” placeholders to substitute.

• mapping (dict, optional) – Dictionary-like mapping with the placeholders to substitute as keys and the values to substitute as values. Defaults to None.

• **kwargs – Keyword arguments replace respective placeholders with whatever value is passed, overwriting the cached mapping.

Returns:

String with all placeholders substituted.

Return type:

str

Raises:

• KeyError – When a value for one or more placeholders is still missing.

• ValueError – When a key is not a valid python identifier.