[3.11] gh-114552: Update `__dir__` method docs: it allows returning an iterable ...

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>

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 0419ee7e21a50a79b5f3f0fb9197fedcd7d9b4f4..c91e9cf43b11e2c894e421e3ffb4fd29092515ac 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1966,8 +1966,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
@@ -1987,7 +1987,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 a8f5b76d1bd6bf61d7d5e9a3f7d5e99afef1ee81..2b4fb0ebde42177b6b40d5ad2702850130196cef 100644 (file)
--- a/Lib/test/test_builtin.py
+++ b/Lib/test/test_builtin.py
@@ -577,6 +577,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):