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

Получает регулярное выражение, которое можно использовать с функцией 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

Получает представление значений от 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 в случае невозможности их определения.

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

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

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

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

locale.getencoding()

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

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

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

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

Добавлена в версии 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

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

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