Adding Martin von Loewis' documentation for his locale module.

7 files changed, 383 insertions, 1 deletions

diff --git a/Doc/Makefile b/Doc/Makefile
index 1410c12..468294d 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -113,7 +113,7 @@ LIBFILES = lib.tex \
     libbase64.tex libfnmatch.tex libquopri.tex libzlib.tex libsocksvr.tex \
     libmailbox.tex libcommands.tex libcmath.tex libni.tex libgzip.tex \
     libpprint.tex libcode.tex libmimify.tex libre.tex libmacic.tex \
-    libuserdict.tex libdis.tex libxmllib.tex libqueue.tex
+    libuserdict.tex libdis.tex libxmllib.tex libqueue.tex liblocale.tex
 
 # Library document
 lib.dvi: $(LIBFILES)
diff --git a/Doc/lib.tex b/Doc/lib.tex
index aa8c31e..38ba18d 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -121,6 +121,7 @@ to Python and how to embed it in other applications.
 \input{liberrno}
 \input{libglob}
 \input{libfnmatch}
+\input{liblocale}
 
 \input{libsomeos}		% Optional Operating System Services
 \input{libsignal}
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index aa8c31e..38ba18d 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -121,6 +121,7 @@ to Python and how to embed it in other applications.
 \input{liberrno}
 \input{libglob}
 \input{libfnmatch}
+\input{liblocale}
 
 \input{libsomeos}		% Optional Operating System Services
 \input{libsignal}
diff --git a/Doc/lib/liballos.tex b/Doc/lib/liballos.tex
index 2a536cd..cc889f3 100644
--- a/Doc/lib/liballos.tex
+++ b/Doc/lib/liballos.tex
@@ -29,4 +29,7 @@ systems as well.  Here's an overview:
 \item[fnmatch]
 --- Unix shell style pathname pattern matching.
 
+\item[locale]
+--- Internationalization services.
+
 \end{description}
diff --git a/Doc/lib/liblocale.tex b/Doc/lib/liblocale.tex
new file mode 100644
index 0000000..acc3620
--- /dev/null
+++ b/Doc/lib/liblocale.tex
@@ -0,0 +1,187 @@
+\section{Standard module \sectcode{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 \code{locale} module is implemented on top of the \code{_locale}
+module, which in turn uses an ANSI C locale implementation if
+available. 
+
+The \code{locale} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module locale)}
+
+\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 \code{locale.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.
+
+\code{setlocale} is not thread safe on most systems. Applications
+typically start with a call of
+\bcode\begin{verbatim}
+import locale
+locale.setlocale(locale.LC_ALL,"")
+\end{verbatim}\ecode
+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{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 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{itemize}
+\item 0 - Currency and value are surrounded by parentheses.
+\item 1 - The sign should precede the value and currency symbol.
+\item 2 - The sign should follow the value and currency symbol.
+\item 3 - The sign should immediately precede the value.
+\item 4 - The sign should immediately follow the value.
+\item LC_MAX - nothing is specified in this locale.
+\end{itemize}
+\end{funcdesc}
+
+\begin{funcdesc}{strcoll}{string1,string2}
+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 \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 builtin function
+\code{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=0}}
+Formats a number \var{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 \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
+\code{string.str}, but takes the decimal point into account.
+\end{funcdesc}
+
+\begin{funcdesc}{atof}{string}
+Converts a string to a floating point number, following the LC_NUMERIC
+settings.
+\end{funcdesc}
+
+\begin{funcdesc}{atoi}{string}
+Converts a string to an integer, following the LC_NUMERIC conventions.
+\end{funcdesc}
+
+\begin{datadesc}{LC_CTYPE}
+Locale category for the character type functions. Depending on the
+settings of this category, the functions of module \code{string}
+dealing with case change their behaviour.
+\end{datadesc}
+
+\begin{datadesc}{LC_COLLATE}
+Locale category for sorting strings. The functions \code{strcoll} and
+\code{strxfrm} of the locale module are affected.
+\end{datadesc}
+
+\begin{datadesc}{LC_TIME}
+Locale category for the formatting of time. The function
+\code{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 \code{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 \code{posix.strerror} might
+be affected by this category.
+\end{datadesc}
+
+\begin{datadesc}{LC_NUMERIC}
+Locale category for formatting numbers. The functions
+\code{format}, \code{atoi}, \code{atof} and \code{str} of the 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
+\code{localeconv}.
+\end{datadesc}
+
+\begin{excdesc}{Error}
+Exception raised when \code{setlocale} fails.
+\end{excdesc}
+
+Example:
+
+\bcode\begin{verbatim}
+>>> import locale
+>>> locale.open(locale.LC_ALL,"de") #setting locale to German
+>>> locale.strcoll("f\344n","foo")  #comparing a string containing an umlaut 
+>>> can.close()
+\end{verbatim}\ecode
diff --git a/Doc/liballos.tex b/Doc/liballos.tex
index 2a536cd..cc889f3 100644
--- a/Doc/liballos.tex
+++ b/Doc/liballos.tex
@@ -29,4 +29,7 @@ systems as well.  Here's an overview:
 \item[fnmatch]
 --- Unix shell style pathname pattern matching.
 
+\item[locale]
+--- Internationalization services.
+
 \end{description}
diff --git a/Doc/liblocale.tex b/Doc/liblocale.tex
new file mode 100644
index 0000000..acc3620
--- /dev/null
+++ b/Doc/liblocale.tex
@@ -0,0 +1,187 @@
+\section{Standard module \sectcode{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 \code{locale} module is implemented on top of the \code{_locale}
+module, which in turn uses an ANSI C locale implementation if
+available. 
+
+The \code{locale} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module locale)}
+
+\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 \code{locale.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.
+
+\code{setlocale} is not thread safe on most systems. Applications
+typically start with a call of
+\bcode\begin{verbatim}
+import locale
+locale.setlocale(locale.LC_ALL,"")
+\end{verbatim}\ecode
+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{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 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{itemize}
+\item 0 - Currency and value are surrounded by parentheses.
+\item 1 - The sign should precede the value and currency symbol.
+\item 2 - The sign should follow the value and currency symbol.
+\item 3 - The sign should immediately precede the value.
+\item 4 - The sign should immediately follow the value.
+\item LC_MAX - nothing is specified in this locale.
+\end{itemize}
+\end{funcdesc}
+
+\begin{funcdesc}{strcoll}{string1,string2}
+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 \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 builtin function
+\code{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=0}}
+Formats a number \var{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 \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
+\code{string.str}, but takes the decimal point into account.
+\end{funcdesc}
+
+\begin{funcdesc}{atof}{string}
+Converts a string to a floating point number, following the LC_NUMERIC
+settings.
+\end{funcdesc}
+
+\begin{funcdesc}{atoi}{string}
+Converts a string to an integer, following the LC_NUMERIC conventions.
+\end{funcdesc}
+
+\begin{datadesc}{LC_CTYPE}
+Locale category for the character type functions. Depending on the
+settings of this category, the functions of module \code{string}
+dealing with case change their behaviour.
+\end{datadesc}
+
+\begin{datadesc}{LC_COLLATE}
+Locale category for sorting strings. The functions \code{strcoll} and
+\code{strxfrm} of the locale module are affected.
+\end{datadesc}
+
+\begin{datadesc}{LC_TIME}
+Locale category for the formatting of time. The function
+\code{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 \code{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 \code{posix.strerror} might
+be affected by this category.
+\end{datadesc}
+
+\begin{datadesc}{LC_NUMERIC}
+Locale category for formatting numbers. The functions
+\code{format}, \code{atoi}, \code{atof} and \code{str} of the 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
+\code{localeconv}.
+\end{datadesc}
+
+\begin{excdesc}{Error}
+Exception raised when \code{setlocale} fails.
+\end{excdesc}
+
+Example:
+
+\bcode\begin{verbatim}
+>>> import locale
+>>> locale.open(locale.LC_ALL,"de") #setting locale to German
+>>> locale.strcoll("f\344n","foo")  #comparing a string containing an umlaut 
+>>> can.close()
+\end{verbatim}\ecode