The locale module opens access to the POSIX locale
database and functionality. The POSIX locale mechanism allows
programmers to deal with certain cultural issues in an application,
without requiring the programmer to know all the specifics of each
country where the software is executed.
The locale module is implemented on top of the
_localemodule, which in turn uses an
ANSI C locale implementation if available.
The locale module defines the following exception and
If locale is specified, it may be a string, a tuple of the
form (language code, encoding), or None.
If it is a tuple, it is converted to a string using the locale
aliasing engine. If locale is given and not None,
setlocale() modifies the locale setting for the
category. The available categories are listed in the data
description below. The value is the name of a locale. An empty
string specifies the user's default settings. If the modification of
the locale fails, the exception Error is raised. If
successful, the new locale setting is returned.
If locale is omitted or None, the current setting for
category is returned.
setlocale() is not thread safe on most systems.
Applications typically start with a call of
This sets the locale for all categories to the user's default
setting (typically specified in the LANG environment
variable). If the locale is not changed thereafter, using
multithreading should not cause problems.
Changed in version 2.0:
Added support for tuple values of the locale
Returns the database of of the local conventions as a dictionary.
This dictionary has the following strings as keys:
Decimal point character.
Sequence of numbers specifying which relative positions
the 'thousands_sep' is expected. If the sequence is
terminated with CHAR_MAX, no further grouping
is performed. If the sequence terminates with a 0,
the last group size is repeatedly used.
Character used between groups.
International currency symbol.
Local currency symbol.
Decimal point used for monetary values.
Group separator used for monetary values.
Equivalent to 'grouping', used for monetary
Symbol used to annotate a positive monetary value.
Symbol used to annotate a nnegative monetary value.
Number of fractional digits used in local formatting
of monetary values.
Number of fractional digits used in international
formatting of monetary values.
The possible values for 'p_sign_posn' and
'n_sign_posn' are given below.
Currency and value are surrounded by parentheses.
The sign should precede the value and currency symbol.
The sign should follow the value and currency symbol.
Return some locale-specific information as a string. This function is
not available on all systems, and the set of possible options might
also vary across platforms. The possible argument values are numbers,
for which symbolic constants are available in the locale module.
Tries to determine the default locale settings and returns
them as a tuple of the form (language code,
According to POSIX, a program which has not called
setlocale(LC_ALL, '') runs using the portable 'C'
locale. Calling setlocale(LC_ALL, '') lets it use the
default locale as defined by the LANG variable. Since we
do not want to interfere with the current locale setting we thus
emulate the behavior in the way described above.
To maintain compatibility with other platforms, not only the
LANG variable is tested, but a list of variables given as
envvars parameter. The first found to be defined will be
used. envvars defaults to the search path used in GNU gettext;
it must always contain the variable name "LANG". The GNU
gettext search path contains 'LANGUAGE', 'LC_ALL',
'LC_CTYPE', and 'LANG', in that order.
Except for the code 'C', the language code corresponds to
RFC 1766. language code and encoding may be
None if their values cannot be determined.
New in version 2.0.
Compares two strings according to the current
LC_COLLATE setting. As any other compare function,
returns a negative, or a positive value, or 0, depending on
whether string1 collates before or after string2 or is
equal to it.
Transforms a string to one that can be used for the built-in
function cmp(), and still returns
locale-aware results. This function can be used when the same
string is compared repeatedly, e.g. when collating a sequence of
Formats a number val according to the current
LC_NUMERIC setting. The format follows the conventions
of the % operator. For floating point values, the decimal
point is modified if appropriate. If grouping is true, also
takes the grouping into account.
Locale category for message display. Python currently does not
support application specific locale-aware messages. Messages
displayed by the operating system, like those returned by
os.strerror() might be affected by this category.
Combination of all locale settings. If this flag is used when the
locale is changed, setting the locale for all categories is
attempted. If that fails for any category, no category is changed at
all. When the locale is retrieved using this flag, a string
indicating the setting for all categories is returned. This string
can be later used to restore the settings.
Return a regular expression that can be used with the regex
function to recognize a positive response to a yes/no question.
The expression is in the syntax suitable for the
regex() function from the C library, which might differ
from the syntax used in re.
The return value represents the era used in the current locale.
Most locales do not define this value. An example of a locale which
does define this value is the Japanese one. In Japan, the traditional
representation of dates includes the name of the era corresponding to
the then-emperor's reign.
Normally it should not be necessary to use this value directly.
Specifying the E modifier in their format strings causes the
strftime function to use this information. The format of the
returned string is not specified, and therefore you should not assume
knowledge of it on different systems.