id_translation.utils.translation_helper#

Utility for single-purpose translation tasks.

Examples

Implementing a function with a translate arg using the helper class.

Initialization

Typically, you’d use something like a id_translation.Translator.from_config() callback with suitable arguments. For our purposes however, dummy translations are enough.

>>> from id_translation import Translator
>>> helper = TranslationHelper[str, str, int](
...     Translator,
...     "translate",  # for error messages
...     names="name",  # fixed translation argument
... )
>>> helper
TranslationHelper(id_translation.Translator, names='name')

The user_params_name=’translate’ argument is not printed because it’s the default.

Function definition

Arguments provided when the helper is initialized are fixed. An exception is raised if fixed arguments overlap either with user_kwargs, or with the defaults provided as keyword-arguments to apply().

In the example below, names="name" is a fixed argument and fmt="{id}:{name}" is a default argument. The translatable (= list(range(n))) and copy arguments are always required, but cannot be defined as fixed arguments. The reasons for this are mostly related to the use of typing.overload().

>>> def example(
...     n: int,
...     *,
...     translate: UserParams[str, str, int] = True,
... ) -> list[str]:
...     items: list[str] = helper.apply(
...         list(range(n)),
...         copy=True,  # required
...         user_params=translate,  # forwarded
...         fmt="{id}:{name}",  # default - user params can override
...     )
...     return items

Let’s take our new function for a spin.

Basic usage

When user_params = translate = True, default settings are used.

>>> example(1)
['0:name-of-0']

Translation may be disabled by passing False, making the helper return immediately.

>>> example(2, translate=False)
[0, 1]

Note the output is of type list[int], rather than expected list[str], in this case.

See also

The ID_TRANSLATION_DISABLED environment variable.

Aside from the obvious true|false behaviour, the TranslationHelper() may also act on the input type. The helper can be configured what input that the user may pass; see the fixed_params argument of the class. Use TranslationHelper.convert_user_params() to validate the configuration.

Argument forwarding

Dicts are interpreted as keyword-arguments for Translator.translate().

>>> example(22, translate={"fmt": "{name} (binary={id:0b})"})[-1]
'name-of-21 (binary=10101)'

Plain strings are interpreted as a temporary translation Format.

>>> example(22, translate="{name} (binary={id:0b})")[-1]
'name-of-21 (binary=10101)'

This is equivalent to passing translate={"fmt": "{name} (binary={id:0b})"}, as we did above.

Documenting user arguments

Initialized helpers provide methods creating user_params and type error docstrings, which may be used as part of the docstring of functions that use translation helpers.

>>> example.__doc__.format(  
...     translate=helper.make_user_params_docstring(),
...     type_error=helper.make_type_error_docstring(),
... )
>>> help(example)

See the example() function below for output.

Functions

example(n, *[, translate])

Create and translate the first n integers.

Classes

TranslationHelper(translator_or_factory[, ...])

Helper class for single-purpose translation tasks.

class TranslationHelper(translator_or_factory, user_params_name='translate', **fixed_params)[source]#

Bases: Generic[NameType, SourceType, IdType]

Helper class for single-purpose translation tasks.

Typing rules

Compared to Translator.translate(), typing is limited. Rules for TranslationHelper.apply():

When user_params=False, output= input.

When user_params != False, output= Any (new variable) or same (existing variable).

When copy=False, output= None.

Note that user_params=False always takes precedence, as the translation process is aborted without any Translator involvement.

Parameters:

translator_or_factory – A callable () -> Translator or an initialized Translator.
user_params_name – Used for reporting errors.
**fixed_params – Fixed parameters for Translator.translate(). Attempting to override these in TranslationHelper.apply() will raise an error.