diff options
Diffstat (limited to 'Doc/liblocale.tex')
| -rw-r--r-- | Doc/liblocale.tex | 274 |
1 files changed, 0 insertions, 274 deletions
diff --git a/Doc/liblocale.tex b/Doc/liblocale.tex deleted file mode 100644 index 07361b8..0000000 --- a/Doc/liblocale.tex +++ /dev/null @@ -1,274 +0,0 @@ -\section{Standard Module \module{locale}} -\stmodindex{locale} - -\label{module-locale} - -The \code{locale} module opens access to the \POSIX{} locale database -and functionality. The \POSIX{} locale mechanism allows applications -to integrate certain cultural aspects into an applications, without -requiring the programmer to know all the specifics of each country -where the software is executed. - -The \module{locale} module is implemented on top of the -\module{_locale}\refbimodindex{_locale} module, which in turn uses an -ANSI \C{} locale implementation if available. - -The \module{locale} module defines the following exception and -functions: - - -\begin{funcdesc}{setlocale}{category\optional{, value}} -If \var{value} is specified, modifies the locale setting for the -\var{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 \exception{Error} is -raised. If successful, the new locale setting is returned. - -If no \var{value} is specified, the current setting for the -\var{category} is returned. - -\function{setlocale()} is not thread safe on most systems. Applications -typically start with a call of -\begin{verbatim} -import locale -locale.setlocale(locale.LC_ALL,"") -\end{verbatim} -This sets the locale for all categories to the user's default setting -(typically specified in the \code{LANG} environment variable). If the -locale is not changed thereafter, using multithreading should not -cause problems. -\end{funcdesc} - -\begin{excdesc}{Error} -Exception raised when \function{setlocale()} fails. -\end{excdesc} - -\begin{funcdesc}{localeconv}{} -Returns the database of of the local conventions as a dictionary. This -dictionary has the following strings as keys: -\begin{itemize} -\item \code{decimal_point} specifies the decimal point used in -floating point number representations for the \code{LC_NUMERIC} -category. -\item \code{grouping} is a sequence of numbers specifying at which -relative positions the \code{thousands_sep} is expected. If the -sequence is terminated with \code{locale.CHAR_MAX}, no further -grouping is performed. If the sequence terminates with a \code{0}, the last -group size is repeatedly used. -\item \code{thousands_sep} is the character used between groups. -\item \code{int_curr_symbol} specifies the international currency -symbol from the \code{LC_MONETARY} category. -\item \code{currency_symbol} is the local currency symbol. -\item \code{mon_decimal_point} is the decimal point used in monetary -values. -\item \code{mon_thousands_sep} is the separator for grouping of -monetary values. -\item \code{mon_grouping} has the same format as the \code{grouping} -key; it is used for monetary values. -\item \code{positive_sign} and \code{negative_sign} gives the sign -used for positive and negative monetary quantities. -\item \code{int_frac_digits} and \code{frac_digits} specify the number -of fractional digits used in the international and local formatting -of monetary values. -\item \code{p_cs_precedes} and \code{n_cs_precedes} specifies whether -the currency symbol precedes the value for positive or negative -values. -\item \code{p_sep_by_space} and \code{n_sep_by_space} specifies -whether there is a space between the positive or negative value and -the currency symbol. -\item \code{p_sign_posn} and \code{n_sign_posn} indicate how the -sign should be placed for positive and negative monetary values. -\end{itemize} - -The possible values for \code{p_sign_posn} and \code{n_sign_posn} -are given below. - -\begin{tableii}{c|l}{code}{Value}{Explanation} -\lineii{0}{Currency and value are surrounded by parentheses.} -\lineii{1}{The sign should precede the value and currency symbol.} -\lineii{2}{The sign should follow the value and currency symbol.} -\lineii{3}{The sign should immediately precede the value.} -\lineii{4}{The sign should immediately follow the value.} -\lineii{LC_MAX}{Nothing is specified in this locale.} -\end{tableii} -\end{funcdesc} - -\begin{funcdesc}{strcoll}{string1,string2} -Compares two strings according to the current \constant{LC_COLLATE} -setting. As any other compare function, returns a negative, or a -positive value, or \code{0}, depending on whether \var{string1} -collates before or after \var{string2} or is equal to it. -\end{funcdesc} - -\begin{funcdesc}{strxfrm}{string} -Transforms a string to one that can be used for the built-in function -\function{cmp()}\bifuncindex{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 strings. -\end{funcdesc} - -\begin{funcdesc}{format}{format, val, \optional{grouping\code{ = 0}}} -Formats a number \var{val} according to the current -\constant{LC_NUMERIC} setting. The format follows the conventions of -the \code{\%} operator. For floating point values, the decimal point -is modified if appropriate. If \var{grouping} is true, also takes the -grouping into account. -\end{funcdesc} - -\begin{funcdesc}{str}{float} -Formats a floating point number using the same format as the built-in -function \code{str(\var{float})}, but takes the decimal point into -account. -\end{funcdesc} - -\begin{funcdesc}{atof}{string} -Converts a string to a floating point number, following the -\constant{LC_NUMERIC} settings. -\end{funcdesc} - -\begin{funcdesc}{atoi}{string} -Converts a string to an integer, following the \constant{LC_NUMERIC} -conventions. -\end{funcdesc} - -\begin{datadesc}{LC_CTYPE} -\refstmodindex{string} -Locale category for the character type functions. Depending on the -settings of this category, the functions of module \module{string} -dealing with case change their behaviour. -\end{datadesc} - -\begin{datadesc}{LC_COLLATE} -Locale category for sorting strings. The functions -\function{strcoll()} and \function{strxfrm()} of the \module{locale} -module are affected. -\end{datadesc} - -\begin{datadesc}{LC_TIME} -Locale category for the formatting of time. The function -\function{time.strftime()} follows these conventions. -\end{datadesc} - -\begin{datadesc}{LC_MONETARY} -Locale category for formatting of monetary values. The available -options are available from the \function{localeconv()} function. -\end{datadesc} - -\begin{datadesc}{LC_MESSAGES} -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 \function{os.strerror()} -might be affected by this category. -\end{datadesc} - -\begin{datadesc}{LC_NUMERIC} -Locale category for formatting numbers. The functions -\function{format()}, \function{atoi()}, \function{atof()} and -\function{str()} of the \module{locale} module are affected by that -category. All other numeric formatting operations are not affected. -\end{datadesc} - -\begin{datadesc}{LC_ALL} -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. -\end{datadesc} - -\begin{datadesc}{CHAR_MAX} -This is a symbolic constant used for different values returned by -\function{localeconv()}. -\end{datadesc} - -Example: - -\begin{verbatim} ->>> import locale ->>> loc = locale.setlocale(locale.LC_ALL) # get current locale ->>> locale.setlocale(locale.LC_ALL, "de") # use German locale ->>> locale.strcoll("f\344n", "foo") # compare a string containing an umlaut ->>> locale.setlocale(locale.LC_ALL, "") # use user's preferred locale ->>> locale.setlocale(locale.LC_ALL, "C") # use default (C) locale ->>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale -\end{verbatim} - -\subsection{Background, details, hints, tips and caveats} - -The C standard defines the locale as a program-wide property that may -be relatively expensive to change. On top of that, some -implementation are broken in such a way that frequent locale changes -may cause core dumps. This makes the locale somewhat painful to use -correctly. - -Initially, when a program is started, the locale is the \samp{C} locale, no -matter what the user's preferred locale is. The program must -explicitly say that it wants the user's preferred locale settings by -calling \code{setlocale(LC_ALL, "")}. - -It is generally a bad idea to call \function{setlocale()} in some library -routine, since as a side effect it affects the entire program. Saving -and restoring it is almost as bad: it is expensive and affects other -threads that happen to run before the settings have been restored. - -If, when coding a module for general use, you need a locale -independent version of an operation that is affected by the locale -(e.g. \function{string.lower()}, or certain formats used with -\function{time.strftime()})), you will have to find a way to do it -without using the standard library routine. Even better is convincing -yourself that using locale settings is okay. Only as a last resort -should you document that your module is not compatible with -non-\samp{C} locale settings. - -The case conversion functions in the -\module{string}\refstmodindex{string} and -\module{strop}\refbimodindex{strop} modules are affected by the locale -settings. When a call to the \function{setlocale()} function changes -the \constant{LC_CTYPE} settings, the variables -\code{string.lowercase}, \code{string.uppercase} and -\code{string.letters} (and their counterparts in \module{strop}) are -recalculated. Note that this code that uses these variable through -`\keyword{from} ... \keyword{import} ...', e.g. \code{from string -import letters}, is not affected by subsequent \function{setlocale()} -calls. - -The only way to perform numeric operations according to the locale -is to use the special functions defined by this module: -\function{atof()}, \function{atoi()}, \function{format()}, -\function{str()}. - -\subsection{For extension writers and programs that embed Python} -\label{embedding-locale} - -Extension modules should never call \function{setlocale()}, except to -find out what the current locale is. But since the return value can -only be used portably to restore it, that is not very useful (except -perhaps to find out whether or not the locale is \samp{C}). - -When Python is embedded in an application, if the application sets the -locale to something specific before initializing Python, that is -generally okay, and Python will use whatever locale is set, -\emph{except} that the \constant{LC_NUMERIC} locale should always be -\samp{C}. - -The \function{setlocale()} function in the \module{locale} module contains -gives the Python progammer the impression that you can manipulate the -\constant{LC_NUMERIC} locale setting, but this not the case at the \C{} -level: \C{} code will always find that the \constant{LC_NUMERIC} locale -setting is \samp{C}. This is because too much would break when the -decimal point character is set to something else than a period -(e.g. the Python parser would break). Caveat: threads that run -without holding Python's global interpreter lock may occasionally find -that the numeric locale setting differs; this is because the only -portable way to implement this feature is to set the numeric locale -settings to what the user requests, extract the relevant -characteristics, and then restore the \samp{C} numeric locale. - -When Python code uses the \module{locale} module to change the locale, -this also affect the embedding application. If the embedding -application doesn't want this to happen, it should remove the -\module{_locale} extension module (which does all the work) from the -table of built-in modules in the \file{config.c} file, and make sure -that the \module{_locale} module is not accessible as a shared library. |