| 1 |
:mod:`!locale` --- Internationalization services |
| 2 |
================================================ |
| 3 |
|
| 4 |
.. module:: locale |
| 5 |
:synopsis: Internationalization services. |
| 6 |
|
| 7 |
.. moduleauthor:: Martin von Löwis <[email protected]> |
| 8 |
.. sectionauthor:: Martin von Löwis <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/locale.py` |
| 11 |
|
| 12 |
-------------- |
| 13 |
|
| 14 |
The :mod:`!locale` module opens access to the POSIX locale database and |
| 15 |
functionality. The POSIX locale mechanism allows programmers to deal with |
| 16 |
certain cultural issues in an application, without requiring the programmer to |
| 17 |
know all the specifics of each country where the software is executed. |
| 18 |
|
| 19 |
.. index:: pair: module; _locale |
| 20 |
|
| 21 |
The :mod:`!locale` module is implemented on top of the :mod:`!_locale` module, |
| 22 |
which in turn uses an ANSI C locale implementation if available. |
| 23 |
|
| 24 |
The :mod:`!locale` module defines the following exception and functions: |
| 25 |
|
| 26 |
|
| 27 |
.. exception:: Error |
| 28 |
|
| 29 |
Exception raised when the locale passed to :func:`setlocale` is not |
| 30 |
recognized. |
| 31 |
|
| 32 |
|
| 33 |
.. function:: setlocale(category, locale=None) |
| 34 |
|
| 35 |
If *locale* is given and not ``None``, :func:`setlocale` modifies the locale |
| 36 |
setting for the *category*. The available categories are listed in the data |
| 37 |
description below. *locale* may be a :ref:`string <locale_name>`, or a pair, |
| 38 |
language code and encoding. An empty string specifies the user's |
| 39 |
default settings. If the modification of the locale fails, the exception |
| 40 |
:exc:`Error` is raised. If successful, the new locale setting is returned. |
| 41 |
|
| 42 |
If *locale* is a pair, it is converted to a locale name using |
| 43 |
the locale aliasing engine. |
| 44 |
The language code has the same format as a :ref:`locale name <locale_name>`, |
| 45 |
but without encoding and ``@``-modifier. |
| 46 |
The language code and encoding can be ``None``. |
| 47 |
|
| 48 |
If *locale* is omitted or ``None``, the current setting for *category* is |
| 49 |
returned. |
| 50 |
|
| 51 |
Example:: |
| 52 |
|
| 53 |
>>> import locale |
| 54 |
>>> loc = locale.setlocale(locale.LC_ALL) # get current locale |
| 55 |
# use German locale; name and availability varies with platform |
| 56 |
>>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8') |
| 57 |
>>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut |
| 58 |
>>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale |
| 59 |
>>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale |
| 60 |
>>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale |
| 61 |
|
| 62 |
:func:`setlocale` is not thread-safe on most systems. Applications typically |
| 63 |
start with a call of:: |
| 64 |
|
| 65 |
import locale |
| 66 |
locale.setlocale(locale.LC_ALL, '') |
| 67 |
|
| 68 |
This sets the locale for all categories to the user's default setting (typically |
| 69 |
specified in the :envvar:`LANG` environment variable). If the locale is not |
| 70 |
changed thereafter, using multithreading should not cause problems. |
| 71 |
|
| 72 |
|
| 73 |
.. function:: localeconv() |
| 74 |
|
| 75 |
Returns the database of the local conventions as a dictionary. This dictionary |
| 76 |
has the following strings as keys: |
| 77 |
|
| 78 |
.. tabularcolumns:: |l|l|L| |
| 79 |
|
| 80 |
+----------------------+-------------------------------------+--------------------------------+ |
| 81 |
| Category | Key | Meaning | |
| 82 |
+======================+=====================================+================================+ |
| 83 |
| :const:`LC_NUMERIC` | ``'decimal_point'`` | Decimal point character. | |
| 84 |
+----------------------+-------------------------------------+--------------------------------+ |
| 85 |
| | ``'grouping'`` | Sequence of numbers specifying | |
| 86 |
| | | which relative positions the | |
| 87 |
| | | ``'thousands_sep'`` is | |
| 88 |
| | | expected. If the sequence is | |
| 89 |
| | | terminated with | |
| 90 |
| | | :const:`CHAR_MAX`, no further | |
| 91 |
| | | grouping is performed. If the | |
| 92 |
| | | sequence terminates with a | |
| 93 |
| | | ``0``, the last group size is | |
| 94 |
| | | repeatedly used. | |
| 95 |
+----------------------+-------------------------------------+--------------------------------+ |
| 96 |
| | ``'thousands_sep'`` | Character used between groups. | |
| 97 |
+----------------------+-------------------------------------+--------------------------------+ |
| 98 |
| :const:`LC_MONETARY` | ``'int_curr_symbol'`` | International currency symbol. | |
| 99 |
+----------------------+-------------------------------------+--------------------------------+ |
| 100 |
| | ``'currency_symbol'`` | Local currency symbol. | |
| 101 |
+----------------------+-------------------------------------+--------------------------------+ |
| 102 |
| | ``'p_cs_precedes/n_cs_precedes'`` | Whether the currency symbol | |
| 103 |
| | | precedes the value (for | |
| 104 |
| | | positive resp. negative | |
| 105 |
| | | values). | |
| 106 |
+----------------------+-------------------------------------+--------------------------------+ |
| 107 |
| | ``'p_sep_by_space/n_sep_by_space'`` | Whether the currency symbol is | |
| 108 |
| | | separated from the value by a | |
| 109 |
| | | space (for positive resp. | |
| 110 |
| | | negative values). | |
| 111 |
+----------------------+-------------------------------------+--------------------------------+ |
| 112 |
| | ``'mon_decimal_point'`` | Decimal point used for | |
| 113 |
| | | monetary values. | |
| 114 |
+----------------------+-------------------------------------+--------------------------------+ |
| 115 |
| | ``'frac_digits'`` | Number of fractional digits | |
| 116 |
| | | used in local formatting of | |
| 117 |
| | | monetary values. | |
| 118 |
+----------------------+-------------------------------------+--------------------------------+ |
| 119 |
| | ``'int_frac_digits'`` | Number of fractional digits | |
| 120 |
| | | used in international | |
| 121 |
| | | formatting of monetary values. | |
| 122 |
+----------------------+-------------------------------------+--------------------------------+ |
| 123 |
| | ``'mon_thousands_sep'`` | Group separator used for | |
| 124 |
| | | monetary values. | |
| 125 |
+----------------------+-------------------------------------+--------------------------------+ |
| 126 |
| | ``'mon_grouping'`` | Equivalent to ``'grouping'``, | |
| 127 |
| | | used for monetary values. | |
| 128 |
+----------------------+-------------------------------------+--------------------------------+ |
| 129 |
| | ``'positive_sign'`` | Symbol used to annotate a | |
| 130 |
| | | positive monetary value. | |
| 131 |
+----------------------+-------------------------------------+--------------------------------+ |
| 132 |
| | ``'negative_sign'`` | Symbol used to annotate a | |
| 133 |
| | | negative monetary value. | |
| 134 |
+----------------------+-------------------------------------+--------------------------------+ |
| 135 |
| | ``'p_sign_posn/n_sign_posn'`` | The position of the sign (for | |
| 136 |
| | | positive resp. negative | |
| 137 |
| | | values), see below. | |
| 138 |
+----------------------+-------------------------------------+--------------------------------+ |
| 139 |
|
| 140 |
All numeric values can be set to :const:`CHAR_MAX` to indicate that there is no |
| 141 |
value specified in this locale. |
| 142 |
|
| 143 |
The possible values for ``'p_sign_posn'`` and ``'n_sign_posn'`` are given below. |
| 144 |
|
| 145 |
+--------------+-----------------------------------------+ |
| 146 |
| Value | Explanation | |
| 147 |
+==============+=========================================+ |
| 148 |
| ``0`` | Currency and value are surrounded by | |
| 149 |
| | parentheses. | |
| 150 |
+--------------+-----------------------------------------+ |
| 151 |
| ``1`` | The sign should precede the value and | |
| 152 |
| | currency symbol. | |
| 153 |
+--------------+-----------------------------------------+ |
| 154 |
| ``2`` | The sign should follow the value and | |
| 155 |
| | currency symbol. | |
| 156 |
+--------------+-----------------------------------------+ |
| 157 |
| ``3`` | The sign should immediately precede the | |
| 158 |
| | value. | |
| 159 |
+--------------+-----------------------------------------+ |
| 160 |
| ``4`` | The sign should immediately follow the | |
| 161 |
| | value. | |
| 162 |
+--------------+-----------------------------------------+ |
| 163 |
| ``CHAR_MAX`` | Nothing is specified in this locale. | |
| 164 |
+--------------+-----------------------------------------+ |
| 165 |
|
| 166 |
The function temporarily sets the ``LC_CTYPE`` locale to the ``LC_NUMERIC`` |
| 167 |
locale or the ``LC_MONETARY`` locale if locales are different and numeric or |
| 168 |
monetary strings are non-ASCII. This temporary change affects other threads. |
| 169 |
|
| 170 |
.. versionchanged:: 3.7 |
| 171 |
The function now temporarily sets the ``LC_CTYPE`` locale to the |
| 172 |
``LC_NUMERIC`` locale in some cases. |
| 173 |
|
| 174 |
|
| 175 |
.. function:: nl_langinfo(option) |
| 176 |
|
| 177 |
Return some locale-specific information as a string. This function is not |
| 178 |
available on all systems, and the set of possible options might also vary |
| 179 |
across platforms. The possible argument values are numbers, for which |
| 180 |
symbolic constants are available in the locale module. |
| 181 |
|
| 182 |
The :func:`nl_langinfo` function accepts one of the following keys. Most |
| 183 |
descriptions are taken from the corresponding description in the GNU C |
| 184 |
library. |
| 185 |
|
| 186 |
.. data:: CODESET |
| 187 |
|
| 188 |
Get a string with the name of the character encoding used in the |
| 189 |
selected locale. |
| 190 |
|
| 191 |
.. data:: D_T_FMT |
| 192 |
|
| 193 |
Get a string that can be used as a format string for :func:`time.strftime` to |
| 194 |
represent date and time in a locale-specific way. |
| 195 |
|
| 196 |
.. data:: D_FMT |
| 197 |
|
| 198 |
Get a string that can be used as a format string for :func:`time.strftime` to |
| 199 |
represent a date in a locale-specific way. |
| 200 |
|
| 201 |
.. data:: T_FMT |
| 202 |
|
| 203 |
Get a string that can be used as a format string for :func:`time.strftime` to |
| 204 |
represent a time in a locale-specific way. |
| 205 |
|
| 206 |
.. data:: T_FMT_AMPM |
| 207 |
|
| 208 |
Get a format string for :func:`time.strftime` to represent time in the am/pm |
| 209 |
format. |
| 210 |
|
| 211 |
.. data:: DAY_1 |
| 212 |
DAY_2 |
| 213 |
DAY_3 |
| 214 |
DAY_4 |
| 215 |
DAY_5 |
| 216 |
DAY_6 |
| 217 |
DAY_7 |
| 218 |
|
| 219 |
Get the name of the n-th day of the week. |
| 220 |
|
| 221 |
.. note:: |
| 222 |
|
| 223 |
This follows the US convention of :const:`DAY_1` being Sunday, not the |
| 224 |
international convention (ISO 8601) that Monday is the first day of the |
| 225 |
week. |
| 226 |
|
| 227 |
.. data:: ABDAY_1 |
| 228 |
ABDAY_2 |
| 229 |
ABDAY_3 |
| 230 |
ABDAY_4 |
| 231 |
ABDAY_5 |
| 232 |
ABDAY_6 |
| 233 |
ABDAY_7 |
| 234 |
|
| 235 |
Get the abbreviated name of the n-th day of the week. |
| 236 |
|
| 237 |
.. data:: MON_1 |
| 238 |
MON_2 |
| 239 |
MON_3 |
| 240 |
MON_4 |
| 241 |
MON_5 |
| 242 |
MON_6 |
| 243 |
MON_7 |
| 244 |
MON_8 |
| 245 |
MON_9 |
| 246 |
MON_10 |
| 247 |
MON_11 |
| 248 |
MON_12 |
| 249 |
|
| 250 |
Get the name of the n-th month. |
| 251 |
|
| 252 |
.. data:: ABMON_1 |
| 253 |
ABMON_2 |
| 254 |
ABMON_3 |
| 255 |
ABMON_4 |
| 256 |
ABMON_5 |
| 257 |
ABMON_6 |
| 258 |
ABMON_7 |
| 259 |
ABMON_8 |
| 260 |
ABMON_9 |
| 261 |
ABMON_10 |
| 262 |
ABMON_11 |
| 263 |
ABMON_12 |
| 264 |
|
| 265 |
Get the abbreviated name of the n-th month. |
| 266 |
|
| 267 |
.. data:: RADIXCHAR |
| 268 |
|
| 269 |
Get the radix character (decimal dot, decimal comma, etc.). |
| 270 |
|
| 271 |
.. data:: THOUSEP |
| 272 |
|
| 273 |
Get the separator character for thousands (groups of three digits). |
| 274 |
|
| 275 |
.. data:: YESEXPR |
| 276 |
|
| 277 |
Get a regular expression that can be used with the regex function to |
| 278 |
recognize a positive response to a yes/no question. |
| 279 |
|
| 280 |
.. data:: NOEXPR |
| 281 |
|
| 282 |
Get a regular expression that can be used with the ``regex(3)`` function to |
| 283 |
recognize a negative response to a yes/no question. |
| 284 |
|
| 285 |
.. note:: |
| 286 |
|
| 287 |
The regular expressions for :const:`YESEXPR` and |
| 288 |
:const:`NOEXPR` use syntax suitable for the |
| 289 |
``regex`` function from the C library, which might |
| 290 |
differ from the syntax used in :mod:`re`. |
| 291 |
|
| 292 |
.. data:: CRNCYSTR |
| 293 |
|
| 294 |
Get the currency symbol, preceded by "-" if the symbol should appear before |
| 295 |
the value, "+" if the symbol should appear after the value, or "." if the |
| 296 |
symbol should replace the radix character. |
| 297 |
|
| 298 |
.. data:: ERA |
| 299 |
|
| 300 |
Get a string which describes how years are counted and displayed for |
| 301 |
each era in a locale. |
| 302 |
|
| 303 |
Most locales do not define this value. An example of a locale which does |
| 304 |
define this value is the Japanese one. In Japan, the traditional |
| 305 |
representation of dates includes the name of the era corresponding to the |
| 306 |
then-emperor's reign. |
| 307 |
|
| 308 |
Normally it should not be necessary to use this value directly. Specifying |
| 309 |
the ``E`` modifier in their format strings causes the :func:`time.strftime` |
| 310 |
function to use this information. |
| 311 |
The format of the returned string is specified in *The Open Group Base |
| 312 |
Specifications Issue 8*, paragraph `7.3.5.2 LC_TIME C-Language Access |
| 313 |
<https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap07.html#tag_07_03_05_02>`_. |
| 314 |
|
| 315 |
.. data:: ERA_D_T_FMT |
| 316 |
|
| 317 |
Get a format string for :func:`time.strftime` to represent date and time in a |
| 318 |
locale-specific era-based way. |
| 319 |
|
| 320 |
.. data:: ERA_D_FMT |
| 321 |
|
| 322 |
Get a format string for :func:`time.strftime` to represent a date in a |
| 323 |
locale-specific era-based way. |
| 324 |
|
| 325 |
.. data:: ERA_T_FMT |
| 326 |
|
| 327 |
Get a format string for :func:`time.strftime` to represent a time in a |
| 328 |
locale-specific era-based way. |
| 329 |
|
| 330 |
.. data:: ALT_DIGITS |
| 331 |
|
| 332 |
Get a string consisting of up to 100 semicolon-separated symbols used |
| 333 |
to represent the values 0 to 99 in a locale-specific way. |
| 334 |
In most locales this is an empty string. |
| 335 |
|
| 336 |
The function temporarily sets the ``LC_CTYPE`` locale to the locale |
| 337 |
of the category that determines the requested value (``LC_TIME``, |
| 338 |
``LC_NUMERIC``, ``LC_MONETARY`` or ``LC_MESSAGES``) if locales are |
| 339 |
different and the resulting string is non-ASCII. |
| 340 |
This temporary change affects other threads. |
| 341 |
|
| 342 |
.. versionchanged:: 3.14 |
| 343 |
The function now temporarily sets the ``LC_CTYPE`` locale in some cases. |
| 344 |
|
| 345 |
|
| 346 |
.. function:: getdefaultlocale([envvars]) |
| 347 |
|
| 348 |
Tries to determine the default locale settings and returns them as a tuple of |
| 349 |
the form ``(language code, encoding)``. |
| 350 |
|
| 351 |
According to POSIX, a program which has not called ``setlocale(LC_ALL, '')`` |
| 352 |
runs using the portable ``'C'`` locale. Calling ``setlocale(LC_ALL, '')`` lets |
| 353 |
it use the default locale as defined by the :envvar:`LANG` variable. Since we |
| 354 |
do not want to interfere with the current locale setting we thus emulate the |
| 355 |
behavior in the way described above. |
| 356 |
|
| 357 |
To maintain compatibility with other platforms, not only the :envvar:`LANG` |
| 358 |
variable is tested, but a list of variables given as envvars parameter. The |
| 359 |
first found to be defined will be used. *envvars* defaults to the search |
| 360 |
path used in GNU gettext; it must always contain the variable name |
| 361 |
``'LANG'``. The GNU gettext search path contains ``'LC_ALL'``, |
| 362 |
``'LC_CTYPE'``, ``'LANG'`` and ``'LANGUAGE'``, in that order. |
| 363 |
|
| 364 |
The language code has the same format as a :ref:`locale name <locale_name>`, |
| 365 |
but without encoding and ``@``-modifier. |
| 366 |
The language code and encoding may be ``None`` if their values cannot be |
| 367 |
determined. |
| 368 |
The "C" locale is represented as ``(None, None)``. |
| 369 |
|
| 370 |
.. deprecated-removed:: 3.11 3.15 |
| 371 |
|
| 372 |
|
| 373 |
.. function:: getlocale(category=LC_CTYPE) |
| 374 |
|
| 375 |
Returns the current setting for the given locale category as a tuple containing |
| 376 |
the language code and encoding. *category* may be one of the :const:`!LC_\*` |
| 377 |
values except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`. |
| 378 |
|
| 379 |
The language code has the same format as a :ref:`locale name <locale_name>`, |
| 380 |
but without encoding and ``@``-modifier. |
| 381 |
The language code and encoding may be ``None`` if their values cannot be |
| 382 |
determined. |
| 383 |
The "C" locale is represented as ``(None, None)``. |
| 384 |
|
| 385 |
|
| 386 |
.. function:: getpreferredencoding(do_setlocale=True) |
| 387 |
|
| 388 |
Return the :term:`locale encoding` used for text data, according to user |
| 389 |
preferences. User preferences are expressed differently on different |
| 390 |
systems, and might not be available programmatically on some systems, so |
| 391 |
this function only returns a guess. |
| 392 |
|
| 393 |
On some systems, it is necessary to invoke :func:`setlocale` to obtain the |
| 394 |
user preferences, so this function is not thread-safe. If invoking setlocale |
| 395 |
is not necessary or desired, *do_setlocale* should be set to ``False``. |
| 396 |
|
| 397 |
On Android or if the :ref:`Python UTF-8 Mode <utf8-mode>` is enabled, always |
| 398 |
return ``'utf-8'``, the :term:`locale encoding` and the *do_setlocale* |
| 399 |
argument are ignored. |
| 400 |
|
| 401 |
The :ref:`Python preinitialization <c-preinit>` configures the LC_CTYPE |
| 402 |
locale. See also the :term:`filesystem encoding and error handler`. |
| 403 |
|
| 404 |
.. versionchanged:: 3.7 |
| 405 |
The function now always returns ``"utf-8"`` on Android or if the |
| 406 |
:ref:`Python UTF-8 Mode <utf8-mode>` is enabled. |
| 407 |
|
| 408 |
|
| 409 |
.. function:: getencoding() |
| 410 |
|
| 411 |
Get the current :term:`locale encoding`: |
| 412 |
|
| 413 |
* On Android and VxWorks, return ``"utf-8"``. |
| 414 |
* On Unix, return the encoding of the current :data:`LC_CTYPE` locale. |
| 415 |
Return ``"utf-8"`` if ``nl_langinfo(CODESET)`` returns an empty string: |
| 416 |
for example, if the current LC_CTYPE locale is not supported. |
| 417 |
* On Windows, return the ANSI code page. |
| 418 |
|
| 419 |
The :ref:`Python preinitialization <c-preinit>` configures the LC_CTYPE |
| 420 |
locale. See also the :term:`filesystem encoding and error handler`. |
| 421 |
|
| 422 |
This function is similar to |
| 423 |
:func:`getpreferredencoding(False) <getpreferredencoding>` except this |
| 424 |
function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`. |
| 425 |
|
| 426 |
.. versionadded:: 3.11 |
| 427 |
|
| 428 |
|
| 429 |
.. function:: normalize(localename) |
| 430 |
|
| 431 |
Returns a normalized locale code for the given locale name. The returned locale |
| 432 |
code is formatted for use with :func:`setlocale`. If normalization fails, the |
| 433 |
original name is returned unchanged. |
| 434 |
|
| 435 |
If the given encoding is not known, the function defaults to the default |
| 436 |
encoding for the locale code just like :func:`setlocale`. |
| 437 |
|
| 438 |
|
| 439 |
.. function:: strcoll(string1, string2) |
| 440 |
|
| 441 |
Compares two strings according to the current :const:`LC_COLLATE` setting. As |
| 442 |
any other compare function, returns a negative, or a positive value, or ``0``, |
| 443 |
depending on whether *string1* collates before or after *string2* or is equal to |
| 444 |
it. |
| 445 |
|
| 446 |
|
| 447 |
.. function:: strxfrm(string) |
| 448 |
|
| 449 |
Transforms a string to one that can be used in locale-aware |
| 450 |
comparisons. For example, ``strxfrm(s1) < strxfrm(s2)`` is |
| 451 |
equivalent to ``strcoll(s1, s2) < 0``. This function can be used |
| 452 |
when the same string is compared repeatedly, e.g. when collating a |
| 453 |
sequence of strings. |
| 454 |
|
| 455 |
|
| 456 |
.. function:: format_string(format, val, grouping=False, monetary=False) |
| 457 |
|
| 458 |
Formats a number *val* according to the current :const:`LC_NUMERIC` setting. |
| 459 |
The format follows the conventions of the ``%`` operator. For floating-point |
| 460 |
values, the decimal point is modified if appropriate. If *grouping* is ``True``, |
| 461 |
also takes the grouping into account. |
| 462 |
|
| 463 |
If *monetary* is true, the conversion uses monetary thousands separator and |
| 464 |
grouping strings. |
| 465 |
|
| 466 |
Processes formatting specifiers as in ``format % val``, but takes the current |
| 467 |
locale settings into account. |
| 468 |
|
| 469 |
.. versionchanged:: 3.7 |
| 470 |
The *monetary* keyword parameter was added. |
| 471 |
|
| 472 |
|
| 473 |
.. function:: currency(val, symbol=True, grouping=False, international=False) |
| 474 |
|
| 475 |
Formats a number *val* according to the current :const:`LC_MONETARY` settings. |
| 476 |
|
| 477 |
The returned string includes the currency symbol if *symbol* is true, which is |
| 478 |
the default. If *grouping* is ``True`` (which is not the default), grouping is done |
| 479 |
with the value. If *international* is ``True`` (which is not the default), the |
| 480 |
international currency symbol is used. |
| 481 |
|
| 482 |
.. note:: |
| 483 |
|
| 484 |
This function will not work with the 'C' locale, so you have to set a |
| 485 |
locale via :func:`setlocale` first. |
| 486 |
|
| 487 |
|
| 488 |
.. function:: str(float) |
| 489 |
|
| 490 |
Formats a floating-point number using the same format as the built-in function |
| 491 |
``str(float)``, but takes the decimal point into account. |
| 492 |
|
| 493 |
|
| 494 |
.. function:: delocalize(string) |
| 495 |
|
| 496 |
Converts a string into a normalized number string, following the |
| 497 |
:const:`LC_NUMERIC` settings. |
| 498 |
|
| 499 |
.. versionadded:: 3.5 |
| 500 |
|
| 501 |
|
| 502 |
.. function:: localize(string, grouping=False, monetary=False) |
| 503 |
|
| 504 |
Converts a normalized number string into a formatted string following the |
| 505 |
:const:`LC_NUMERIC` settings. |
| 506 |
|
| 507 |
.. versionadded:: 3.10 |
| 508 |
|
| 509 |
|
| 510 |
.. function:: atof(string, func=float) |
| 511 |
|
| 512 |
Converts a string to a number, following the :const:`LC_NUMERIC` settings, |
| 513 |
by calling *func* on the result of calling :func:`delocalize` on *string*. |
| 514 |
|
| 515 |
|
| 516 |
.. function:: atoi(string) |
| 517 |
|
| 518 |
Converts a string to an integer, following the :const:`LC_NUMERIC` conventions. |
| 519 |
|
| 520 |
|
| 521 |
.. data:: LC_CTYPE |
| 522 |
|
| 523 |
Locale category for the character type functions. Most importantly, this |
| 524 |
category defines the text encoding, i.e. how bytes are interpreted as |
| 525 |
Unicode codepoints. See :pep:`538` and :pep:`540` for how this variable |
| 526 |
might be automatically coerced to ``C.UTF-8`` to avoid issues created by |
| 527 |
invalid settings in containers or incompatible settings passed over remote |
| 528 |
SSH connections. |
| 529 |
|
| 530 |
Python doesn't internally use locale-dependent character transformation functions |
| 531 |
from ``ctype.h``. Instead, ``pyctype.h`` provides locale-independent |
| 532 |
equivalents like :c:macro:`Py_TOLOWER`. |
| 533 |
|
| 534 |
|
| 535 |
.. data:: LC_COLLATE |
| 536 |
|
| 537 |
Locale category for sorting strings. The functions :func:`strcoll` and |
| 538 |
:func:`strxfrm` of the :mod:`!locale` module are affected. |
| 539 |
|
| 540 |
|
| 541 |
.. data:: LC_TIME |
| 542 |
|
| 543 |
Locale category for the formatting of time. The function :func:`time.strftime` |
| 544 |
follows these conventions. |
| 545 |
|
| 546 |
|
| 547 |
.. data:: LC_MONETARY |
| 548 |
|
| 549 |
Locale category for formatting of monetary values. The available options are |
| 550 |
available from the :func:`localeconv` function. |
| 551 |
|
| 552 |
|
| 553 |
.. data:: LC_MESSAGES |
| 554 |
|
| 555 |
Locale category for message display. Python currently does not support |
| 556 |
application specific locale-aware messages. Messages displayed by the operating |
| 557 |
system, like those returned by :func:`os.strerror` might be affected by this |
| 558 |
category. |
| 559 |
|
| 560 |
This value may not be available on operating systems not conforming to the |
| 561 |
POSIX standard, most notably Windows. |
| 562 |
|
| 563 |
|
| 564 |
.. data:: LC_NUMERIC |
| 565 |
|
| 566 |
Locale category for formatting numbers. The functions :func:`format_string`, |
| 567 |
:func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`!locale` module are |
| 568 |
affected by that category. All other numeric formatting operations are not |
| 569 |
affected. |
| 570 |
|
| 571 |
|
| 572 |
.. data:: LC_ALL |
| 573 |
|
| 574 |
Combination of all locale settings. If this flag is used when the locale is |
| 575 |
changed, setting the locale for all categories is attempted. If that fails for |
| 576 |
any category, no category is changed at all. When the locale is retrieved using |
| 577 |
this flag, a string indicating the setting for all categories is returned. This |
| 578 |
string can be later used to restore the settings. |
| 579 |
|
| 580 |
|
| 581 |
.. data:: CHAR_MAX |
| 582 |
|
| 583 |
This is a symbolic constant used for different values returned by |
| 584 |
:func:`localeconv`. |
| 585 |
|
| 586 |
|
| 587 |
Background, details, hints, tips and caveats |
| 588 |
-------------------------------------------- |
| 589 |
|
| 590 |
The C standard defines the locale as a program-wide property that may be |
| 591 |
relatively expensive to change. On top of that, some implementations are broken |
| 592 |
in such a way that frequent locale changes may cause core dumps. This makes the |
| 593 |
locale somewhat painful to use correctly. |
| 594 |
|
| 595 |
Initially, when a program is started, the locale is the ``C`` locale, no matter |
| 596 |
what the user's preferred locale is. There is one exception: the |
| 597 |
:data:`LC_CTYPE` category is changed at startup to set the current locale |
| 598 |
encoding to the user's preferred locale encoding. The program must explicitly |
| 599 |
say that it wants the user's preferred locale settings for other categories by |
| 600 |
calling ``setlocale(LC_ALL, '')``. |
| 601 |
|
| 602 |
It is generally a bad idea to call :func:`setlocale` in some library routine, |
| 603 |
since as a side effect it affects the entire program. Saving and restoring it |
| 604 |
is almost as bad: it is expensive and affects other threads that happen to run |
| 605 |
before the settings have been restored. |
| 606 |
|
| 607 |
If, when coding a module for general use, you need a locale independent version |
| 608 |
of an operation that is affected by the locale (such as |
| 609 |
certain formats used with :func:`time.strftime`), you will have to find a way to |
| 610 |
do it without using the standard library routine. Even better is convincing |
| 611 |
yourself that using locale settings is okay. Only as a last resort should you |
| 612 |
document that your module is not compatible with non-\ ``C`` locale settings. |
| 613 |
|
| 614 |
The only way to perform numeric operations according to the locale is to use the |
| 615 |
special functions defined by this module: :func:`atof`, :func:`atoi`, |
| 616 |
:func:`format_string`, :func:`.str`. |
| 617 |
|
| 618 |
There is no way to perform case conversions and character classifications |
| 619 |
according to the locale. For (Unicode) text strings these are done according |
| 620 |
to the character value only, while for byte strings, the conversions and |
| 621 |
classifications are done according to the ASCII value of the byte, and bytes |
| 622 |
whose high bit is set (i.e., non-ASCII bytes) are never converted or considered |
| 623 |
part of a character class such as letter or whitespace. |
| 624 |
|
| 625 |
|
| 626 |
.. _locale_name: |
| 627 |
|
| 628 |
Locale names |
| 629 |
------------ |
| 630 |
|
| 631 |
The format of the locale name is platform dependent, and the set of supported |
| 632 |
locales can depend on the system configuration. |
| 633 |
|
| 634 |
On Posix platforms, it usually has the format [1]_: |
| 635 |
|
| 636 |
.. productionlist:: locale_name |
| 637 |
: language ["_" territory] ["." charset] ["@" modifier] |
| 638 |
|
| 639 |
where *language* is a two- or three-letter language code from `ISO 639`_, |
| 640 |
*territory* is a two-letter country or region code from `ISO 3166`_, |
| 641 |
*charset* is a locale encoding, and *modifier* is a script name, |
| 642 |
a language subtag, a sort order identifier, or other locale modifier |
| 643 |
(for example, "latin", "valencia", "stroke" and "euro"). |
| 644 |
|
| 645 |
On Windows, several formats are supported. [2]_ [3]_ |
| 646 |
A subset of `IETF BCP 47`_ tags: |
| 647 |
|
| 648 |
.. productionlist:: locale_name |
| 649 |
: language ["-" script] ["-" territory] ["." charset] |
| 650 |
: language ["-" script] "-" territory "-" modifier |
| 651 |
|
| 652 |
where *language* and *territory* have the same meaning as in Posix, |
| 653 |
*script* is a four-letter script code from `ISO 15924`_, |
| 654 |
and *modifier* is a language subtag, a sort order identifier |
| 655 |
or custom modifier (for example, "valencia", "stroke" or "x-python"). |
| 656 |
Both hyphen (``'-'``) and underscore (``'_'``) separators are supported. |
| 657 |
Only UTF-8 encoding is allowed for BCP 47 tags. |
| 658 |
|
| 659 |
Windows also supports locale names in the format: |
| 660 |
|
| 661 |
.. productionlist:: locale_name |
| 662 |
: language ["_" territory] ["." charset] |
| 663 |
|
| 664 |
where *language* and *territory* are full names, such as "English" and |
| 665 |
"United States", and *charset* is either a code page number (for example, "1252") |
| 666 |
or UTF-8. |
| 667 |
Only the underscore separator is supported in this format. |
| 668 |
|
| 669 |
The "C" locale is supported on all platforms. |
| 670 |
|
| 671 |
.. _ISO 639: https://www.iso.org/iso-639-language-code |
| 672 |
.. _ISO 3166: https://www.iso.org/iso-3166-country-codes.html |
| 673 |
.. _IETF BCP 47: https://www.rfc-editor.org/info/bcp47 |
| 674 |
.. _ISO 15924: https://www.unicode.org/iso15924/ |
| 675 |
|
| 676 |
.. [1] `IEEE Std 1003.1-2024; 8.2 Internationalization Variables <https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html#tag_08_02>`_ |
| 677 |
.. [2] `UCRT Locale names, Languages, and Country/Region strings <https://learn.microsoft.com/en-us/cpp/c-runtime-library/locale-names-languages-and-country-region-strings>`_ |
| 678 |
.. [3] `Locale Names <https://learn.microsoft.com/en-us/windows/win32/intl/locale-names>`_ |
| 679 |
|
| 680 |
|
| 681 |
.. _embedding-locale: |
| 682 |
|
| 683 |
For extension writers and programs that embed Python |
| 684 |
---------------------------------------------------- |
| 685 |
|
| 686 |
Extension modules should never call :func:`setlocale`, except to find out what |
| 687 |
the current locale is. But since the return value can only be used portably to |
| 688 |
restore it, that is not very useful (except perhaps to find out whether or not |
| 689 |
the locale is ``C``). |
| 690 |
|
| 691 |
When Python code uses the :mod:`!locale` module to change the locale, this also |
| 692 |
affects the embedding application. If the embedding application doesn't want |
| 693 |
this to happen, it should remove the :mod:`!_locale` extension module (which does |
| 694 |
all the work) from the table of built-in modules in the :file:`config.c` file, |
| 695 |
and make sure that the :mod:`!_locale` module is not accessible as a shared |
| 696 |
library. |
| 697 |
|
| 698 |
|
| 699 |
.. _locale-gettext: |
| 700 |
|
| 701 |
Access to message catalogs |
| 702 |
-------------------------- |
| 703 |
|
| 704 |
.. function:: gettext(msg) |
| 705 |
.. function:: dgettext(domain, msg) |
| 706 |
.. function:: dcgettext(domain, msg, category) |
| 707 |
.. function:: textdomain(domain) |
| 708 |
.. function:: bindtextdomain(domain, dir) |
| 709 |
.. function:: bind_textdomain_codeset(domain, codeset) |
| 710 |
|
| 711 |
The locale module exposes the C library's gettext interface on systems that |
| 712 |
provide this interface. It consists of the functions :func:`gettext`, |
| 713 |
:func:`dgettext`, :func:`dcgettext`, :func:`textdomain`, :func:`bindtextdomain`, |
| 714 |
and :func:`bind_textdomain_codeset`. These are similar to the same functions in |
| 715 |
the :mod:`gettext` module, but use the C library's binary format for message |
| 716 |
catalogs, and the C library's search algorithms for locating message catalogs. |
| 717 |
|
| 718 |
Python applications should normally find no need to invoke these functions, and |
| 719 |
should use :mod:`gettext` instead. A known exception to this rule are |
| 720 |
applications that link with additional C libraries which internally invoke |
| 721 |
C functions ``gettext`` or ``dcgettext``. For these applications, it may be |
| 722 |
necessary to bind the text domain, so that the libraries can properly locate |
| 723 |
their message catalogs. |