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

Источник: Lib/locale.py

---

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

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

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

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)

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

Получите текущее значение locale encoding:

• В Android и VxWorks возвращается "utf-8".

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

• В Windows верните кодовую страницу ANSI.

Параметр Python preinitialization задает локаль LC_CTYPE. См. также filesystem encoding and error handler.

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

Added in version 3.11.

locale.normalize(localename)

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

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

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: Добавлен параметр с ключевым словом монетарный.

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.

Added in version 3.5.

locale.localize(string, grouping=False, monetary=False)

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

Added in version 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

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

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

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

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

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

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

Не существует способа выполнить преобразование регистра и классификацию символов в соответствии с локалью. Для текстовых строк (Unicode) они выполняются только в соответствии со значением символа, в то время как для байтовых строк преобразования и классификация выполняются в соответствии со значением 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.bind_textdomain_codeset(domain, codeset)

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

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