Specify that __all__ should be a tuple

[parejkoj]

We've had some conversation about this on slack in the past, and settled on tuple, but never specified it in the dev guide.

[timj]

A tuple seems right to me given that you don't want someone to change the content, but there is a problem that the Python docs themselves use a list: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package

Not sure if we want to require tuple or just allow Sequence.

[timj]

The other downside of tuple is that:

__all__ = ("myfunc")

is not what you want but

__all__ = ["myfunc"]

will work without having to worry about the trailing comma.

[parejkoj]

Yeah, there's a tradeoff either way. Having ("myfunc") is caught immediately on import, and we don't have a lot of single-object modules. Should we have a poll?

[timj]

I'm happy to let @ktlim decide.

[ktlim]

It's really hard to search for __all__ tuple list on Slack :)

A GitHub search for __all__ = ( gives 234K code results; __all__ = [ gives 963K code results.

The "caught immediately on import" for a missing trailing comma gives a less-than-fully-helpful error (AttributeError: module 'y' has no attribute 'm').

https://stackoverflow.com/questions/66098828/using-list-instead-of-tuple-in-module-all gives some more arguments for list over tuple (including that it is sometimes useful to extend a list programmatically). "Accidentally" modifying __all__ seems pretty unlikely.

I would prefer to go with the syntax in the Python docs, so until the docs give a tuple example, we should stick with list.

[ktlim]

Note that even cpython is internally inconsistent: the somewhat newer asyncio and tomllib use tuple, while most other modules seem to use list (including ones where it's required due to modification).