rics.translation.offline package

Submodules

rics.translation.offline.types module

Types used for offline translation.

class rics.translation.offline.types.PlaceholderTranslations(source: SourceType, placeholders: Tuple[str, ...], records: Sequence[Sequence[Any]], id_pos: int = - 1)[source]

Bases: Generic[SourceType]

Matrix of ID translation components returned by fetchers.

source

Source for the placeholders.

Type: rics.translation.offline.types.SourceType

placeholders

Names of placeholders in the order in which they appear in records.

Type: Tuple[str, …]

records

Response matrix of shape N x M where N is the number of IDs returned and M is the length of placeholders.

Type: Sequence[Sequence[Any]]

id_pos

Position if the “id” placeholder in placeholders.

Type: int

MakeTypes: alias of Union[PlaceholderTranslations, DataFrame, Dict[str, Sequence[Any]]]

source: SourceType

placeholders: Tuple[str, ...]

records: Sequence[Sequence[Any]]

id_pos: int = -1

classmethod make(source: SourceType, data: Union[PlaceholderTranslations, DataFrame, Dict[str, Sequence[Any]]]) → PlaceholderTranslations[source]

Try to make in instance from arbitrary input data.

Parameters

source – Source label for the translations.
data – Some data to convert to a PlaceholderTranslations instance.

Returns

A new PlaceholderTranslations instance.

Raises

TypeError – If data cannot be converted.

to_dict(max_rows: int = 0) → Dict[str, Sequence[Any]][source]: Create a dict representation of the translations.

static to_dicts(source_placeholder_translations: Dict[SourceType, PlaceholderTranslations], max_rows: int = 0) → Dict[SourceType, Dict[str, Sequence[Any]]][source]: Create a nested dict representation of the translations.

classmethod from_dataframe(source: SourceType, data: DataFrame) → PlaceholderTranslations[source]: Create instance from a pandas DataFrame.

classmethod from_dict(source: SourceType, data: Dict[str, Sequence[Any]]) → PlaceholderTranslations[source]: Create instance from a dict.

Module contents

Translation using local data given at initialization.

class rics.translation.offline.Format(fmt: str)[source]

Bases: object

Format specification for translations strings.

Translator formats are similar to regular f-strings, with two important exceptions: 1. Positional arguments may not be used; '{}' is not accepted, correct form is '{key-name}'. 2. Substrings surrounded by [] denote an optional element.

Parameters: fmt – A translation fstring.

PLACEHOLDER_PATTERN: Pattern = re.compile('(?P<optional>\\[(?P<left>.*?){(?P<optional_name>\\w+)}(?P<right>.*?)\\])|{(?P<required>\\w+)}'): Pattern which denotes placeholder elements in format strings.

fstring(placeholders: Optional[Iterable[str]] = None, positional: bool = False) → str[source]

Create a format string for the given placeholders.

Parameters

placeholders – Keys to keep. Passing None is equivalent to passing required_placeholders.
positional – If True, remove names to return a positional fstring.

Returns

An fstring with optional elements removed unless included in placeholders.

Raises

KeyError – If required placeholders are missing.

property positional: bool: If True, names are stripped from fstring placeholders.

property source: SourceType: Return translation source.

property placeholders: List[str]: Return placeholder names in sorted order.

class rics.translation.offline.DefaultFormatApplier(placeholder_translations: ~rics.translation.offline.types.PlaceholderTranslations, default: ~typing.Union[~typing.Literal[<_NoDefault.NO_DEFAULT: '<no-default>'>], ~typing.Dict[str, ~typing.Any]] = _NoDefault.NO_DEFAULT, required_placeholders: ~typing.Optional[~typing.Collection[str]] = None)[source]

Bases: FormatApplier

Default format applier implementation.

class rics.translation.offline.DefaultTranslations(shared: Optional[Dict[str, Any]] = None, source_specific: Optional[Dict[SourceType, Dict[str, Any]]] = None)[source]

Bases: Mapping[SourceType, Dict[str, Any]]

Default placeholder translations for unknown IDs.

Parameters

shared – Translations shared by all sources.
source_specific – Source-specific translations, backed by shared mappings.

classmethod from_dict(mapping: Dict[str, Union[Dict[str, Any], Dict[str, Dict[str, Any]]]]) → DefaultTranslations[source]

Create instance from a mapping.

The given argument must follow the format specified below:

{
    "shared": {placeholder: value},
    "source-specific": {
        source0: {placeholder: value},
        source1: {placeholder: value},
        ...
        sourceN: {placeholder: value},
    }
}

No other top-level keys are accepted, but neither shared nor source-specific are required.

Parameters: mapping – A remapping dict.
Returns: A new instance.
Raises: ValueError – If there are any keys other than ‘shared’ and ‘source-specific’ present in mapping.

class rics.translation.offline.PlaceholderOverrides(shared: Optional[Dict[str, str]] = None, source_specific: Optional[Dict[SourceType, Dict[str, str]]] = None)[source]

Bases: Generic[SourceType]

Remapping from non-compliant to compliant placeholder names.

Format is <what-it-is> => <what-it-should-be>.

Parameters

shared – Mappings shared by all sources.
source_specific – Source-specific mappings, backed by shared mappings.

info_string(source: SourceType) → str[source]: Get an override info string for source.

reverse() → PlaceholderOverrides[source]: Return a reversed copy of self, swapping from_placeholder <-> to_placeholder.

classmethod from_dict(mapping: Dict[str, Union[Dict[str, str], Dict[str, Dict[str, str]]]]) → PlaceholderOverrides[source]

Create instance from a mapping.

The given argument must follow the format specified below:

{
    "shared": {from_placeholder: to_placeholder},
    "source-specific": {
        source0: {from_placeholder: to_placeholder},
        source1: {from_placeholder: to_placeholder},
        ...
        sourceN: {from_placeholder: to_placeholder},
    }
}

No other top-level keys are accepted, but neither shared nor source-specific are required.

Parameters: mapping – A remapping dict.
Returns: A new instance.
Raises: ValueError – If there are any keys other than ‘shared’ and ‘source-specific’ present in mapping.

class rics.translation.offline.TranslationMap(source_placeholder_translations: Dict[SourceType, PlaceholderTranslations], name_to_source: Dict[NameType, SourceType] = None, fmt: Union[str, Format] = None, default: DefaultTranslations[SourceType] = None, default_fmt: Union[str, Format] = None)[source]

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

Storage class for fetched translations.

Parameters

source_placeholder_translations – Fetched translations {source: PlaceholderTranslations}.
name_to_source – Mappings {name: source}, but may be overridden by the user.
fmt – A translation format. Must be given to use as a mapping.
default – Per-source default values.
default_fmt – Alternative format specification to use instead of fmt for fallback translation.

FORMAT_APPLIER_TYPE: alias of DefaultFormatApplier

apply(name: NameType, fmt: Optional[Union[str, Format]] = None, default_fmt: Optional[Union[str, Format]] = None) → MagicDict[IdType][source]

Create translations for names. Note: __getitem__ delegates to this method.

Parameters

name – A name to translate.
fmt – Format to use. If None, fall back to init format.
default_fmt – Alternative format for default translation. Resolution: Arg -> init arg, fmt arg, init fmt arg

Returns

Translations for name as a dict {id: translation}.

Raises

ValueError – If fmt==None and initialized without fmt.
KeyError – If trying to translate name which is not known.

property names: List[NameType]: Return names that can be translated.

property sources: List[SourceType]: Return translation source.

property name_to_source: Dict[NameType, SourceType]: Return name-to-source mapping.

class rics.translation.offline.MagicDict(real_translations: Dict[IdType, str], default_value: Optional[str] = None, add_id: bool = True)[source]

Bases: Mapping[IdType, str]

Immutable mapping for translated IDs.

If default_value is given, it is used as the default answer for any calls to __getitem__ where the key is not in translated_ids.

Should the add_id flag also be set, it will be converted into a callable that includes the ID requested in the returned value. In this case, the default_value must include exactly one positional placeholder.

If has_placeholder is not set, there should not be any placeholders in default_value at all.

Parameters

real_translations – A dict holding real translations.
default_value – String format callable with a single positional placeholder.
add_id – Indicates that string has a single placeholder that should be replaced by the given key when key not in translated_ids.

classmethod make(real_translations: ~typing.Dict[~rics.translation.offline.types.IdType, str], fstring: str, placeholders: ~typing.Tuple[str, ...], default: ~typing.Union[~typing.Literal[<_NoDefault.NO_DEFAULT: '<no-default>'>], ~typing.Dict[str, ~typing.Any]] = _NoDefault.NO_DEFAULT) → MagicDict[IdType][source]

Create a new instance.

Parameters

real_translations – A dict holding real translations.
fstring – A positional format string to create a default return value from.
placeholders – Names of placeholders in fstring, in order.
default – A dict of default values for placeholders in fstring.

Returns

A new MagicDict.