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/issue30588I 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-documentation-vs-software-design-documentation/373442#373442)
_______________________________________________ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/SJWR73UOGRSVC3HKHR4SZEJ3KINH32PQ/
-- Regards, Ivan _______________________________________________ Python-Dev mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/[email protected]/message/7R6ADYJMEAXI7PPJ5R3VLVVNH4UFSGAY/