On Jul 13, 2019, at 1:56 PM, Serhiy Storchaka <storchaka@gmail.com> wrote:
I thought that the name in a module is in the public interface if:
* It doesn't start with an underscore and the module does not have __all__. * It is included in the module's __all__ list. * It is explicitly documented as a part of the public interface.
help() uses more complex rules, but it believes __all__ if it defined.
But seems there are different views on this.
* Raymond suggested to add an underscore the two dozens of names in the calendar module not included in __all__. https://bugs.python.org/issue28292#msg347758
I do not like this idea, because it looks like a code churn and makes the code less readable.
* Gregory suggests to document codecs.escape_decode() despite it is not included in __all__. https://bugs.python.org/issue30588
I do not like this idea, because this function always was internal, its only purpose was implementing the "string-escape" codec which was removed in Python 3 (for reasons). In Python 3 it is only used for supporting the old pickle protocol 0.
Could we strictly define what is considered a public module interface in Python?
My apologies for not having read this very large thread before posting, but hopefully this small note won't be adding too much fuel to the fire: Earlier this year I created an extremely small project called "publication" (https://pypi.org/project/publication/ <https://pypi.org/project/publication/>, https://github.com/glyph/publication <https://github.com/glyph/publication>) which attempts to harmonize the lofty ideal of "only the names explicitly mentioned in __all__ and in the documentation!" with the realpolitik of "anything I can reach where I don't have to type a leading underscore is fair game". It simply removes the ability to externally invoke non-__all__-exported names without importing an explicitly named "._private" namespace. It does not add any new syntactic idiom like a @public decorator (despite the aesthetic benefits of doing something like that) so that existing IDEs, type checkers, refactoring tools, code browsers etc can use the existing __all__ idiom and not break. It intentionally doesn't try hard to hide the implementation; it's still Python and if you demonstrate that you know what you're doing you're welcome to all the fiddly internals, it just makes sure you know that that's what you're getting. While I am perhaps infamously a stdlib contrarian ;-) this project is a single module with extremely straightforward, stable semantics which I would definitely not mind being copy/pasted into the stdlib wholesale, either under a different (private, experimental) name, or even under its current one if folks like it. I'd be very pleased if this could solve the issue for the calendar module. Thanks for reading, -glyph