Note

This is the generated documentation for the rsundqvist/id-translation-project demo project.

ID Translation#

Translation of IDs found in Big Corporation Inc. databases.

Example#

Using translate() with a temporary translation Format. Input file: transactions.csv.

def demo_translate():
    import pandas as pd
    from big_corporation_inc.id_translation import translate

    df = pd.read_csv("transactions.csv")
    result = translate(df, fmt="{id}:[{title}][{name}]")
    print(result)

Output: `translated-transactions.csv`.#
customer_id	film_id	category_id	staff_id	rental_date
313:DONALD	797:SILENCE KANE	12:Music	1:Mike	2005-08-22 20:55:56
107:FLORENCE	767:SCALAWAG DUCK	12:Music	1:Mike	2005-08-21 16:22:59
54:TERESA	7:AIRPLANE SIERRA	5:Comedy	2:Jon	2005-08-21 04:34:11

Modules#

Available modules are listed below. See Reexported functions for an overview of the most important functions of the package.

`big_corporation_inc.id_translation.singleton`	Convenience functions using the `Translator` singleton.
`big_corporation_inc.id_translation.config`	Configuration constants.
`big_corporation_inc.id_translation.customization`	Custom implementations may be used to change behavior in ways that TOML configuration alone does not permit.

Reexported functions#

Translation of IDs found in Big Corporation Inc. databases.

The most important functions are reexported here (big_corporation_inc.id_translation). See the various submodules (navigation bar at the top) for complete documentation.

get_singleton(*, recreate=False)#

Get the Translator singleton instance.

The exact type returned depends on TRANSLATOR_TYPE. By default, this is the regular id_translation.Translator type provided by id_translation.

Parameters:: recreate – If True, force recreating the current singleton instance.
Returns:: A id_translation.Translator.

translate(self, translatable, names=None, *, ignore_names=None, inplace=False, override_function=None, maximal_untranslated_fraction=1.0, reverse=False, fmt=None)#

Translate IDs to human-readable strings.

Note

Convenience method. Calls id_translation.Translator.translate() using the the current get_singleton() instance. See below for original docstring.

Simplified process:

The map method performs name-to-source mapping (see DirectionalMapping).
The fetch method extracts IDs to translate and retrieves data (see TranslationMap).
Finally, the translate method applies the translations and returns to the caller.

See the Translation primer page for a detailed process description.

See also

🔑 This is a key event method. Exit-events are emitted on the ℹ️INFO-level if the Translator is online. Enter-events are always emitted on the 🪲DEBUG-level. See Key Event Records for details.

Parameters:

translatable – A data structure to translate.
names – Explicit names to translate. Derive from translatable if None. Alternatively, you may pass a dict on the form {name_in_translatable: source_to_use}.
ignore_names – Names not to translate, or a predicate (NameType) -> bool.
inplace – If True, translate in-place and return None.
override_function – A callable (name, sources, ids) -> Source | None. See Mapper.apply() for details.
maximal_untranslated_fraction – The maximum fraction of IDs for which translation may fail. 1=disabled.
reverse – If True, perform translations back to IDs. Offline mode only.
fmt – A format string such as ‘{id}:{name}’ use. Default is Translator.fmt.

Returns:

A translated copy of translatable if inplace=False, otherwise None.

Examples

Manual name-to-source mapping with a temporary name-only Format.

>>> n2s = {"lions": "animals", "big_cats": "animals"}
>>> translator.translate({"lions": 2, "big_cats": 2}, names=n2s, fmt="{name}")
{'lions': 'Simba', 'big_cats': 'Simba'}

Name mappings must be complete; any name not present in the keys will be ignored (left as-is).

Raises:

UntranslatableTypeError – If type(translatable) cannot be translated.
MissingNamesError – If names are not given and cannot be derived from translatable.
MappingError – If any required (explicitly given) names fail to map to a source.
MappingError – If name-to-source mapping is ambiguous.
ValueError – If maximal_untranslated_fraction is not a valid fraction.
TooManyFailedTranslationsError – If translation fails for more than maximal_untranslated_fraction of IDs.
ConnectionStatusError – If reverse=True while the Translator is online.
UserMappingError – If override_function returns a source which is not known, and self.mapper.unknown_user_override_action != 'ignore'.

create_translator()#: Create a new preconfigured Translator instance.

load_cached_translator(max_age='12h')#: Load or (re)create a cached Translator instance.