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.

See also

See docs for the backing API for additional help: https://id-translation.readthedocs.io/

This documentation was generated from the rsundqvist/id-translation-project template on Monday, 09 Mar 2026, a cookiecutter template template for the rsundqvist/id-translation package suite.

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, copy=True, override_function=None, max_fails=1.0, reverse=False, fmt=None, io_kwargs=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:

  1. The extract_names() method derives names of the translatable to translate (if needed).

  2. The map() method performs name-to-source mapping (see DirectionalMapping).

  3. The fetch() method extracts IDs to translate and retrieves data (see TranslationMap).

  4. Finally, the translate() method (i.e. this one) 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. 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.

  • copy – If False, translate in-place and return None.

  • override_function – A callable (name, sources, ids) -> Source | None. See Mapper.apply() for details.

  • max_fails – 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.

  • io_kwargs – Keyword arguments for the IO class (e.g. PandasIO).

Returns:

A translated copy of translatable if copy=True, 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.

  • UnmappedExplicitNamesError – If any required (explicitly given) names fail to map to a source.

  • MappingError – If name-to-source mapping is ambiguous.

  • ValueError – If max_fails is not a valid fraction.

  • TooManyFailedTranslationsError – If translation fails for more than max_fails of IDs.

  • ConnectionStatusError – If reverse=True while the Translator is online.

  • UserMappingError – If override_function returns a source which is not known, and mapper.on_unknown_user_override != 'ignore'.

See also

The ID_TRANSLATION_DISABLED variable.

create_translator()#

Create a new preconfigured Translator instance.

load_cached_translator(max_age='12h')#

Load or (re)create a cached Translator instance.