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

Исходный код: Lib/locale.py

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

Модуль 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, ''), запускается с использованием языкового стандарта portable '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.

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

locale.normalize(localename)¶

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

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

locale.resetlocale(category=LC_ALL)¶

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

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

Утратил актуальность с версии 3.11, будет удален в версии 3.13.

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. Формат соответствует условным обозначениям оператора %. Для значений с плавающей запятой при необходимости изменяется десятичная точка. Если группировка равна True, то также учитывается группировка.

Если значение monetary равно true, то при преобразовании используется разделитель денежных тысяч и группирующие строки.

Обрабатывает спецификаторы форматирования, как в 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 равно true, что является значением по умолчанию. Если значение 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¶

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