`locale.md`

317 строк · 34.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.5/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.5/library/locale.html#module-locale) – Службы интернационализации89**Исходный код:** [Lib/locale.py](https://python-all.ru/src/3.5/Lib/locale.py)1011---1213Модуль [`locale`](https://python-all.ru/3.5/library/locale.html#module-locale) предоставляет доступ к базе данных локалей POSIX и её функциональности. Механизм локалей POSIX позволяет разработчикам решать задачи, связанные с культурными особенностями приложения, не требуя от них знания всех тонкостей каждой страны, где выполняется программа.1415Модуль [`locale`](https://python-all.ru/3.5/library/locale.html#module-locale) реализован поверх модуля `_locale`, который, в свою очередь, использует реализацию локали ANSI C, если она доступна.1617Модуль [`locale`](https://python-all.ru/3.5/library/locale.html#module-locale) определяет следующее исключение и функции:1819#### `exception locale.Error`2021Исключение возникает, когда локаль, переданная в [`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale), не распознана.2223#### `locale.setlocale(category, locale=None)`2425Если передан *locale* и он не равен `None`, то [`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale) изменяет настройки локали для категории *category*. Доступные категории перечислены ниже в описании данных. *locale* может быть строкой или итерируемым объектом из двух строк (код языка и кодировка). Если это итерируемый объект, он преобразуется в имя локали с помощью механизма псевдонимов локалей. Пустая строка задаёт настройки пользователя по умолчанию. Если изменение локали не удаётся, вызывается исключение [`Error`](https://python-all.ru/3.5/library/locale.html#locale.Error). В случае успеха возвращается новая настройка локали.2627Если *locale* опущен или равен `None`, возвращается текущая настройка для категории *category*.2829[`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale) не является потокобезопасной на большинстве систем. Приложения обычно начинают с вызова3031```python32import locale33locale.setlocale(locale.LC_ALL, '')34```3536Это устанавливает локаль для всех категорий в пользовательскую настройку по умолчанию (обычно заданную в переменной окружения `LANG`). Если впоследствии локаль не изменять, использование многопоточности не должно вызывать проблем.3738#### `locale.localeconv()`3940Возвращает словарь с данными о локальных соглашениях. Ключами этого словаря являются следующие строки:4142| Категория | Клавиша | Значение |43| --- | --- | --- |44| [`LC_NUMERIC`](https://python-all.ru/3.5/library/locale.html#locale.LC_NUMERIC) | `'decimal_point'` | Символ десятичной точки. |45|  | `'grouping'` | Последовательность чисел, указывающая, в каких относительных позициях ожидается `'thousands_sep'`. Если последовательность завершается значением [`CHAR_MAX`](https://python-all.ru/3.5/library/locale.html#locale.CHAR_MAX), дальнейшая группировка не выполняется. Если последовательность завершается значением `0`, размер последней группы используется повторно. |46|  | `'thousands_sep'` | Символ, используемый между группами. |47| [`LC_MONETARY`](https://python-all.ru/3.5/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.5/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(option)`7475Возвращает строку с информацией, зависящей от локали. Эта функция доступна не на всех системах, и набор возможных опций может различаться на разных платформах. Аргументы – числа, для которых в модуле locale определены символьные константы.7677Функция [`nl_langinfo()`](https://python-all.ru/3.5/library/locale.html#locale.nl_langinfo) принимает один из следующих ключей. Большинство описаний взяты из соответствующих описаний в библиотеке GNU C.7879#### `locale.CODESET`8081Возвращает строку с именем кодировки символов, используемой в выбранной локали.8283#### `locale.D_T_FMT`8485Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) для представления даты и времени с учётом локали.8687#### `locale.D_FMT`8889Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) для представления даты с учётом локали.9091#### `locale.T_FMT`9293Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) для представления времени с учётом локали.9495#### `locale.T_FMT_AMPM`9697Возвращает строку форматирования для [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) для представления времени в формате AM/PM.9899#### `DAY_1 ... DAY_7`100101Возвращает название n-го дня недели.102103> **Примечание**104>105> В соответствии с американским соглашением `DAY_1` – воскресенье, а не международным (ISO 8601), где первый день недели – понедельник.106107#### `ABDAY_1 ... ABDAY_7`108109Возвращает сокращённое название n-го дня недели.110111#### `MON_1 ... MON_12`112113Возвращает название n-го месяца.114115#### `ABMON_1 ... ABMON_12`116117Получить сокращённое название n-го месяца.118119#### `locale.RADIXCHAR`120121Получить символ десятичного разделителя (десятичная точка, десятичная запятая и т.д.).122123#### `locale.THOUSEP`124125Получить символ разделителя тысяч (групп по три цифры).126127#### `locale.YESEXPR`128129Получить регулярное выражение, которое можно использовать с функцией regex для распознавания положительного ответа на вопрос «да/нет».130131> **Примечание**132>133> Выражение имеет синтаксис, подходящий для функции `regex()` из библиотеки C, который может отличаться от синтаксиса, используемого в [`re`](https://python-all.ru/3.5/library/re.html#module-re).134135#### `locale.NOEXPR`136137Возвращает регулярное выражение, которое можно использовать с функцией regex(3) для распознавания отрицательного ответа на вопрос «да/нет».138139#### `locale.CRNCYSTR`140141Получить символ валюты, перед которым стоит «-», если символ должен отображаться перед значением, «+», если символ должен отображаться после значения, или «.», если символ должен заменить десятичный разделитель.142143#### `locale.ERA`144145Возвращает строку, представляющую эру, используемую в текущей локали.146147Большинство локалей не определяют это значение. Примером локали, которая определяет это значение, является японская. В Японии традиционное представление дат включает название эры, соответствующей правлению действующего императора.148149Обычно нет необходимости использовать это значение напрямую. Указание модификатора `E` в строках формата заставляет функцию [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) использовать эту информацию. Формат возвращаемой строки не определён, поэтому не следует полагаться на его вид в разных системах.150151#### `locale.ERA_D_T_FMT`152153Получить строку формата для [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) для представления даты и времени в локализованном формате, основанном на эре.154155#### `locale.ERA_D_FMT`156157Получить строку формата для [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) для представления даты в локализованном формате, основанном на эре.158159#### `locale.ERA_T_FMT`160161Получить строку формата для [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) для представления времени в локализованном формате, основанном на эре.162163#### `locale.ALT_DIGITS`164165Возвращает представление до 100 значений, используемых для обозначения чисел от 0 до 99.166167#### `locale.getdefaultlocale([envvars])`168169Пытается определить настройки локали по умолчанию и возвращает их в виде кортежа вида `(language code, encoding)`.170171Согласно POSIX, программа, которая не вызывала `setlocale(LC_ALL, '')`, работает с переносимой локалью `'C'`. Вызов `setlocale(LC_ALL, '')` позволяет ей использовать локаль по умолчанию, определённую переменной `LANG`. Поскольку мы не хотим вмешиваться в текущую настройку локали, мы имитируем описанное выше поведение.172173Для поддержания совместимости с другими платформами тестируется не только переменная `LANG`, но и список переменных, задаваемый параметром envvars. Первая обнаруженная определённая переменная будет использована. *envvars* по умолчанию равен пути поиска, используемому в GNU gettext; он всегда должен содержать имя переменной `'LANG'`. Путь поиска GNU gettext содержит `'LC_ALL'`, `'LC_CTYPE'`, `'LANG'` и `'LANGUAGE'` в указанном порядке.174175За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.5/library/locale.html). *Код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.176177#### `locale.getlocale(category=LC_CTYPE)`178179Возвращает текущую настройку для указанной категории локали в виде последовательности, содержащей *код языка*, *кодировку*. *Категория* может быть одним из значений `LC_*`, кроме [`LC_ALL`](https://python-all.ru/3.5/library/locale.html#locale.LC_ALL). По умолчанию [`LC_CTYPE`](https://python-all.ru/3.5/library/locale.html#locale.LC_CTYPE).180181За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.5/library/locale.html). *Код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.182183#### `locale.getpreferredencoding(do_setlocale=True)`184185Возвращает кодировку, используемую для текстовых данных, в соответствии с пользовательскими настройками. Пользовательские настройки выражаются по-разному в разных системах и могут быть недоступны программно в некоторых системах, поэтому эта функция возвращает только предположение.186187В некоторых системах необходимо вызвать [`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale) для получения пользовательских настроек, поэтому эта функция не является потокобезопасной. Если вызов setlocale не требуется или нежелателен, *do\_setlocale* следует установить в `False`.188189#### `locale.normalize(localename)`190191Возвращает нормализованный код локали для заданного имени локали. Возвращённый код локали отформатирован для использования с [`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale). Если нормализация не удалась, исходное имя возвращается без изменений.192193Если заданная кодировка неизвестна, функция использует кодировку по умолчанию для кода локали, как и [`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale).194195#### `locale.resetlocale(category=LC_ALL)`196197Устанавливает локаль для *category* в значение по умолчанию.198199Значение по умолчанию определяется вызовом [`getdefaultlocale()`](https://python-all.ru/3.5/library/locale.html#locale.getdefaultlocale). *category* по умолчанию равен [`LC_ALL`](https://python-all.ru/3.5/library/locale.html#locale.LC_ALL).200201#### `locale.strcoll(string1, string2)`202203Сравнивает две строки в соответствии с текущей настройкой [`LC_COLLATE`](https://python-all.ru/3.5/library/locale.html#locale.LC_COLLATE). Как и любая другая функция сравнения, возвращает отрицательное, положительное значение или `0` в зависимости от того, располагается ли *string1* до или после *string2* или равна ей.204205#### `locale.strxfrm(string)`206207Преобразует строку в форму, пригодную для сравнений с учётом локали. Например, `strxfrm(s1) < strxfrm(s2)` эквивалентно `strcoll(s1, s2) < 0`. Эта функция может использоваться, когда одна и та же строка сравнивается многократно, например, при сортировке последовательности строк.208209#### `locale.format(format, val, grouping=False, monetary=False)`210211Форматирует число *val* в соответствии с текущей настройкой [`LC_NUMERIC`](https://python-all.ru/3.5/library/locale.html#locale.LC_NUMERIC). Формат следует соглашениям оператора `%`. Для чисел с плавающей запятой десятичная точка изменяется, если это уместно. Если *grouping* равно true, также учитывается группировка.212213Если *monetary* истинно, преобразование использует денежные разделители тысяч и строки группировки.214215Обратите внимание, что эта функция работает только для одного спецификатора %char. Для целых строк формата используйте [`format_string()`](https://python-all.ru/3.5/library/locale.html#locale.format_string).216217#### `locale.format_string(format, val, grouping=False)`218219Обрабатывает спецификаторы форматирования, как в `format % val`, но с учётом текущих настроек локали.220221#### `locale.currency(val, symbol=True, grouping=False, international=False)`222223Форматирует число *val* в соответствии с текущими настройками [`LC_MONETARY`](https://python-all.ru/3.5/library/locale.html#locale.LC_MONETARY).224225Возвращаемая строка включает символ валюты, если *symbol* равно true (значение по умолчанию). Если *grouping* равно true (не по умолчанию), выполняется группировка значения. Если *international* равно true (не по умолчанию), используется международный символ валюты.226227Обратите внимание, что эта функция не работает с локалью 'C', поэтому сначала необходимо установить локаль через [`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale).228229#### `locale.str(float)`230231Форматирует число с плавающей запятой, используя тот же формат, что и встроенная функция `str(float)`, но учитывает десятичную точку.232233#### `locale.delocalize(string)`234235Преобразует строку в нормализованное строковое представление числа в соответствии с настройками [`LC_NUMERIC`](https://python-all.ru/3.5/library/locale.html#locale.LC_NUMERIC).236237Новое в версии 3.5.238239#### `locale.atof(string)`240241Преобразует строку в число с плавающей запятой в соответствии с [`LC_NUMERIC`](https://python-all.ru/3.5/library/locale.html#locale.LC_NUMERIC) настройками.242243#### `locale.atoi(string)`244245Преобразует строку в целое число, следуя соглашениям [`LC_NUMERIC`](https://python-all.ru/3.5/library/locale.html#locale.LC_NUMERIC).246247#### `locale.LC_CTYPE`248249Категория локали для функций обработки символов. В зависимости от настроек этой категории функции модуля [`string`](https://python-all.ru/3.5/library/string.html#module-string), работающие с регистром, изменяют своё поведение.250251#### `locale.LC_COLLATE`252253Категория локали для сортировки строк. Функции [`strcoll()`](https://python-all.ru/3.5/library/locale.html#locale.strcoll) и [`strxfrm()`](https://python-all.ru/3.5/library/locale.html#locale.strxfrm) модуля [`locale`](https://python-all.ru/3.5/library/locale.html#module-locale) затрагиваются.254255#### `locale.LC_TIME`256257Категория локали для форматирования времени. Функция [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime) следует этим соглашениям.258259#### `locale.LC_MONETARY`260261Категория локали для форматирования денежных значений. Доступные параметры можно получить из функции [`localeconv()`](https://python-all.ru/3.5/library/locale.html#locale.localeconv).262263#### `locale.LC_MESSAGES`264265Категория локали для отображения сообщений. В настоящее время Python не поддерживает сообщения, учитывающие локаль, для конкретных приложений. Сообщения, выводимые операционной системой, например возвращаемые [`os.strerror()`](https://python-all.ru/3.5/library/os.html#os.strerror), могут затрагиваться этой категорией.266267#### `locale.LC_NUMERIC`268269Категория локали для форматирования чисел. Функции [`format()`](https://python-all.ru/3.5/library/locale.html#locale.format), [`atoi()`](https://python-all.ru/3.5/library/locale.html#locale.atoi), [`atof()`](https://python-all.ru/3.5/library/locale.html#locale.atof) и [`str()`](https://python-all.ru/3.5/library/locale.html#locale.str) модуля [`locale`](https://python-all.ru/3.5/library/locale.html#module-locale) затрагиваются этой категорией. Все остальные операции форматирования чисел не затрагиваются.270271#### `locale.LC_ALL`272273Комбинация всех настроек локали. Если этот флаг используется при изменении локали, предпринимается попытка установить локаль для всех категорий. Если это не удаётся для какой-либо категории, ни одна категория не изменяется. При получении локали с помощью этого флага возвращается строка, указывающая настройки для всех категорий. Эту строку можно впоследствии использовать для восстановления настроек.274275#### `locale.CHAR_MAX`276277Это символическая константа, используемая для различных значений, возвращаемых [`localeconv()`](https://python-all.ru/3.5/library/locale.html#locale.localeconv).278279Пример:280281```python282>>> import locale283>>> loc = locale.getlocale()  # получить текущую локаль284# use German locale; name might vary with platform285>>> locale.setlocale(locale.LC_ALL, 'de_DE')286>>> locale.strcoll('f\xe4n', 'foo')  # сравнить строку, содержащую умлаут287>>> locale.setlocale(locale.LC_ALL, '')   # использовать предпочтительную локаль пользователя288>>> locale.setlocale(locale.LC_ALL, 'C')  # использовать локаль по умолчанию (C)289>>> locale.setlocale(locale.LC_ALL, loc)  # восстановить сохранённую локаль290```291292## 23.2.1. Общие сведения, подробности, подсказки, советы и предостережения293294Стандарт C определяет локаль как свойство всей программы, которое может быть относительно дорогим для изменения. Вдобавок некоторые реализации настолько некорректны, что частые смены локали могут приводить к дампам памяти. Это делает локаль несколько болезненной для правильного использования.295296Изначально при запуске программы локалью является `C`, независимо от того, какая локаль предпочтительна для пользователя. Есть одно исключение: категория [`LC_CTYPE`](https://python-all.ru/3.5/library/locale.html#locale.LC_CTYPE) изменяется при запуске, чтобы установить текущую кодировку локали на предпочтительную кодировку локали пользователя. Программа должна явно указать, что она хочет использовать предпочтительные настройки локали пользователя для других категорий, вызвав `setlocale(LC_ALL, '')`.297298Обычно плохая идея вызывать [`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale) в какой-либо библиотечной функции, так как побочный эффект затрагивает всю программу. Сохранение и восстановление почти так же плохо: это дорого и затрагивает другие потоки, которые могут выполняться до восстановления настроек.299300Если при написании модуля общего назначения требуется независимая от локали версия операции, на которую влияет локаль (например, определённые форматы, используемые с [`time.strftime()`](https://python-all.ru/3.5/library/time.html#time.strftime)), необходимо найти способ сделать это без использования процедур из стандартной библиотеки. Ещё лучше убедиться, что использование настроек локали допустимо. И только в крайнем случае стоит документировать, что модуль несовместим с настройками локали, отличными от `C`.301302Единственный способ выполнять числовые операции в соответствии с локалью – использовать специальные функции, определённые в этом модуле: [`atof()`](https://python-all.ru/3.5/library/locale.html#locale.atof), [`atoi()`](https://python-all.ru/3.5/library/locale.html#locale.atoi), [`format()`](https://python-all.ru/3.5/library/locale.html#locale.format), [`str()`](https://python-all.ru/3.5/library/locale.html#locale.str).303304Не существует способа выполнять преобразование регистра и классификацию символов в соответствии с локалью. Для текстовых строк (Unicode) они выполняются только по значению символа, тогда как для байтовых строк преобразования и классификации выполняются по значению ASCII байта, а байты, у которых установлен старший бит (т.е. не-ASCII байты), никогда не преобразуются и не считаются частью какого-либо класса символов, такого как буква или пробел.305306## 23.2.2. Для разработчиков расширений и программ, встраивающих Python307308Модули расширений никогда не должны вызывать [`setlocale()`](https://python-all.ru/3.5/library/locale.html#locale.setlocale), за исключением случаев, когда нужно узнать текущую локаль. Но поскольку возвращаемое значение можно переносимо использовать только для её восстановления, это не очень полезно (кроме, возможно, выяснения, является ли локаль `C` или нет).309310Когда код Python использует модуль [`locale`](https://python-all.ru/3.5/library/locale.html#module-locale) для смены локали, это также влияет на встраиваемое приложение. Если встраиваемое приложение не хочет, чтобы это происходило, оно должно удалить модуль расширения `_locale` (который выполняет всю работу) из таблицы встроенных модулей в файле `config.c`, и убедиться, что модуль `_locale` недоступен как разделяемая библиотека.311312## 23.2.3. Доступ к каталогам сообщений313314Модуль locale предоставляет интерфейс gettext библиотеки C на системах, которые поддерживают этот интерфейс. Он состоит из функций [`gettext()`](https://python-all.ru/3.5/library/gettext.html#module-gettext), `dgettext()`, `dcgettext()`, `textdomain()`, `bindtextdomain()`, и `bind_textdomain_codeset()`. Они аналогичны одноимённым функциям в модуле [`gettext`](https://python-all.ru/3.5/library/gettext.html#module-gettext), но используют бинарный формат библиотеки C для каталогов сообщений и алгоритмы поиска библиотеки C для нахождения каталогов сообщений.315316Приложениям Python обычно не требуется вызывать эти функции, и следует использовать [`gettext`](https://python-all.ru/3.5/library/gettext.html#module-gettext) вместо этого. Известным исключением из этого правила являются приложения, которые связываются с дополнительными библиотеками C, внутренне вызывающими `gettext()` или `dcgettext()`. Для таких приложений может потребоваться привязка текстового домена, чтобы библиотеки могли правильно найти свои каталоги сообщений.317