`locale.md`

427 строк · 33.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/locale.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 22.2. `locale` – Службы интернационализации89Модуль `locale` предоставляет доступ к базе данных локали POSIX и её функциональности. Механизм локали POSIX позволяет программистам решать культурные вопросы в приложении, не требуя знания всех особенностей каждой страны, где выполняется данное ПО.1011Модуль `locale` реализован на основе модуля `_locale`, который, в свою очередь, использует реализацию локали ANSI C, если таковая доступна.1213Модуль `locale` определяет следующие исключение и функции:1415#### `exception locale.Error`1617Исключение, возникающее при сбое1819[`setlocale()`](https://python-all.ru/3.1/library/locale.html#locale.setlocale)2021.2223#### `locale.setlocale(category, locale=None)`2425Если указан *locale*, он может быть строкой, кортежем вида `(код языка , кодировка)` или `None`. Если это кортеж, он преобразуется в строку с помощью механизма псевдонимов локали. Если *locale* указан и не равен `None`, [`setlocale()`](https://python-all.ru/3.1/library/locale.html#locale.setlocale) изменяет настройку локали для *category*. Доступные категории перечислены в описании данных ниже. Значение – это имя локали. Пустая строка задаёт настройки пользователя по умолчанию. Если изменение локали завершается с ошибкой, вызывается исключение [`Error`](https://python-all.ru/3.1/library/locale.html#locale.Error). В случае успеха возвращается новая настройка локали.2627Если *locale* опущен или равен `None`, возвращается текущая настройка для *category*.2829[`setlocale()`](https://python-all.ru/3.1/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.1/library/locale.html#locale.LC_NUMERIC) | `'decimal_point'` | Символ десятичной точки. |45|  | `'grouping'` | Последовательность чисел, определяющая, на каких относительных позициях ожидается `'thousands_sep'`. Если последовательность заканчивается на [`CHAR_MAX`](https://python-all.ru/3.1/library/locale.html#locale.CHAR_MAX), дальнейшая группировка не выполняется. Если последовательность заканчивается на `0`, последний размер группы повторно используется. |46|  | `'thousands_sep'` | Символ, используемый между группами. |47| [`LC_MONETARY`](https://python-all.ru/3.1/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.1/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.1/library/locale.html#locale.nl_langinfo) принимает один из следующих ключей. Большинство описаний взято из соответствующих описаний в библиотеке GNU C .7879#### `locale.CODESET`8081Возвращает строку с именем кодировки символов, используемой в выбранной локали.8283#### `locale.D_T_FMT`8485Возвращает строку, которая может использоваться как строка формата для8687`strftime()`8889для представления даты и времени в соответствии с локалью.9091#### `locale.D_FMT`9293Возвращает строку, которую можно использовать в качестве форматной строки для9495`strftime()`9697для представления даты с учётом локали.9899#### `locale.T_FMT`100101Возвращает строку, которую можно использовать в качестве форматной строки для102103`strftime()`104105для представления времени с учётом локали.106107#### `locale.T_FMT_AMPM`108109Возвращает форматную строку для110111`strftime()`112113для представления времени в формате am/pm.114115#### `DAY_1 ... DAY_7`116117Возвращает название n-го дня недели.118119> **Примечание**120>121> Это соответствует соглашению США, по которому `DAY_1` – воскресенье, а не международному соглашению (ISO 8601), согласно которому понедельник – первый день недели.122123#### `ABDAY_1 ... ABDAY_7`124125Возвращает сокращённое название n-го дня недели.126127#### `MON_1 ... MON_12`128129Возвращает название n-го месяца.130131#### `ABMON_1 ... ABMON_12`132133Получить сокращённое название n-го месяца.134135#### `locale.RADIXCHAR`136137Получить символ-разделитель целой и дробной части (десятичная точка, десятичная запятая и т.п.)138139#### `locale.THOUSEP`140141Получить символ разделителя тысяч (групп по три цифры).142143#### `locale.YESEXPR`144145Получить регулярное выражение, которое можно использовать с функцией regex для распознавания положительного ответа на вопрос «да/нет».146147> **Примечание**148>149> Выражение записано в синтаксисе, подходящем для функции `regex()` из библиотеки C, который может отличаться от синтаксиса, используемого в [`re`](https://python-all.ru/3.1/library/re.html#module-re).150151#### `locale.NOEXPR`152153Возвращает регулярное выражение, которое можно использовать с функцией regex(3) для распознавания отрицательного ответа на вопрос «да/нет».154155#### `locale.CRNCYSTR`156157Получить символ валюты, перед которым стоит «-», если символ должен отображаться перед значением, «+», если символ должен отображаться после значения, или «.», если символ должен заменить десятичный разделитель.158159#### `locale.ERA`160161Возвращает строку, представляющую эру, используемую в текущей локали.162163Большинство локалей не определяют это значение. Примером локали, которая определяет это значение, является японская. В Японии традиционное представление дат включает название эры, соответствующей правлению действующего императора.164165Обычно нет необходимости использовать это значение напрямую. Указание модификатора `E` в форматных строках приводит к тому, что функция `strftime()` использует эту информацию. Формат возвращаемой строки не определён, поэтому не следует рассчитывать на его одинаковое понимание на разных системах.166167#### `locale.ERA_D_T_FMT`168169Возвращает форматную строку для170171`strftime()`172173для представления даты и времени с учётом локали на основе эры.174175#### `locale.ERA_D_FMT`176177Возвращает форматную строку для178179`strftime()`180181для представления даты с учётом локали на основе эры.182183#### `locale.ERA_T_FMT`184185Возвращает форматную строку для186187`strftime()`188189для представления времени с учётом локали на основе эры.190191#### `locale.ALT_DIGITS`192193Возвращает представление до 100 значений, используемых для обозначения чисел от 0 до 99.194195#### `locale.getdefaultlocale([envvars])`196197Пытается определить настройки локали по умолчанию и возвращает их в виде кортежа `(язык код, кодировка)`.198199Согласно POSIX, программа, которая не вызывала `setlocale(LC_ALL, '')`, работает с переносимой локалью `'C'`. Вызов `setlocale(LC_ALL, '')` позволяет ей использовать локаль по умолчанию, определяемую переменной **LANG**. Поскольку мы не хотим вмешиваться в текущую настройку локали, мы имитируем такое поведение описанным выше способом.200201Для поддержания совместимости с другими платформами проверяется не только переменная **LANG**, но и список переменных, указанных в параметре envvars. Будет использована первая обнаруженная определённая переменная. *envvars* по умолчанию соответствует пути поиска, используемому в GNU gettext; он всегда должен содержать имя переменной `'LANG'`. Путь поиска GNU gettext содержит `'LC_ALL'`, `'LC_CTYPE'`, `'LANG'` и `'LANGUAGE'`, в указанном порядке.202203За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.1/library/locale.html). *код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.204205#### `locale.getlocale(category=LC_CTYPE)`206207Возвращает текущую настройку для указанной категории локали в виде последовательности, содержащей *код языка* и *кодировку*. *category* может быть одним из значений `LC_*`, за исключением [`LC_ALL`](https://python-all.ru/3.1/library/locale.html#locale.LC_ALL). По умолчанию он равен [`LC_CTYPE`](https://python-all.ru/3.1/library/locale.html#locale.LC_CTYPE).208209За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.1/library/locale.html). *код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить.210211#### `locale.getpreferredencoding(do_setlocale=True)`212213Возвращает кодировку, используемую для текстовых данных, в соответствии с пользовательскими настройками. Пользовательские настройки выражаются по-разному в разных системах и могут быть недоступны программно в некоторых системах, поэтому эта функция возвращает только предположение.214215На некоторых системах необходимо вызвать [`setlocale()`](https://python-all.ru/3.1/library/locale.html#locale.setlocale), чтобы получить пользовательские настройки, поэтому эта функция не является потокобезопасной. Если вызов setlocale не требуется или нежелателен, *do\_setlocale* следует установить в `False`.216217#### `locale.normalize(localename)`218219Возвращает нормализованный код локали для указанного имени локали. Возвращаемый код локали отформатирован для использования с [`setlocale()`](https://python-all.ru/3.1/library/locale.html#locale.setlocale). Если нормализация завершается неудачей, возвращается исходное имя без изменений.220221Если указанная кодировка неизвестна, функция использует кодировку по умолчанию для кода локали, как и [`setlocale()`](https://python-all.ru/3.1/library/locale.html#locale.setlocale).222223#### `locale.resetlocale(category=LC_ALL)`224225Устанавливает локаль для *category* в значение по умолчанию.226227Настройка по умолчанию определяется вызовом [`getdefaultlocale()`](https://python-all.ru/3.1/library/locale.html#locale.getdefaultlocale). *category* по умолчанию равен [`LC_ALL`](https://python-all.ru/3.1/library/locale.html#locale.LC_ALL).228229#### `locale.strcoll(string1, string2)`230231Сравнивает две строки в соответствии с текущей настройкой232233[`LC_COLLATE`](https://python-all.ru/3.1/library/locale.html#locale.LC_COLLATE)234235. Как и любая другая функция сравнения, возвращает отрицательное или положительное значение, или236237`0`238239, в зависимости от того, сортируется ли240241*string1*242243до или после244245*string2*246247, или равна ей.248249#### `locale.strxfrm(string)`250251Преобразует строку в строку, пригодную для сравнения с учётом локали. Например,252253`strxfrm(s1) < strxfrm(s2)`254255эквивалентно256257`strcoll(s1, s2) < 0`258259. Эту функцию можно использовать, когда одна и та же строка сравнивается многократно, например, при сортировке последовательности строк.260261#### `locale.format(format, val, grouping=False, monetary=False)`262263Форматирует число *val* в соответствии с текущей настройкой [`LC_NUMERIC`](https://python-all.ru/3.1/library/locale.html#locale.LC_NUMERIC). Формат соответствует соглашениям оператора `%`. Для чисел с плавающей точкой десятичная точка изменяется при необходимости. Если *grouping* равно True, также учитывается группировка.264265Если *monetary* истинно, преобразование использует денежные разделители тысяч и строки группировки.266267Обратите внимание, что эта функция работает только для одного спецификатора %char. Для целых строк форматирования используйте [`format_string()`](https://python-all.ru/3.1/library/locale.html#locale.format_string).268269#### `locale.format_string(format, val, grouping=False)`270271Обрабатывает спецификаторы форматирования, как в272273`format % val`274275, но с учётом текущих настроек локали.276277#### `locale.currency(val, symbol=True, grouping=False, international=False)`278279Форматирует число *val* в соответствии с текущими настройками [`LC_MONETARY`](https://python-all.ru/3.1/library/locale.html#locale.LC_MONETARY).280281Возвращаемая строка включает символ валюты, если *symbol* равно true (значение по умолчанию). Если *grouping* равно true (не по умолчанию), выполняется группировка значения. Если *international* равно true (не по умолчанию), используется международный символ валюты.282283Обратите внимание, что эта функция не работает с локалью 'C', поэтому необходимо сначала установить локаль через [`setlocale()`](https://python-all.ru/3.1/library/locale.html#locale.setlocale).284285#### `locale.str(float)`286287Форматирует число с плавающей точкой, используя тот же формат, что и встроенная функция288289`str(float)`290291, но с учётом десятичной точки.292293#### `locale.atof(string)`294295Преобразует строку в число с плавающей точкой, следуя настройкам296297[`LC_NUMERIC`](https://python-all.ru/3.1/library/locale.html#locale.LC_NUMERIC)298299.300301#### `locale.atoi(string)`302303Преобразует строку в целое число, следуя соглашениям304305[`LC_NUMERIC`](https://python-all.ru/3.1/library/locale.html#locale.LC_NUMERIC)306307.308309#### `locale.LC_CTYPE`310311Категория локали для функций, работающих с типами символов. В зависимости от настроек этой категории, функции модуля [`string`](https://python-all.ru/3.1/library/string.html#module-string), отвечающие за изменение регистра, меняют своё поведение.312313#### `locale.LC_COLLATE`314315Категория локали для сортировки строк. На неё влияют функции316317[`strcoll()`](https://python-all.ru/3.1/library/locale.html#locale.strcoll)318319и320321[`strxfrm()`](https://python-all.ru/3.1/library/locale.html#locale.strxfrm)322323модуля324325`locale`326327.328329#### `locale.LC_TIME`330331Категория локали для форматирования времени. Функция332333[`time.strftime()`](https://python-all.ru/3.1/library/time.html#time.strftime)334335следует этим соглашениям.336337#### `locale.LC_MONETARY`338339Категория локали для форматирования денежных значений. Доступные параметры можно получить из функции340341[`localeconv()`](https://python-all.ru/3.1/library/locale.html#locale.localeconv)342343.344345#### `locale.LC_MESSAGES`346347Категория локали для отображения сообщений. В настоящее время Python не поддерживает зависящие от локали сообщения приложений. Сообщения, отображаемые операционной системой, например возвращаемые348349[`os.strerror()`](https://python-all.ru/3.1/library/os.html#os.strerror)350351, могут зависеть от этой категории.352353#### `locale.LC_NUMERIC`354355Категория локали для форматирования чисел. На неё влияют функции356357[`format()`](https://python-all.ru/3.1/library/locale.html#locale.format)358359,360361[`atoi()`](https://python-all.ru/3.1/library/locale.html#locale.atoi)362363,364365[`atof()`](https://python-all.ru/3.1/library/locale.html#locale.atof)366367и368369[`str()`](https://python-all.ru/3.1/library/locale.html#locale.str)370371модуля372373`locale`374375. Все остальные операции форматирования чисел на неё не влияют.376377#### `locale.LC_ALL`378379Комбинация всех настроек локали. Если этот флаг используется при изменении локали, предпринимается попытка установить локаль для всех категорий. Если это не удаётся для какой-либо категории, ни одна категория не изменяется. При получении локали с помощью этого флага возвращается строка, указывающая настройки для всех категорий. Эту строку можно впоследствии использовать для восстановления настроек.380381#### `locale.CHAR_MAX`382383Это символическая константа, используемая для различных значений, возвращаемых384385[`localeconv()`](https://python-all.ru/3.1/library/locale.html#locale.localeconv)386387.388389Пример:390391```python392>>> import locale393>>> loc = locale.getlocale() # получить текущую локаль394# use German locale; name might vary with platform395>>> locale.setlocale(locale.LC_ALL, 'de_DE')396>>> locale.strcoll('f\xe4n', 'foo') # сравнить строку, содержащую умлаут397>>> locale.setlocale(locale.LC_ALL, '') # использовать предпочтительную локаль пользователя398>>> locale.setlocale(locale.LC_ALL, 'C') # использовать локаль по умолчанию (C)399>>> locale.setlocale(locale.LC_ALL, loc) # восстановить сохранённую локаль400```401402## 22.2.1. Предыстория, подробности, подсказки, советы и предостережения403404Стандарт C определяет локаль как свойство всей программы, которое может быть относительно дорогим для изменения. Вдобавок некоторые реализации настолько некорректны, что частые смены локали могут приводить к дампам памяти. Это делает локаль несколько болезненной для правильного использования.405406Изначально при запуске программы локалью является `C`, независимо от того, какую локаль предпочитает пользователь. Программа должна явно указать, что хочет использовать настройки локали пользователя, вызвав `setlocale(LC_ALL, '')`.407408Как правило, не стоит вызывать [`setlocale()`](https://python-all.ru/3.1/library/locale.html#locale.setlocale) в какой-либо библиотечной функции, поскольку это побочным образом влияет на всю программу. Сохранение и восстановление почти так же плохо: это дорогостоящая операция, которая влияет на другие потоки, которые могут выполняться до восстановления настроек.409410Если при написании модуля общего назначения требуется независимая от локали версия операции, на которую влияет локаль (например, некоторые форматы, используемые с [`time.strftime()`](https://python-all.ru/3.1/library/time.html#time.strftime)), придётся найти способ сделать это без использования стандартной библиотечной функции. Ещё лучше – убедиться, что использование настроек локали допустимо. И только в крайнем случае следует документировать, что модуль несовместим с настройками локали, отличными от `C`.411412Единственный способ выполнять числовые операции в соответствии с локалью – использовать специальные функции, определённые в этом модуле: [`atof()`](https://python-all.ru/3.1/library/locale.html#locale.atof), [`atoi()`](https://python-all.ru/3.1/library/locale.html#locale.atoi), [`format()`](https://python-all.ru/3.1/library/locale.html#locale.format), [`str()`](https://python-all.ru/3.1/library/locale.html#locale.str).413414Не существует способа выполнять преобразование регистра и классификацию символов в соответствии с локалью. Для текстовых строк (Unicode) они выполняются только по значению символа, тогда как для байтовых строк преобразования и классификации выполняются по значению ASCII байта, а байты, у которых установлен старший бит (т.е. не-ASCII байты), никогда не преобразуются и не считаются частью какого-либо класса символов, такого как буква или пробел.415416## 22.2.2. Для разработчиков расширений и программ, встраивающих Python417418Модули расширения никогда не должны вызывать [`setlocale()`](https://python-all.ru/3.1/library/locale.html#locale.setlocale), за исключением случаев, когда нужно узнать текущую локаль. Но поскольку возвращаемое значение можно переносимо использовать только для её восстановления, это не очень полезно (разве что для выяснения, является ли локаль `C`).419420Когда код на Python использует модуль `locale` для смены локали, это также влияет на встраивающее приложение. Если встраивающее приложение не хочет этого, оно должно удалить модуль расширения `_locale` (который выполняет всю работу) из таблицы встроенных модулей в файле `config.c` и убедиться, что модуль `_locale` недоступен в виде общей библиотеки.421422## 22.2.3. Доступ к каталогам сообщений423424Модуль locale предоставляет интерфейс gettext библиотеки C в системах, которые поддерживают этот интерфейс. Он состоит из функций `gettext()`, `dgettext()`, `dcgettext()`, `textdomain()`, `bindtextdomain()` и `bind_textdomain_codeset()`. Они аналогичны одноимённым функциям в модуле [`gettext`](https://python-all.ru/3.1/library/gettext.html#module-gettext), но используют двоичный формат каталогов сообщений библиотеки C и её алгоритмы поиска каталогов сообщений.425426Приложениям Python обычно не нужно вызывать эти функции, и следует использовать [`gettext`](https://python-all.ru/3.1/library/gettext.html#module-gettext). Известное исключение из этого правила – приложения, которые связываются с дополнительными библиотеками C, внутренне вызывающими `gettext()` или `dcgettext()`. Для таких приложений может потребоваться привязать текстовый домен, чтобы библиотеки могли правильно находить свои каталоги сообщений.427