Doc/lib/liblocale.tex

   1 \section{\module{locale} ---
   2          Internationalization services.}
   3 \declaremodule{standard}{locale}
   4
   5
   6 \modulesynopsis{Internationalization services.}
   7
   8
   9 The \code{locale} module opens access to the \POSIX{} locale database
  10 and functionality. The \POSIX{} locale mechanism allows applications
  11 to integrate certain cultural aspects into an applications, without
  12 requiring the programmer to know all the specifics of each country
  13 where the software is executed.
  14
  15 The \module{locale} module is implemented on top of the
  16 \module{_locale}\refbimodindex{_locale} module, which in turn uses an
  17 ANSI \C{} locale implementation if available.
  18
  19 The \module{locale} module defines the following exception and
  20 functions:
  21
  22
  23 \begin{funcdesc}{setlocale}{category\optional{, value}}
  24 If \var{value} is specified, modifies the locale setting for the
  25 \var{category}. The available categories are listed in the data
  26 description below. The value is the name of a locale. An empty string
  27 specifies the user's default settings. If the modification of the
  28 locale fails, the exception \exception{Error} is
  29 raised. If successful, the new locale setting is returned.
  30
  31 If no \var{value} is specified, the current setting for the
  32 \var{category} is returned.
  33
  34 \function{setlocale()} is not thread safe on most systems. Applications
  35 typically start with a call of
  36 \begin{verbatim}
  37 import locale
  38 locale.setlocale(locale.LC_ALL,"")
  39 \end{verbatim}
  40 This sets the locale for all categories to the user's default setting
  41 (typically specified in the \code{LANG} environment variable). If the
  42 locale is not changed thereafter, using multithreading should not
  43 cause problems.
  44 \end{funcdesc}
  45
  46 \begin{excdesc}{Error}
  47 Exception raised when \function{setlocale()} fails.
  48 \end{excdesc}
  49
  50 \begin{funcdesc}{localeconv}{}
  51 Returns the database of of the local conventions as a dictionary. This
  52 dictionary has the following strings as keys:
  53 \begin{itemize}
  54 \item \code{decimal_point} specifies the decimal point used in
  55 floating point number representations for the \code{LC_NUMERIC}
  56 category.
  57 \item \code{grouping} is a sequence of numbers specifying at which
  58 relative positions the \code{thousands_sep} is expected. If the
  59 sequence is terminated with \code{locale.CHAR_MAX}, no further
  60 grouping is performed. If the sequence terminates with a \code{0}, the last
  61 group size is repeatedly used.
  62 \item \code{thousands_sep} is the character used between groups.
  63 \item \code{int_curr_symbol} specifies the international currency
  64 symbol from the \code{LC_MONETARY} category.
  65 \item \code{currency_symbol} is the local currency symbol.
  66 \item \code{mon_decimal_point} is the decimal point used in monetary
  67 values.
  68 \item \code{mon_thousands_sep} is the separator for grouping of
  69 monetary values.
  70 \item \code{mon_grouping} has the same format as the \code{grouping}
  71 key; it is used for monetary values.
  72 \item \code{positive_sign} and \code{negative_sign} gives the sign
  73 used for positive and negative monetary quantities.
  74 \item \code{int_frac_digits} and \code{frac_digits} specify the number
  75 of fractional digits used in the international and local formatting
  76 of monetary values.
  77 \item \code{p_cs_precedes} and \code{n_cs_precedes} specifies whether
  78 the currency symbol precedes the value for positive or negative
  79 values.
  80 \item \code{p_sep_by_space} and \code{n_sep_by_space} specifies
  81 whether there is a space between the positive or negative value and
  82 the currency symbol.
  83 \item \code{p_sign_posn} and \code{n_sign_posn} indicate how the
  84 sign should be placed for positive and negative monetary values.
  85 \end{itemize}
  86
  87 The possible values for \code{p_sign_posn} and \code{n_sign_posn}
  88 are given below.
  89
  90 \begin{tableii}{c|l}{code}{Value}{Explanation}
  91 \lineii{0}{Currency and value are surrounded by parentheses.}
  92 \lineii{1}{The sign should precede the value and currency symbol.}
  93 \lineii{2}{The sign should follow the value and currency symbol.}
  94 \lineii{3}{The sign should immediately precede the value.}
  95 \lineii{4}{The sign should immediately follow the value.}
  96 \lineii{LC_MAX}{Nothing is specified in this locale.}
  97 \end{tableii}
  98 \end{funcdesc}
  99
 100 \begin{funcdesc}{strcoll}{string1,string2}
 101 Compares two strings according to the current \constant{LC_COLLATE}
 102 setting. As any other compare function, returns a negative, or a
 103 positive value, or \code{0}, depending on whether \var{string1}
 104 collates before or after \var{string2} or is equal to it.
 105 \end{funcdesc}
 106
 107 \begin{funcdesc}{strxfrm}{string}
 108 Transforms a string to one that can be used for the built-in function
 109 \function{cmp()}\bifuncindex{cmp}, and still returns locale-aware
 110 results.  This function can be used when the same string is compared
 111 repeatedly, e.g. when collating a sequence of strings.
 112 \end{funcdesc}
 113
 114 \begin{funcdesc}{format}{format, val, \optional{grouping\code{ = 0}}}
 115 Formats a number \var{val} according to the current
 116 \constant{LC_NUMERIC} setting.  The format follows the conventions of
 117 the \code{\%} operator.  For floating point values, the decimal point
 118 is modified if appropriate.  If \var{grouping} is true, also takes the
 119 grouping into account.
 120 \end{funcdesc}
 121
 122 \begin{funcdesc}{str}{float}
 123 Formats a floating point number using the same format as the built-in
 124 function \code{str(\var{float})}, but takes the decimal point into
 125 account.
 126 \end{funcdesc}
 127
 128 \begin{funcdesc}{atof}{string}
 129 Converts a string to a floating point number, following the
 130 \constant{LC_NUMERIC} settings.
 131 \end{funcdesc}
 132
 133 \begin{funcdesc}{atoi}{string}
 134 Converts a string to an integer, following the \constant{LC_NUMERIC}
 135 conventions.
 136 \end{funcdesc}
 137
 138 \begin{datadesc}{LC_CTYPE}
 139 \refstmodindex{string}
 140 Locale category for the character type functions. Depending on the
 141 settings of this category, the functions of module \module{string}
 142 dealing with case change their behaviour.
 143 \end{datadesc}
 144
 145 \begin{datadesc}{LC_COLLATE}
 146 Locale category for sorting strings. The functions
 147 \function{strcoll()} and \function{strxfrm()} of the \module{locale}
 148 module are affected.
 149 \end{datadesc}
 150
 151 \begin{datadesc}{LC_TIME}
 152 Locale category for the formatting of time. The function
 153 \function{time.strftime()} follows these conventions.
 154 \end{datadesc}
 155
 156 \begin{datadesc}{LC_MONETARY}
 157 Locale category for formatting of monetary values. The available
 158 options are available from the \function{localeconv()} function.
 159 \end{datadesc}
 160
 161 \begin{datadesc}{LC_MESSAGES}
 162 Locale category for message display. Python currently does not support
 163 application specific locale-aware messages. Messages displayed by the
 164 operating system, like those returned by \function{os.strerror()}
 165 might be affected by this category.
 166 \end{datadesc}
 167
 168 \begin{datadesc}{LC_NUMERIC}
 169 Locale category for formatting numbers. The functions
 170 \function{format()}, \function{atoi()}, \function{atof()} and
 171 \function{str()} of the \module{locale} module are affected by that
 172 category. All other numeric formatting operations are not affected.
 173 \end{datadesc}
 174
 175 \begin{datadesc}{LC_ALL}
 176 Combination of all locale settings. If this flag is used when the
 177 locale is changed, setting the locale for all categories is
 178 attempted. If that fails for any category, no category is changed at
 179 all. When the locale is retrieved using this flag, a string indicating
 180 the setting for all categories is returned. This string can be later
 181 used to restore the settings.
 182 \end{datadesc}
 183
 184 \begin{datadesc}{CHAR_MAX}
 185 This is a symbolic constant used for different values returned by
 186 \function{localeconv()}.
 187 \end{datadesc}
 188
 189 Example:
 190
 191 \begin{verbatim}
 192 >>> import locale
 193 >>> loc = locale.setlocale(locale.LC_ALL) # get current locale
 194 >>> locale.setlocale(locale.LC_ALL, "de") # use German locale
 195 >>> locale.strcoll("f\344n", "foo") # compare a string containing an umlaut
 196 >>> locale.setlocale(locale.LC_ALL, "") # use user's preferred locale
 197 >>> locale.setlocale(locale.LC_ALL, "C") # use default (C) locale
 198 >>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
 199 \end{verbatim}
 200
 201 \subsection{Background, details, hints, tips and caveats}
 202
 203 The C standard defines the locale as a program-wide property that may
 204 be relatively expensive to change.  On top of that, some
 205 implementation are broken in such a way that frequent locale changes
 206 may cause core dumps.  This makes the locale somewhat painful to use
 207 correctly.
 208
 209 Initially, when a program is started, the locale is the \samp{C} locale, no
 210 matter what the user's preferred locale is.  The program must
 211 explicitly say that it wants the user's preferred locale settings by
 212 calling \code{setlocale(LC_ALL, "")}.
 213
 214 It is generally a bad idea to call \function{setlocale()} in some library
 215 routine, since as a side effect it affects the entire program.  Saving
 216 and restoring it is almost as bad: it is expensive and affects other
 217 threads that happen to run before the settings have been restored.
 218
 219 If, when coding a module for general use, you need a locale
 220 independent version of an operation that is affected by the locale
 221 (e.g. \function{string.lower()}, or certain formats used with
 222 \function{time.strftime()})), you will have to find a way to do it
 223 without using the standard library routine.  Even better is convincing
 224 yourself that using locale settings is okay.  Only as a last resort
 225 should you document that your module is not compatible with
 226 non-\samp{C} locale settings.
 227
 228 The case conversion functions in the
 229 \module{string}\refstmodindex{string} and
 230 \module{strop}\refbimodindex{strop} modules are affected by the locale
 231 settings.  When a call to the \function{setlocale()} function changes
 232 the \constant{LC_CTYPE} settings, the variables
 233 \code{string.lowercase}, \code{string.uppercase} and
 234 \code{string.letters} (and their counterparts in \module{strop}) are
 235 recalculated.  Note that this code that uses these variable through
 236 `\keyword{from} ... \keyword{import} ...', e.g. \code{from string
 237 import letters}, is not affected by subsequent \function{setlocale()}
 238 calls.
 239
 240 The only way to perform numeric operations according to the locale
 241 is to use the special functions defined by this module:
 242 \function{atof()}, \function{atoi()}, \function{format()},
 243 \function{str()}.
 244
 245 \subsection{For extension writers and programs that embed Python}
 246 \label{embedding-locale}
 247
 248 Extension modules should never call \function{setlocale()}, except to
 249 find out what the current locale is.  But since the return value can
 250 only be used portably to restore it, that is not very useful (except
 251 perhaps to find out whether or not the locale is \samp{C}).
 252
 253 When Python is embedded in an application, if the application sets the
 254 locale to something specific before initializing Python, that is
 255 generally okay, and Python will use whatever locale is set,
 256 \emph{except} that the \constant{LC_NUMERIC} locale should always be
 257 \samp{C}.
 258
 259 The \function{setlocale()} function in the \module{locale} module contains
 260 gives the Python progammer the impression that you can manipulate the
 261 \constant{LC_NUMERIC} locale setting, but this not the case at the \C{}
 262 level: \C{} code will always find that the \constant{LC_NUMERIC} locale
 263 setting is \samp{C}.  This is because too much would break when the
 264 decimal point character is set to something else than a period
 265 (e.g. the Python parser would break).  Caveat: threads that run
 266 without holding Python's global interpreter lock may occasionally find
 267 that the numeric locale setting differs; this is because the only
 268 portable way to implement this feature is to set the numeric locale
 269 settings to what the user requests, extract the relevant
 270 characteristics, and then restore the \samp{C} numeric locale.
 271
 272 When Python code uses the \module{locale} module to change the locale,
 273 this also affect the embedding application.  If the embedding
 274 application doesn't want this to happen, it should remove the
 275 \module{_locale} extension module (which does all the work) from the
 276 table of built-in modules in the \file{config.c} file, and make sure
 277 that the \module{_locale} module is not accessible as a shared library.