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

Модуль 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	В этой локали ничего не указано.

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])¶

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

Согласно 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)¶

Возвращает текущую настройку для указанной категории локали в виде последовательности, содержащей код языка и кодировку. category может быть одним из значений 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.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) # восстановить сохранённую локаль