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-documentation-vs-software-design-documentation/373442#373442)
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@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/SJWR73UOGRSVC3HKHR4SZEJ3KINH32PQ/
--
Regards,
Ivan
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@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/7R6ADYJMEAXI7PPJ5R3VLVVNH4UFSGAY/
