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

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

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

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

locale.getencoding()

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

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

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

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

Новая в версии 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 истинно, преобразование использует разделитель тысяч и группирующие символы для валют.

Обрабатывает спецификаторы форматирования, как и в 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 истинно, что является значением по умолчанию. Если 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(), 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