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.

Notes

Creating the instance is not thread safe, and neither is the first initialize_sources() call it performs – that call resolves the sources and registers fetcher-provided transformers, mutating the Translator. Since translate() triggers it implicitly, the first concurrent translate() call through the singleton is the hazard. Warm the singleton once during startup:

get_singleton().initialize_sources()

before handing it to worker threads. See https://id-translation.readthedocs.io/en/stable/documentation/translation-concurrency.html#thread-safety.

translate(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 current get_singleton() instance. See below for original docstring.

Simplified process:

The extract_names() method derives names of the translatable to translate (if needed).
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 (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. Missing IDs (e.g. NaN) in pandas types are pass-throughs and never count; a None in a builtin collection is an ordinary – unknown – ID, and does.
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'.

ID Translation#

Example#

Modules#

Reexported functions#

This Page