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

_getUserLocaleUnsafe

Get locale conventions dictionary. May change the global locale if called directly.

getUserLocale

Get locale conventions dictionary. Ensures that the locale (global to the process) is reset afterwards.

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]

_unsafeIsLocaleCompatible

Checks if locale can be set by python on the system. May change the global locale if called directly.

_unsafeFindCompatibleLocale

Attempts to find a system compatible locale (checks default regions and possible encodings) based on the user provided locale value. May change the global locale if called directly.

findCompatibleLocale

Attempts to find a system compatible locale (checks default regions and possible encodings) based on the user provided locale value.

_candidateLocaleCodes

Returns a list of additional candidate POSIX locales including default region and utf-8 encoding variants.

bcp47LangToPosixLocale

Transform a BCP47 language tag (en-US) to a POSIX locale (en_US).

posixLocaleToBCP47Lang

Transform a POSIX locale (en_US.utf-8) to a BCP47 language tag (en-US).

_buildPosixLocale

_buildBCP47LanguageTag

_getPosixLocaleLangRegionAndEncoding

returns the language, region, and encoding values from the POSIX locale. None is returned for region and encoding if not present.

getLocale

_tryRunShellCommand

Tries to return the results of the provided shell command. Returns stdout or None if the command exists with a non-zero code.

getLocaleList

Attempts to a return a list of locales from locale -a with a fallback of an empty list.

availableLocales

Returns a set of available system languages (POSIX format without encoding). On Windows system locales can’t be easily determined and an empty set is returned.

languageCodes

setApplicationLocale

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

setDisableRTL

rtlString

_grouping_intervals

_group

_strip_padding

format

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

_format

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

API

arelle.Locale._: arelle.typing.TypeGetText

None

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.MACOS_PLATFORM

‘darwin’

arelle.Locale.WINDOWS_PLATFORM

‘win32’

arelle.Locale.BCP47_LANGUAGE_REGION_SEPARATOR

‘-’

arelle.Locale.POSIX_LANGUAGE_REGION_SEPARATOR

‘_’

arelle.Locale.POSIX_LOCALE_ENCODING_SEPARATOR

‘.’

arelle.Locale.BCP47_LANGUAGE_TAG

‘compile(…)’

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

Get locale conventions dictionary. May change the global locale if called directly.

Parameters:

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

Returns:

Tuple of local conventions dictionary and a user-directed setup message

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

Get locale conventions dictionary. Ensures that the locale (global to the process) is reset afterwards.

Parameters:

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

Returns:

Tuple of local conventions dictionary and a user-directed setup message

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._unsafeIsLocaleCompatible(localeValue: str) bool

Checks if locale can be set by python on the system. May change the global locale if called directly.

arelle.Locale._unsafeFindCompatibleLocale(localeValue: str) str | None

Attempts to find a system compatible locale (checks default regions and possible encodings) based on the user provided locale value. May change the global locale if called directly.

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

Attempts to find a system compatible locale (checks default regions and possible encodings) based on the user provided locale value.

arelle.Locale._candidateLocaleCodes(posixLocale: str) list[str]

Returns a list of additional candidate POSIX locales including default region and utf-8 encoding variants.

arelle.Locale.bcp47LangToPosixLocale(bcp47Lang: str) str

Transform a BCP47 language tag (en-US) to a POSIX locale (en_US).

arelle.Locale.posixLocaleToBCP47Lang(posixLocale: str) str

Transform a POSIX locale (en_US.utf-8) to a BCP47 language tag (en-US).

arelle.Locale._buildPosixLocale(lang: str, region: str | None = None, encoding: str | None = None) str
arelle.Locale._buildBCP47LanguageTag(lang: str, region: str | None = None) str
arelle.Locale._getPosixLocaleLangRegionAndEncoding(posixLocale: str) tuple[str, str | None, str | None]

returns the language, region, and encoding values from the POSIX locale. None is returned for region and encoding if not present.

arelle.Locale._locale

None

arelle.Locale.getLocale() str | None
arelle.Locale._tryRunShellCommand(*args: str) str | None

Tries to return the results of the provided shell command. Returns stdout or None if the command exists with a non-zero code.

arelle.Locale.iso3region

None

arelle.Locale._systemLocales

None

arelle.Locale.getLocaleList() list[str]

Attempts to a return a list of locales from locale -a with a fallback of an empty list.

arelle.Locale.availableLocales() set[str]

Returns a set of available system languages (POSIX format without encoding). On Windows system locales can’t be easily determined and an empty set is returned.

arelle.Locale._languageCodes

None

arelle.Locale.languageCodes() dict[str, str]
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._disableRTL: bool

False

arelle.Locale.setDisableRTL(disableRTL: bool) None
arelle.Locale.rtlString(source: str, lang: str | None) str
arelle.Locale._grouping_intervals(grouping: list[int]) Generator[int, None, None]
arelle.Locale._group(conv: arelle.typing.LocaleDict, s: str, monetary: bool = False) tuple[str, int]
arelle.Locale._strip_padding(s: str, amount: int) str
arelle.Locale._percent_re

‘compile(…)’

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(conv: arelle.typing.LocaleDict, percent: str, value: Any, grouping: bool = False, monetary: bool = False, *additional: str) str
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: 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>’