23.2. locale – Службы интернационализации¶locale – Internationalization services

Исходный код: Lib/locale.py

Модуль locale предоставляет доступ к базе данных локалей POSIX и её функциональности. Механизм локалей POSIX позволяет разработчикам решать задачи, связанные с культурными особенностями приложения, не требуя от них знания всех тонкостей каждой страны, где выполняется программа.

Модуль locale реализован поверх модуля _locale, который, в свою очередь, использует реализацию локали ANSI C, если она доступна.

Модуль locale определяет следующее исключение и функции:

exception locale.Error¶

Исключение возникает, когда локаль, переданная в setlocale(), не распознана.

locale.setlocale(category, locale=None)¶

Если передан locale и он не равен None, то setlocale() изменяет настройки локали для категории category. Доступные категории перечислены ниже в описании данных. locale может быть строкой или итерируемым объектом из двух строк (код языка и кодировка). Если это итерируемый объект, он преобразуется в имя локали с помощью механизма псевдонимов локалей. Пустая строка задаёт настройки пользователя по умолчанию. Если изменение локали не удаётся, вызывается исключение Error. В случае успеха возвращается новая настройка локали.

Если locale опущен или равен None, возвращается текущая настройка для категории category.

setlocale() не является потокобезопасной на большинстве систем. Приложения обычно начинают с вызова

import locale
locale.setlocale(locale.LC_ALL, '')

Это устанавливает локаль для всех категорий в пользовательскую настройку по умолчанию (обычно заданную в переменной окружения LANG). Если впоследствии локаль не изменять, использование многопоточности не должно вызывать проблем.

locale.localeconv()¶

Возвращает словарь с данными о локальных соглашениях. Ключами этого словаря являются следующие строки:

Категория	Клавиша	Значение
LC_NUMERIC	'decimal_point'	Символ десятичной точки.
	'grouping'	Последовательность чисел, указывающая, в каких относительных позициях ожидается 'thousands_sep'. Если последовательность завершается значением CHAR_MAX, дальнейшая группировка не выполняется. Если последовательность завершается значением 0, размер последней группы используется повторно.
	'thousands_sep'	Символ, используемый между группами.
LC_MONETARY	'int_curr_symbol'	Международный символ валюты.
	'currency_symbol'	Локальный символ валюты.
	'p_cs_precedes/n_cs_precedes'	Предшествует ли символ валюты значению (для положительных и отрицательных значений соответственно).
	'p_sep_by_space/n_sep_by_space'	Отделяется ли символ валюты от значения пробелом (для положительных и отрицательных значений соответственно).
	'mon_decimal_point'	Десятичная точка, используемая для денежных значений.
	'frac_digits'	Количество дробных цифр, используемых в локальном форматировании денежных значений.
	'int_frac_digits'	Количество дробных цифр, используемых в международном форматировании денежных значений.
	'mon_thousands_sep'	Разделитель групп, используемый для денежных значений.
	'mon_grouping'	Эквивалентно 'grouping', используется для денежных значений.
	'positive_sign'	Символ, используемый для обозначения положительного денежного значения.
	'negative_sign'	Символ, используемый для обозначения отрицательного денежного значения.
	'p_sign_posn/n_sign_posn'	Положение знака (для положительных и отрицательных значений соответственно), см. ниже.

Все числовые значения можно задать как CHAR_MAX, чтобы указать, что в данной локали значение не задано.

Возможные значения для 'p_sign_posn' и 'n_sign_posn' приведены ниже.

Значение	Пояснение
0	Валюта и значение заключаются в скобки.
1	Знак должен стоять перед значением и символом валюты.
2	Знак должен следовать после значения и символа валюты.
3	Знак должен стоять непосредственно перед значением.
4	Знак должен стоять непосредственно после значения.
CHAR_MAX	В этой локали ничего не указано.

Функция временно устанавливает локаль LC_CTYPE в локаль LC_NUMERIC или локаль LC_MONETARY, если локали различаются, а числовые или денежные строки не являются ASCII. Это временное изменение влияет на другие потоки.

Изменено в версии 3.6.5: Функция теперь временно устанавливает локаль LC_CTYPE на локаль LC_NUMERIC в некоторых случаях.

locale.nl_langinfo(option)¶

Возвращает строку с информацией, зависящей от локали. Эта функция доступна не на всех системах, и набор возможных опций может различаться на разных платформах. Аргументы – числа, для которых в модуле locale определены символьные константы.

Функция nl_langinfo() принимает один из следующих ключей. Большинство описаний взяты из соответствующих описаний в библиотеке GNU C.

locale.CODESET¶

Возвращает строку с именем кодировки символов, используемой в выбранной локали.

locale.D_T_FMT¶

Возвращает строку, которую можно использовать как строку форматирования для time.strftime() для представления даты и времени с учётом локали.

locale.D_FMT¶

Возвращает строку, которую можно использовать как строку форматирования для time.strftime() для представления даты с учётом локали.

locale.T_FMT¶

Возвращает строку, которую можно использовать как строку форматирования для time.strftime() для представления времени с учётом локали.

locale.T_FMT_AMPM¶

Возвращает строку форматирования для time.strftime() для представления времени в формате AM/PM.

DAY_1 ... DAY_7

Возвращает название n-го дня недели.

Примечание

В соответствии с американским соглашением DAY_1 – воскресенье, а не международным (ISO 8601), где первый день недели – понедельник.

ABDAY_1 ... ABDAY_7

Возвращает сокращённое название n-го дня недели.

MON_1 ... MON_12

Возвращает название n-го месяца.

ABMON_1 ... ABMON_12

Получить сокращённое название n-го месяца.

locale.RADIXCHAR¶

Получить символ десятичного разделителя (десятичная точка, десятичная запятая и т.д.).

locale.THOUSEP¶

Получить символ разделителя тысяч (групп по три цифры).

locale.YESEXPR¶

Получить регулярное выражение, которое можно использовать с функцией regex для распознавания положительного ответа на вопрос «да/нет».

Примечание

Выражение имеет синтаксис, подходящий для функции regex() из библиотеки C, который может отличаться от синтаксиса, используемого в re.

locale.NOEXPR¶

Возвращает регулярное выражение, которое можно использовать с функцией regex(3) для распознавания отрицательного ответа на вопрос «да/нет».

locale.CRNCYSTR¶

Получить символ валюты, перед которым стоит «-», если символ должен отображаться перед значением, «+», если символ должен отображаться после значения, или «.», если символ должен заменить десятичный разделитель.

locale.ERA¶

Возвращает строку, представляющую эру, используемую в текущей локали.

Большинство локалей не определяют это значение. Примером локали, которая определяет это значение, является японская. В Японии традиционное представление дат включает название эры, соответствующей правлению действующего императора.

Обычно нет необходимости использовать это значение напрямую. Указание модификатора E в строках формата заставляет функцию time.strftime() использовать эту информацию. Формат возвращаемой строки не определён, поэтому не следует полагаться на его вид в разных системах.

locale.ERA_D_T_FMT¶

Получить строку формата для time.strftime() для представления даты и времени в локализованном формате, основанном на эре.

locale.ERA_D_FMT¶

Получить строку формата для time.strftime() для представления даты в локализованном формате, основанном на эре.

locale.ERA_T_FMT¶

Получить строку формата для time.strftime() для представления времени в локализованном формате, основанном на эре.

locale.ALT_DIGITS¶

Возвращает представление до 100 значений, используемых для обозначения чисел от 0 до 99.

locale.getdefaultlocale([envvars])¶

Пытается определить настройки локали по умолчанию и возвращает их в виде кортежа вида (language code, encoding).

Согласно POSIX, программа, которая не вызывала setlocale(LC_ALL, ''), работает с переносимой локалью 'C'. Вызов setlocale(LC_ALL, '') позволяет ей использовать локаль по умолчанию, определённую переменной LANG. Поскольку мы не хотим вмешиваться в текущую настройку локали, мы имитируем описанное выше поведение.

Для поддержания совместимости с другими платформами тестируется не только переменная LANG, но и список переменных, задаваемый параметром envvars. Первая обнаруженная определённая переменная будет использована. envvars по умолчанию равен пути поиска, используемому в GNU gettext; он всегда должен содержать имя переменной 'LANG'. Путь поиска GNU gettext содержит 'LC_ALL', 'LC_CTYPE', 'LANG' и 'LANGUAGE' в указанном порядке.

За исключением кода 'C', код языка соответствует RFC 1766. Код языка и кодировка могут быть None, если их значения не удаётся определить.

locale.getlocale(category=LC_CTYPE)¶

Возвращает текущую настройку для указанной категории локали в виде последовательности, содержащей код языка, кодировку. Категория может быть одним из значений LC_*, кроме LC_ALL. По умолчанию LC_CTYPE.

За исключением кода 'C', код языка соответствует RFC 1766. Код языка и кодировка могут быть None, если их значения не удаётся определить.

locale.getpreferredencoding(do_setlocale=True)¶

Возвращает кодировку, используемую для текстовых данных, в соответствии с пользовательскими настройками. Пользовательские настройки выражаются по-разному в разных системах и могут быть недоступны программно в некоторых системах, поэтому эта функция возвращает только предположение.

В некоторых системах необходимо вызвать setlocale() для получения пользовательских настроек, поэтому эта функция не является потокобезопасной. Если вызов setlocale не требуется или нежелателен, do_setlocale следует установить в False.

locale.normalize(localename)¶

Возвращает нормализованный код локали для заданного имени локали. Возвращённый код локали отформатирован для использования с setlocale(). Если нормализация не удалась, исходное имя возвращается без изменений.

Если заданная кодировка неизвестна, функция использует кодировку по умолчанию для кода локали, как и setlocale().

locale.resetlocale(category=LC_ALL)¶

Устанавливает локаль для category в значение по умолчанию.

Значение по умолчанию определяется вызовом getdefaultlocale(). category по умолчанию равен LC_ALL.

locale.strcoll(string1, string2)¶

Сравнивает две строки в соответствии с текущей настройкой LC_COLLATE. Как и любая другая функция сравнения, возвращает отрицательное, положительное значение или 0 в зависимости от того, располагается ли string1 до или после string2 или равна ей.

locale.strxfrm(string)¶

Преобразует строку в форму, пригодную для сравнений с учётом локали. Например, strxfrm(s1) < strxfrm(s2) эквивалентно strcoll(s1, s2) < 0. Эта функция может использоваться, когда одна и та же строка сравнивается многократно, например, при сортировке последовательности строк.

locale.format(format, val, grouping=False, monetary=False)¶

Форматирует число val в соответствии с текущей настройкой LC_NUMERIC. Формат следует соглашениям оператора %. Для чисел с плавающей запятой десятичная точка изменяется, если это уместно. Если grouping равно true, также учитывается группировка.

Если monetary истинно, преобразование использует денежные разделители тысяч и строки группировки.

Обратите внимание, что эта функция работает только для одного спецификатора %char. Для целых строк формата используйте format_string().

locale.format_string(format, val, grouping=False)¶

Обрабатывает спецификаторы форматирования, как в format % val, но с учётом текущих настроек локали.

locale.currency(val, symbol=True, grouping=False, international=False)¶

Форматирует число val в соответствии с текущими настройками LC_MONETARY.

Возвращаемая строка включает символ валюты, если symbol равно true (значение по умолчанию). Если grouping равно true (не по умолчанию), выполняется группировка значения. Если international равно true (не по умолчанию), используется международный символ валюты.

Обратите внимание, что эта функция не работает с локалью 'C', поэтому сначала необходимо установить локаль через setlocale().

locale.str(float)¶

Форматирует число с плавающей запятой, используя тот же формат, что и встроенная функция str(float), но учитывает десятичную точку.

locale.delocalize(string)¶

Преобразует строку в нормализованное строковое представление числа в соответствии с настройками LC_NUMERIC.

Новое в версии 3.5.

locale.atof(string)¶

Преобразует строку в число с плавающей запятой в соответствии с LC_NUMERIC настройками.

locale.atoi(string)¶

Преобразует строку в целое число, следуя соглашениям LC_NUMERIC.

locale.LC_CTYPE¶

Категория локали для функций обработки символов. В зависимости от настроек этой категории функции модуля string, работающие с регистром, изменяют своё поведение.

locale.LC_COLLATE¶

Категория локали для сортировки строк. Функции strcoll() и strxfrm() модуля locale затрагиваются.

locale.LC_TIME¶

Категория локали для форматирования времени. Функция time.strftime() следует этим соглашениям.

locale.LC_MONETARY¶

Категория локали для форматирования денежных значений. Доступные параметры можно получить из функции localeconv().

locale.LC_MESSAGES¶

Категория локали для отображения сообщений. В настоящее время Python не поддерживает сообщения, учитывающие локаль, для конкретных приложений. Сообщения, выводимые операционной системой, например возвращаемые os.strerror(), могут затрагиваться этой категорией.

locale.LC_NUMERIC¶

Категория локали для форматирования чисел. Функции format(), atoi(), atof() и str() модуля locale затрагиваются этой категорией. Все остальные операции форматирования чисел не затрагиваются.

locale.LC_ALL¶

Комбинация всех настроек локали. Если этот флаг используется при изменении локали, предпринимается попытка установить локаль для всех категорий. Если это не удаётся для какой-либо категории, ни одна категория не изменяется. При получении локали с помощью этого флага возвращается строка, указывающая настройки для всех категорий. Эту строку можно впоследствии использовать для восстановления настроек.

locale.CHAR_MAX¶

Это символическая константа, используемая для различных значений, возвращаемых localeconv().

Пример:

>>> import locale
>>> loc = locale.getlocale()  # получить текущую локаль
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # сравнить строку, содержащую умлаут
>>> locale.setlocale(locale.LC_ALL, '')   # использовать предпочтительную локаль пользователя
>>> locale.setlocale(locale.LC_ALL, 'C')  # использовать локаль по умолчанию (C)
>>> locale.setlocale(locale.LC_ALL, loc)  # восстановить сохранённую локаль