diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Makefile | 2 | ||||
| -rw-r--r-- | Doc/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/liballos.tex | 3 | ||||
| -rw-r--r-- | Doc/lib/liblocale.tex | 187 | ||||
| -rw-r--r-- | Doc/liballos.tex | 3 | ||||
| -rw-r--r-- | Doc/liblocale.tex | 187 |
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 |