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)

Преобразует строку в число с плавающей точкой, следуя настройкам 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()  # 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