id_translation.Translator#

class Translator(fetcher=None, fmt='{id}:{name}', mapper=None, default_fmt='<Failed: id={id!r}>', default_fmt_placeholders=None, enable_uuid_heuristics=False, transformers=None)[source]#

Bases: Generic[NameType, SourceType, IdType], HasSources[SourceType]

End-user interface for all translation tasks.

See Translator.translate() for runtime configuration options. Any argument chosen when the Translator is created can be overridden with Translator.copy(). Use go_offline() to store translations in memory.

Parameters:

fetcher – A Fetcher or ready-to-use translations.
fmt – String Format specification for translations.
mapper – A Mapper instance for binding names to sources.
default_fmt – Alternative Format to use fallback translation of unknown IDs.
default_fmt_placeholders – Shared and/or source-specific default placeholder values for unknown IDs. See InheritedKeysDict.make() for details.
enable_uuid_heuristics – Improves matching when UUID-like IDs are in use.
transformers – A dict {source: transformer} of initialized Transformer instances.

Examples

Basic usage. For a more complete use case, see the Sakila DVD Rental Database example.

Assume that we have data for people and animals as in the tables below:

people:            animals:
     id | name        id | name   | is_nice
  ------+---------   ----+--------+---------
   1991 | Richard      0 | Tarzan | false
   1999 | Sofia        1 | Morris | true
   1904 | Fred         2 | Simba  | true

In most real cases we’d fetch this table from somewhere. In this case, however, there’s so little data that we can simply enumerate the components needed for translation ourselves.

>>> from id_translation import Translator
>>> translation_data = {
...     "animals": {
...         "id": [0, 1, 2],
...         "name": ["Tarzan", "Morris", "Simba"],
...         "is_nice": [False, True, True],
...     },
...     "people": {1999: "Sofia", 1991: "Richard", 1904: "Fred"},
... }
>>> fmt = "{id}:{name}[, nice={is_nice}]"
>>> translator = Translator(translation_data, fmt=fmt)

Since people only has columns id and name, we can use the simplified {id: name} data format. We’re using the full format for animals since we have an additional is_nice column in this table. We didn’t define a Mapper, so the names must match exactly.

>>> import pandas as pd
>>> df = pd.DataFrame({"animals": [0, 2], "people": [1991, 1999]})
>>> translator.translate(df)  # Returns a copy
                animals        people
0  0:Tarzan, nice=False  1991:Richard
1    2:Simba, nice=True    1999:Sofia

Check out the Translation primer to learn how this is done “under the hood”.

Methods

`copy`(**overrides)	Make a copy of this `Translator`.
`fetch`([translatable, names, ignore_names, ...])	Fetch translations.
`from_config`(path[, extra_fetchers])	Create a `Translator` from TOML inputs.
`go_offline`([translatable, names, ...])	Retrieve and store translations in memory.
`load_persistent_instance`(cache_dir, config_path)	Load or create a persistent `fetch_all`-instance.
`map`(translatable[, names, ignore_names, ...])	Map names to translation sources.
`map_scores`(translatable[, names, ...])	Returns raw match scores for name-to-source mapping.
`restore`(path)	Restore a serialized `Translator`.
`translate`(translatable[, names, ...])	Translate IDs to human-readable strings.
`translated_names`([with_source])	Return the names that were translated by the most recent `translate()`-call.

Attributes

`cache`	Return a `TranslationMap` of cached translations.
`config_metadata`	Return `from_config()` initialization `metadata`.
`default_fmt`	Alternative translation `Format`, used for unknown IDs.
`enable_uuid_heuristics`	Improves matching when `UUID`-like IDs are in use.
`fetcher`	Return the `Fetcher` instance used to retrieve translations.
`fmt`	Main translation `Format` for this `Translator` instance.
`mapper`	Return the `Mapper` instance used for name-to-source binding.
`online`	Return connectivity status.
`placeholders`	A dict `source: [placeholders..]}`.
`sources`	A list of known sources names.
`transformers`	Get a dict `{source: transformer}` of `Transformer` instances used by this `Translator`.