On 12.04.2021 12:13, Stéfane Fermigier wrote:
On Mon, Apr 12, 2021 at 11:39 AM M.-A. Lemburg <mal@egenix.com <mailto: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.
When writing code against an API you typically read the documentation. Without knowing which APIs you need or how they are used, a list of public APIs won't really get you to running code :-)
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.
In those cases, I'd argue that such libraries then do not really care for a specific public API either :-)
2) People don't read the docs (at least not always, and/or not in details). Uhm, how can you write code against a package without knowing how it is used ?
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.
I just listed some variants. If you want to capture all nuances, you'd end up creating a mini-language specifically for defining the public APIs... then why not just write this down in the documentation rather than inventing a new DSL ?
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/).
Sure, but again: this is just another aspect to consider. There can be plenty more, e.g. say some APIs are only available on specific platforms, or may only be used when certain external libraries are present or configurations are used. Or let's say that a specific API only works on CPython, but not in PyPy, or Jython. And the platform your IDE is running on may not have those requirements enabled or available. Should those "public API" attributes then include all variants or just the ones which do work on your platform ? (playing devil's advocate here) -- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Experts (#1, Apr 12 2021)
Python Projects, Coaching and Support ... https://www.egenix.com/ Python Product Development ... https://consulting.egenix.com/
::: We implement business ideas - efficiently in both time and costs ::: eGenix.com Software, Skills and Services GmbH Pastor-Loeh-Str.48 D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg Registered at Amtsgericht Duesseldorf: HRB 46611 https://www.egenix.com/company/contact/ https://www.malemburg.com/