`locale.md`

335 строк · 35.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/library/locale.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 22.2. [`locale`](https://python-all.ru/2.7/library/locale.html#module-locale) – Службы интернационализации89Модуль [`locale`](https://python-all.ru/2.7/library/locale.html#module-locale) предоставляет доступ к базе данных локалей POSIX и её функциональности. Механизм локалей POSIX позволяет разработчикам решать задачи, связанные с культурными особенностями приложения, не требуя от них знания всех тонкостей каждой страны, где выполняется программа.1011Модуль [`locale`](https://python-all.ru/2.7/library/locale.html#module-locale) реализован поверх модуля `_locale`, который, в свою очередь, использует реализацию локали ANSI C, если она доступна.1213Модуль [`locale`](https://python-all.ru/2.7/library/locale.html#module-locale) определяет следующее исключение и функции:1415#### `exception locale.Error`1617Исключение возникает, когда локаль, переданная в [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale), не распознана.1819#### `locale.setlocale(category[, locale])`2021Если передан *locale* и он не равен `None`, то [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale) изменяет настройки локали для категории *category*. Доступные категории перечислены ниже в описании данных. *locale* может быть строкой или итерируемым объектом из двух строк (код языка и кодировка). Если это итерируемый объект, он преобразуется в имя локали с помощью механизма псевдонимов локалей. Пустая строка задаёт настройки пользователя по умолчанию. Если изменение локали не удаётся, вызывается исключение [`Error`](https://python-all.ru/2.7/library/locale.html#locale.Error). В случае успеха возвращается новая настройка локали.2223Если *locale* опущен или равен `None`, возвращается текущая настройка для категории *category*.2425[`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale) не является потокобезопасной на большинстве систем. Приложения обычно начинают с вызова2627```python28import locale29locale.setlocale(locale.LC_ALL, '')30```3132Это устанавливает локаль для всех категорий в пользовательскую настройку по умолчанию (обычно заданную в переменной окружения `LANG`). Если впоследствии локаль не изменять, использование многопоточности не должно вызывать проблем.3334Изменено в версии 2.0: Добавлена поддержка итерируемых значений параметра *locale*.3536#### `locale.localeconv()`3738Возвращает словарь с данными о локальных соглашениях. Ключами этого словаря являются следующие строки:3940| Категория | Клавиша | Значение |41| --- | --- | --- |42| [`LC_NUMERIC`](https://python-all.ru/2.7/library/locale.html#locale.LC_NUMERIC) | `'decimal_point'` | Символ десятичной точки. |43|  | `'grouping'` | Последовательность чисел, указывающая, в каких относительных позициях ожидается `'thousands_sep'`. Если последовательность завершается значением [`CHAR_MAX`](https://python-all.ru/2.7/library/locale.html#locale.CHAR_MAX), дальнейшая группировка не выполняется. Если последовательность завершается значением `0`, размер последней группы используется повторно. |44|  | `'thousands_sep'` | Символ, используемый между группами. |45| [`LC_MONETARY`](https://python-all.ru/2.7/library/locale.html#locale.LC_MONETARY) | `'int_curr_symbol'` | Международный символ валюты. |46|  | `'currency_symbol'` | Локальный символ валюты. |47|  | `'p_cs_precedes/n_cs_precedes'` | Предшествует ли символ валюты значению (для положительных и отрицательных значений соответственно). |48|  | `'p_sep_by_space/n_sep_by_space'` | Отделяется ли символ валюты от значения пробелом (для положительных и отрицательных значений соответственно). |49|  | `'mon_decimal_point'` | Десятичная точка, используемая для денежных значений. |50|  | `'frac_digits'` | Количество дробных цифр, используемых в локальном форматировании денежных значений. |51|  | `'int_frac_digits'` | Количество дробных цифр, используемых в международном форматировании денежных значений. |52|  | `'mon_thousands_sep'` | Разделитель групп, используемый для денежных значений. |53|  | `'mon_grouping'` | Эквивалентно `'grouping'`, используется для денежных значений. |54|  | `'positive_sign'` | Символ, используемый для обозначения положительного денежного значения. |55|  | `'negative_sign'` | Символ, используемый для обозначения отрицательного денежного значения. |56|  | `'p_sign_posn/n_sign_posn'` | Положение знака (для положительных и отрицательных значений соответственно), см. ниже. |5758Все числовые значения можно задать как [`CHAR_MAX`](https://python-all.ru/2.7/library/locale.html#locale.CHAR_MAX), чтобы указать, что в данной локали значение не задано.5960Возможные значения для `'p_sign_posn'` и `'n_sign_posn'` приведены ниже.6162| Значение | Пояснение |63| --- | --- |64| `0` | Валюта и значение заключаются в скобки. |65| `1` | Знак должен стоять перед значением и символом валюты. |66| `2` | Знак должен следовать после значения и символа валюты. |67| `3` | Знак должен стоять непосредственно перед значением. |68| `4` | Знак должен стоять непосредственно после значения. |69| `CHAR_MAX` | В этой локали ничего не указано. |7071#### `locale.nl_langinfo(option)`7273Возвращает строку с информацией, зависящей от локали. Эта функция доступна не на всех системах, и набор возможных опций может различаться на разных платформах. Аргументы – числа, для которых в модуле locale определены символьные константы.7475Функция [`nl_langinfo()`](https://python-all.ru/2.7/library/locale.html#locale.nl_langinfo) принимает один из следующих ключей. Большинство описаний взяты из соответствующих описаний в библиотеке GNU C.7677#### `locale.CODESET`7879Возвращает строку с именем кодировки символов, используемой в выбранной локали.8081#### `locale.D_T_FMT`8283Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) для представления даты и времени с учётом локали.8485#### `locale.D_FMT`8687Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) для представления даты с учётом локали.8889#### `locale.T_FMT`9091Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) для представления времени с учётом локали.9293#### `locale.T_FMT_AMPM`9495Возвращает строку форматирования для [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) для представления времени в формате AM/PM.9697#### `DAY_1 ... DAY_7`9899Возвращает название n-го дня недели.100101> **Примечание**102>103> В соответствии с американским соглашением `DAY_1` – воскресенье, а не международным (ISO 8601), где первый день недели – понедельник.104105#### `ABDAY_1 ... ABDAY_7`106107Возвращает сокращённое название n-го дня недели.108109#### `MON_1 ... MON_12`110111Возвращает название n-го месяца.112113#### `ABMON_1 ... ABMON_12`114115Получить сокращённое название n-го месяца.116117#### `locale.RADIXCHAR`118119Получить символ десятичного разделителя (десятичная точка, десятичная запятая и т.д.).120121#### `locale.THOUSEP`122123Получить символ разделителя тысяч (групп по три цифры).124125#### `locale.YESEXPR`126127Получить регулярное выражение, которое можно использовать с функцией regex для распознавания положительного ответа на вопрос «да/нет».128129> **Примечание**130>131> Выражение имеет синтаксис, подходящий для функции `regex()` из библиотеки C, который может отличаться от синтаксиса, используемого в [`re`](https://python-all.ru/2.7/library/re.html#module-re).132133#### `locale.NOEXPR`134135Возвращает регулярное выражение, которое можно использовать с функцией regex(3) для распознавания отрицательного ответа на вопрос «да/нет».136137#### `locale.CRNCYSTR`138139Получить символ валюты, перед которым стоит «-», если символ должен отображаться перед значением, «+», если символ должен отображаться после значения, или «.», если символ должен заменить десятичный разделитель.140141#### `locale.ERA`142143Возвращает строку, представляющую эру, используемую в текущей локали.144145Большинство локалей не определяют это значение. Примером локали, которая определяет это значение, является японская. В Японии традиционное представление дат включает название эры, соответствующей правлению действующего императора.146147Обычно нет необходимости использовать это значение напрямую. Указание модификатора `E` в строках формата заставляет функцию [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) использовать эту информацию. Формат возвращаемой строки не определён, поэтому не следует полагаться на его вид в разных системах.148149#### `locale.ERA_D_T_FMT`150151Получить строку формата для [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) для представления даты и времени в локализованном формате, основанном на эре.152153#### `locale.ERA_D_FMT`154155Получить строку формата для [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) для представления даты в локализованном формате, основанном на эре.156157#### `locale.ERA_T_FMT`158159Получить строку формата для [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) для представления времени в локализованном формате, основанном на эре.160161#### `locale.ALT_DIGITS`162163Возвращает представление до 100 значений, используемых для обозначения чисел от 0 до 99.164165#### `locale.getdefaultlocale([envvars])`166167Пытается определить настройки локали по умолчанию и возвращает их в виде кортежа вида `(language code, encoding)`.168169Согласно POSIX, программа, которая не вызывала `setlocale(LC_ALL, '')`, работает с переносимой локалью `'C'`. Вызов `setlocale(LC_ALL, '')` позволяет ей использовать локаль по умолчанию, определённую переменной `LANG`. Поскольку мы не хотим вмешиваться в текущую настройку локали, мы имитируем описанное выше поведение.170171Для сохранения совместимости с другими платформами проверяется не только переменная `LANG` , но и список переменных, заданных параметром envvars. Будет использована первая обнаруженная определённая переменная. *envvars* по умолчанию равен пути поиска, используемому в GNU gettext; он всегда должен содержать имя переменной `LANG`. Путь поиска GNU gettext содержит `'LANGUAGE'`, `'LC_ALL'`, `'LC_CTYPE'` и `'LANG'` в указанном порядке.172173За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/2.7/library/locale.html). *Код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.174175Новое в версии 2.0.176177#### `locale.getlocale([category])`178179Возвращает текущую настройку для указанной категории локали в виде последовательности, содержащей *код языка*, *кодировку*. *Категория* может быть одним из значений `LC_*`, кроме [`LC_ALL`](https://python-all.ru/2.7/library/locale.html#locale.LC_ALL). По умолчанию [`LC_CTYPE`](https://python-all.ru/2.7/library/locale.html#locale.LC_CTYPE).180181За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/2.7/library/locale.html). *Код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.182183Новое в версии 2.0.184185#### `locale.getpreferredencoding([do_setlocale])`186187Возвращает кодировку, используемую для текстовых данных, в соответствии с пользовательскими настройками. Пользовательские настройки выражаются по-разному в разных системах и могут быть недоступны программно в некоторых системах, поэтому эта функция возвращает только предположение.188189В некоторых системах необходимо вызвать [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale) для получения пользовательских настроек, поэтому эта функция не является потокобезопасной. Если вызов setlocale не требуется или нежелателен, *do\_setlocale* следует установить в `False`.190191Новое в версии 2.3.192193#### `locale.normalize(localename)`194195Возвращает нормализованный код локали для заданного имени локали. Возвращённый код локали отформатирован для использования с [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale). Если нормализация не удалась, исходное имя возвращается без изменений.196197Если заданная кодировка неизвестна, функция использует кодировку по умолчанию для кода локали, как и [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale).198199Новое в версии 2.0.200201#### `locale.resetlocale([category])`202203Устанавливает локаль для *category* в значение по умолчанию.204205Значение по умолчанию определяется вызовом [`getdefaultlocale()`](https://python-all.ru/2.7/library/locale.html#locale.getdefaultlocale). *category* по умолчанию равен [`LC_ALL`](https://python-all.ru/2.7/library/locale.html#locale.LC_ALL).206207Новое в версии 2.0.208209#### `locale.strcoll(string1, string2)`210211Сравнивает две строки в соответствии с текущей настройкой [`LC_COLLATE`](https://python-all.ru/2.7/library/locale.html#locale.LC_COLLATE). Как и любая другая функция сравнения, возвращает отрицательное, положительное значение или `0` в зависимости от того, располагается ли *string1* до или после *string2* или равна ей.212213#### `locale.strxfrm(string)`214215Преобразует строку в такую, которая может использоваться для встроенной функции [`cmp()`](https://python-all.ru/2.7/library/functions.html#cmp) и при этом возвращает результаты с учётом локали. Эту функцию можно использовать, когда одна и та же строка сравнивается многократно, например при сортировке последовательности строк.216217#### `locale.format(format, val[, grouping[, monetary]])`218219Форматирует число *val* в соответствии с текущей настройкой [`LC_NUMERIC`](https://python-all.ru/2.7/library/locale.html#locale.LC_NUMERIC). Формат следует соглашениям оператора `%`. Для чисел с плавающей запятой десятичная точка изменяется, если это уместно. Если *grouping* равно true, также учитывается группировка.220221Если *monetary* истинно, преобразование использует денежные разделители тысяч и строки группировки.222223Обратите внимание, что эта функция работает только для одного спецификатора %char. Для целых строк формата используйте [`format_string()`](https://python-all.ru/2.7/library/locale.html#locale.format_string).224225Изменено в версии 2.5: Добавлен параметр *monetary*.226227#### `locale.format_string(format, val[, grouping])`228229Обрабатывает спецификаторы форматирования, как в `format % val`, но с учётом текущих настроек локали.230231Новое в версии 2.5.232233#### `locale.currency(val[, symbol[, grouping[, international]]])`234235Форматирует число *val* в соответствии с текущими настройками [`LC_MONETARY`](https://python-all.ru/2.7/library/locale.html#locale.LC_MONETARY).236237Возвращаемая строка включает символ валюты, если *symbol* равно true (значение по умолчанию). Если *grouping* равно true (не по умолчанию), выполняется группировка значения. Если *international* равно true (не по умолчанию), используется международный символ валюты.238239Обратите внимание, что эта функция не работает с локалью 'C', поэтому сначала необходимо установить локаль через [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale).240241Новое в версии 2.5.242243#### `locale.str(float)`244245Форматирует число с плавающей запятой, используя тот же формат, что и встроенная функция `str(float)`, но учитывает десятичную точку.246247#### `locale.atof(string)`248249Преобразует строку в число с плавающей запятой в соответствии с [`LC_NUMERIC`](https://python-all.ru/2.7/library/locale.html#locale.LC_NUMERIC) настройками.250251#### `locale.atoi(string)`252253Преобразует строку в целое число, следуя соглашениям [`LC_NUMERIC`](https://python-all.ru/2.7/library/locale.html#locale.LC_NUMERIC).254255#### `locale.LC_CTYPE`256257Категория локали для функций обработки символов. В зависимости от настроек этой категории функции модуля [`string`](https://python-all.ru/2.7/library/string.html#module-string), работающие с регистром, изменяют своё поведение.258259#### `locale.LC_COLLATE`260261Категория локали для сортировки строк. Функции [`strcoll()`](https://python-all.ru/2.7/library/locale.html#locale.strcoll) и [`strxfrm()`](https://python-all.ru/2.7/library/locale.html#locale.strxfrm) модуля [`locale`](https://python-all.ru/2.7/library/locale.html#module-locale) затрагиваются.262263#### `locale.LC_TIME`264265Категория локали для форматирования времени. Функция [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime) следует этим соглашениям.266267#### `locale.LC_MONETARY`268269Категория локали для форматирования денежных значений. Доступные параметры можно получить из функции [`localeconv()`](https://python-all.ru/2.7/library/locale.html#locale.localeconv).270271#### `locale.LC_MESSAGES`272273Категория локали для отображения сообщений. В настоящее время Python не поддерживает сообщения, учитывающие локаль, для конкретных приложений. Сообщения, выводимые операционной системой, например возвращаемые [`os.strerror()`](https://python-all.ru/2.7/library/os.html#os.strerror), могут затрагиваться этой категорией.274275#### `locale.LC_NUMERIC`276277Категория локали для форматирования чисел. Функции [`format()`](https://python-all.ru/2.7/library/locale.html#locale.format), [`atoi()`](https://python-all.ru/2.7/library/locale.html#locale.atoi), [`atof()`](https://python-all.ru/2.7/library/locale.html#locale.atof) и [`str()`](https://python-all.ru/2.7/library/locale.html#locale.str) модуля [`locale`](https://python-all.ru/2.7/library/locale.html#module-locale) затрагиваются этой категорией. Все остальные операции форматирования чисел не затрагиваются.278279#### `locale.LC_ALL`280281Комбинация всех настроек локали. Если этот флаг используется при изменении локали, предпринимается попытка установить локаль для всех категорий. Если это не удаётся для какой-либо категории, ни одна категория не изменяется. При получении локали с помощью этого флага возвращается строка, указывающая настройки для всех категорий. Эту строку можно впоследствии использовать для восстановления настроек.282283#### `locale.CHAR_MAX`284285Это символическая константа, используемая для различных значений, возвращаемых [`localeconv()`](https://python-all.ru/2.7/library/locale.html#locale.localeconv).286287Пример:288289```python290>>> import locale291>>> loc = locale.getlocale()  # получить текущую локаль292# use German locale; name might vary with platform293>>> locale.setlocale(locale.LC_ALL, 'de_DE')294>>> locale.strcoll('f\xe4n', 'foo')  # сравнить строку, содержащую умлаут295>>> locale.setlocale(locale.LC_ALL, '')   # использовать предпочтительную локаль пользователя296>>> locale.setlocale(locale.LC_ALL, 'C')  # использовать локаль по умолчанию (C)297>>> locale.setlocale(locale.LC_ALL, loc)  # восстановить сохранённую локаль298```299300## 22.2.1. Общая информация, подробности, подсказки, советы и предостережения301302Стандарт C определяет локаль как свойство всей программы, которое может быть относительно дорогим для изменения. Вдобавок некоторые реализации настолько некорректны, что частые смены локали могут приводить к дампам памяти. Это делает локаль несколько болезненной для правильного использования.303304Изначально, при запуске программы, локалью является `C`, независимо от того, какая локаль предпочитается пользователем. Программа должна явно указать, что она хочет использовать предпочитаемые пользователем настройки локали, вызвав `setlocale(LC_ALL, '')`.305306Обычно плохая идея вызывать [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale) в какой-либо библиотечной функции, так как побочный эффект затрагивает всю программу. Сохранение и восстановление почти так же плохо: это дорого и затрагивает другие потоки, которые могут выполняться до восстановления настроек.307308Если при написании модуля общего назначения требуется версия операции, не зависящая от локали, но сама операция зависит от локали (например, [`string.lower()`](https://python-all.ru/2.7/library/string.html#string.lower) или некоторые форматы, используемые с [`time.strftime()`](https://python-all.ru/2.7/library/time.html#time.strftime)), придётся найти способ выполнить её без использования стандартной библиотечной процедуры. Ещё лучше убедить себя, что использование настроек локали допустимо. Только в крайнем случае следует документировать, что модуль несовместим с настройками локали, отличными от `C`.309310Функции преобразования регистра в модуле [`string`](https://python-all.ru/2.7/library/string.html#module-string) зависят от настроек локали. При вызове функции [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale), изменяющей настройки [`LC_CTYPE`](https://python-all.ru/2.7/library/locale.html#locale.LC_CTYPE), переменные `string.lowercase`, `string.uppercase` и `string.letters` пересчитываются. Обратите внимание, что код, использующий эти переменные через '[`from`](https://python-all.ru/2.7/reference/simple_stmts.html#from) … [`import`](https://python-all.ru/2.7/reference/simple_stmts.html#import) …', например `from string import letters`, не зависит от последующих вызовов [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale).311312Единственный способ выполнять числовые операции в соответствии с локалью – использовать специальные функции, определённые в этом модуле: [`atof()`](https://python-all.ru/2.7/library/locale.html#locale.atof), [`atoi()`](https://python-all.ru/2.7/library/locale.html#locale.atoi), [`format()`](https://python-all.ru/2.7/library/locale.html#locale.format), [`str()`](https://python-all.ru/2.7/library/locale.html#locale.str).313314## 22.2.2. Для разработчиков расширений и программ, встраивающих Python315316Модули расширений никогда не должны вызывать [`setlocale()`](https://python-all.ru/2.7/library/locale.html#locale.setlocale), за исключением случаев, когда нужно узнать текущую локаль. Но поскольку возвращаемое значение можно переносимо использовать только для её восстановления, это не очень полезно (кроме, возможно, выяснения, является ли локаль `C` или нет).317318Когда код Python использует модуль [`locale`](https://python-all.ru/2.7/library/locale.html#module-locale) для смены локали, это также влияет на встраиваемое приложение. Если встраиваемое приложение не хочет, чтобы это происходило, оно должно удалить модуль расширения `_locale` (который выполняет всю работу) из таблицы встроенных модулей в файле `config.c`, и убедиться, что модуль `_locale` недоступен как разделяемая библиотека.319320## 22.2.3. Доступ к каталогам сообщений321322#### `locale.gettext(msg)`323324#### `locale.dgettext(domain, msg)`325326#### `locale.dcgettext(domain, msg, category)`327328#### `locale.textdomain(domain)`329330#### `locale.bindtextdomain(domain, dir)`331332Модуль locale предоставляет интерфейс gettext библиотеки C на системах, которые поддерживают этот интерфейс. Он состоит из функций `gettext()`, `dgettext()`, `dcgettext()`, `textdomain()`, `bindtextdomain()`, и `bind_textdomain_codeset()`. Они аналогичны одноимённым функциям в модуле [`gettext`](https://python-all.ru/2.7/library/gettext.html#module-gettext), но используют бинарный формат библиотеки C для каталогов сообщений и алгоритмы поиска библиотеки C для нахождения каталогов сообщений.333334Приложениям Python обычно не требуется вызывать эти функции, и следует использовать [`gettext`](https://python-all.ru/2.7/library/gettext.html#module-gettext) вместо этого. Известным исключением из этого правила являются приложения, которые связываются с дополнительными библиотеками C, внутренне вызывающими `gettext()` или `dcgettext()`. Для таких приложений может потребоваться привязка текстового домена, чтобы библиотеки могли правильно найти свои каталоги сообщений.335