blob: bf57a0835591682c2abb0402692ef93f59d7ce55 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`locale` --- Internationalization services
2===============================================
3
4.. module:: locale
5 :synopsis: Internationalization services.
Terry Jan Reedyfa089b92016-06-11 15:02:54 -04006
Georg Brandl116aa622007-08-15 14:28:22 +00007.. moduleauthor:: Martin von Löwis <martin@v.loewis.de>
8.. sectionauthor:: Martin von Löwis <martin@v.loewis.de>
9
Terry Jan Reedyfa089b92016-06-11 15:02:54 -040010**Source code:** :source:`Lib/locale.py`
11
12--------------
Georg Brandl116aa622007-08-15 14:28:22 +000013
14The :mod:`locale` module opens access to the POSIX locale database and
15functionality. The POSIX locale mechanism allows programmers to deal with
16certain cultural issues in an application, without requiring the programmer to
17know all the specifics of each country where the software is executed.
18
19.. index:: module: _locale
20
21The :mod:`locale` module is implemented on top of the :mod:`_locale` module,
22which in turn uses an ANSI C locale implementation if available.
23
24The :mod:`locale` module defines the following exception and functions:
25
26
27.. exception:: Error
28
Petri Lehtinen395ca722011-11-05 10:18:50 +020029 Exception raised when the locale passed to :func:`setlocale` is not
30 recognized.
Georg Brandl116aa622007-08-15 14:28:22 +000031
32
Georg Brandlcd7f32b2009-06-08 09:13:45 +000033.. function:: setlocale(category, locale=None)
Georg Brandl116aa622007-08-15 14:28:22 +000034
Petri Lehtinen395ca722011-11-05 10:18:50 +020035 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 Brandl116aa622007-08-15 14:28:22 +000042
43 If *locale* is omitted or ``None``, the current setting for *category* is
44 returned.
45
Georg Brandlf285bcc2010-10-19 21:07:16 +000046 :func:`setlocale` is not thread-safe on most systems. Applications typically
Georg Brandl116aa622007-08-15 14:28:22 +000047 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 Brandl116aa622007-08-15 14:28:22 +000056
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 Brandl44ea77b2013-03-28 13:28:44 +010062 .. tabularcolumns:: |l|l|L|
63
Georg Brandl116aa622007-08-15 14:28:22 +000064 +----------------------+-------------------------------------+--------------------------------+
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
Victor Stinnercb064fc2018-01-15 15:58:02 +0100150 The function sets temporarily the ``LC_CTYPE`` locale to the ``LC_NUMERIC``
Victor Stinner02e6bf72018-11-20 16:20:16 +0100151 locale or the ``LC_MONETARY`` locale if locales are different and numeric or
152 monetary strings are non-ASCII. This temporary change affects other threads.
Victor Stinnercb064fc2018-01-15 15:58:02 +0100153
154 .. versionchanged:: 3.7
155 The function now sets temporarily the ``LC_CTYPE`` locale to the
156 ``LC_NUMERIC`` locale in some cases.
157
Georg Brandl116aa622007-08-15 14:28:22 +0000158
159.. function:: nl_langinfo(option)
160
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000161 Return some locale-specific information as a string. This function is not
162 available on all systems, and the set of possible options might also vary
163 across platforms. The possible argument values are numbers, for which
164 symbolic constants are available in the locale module.
165
166 The :func:`nl_langinfo` function accepts one of the following keys. Most
167 descriptions are taken from the corresponding description in the GNU C
168 library.
169
170 .. data:: CODESET
171
172 Get a string with the name of the character encoding used in the
173 selected locale.
174
175 .. data:: D_T_FMT
176
Sandro Tosi964f2052012-06-02 18:22:02 +0200177 Get a string that can be used as a format string for :func:`time.strftime` to
Georg Brandl1d0a0f52011-03-06 11:09:51 +0100178 represent date and time in a locale-specific way.
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000179
180 .. data:: D_FMT
181
Sandro Tosi964f2052012-06-02 18:22:02 +0200182 Get a string that can be used as a format string for :func:`time.strftime` to
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000183 represent a date in a locale-specific way.
184
185 .. data:: T_FMT
186
Sandro Tosi964f2052012-06-02 18:22:02 +0200187 Get a string that can be used as a format string for :func:`time.strftime` to
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000188 represent a time in a locale-specific way.
189
190 .. data:: T_FMT_AMPM
191
Sandro Tosi964f2052012-06-02 18:22:02 +0200192 Get a format string for :func:`time.strftime` to represent time in the am/pm
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000193 format.
194
195 .. data:: DAY_1 ... DAY_7
196
197 Get the name of the n-th day of the week.
198
199 .. note::
200
201 This follows the US convention of :const:`DAY_1` being Sunday, not the
202 international convention (ISO 8601) that Monday is the first day of the
203 week.
204
205 .. data:: ABDAY_1 ... ABDAY_7
206
207 Get the abbreviated name of the n-th day of the week.
208
209 .. data:: MON_1 ... MON_12
210
211 Get the name of the n-th month.
212
213 .. data:: ABMON_1 ... ABMON_12
214
215 Get the abbreviated name of the n-th month.
216
217 .. data:: RADIXCHAR
218
Martin Panterd21e0b52015-10-10 10:36:22 +0000219 Get the radix character (decimal dot, decimal comma, etc.).
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000220
221 .. data:: THOUSEP
222
223 Get the separator character for thousands (groups of three digits).
224
225 .. data:: YESEXPR
226
227 Get a regular expression that can be used with the regex function to
228 recognize a positive response to a yes/no question.
229
230 .. note::
231
Georg Brandl60203b42010-10-06 10:11:56 +0000232 The expression is in the syntax suitable for the :c:func:`regex` function
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000233 from the C library, which might differ from the syntax used in :mod:`re`.
234
235 .. data:: NOEXPR
236
237 Get a regular expression that can be used with the regex(3) function to
238 recognize a negative response to a yes/no question.
239
240 .. data:: CRNCYSTR
241
242 Get the currency symbol, preceded by "-" if the symbol should appear before
243 the value, "+" if the symbol should appear after the value, or "." if the
244 symbol should replace the radix character.
245
246 .. data:: ERA
247
248 Get a string that represents the era used in the current locale.
249
250 Most locales do not define this value. An example of a locale which does
251 define this value is the Japanese one. In Japan, the traditional
252 representation of dates includes the name of the era corresponding to the
253 then-emperor's reign.
254
255 Normally it should not be necessary to use this value directly. Specifying
Sandro Tosi964f2052012-06-02 18:22:02 +0200256 the ``E`` modifier in their format strings causes the :func:`time.strftime`
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000257 function to use this information. The format of the returned string is not
258 specified, and therefore you should not assume knowledge of it on different
259 systems.
260
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000261 .. data:: ERA_D_T_FMT
262
Sandro Tosi964f2052012-06-02 18:22:02 +0200263 Get a format string for :func:`time.strftime` to represent date and time in a
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000264 locale-specific era-based way.
265
266 .. data:: ERA_D_FMT
267
Sandro Tosi964f2052012-06-02 18:22:02 +0200268 Get a format string for :func:`time.strftime` to represent a date in a
Georg Brandl1d0a0f52011-03-06 11:09:51 +0100269 locale-specific era-based way.
270
271 .. data:: ERA_T_FMT
272
Sandro Tosi964f2052012-06-02 18:22:02 +0200273 Get a format string for :func:`time.strftime` to represent a time in a
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000274 locale-specific era-based way.
275
276 .. data:: ALT_DIGITS
277
278 Get a representation of up to 100 values used to represent the values
279 0 to 99.
Georg Brandl116aa622007-08-15 14:28:22 +0000280
281
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000282.. function:: getdefaultlocale([envvars])
Georg Brandl116aa622007-08-15 14:28:22 +0000283
284 Tries to determine the default locale settings and returns them as a tuple of
285 the form ``(language code, encoding)``.
286
287 According to POSIX, a program which has not called ``setlocale(LC_ALL, '')``
288 runs using the portable ``'C'`` locale. Calling ``setlocale(LC_ALL, '')`` lets
289 it use the default locale as defined by the :envvar:`LANG` variable. Since we
290 do not want to interfere with the current locale setting we thus emulate the
291 behavior in the way described above.
292
293 To maintain compatibility with other platforms, not only the :envvar:`LANG`
294 variable is tested, but a list of variables given as envvars parameter. The
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000295 first found to be defined will be used. *envvars* defaults to the search
296 path used in GNU gettext; it must always contain the variable name
297 ``'LANG'``. The GNU gettext search path contains ``'LC_ALL'``,
298 ``'LC_CTYPE'``, ``'LANG'`` and ``'LANGUAGE'``, in that order.
Georg Brandl116aa622007-08-15 14:28:22 +0000299
300 Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
301 *language code* and *encoding* may be ``None`` if their values cannot be
302 determined.
303
Georg Brandl116aa622007-08-15 14:28:22 +0000304
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000305.. function:: getlocale(category=LC_CTYPE)
Georg Brandl116aa622007-08-15 14:28:22 +0000306
307 Returns the current setting for the given locale category as sequence containing
308 *language code*, *encoding*. *category* may be one of the :const:`LC_\*` values
309 except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`.
310
311 Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
312 *language code* and *encoding* may be ``None`` if their values cannot be
313 determined.
314
Georg Brandl116aa622007-08-15 14:28:22 +0000315
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000316.. function:: getpreferredencoding(do_setlocale=True)
Georg Brandl116aa622007-08-15 14:28:22 +0000317
318 Return the encoding used for text data, according to user preferences. User
319 preferences are expressed differently on different systems, and might not be
320 available programmatically on some systems, so this function only returns a
321 guess.
322
323 On some systems, it is necessary to invoke :func:`setlocale` to obtain the user
324 preferences, so this function is not thread-safe. If invoking setlocale is not
325 necessary or desired, *do_setlocale* should be set to ``False``.
326
Victor Stinner91106cd2017-12-13 12:29:09 +0100327 On Android or in the UTF-8 mode (:option:`-X` ``utf8`` option), always
328 return ``'UTF-8'``, the locale and the *do_setlocale* argument are ignored.
329
330 .. versionchanged:: 3.7
331 The function now always returns ``UTF-8`` on Android or if the UTF-8 mode
332 is enabled.
333
Georg Brandl116aa622007-08-15 14:28:22 +0000334
335.. function:: normalize(localename)
336
337 Returns a normalized locale code for the given locale name. The returned locale
338 code is formatted for use with :func:`setlocale`. If normalization fails, the
339 original name is returned unchanged.
340
341 If the given encoding is not known, the function defaults to the default
342 encoding for the locale code just like :func:`setlocale`.
343
Georg Brandl116aa622007-08-15 14:28:22 +0000344
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000345.. function:: resetlocale(category=LC_ALL)
Georg Brandl116aa622007-08-15 14:28:22 +0000346
347 Sets the locale for *category* to the default setting.
348
349 The default setting is determined by calling :func:`getdefaultlocale`.
350 *category* defaults to :const:`LC_ALL`.
351
Georg Brandl116aa622007-08-15 14:28:22 +0000352
353.. function:: strcoll(string1, string2)
354
355 Compares two strings according to the current :const:`LC_COLLATE` setting. As
356 any other compare function, returns a negative, or a positive value, or ``0``,
357 depending on whether *string1* collates before or after *string2* or is equal to
358 it.
359
360
361.. function:: strxfrm(string)
362
Mark Dickinsonc48d8342009-02-01 14:18:10 +0000363 Transforms a string to one that can be used in locale-aware
364 comparisons. For example, ``strxfrm(s1) < strxfrm(s2)`` is
365 equivalent to ``strcoll(s1, s2) < 0``. This function can be used
366 when the same string is compared repeatedly, e.g. when collating a
367 sequence of strings.
Georg Brandl116aa622007-08-15 14:28:22 +0000368
369
Garvit Khatri1cf93a72017-03-28 23:43:38 +0800370.. function:: format_string(format, val, grouping=False, monetary=False)
Georg Brandl116aa622007-08-15 14:28:22 +0000371
372 Formats a number *val* according to the current :const:`LC_NUMERIC` setting.
373 The format follows the conventions of the ``%`` operator. For floating point
374 values, the decimal point is modified if appropriate. If *grouping* is true,
375 also takes the grouping into account.
376
377 If *monetary* is true, the conversion uses monetary thousands separator and
378 grouping strings.
379
Georg Brandl116aa622007-08-15 14:28:22 +0000380 Processes formatting specifiers as in ``format % val``, but takes the current
381 locale settings into account.
382
Garvit Khatri1cf93a72017-03-28 23:43:38 +0800383 .. versionchanged:: 3.7
384 The *monetary* keyword parameter was added.
385
386
387.. function:: format(format, val, grouping=False, monetary=False)
388
Berker Peksag6dbdedb2017-04-20 07:38:43 +0300389 Please note that this function works like :meth:`format_string` but will
390 only work for exactly one ``%char`` specifier. For example, ``'%f'`` and
Victor Stinner8c663fd2017-11-08 14:44:44 -0800391 ``'%.0f'`` are both valid specifiers, but ``'%f KiB'`` is not.
Garvit Khatri1cf93a72017-03-28 23:43:38 +0800392
393 For whole format strings, use :func:`format_string`.
394
395 .. deprecated:: 3.7
Berker Peksag6dbdedb2017-04-20 07:38:43 +0300396 Use :meth:`format_string` instead.
Garvit Khatri1cf93a72017-03-28 23:43:38 +0800397
Georg Brandl116aa622007-08-15 14:28:22 +0000398
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000399.. function:: currency(val, symbol=True, grouping=False, international=False)
Georg Brandl116aa622007-08-15 14:28:22 +0000400
401 Formats a number *val* according to the current :const:`LC_MONETARY` settings.
402
403 The returned string includes the currency symbol if *symbol* is true, which is
404 the default. If *grouping* is true (which is not the default), grouping is done
405 with the value. If *international* is true (which is not the default), the
406 international currency symbol is used.
407
408 Note that this function will not work with the 'C' locale, so you have to set a
409 locale via :func:`setlocale` first.
410
Georg Brandl116aa622007-08-15 14:28:22 +0000411
412.. function:: str(float)
413
414 Formats a floating point number using the same format as the built-in function
415 ``str(float)``, but takes the decimal point into account.
416
417
Antoine Pitroub64bca92014-10-23 22:52:31 +0200418.. function:: delocalize(string)
419
420 Converts a string into a normalized number string, following the
Antoine Pitrou821b5a12014-10-23 23:03:35 +0200421 :const:`LC_NUMERIC` settings.
Antoine Pitroub64bca92014-10-23 22:52:31 +0200422
423 .. versionadded:: 3.5
424
425
Georg Brandl116aa622007-08-15 14:28:22 +0000426.. function:: atof(string)
427
428 Converts a string to a floating point number, following the :const:`LC_NUMERIC`
429 settings.
430
431
432.. function:: atoi(string)
433
434 Converts a string to an integer, following the :const:`LC_NUMERIC` conventions.
435
436
437.. data:: LC_CTYPE
438
439 .. index:: module: string
440
441 Locale category for the character type functions. Depending on the settings of
442 this category, the functions of module :mod:`string` dealing with case change
443 their behaviour.
444
445
446.. data:: LC_COLLATE
447
448 Locale category for sorting strings. The functions :func:`strcoll` and
449 :func:`strxfrm` of the :mod:`locale` module are affected.
450
451
452.. data:: LC_TIME
453
454 Locale category for the formatting of time. The function :func:`time.strftime`
455 follows these conventions.
456
457
458.. data:: LC_MONETARY
459
460 Locale category for formatting of monetary values. The available options are
461 available from the :func:`localeconv` function.
462
463
464.. data:: LC_MESSAGES
465
466 Locale category for message display. Python currently does not support
467 application specific locale-aware messages. Messages displayed by the operating
468 system, like those returned by :func:`os.strerror` might be affected by this
469 category.
470
471
472.. data:: LC_NUMERIC
473
Georg Brandl502d9a52009-07-26 15:02:41 +0000474 Locale category for formatting numbers. The functions :func:`.format`,
475 :func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`locale` module are
Georg Brandl116aa622007-08-15 14:28:22 +0000476 affected by that category. All other numeric formatting operations are not
477 affected.
478
479
480.. data:: LC_ALL
481
482 Combination of all locale settings. If this flag is used when the locale is
483 changed, setting the locale for all categories is attempted. If that fails for
484 any category, no category is changed at all. When the locale is retrieved using
485 this flag, a string indicating the setting for all categories is returned. This
486 string can be later used to restore the settings.
487
488
489.. data:: CHAR_MAX
490
491 This is a symbolic constant used for different values returned by
492 :func:`localeconv`.
493
Georg Brandl116aa622007-08-15 14:28:22 +0000494
495Example::
496
497 >>> import locale
Serhiy Storchakadba90392016-05-10 12:01:23 +0300498 >>> loc = locale.getlocale() # get current locale
Alexandre Vassalotti711ed4a2009-07-17 10:42:05 +0000499 # use German locale; name might vary with platform
500 >>> locale.setlocale(locale.LC_ALL, 'de_DE')
Serhiy Storchakadba90392016-05-10 12:01:23 +0300501 >>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
502 >>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
503 >>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
504 >>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
Georg Brandl116aa622007-08-15 14:28:22 +0000505
506
507Background, details, hints, tips and caveats
508--------------------------------------------
509
510The C standard defines the locale as a program-wide property that may be
511relatively expensive to change. On top of that, some implementation are broken
512in such a way that frequent locale changes may cause core dumps. This makes the
513locale somewhat painful to use correctly.
514
515Initially, when a program is started, the locale is the ``C`` locale, no matter
Victor Stinnera01f1ad2012-06-06 01:37:37 +0200516what the user's preferred locale is. There is one exception: the
517:data:`LC_CTYPE` category is changed at startup to set the current locale
518encoding to the user's preferred locale encoding. The program must explicitly
519say that it wants the user's preferred locale settings for other categories by
520calling ``setlocale(LC_ALL, '')``.
Georg Brandl116aa622007-08-15 14:28:22 +0000521
522It is generally a bad idea to call :func:`setlocale` in some library routine,
523since as a side effect it affects the entire program. Saving and restoring it
524is almost as bad: it is expensive and affects other threads that happen to run
525before the settings have been restored.
526
527If, when coding a module for general use, you need a locale independent version
Guido van Rossum8d2ef872007-10-15 15:42:31 +0000528of an operation that is affected by the locale (such as
Georg Brandl116aa622007-08-15 14:28:22 +0000529certain formats used with :func:`time.strftime`), you will have to find a way to
530do it without using the standard library routine. Even better is convincing
531yourself that using locale settings is okay. Only as a last resort should you
532document that your module is not compatible with non-\ ``C`` locale settings.
533
Georg Brandl116aa622007-08-15 14:28:22 +0000534The only way to perform numeric operations according to the locale is to use the
535special functions defined by this module: :func:`atof`, :func:`atoi`,
Georg Brandl502d9a52009-07-26 15:02:41 +0000536:func:`.format`, :func:`.str`.
Georg Brandl116aa622007-08-15 14:28:22 +0000537
Guido van Rossum8d2ef872007-10-15 15:42:31 +0000538There is no way to perform case conversions and character classifications
539according to the locale. For (Unicode) text strings these are done according
540to the character value only, while for byte strings, the conversions and
541classifications are done according to the ASCII value of the byte, and bytes
542whose high bit is set (i.e., non-ASCII bytes) are never converted or considered
543part of a character class such as letter or whitespace.
544
Georg Brandl116aa622007-08-15 14:28:22 +0000545
546.. _embedding-locale:
547
548For extension writers and programs that embed Python
549----------------------------------------------------
550
551Extension modules should never call :func:`setlocale`, except to find out what
552the current locale is. But since the return value can only be used portably to
553restore it, that is not very useful (except perhaps to find out whether or not
554the locale is ``C``).
555
556When Python code uses the :mod:`locale` module to change the locale, this also
557affects the embedding application. If the embedding application doesn't want
558this to happen, it should remove the :mod:`_locale` extension module (which does
559all the work) from the table of built-in modules in the :file:`config.c` file,
560and make sure that the :mod:`_locale` module is not accessible as a shared
561library.
562
563
564.. _locale-gettext:
565
566Access to message catalogs
567--------------------------
568
Serhiy Storchakac02a1f42017-10-04 20:28:20 +0300569.. function:: gettext(msg)
570.. function:: dgettext(domain, msg)
571.. function:: dcgettext(domain, msg, category)
572.. function:: textdomain(domain)
573.. function:: bindtextdomain(domain, dir)
574
Georg Brandl116aa622007-08-15 14:28:22 +0000575The locale module exposes the C library's gettext interface on systems that
Serhiy Storchakac02a1f42017-10-04 20:28:20 +0300576provide this interface. It consists of the functions :func:`!gettext`,
577:func:`!dgettext`, :func:`!dcgettext`, :func:`!textdomain`, :func:`!bindtextdomain`,
578and :func:`!bind_textdomain_codeset`. These are similar to the same functions in
Georg Brandl116aa622007-08-15 14:28:22 +0000579the :mod:`gettext` module, but use the C library's binary format for message
580catalogs, and the C library's search algorithms for locating message catalogs.
581
582Python applications should normally find no need to invoke these functions, and
583should use :mod:`gettext` instead. A known exception to this rule are
Georg Brandl599dbfc2010-10-26 19:58:11 +0000584applications that link with additional C libraries which internally invoke
Serhiy Storchakac02a1f42017-10-04 20:28:20 +0300585:c:func:`gettext` or :c:func:`dcgettext`. For these applications, it may be
Georg Brandl116aa622007-08-15 14:28:22 +0000586necessary to bind the text domain, so that the libraries can properly locate
587their message catalogs.
588