rics.translation package

Subpackages

Submodules

rics.translation.exceptions module

General errors for the translation suite.

exception rics.translation.exceptions.ConfigurationError[source]

Bases: ValueError

Raised in case of bad configuration.

exception rics.translation.exceptions.OfflineError[source]

Bases: ValueError

Raised for offline state errors.

Module contents

Translation of IDs with flexible formatting and name matching.

class rics.translation.Translator(fetcher: Union[Fetcher, TranslationMap, Dict[SourceType, PlaceholderTranslations], Dict[SourceType, Union[PlaceholderTranslations, DataFrame, Dict[str, Sequence[Any]]]]], fmt: Union[str, Format] = '{id}:{name}', mapper: Optional[Mapper] = None, default_fmt: Optional[Union[str, Format]] = None, default_translations: Optional[Union[DefaultTranslations, Dict[str, Union[Dict[str, Any], Dict[str, Dict[str, Any]]]]]] = None)[source]

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

Translate IDs to human-readable labels.

Untranslatable IDs will be None by default if neither default_fmt nor default_translations is given.

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 specification to use instead of fmt for fallback translation of unknown IDs.

  • default_translations – Shared and/or source-specific default placeholder values for unknown IDs.

See also

Related classes:

classmethod from_config(path: Union[str, bytes, PathLike, Dict[str, Any]]) → Translator[source]

Create a translator from a YAML file.

Parameters

path – Path to a YAML file, or a pre-parsed dict.

Returns

A Translator object.

Raises

ConfigurationError – If the config is invalid.

translate(translatable: DefaultTranslatable, names: Optional[Union[NameType, Iterable[NameType], Callable[[NameType], bool]]] = None, ignore_names: Optional[Union[NameType, Iterable[NameType], Callable[[NameType], bool]]] = None, inplace: bool = False) → Optional[DefaultTranslatable][source]

Translate IDs to human-readable strings.

Parameters

  • translatable – A data structure to translate.

  • names – Explicit names to translate. Will try to derive form translatable if not given. May also be a predicate which indicates (returns True for) derived names to keep.

  • ignore_names – Names not to translate. Always precedence over names, both explicit and derived. May also be a predicate which indicates (returns True for) names to ignore.

  • inplace – If True, translation is performed in-place and this function returns None.

Returns

A copy of translatable with IDs replaced by translations if inplace=False, otherwise None.

Raises

  • UntranslatableTypeError – If translatable is not translatable using any standard IOs.

  • AttributeError – If names are not given and cannot be derived from translatable.

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

map_to_sources(translatable: DefaultTranslatable, names: Optional[Union[NameType, Iterable[NameType], Callable[[NameType], bool]]] = None, ignore_names: Optional[Union[NameType, Iterable[NameType], Callable[[NameType], bool]]] = None) → Optional[DirectionalMapping][source]

Map names to translation sources.

Parameters

  • translatable – A data structure to map names for.

  • names – Explicit names to translate. Will try to derive form translatable if not given. May also be a predicate which indicates (returns True for) derived names to keep.

  • ignore_names – Names not to translate. Always precedence over names, both explicit and derived. May also be a predicate which indicates (returns True for) names to ignore.

Returns

A mapping of names to translation sources. Returns None if mapping failed but success was not required.

Raises

  • AttributeError – If names are not given and cannot be derived from translatable.

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

fetch(translatable: DefaultTranslatable, name_to_source: DirectionalMapping[NameType, SourceType], data_structure_io: Optional[Type[DataStructureIO]] = None) → TranslationMap[source]

Fetch translations.

Parameters

  • translatable – A data structure to translate.

  • name_to_source – Mappings of names in translatable to translation sources known the fetcher.

  • data_structure_io – Static Data Structure IO class used to extract IDs from translatable. None=derive.

Returns

A TranslationMap.

Raises

OfflineError – If disconnected from the fetcher, ie not online.

property online: bool

Return connectivity status. If False, no new translations may be fetched.

store(translatable: Optional[DefaultTranslatable] = None, names: Optional[Union[NameType, Iterable[NameType], Callable[[NameType], bool]]] = None, ignore_names: Optional[Union[NameType, Iterable[NameType], Callable[[NameType], bool]]] = None, delete_fetcher: bool = True) → Translator[source]

Retrieve and store translations in a local cache.

Parameters

  • translatable – Data from which IDs to fetch will be extracted. None=fetch all IDs.

  • names – Explicit names to translate. Will try to derive form translatable if not given. May also be a predicate which indicates (returns True for) derived names to keep.

  • ignore_names – Names not to translate. Always precedence over names, both explicit and derived. May also be a predicate which indicates (returns True for) names to ignore.

  • delete_fetcher – If True, go offline after retrieving data. The translation will still function, but some methods may raise exceptions and new data cannot be retrieved. Deleting allows the fetcher to close files and connections. If the fetcher has a close()-method, it will be called before deletion.

Returns

Self, for chained assignment.

Raises

  • ForbiddenOperationError – If the fetcher does not permit the FETCH_ALL operation (only when translatable is None).

  • MappingError – If a translatable is given, but no names to translate could be extracted.

See also

rics.translation.fetching.Fetcher.fetch_all() rics.translation.offline.TranslationMap