`locale.md`

406 строк · 33.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/locale.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `locale` – Интернационализация89Модуль `locale` предоставляет доступ к базе данных локали POSIX и её функциональности. Механизм локали POSIX позволяет программистам решать культурные вопросы в приложении, не требуя знания всех особенностей каждой страны, где выполняется данное ПО.1011Модуль `locale` реализован на основе модуля `_locale`, который, в свою очередь, использует реализацию локали ANSI C, если таковая доступна.1213Модуль `locale` определяет следующие исключение и функции:1415#### `[locale.Error]exception locale.Error`1617Исключение, возникающее при сбое1819[`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale)2021.2223#### `[locale.setlocale]locale.setlocale(category[, locale])`2425Если указан *locale*, он может быть строкой, кортежем вида `(код языка , кодировка)` или `None`. Если это кортеж, он преобразуется в строку с помощью механизма псевдонимов локали. Если *locale* указан и не равен `None`, [`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale) изменяет настройку локали для *category*. Доступные категории перечислены в описании данных ниже. Значение – это имя локали. Пустая строка задаёт настройки пользователя по умолчанию. Если изменение локали завершается с ошибкой, вызывается исключение [`Error`](https://python-all.ru/3.0/library/locale.html#locale.Error). В случае успеха возвращается новая настройка локали.2627Если *locale* опущен или равен `None`, возвращается текущая настройка для *category*.2829[`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale) не является потокобезопасной в большинстве систем. Обычно приложения начинают с вызова3031```python32import locale33locale.setlocale(locale.LC_ALL, '')34```3536Это устанавливает локаль для всех категорий в настройки пользователя по умолчанию (обычно указывается в переменной окружения **LANG**). Если впоследствии локаль не меняется, использование многопоточности не должно вызывать проблем.3738#### `[locale.localeconv]locale.localeconv()`3940Возвращает словарь с данными о локальных соглашениях. Ключами этого словаря являются следующие строки:4142| Категория | Клавиша | Значение |43| --- | --- | --- |44| [`LC_NUMERIC`](https://python-all.ru/3.0/library/locale.html#locale.LC_NUMERIC) | `'decimal_point'` | Символ десятичной точки. |45|  | `'grouping'` | Последовательность чисел, определяющая, на каких относительных позициях ожидается `'thousands_sep'`. Если последовательность заканчивается на [`CHAR_MAX`](https://python-all.ru/3.0/library/locale.html#locale.CHAR_MAX), дальнейшая группировка не выполняется. Если последовательность заканчивается на `0`, последний размер группы повторно используется. |46|  | `'thousands_sep'` | Символ, используемый между группами. |47| [`LC_MONETARY`](https://python-all.ru/3.0/library/locale.html#locale.LC_MONETARY) | `'int_curr_symbol'` | Международный символ валюты. |48|  | `'currency_symbol'` | Локальный символ валюты. |49|  | `'p_cs_precedes/n_cs_precedes'` | Предшествует ли символ валюты значению (для положительных и отрицательных значений соответственно). |50|  | `'p_sep_by_space/n_sep_by_space'` | Отделяется ли символ валюты от значения пробелом (для положительных и отрицательных значений соответственно). |51|  | `'mon_decimal_point'` | Десятичная точка, используемая для денежных значений. |52|  | `'frac_digits'` | Количество дробных цифр, используемых в локальном форматировании денежных значений. |53|  | `'int_frac_digits'` | Количество дробных цифр, используемых в международном форматировании денежных значений. |54|  | `'mon_thousands_sep'` | Разделитель групп, используемый для денежных значений. |55|  | `'mon_grouping'` | Эквивалентно `'grouping'`, используется для денежных значений. |56|  | `'positive_sign'` | Символ, используемый для обозначения положительного денежного значения. |57|  | `'negative_sign'` | Символ, используемый для обозначения отрицательного денежного значения. |58|  | `'p_sign_posn/n_sign_posn'` | Положение знака (для положительных и отрицательных значений соответственно), см. ниже. |5960Все числовые значения можно установить в [`CHAR_MAX`](https://python-all.ru/3.0/library/locale.html#locale.CHAR_MAX), чтобы указать, что в данной локали значение не задано.6162Возможные значения для `'p_sign_posn'` и `'n_sign_posn'` приведены ниже.6364| Значение | Пояснение |65| --- | --- |66| `0` | Валюта и значение заключаются в скобки. |67| `1` | Знак должен стоять перед значением и символом валюты. |68| `2` | Знак должен следовать после значения и символа валюты. |69| `3` | Знак должен стоять непосредственно перед значением. |70| `4` | Знак должен стоять непосредственно после значения. |71| `CHAR_MAX` | В этой локали ничего не указано. |7273#### `[locale.nl_langinfo]locale.nl_langinfo(option)`7475Возвращает строку с информацией, зависящей от локали. Эта функция доступна не во всех системах, и набор возможных опций также может различаться на разных платформах. Допустимые значения аргументов – числа, для которых в модуле locale определены символические константы.7677#### `[locale.getdefaultlocale]locale.getdefaultlocale([envvars])`7879Пытается определить настройки локали по умолчанию и возвращает их в виде кортежа `(язык код, кодировка)`.8081Согласно POSIX, программа, которая не вызывала `setlocale(LC_ALL, '')`, работает с переносимой локалью `'C'`. Вызов `setlocale(LC_ALL, '')` позволяет ей использовать локаль по умолчанию, определяемую переменной **LANG**. Поскольку мы не хотим вмешиваться в текущую настройку локали, мы имитируем такое поведение описанным выше способом.8283Для совместимости с другими платформами проверяется не только **LANG** , но и список переменных, заданный параметром envvars. Будет использована первая обнаруженная определенная переменная. *envvars* по умолчанию равен пути поиска, используемому в GNU gettext; он всегда должен содержать имя переменной `LANG`. Путь поиска GNU gettext включает `'LANGUAGE'`, `'LC_ALL'`, `'LC_CTYPE'` и `'LANG'` в указанном порядке.8485За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.0/library/locale.html). *код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.8687#### `[locale.getlocale]locale.getlocale([category])`8889Возвращает текущую настройку для указанной категории локали в виде последовательности, содержащей *код языка* и *кодировку*. *category* может быть одним из значений `LC_*`, за исключением [`LC_ALL`](https://python-all.ru/3.0/library/locale.html#locale.LC_ALL). По умолчанию он равен [`LC_CTYPE`](https://python-all.ru/3.0/library/locale.html#locale.LC_CTYPE).9091За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.0/library/locale.html). *код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.9293#### `[locale.getpreferredencoding]locale.getpreferredencoding([do_setlocale])`9495Возвращает кодировку, используемую для текстовых данных, в соответствии с пользовательскими настройками. Пользовательские настройки выражаются по-разному в разных системах и могут быть недоступны программно в некоторых системах, поэтому эта функция возвращает только предположение.9697На некоторых системах необходимо вызвать [`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale), чтобы получить пользовательские настройки, поэтому эта функция не является потокобезопасной. Если вызов setlocale не требуется или нежелателен, *do\_setlocale* следует установить в `False`.9899#### `[locale.normalize]locale.normalize(localename)`100101Возвращает нормализованный код локали для указанного имени локали. Возвращаемый код локали отформатирован для использования с [`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale). Если нормализация завершается неудачей, возвращается исходное имя без изменений.102103Если указанная кодировка неизвестна, функция использует кодировку по умолчанию для кода локали, как и [`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale).104105#### `[locale.resetlocale]locale.resetlocale([category])`106107Устанавливает локаль для *category* в значение по умолчанию.108109Настройка по умолчанию определяется вызовом [`getdefaultlocale()`](https://python-all.ru/3.0/library/locale.html#locale.getdefaultlocale). *category* по умолчанию равен [`LC_ALL`](https://python-all.ru/3.0/library/locale.html#locale.LC_ALL).110111#### `[locale.strcoll]locale.strcoll(string1, string2)`112113Сравнивает две строки в соответствии с текущей настройкой114115[`LC_COLLATE`](https://python-all.ru/3.0/library/locale.html#locale.LC_COLLATE)116117. Как и любая другая функция сравнения, возвращает отрицательное или положительное значение, или118119`0`120121, в зависимости от того, сортируется ли122123*string1*124125до или после126127*string2*128129, или равна ей.130131#### `[locale.strxfrm]locale.strxfrm(string)`132133Преобразует строку в строку, пригодную для сравнения с учётом локали. Например,134135`strxfrm(s1) < strxfrm(s2)`136137эквивалентно138139`strcoll(s1, s2) < 0`140141. Эту функцию можно использовать, когда одна и та же строка сравнивается многократно, например, при сортировке последовательности строк.142143#### `[locale.format]locale.format(format, val[, grouping[, monetary]])`144145Форматирует число *val* в соответствии с текущей настройкой [`LC_NUMERIC`](https://python-all.ru/3.0/library/locale.html#locale.LC_NUMERIC). Формат соответствует соглашениям оператора `%`. Для чисел с плавающей точкой десятичная точка изменяется при необходимости. Если *grouping* равно True, также учитывается группировка.146147Если *monetary* истинно, преобразование использует денежные разделители тысяч и строки группировки.148149Обратите внимание, что эта функция работает только для одного спецификатора %char. Для целых строк форматирования используйте [`format_string()`](https://python-all.ru/3.0/library/locale.html#locale.format_string).150151#### `[locale.format_string]locale.format_string(format, val[, grouping])`152153Обрабатывает спецификаторы форматирования, как в154155`format % val`156157, но с учётом текущих настроек локали.158159#### `[locale.currency]locale.currency(val[, symbol[, grouping[, international]]])`160161Форматирует число *val* в соответствии с текущими настройками [`LC_MONETARY`](https://python-all.ru/3.0/library/locale.html#locale.LC_MONETARY).162163Возвращаемая строка включает символ валюты, если *symbol* равно true (значение по умолчанию). Если *grouping* равно true (не по умолчанию), выполняется группировка значения. Если *international* равно true (не по умолчанию), используется международный символ валюты.164165Обратите внимание, что эта функция не работает с локалью 'C', поэтому необходимо сначала установить локаль через [`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale).166167#### `[locale.str]locale.str(float)`168169Форматирует число с плавающей точкой, используя тот же формат, что и встроенная функция170171`str(float)`172173, но с учётом десятичной точки.174175#### `[locale.atof]locale.atof(string)`176177Преобразует строку в число с плавающей точкой, следуя настройкам178179[`LC_NUMERIC`](https://python-all.ru/3.0/library/locale.html#locale.LC_NUMERIC)180181.182183#### `[locale.atoi]locale.atoi(string)`184185Преобразует строку в целое число, следуя соглашениям186187[`LC_NUMERIC`](https://python-all.ru/3.0/library/locale.html#locale.LC_NUMERIC)188189.190191#### `[locale.LC_CTYPE]locale.LC_CTYPE`192193Категория локали для функций, работающих с типами символов. В зависимости от настроек этой категории, функции модуля [`string`](https://python-all.ru/3.0/library/string.html#module-string), отвечающие за изменение регистра, меняют своё поведение.194195#### `[locale.LC_COLLATE]locale.LC_COLLATE`196197Категория локали для сортировки строк. На неё влияют функции198199[`strcoll()`](https://python-all.ru/3.0/library/locale.html#locale.strcoll)200201и202203[`strxfrm()`](https://python-all.ru/3.0/library/locale.html#locale.strxfrm)204205модуля206207`locale`208209.210211#### `[locale.LC_TIME]locale.LC_TIME`212213Категория локали для форматирования времени. Функция214215[`time.strftime()`](https://python-all.ru/3.0/library/time.html#time.strftime)216217следует этим соглашениям.218219#### `[locale.LC_MONETARY]locale.LC_MONETARY`220221Категория локали для форматирования денежных значений. Доступные параметры можно получить из функции222223[`localeconv()`](https://python-all.ru/3.0/library/locale.html#locale.localeconv)224225.226227#### `[locale.LC_MESSAGES]locale.LC_MESSAGES`228229Категория локали для отображения сообщений. В настоящее время Python не поддерживает зависящие от локали сообщения приложений. Сообщения, отображаемые операционной системой, например возвращаемые230231[`os.strerror()`](https://python-all.ru/3.0/library/os.html#os.strerror)232233, могут зависеть от этой категории.234235#### `[locale.LC_NUMERIC]locale.LC_NUMERIC`236237Категория локали для форматирования чисел. На неё влияют функции238239[`format()`](https://python-all.ru/3.0/library/functions.html#format)240241,242243[`atoi()`](https://python-all.ru/3.0/library/locale.html#locale.atoi)244245,246247[`atof()`](https://python-all.ru/3.0/library/locale.html#locale.atof)248249и250251[`str()`](https://python-all.ru/3.0/library/functions.html#str)252253модуля254255`locale`256257. Все остальные операции форматирования чисел на неё не влияют.258259#### `[locale.LC_ALL]locale.LC_ALL`260261Комбинация всех настроек локали. Если этот флаг используется при изменении локали, предпринимается попытка установить локаль для всех категорий. Если это не удаётся для какой-либо категории, ни одна категория не изменяется. При получении локали с помощью этого флага возвращается строка, указывающая настройки для всех категорий. Эту строку можно впоследствии использовать для восстановления настроек.262263#### `[locale.CHAR_MAX]locale.CHAR_MAX`264265Это символическая константа, используемая для различных значений, возвращаемых266267[`localeconv()`](https://python-all.ru/3.0/library/locale.html#locale.localeconv)268269.270271Функция [`nl_langinfo()`](https://python-all.ru/3.0/library/locale.html#locale.nl_langinfo) принимает один из следующих ключей. Большинство описаний взяты из соответствующих описаний в библиотеке GNU C.272273#### `[locale.CODESET]locale.CODESET`274275Возвращает строку с названием кодировки символов, используемой в выбранной локали.276277#### `[locale.D_T_FMT]locale.D_T_FMT`278279Возвращает строку, которую можно использовать как форматную строку для strftime(3), чтобы представить время и дату в соответствии с локалью.280281#### `[locale.D_FMT]locale.D_FMT`282283Возвращает строку, которую можно использовать как форматную строку для strftime(3), чтобы представить дату в соответствии с локалью.284285#### `[locale.T_FMT]locale.T_FMT`286287Возвращает строку, которую можно использовать как форматную строку для strftime(3), чтобы представить время в соответствии с локалью.288289#### `[locale.T_FMT_AMPM]locale.T_FMT_AMPM`290291Возвращаемое значение можно использовать как форматную строку для 'strftime' для представления времени в формате AM/PM.292293#### `DAY_1 ... DAY_7`294295Возвращает название n-го дня недели.296297> **Предупреждение**298>299> Это соответствует соглашению США, согласно которому `DAY_1` – воскресенье, а не международному соглашению (ISO 8601), по которому понедельник – первый день недели.300301#### `ABDAY_1 ... ABDAY_7`302303Возвращает сокращённое название n-го дня недели.304305#### `MON_1 ... MON_12`306307Возвращает название n-го месяца.308309#### `ABMON_1 ... ABMON_12`310311Возвращает сокращённое название n-го месяца.312313#### `[locale.RADIXCHAR]locale.RADIXCHAR`314315Возвращает символ десятичного разделителя (точка, запятая и т.д.).316317#### `[locale.THOUSEP]locale.THOUSEP`318319Возвращает символ разделителя тысяч (групп по три цифры).320321#### `[locale.YESEXPR]locale.YESEXPR`322323Возвращает регулярное выражение, которое можно использовать с функцией regex для распознавания положительного ответа на вопрос «да/нет».324325> **Предупреждение**326>327> Выражение имеет синтаксис, подходящий для функции `regex` из библиотеки C, который может отличаться от синтаксиса, используемого в модуле [`re`](https://python-all.ru/3.0/library/re.html#module-re).328329#### `[locale.NOEXPR]locale.NOEXPR`330331Возвращает регулярное выражение, которое можно использовать с функцией regex(3) для распознавания отрицательного ответа на вопрос «да/нет».332333#### `[locale.CRNCYSTR]locale.CRNCYSTR`334335Возвращает символ валюты с префиксом «-», если символ должен стоять перед значением, «+» – если после значения, или «.», если символ заменяет десятичный разделитель.336337#### `[locale.ERA]locale.ERA`338339Возвращаемое значение представляет эру, используемую в текущей локали.340341Большинство локалей не определяют это значение. Примером локали, которая его определяет, является японская. В Японии традиционное представление дат включает название эры, соответствующей правлению императора.342343Обычно нет необходимости использовать это значение напрямую. Указание модификатора `E` в строках формата заставляет функцию `strftime()` использовать эту информацию. Формат возвращаемой строки не определён, поэтому на разных системах не следует полагаться на его знание.344345#### `[locale.ERA_YEAR]locale.ERA_YEAR`346347Возвращаемое значение указывает год в соответствующей эре локали.348349#### `[locale.ERA_D_T_FMT]locale.ERA_D_T_FMT`350351Это возвращаемое значение можно использовать в качестве строки формата для352353`strftime()`354355для представления дат и времени в локале-зависимом формате на основе эры.356357#### `[locale.ERA_D_FMT]locale.ERA_D_FMT`358359Это возвращаемое значение можно использовать в качестве строки формата для360361`strftime()`362363для представления времени в локале-зависимом формате на основе эры.364365#### `[locale.ALT_DIGITS]locale.ALT_DIGITS`366367Возвращаемое значение представляет собой набор до 100 значений, используемых для представления чисел от 0 до 99.368369Пример:370371```python372>>> import locale373>>> loc = locale.getlocale() # получить текущую локаль374>>> locale.setlocale(locale.LC_ALL, 'de_DE') # использовать немецкую локаль; имя может различаться в зависимости от платформы375>>> locale.strcoll('f\xe4n', 'foo') # сравнить строку, содержащую умлаут376>>> locale.setlocale(locale.LC_ALL, '') # использовать предпочтительную локаль пользователя377>>> locale.setlocale(locale.LC_ALL, 'C') # использовать локаль по умолчанию (C)378>>> locale.setlocale(locale.LC_ALL, loc) # восстановить сохранённую локаль379```380381## Предыстория, подробности, подсказки, советы и предостережения382383Стандарт C определяет локаль как свойство всей программы, которое может быть относительно дорогим для изменения. Вдобавок некоторые реализации настолько некорректны, что частые смены локали могут приводить к дампам памяти. Это делает локаль несколько болезненной для правильного использования.384385Изначально при запуске программы локалью является `C`, независимо от того, какую локаль предпочитает пользователь. Программа должна явно указать, что хочет использовать настройки локали пользователя, вызвав `setlocale(LC_ALL, '')`.386387Как правило, не стоит вызывать [`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale) в какой-либо библиотечной функции, поскольку это побочным образом влияет на всю программу. Сохранение и восстановление почти так же плохо: это дорогостоящая операция, которая влияет на другие потоки, которые могут выполняться до восстановления настроек.388389Если при написании модуля общего назначения требуется независимая от локали версия операции, на которую влияет локаль (например, некоторые форматы, используемые с [`time.strftime()`](https://python-all.ru/3.0/library/time.html#time.strftime)), придётся найти способ сделать это без использования стандартной библиотечной функции. Ещё лучше – убедиться, что использование настроек локали допустимо. И только в крайнем случае следует документировать, что модуль несовместим с настройками локали, отличными от `C`.390391Единственный способ выполнять числовые операции в соответствии с локалью – использовать специальные функции, определённые в этом модуле: [`atof()`](https://python-all.ru/3.0/library/locale.html#locale.atof), [`atoi()`](https://python-all.ru/3.0/library/locale.html#locale.atoi), [`format()`](https://python-all.ru/3.0/library/functions.html#format), [`str()`](https://python-all.ru/3.0/library/functions.html#str).392393Не существует способа выполнять преобразование регистра и классификацию символов в соответствии с локалью. Для текстовых строк (Unicode) они выполняются только по значению символа, тогда как для байтовых строк преобразования и классификации выполняются по значению ASCII байта, а байты, у которых установлен старший бит (т.е. не-ASCII байты), никогда не преобразуются и не считаются частью какого-либо класса символов, такого как буква или пробел.394395## Для разработчиков расширений и программ, встраивающих Python396397Модули расширения никогда не должны вызывать [`setlocale()`](https://python-all.ru/3.0/library/locale.html#locale.setlocale), за исключением случаев, когда нужно узнать текущую локаль. Но поскольку возвращаемое значение можно переносимо использовать только для её восстановления, это не очень полезно (разве что для выяснения, является ли локаль `C`).398399Когда код на Python использует модуль `locale` для смены локали, это также влияет на встраивающее приложение. Если встраивающее приложение не хочет этого, оно должно удалить модуль расширения `_locale` (который выполняет всю работу) из таблицы встроенных модулей в файле `config.c` и убедиться, что модуль `_locale` недоступен в виде общей библиотеки.400401## Доступ к каталогам сообщений402403Модуль locale предоставляет интерфейс gettext библиотеки C в системах, которые поддерживают этот интерфейс. Он состоит из функций `gettext()`, `dgettext()`, `dcgettext()`, `textdomain()`, `bindtextdomain()` и `bind_textdomain_codeset()`. Они аналогичны одноимённым функциям в модуле [`gettext`](https://python-all.ru/3.0/library/gettext.html#module-gettext), но используют двоичный формат каталогов сообщений библиотеки C и её алгоритмы поиска каталогов сообщений.404405Приложениям Python обычно не требуется вызывать эти функции; вместо этого следует использовать [`gettext`](https://python-all.ru/3.0/library/gettext.html#module-gettext). Известным исключением из этого правила являются приложения, которые связываются с дополнительными библиотеками C, внутренне вызывающими `gettext` или `dcgettext()`. Для таких приложений может потребоваться привязать текстовый домен, чтобы библиотеки могли правильно находить свои каталоги сообщений.406