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