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)¶ Возвращает некоторую языковую информацию в качестве строка. Эта функция доступна не для всех систем, и набор возможных опций может также различаться для разных платформ. Возможным аргументом значения являются числа, для которых в модуле локали доступны символьные константы.
Функция
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 для распознавания положительного ответа на вопрос yes/no.
Примечание
Выражение имеет синтаксис, подходящий для функции
regex()
из библиотеки C, который может отличаться от синтаксиса используемый вre
.
-
locale.
NOEXPR
¶ Получить регулярное выражение, которое может быть используемый с функцией regex (3), чтобы распознать отрицательный ответ на вопрос yes/no.
-
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
, но и список переменных, заданных в качестве параметра envars. Первый найденный элемент будет определен как используемый. envvars по умолчанию задает путь поиска используемый в GNU gettext; он всегда должен содержать имя переменной'LANG'
. Путь поиска GNU gettext содержит'LC_ALL'
,'LC_CTYPE'
,'LANG'
и'LANGUAGE'
в этом порядке.Кроме код
'C'
, язык код соответствует RFC 1766. language code и encoding могут бытьNone
, если их значения не могут быть определены.
-
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 (параметр
-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 имеет значение true (которое не является значением по умолчанию), группирование выполняется с помощью значение. Если 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') # сравнить строку, содержащую умлаут
>>> 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)¶
Модуль локали предоставляет интерфейс gettext библиотеки C в
системах, предоставляющих этот интерфейс. Он состоит из функций gettext()
,
dgettext()
, dcgettext()
, textdomain()
, bindtextdomain()
и bind_textdomain_codeset()
. Они аналогичны
тем же функциям в модуле gettext
, но используют двоичный формат библиотеки C
для каталогов сообщений и алгоритмы поиска библиотеки C для поиска каталогов
сообщений.
Python приложения, как правило, не должны обнаруживать необходимости в
вызове этих функций и вместо этого должны использовать gettext
. Известным
исключением из этого правила являются приложения, связанные с дополнительными
библиотеками C, которые внутренне вызывают gettext()
или dcgettext()
. Для этих
приложений может потребоваться привязка текстового домена, чтобы библиотеки
могли правильно найти свои каталоги сообщений.