Must `object.__dir__` return a sequence of `str`, or is any iterable OK?

[ktbarrett]

According to the documentation __dir__ must return a Sequence, but e.g. typeshed's annotations currently imply that any iterable will do:

class object:
    def __dir__(self) -> Iterable[str]: ...

https://github.com/python/typeshed/blob/26452a7c68c6ad512be00b553f7a03f869f64be9/stdlib/builtins.pyi#L125

Linked PRs

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

[srittau]

Thanks for reporting this, the annotation was "always" wrong (since at least 2017). PR welcome.

[hauntsaninja]

I think the Python docs can sometimes be a little imprecise about what "sequence" means. E.g., the actual code that dir() uses just calls PySequence_List on the result of __dir__(). PySequence_List is another good example of imprecise use of "sequence"; it's perfectly happy to take in an iterable. So everything always works with Iterable at runtime.

[srittau]

Indeed. Another alternative is to fix the Python docs to match the implementation. Maybe this is something we should try first? In any case, I think it's important to be precise here, for cases, where someone uses __dir__ directly.

[AlexWaygood]

I can find one use of __dir__ in the stdlib where it returns a non-sequence:

cpython/Lib/unittest/__init__.py

Lines 72 to 73 in ea3cd04

	def __dir__():
	return globals().keys() | {'IsolatedAsyncioTestCase'}

It's a module-level use of __dir__ rather than a a method. (But then, ModuleType is a subclass of object, just like any other class. And the datamodel docs for __dir__ as a module-level function also state that it "should return a sequence".)

[srittau]

I suggest to move this issue to python/cpython and suggest to change the docs. Returning a set from __dir__ makes a lot of sense to me.

[AlexWaygood]

I've transferred this issue to CPython and made some light edits to a few comments by participants in the discussion, so that the issue thread will make sense to CPython triagers reading it for the first time.

[sobolevn]

My 2c:

• PySequence_List already says: Return a list object with the same contents as the sequence or iterable *o*, which I guess is fine
• I've updated __dir__ docs to mention iterable instead of sequence, because it is how runtime behaves (correctly)