locale — Услуги интернационализации

Исходный код: 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.7: Функция теперь временно устанавливает 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)

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

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

locale.getpreferredencoding(do_setlocale=True)

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

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

На Android или в режиме UTF-8 (-X опция utf8), всегда возвращает 'UTF-8', локали и аргумент do_setlocale игнорируются.

Изменено в версии 3.7: Функция теперь всегда возвращает UTF-8 на Android или при включении режима UTF-8.

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_string(format, val, grouping=False, monetary=False)

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

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

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

Изменено в версии 3.7: Параметр monetary был добавлен.

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

Обратите внимание, что эта функция работает как format_string(), но будет работать только с ровно одним %char спецификатором. Например, '%f' и '%.0f' являются допустимыми спецификаторами, но '%f KiB' нет.

Для целых строк форматирования используйте format_string().

Устарело начиная с версии 3.7: Используйте format_string() вместо этого.

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, func=float)

Преобразует строку в число, следуя настройкам LC_NUMERIC, вызывая func на результате вызова delocalize() для string.

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()  # get current locale
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '')   # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale