From 416ecffcc49941a39ec3109eb20ae9ce558326ea Mon Sep 17 00:00:00 2001
From: Petri Lehtinen <petri@digip.org>
Date: Sat, 5 Nov 2011 10:18:50 +0200
Subject: [PATCH] Issue #3067: Enhance the documentation and docstring of
 locale.setlocale()

---
 Doc/library/locale.rst | 20 ++++++++++----------
 Lib/locale.py          |  5 +++--
 Misc/NEWS              |  3 +++
 3 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst
index 85dad990166..9cc3ab58850 100644
--- a/Doc/library/locale.rst
+++ b/Doc/library/locale.rst
@@ -23,19 +23,19 @@ The :mod:`locale` module defines the following exception and functions:
 
 .. exception:: Error
 
-   Exception raised when :func:`setlocale` fails.
+   Exception raised when the locale passed to :func:`setlocale` is not
+   recognized.
 
 
 .. function:: setlocale(category[, locale])
 
-   If *locale* is specified, it may be a string, a tuple of the form ``(language
-   code, encoding)``, or ``None``. If it is a tuple, it is converted to a string
-   using the locale aliasing engine.  If *locale* is given and not ``None``,
-   :func:`setlocale` modifies the locale setting for the *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 :exc:`Error` is raised.  If
-   successful, the new locale setting is returned.
+   If *locale* is given and not ``None``, :func:`setlocale` modifies the locale
+   setting for the *category*. The available categories are listed in the data
+   description below. *locale* may be a string, or an iterable of two strings
+   (language code and encoding). If it's an iterable, it's converted to a locale
+   name using the locale aliasing engine. An empty string specifies the user's
+   default settings. If the modification of the locale fails, the exception
+   :exc:`Error` is raised. If successful, the new locale setting is returned.
 
    If *locale* is omitted or ``None``, the current setting for *category* is
    returned.
@@ -51,7 +51,7 @@ The :mod:`locale` module defines the following exception and functions:
    changed thereafter, using multithreading should not cause problems.
 
    .. versionchanged:: 2.0
-      Added support for tuple values of the *locale* parameter.
+      Added support for iterable values of the *locale* parameter.
 
 
 .. function:: localeconv()
diff --git a/Lib/locale.py b/Lib/locale.py
index ae667a898b8..561e9e44788 100644
--- a/Lib/locale.py
+++ b/Lib/locale.py
@@ -524,9 +524,10 @@ def getlocale(category=LC_CTYPE):
 def setlocale(category, locale=None):
 
     """ Set the locale for the given category.  The locale can be
-        a string, a locale tuple (language code, encoding), or None.
+        a string, an iterable of two strings (language code and encoding),
+        or None.
 
-        Locale tuples are converted to strings the locale aliasing
+        Iterables are converted to strings using the locale aliasing
         engine.  Locale strings are passed directly to the C lib.
 
         category may be given as one of the LC_* values.
diff --git a/Misc/NEWS b/Misc/NEWS
index f55fe04b9c3..d053a2b090e 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -74,6 +74,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #3067: Enhance the documentation and docstring of
+  locale.setlocale().
+
 - Issue #13254: Fix Maildir initialization so that maildir contents
   are read correctly.