3.12.4. `sciexp2.common.text.Translator`

Methods

`translate`(env[, recursive])	Apply translation with given variables.
`translate_many`(envs[, recursive, ...])	Apply translation with given set of variables.

Attributes

DEFAULT_BACKEND

class Translator(template, backend=None, backend_options={})

Bases: object

Translate a template text with given variables.

Parameters:

templatestr or TemplateContents or TemplatePath: Template contents (when using TemplateContents) or path to a file containing them (when using TemplatePath). Passing a str is a shorthand for TemplateContents(template).
backend{‘pystache’, ‘jinja2’}, optional: Name of the templating backend to process the contents of template.
backend_optionsdict, optional: Options for the translation backend.

Notes

The “pystache” backend recognizes no options.

The “jinja2” backend recognizes the following options: - loader_search_path : list of str, default [os.getcwd(), “/”]

Paths to search for template and any files it includes. Uses the jinja2.FileSystemLoader() to find files.

environment_filtersdict, default {}
Custom Jinja2 filters to add to the environment. Keys are filter names, values are filter functions.
environment_extensionslist of str or Extension classes, default []
Jinja2 extensions to load into the environment (e.g., [‘jinja2.ext.do’, ‘jinja2.ext.loopcontrols’]).

DEFAULT_BACKEND = 'pystache'

translate(env, recursive=True)

Apply translation with given variables.

Parameters:

envdict: Mapping of variable names to their values.
recursivebool, optional: Whether to apply translations recursively.

Examples

You can perform simple text translations:

>>> t = Translator('Hello {{a}}')
>>> t.translate({'a': 'you'})
'Hello you'
>>> t.translate({'a': [1, 2]})
'Hello [1, 2]'

And also recursive ones:

>>> t.translate({'a': '{{b}}', 'b': 'them'})
'Hello them'

More complex cases like conditionals are also possible:

>>> t = Translator('{{#a}}is true{{/a}}{{^a}}is false{{/a}}')
>>> t.translate({'a': 1})
'is true'
>>> t.translate({'a': 0})
'is false'

Or even calls to functions (arguments are the unexpanded text on the template):

>>> Translator('{{a}}').translate({'a': lambda: 'value'})
'value'
>>> Translator('{{#a}}{{b}}{{/a}}').translate(
...     {'a': lambda arg: 2*arg, 'b': 4})
'44'
>>> Translator('{{#a}}{{b}}{{/a}}').translate(
...     {'a': lambda arg: " ".join(list(arg))})
'{ { b } }'

And expansion of nested variables with multiple values is also possible:

>>> Translator('{{#a}}A.B=={{b}} {{/a}}').translate({'a': [{'b': 1}, {'b': 2}]})
'A.B==1 A.B==2 '

translate_many(envs, recursive=True, ignore_variable_error=False, with_envs=False)

Apply translation with given set of variables.

Parameters:

envssequence of dict: Sequence of variable names to value mappings to apply the translation for.
recursivebool, optional: Whether to apply translations recursively.
ignore_variable_errorbool, optional: Ignore translations for variable maps that have missing variables.
with_envsbool, optional: Get the set of maps that led to each translation.

Returns:

list of str: Translations when with_envs is False.
list of (str, [env]): Translations with their corresponding variable maps when with_envs is True.

Notes

The result is guaranteed to maintain the order of the elements of envs.

Examples

You can very easily translate a sequence of variable maps:

>>> t = Translator('Hello {{a}}')
>>> t.translate_many([{'a': 'you'}, {'a': 'them'}])
['Hello you', 'Hello them']

Multiple maps can also translate into the same text:

>>> t.translate_many([{'a': 'you'}, {'a': 'them', 'b': 1}, {'a': 'them', 'b': 2}])
['Hello you', 'Hello them']

But you can also get the maps that led to each translation:

>>> t = Translator('Hello {{a}}')
>>> translated = t.translate_many([{'a': 'you'}, {'a': 'them', 'b': 1},
...                                {'a': 'them', 'b': 2}], with_envs=True)
>>> translated == [('Hello you', [{'a': 'you'}]),
...                ('Hello them', [{'a': 'them', 'b': 1},
...                                {'a': 'them', 'b': 2}])]
True

3.12.4. sciexp2.common.text.Translator

3.12.4. `sciexp2.common.text.Translator`