Submodule template

This file originates from the file beets/util/functemplate.py of the beets project.

This module implements a string formatter based on the standard PEP 292 string.Template class extended with function calls. Variables, as with string.Template, are indicated with $ and functions are delimited with %.

This module assumes that everything is Unicode: the template and the substitution values. Bytestrings are not supported. Also, the templates always behave like the safe_substitute method in the standard library: unknown symbols are left intact.

This is sort of like a tiny, horrible degeneration of a real templating engine like Jinja2 or Mustache.

class tmep.template.Environment(values: Dict[str, Any], functions: Dict[str, Callable[[...], str | int]])

Bases: object

Contains the values and functions to be substituted into a template.

values: Dict[str, Any]

functions: Dict[str, Callable[[...], str | int]]

tmep.template.ex_rvalue(name: str) → Name

A variable store expression.

Parameters:

name – For example 'str', 'map', '__func_alpha'

tmep.template.ex_literal(val: int | float | bool | str | Call | List | Name | None) → Constant

An int, float, long, bool, string, or None literal with the given value.

Parameters:

val – For example 'abc123'

tmep.template.ex_call(func: str | Attribute | Name, args: list[Call | List | Name | Any]) → Call

A function-call expression with only positional parameters. The function may be an expression or the name of a function. Each argument may be an expression or a value to be used as a literal.

tmep.template.compile_func(arg_names: list[str], statements: list[Return], name: str = '_the_func', debug: bool = False) → Callable[[...], Any]

Compile a list of statements as the body of a function and return the resulting Python function. If debug, then print out the bytecode of the compiled function.

class tmep.template.Symbol(ident: str, original: str)

Bases: object

A variable-substitution symbol in a template.

ident: str

original: str

evaluate(env: Environment)

Evaluate the symbol in the environment, returning a Unicode string.

translate() → tuple[list[Name], set[str], set[str]]

Compile the variable lookup.

class tmep.template.Call(ident: str, args: list[Expression], original: str)

Bases: object

A function call in a template.

ident: str

args: list[Expression]

original: str

evaluate(env: Environment) → str

Evaluate the function call in the environment, returning a Unicode string.

translate()

Compile the function call.

class tmep.template.Expression(parts: list[str | Symbol | Call])

Bases: object

Top-level template construct: contains a list of text blobs, Symbols, and Calls.

parts: list[str | Symbol | Call]

evaluate(env: Environment) → str

Evaluate the entire expression in the environment, returning a Unicode string.

translate()

Compile the expression to a list of Python AST expressions, a set of variable names used, and a set of function names.

exception tmep.template.ParseError

Bases: Exception

class tmep.template.Parser(string: str, in_argument: bool = False)

Bases: object

Parses a template expression string. Instantiate the class with the template source and call parse_expression. The pos field will indicate the character after the expression finished and parts will contain a list of Unicode strings, Symbols, and Calls reflecting the concatenated portions of the expression.

This is a terrible, ad-hoc parser implementation based on a left-to-right scan with no lexing step to speak of; it’s probably both inefficient and incorrect. Maybe this should eventually be replaced with a real, accepted parsing technique (PEG, parser generator, etc.).

string: str

in_argument: bool

pos: int

parts: list[str | Symbol | Call]

special_chars

special_char_re

escapable_chars

terminator_chars

parse_expression() → None

Parse a template expression starting at pos. Resulting components (Unicode strings, Symbols, and Calls) are added to the parts field, a list. The pos field is updated to be the next character after the expression.

parse_symbol() → None

Parse a variable reference (like $foo or ${foo}) starting at pos. Possibly appends a Symbol object (or, failing that, text) to the parts field and updates pos. The character at pos must, as a precondition, be $.

parse_call()

Parse a function call (like %foo{bar,baz}) starting at pos. Possibly appends a Call object to parts and update pos. The character at pos must be %.

parse_argument_list() → list[Expression]

Parse a list of arguments starting at pos, returning a list of Expression objects. Does not modify parts. Should leave pos pointing to a } character or the end of the string.

tmep.template.template(fmt: str) → Template

class tmep.template.Template(template: str)

Bases: object

A string template, including text, Symbols, and Calls.

expr: Expression

original: str

interpret(values: Dict[str, Any] = {}, functions: Dict[str, Callable[[...], str | int]] = {}) → str

Like substitute, but forces the interpreter (rather than the compiled version) to be used. The interpreter includes exception-handling code for missing variables and buggy template functions but is much slower.

substitute(values: Dict[str, Any] = {}, functions: Dict[str, Callable[[...], str | int]] = {}) → str

Evaluate the template given the values and functions.

translate() → Callable[[...], str]

Compile the template to a Python function.