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.

Если аргумент 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 Base Specifications Issue 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' именно в таком порядке.

Код языка имеет тот же формат, что и имя локали, но без кодировки и модификатора @. Код языка и кодировка могут быть None, если их значения определить невозможно. Локаль «C» представляется как (None, None).

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

locale.getlocale(category=LC_CTYPE)

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

Код языка имеет тот же формат, что и имя локали, но без кодировки и модификатора @. Код языка и кодировка могут быть None, если их значения определить невозможно. Локаль «C» представляется как (None, 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.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

     language ["_" territory] ["." charset] ["@" modifier]

     language ["-" script] ["-" territory] ["." charset]
     language ["-" script] "-" territory "-" modifier

     language ["_" territory] ["." charset]