[3.12] gh-114552: Update `__dir__` method docs: it allows returning an iterable (GH-114662) (#115234)

gh-114552: Update `__dir__` method docs: it allows returning an iterable (GH-114662)
(cherry picked from commit e19103a346f0277c44a43dfaebad9a5aa468bf1e)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

2 files changed, 11 insertions, 3 deletions

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index fcb65b8..a9ce0f4 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1983,8 +1983,8 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances.
 
 .. method:: object.__dir__(self)
 
-   Called when :func:`dir` is called on the object. A sequence must be
-   returned. :func:`dir` converts the returned sequence to a list and sorts it.
+   Called when :func:`dir` is called on the object. An iterable must be
+   returned. :func:`dir` converts the returned iterable to a list and sorts it.
 
 
 Customizing module attribute access
@@ -2004,7 +2004,7 @@ not found on a module object through the normal lookup, i.e.
 the module ``__dict__`` before raising an :exc:`AttributeError`. If found,
 it is called with the attribute name and the result is returned.
 
-The ``__dir__`` function should accept no arguments, and return a sequence of
+The ``__dir__`` function should accept no arguments, and return an iterable of
 strings that represents the names accessible on module. If present, this
 function overrides the standard :func:`dir` search on a module.
 
diff --git a/Lib/test/test_builtin.py b/Lib/test/test_builtin.py
index 4d03c46..211dd89 100644
--- a/Lib/test/test_builtin.py
+++ b/Lib/test/test_builtin.py
@@ -586,6 +586,14 @@ class BuiltinTest(unittest.TestCase):
         self.assertIsInstance(res, list)
         self.assertTrue(res == ["a", "b", "c"])
 
+        # dir(obj__dir__iterable)
+        class Foo(object):
+            def __dir__(self):
+                return {"b", "c", "a"}
+        res = dir(Foo())
+        self.assertIsInstance(res, list)
+        self.assertEqual(sorted(res), ["a", "b", "c"])
+
         # dir(obj__dir__not_sequence)
         class Foo(object):
             def __dir__(self):