On 13.07.2019 23:56, Serhiy Storchaka 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? Is "what is present in the reference documentation" insufficient? Documenting all the official guarantees (which the public interface is a part of) is the whole purpose of a reference documentation. (https://softwareengineering.stackexchange.com/questions/373439/technical-doc...) _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/SJWR73UO...
-- Regards, Ivan