locale — Службы интернационализации

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

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

Модуль 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)

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

Функция 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() из библиотеки 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)

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

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

locale.getpreferredencoding(do_setlocale=True)

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

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

На Android или в режиме UTF-8 (опция -X utf8) всегда возвращайте 'UTF-8', локаль и аргумент do_setlocale игнорируются.

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

locale.normalize(localename)

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

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

locale.resetlocale(category=LC_ALL)

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

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

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 истинно, также учитывается группировка.

Если значение 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 имеет значение истина (что не является значением по умолчанию), группировка выполняется со значением. Если international имеет значение истина (что не является значением по умолчанию), используется международный символ валюты.

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

locale.str(float)

Форматирует число с плавающей запятой, используя тот же формат, что и встроенная функция str(float), но с учётом десятичной точки.

locale.delocalize(string)

Преобразует строку в нормализованную числовую строку в соответствии с настройками LC_NUMERIC.

Добавлено в версии 3.5.

locale.atof(string)

Преобразует строку в число с плавающей запятой в соответствии с настройками LC_NUMERIC.

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()  # получить текущую локаль
# Используется немецкая локаль; имя может варьироваться в зависимости от платформы
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # сравнивает строку, содержащую Umlaut
>>> locale.setlocale(locale.LC_ALL, '')   # использовать предпочтительную локаль пользователя
>>> locale.setlocale(locale.LC_ALL, 'C')  # использовать локаль по умолчанию (C)
>>> locale.setlocale(locale.LC_ALL, loc)  # восстановить сохранённую локаль

Предыстория, детали, подсказки, советы и предостережения

Стандарт C определяет локаль как общепрограммное свойство, изменение которого может быть относительно дорогостоящим. Вдобавок ко всему, некоторые реализации сломаны таким образом, что частые изменения локали могут привести к дампу ядра. Это делает локаль несколько болезненной для правильного использования.

Первоначально, когда программа запускается, локаль по-умолчанию — это C, независимо от предпочтительной локали пользователя. Есть одно исключение: категория LC_CTYPE изменяется при запуске, чтобы установить текущую кодировку локали на предпочитаемую пользователем кодировку локали. Программа должна явно указать, что ей нужны предпочтительные настройки локали пользователя для других категорий, вызвав setlocale(LC_ALL, '').

Как правило, вызывать setlocale() в какой-либо библиотечной подпрограмме — плохая идея, поскольку в качестве побочного эффекта это влияет на всю программу. Сохранение и восстановление почти так же плохо: это дорого и влияет на другие потоки, которые выполняются до того, как настройки были восстановлены.

Если при кодировании модуля для общего использования вам нужна независимая от локали версия операции, на которую влияет локаль (например, определённые форматы, используемые с time.strftime()), вам придется найти способ сделать это без использования стандартной библиотеки. Рутина. Ещё лучше убедить себя, что использование региональных настроек — это нормально. Только в крайнем случае вы должны задокументировать, что ваш модуль не совместим с настройками локали, отличными от C.

Единственный способ выполнять числовые операции в соответствии с локалью — использовать специальные функции, определённые этим модулем: atof(), atoi(), format(), str().

Невозможно выполнить преобразование регистра и классификацию символов в соответствии с локалью. Для текстовых строк (Юникод) они выполняются только в соответствии со значением символа, в то время как для байтовых строк преобразования и классификации выполняются в соответствии со значением ASCII байта и байтами, чей старший бит установлен (т. е. байты, отличные от ASCII) никогда не преобразуются и не считаются частью класса символов, такого как буква или пробел.

Для авторов расширений и программ, встраивающих Python

Модули расширения никогда не должны вызывать setlocale(), кроме как для выяснения текущей локали. Но поскольку возвращаемое значение можно использовать только для его восстановления, это не очень полезно (за исключением, возможно, выяснения, является ли языковой стандарт C).

Когда код Python использует модуль locale для изменения языкового стандарта, это также влияет на встраиваемое приложение. Если встраивающее приложение не хочет, чтобы это произошло, оно должно удалить модуль расширения _locale (который выполняет всю работу) из таблицы встроенных модулей в файле config.c и убедиться, что модуль _locale недоступен, т. к. общая библиотека.

Доступ к каталогам сообщений

locale.gettext(msg)
locale.dgettext(domain, msg)
locale.dcgettext(domain, msg, category)
locale.textdomain(domain)
locale.bindtextdomain(domain, dir)

Модуль locale предоставляет интерфейс gettext библиотеки C в системах, предоставляющих данный интерфейс. Он состоит из функций gettext(), dgettext(), dcgettext(), textdomain(), bindtextdomain() и bind_textdomain_codeset(). Они аналогичны тем же функциям в модуле gettext, но используют двоичный формат библиотеки C для каталогов сообщений и алгоритмы поиска библиотеки C для поиска каталогов сообщений.

Приложения Python обычно не должны вызывать данные функции и вместо этого должны использовать gettext. Известным исключением из этого правила являются приложения, связываемые с дополнительными библиотеками C, которые внутренне вызывают gettext() или dcgettext(). Для данных приложений может потребоваться привязка текстового домена, чтобы библиотеки могли правильно найти свои каталоги сообщений.