arelle.Locale

This module is a local copy of python locale in order to allow passing in localconv as an argument to functions without affecting system-wide settings. (The system settings can remain in ‘C’ locale.)

See COPYRIGHT.md for copyright information.

Module Contents

Functions

getUserLocale	Get locale conventions dictionary.
getLanguageCode
getLanguageCodes	Returns a list of language code formats that can be used with gettext to look up translation files. configLang is user specified and may be in the BCP 47 format (en-US) or POSIX locale (en_US.utf-8). The translation files can also be user generated and in any of these formats. We do our best to work with both formats. [en_US, en-US, en] [fr]
findCompatibleLocale	Attempts to find a system-compatible locale based on the provided value. Checks default regions and possible encodings.
bcp47LangToPosixLocale	Normalise a locale string to POSIX format (en_US). Accepts BCP47 (en-US) or POSIX (en_US.utf-8). Unrecognised strings fall back to the Arelle default locale.
posixLocaleToBCP47Lang	Normalise a locale string to BCP47 format (en-US). Accepts POSIX (en_US.utf-8) or BCP47 (en-US). Unrecognised strings fall back to the Arelle default locale.
getLocale	Returns the user’s locale as a POSIX locale string without encoding (e.g. ‘en_US’, ‘fr_FR’). The POSIX and C locales are treated as unset (return None) since they have no real language. The result is cached after the first call.
getLocaleList	Returns a list of available system locale codes in POSIX format (e.g. ‘en_US’, ‘fr_FR’).
availableLocales	Returns a set of available system languages (POSIX format without encoding).
availableBCP47LangTags	Returns a set of available system languages (BCP-47 format).
languageCodes	Return a mapping of English language names to BCP47 tags (e.g. ‘English (United Kingdom)’ → ‘en-GB’).
setApplicationLocale	Sets the locale to C, to be used when running Arelle as a standalone application (e.g., arelleCmdLine, arelleGUI.)
setDisableRTL
rtlString
format	Returns the locale-aware substitution of a %? specifier (percent).
format_string	Formats a string in the same way that the % formatting would use, but takes the current locale into account. Grouping is applied if the third parameter is true.
currency	Formats val according to the currency settings in the current locale.
ftostr	Convert float to integer, taking the locale into account.
atof	Parses a string as a float according to the locale settings.
atoi	Converts a string to an integer according to the locale settings.
format_picture
format_decimal	Convert Decimal to a formatted string including currency if any.

Data

CHAR_MAX
LC_ALL
LC_COLLATE
LC_CTYPE
LC_MESSAGES
LC_MONETARY
LC_NUMERIC
LC_TIME
defaultLocaleCodes
BCP47_LANGUAGE_REGION_SEPARATOR
POSIX_LANGUAGE_REGION_SEPARATOR
POSIX_LOCALE_ENCODING_SEPARATOR
POSIX_LOCALE_DEFAULT_ENCODING
POSIX_PSEUDO_LOCALES
BCP47_LANGUAGE_TAG_RE
POSIX_LOCALENAME_RE
iso3region

API

arelle.Locale.CHAR_MAX

127

arelle.Locale.LC_ALL

6

arelle.Locale.LC_COLLATE

3

arelle.Locale.LC_CTYPE

0

arelle.Locale.LC_MESSAGES

5

arelle.Locale.LC_MONETARY

4

arelle.Locale.LC_NUMERIC

1

arelle.Locale.LC_TIME

2

arelle.Locale.defaultLocaleCodes

None

arelle.Locale.BCP47_LANGUAGE_REGION_SEPARATOR

‘-’

arelle.Locale.POSIX_LANGUAGE_REGION_SEPARATOR

‘_’

arelle.Locale.POSIX_LOCALE_ENCODING_SEPARATOR

‘.’

arelle.Locale.POSIX_LOCALE_DEFAULT_ENCODING

‘utf-8’

arelle.Locale.POSIX_PSEUDO_LOCALES

‘frozenset(…)’

arelle.Locale.BCP47_LANGUAGE_TAG_RE

‘compile(…)’

arelle.Locale.POSIX_LOCALENAME_RE

‘compile(…)’

arelle.Locale.getUserLocale(posixLocale: str | None = None) → tuple[arelle.typing.LocaleDict, str | None]

Get locale conventions dictionary.

Parameters:

posixLocale – The locale code to use to retrieve conventions. Defaults to system default.

Returns:

Tuple of (locale conventions dict, optional error message for the user)

arelle.Locale.getLanguageCode() → str

arelle.Locale.getLanguageCodes(configLang: str | None = None) → list[str]

Returns a list of language code formats that can be used with gettext to look up translation files. configLang is user specified and may be in the BCP 47 format (en-US) or POSIX locale (en_US.utf-8). The translation files can also be user generated and in any of these formats. We do our best to work with both formats. [en_US, en-US, en] [fr]

arelle.Locale.findCompatibleLocale(localeValue: str | None) → str | None

Attempts to find a system-compatible locale based on the provided value. Checks default regions and possible encodings.

Parameters:

localeValue – Locale string in BCP-47 format (e.g. 'en-US') or POSIX format (e.g. 'en_US.utf-8').

Returns:

A POSIX-style locale string that can be passed to setlocale, or None if no compatible locale is found.

arelle.Locale.bcp47LangToPosixLocale(bcp47Lang: str) → str

Normalise a locale string to POSIX format (en_US). Accepts BCP47 (en-US) or POSIX (en_US.utf-8). Unrecognised strings fall back to the Arelle default locale.

arelle.Locale.posixLocaleToBCP47Lang(posixLocale: str) → str

Normalise a locale string to BCP47 format (en-US). Accepts POSIX (en_US.utf-8) or BCP47 (en-US). Unrecognised strings fall back to the Arelle default locale.

arelle.Locale.getLocale() → str | None

Returns the user’s locale as a POSIX locale string without encoding (e.g. ‘en_US’, ‘fr_FR’). The POSIX and C locales are treated as unset (return None) since they have no real language. The result is cached after the first call.

arelle.Locale.iso3region

None

arelle.Locale.getLocaleList() → list[str]

Returns a list of available system locale codes in POSIX format (e.g. ‘en_US’, ‘fr_FR’).

arelle.Locale.availableLocales() → frozenset[str]

Returns a set of available system languages (POSIX format without encoding).

arelle.Locale.availableBCP47LangTags() → frozenset[str]

Returns a set of available system languages (BCP-47 format).

arelle.Locale.languageCodes() → dict[str, str]

Return a mapping of English language names to BCP47 tags (e.g. ‘English (United Kingdom)’ → ‘en-GB’).

arelle.Locale.setApplicationLocale() → None

Sets the locale to C, to be used when running Arelle as a standalone application (e.g., arelleCmdLine, arelleGUI.)

Returns:

arelle.Locale.setDisableRTL(disableRTL: bool) → None

arelle.Locale.rtlString(source: str, lang: str | None) → str

arelle.Locale.format(conv: arelle.typing.LocaleDict, percent: str, value: Any, grouping: bool = False, monetary: bool = False, *additional: str) → str

Returns the locale-aware substitution of a %? specifier (percent).

additional is for format strings which contain one or more ‘*’ modifiers.

arelle.Locale.format_string(conv: arelle.typing.LocaleDict, f: str, val: Any, grouping: bool = False) → str

Formats a string in the same way that the % formatting would use, but takes the current locale into account. Grouping is applied if the third parameter is true.

arelle.Locale.currency(conv: arelle.typing.LocaleDict, val: int | float, symbol: bool = True, grouping: bool = False, international: bool = False) → str

Formats val according to the currency settings in the current locale.

arelle.Locale.ftostr(conv: arelle.typing.LocaleDict, val: Any) → str

Convert float to integer, taking the locale into account.

arelle.Locale.atof(conv: arelle.typing.LocaleDict, string: str, func: collections.abc.Callable[[str], Any] = float) → Any

Parses a string as a float according to the locale settings.

arelle.Locale.atoi(conv: arelle.typing.LocaleDict, str: arelle.Locale.atoi.str) → int

Converts a string to an integer according to the locale settings.

arelle.Locale.format_picture(conv: arelle.typing.LocaleDict, value: Any, picture: str) → str

arelle.Locale.format_decimal(conv: arelle.typing.LocaleDict | None, value: decimal.Decimal, intPlaces: int = 1, fractPlaces: int = 2, curr: str = '', sep: str | None = None, grouping: int | None = None, dp: str | None = None, pos: str | None = None, neg: str | None = None, trailpos: str | None = None, trailneg: str | None = None) → str

Convert Decimal to a formatted string including currency if any.

intPlaces: required number of digits before the decimal point fractPlaces: required number of places after the decimal point curr: optional currency symbol before the sign (may be blank) sep: optional grouping separator (comma, period, space, or blank) dp: decimal point indicator (comma or period) only specify as blank when places is zero pos: optional sign for positive numbers: ‘+’, space or blank neg: optional sign for negative numbers: ‘-’, ‘(’, space or blank trailneg:optional trailing minus indicator: ‘-’, ‘)’, space or blank

d = Decimal(‘-1234567.8901’) format_decimal(getUserLocale()[0], d, curr=’$’) ‘-$1,234,567.89’ format_decimal(getUserLocale()[0], d, fractPlaces=0, sep=’.’, dp=’’, neg=’’, trailneg=’-‘) ‘1.234.568-’ format_decimal(getUserLocale()[0], d, curr=’$’, neg=’(’, trailneg=’)’) ‘($1,234,567.89)’ format_decimal(getUserLocale()[0], Decimal(123456789), sep=’ ‘) ‘123 456 789.00’ format_decimal(getUserLocale()[0], Decimal(‘-0.02’), neg=’<’, trailneg=’>’) ‘<0.02>’