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 для распознавания положительного ответа на вопрос «да/нет».

locale.NOEXPR

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

Примечание

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

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 Python, всегда возвращается 'UTF-8', кодировка локали и аргумент do_setlocale игнорируются.

Предварительная инициализация Python настраивает локаль LC_CTYPE. См. также кодировку и обработчик ошибок файловой системы.

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

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.localize(string, grouping=False, monetary=False)

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

Введено в версии 3.10.

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(), могут быть затронуты этой категорией.

Это значение может быть недоступно на операционных системах, не соответствующих стандарту POSIX, в частности, на Windows.

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