translator Module

class translator.Translator

Bases: object

Abstract class to define translators from a set of strings (such as file paths) to associated information.

All subclasses implement the following methods:

• Translator.all(strings, strings_first=False)

• Translator.first(strings, strings_first=False)

Input is a list of strings. The Translator object tests each string and determines if it passes a test. If it does pass the test, then one or more “translated” strings are returned.

Translator.all() returns every translated string. Translator.first() returns the first translated string.

Parameters:

• strings – A string or list of strings to translate.

• strings_first – If True, every test is applied to the first string, then every test is applied to the second string, etc. If False, the first test is applied to every string, then the second test is applied to every string, etc. This can affect the order of the translated strings returned by all(), or the single translated string that is returned by first().

__add__(other)

Add two translators together using the + operator.

Parameters:

other – A Translator object to append.

Returns:

A new Translator combining self and other.

__iadd__(other)

Add two translators together using the += operator.

Parameters:

other – A Translator object to append.

Returns:

A new Translator combining self and other.

class translator.TranslatorBySequence(args)

Bases: Translator

Translator defined by a sequence of other translators.

TAG = 'SEQUENCE'

__init__(args)

Initialize a TranslatorBySequence.

Parameters:

args – A sequence of Translator objects to apply in order.

all(strings, strings_first=False)

Apply a translator to one or more strings, returning every unique result in priority order.

Parameters:

• strings – A string or list of strings to translate.

• strings_first – If True, try each string in order with all translators. If False, try each translator in order with all strings.

Returns:

A list of all unique translated results in priority order.

first(strings, strings_first=False)

Apply a translator to one or more strings, returning the first result.

Parameters:

• strings – A string or list of strings to translate.

• strings_first – If True, try each string in order with all translators. If False, try each translator in order with all strings.

Returns:

The first translated result, or None if no translation is found.

keys()

Return all of the keys.

Returns:

A list of keys from all translators in the sequence.

values()

Return all of the values in the same order as keys().

Returns:

A list of values from all translators in the sequence.

prepend(translator)

Return a new translator with the given translator in front of this one.

append(translator)

Return a new translator with the given translator after this one.

class translator.TranslatorByDict(arg, path_translator=None)

Bases: Translator

Translator defined by a standard dictionary. Fast but inflexible.

If the value is string containing “
”, that substring is replaced by the key.

Parameters:

• arg – A dictionary mapping keys to values. Values can be strings (with optional “
  ” replacement), lists, or tuples.

• path_translator – Optional Translator object that translates input strings into the keys used in the dictionary.

TAG = 'DICT'

__init__(arg, path_translator=None)

Initialize a TranslatorByDict.

Parameters:

• arg – A dictionary mapping keys to values.

• path_translator – Optional Translator to translate input strings to keys.

all(strings, strings_first=False)

Apply a translator to one or more strings, returning every unique result in priority order.

Parameters:

• strings – A string or list of strings to translate.

• strings_first – Ignored for this subclass.

Returns:

A list of all unique translated results in priority order.

first(strings, strings_first=False)

Apply a translator to one or more strings, returning the first result.

Parameters:

• strings – A string or list of strings to translate.

• strings_first – Ignored for this subclass.

Returns:

The first translated result, or None if no translation is found.

static expand(results, key)

Expand result values by replacing “
” with the key.

Parameters:

• results – A value or list of values from the dictionary.

• key – The dictionary key to use for “
  ” replacement.

Returns:

A list of expanded results.

keys()

Return all of the keys (in a vaguely sensible order).

Returns:

A sorted list of dictionary keys.

values()

Return all of the values in the same order as keys().

prepend(translator)

Return a new translator with the given translator in front of this one.

append(translator)

Add a new translator after this one.

class translator.TranslatorByRegex(tuples)

Bases: Translator

Translator defined by a list of tuples defining regular expressions.

Each element in the list must be a tuple:

(regular expression string, flags, value)

or a tuple:

(compiled regex, value)

Upon evaluation, if the regular expression matches a given string, using the given set of regular expression flags, then the replacement patterns are applied to a value and the modified value is returned.

Parameters:

tuples –

A list of tuples. Each tuple can be:

• (regex_string, flags, replacement_value) for 3-tuple

• (regex_string, replacement_value) for 2-tuple

• (compiled_regex, replacement_value) for 2-tuple with compiled regex

The replacement value can be a string, a list of strings, or a tuple of strings. Strings can contain “#UPPER#”, “#LOWER#”, “#MIXED#” directives for case control, and dictionary expressions like “{‘a’: ‘b’}[‘a’]” for inline evaluation.

TAG = 'REGEX'

__init__(tuples)

Initialize a TranslatorByRegex.

Parameters:

tuples – A list of tuples defining regex patterns and replacements.

all(strings, strings_first=False)

Apply a translator to one or more strings, returning every unique value in priority order.

Parameters:

• strings – A string or list of strings to translate.

• strings_first – If True, try each string in order with all regex patterns. If False, try each regex pattern in order with all strings.

Returns:

A list of all unique translated results in priority order.

first(strings, strings_first=False)

Apply a translator to one or more strings, returning the first result. Return None if no translation is found.

static expand(regex, string, replacements)

Handle substitutions in the cases where the replacement is a list, a string, or a tuple containing strings.

Parameters:

• regex – A compiled regular expression pattern.

• string – The string to match against the regex.

• replacements – A string, list of strings, tuple of strings, or other value to use as replacement.

Returns:

A list of expanded replacement results, or empty list if no match.

keys()

Return all of the keys.

values()

Return all of the values in the same order as keys().

prepend(translator)

Return a new translator with the given translator in front of this one.

append(translator)

Add a new translator after this one.

class translator.NullTranslator

Bases: Translator

Translator that returns nothing.

TAG = 'NULL'

__init__()

all(strings, strings_first=False)

Apply a translator to one or more strings, returning every unique result.

first(strings, strings_first=False)

Apply a translator to one or more strings, returning the first result. Return None if no translation is found.

keys()

Return all of the keys.

values()

Return all of the values in the same order as keys().

prepend(translator)

Return a new translator with the given translator in front of this one.

append(translator)

Return a new translator with the given translator after this one.

class translator.SelfTranslator

Bases: Translator

Translator that returns itself.

TAG = 'SELF'

__init__()

all(strings, strings_first=False)

Apply a translator to one or more strings, returning every unique result.

first(strings, strings_first=False)

Apply a translator to one or more strings, returning the first result. Return None if no translation is found.

keys()

Return all of the keys.

values()

Return all of the values in the same order as keys().

prepend(translator)

Return a new translator with the given translator in front of this one.

append(translator)

Return a new translator with the given translator after this one.