This problem report about the locale module
consists of three closely related parts 
(this is why I have decided to put it in one report).
a) the example in the docs is wrong / missleading
b) under some locale settings python as a defect
c) a test case for the locale module, showing b)
   but useful as general start for a test module.

Details:
        a)
        Section example:
                The line
                >>> loc = locale.getlocale(locale.LC_ALL) # get current locale
                contradicts that getlocale should not be called with
                        LC_ALL, as stated in the description of getlocale.
                Suggestion is to change the example to be more useful
                as getting the locale as first action is not really useful.
                It should be "C" anyway which will lead to (None, None)
                so the value is already known. It would make more sense to

                first set the default locale to the user preferences:
import locale
locale.setlocale(locale.LC_ALL,'')
loc = locale.getlocale(locale.LC_NUMERIC)
locale.setlocale(locale.LC_NUMERIC,"C")
# convert a string here
locale.setlocale(locale.LC_NUMERIC, loc)

                _but_ this does not work, see problem b).
                What does work is:

import
locale.setlocale(locale.LC_ALL,'')
loc = locale.setlocale(locale.LC_NUMERIC)
locale.setlocale(locale.LC_NUMERIC,"C")
# convert a string here
locale.setlocale(locale.LC_NUMERIC, loc)

Note that all_loc = locale.setlocale(locale.LC_ALL) might contain
several categories (see attached test_locale.py where I needed to decode
this).
'LC_CTYPE=de_DE.UTF-8;LC_NUMERIC=en_GB.utf8;LC_TIME=de_DE.UTF-8;LC_COLLATE=de_DE.UTF-8;LC_MONETARY=de_DE.UTF-8;LC_MESSAGES=de_DE.UTF-8;LC_PAPER=de_DE.UTF-8;LC_NAME=de_DE.UTF-8;LC_ADDRESS=de_DE.UTF-8;LC_TELEPHONE=de_DE.UTF-8;LC_MEASUREMENT=de_DE.UTF-8;LC_IDENTIFICATION=de_DE.UTF-8'


        b)
                The output of getlocale cannot be used as input to
                setlocale sometimes.
                Works with
                * python2.5 und python2.4 on
                  Debian GNU/Linux Etch ppc, de_DE.utf8.

                I had failures with
                * python2.3, python2.4, python2.5
                  on Debian GNU/Linux Sarge ppc, de_DE@euro
                * Windows XP SP2
                        python-2.4.4.msi    German, see:

                >>> import locale
                >>> result = locale.setlocale(locale.LC_NUMERIC,"")
                >>> print result
                German_Germany.1252
                >>> got = locale.getlocale(locale.LC_NUMERIC)
                >>> print got
                ('de_DE', '1252')
                >>> # works
                ... locale.setlocale(locale.LC_NUMERIC, result)
                'German_Germany.1252'
                >>> # fails
                ... locale.setlocale(locale.LC_NUMERIC, got)
                Traceback (most recent call last):
                  File "<stdin>", line 2, in ?
                  File "C:\Python24\lib\locale.py", line 381, in setlocale
                    return _setlocale(category, locale)
                locale.Error: unsupported locale setting
                >>>