Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`locale` --- Internationalization services |
| 2 | =============================================== |
| 3 | |
| 4 | .. module:: locale |
| 5 | :synopsis: Internationalization services. |
| 6 | .. moduleauthor:: Martin von Löwis <martin@v.loewis.de> |
| 7 | .. sectionauthor:: Martin von Löwis <martin@v.loewis.de> |
| 8 | |
| 9 | |
| 10 | The :mod:`locale` module opens access to the POSIX locale database and |
| 11 | functionality. The POSIX locale mechanism allows programmers to deal with |
| 12 | certain cultural issues in an application, without requiring the programmer to |
| 13 | know all the specifics of each country where the software is executed. |
| 14 | |
| 15 | .. index:: module: _locale |
| 16 | |
| 17 | The :mod:`locale` module is implemented on top of the :mod:`_locale` module, |
| 18 | which in turn uses an ANSI C locale implementation if available. |
| 19 | |
| 20 | The :mod:`locale` module defines the following exception and functions: |
| 21 | |
| 22 | |
| 23 | .. exception:: Error |
| 24 | |
Petri Lehtinen | 395ca72 | 2011-11-05 10:18:50 +0200 | [diff] [blame] | 25 | Exception raised when the locale passed to :func:`setlocale` is not |
| 26 | recognized. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | |
| 28 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 29 | .. function:: setlocale(category, locale=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
Petri Lehtinen | 395ca72 | 2011-11-05 10:18:50 +0200 | [diff] [blame] | 31 | If *locale* is given and not ``None``, :func:`setlocale` modifies the locale |
| 32 | setting for the *category*. The available categories are listed in the data |
| 33 | description below. *locale* may be a string, or an iterable of two strings |
| 34 | (language code and encoding). If it's an iterable, it's converted to a locale |
| 35 | name using the locale aliasing engine. An empty string specifies the user's |
| 36 | default settings. If the modification of the locale fails, the exception |
| 37 | :exc:`Error` is raised. If successful, the new locale setting is returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
| 39 | If *locale* is omitted or ``None``, the current setting for *category* is |
| 40 | returned. |
| 41 | |
Georg Brandl | f285bcc | 2010-10-19 21:07:16 +0000 | [diff] [blame] | 42 | :func:`setlocale` is not thread-safe on most systems. Applications typically |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | start with a call of :: |
| 44 | |
| 45 | import locale |
| 46 | locale.setlocale(locale.LC_ALL, '') |
| 47 | |
| 48 | This sets the locale for all categories to the user's default setting (typically |
| 49 | specified in the :envvar:`LANG` environment variable). If the locale is not |
| 50 | changed thereafter, using multithreading should not cause problems. |
| 51 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
| 53 | .. function:: localeconv() |
| 54 | |
| 55 | Returns the database of the local conventions as a dictionary. This dictionary |
| 56 | has the following strings as keys: |
| 57 | |
| 58 | +----------------------+-------------------------------------+--------------------------------+ |
| 59 | | Category | Key | Meaning | |
| 60 | +======================+=====================================+================================+ |
| 61 | | :const:`LC_NUMERIC` | ``'decimal_point'`` | Decimal point character. | |
| 62 | +----------------------+-------------------------------------+--------------------------------+ |
| 63 | | | ``'grouping'`` | Sequence of numbers specifying | |
| 64 | | | | which relative positions the | |
| 65 | | | | ``'thousands_sep'`` is | |
| 66 | | | | expected. If the sequence is | |
| 67 | | | | terminated with | |
| 68 | | | | :const:`CHAR_MAX`, no further | |
| 69 | | | | grouping is performed. If the | |
| 70 | | | | sequence terminates with a | |
| 71 | | | | ``0``, the last group size is | |
| 72 | | | | repeatedly used. | |
| 73 | +----------------------+-------------------------------------+--------------------------------+ |
| 74 | | | ``'thousands_sep'`` | Character used between groups. | |
| 75 | +----------------------+-------------------------------------+--------------------------------+ |
| 76 | | :const:`LC_MONETARY` | ``'int_curr_symbol'`` | International currency symbol. | |
| 77 | +----------------------+-------------------------------------+--------------------------------+ |
| 78 | | | ``'currency_symbol'`` | Local currency symbol. | |
| 79 | +----------------------+-------------------------------------+--------------------------------+ |
| 80 | | | ``'p_cs_precedes/n_cs_precedes'`` | Whether the currency symbol | |
| 81 | | | | precedes the value (for | |
| 82 | | | | positive resp. negative | |
| 83 | | | | values). | |
| 84 | +----------------------+-------------------------------------+--------------------------------+ |
| 85 | | | ``'p_sep_by_space/n_sep_by_space'`` | Whether the currency symbol is | |
| 86 | | | | separated from the value by a | |
| 87 | | | | space (for positive resp. | |
| 88 | | | | negative values). | |
| 89 | +----------------------+-------------------------------------+--------------------------------+ |
| 90 | | | ``'mon_decimal_point'`` | Decimal point used for | |
| 91 | | | | monetary values. | |
| 92 | +----------------------+-------------------------------------+--------------------------------+ |
| 93 | | | ``'frac_digits'`` | Number of fractional digits | |
| 94 | | | | used in local formatting of | |
| 95 | | | | monetary values. | |
| 96 | +----------------------+-------------------------------------+--------------------------------+ |
| 97 | | | ``'int_frac_digits'`` | Number of fractional digits | |
| 98 | | | | used in international | |
| 99 | | | | formatting of monetary values. | |
| 100 | +----------------------+-------------------------------------+--------------------------------+ |
| 101 | | | ``'mon_thousands_sep'`` | Group separator used for | |
| 102 | | | | monetary values. | |
| 103 | +----------------------+-------------------------------------+--------------------------------+ |
| 104 | | | ``'mon_grouping'`` | Equivalent to ``'grouping'``, | |
| 105 | | | | used for monetary values. | |
| 106 | +----------------------+-------------------------------------+--------------------------------+ |
| 107 | | | ``'positive_sign'`` | Symbol used to annotate a | |
| 108 | | | | positive monetary value. | |
| 109 | +----------------------+-------------------------------------+--------------------------------+ |
| 110 | | | ``'negative_sign'`` | Symbol used to annotate a | |
| 111 | | | | negative monetary value. | |
| 112 | +----------------------+-------------------------------------+--------------------------------+ |
| 113 | | | ``'p_sign_posn/n_sign_posn'`` | The position of the sign (for | |
| 114 | | | | positive resp. negative | |
| 115 | | | | values), see below. | |
| 116 | +----------------------+-------------------------------------+--------------------------------+ |
| 117 | |
| 118 | All numeric values can be set to :const:`CHAR_MAX` to indicate that there is no |
| 119 | value specified in this locale. |
| 120 | |
| 121 | The possible values for ``'p_sign_posn'`` and ``'n_sign_posn'`` are given below. |
| 122 | |
| 123 | +--------------+-----------------------------------------+ |
| 124 | | Value | Explanation | |
| 125 | +==============+=========================================+ |
| 126 | | ``0`` | Currency and value are surrounded by | |
| 127 | | | parentheses. | |
| 128 | +--------------+-----------------------------------------+ |
| 129 | | ``1`` | The sign should precede the value and | |
| 130 | | | currency symbol. | |
| 131 | +--------------+-----------------------------------------+ |
| 132 | | ``2`` | The sign should follow the value and | |
| 133 | | | currency symbol. | |
| 134 | +--------------+-----------------------------------------+ |
| 135 | | ``3`` | The sign should immediately precede the | |
| 136 | | | value. | |
| 137 | +--------------+-----------------------------------------+ |
| 138 | | ``4`` | The sign should immediately follow the | |
| 139 | | | value. | |
| 140 | +--------------+-----------------------------------------+ |
| 141 | | ``CHAR_MAX`` | Nothing is specified in this locale. | |
| 142 | +--------------+-----------------------------------------+ |
| 143 | |
| 144 | |
| 145 | .. function:: nl_langinfo(option) |
| 146 | |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 147 | Return some locale-specific information as a string. This function is not |
| 148 | available on all systems, and the set of possible options might also vary |
| 149 | across platforms. The possible argument values are numbers, for which |
| 150 | symbolic constants are available in the locale module. |
| 151 | |
| 152 | The :func:`nl_langinfo` function accepts one of the following keys. Most |
| 153 | descriptions are taken from the corresponding description in the GNU C |
| 154 | library. |
| 155 | |
| 156 | .. data:: CODESET |
| 157 | |
| 158 | Get a string with the name of the character encoding used in the |
| 159 | selected locale. |
| 160 | |
| 161 | .. data:: D_T_FMT |
| 162 | |
| 163 | Get a string that can be used as a format string for :func:`strftime` to |
Georg Brandl | 1d0a0f5 | 2011-03-06 11:09:51 +0100 | [diff] [blame] | 164 | represent date and time in a locale-specific way. |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 165 | |
| 166 | .. data:: D_FMT |
| 167 | |
| 168 | Get a string that can be used as a format string for :func:`strftime` to |
| 169 | represent a date in a locale-specific way. |
| 170 | |
| 171 | .. data:: T_FMT |
| 172 | |
| 173 | Get a string that can be used as a format string for :func:`strftime` to |
| 174 | represent a time in a locale-specific way. |
| 175 | |
| 176 | .. data:: T_FMT_AMPM |
| 177 | |
| 178 | Get a format string for :func:`strftime` to represent time in the am/pm |
| 179 | format. |
| 180 | |
| 181 | .. data:: DAY_1 ... DAY_7 |
| 182 | |
| 183 | Get the name of the n-th day of the week. |
| 184 | |
| 185 | .. note:: |
| 186 | |
| 187 | This follows the US convention of :const:`DAY_1` being Sunday, not the |
| 188 | international convention (ISO 8601) that Monday is the first day of the |
| 189 | week. |
| 190 | |
| 191 | .. data:: ABDAY_1 ... ABDAY_7 |
| 192 | |
| 193 | Get the abbreviated name of the n-th day of the week. |
| 194 | |
| 195 | .. data:: MON_1 ... MON_12 |
| 196 | |
| 197 | Get the name of the n-th month. |
| 198 | |
| 199 | .. data:: ABMON_1 ... ABMON_12 |
| 200 | |
| 201 | Get the abbreviated name of the n-th month. |
| 202 | |
| 203 | .. data:: RADIXCHAR |
| 204 | |
| 205 | Get the radix character (decimal dot, decimal comma, etc.) |
| 206 | |
| 207 | .. data:: THOUSEP |
| 208 | |
| 209 | Get the separator character for thousands (groups of three digits). |
| 210 | |
| 211 | .. data:: YESEXPR |
| 212 | |
| 213 | Get a regular expression that can be used with the regex function to |
| 214 | recognize a positive response to a yes/no question. |
| 215 | |
| 216 | .. note:: |
| 217 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 218 | The expression is in the syntax suitable for the :c:func:`regex` function |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 219 | from the C library, which might differ from the syntax used in :mod:`re`. |
| 220 | |
| 221 | .. data:: NOEXPR |
| 222 | |
| 223 | Get a regular expression that can be used with the regex(3) function to |
| 224 | recognize a negative response to a yes/no question. |
| 225 | |
| 226 | .. data:: CRNCYSTR |
| 227 | |
| 228 | Get the currency symbol, preceded by "-" if the symbol should appear before |
| 229 | the value, "+" if the symbol should appear after the value, or "." if the |
| 230 | symbol should replace the radix character. |
| 231 | |
| 232 | .. data:: ERA |
| 233 | |
| 234 | Get a string that represents the era used in the current locale. |
| 235 | |
| 236 | Most locales do not define this value. An example of a locale which does |
| 237 | define this value is the Japanese one. In Japan, the traditional |
| 238 | representation of dates includes the name of the era corresponding to the |
| 239 | then-emperor's reign. |
| 240 | |
| 241 | Normally it should not be necessary to use this value directly. Specifying |
| 242 | the ``E`` modifier in their format strings causes the :func:`strftime` |
| 243 | function to use this information. The format of the returned string is not |
| 244 | specified, and therefore you should not assume knowledge of it on different |
| 245 | systems. |
| 246 | |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 247 | .. data:: ERA_D_T_FMT |
| 248 | |
Georg Brandl | 1d0a0f5 | 2011-03-06 11:09:51 +0100 | [diff] [blame] | 249 | Get a format string for :func:`strftime` to represent date and time in a |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 250 | locale-specific era-based way. |
| 251 | |
| 252 | .. data:: ERA_D_FMT |
| 253 | |
Georg Brandl | 1d0a0f5 | 2011-03-06 11:09:51 +0100 | [diff] [blame] | 254 | Get a format string for :func:`strftime` to represent a date in a |
| 255 | locale-specific era-based way. |
| 256 | |
| 257 | .. data:: ERA_T_FMT |
| 258 | |
| 259 | Get a format string for :func:`strftime` to represent a time in a |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 260 | locale-specific era-based way. |
| 261 | |
| 262 | .. data:: ALT_DIGITS |
| 263 | |
| 264 | Get a representation of up to 100 values used to represent the values |
| 265 | 0 to 99. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 266 | |
| 267 | |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 268 | .. function:: getdefaultlocale([envvars]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 269 | |
| 270 | Tries to determine the default locale settings and returns them as a tuple of |
| 271 | the form ``(language code, encoding)``. |
| 272 | |
| 273 | According to POSIX, a program which has not called ``setlocale(LC_ALL, '')`` |
| 274 | runs using the portable ``'C'`` locale. Calling ``setlocale(LC_ALL, '')`` lets |
| 275 | it use the default locale as defined by the :envvar:`LANG` variable. Since we |
| 276 | do not want to interfere with the current locale setting we thus emulate the |
| 277 | behavior in the way described above. |
| 278 | |
| 279 | To maintain compatibility with other platforms, not only the :envvar:`LANG` |
| 280 | variable is tested, but a list of variables given as envvars parameter. The |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 281 | first found to be defined will be used. *envvars* defaults to the search |
| 282 | path used in GNU gettext; it must always contain the variable name |
| 283 | ``'LANG'``. The GNU gettext search path contains ``'LC_ALL'``, |
| 284 | ``'LC_CTYPE'``, ``'LANG'`` and ``'LANGUAGE'``, in that order. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
| 286 | Except for the code ``'C'``, the language code corresponds to :rfc:`1766`. |
| 287 | *language code* and *encoding* may be ``None`` if their values cannot be |
| 288 | determined. |
| 289 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 290 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 291 | .. function:: getlocale(category=LC_CTYPE) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 292 | |
| 293 | Returns the current setting for the given locale category as sequence containing |
| 294 | *language code*, *encoding*. *category* may be one of the :const:`LC_\*` values |
| 295 | except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`. |
| 296 | |
| 297 | Except for the code ``'C'``, the language code corresponds to :rfc:`1766`. |
| 298 | *language code* and *encoding* may be ``None`` if their values cannot be |
| 299 | determined. |
| 300 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 301 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 302 | .. function:: getpreferredencoding(do_setlocale=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 303 | |
| 304 | Return the encoding used for text data, according to user preferences. User |
| 305 | preferences are expressed differently on different systems, and might not be |
| 306 | available programmatically on some systems, so this function only returns a |
| 307 | guess. |
| 308 | |
| 309 | On some systems, it is necessary to invoke :func:`setlocale` to obtain the user |
| 310 | preferences, so this function is not thread-safe. If invoking setlocale is not |
| 311 | necessary or desired, *do_setlocale* should be set to ``False``. |
| 312 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 313 | |
| 314 | .. function:: normalize(localename) |
| 315 | |
| 316 | Returns a normalized locale code for the given locale name. The returned locale |
| 317 | code is formatted for use with :func:`setlocale`. If normalization fails, the |
| 318 | original name is returned unchanged. |
| 319 | |
| 320 | If the given encoding is not known, the function defaults to the default |
| 321 | encoding for the locale code just like :func:`setlocale`. |
| 322 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 323 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 324 | .. function:: resetlocale(category=LC_ALL) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 325 | |
| 326 | Sets the locale for *category* to the default setting. |
| 327 | |
| 328 | The default setting is determined by calling :func:`getdefaultlocale`. |
| 329 | *category* defaults to :const:`LC_ALL`. |
| 330 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 331 | |
| 332 | .. function:: strcoll(string1, string2) |
| 333 | |
| 334 | Compares two strings according to the current :const:`LC_COLLATE` setting. As |
| 335 | any other compare function, returns a negative, or a positive value, or ``0``, |
| 336 | depending on whether *string1* collates before or after *string2* or is equal to |
| 337 | it. |
| 338 | |
| 339 | |
| 340 | .. function:: strxfrm(string) |
| 341 | |
Mark Dickinson | c48d834 | 2009-02-01 14:18:10 +0000 | [diff] [blame] | 342 | Transforms a string to one that can be used in locale-aware |
| 343 | comparisons. For example, ``strxfrm(s1) < strxfrm(s2)`` is |
| 344 | equivalent to ``strcoll(s1, s2) < 0``. This function can be used |
| 345 | when the same string is compared repeatedly, e.g. when collating a |
| 346 | sequence of strings. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 347 | |
| 348 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 349 | .. function:: format(format, val, grouping=False, monetary=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 350 | |
| 351 | Formats a number *val* according to the current :const:`LC_NUMERIC` setting. |
| 352 | The format follows the conventions of the ``%`` operator. For floating point |
| 353 | values, the decimal point is modified if appropriate. If *grouping* is true, |
| 354 | also takes the grouping into account. |
| 355 | |
| 356 | If *monetary* is true, the conversion uses monetary thousands separator and |
| 357 | grouping strings. |
| 358 | |
| 359 | Please note that this function will only work for exactly one %char specifier. |
| 360 | For whole format strings, use :func:`format_string`. |
| 361 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 362 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 363 | .. function:: format_string(format, val, grouping=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 364 | |
| 365 | Processes formatting specifiers as in ``format % val``, but takes the current |
| 366 | locale settings into account. |
| 367 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 368 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 369 | .. function:: currency(val, symbol=True, grouping=False, international=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 370 | |
| 371 | Formats a number *val* according to the current :const:`LC_MONETARY` settings. |
| 372 | |
| 373 | The returned string includes the currency symbol if *symbol* is true, which is |
| 374 | the default. If *grouping* is true (which is not the default), grouping is done |
| 375 | with the value. If *international* is true (which is not the default), the |
| 376 | international currency symbol is used. |
| 377 | |
| 378 | Note that this function will not work with the 'C' locale, so you have to set a |
| 379 | locale via :func:`setlocale` first. |
| 380 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 381 | |
| 382 | .. function:: str(float) |
| 383 | |
| 384 | Formats a floating point number using the same format as the built-in function |
| 385 | ``str(float)``, but takes the decimal point into account. |
| 386 | |
| 387 | |
| 388 | .. function:: atof(string) |
| 389 | |
| 390 | Converts a string to a floating point number, following the :const:`LC_NUMERIC` |
| 391 | settings. |
| 392 | |
| 393 | |
| 394 | .. function:: atoi(string) |
| 395 | |
| 396 | Converts a string to an integer, following the :const:`LC_NUMERIC` conventions. |
| 397 | |
| 398 | |
| 399 | .. data:: LC_CTYPE |
| 400 | |
| 401 | .. index:: module: string |
| 402 | |
| 403 | Locale category for the character type functions. Depending on the settings of |
| 404 | this category, the functions of module :mod:`string` dealing with case change |
| 405 | their behaviour. |
| 406 | |
| 407 | |
| 408 | .. data:: LC_COLLATE |
| 409 | |
| 410 | Locale category for sorting strings. The functions :func:`strcoll` and |
| 411 | :func:`strxfrm` of the :mod:`locale` module are affected. |
| 412 | |
| 413 | |
| 414 | .. data:: LC_TIME |
| 415 | |
| 416 | Locale category for the formatting of time. The function :func:`time.strftime` |
| 417 | follows these conventions. |
| 418 | |
| 419 | |
| 420 | .. data:: LC_MONETARY |
| 421 | |
| 422 | Locale category for formatting of monetary values. The available options are |
| 423 | available from the :func:`localeconv` function. |
| 424 | |
| 425 | |
| 426 | .. data:: LC_MESSAGES |
| 427 | |
| 428 | Locale category for message display. Python currently does not support |
| 429 | application specific locale-aware messages. Messages displayed by the operating |
| 430 | system, like those returned by :func:`os.strerror` might be affected by this |
| 431 | category. |
| 432 | |
| 433 | |
| 434 | .. data:: LC_NUMERIC |
| 435 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 436 | Locale category for formatting numbers. The functions :func:`.format`, |
| 437 | :func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`locale` module are |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 438 | affected by that category. All other numeric formatting operations are not |
| 439 | affected. |
| 440 | |
| 441 | |
| 442 | .. data:: LC_ALL |
| 443 | |
| 444 | Combination of all locale settings. If this flag is used when the locale is |
| 445 | changed, setting the locale for all categories is attempted. If that fails for |
| 446 | any category, no category is changed at all. When the locale is retrieved using |
| 447 | this flag, a string indicating the setting for all categories is returned. This |
| 448 | string can be later used to restore the settings. |
| 449 | |
| 450 | |
| 451 | .. data:: CHAR_MAX |
| 452 | |
| 453 | This is a symbolic constant used for different values returned by |
| 454 | :func:`localeconv`. |
| 455 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 456 | |
| 457 | Example:: |
| 458 | |
| 459 | >>> import locale |
Benjamin Peterson | f608c61 | 2008-11-16 18:33:53 +0000 | [diff] [blame] | 460 | >>> loc = locale.getlocale() # get current locale |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 461 | # use German locale; name might vary with platform |
| 462 | >>> locale.setlocale(locale.LC_ALL, 'de_DE') |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 463 | >>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 464 | >>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale |
| 465 | >>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale |
| 466 | >>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale |
| 467 | |
| 468 | |
| 469 | Background, details, hints, tips and caveats |
| 470 | -------------------------------------------- |
| 471 | |
| 472 | The C standard defines the locale as a program-wide property that may be |
| 473 | relatively expensive to change. On top of that, some implementation are broken |
| 474 | in such a way that frequent locale changes may cause core dumps. This makes the |
| 475 | locale somewhat painful to use correctly. |
| 476 | |
| 477 | Initially, when a program is started, the locale is the ``C`` locale, no matter |
| 478 | what the user's preferred locale is. The program must explicitly say that it |
| 479 | wants the user's preferred locale settings by calling ``setlocale(LC_ALL, '')``. |
| 480 | |
| 481 | It is generally a bad idea to call :func:`setlocale` in some library routine, |
| 482 | since as a side effect it affects the entire program. Saving and restoring it |
| 483 | is almost as bad: it is expensive and affects other threads that happen to run |
| 484 | before the settings have been restored. |
| 485 | |
| 486 | If, when coding a module for general use, you need a locale independent version |
Guido van Rossum | 8d2ef87 | 2007-10-15 15:42:31 +0000 | [diff] [blame] | 487 | of an operation that is affected by the locale (such as |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 488 | certain formats used with :func:`time.strftime`), you will have to find a way to |
| 489 | do it without using the standard library routine. Even better is convincing |
| 490 | yourself that using locale settings is okay. Only as a last resort should you |
| 491 | document that your module is not compatible with non-\ ``C`` locale settings. |
| 492 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 493 | The only way to perform numeric operations according to the locale is to use the |
| 494 | special functions defined by this module: :func:`atof`, :func:`atoi`, |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 495 | :func:`.format`, :func:`.str`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 496 | |
Guido van Rossum | 8d2ef87 | 2007-10-15 15:42:31 +0000 | [diff] [blame] | 497 | There is no way to perform case conversions and character classifications |
| 498 | according to the locale. For (Unicode) text strings these are done according |
| 499 | to the character value only, while for byte strings, the conversions and |
| 500 | classifications are done according to the ASCII value of the byte, and bytes |
| 501 | whose high bit is set (i.e., non-ASCII bytes) are never converted or considered |
| 502 | part of a character class such as letter or whitespace. |
| 503 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 504 | |
| 505 | .. _embedding-locale: |
| 506 | |
| 507 | For extension writers and programs that embed Python |
| 508 | ---------------------------------------------------- |
| 509 | |
| 510 | Extension modules should never call :func:`setlocale`, except to find out what |
| 511 | the current locale is. But since the return value can only be used portably to |
| 512 | restore it, that is not very useful (except perhaps to find out whether or not |
| 513 | the locale is ``C``). |
| 514 | |
| 515 | When Python code uses the :mod:`locale` module to change the locale, this also |
| 516 | affects the embedding application. If the embedding application doesn't want |
| 517 | this to happen, it should remove the :mod:`_locale` extension module (which does |
| 518 | all the work) from the table of built-in modules in the :file:`config.c` file, |
| 519 | and make sure that the :mod:`_locale` module is not accessible as a shared |
| 520 | library. |
| 521 | |
| 522 | |
| 523 | .. _locale-gettext: |
| 524 | |
| 525 | Access to message catalogs |
| 526 | -------------------------- |
| 527 | |
| 528 | The locale module exposes the C library's gettext interface on systems that |
| 529 | provide this interface. It consists of the functions :func:`gettext`, |
| 530 | :func:`dgettext`, :func:`dcgettext`, :func:`textdomain`, :func:`bindtextdomain`, |
| 531 | and :func:`bind_textdomain_codeset`. These are similar to the same functions in |
| 532 | the :mod:`gettext` module, but use the C library's binary format for message |
| 533 | catalogs, and the C library's search algorithms for locating message catalogs. |
| 534 | |
| 535 | Python applications should normally find no need to invoke these functions, and |
| 536 | should use :mod:`gettext` instead. A known exception to this rule are |
Georg Brandl | 599dbfc | 2010-10-26 19:58:11 +0000 | [diff] [blame] | 537 | applications that link with additional C libraries which internally invoke |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 538 | :c:func:`gettext` or :func:`dcgettext`. For these applications, it may be |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 539 | necessary to bind the text domain, so that the libraries can properly locate |
| 540 | their message catalogs. |
| 541 | |