[3.14] gh-85204: Improve `locale.setlocale` example (GH-132683) (#142798)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst
index 790bd3a5836423d10ad4cb65fafd434731fe18a3..0f49f30b9d765deed0cba1443600ff9e6ca73540 100644 (file)
--- a/Doc/library/locale.rst
+++ b/Doc/library/locale.rst
@@ -48,8 +48,19 @@ The :mod:`locale` module defines the following exception and functions:
    If *locale* is omitted or ``None``, the current setting for *category* is
    returned.
 
+   Example::
+
+      >>> import locale
+      >>> loc = locale.setlocale(locale.LC_ALL)  # get current locale
+      # use German locale; name and availability varies with platform
+      >>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
+      >>> locale.strcoll('f\xe4n', '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
+
    :func:`setlocale` is not thread-safe on most systems. Applications typically
-   start with a call of ::
+   start with a call of::
 
       import locale
       locale.setlocale(locale.LC_ALL, '')
@@ -573,18 +584,6 @@ The :mod:`locale` module defines the following exception and functions:
    :func:`localeconv`.
 
 
-Example::
-
-   >>> import locale
-   >>> loc = locale.getlocale()  # get current locale
-   # use German locale; name might vary with platform
-   >>> locale.setlocale(locale.LC_ALL, 'de_DE')
-   >>> locale.strcoll('f\xe4n', '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
-
-
 Background, details, hints, tips and caveats
 --------------------------------------------