gws.lib.intl

Locales and locale-aware formatting.

Builds gws.Locale objects from babel and pycountry data and provides locale-aware formatters for dates, times and numbers.

locale finds a locale by a language or locale name (de or de_DE), optionally restricted to a list of allowed locale uids, and falls back to the first allowed locale or to the default locale en_CA (English with metric units). formatters returns a DateFormatter, TimeFormatter and NumberFormatter for a locale. Locales and formatters are cached per application.

Example:

loc = gws.lib.intl.locale('de', allowed=['de_DE', 'en_US'])
date_fmt, time_fmt, num_fmt = gws.lib.intl.formatters(loc)
date_fmt.long('2013-12-11')        # '11. Dezember 2013'
num_fmt.grouped(1234567.5)         # '1.234.567,5'

Source code: gws.lib.intl

Package Contents

class gws.lib.intl.DateFormatter(loc: gws.Locale)

Bases: gws.DateFormatter

Date formatter, based on babel.dates.

iso

Format a date in the ISO 8601 format, e.g. 2013-12-11.

Parameters:

date – Date or date string, the current date by default.

Returns:

The formatted date.

locale
long

Format a date in the long format of the locale, e.g. 11. Dezember 2013.

Parameters:

date – Date or date string, the current date by default.

Returns:

The formatted date.

medium

Format a date in the medium format of the locale, e.g. 11.12.2013.

Parameters:

date – Date or date string, the current date by default.

Returns:

The formatted date.

short

Format a date in the short format of the locale, e.g. 11.12.13.

Parameters:

date – Date or date string, the current date by default.

Returns:

The formatted date.

format(fmt: gws.DateTimeFormat, date=None)

Format a date.

Parameters:

  • fmt – Format type, or a babel (CLDR) date pattern like dd.MM.yyyy.

  • date – Date or date string, the current date by default.

Returns:

The formatted date.

Raises:

Error – If the date cannot be parsed.

gws.lib.intl.default_locale()

Return the default locale en_CA.

Returns:

A Locale object.

gws.lib.intl.formatters(loc: gws.Locale) → tuple[DateFormatter, TimeFormatter, NumberFormatter]

Return the formatters for a locale.

Formatters are cached per locale.

Parameters:

loc – A Locale object.

Returns:

A date, a time and a number formatter.

gws.lib.intl.locale(name: str | None, allowed: list[str] = None, fallback: bool = True) → gws.Locale

Find a locale by a language or locale name.

A language name selects the first allowed locale for that language or, if there is none, the most likely locale for the language (de becomes de_DE). A locale name must be allowed. If no locale is found and fallback is True, the first allowed locale or the default locale is returned.

Parameters:

  • name – Language or locale name like de, de_DE or de-DE.

  • allowed – Allowed locale uids.

  • fallback – If True, fall back to a default instead of raising an error.

Returns:

A Locale object.

Raises:

gws.Error – If no locale is found and fallback is False.

class gws.lib.intl.NumberFormatter(loc: gws.Locale)

Bases: gws.NumberFormatter

Number formatter, based on babel.numbers.

fns
locale
currency(n, currency, *args, **kwargs)

Format a number as a currency value.

Parameters:

  • n – Number.

  • currency – Currency code like EUR.

  • *args – Arguments for babel.numbers.format_currency.

  • **kwargs – Keyword arguments for babel.numbers.format_currency.

Returns:

The formatted value.

decimal(n, *args, **kwargs)

Format a number as a decimal without group separators.

Parameters:

  • n – Number.

  • *args – Arguments for babel.numbers.format_decimal.

  • **kwargs – Keyword arguments for babel.numbers.format_decimal.

Returns:

The formatted number.

format(fmt, n, *args, **kwargs)

Format a number.

Parameters:

  • fmt – Format type. For an unknown format, the number is converted with str.

  • n – Number.

  • *args – Arguments for the format method, e.g. the currency for currency.

  • **kwargs – Keyword arguments for the format method.

Returns:

The formatted number.

grouped(n, *args, **kwargs)

Format a number as a decimal with group separators.

Parameters:

  • n – Number.

  • *args – Arguments for babel.numbers.format_decimal.

  • **kwargs – Keyword arguments for babel.numbers.format_decimal.

Returns:

The formatted number.

percent(n, *args, **kwargs)

Format a number as a percentage, 0.5 is 50 percent.

Parameters:

  • n – Number.

  • *args – Arguments for babel.numbers.format_percent.

  • **kwargs – Keyword arguments for babel.numbers.format_percent.

Returns:

The formatted value.

class gws.lib.intl.TimeFormatter(loc: gws.Locale)

Bases: gws.TimeFormatter

Time formatter, based on babel.dates.

iso

Format a time in the ISO 8601 format, with the time zone offset, e.g. 11:22:33+0100.

Parameters:

time – Time, datetime or time string, the current time by default.

Returns:

The formatted time.

locale
long

Format a time in the long format of the locale, which usually includes the time zone.

Parameters:

time – Time, datetime or time string, the current time by default.

Returns:

The formatted time.

medium

Format a time in the medium format of the locale, e.g. 11:22:33.

Parameters:

time – Time, datetime or time string, the current time by default.

Returns:

The formatted time.

short

Format a time in the short format of the locale, e.g. 11:22.

Parameters:

time – Time, datetime or time string, the current time by default.

Returns:

The formatted time.

format(fmt: gws.DateTimeFormat, date=None) → str

Format a time.

Parameters:

  • fmt – Format type, or a babel (CLDR) time pattern like HH:mm.

  • time – Time, datetime or time string, the current time by default.

Returns:

The formatted time.

Raises:

Error – If the time cannot be parsed.