locale — Услуги по интернационализации¶

Исходный код: Lib/locale.py.

Модуль locale открывает доступ к базе данных и функциональности POSIX locale. Механизм POSIX locale позволяет программистам решать определенные культурные вопросы в приложении, не требуя от программиста знания всех особенностей каждой страны, где выполняется программа.

Модуль locale реализован поверх модуля _locale, который в свою очередь использует реализацию локали ANSI C, если она доступна.

Модуль locale определяет следующие исключения и функции:

exception locale.Error¶

Исключение, возникающее, когда локаль, переданная в setlocale(), не распознана.

locale.setlocale(category, locale=None)¶

Если задана locale, а не None, setlocale() изменяет настройки локали для категории. Доступные категории перечислены в описании данных ниже. 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 для распознавания положительного ответа на вопрос «да/нет».

Примечание

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

locale.NOEXPR¶

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

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¶

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

locale.getlocale(category=LC_CTYPE)¶

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

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

locale.getpreferredencoding(do_setlocale=True)¶

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

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

На Android или если включен Python UTF-8 Mode, всегда возвращается 'UTF-8', locale encoding и аргумент do_setlocale игнорируются.

Python preinitialization настраивает локаль LC_CTYPE. См. также filesystem encoding and error handler.

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

locale.normalize(localename)¶

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

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

locale.resetlocale(category=LC_ALL)¶

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

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

locale.strcoll(string1, string2)¶

Сравнивает две строки в соответствии с текущей настройкой LC_COLLATE. Как и любая другая функция сравнения, возвращает отрицательное, или положительное значение, или 0, в зависимости от того, располагается ли строка1 перед или после строки2 или равна ей.

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.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 равно 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¶

Категория локали для функций символьного типа. В зависимости от настроек этой категории, функции модуля string, работающие с регистром, меняют свое поведение.

locale.LC_COLLATE¶

Категория локали для сортировки строк. Затронуты функции strcoll() и strxfrm() модуля locale.

locale.LC_TIME¶

Категория локали для форматирования времени. Функция time.strftime() следует этим соглашениям.

locale.LC_MONETARY¶

Категория локали для форматирования денежных значений. Доступные опции можно получить из функции localeconv().

locale.LC_MESSAGES¶

Категория локали для отображения сообщений. В настоящее время Python не поддерживает сообщения с учетом локали для конкретного приложения. Сообщения, отображаемые операционной системой, например, сообщения, возвращаемые командой os.strerror(), могут быть затронуты этой категорией.

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