On Mon, Apr 12, 2021 at 11:39 AM M.-A. Lemburg <mal@egenix.com> wrote:
I don't think that trying to do this programmatically via some kind of language construct is a good approach.
It's not the only approach, but I argue that it's useful. Two use cases: - IDE's that will nudge the developer towards importing the "right" objects. - Linters and runtime checkers that will issue warnings / errors and minimise the amount of human code auditing or reviewing.
The public API of a library is the one which is documented as such.
Right, except that in practice: 1) Many useful libraries are not documented or properly documented. 2) People don't read the docs (at least not always, and/or not in details).
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.
E.g. you may have situations where you have more than one level of documented APIs, e.g. a public stable one and an experimental one which is likely to change over time, or a high level one and a low-level one, where more care has to be applied in using it.
Yes. This can be formalized by having more than one namespace for the Public API.
Or you have APIs which are deprecated but still public and you know that the APIs will go away in a future version, so you should probably not start using them in new code and plan for a refactoring of existing code.
There are already conventions and tools for that, e.g. the @deprecated decorator (https://pypi.org/project/Deprecated/). S. -- Stefane Fermigier - http://fermigier.com/ - http://twitter.com/sfermigier - http://linkedin.com/in/sfermigier Founder & CEO, Abilian - Enterprise Social Software - http://www.abilian.com/ Chairman, National Council for Free & Open Source Software (CNLL) - http://cnll.fr/ Founder & Organiser, PyParis & PyData Paris - http://pyparis.org/ & http://pydata.fr/