`locale.md`

307 строк · 34.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.3/library/locale.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 23.2. [`locale`](https://python-all.ru/3.3/library/locale.html#module-locale) – Службы интернационализации89Модуль [`locale`](https://python-all.ru/3.3/library/locale.html#module-locale) открывает доступ к базе данных локалей POSIX и соответствующим функциям. Механизм локалей POSIX позволяет программистам решать определённые культурные аспекты в приложении, не требуя от них знания всех особенностей каждой страны, где будет выполняться программа.1011Модуль [`locale`](https://python-all.ru/3.3/library/locale.html#module-locale) реализован поверх модуля `_locale`, который, в свою очередь, использует реализацию локалей ANSI C, если таковая доступна.1213Модуль [`locale`](https://python-all.ru/3.3/library/locale.html#module-locale) определяет следующие исключение и функции:1415#### `exception locale.Error`1617Исключение возбуждается, когда локаль, переданная в [`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale), не распознана.1819#### `locale.setlocale(category, locale=None)`2021Если *locale* указан и не равен `None`, [`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale) изменяет настройку локали для *category*. Доступные категории перечислены в описании данных ниже. *locale* может быть строкой или итерабельным объектом из двух строк (код языка и кодировка). Если это итерабельный объект, он преобразуется в имя локали с помощью механизма псевдонимов локали. Пустая строка задаёт пользовательские настройки по умолчанию. Если изменение локали не удалось, возбуждается исключение [`Error`](https://python-all.ru/3.3/library/locale.html#locale.Error). В случае успеха возвращается новая настройка локали.2223Если *locale* опущен или равен `None`, возвращается текущая настройка для *category*.2425[`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale) не является потокобезопасной на большинстве систем. Приложения обычно начинают с вызова2627```python28import locale29locale.setlocale(locale.LC_ALL, '')30```3132Это устанавливает локаль для всех категорий в пользовательские настройки по умолчанию (обычно задаётся в переменной окружения `LANG`). Если после этого локаль не меняется, использование многопоточности не должно вызывать проблем.3334#### `locale.localeconv()`3536Возвращает словарь с данными о локальных соглашениях. Ключами этого словаря являются следующие строки:3738| Категория | Клавиша | Значение |39| --- | --- | --- |40| [`LC_NUMERIC`](https://python-all.ru/3.3/library/locale.html#locale.LC_NUMERIC) | `'decimal_point'` | Символ десятичной точки. |41|  | `'grouping'` | Последовательность чисел, определяющая, на каких относительных позициях ожидается `'thousands_sep'`. Если последовательность заканчивается на [`CHAR_MAX`](https://python-all.ru/3.3/library/locale.html#locale.CHAR_MAX), дальнейшая группировка не выполняется. Если последовательность заканчивается на `0`, последний размер группы повторно используется. |42|  | `'thousands_sep'` | Символ, используемый между группами. |43| [`LC_MONETARY`](https://python-all.ru/3.3/library/locale.html#locale.LC_MONETARY) | `'int_curr_symbol'` | Международный символ валюты. |44|  | `'currency_symbol'` | Локальный символ валюты. |45|  | `'p_cs_precedes/n_cs_precedes'` | Предшествует ли символ валюты значению (для положительных и отрицательных значений соответственно). |46|  | `'p_sep_by_space/n_sep_by_space'` | Отделяется ли символ валюты от значения пробелом (для положительных и отрицательных значений соответственно). |47|  | `'mon_decimal_point'` | Десятичная точка, используемая для денежных значений. |48|  | `'frac_digits'` | Количество дробных цифр, используемых в локальном форматировании денежных значений. |49|  | `'int_frac_digits'` | Количество дробных цифр, используемых в международном форматировании денежных значений. |50|  | `'mon_thousands_sep'` | Разделитель групп, используемый для денежных значений. |51|  | `'mon_grouping'` | Эквивалентно `'grouping'`, используется для денежных значений. |52|  | `'positive_sign'` | Символ, используемый для обозначения положительного денежного значения. |53|  | `'negative_sign'` | Символ, используемый для обозначения отрицательного денежного значения. |54|  | `'p_sign_posn/n_sign_posn'` | Положение знака (для положительных и отрицательных значений соответственно), см. ниже. |5556Все числовые значения можно установить в [`CHAR_MAX`](https://python-all.ru/3.3/library/locale.html#locale.CHAR_MAX), чтобы указать, что в данной локали значение не задано.5758Возможные значения для `'p_sign_posn'` и `'n_sign_posn'` приведены ниже.5960| Значение | Пояснение |61| --- | --- |62| `0` | Валюта и значение заключаются в скобки. |63| `1` | Знак должен стоять перед значением и символом валюты. |64| `2` | Знак должен следовать после значения и символа валюты. |65| `3` | Знак должен стоять непосредственно перед значением. |66| `4` | Знак должен стоять непосредственно после значения. |67| `CHAR_MAX` | В этой локали ничего не указано. |6869#### `locale.nl_langinfo(option)`7071Возвращает строку с информацией, зависящей от локали. Эта функция доступна не на всех системах, и набор возможных опций может различаться на разных платформах. Аргументы – числа, для которых в модуле locale определены символьные константы.7273Функция [`nl_langinfo()`](https://python-all.ru/3.3/library/locale.html#locale.nl_langinfo) принимает один из следующих ключей. Большинство описаний взято из соответствующих описаний в библиотеке GNU C .7475#### `locale.CODESET`7677Возвращает строку с именем кодировки символов, используемой в выбранной локали.7879#### `locale.D_T_FMT`8081Возвращает строку, которую можно использовать как форматную строку для [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) для представления даты и времени с учётом локали.8283#### `locale.D_FMT`8485Возвращает строку, которую можно использовать как форматную строку для [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) для представления даты с учётом локали.8687#### `locale.T_FMT`8889Возвращает строку, которую можно использовать как форматную строку для [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) для представления времени с учётом локали.9091#### `locale.T_FMT_AMPM`9293Возвращает форматную строку для [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) для представления времени в формате am/pm .9495#### `DAY_1 ... DAY_7`9697Возвращает название n-го дня недели.9899> **Примечание**100>101> Это соответствует соглашению США, по которому `DAY_1` – воскресенье, а не международному соглашению (ISO 8601), согласно которому понедельник – первый день недели.102103#### `ABDAY_1 ... ABDAY_7`104105Возвращает сокращённое название n-го дня недели.106107#### `MON_1 ... MON_12`108109Возвращает название n-го месяца.110111#### `ABMON_1 ... ABMON_12`112113Получить сокращённое название n-го месяца.114115#### `locale.RADIXCHAR`116117Получить символ-разделитель целой и дробной части (десятичная точка, десятичная запятая и т.п.)118119#### `locale.THOUSEP`120121Получить символ разделителя тысяч (групп по три цифры).122123#### `locale.YESEXPR`124125Получить регулярное выражение, которое можно использовать с функцией regex для распознавания положительного ответа на вопрос «да/нет».126127> **Примечание**128>129> Выражение записано в синтаксисе, подходящем для функции `regex()` из библиотеки C, который может отличаться от синтаксиса, используемого в [`re`](https://python-all.ru/3.3/library/re.html#module-re).130131#### `locale.NOEXPR`132133Возвращает регулярное выражение, которое можно использовать с функцией regex(3) для распознавания отрицательного ответа на вопрос «да/нет».134135#### `locale.CRNCYSTR`136137Возвращает символ валюты, перед которым ставится «-», если символ должен отображаться перед значением, «+», если символ должен отображаться после значения, или «.», если символ заменяет десятичный разделитель.138139#### `locale.ERA`140141Возвращает строку, представляющую эру, используемую в текущей локали.142143Большинство локалей не определяют это значение. Примером локали, которая определяет это значение, является японская. В Японии традиционное представление дат включает название эры, соответствующей правлению действующего императора.144145Обычно нет необходимости использовать это значение напрямую. Указание модификатора `E` в форматных строках заставляет функцию [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) использовать эту информацию. Формат возвращаемой строки не задан, поэтому не следует полагаться на его знание в разных системах.146147#### `locale.ERA_D_T_FMT`148149Возвращает форматную строку для [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) для представления даты и времени с учётом локали на основе эры.150151#### `locale.ERA_D_FMT`152153Возвращает форматную строку для [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) для представления даты с учётом локали на основе эры.154155#### `locale.ERA_T_FMT`156157Получить строку формата для [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) для представления времени в формате, учитывающем эру и локаль.158159#### `locale.ALT_DIGITS`160161Возвращает представление до 100 значений, используемых для обозначения чисел от 0 до 99.162163#### `locale.getdefaultlocale([envvars])`164165Пытается определить настройки локали по умолчанию и возвращает их в виде кортежа `(язык код, кодировка)`.166167Согласно POSIX, программа, которая не вызвала `setlocale(LC_ALL, '')`, работает с переносимой локалью `'C'`. Вызов `setlocale(LC_ALL, '')` позволяет ей использовать локаль по умолчанию, заданную переменной `LANG`. Поскольку мы не хотим вмешиваться в текущую настройку локали, мы эмулируем это поведение описанным выше способом.168169Для сохранения совместимости с другими платформами проверяется не только переменная `LANG`, но и список переменных, заданный параметром envvars. Будет использована первая определённая переменная. *envvars* по умолчанию равен пути поиска, используемому в GNU gettext; он всегда должен содержать имя переменной `'LANG'`. Путь поиска GNU gettext содержит `'LC_ALL'`, `'LC_CTYPE'`, `'LANG'` и `'LANGUAGE'`, в указанном порядке.170171За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.3/library/locale.html). *код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.172173#### `locale.getlocale(category=LC_CTYPE)`174175Возвращает текущую настройку для указанной категории локали в виде последовательности, содержащей *код языка* и *кодировку*. *category* может быть одним из значений `LC_*`, за исключением [`LC_ALL`](https://python-all.ru/3.3/library/locale.html#locale.LC_ALL). По умолчанию он равен [`LC_CTYPE`](https://python-all.ru/3.3/library/locale.html#locale.LC_CTYPE).176177За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.3/library/locale.html). *код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.178179#### `locale.getpreferredencoding(do_setlocale=True)`180181Возвращает кодировку, используемую для текстовых данных, в соответствии с пользовательскими настройками. Пользовательские настройки выражаются по-разному в разных системах и могут быть недоступны программно в некоторых системах, поэтому эта функция возвращает только предположение.182183На некоторых системах необходимо вызвать [`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale), чтобы получить пользовательские настройки, поэтому эта функция не является потокобезопасной. Если вызов setlocale не требуется или нежелателен, *do\_setlocale* следует установить в `False`.184185#### `locale.normalize(localename)`186187Возвращает нормализованный код локали для указанного имени локали. Возвращаемый код локали отформатирован для использования с [`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale). Если нормализация завершается неудачей, возвращается исходное имя без изменений.188189Если указанная кодировка неизвестна, функция использует кодировку по умолчанию для кода локали, как и [`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale).190191#### `locale.resetlocale(category=LC_ALL)`192193Устанавливает локаль для *category* в значение по умолчанию.194195Настройка по умолчанию определяется вызовом [`getdefaultlocale()`](https://python-all.ru/3.3/library/locale.html#locale.getdefaultlocale). *category* по умолчанию равен [`LC_ALL`](https://python-all.ru/3.3/library/locale.html#locale.LC_ALL).196197#### `locale.strcoll(string1, string2)`198199Сравнивает две строки в соответствии с текущей настройкой [`LC_COLLATE`](https://python-all.ru/3.3/library/locale.html#locale.LC_COLLATE). Как и любая другая функция сравнения, возвращает отрицательное или положительное значение, или `0`, в зависимости от того, сортируется ли *string1* до или после *string2*, или равна ей.200201#### `locale.strxfrm(string)`202203Преобразует строку в строку, пригодную для сравнения с учётом локали. Например, `strxfrm(s1) < strxfrm(s2)` эквивалентно `strcoll(s1, s2) < 0`. Эту функцию можно использовать, когда одна и та же строка сравнивается многократно, например, при сортировке последовательности строк.204205#### `locale.format(format, val, grouping=False, monetary=False)`206207Форматирует число *val* в соответствии с текущей настройкой [`LC_NUMERIC`](https://python-all.ru/3.3/library/locale.html#locale.LC_NUMERIC). Формат соответствует соглашениям оператора `%`. Для чисел с плавающей точкой десятичная точка изменяется при необходимости. Если *grouping* равно True, также учитывается группировка.208209Если *monetary* истинно, преобразование использует денежные разделители тысяч и строки группировки.210211Обратите внимание, что эта функция работает только для одного спецификатора %char. Для целых строк форматирования используйте [`format_string()`](https://python-all.ru/3.3/library/locale.html#locale.format_string).212213#### `locale.format_string(format, val, grouping=False)`214215Обрабатывает спецификаторы форматирования, как в `format % val`, но с учётом текущих настроек локали.216217#### `locale.currency(val, symbol=True, grouping=False, international=False)`218219Форматирует число *val* в соответствии с текущими настройками [`LC_MONETARY`](https://python-all.ru/3.3/library/locale.html#locale.LC_MONETARY).220221Возвращаемая строка включает символ валюты, если *symbol* равно true (значение по умолчанию). Если *grouping* равно true (не по умолчанию), выполняется группировка значения. Если *international* равно true (не по умолчанию), используется международный символ валюты.222223Обратите внимание, что эта функция не работает с локалью 'C', поэтому необходимо сначала установить локаль через [`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale).224225#### `locale.str(float)`226227Форматирует число с плавающей точкой, используя тот же формат, что и встроенная функция `str(float)`, но с учётом десятичной точки.228229#### `locale.atof(string)`230231Преобразует строку в число с плавающей точкой, следуя настройкам [`LC_NUMERIC`](https://python-all.ru/3.3/library/locale.html#locale.LC_NUMERIC) .232233#### `locale.atoi(string)`234235Преобразует строку в целое число, следуя соглашениям [`LC_NUMERIC`](https://python-all.ru/3.3/library/locale.html#locale.LC_NUMERIC).236237#### `locale.LC_CTYPE`238239Категория локали для функций, работающих с типами символов. В зависимости от настроек этой категории, функции модуля [`string`](https://python-all.ru/3.3/library/string.html#module-string), отвечающие за изменение регистра, меняют своё поведение.240241#### `locale.LC_COLLATE`242243Категория локали для сортировки строк. Затрагиваются функции [`strcoll()`](https://python-all.ru/3.3/library/locale.html#locale.strcoll) и [`strxfrm()`](https://python-all.ru/3.3/library/locale.html#locale.strxfrm) модуля [`locale`](https://python-all.ru/3.3/library/locale.html#module-locale).244245#### `locale.LC_TIME`246247Категория локали для форматирования времени. Функция [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime) следует этим соглашениям.248249#### `locale.LC_MONETARY`250251Категория локали для форматирования денежных значений. Доступные параметры можно получить из функции [`localeconv()`](https://python-all.ru/3.3/library/locale.html#locale.localeconv).252253#### `locale.LC_MESSAGES`254255Категория локали для отображения сообщений. В настоящее время Python не поддерживает зависящие от локали сообщения приложений. Сообщения, отображаемые операционной системой, например возвращаемые [`os.strerror()`](https://python-all.ru/3.3/library/os.html#os.strerror), могут зависеть от этой категории.256257#### `locale.LC_NUMERIC`258259Категория локали для форматирования чисел. Функции [`format()`](https://python-all.ru/3.3/library/locale.html#locale.format), [`atoi()`](https://python-all.ru/3.3/library/locale.html#locale.atoi), [`atof()`](https://python-all.ru/3.3/library/locale.html#locale.atof) и [`str()`](https://python-all.ru/3.3/library/locale.html#locale.str) модуля [`locale`](https://python-all.ru/3.3/library/locale.html#module-locale) зависят от этой категории. Все остальные операции форматирования чисел не зависят.260261#### `locale.LC_ALL`262263Комбинация всех настроек локали. Если этот флаг используется при изменении локали, предпринимается попытка установить локаль для всех категорий. Если это не удаётся для какой-либо категории, ни одна категория не изменяется. При получении локали с помощью этого флага возвращается строка, указывающая настройки для всех категорий. Эту строку можно впоследствии использовать для восстановления настроек.264265#### `locale.CHAR_MAX`266267Это символическая константа, используемая для различных значений, возвращаемых [`localeconv()`](https://python-all.ru/3.3/library/locale.html#locale.localeconv).268269Пример:270271```python272>>> import locale273>>> loc = locale.getlocale() # получить текущую локаль274# use German locale; name might vary with platform275>>> locale.setlocale(locale.LC_ALL, 'de_DE')276>>> locale.strcoll('f\xe4n', 'foo') # сравнить строку, содержащую умлаут277>>> locale.setlocale(locale.LC_ALL, '') # использовать предпочтительную локаль пользователя278>>> locale.setlocale(locale.LC_ALL, 'C') # использовать локаль по умолчанию (C)279>>> locale.setlocale(locale.LC_ALL, loc) # восстановить сохранённую локаль280```281282## 23.2.1. Общие сведения, подробности, подсказки, советы и предостережения283284Стандарт C определяет локаль как свойство всей программы, которое может быть относительно дорогим для изменения. Вдобавок некоторые реализации настолько некорректны, что частые смены локали могут приводить к дампам памяти. Это делает локаль несколько болезненной для правильного использования.285286Изначально при запуске программы локалью является `C`, независимо от предпочитаемой локали пользователя. Есть одно исключение: категория [`LC_CTYPE`](https://python-all.ru/3.3/library/locale.html#locale.LC_CTYPE) изменяется при запуске, чтобы установить текущую кодировку локали в предпочитаемую пользователем кодировку локали. Программа должна явно указать, что хочет использовать предпочитаемые пользователем настройки локали для других категорий, вызвав `setlocale(LC_ALL, '')`.287288Как правило, не стоит вызывать [`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale) в какой-либо библиотечной функции, поскольку это побочным образом влияет на всю программу. Сохранение и восстановление почти так же плохо: это дорогостоящая операция, которая влияет на другие потоки, которые могут выполняться до восстановления настроек.289290Если при написании модуля общего назначения требуется независимая от локали версия операции, на которую влияет локаль (например, некоторые форматы, используемые с [`time.strftime()`](https://python-all.ru/3.3/library/time.html#time.strftime)), придётся найти способ сделать это без использования стандартной библиотечной функции. Ещё лучше – убедиться, что использование настроек локали допустимо. И только в крайнем случае следует документировать, что модуль несовместим с настройками локали, отличными от `C`.291292Единственный способ выполнять числовые операции в соответствии с локалью – использовать специальные функции, определённые в этом модуле: [`atof()`](https://python-all.ru/3.3/library/locale.html#locale.atof), [`atoi()`](https://python-all.ru/3.3/library/locale.html#locale.atoi), [`format()`](https://python-all.ru/3.3/library/locale.html#locale.format), [`str()`](https://python-all.ru/3.3/library/locale.html#locale.str).293294Не существует способа выполнять преобразование регистра и классификацию символов в соответствии с локалью. Для текстовых строк (Unicode) они выполняются только по значению символа, тогда как для байтовых строк преобразования и классификации выполняются по значению ASCII байта, а байты, у которых установлен старший бит (т.е. не-ASCII байты), никогда не преобразуются и не считаются частью какого-либо класса символов, такого как буква или пробел.295296## 23.2.2. Для разработчиков расширений и программ, встраивающих Python297298Модули расширения никогда не должны вызывать [`setlocale()`](https://python-all.ru/3.3/library/locale.html#locale.setlocale), за исключением случаев, когда нужно узнать текущую локаль. Но поскольку возвращаемое значение можно переносимо использовать только для её восстановления, это не очень полезно (разве что для выяснения, является ли локаль `C`).299300Когда код Python использует модуль [`locale`](https://python-all.ru/3.3/library/locale.html#module-locale) для изменения локали, это также влияет на встраивающее приложение. Если встраивающее приложение не хочет, чтобы это происходило, оно должно удалить модуль расширения `_locale` (который выполняет всю работу) из таблицы встроенных модулей в файле `config.c` и убедиться, что модуль `_locale` недоступен как динамическая библиотека.301302## 23.2.3. Доступ к каталогам сообщений303304Модуль locale предоставляет интерфейс gettext библиотеки C в системах, которые поддерживают этот интерфейс. Он состоит из функций [`gettext()`](https://python-all.ru/3.3/library/gettext.html#module-gettext), `dgettext()`, `dcgettext()`, `textdomain()`, `bindtextdomain()`, и `bind_textdomain_codeset()`. Они аналогичны таким же функциям в модуле [`gettext`](https://python-all.ru/3.3/library/gettext.html#module-gettext), но используют бинарный формат каталогов сообщений библиотеки C и алгоритмы поиска каталогов сообщений библиотеки C.305306Приложениям Python обычно не нужно вызывать эти функции, и следует использовать [`gettext`](https://python-all.ru/3.3/library/gettext.html#module-gettext). Известное исключение из этого правила – приложения, которые связываются с дополнительными библиотеками C, внутренне вызывающими `gettext()` или `dcgettext()`. Для таких приложений может потребоваться привязать текстовый домен, чтобы библиотеки могли правильно находить свои каталоги сообщений.307