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 locale, если локали отличаются, а числовые или денежные строки не являются ASCII. Это временное изменение затрагивает и другие потоки.

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

locale.nl_langinfo(option)

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

Функция nl_langinfo() принимает один из следующих ключей. Большинство описаний взяты из соответствующего описания в GNU C library.

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 в формате, специфичном для локали. В большинстве локалей эта строка пустая.

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