locale – Службы интернационализации¶locale – Internationalization services

Исходный код: 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 может быть строкой string или парой – кодом языка и кодировкой. Пустая строка задает пользовательские настройки по умолчанию. Если изменение локали не удалось, вызывается исключение Error. В случае успеха возвращается новая настройка локали.

Если locale является парой, она преобразуется в имя локали с помощью механизма псевдонимов локалей. Код языка имеет тот же формат, что и имя локали, но без кодировки и модификатора @. Код языка и кодировка могут быть None.

Если locale опущен или равен None, возвращается текущая настройка для категории category.

Пример:

>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL)  # получить текущую локаль
# use German locale; name and availability varies with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
>>> locale.strcoll('f\xe4n', 'foo')  # сравнить строку, содержащую умлаут
>>> locale.setlocale(locale.LC_ALL, '')   # использовать предпочтительную локаль пользователя
>>> locale.setlocale(locale.LC_ALL, 'C')  # использовать локаль по умолчанию (C)
>>> locale.setlocale(locale.LC_ALL, loc)  # восстановить сохранённую локаль

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

Функция временно устанавливает локаль LC_CTYPE на локаль категории, определяющей запрашиваемое значение (LC_TIME, LC_NUMERIC, LC_MONETARY или LC_MESSAGES), если локали различаются и результирующая строка не является ASCII. Это временное изменение влияет на другие потоки.

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

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' в указанном порядке.

Код языка имеет тот же формат, что и имя локали, но без кодировки и модификатора @. Код языка и кодировка могут быть равны None, если их значения не удаётся определить. Локаль «C» представляется как (None, None).

locale.getlocale(category=LC_CTYPE)¶

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

Код языка имеет тот же формат, что и имя локали, но без кодировки и модификатора @. Код языка и кодировка могут быть равны None, если их значения не удаётся определить. Локаль «C» представляется как (None, 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.

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.

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

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¶

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

  language ["_" territory] ["." charset] ["@" modifier]

  language ["-" script] ["-" territory] ["." charset]
  language ["-" script] "-" territory "-" modifier

  language ["_" territory] ["." charset]