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.

locale.DAY_1

locale.DAY_2

locale.DAY_3

locale.DAY_4

locale.DAY_5

locale.DAY_6

locale.DAY_7

Получить название n-го дня недели.

Примечание

Здесь используется принятый в США порядок: DAY_1 — воскресенье, а не международный порядок (ISO 8601), в котором неделя начинается с понедельника.

locale.ABDAY_1

locale.ABDAY_2

locale.ABDAY_3

locale.ABDAY_4

locale.ABDAY_5

locale.ABDAY_6

locale.ABDAY_7

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

locale.MON_1

locale.MON_2

locale.MON_3

locale.MON_4

locale.MON_5

locale.MON_6

locale.MON_7

locale.MON_8

locale.MON_9

locale.MON_10

locale.MON_11

locale.MON_12

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

locale.ABMON_1

locale.ABMON_2

locale.ABMON_3

locale.ABMON_4

locale.ABMON_5

locale.ABMON_6

locale.ABMON_7

locale.ABMON_8

locale.ABMON_9

locale.ABMON_10

locale.ABMON_11

locale.ABMON_12

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

locale.RADIXCHAR

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

locale.THOUSEP

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

locale.YESEXPR

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

locale.NOEXPR

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

Примечание

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

locale.CRNCYSTR

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

locale.ERA

Получить строку, описывающую способы исчисления и отображения лет для каждой эры в данной локали.

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

Обычно нет необходимости напрямую использовать это значение. Указание модификатора E в строках формата заставляет функцию time.strftime() использовать эти сведения. Формат возвращаемой строки задан в Основных спецификациях The Open Group, выпуск 8, пункте 7.3.5.2 Доступ к LC_TIME из языка C.

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. Значения language code и encoding могут быть равны None, если их невозможно определить.

Устарело с версии 3.11, будет удалено в версии 3.15.

locale.getlocale(category=LC_CTYPE)

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

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

locale.getpreferredencoding(do_setlocale=True)

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

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

На Android или при включённом режиме UTF-8 Python всегда возвращается 'utf-8'; аргументы кодировка локали и do_setlocale игнорируются.

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

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

locale.getencoding()

Получить текущую кодировку локали:

• На Android и VxWorks возвращает "utf-8".
• В Unix возвращает кодировку текущей локали LC_CTYPE. Возвращает "utf-8", если nl_langinfo(CODESET) возвращает пустую строку, например, если текущая локаль LC_CTYPE не поддерживается.
• В Windows возвращает кодовую страницу ANSI.

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

Эта функция похожа на getpreferredencoding(False), но игнорирует режим UTF-8 Python.

Добавлено в версии 3.11.

locale.normalize(localename)

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

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

locale.resetlocale(category=LC_ALL)

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

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

Устарело с версии 3.11, будет удалено в версии 3.13.

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.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

Категория локали для функций, работающих с типами символов. Важнее всего то, что эта категория задаёт кодировку текста, то есть способ интерпретации байтов как кодовых точек Unicode. О том, как эта переменная может автоматически принудительно устанавливаться в C.UTF-8 во избежание проблем из-за недопустимых настроек в контейнерах или несовместимых настроек, переданных через удалённые SSH-подключения, см. PEP 538 и PEP 540.

Python не использует внутри себя зависящие от локали функции преобразования символов из ctype.h. Вместо этого внутренний pyctype.h предоставляет эквивалентные функции, не зависящие от локали, например Py_TOLOWER.

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_string(), 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