This is a great discussion. However, there's one issue that seems to be getting lost. Consider this library structure: test/lemon test/lemon/__init__.py test/module.py where test/module.py is: __all__ = ['lemon'] def lemon(): pass and test/__init__.py is: from .module import * from .lemon import * and test/lemon/__init__.py is empty. What do you think test.lemon is? It's not the function because it's hidden by the eponymous package. Also, test.module is exported whether you wanted to export it or not. This is the problem with any mechanism like __all__ or export. I think the main motivation behind the Jax team tucking everything in _src is that it hides the package names and module names from the public interface. I think I'm going to start only using __all__ for collecting private symbols into packages under a _src package. For the external interface, I'm going to explicitly import from dummy modules. I'd love to know if something better exists, but I don't think the export keyword works because of the above problem. Best, Neil On Mon, Apr 12, 2021 at 7:39 AM Joseph Martinot-Lagarde <contrebasse@gmail.com> wrote:
M.-A. Lemburg wrote:
The public API of a library is the one which is documented as such. That's really all there is to it. Documentation is written explicitly by the author of a package and languages provides a lot more nuances than using some programmatic mechanism. I use __all__ with sphinx to automatically build my documentation, so __all__ effectively becomes part of the documentation. I don't expect people to use import *. Maybe for big projects there is a need to write all the documentation by hand, but for small libraries using __all__ and automatically build the documentation (along other pages like FAQ, HOWTO and so on) is very powerful and makes a good documentation while assurint it's up to date with the code. There are definitely use cases for __all__ outside of import *.
Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-leave@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/ASZOJH... Code of Conduct: http://python.org/psf/codeofconduct/
--
--- You received this message because you are subscribed to a topic in the Google Groups "python-ideas" group. To unsubscribe from this topic, visit https://groups.google.com/d/topic/python-ideas/c2JTmIJnX5c/unsubscribe. To unsubscribe from this group and all its topics, send an email to python-ideas+unsubscribe@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/python-ideas/161822751700.5428.12873752338....