py_research.intl module#

Simple & semi-automatic intl. + localization of data analysis functions.

class DtUnit(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

Common datetime units with their LDML pattern strings.

year = 'yyyy'#
quarter = 'QQQ'#
month = 'MM'#
week = 'ww'#
week_of_month = 'W'#
day = 'dd'#
day_of_year = 'DD'#
hour = 'HH'#
minute = 'mm'#
second = 'ss'#
millisecond = 'SSS'#
class Format(decimal_notation=None, decimal_digits=None, decimal_min_digits=None, decimal_max_digits=None, decimal_group_separator=None, datetime_auto_format=None, datetime_format=None, timedelta_auto_format=None, timedelta_resolution=None, country_format=None, fallback_to_translation=True, na_representation='')[source]#

Bases: object

Custom options for localized formatting.

Parameters:

  • decimal_notation (Literal['plain', 'scientific', 'percent'] | None) –

  • decimal_digits (int | None) –

  • decimal_min_digits (int | None) –

  • decimal_max_digits (int | None) –

  • decimal_group_separator (bool | None) –

  • datetime_auto_format (Literal['short', 'medium', 'long'] | None) –

  • datetime_format (DtUnit | str | None) –

  • timedelta_auto_format (Literal['narrow', 'short', 'medium', 'long', 'raw'] | None) –

  • timedelta_resolution (Literal['year', 'month', 'week', 'day', 'hour', 'minute', 'second'] | None) –

  • country_format (Literal[GeoScheme.country_name, GeoScheme.cc_iso2, GeoScheme.cc_iso3] | None) –

  • fallback_to_translation (bool) –

  • na_representation (str) –

decimal_notation: Literal['plain', 'scientific', 'percent'] | None = None#

How to format decimals.

decimal_digits: int | None = None#

How many digits to show after the decimal point.

decimal_min_digits: int | None = None#

Minimum number of digits to show after the decimal point.

decimal_max_digits: int | None = None#

Maximum number of digits to show after the decimal point.

decimal_group_separator: bool | None = None#

Whether to use decimal group separators.

datetime_auto_format: Literal['short', 'medium', 'long'] | None = None#

How to auto-format datetimes.

datetime_format: DtUnit | str | None = None#

`ldml pattern`_ for formatting datetime objects. .. _ldml pattern: https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table

timedelta_auto_format: Literal['narrow', 'short', 'medium', 'long', 'raw'] | None = None#

How to auto-format timedeltas.

timedelta_resolution: Literal['year', 'month', 'week', 'day', 'hour', 'minute', 'second'] | None = None#

Unit to use for formatting timedeltas. Has no effect for auto-format ‘raw’.

country_format: Literal[GeoScheme.country_name, GeoScheme.cc_iso2, GeoScheme.cc_iso3] | None = None#

How to format countries.

fallback_to_translation: bool = True#

Whether to fallback to text translation if no other formatting method matches.

na_representation: str = ''#

String to use for NaN or None values.

merge(other)[source]#

Merge and override self with other.

Parameters:

other (Self) –

Return type:

Self

spec(t)[source]#

Generate format-spec matching this format usign current locale.

Parameters:

t (type) –

Return type:

str

auto_digits(series, min_sig=3, fixed=True)[source]#

Copy and change options according to numbers in sample.

Change such that all given numbers have minimum min_sig significant digits.

Parameters:

  • series (Iterable[float]) – Series of numbers to use for determining options.

  • min_sig (int) – Minimum number of significant digits.

  • fixed (bool) – Whether to fix the number of digits after the decimal point.

Returns:

New instance with changed options.

Return type:

Self

class Args(values=None, all=False)[source]#

Bases: object

Match for args of a text template.

Parameters:
values: Any = None#
all: bool = False#
match(args)[source]#

Check whether given args match this match.

Parameters:

args (tuple) –

Return type:

float

class Template(replace=None, wrap=None, args=None)[source]#

Bases: object

Override for a text template.

Parameters:
replace: str | None = None#

Replace template with this template string.

wrap: str | None = None#

Wrap template with this template string.

args: tuple | dict[int, Any] | None = None#

Replace (some) args.

apply_tmpl(tmpl)[source]#

Apply this template to given template string and args.

Parameters:

tmpl (str) –

Return type:

str | None

apply_args(args)[source]#

Apply this template to given args.

Parameters:

args (tuple) –

Return type:

tuple | None

class Overrides(templates=<factory>, vocabulary=<factory>, format=<factory>)[source]#

Bases: object

Custom, language-dependent text overrides.

Parameters:
templates: Mapping[str, str | Template | dict[str | tuple | Args, str | Template]]#

Template overrides by name.

vocabulary: dict[str, str]#

Term overrides.

format: Format#

Overrides for formatting.

merge(other)[source]#

Merge and override self with other.

Parameters:

other (Self) –

Return type:

Self

class Localization(loc=None, overrides=None, show_raw=False)[source]#

Bases: object

Locale config, which can be used as a context manager to activate the locale.

Parameters:
loc: Locale | str | None = None#

Locale to use for this localization. If None, use parent context’s locale.

overrides: Overrides | dict[Locale, Overrides] | dict[str, Overrides] | None = None#

Optional translation overrides for the current or other locales.

show_raw: bool = False#

Whether to show raw function calls instead of localized text, for debugging.

property locale: Locale#

Return first locale found up the parent tree or default locale.

property override_dict: dict[Locale, Overrides]#

Return dict of all overrides, keyed by locale string.

get_overrides(locale)[source]#

Return merger of all the parents’ and self’s overrides for given locale.

Parameters:

locale (Locale) –

Return type:

Overrides

activate()[source]#

Set this the as current localization.

deactivate(*_)[source]#

Reset locale to previous value.

term(term, locale=None)[source]#

Localize given term.

Parameters:

  • term (str) – Term to localize.

  • locale (Locale | None) – Locale to use for localization. Defaults to the currently activated locale.

Returns:

Localized term.

Return type:

str

text(context, content, *args, locale=None)[source]#

Localize given text.

Parameters:

  • context (str) – Label indentifying the context of the text to localize.

  • content (str | None) – Text to localize.

  • args (Any) – Extra args to pass, if given text content is a template string.

  • locale (Locale | None) – Locale to use for localization. Defaults to the currently activated locale.

Returns:

Localized text.

Return type:

str

label(label, context=None, locale=None)[source]#

Localize given label.

Parameters:

  • label (str) – Label to localize.

  • context (str | None) – Context in which the label is used.

  • locale (Locale | None) – Locale to use for localization. Defaults to the currently activated locale.

Returns:

Localized label.

Return type:

str

value(v, options=Format(decimal_notation=None, decimal_digits=None, decimal_min_digits=None, decimal_max_digits=None, decimal_group_separator=None, datetime_auto_format=None, datetime_format=None, timedelta_auto_format=None, timedelta_resolution=None, country_format=None, fallback_to_translation=True, na_representation=''), locale=None)[source]#

Return localized string represention of given value.

Parameters:

  • v (Any) – Value to localize.

  • options (Format) – Options for formatting.

  • context – Context in which the value is used.

  • locale (Locale | None) – Locale to use for localization.

Returns:

Localized value.

Return type:

str

formatter(options=Format(decimal_notation=None, decimal_digits=None, decimal_min_digits=None, decimal_max_digits=None, decimal_group_separator=None, datetime_auto_format=None, datetime_format=None, timedelta_auto_format=None, timedelta_resolution=None, country_format=None, fallback_to_translation=True, na_representation=''), locale=None)[source]#

Return a formatting function bound to this locale.

Parameters:

  • options (Format) – Options for formatting.

  • locale (Locale | None) – Locale to use for localization.

Returns:

Formatting function for generating localized values.

Return type:

Callable[[Any], str]

format_spec(typ, options=Format(decimal_notation=None, decimal_digits=None, decimal_min_digits=None, decimal_max_digits=None, decimal_group_separator=None, datetime_auto_format=None, datetime_format=None, timedelta_auto_format=None, timedelta_resolution=None, country_format=None, fallback_to_translation=True, na_representation=''), locale=None)[source]#

Return locale-aware format-string for given type, if applicable.

Parameters:

  • typ (type) – Type to get format-string for.

  • options (Format) – Options for formatting.

  • locale (Locale | None) – Locale to use for localization.

Return type:

str

get_localization()[source]#

Get currently active localization.

Return type:

Localization

iter_locales(locales=None, overrides=None)[source]#

Iterate over localizations for given locales w/ optional overrides.

Parameters:

  • locales (list[str] | None) – Locales to iterate over. If None, iterates over all locales, for which overrides are defined.

  • overrides (dict[str, Overrides] | None) – Optional text overrides for the localizations.

Returns:

Generator of localizations.

Return type:

Generator[Localization, None, None]

default_file_path = PosixPath('/home/runner/work/py-research/py-research/texts.yaml')#

Default path to text overrides file.

load_from_file(path=None)[source]#

Load text overrides from file.

Parameters:

path (Path | str | None) – Path to file. If None, the default file path is used.

Returns:

Path to the loaded file, if not given as argument.

Return type:

Path | None