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.

Пример:

>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL)  # get current locale
# use German locale; name and availability varies with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
>>> 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

Функция 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

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

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

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 в соответствии с локалью. В большинстве локалей эта строка пуста.

Функция временно устанавливает локаль LC_CTYPE в локаль категории, определяющей запрошенное значение (LC_TIME, LC_NUMERIC, LC_MONETARY или LC_MESSAGES), если локали различаются, а полученная строка содержит символы, отличные от ASCII. Это временное изменение влияет на другие потоки.

Изменено в версии 3.14: В некоторых случаях функция теперь временно устанавливает локаль LC_CTYPE.

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

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. Если nl_langinfo(CODESET) возвращает пустую строку, возвращается "utf-8": например, если текущая локаль 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().

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

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

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