|
| 1 | +\section{Standard module \sectcode{locale}} |
| 2 | +\stmodindex{locale} |
| 3 | + |
| 4 | +\label{module-locale} |
| 5 | + |
| 6 | +The \code{locale} module opens access to the POSIX locale database and |
| 7 | +functionality. The POSIX locale mechanism allows applications to |
| 8 | +integrate certain cultural aspects into an applications, without |
| 9 | +requiring the programmer to know all the specifics of each country |
| 10 | +where the software is executed. |
| 11 | + |
| 12 | +The \code{locale} module is implemented on top of the \code{_locale} |
| 13 | +module, which in turn uses an ANSI C locale implementation if |
| 14 | +available. |
| 15 | + |
| 16 | +The \code{locale} module defines the following functions: |
| 17 | + |
| 18 | +\renewcommand{\indexsubitem}{(in module locale)} |
| 19 | + |
| 20 | +\begin{funcdesc}{setlocale}{category\optional{\, value}} |
| 21 | +If \var{value} is specified, modifies the locale setting for the |
| 22 | +\var{category}. The available categories are listed in the data |
| 23 | +description below. The value is the name of a locale. An empty string |
| 24 | +specifies the user's default settings. If the modification of the |
| 25 | +locale fails, the exception \code{locale.Error} is |
| 26 | +raised. If successful, the new locale setting is returned. |
| 27 | + |
| 28 | +If no \var{value} is specified, the current setting for the |
| 29 | +\var{category} is returned. |
| 30 | + |
| 31 | +\code{setlocale} is not thread safe on most systems. Applications |
| 32 | +typically start with a call of |
| 33 | +\bcode\begin{verbatim} |
| 34 | +import locale |
| 35 | +locale.setlocale(locale.LC_ALL,"") |
| 36 | +\end{verbatim}\ecode |
| 37 | +This sets the locale for all categories to the user's default setting |
| 38 | +(typically specified in the \code{LANG} environment variable). If the |
| 39 | +locale is not changed thereafter, using multithreading should not |
| 40 | +cause problems. |
| 41 | +\end{funcdesc} |
| 42 | + |
| 43 | +\begin{funcdesc}{localeconv}{} |
| 44 | +Returns the database of of the local conventions as a dictionary. This |
| 45 | +dictionary has the following strings as keys: |
| 46 | +\begin{itemize} |
| 47 | +\item \code{decimal_point} specifies the decimal point used in |
| 48 | +floating point number representations for the \code{LC_NUMERIC} |
| 49 | +category. |
| 50 | +\item \code{grouping} is a sequence of numbers specifying at which |
| 51 | +relative positions the \code{thousands_sep} is expected. If the |
| 52 | +sequence is terminated with \code{locale.CHAR_MAX}, no further |
| 53 | +grouping is performed. If the sequence terminates with a 0, the last |
| 54 | +group size is repeatedly used. |
| 55 | +\item \code{thousands_sep} is the character used between groups. |
| 56 | +\item \code{int_curr_symbol} specifies the international currency |
| 57 | +symbol from the \code{LC_MONETARY} category. |
| 58 | +\item \code{currency_symbol} is the local currency symbol. |
| 59 | +\item \code{mon_decimal_point} is the decimal point used in monetary |
| 60 | +values. |
| 61 | +\item \code{mon_thousands_sep} is the separator for grouping of |
| 62 | +monetary values. |
| 63 | +\item \code{mon_grouping} has the same format as the \code{grouping} |
| 64 | +key; it is used for monetary values. |
| 65 | +\item \code{positive_sign} and \code{negative_sign} gives the sign |
| 66 | +used for positive and negative monetary quantities. |
| 67 | +\item \code{int_frac_digits} and \code{frac_digits} specify the number |
| 68 | +of fractional digits used in the international and local formatting |
| 69 | +of monetary values. |
| 70 | +\item \code{p_cs_precedes} and \code{n_cs_precedes} specifies whether |
| 71 | +the currency symbol precedes the value for positive or negative |
| 72 | +values. |
| 73 | +\item \code{p_sep_by_space} and \code{n_sep_by_space} specifies |
| 74 | +whether there is a space between the positive or negative value and |
| 75 | +the currency symbol. |
| 76 | +\item \code{p_sign_posn} and \code{n_sign_posn} indicate how the |
| 77 | +sign should be placed for positive and negative monetary values. |
| 78 | +\end{itemize} |
| 79 | +The possible values for \code{p_sign_posn} and \code{n_sign_posn} |
| 80 | +are given below. |
| 81 | +\begin{itemize} |
| 82 | +\item 0 - Currency and value are surrounded by parentheses. |
| 83 | +\item 1 - The sign should precede the value and currency symbol. |
| 84 | +\item 2 - The sign should follow the value and currency symbol. |
| 85 | +\item 3 - The sign should immediately precede the value. |
| 86 | +\item 4 - The sign should immediately follow the value. |
| 87 | +\item LC_MAX - nothing is specified in this locale. |
| 88 | +\end{itemize} |
| 89 | +\end{funcdesc} |
| 90 | + |
| 91 | +\begin{funcdesc}{strcoll}{string1,string2} |
| 92 | +Compares two strings according to the current LC_COLLATE setting. As |
| 93 | +any other compare function, returns a negative, or a positive value, |
| 94 | +or 0, depending on whether \var{string1} collates before or after |
| 95 | +\var{string2} or is equal to it. |
| 96 | +\end{funcdesc} |
| 97 | + |
| 98 | +\begin{funcdesc}{strxfrm}{string} |
| 99 | +Transforms a string to one that can be used for the builtin function |
| 100 | +\code{cmp}, and still returns locale-aware results. This function can be |
| 101 | +used when the same string is compared repeatedly, e.g. when collating |
| 102 | +a sequence of strings. |
| 103 | +\end{funcdesc} |
| 104 | + |
| 105 | +\begin{funcdesc}{format}{format,val\optional{grouping=0}} |
| 106 | +Formats a number \var{val} according to the current LC_NUMERIC |
| 107 | +setting. The format follows the conventions of the \% operator. For |
| 108 | +floating point values, the decimal point is modified if |
| 109 | +appropriate. If \var{grouping} is true, also takes the grouping into |
| 110 | +account. |
| 111 | +\end{funcdesc} |
| 112 | + |
| 113 | +\begin{funcdesc}{str}{float} |
| 114 | +Formats a floating point number using the same format as |
| 115 | +\code{string.str}, but takes the decimal point into account. |
| 116 | +\end{funcdesc} |
| 117 | + |
| 118 | +\begin{funcdesc}{atof}{string} |
| 119 | +Converts a string to a floating point number, following the LC_NUMERIC |
| 120 | +settings. |
| 121 | +\end{funcdesc} |
| 122 | + |
| 123 | +\begin{funcdesc}{atoi}{string} |
| 124 | +Converts a string to an integer, following the LC_NUMERIC conventions. |
| 125 | +\end{funcdesc} |
| 126 | + |
| 127 | +\begin{datadesc}{LC_CTYPE} |
| 128 | +Locale category for the character type functions. Depending on the |
| 129 | +settings of this category, the functions of module \code{string} |
| 130 | +dealing with case change their behaviour. |
| 131 | +\end{datadesc} |
| 132 | + |
| 133 | +\begin{datadesc}{LC_COLLATE} |
| 134 | +Locale category for sorting strings. The functions \code{strcoll} and |
| 135 | +\code{strxfrm} of the locale module are affected. |
| 136 | +\end{datadesc} |
| 137 | + |
| 138 | +\begin{datadesc}{LC_TIME} |
| 139 | +Locale category for the formatting of time. The function |
| 140 | +\code{time.strftime} follows these conventions. |
| 141 | +\end{datadesc} |
| 142 | + |
| 143 | +\begin{datadesc}{LC_MONETARY} |
| 144 | +Locale category for formatting of monetary values. The available |
| 145 | +options are available from the \code{localeconv} function. |
| 146 | +\end{datadesc} |
| 147 | + |
| 148 | +\begin{datadesc}{LC_MESSAGES} |
| 149 | +Locale category for message display. Python currently does not support |
| 150 | +application specific locale-aware messages. Messages displayed by the |
| 151 | +operating system, like those returned by \code{posix.strerror} might |
| 152 | +be affected by this category. |
| 153 | +\end{datadesc} |
| 154 | + |
| 155 | +\begin{datadesc}{LC_NUMERIC} |
| 156 | +Locale category for formatting numbers. The functions |
| 157 | +\code{format}, \code{atoi}, \code{atof} and \code{str} of the locale module |
| 158 | +are affected by that category. All other numeric formatting operations |
| 159 | +are not affected. |
| 160 | +\end{datadesc} |
| 161 | + |
| 162 | +\begin{datadesc}{LC_ALL} |
| 163 | +Combination of all locale settings. If this flag is used when the |
| 164 | +locale is changed, setting the locale for all categories is |
| 165 | +attempted. If that fails for any category, no category is changed at |
| 166 | +all. When the locale is retrieved using this flag, a string indicating |
| 167 | +the setting for all categories is returned. This string can be later |
| 168 | +used to restore the settings. |
| 169 | +\end{datadesc} |
| 170 | + |
| 171 | +\begin{datadesc}{CHAR_MAX} |
| 172 | +This is a symbolic constant used for different values returned by |
| 173 | +\code{localeconv}. |
| 174 | +\end{datadesc} |
| 175 | + |
| 176 | +\begin{excdesc}{Error} |
| 177 | +Exception raised when \code{setlocale} fails. |
| 178 | +\end{excdesc} |
| 179 | + |
| 180 | +Example: |
| 181 | + |
| 182 | +\bcode\begin{verbatim} |
| 183 | +>>> import locale |
| 184 | +>>> locale.open(locale.LC_ALL,"de") #setting locale to German |
| 185 | +>>> locale.strcoll("f\344n","foo") #comparing a string containing an umlaut |
| 186 | +>>> can.close() |
| 187 | +\end{verbatim}\ecode |
0 commit comments