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

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

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

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

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

locale.getlocale(category=LC_CTYPE)

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

За исключением кода 'C', код языка соответствует RFC 1766. Значения language code и encoding могут быть 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.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.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

Категория локали для функций, работающих с типами символов. Важнее всего то, что эта категория определяет кодировку текста, то есть способ интерпретации байтов как кодовых точек 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(), 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