So I think there are multiple behaviors that are being described here and I think there is validity in being able to potentially patch/modify definitions when absolutely necessary, but I wonder if there's room here for something in-between (also, I find the 'import export' or 'export import' statements quite hard to read. Please don't combine 2 verbs in one statement) Here's my preference (which admittedly is partially taken from NodeJS/Javascript): """ # Base examples export x = 2 export x as y # Export a previous name under a new name (not quoted to emphasize it must be a valid variable name, not arbitrary string) export class MyClass: pass export DEFAULT = MyClass() DEFAULT.setup_with_defaults() # exported entities named within this module are named entities # Exporting from other modules from .my_submodule export * # This is just syntactic sugar similar to "from .my_submodule import *" where in this case it's a pure forwarding reference. Debatable on whether or not the found name are assigned to in the current local namespace from .my_other_submodule export ThisInterface as ThatInterface """ That said, I'm very new here and understand there are likely multiple edge-cases I'm not considering. But I am a very interested stakeholder in the result :-) Cheers, -Jeff On Mon, Apr 12, 2021 at 2:36 PM Oscar Benjamin <oscar.j.benjamin@gmail.com> wrote:
On Mon, 12 Apr 2021 at 21:27, Brendan Barnwell <brenbarn@brenbarn.net> wrote:
On 2021-04-12 03:13, Stéfane Fermigier wrote:
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.
Then they're buggy. I'm not convinced by the argument that "in practice" people do things they shouldn't do and that therefore we should encourage them to do more of that.
A library can be useful and buggy at the same time or it can be useful but have some parts that are buggy and less useful.
Ideally if some code is (potentially) useful but buggy then someone would come along and make it less buggy. If one of the deficiencies of the code to be improved is that it does not have a clear distinction between public and internal API then that task can be made much more difficult.
2) People don't read the docs (at least not always, and/or not in details).
Insofar as someone relies on behavior other than that given in the docs, they are being foolish. Again, I'm not convinced by the argument that "in practice" people do foolish things and that therefore we should encourage them to do more of that.
Maybe the docs were not so clear or maybe the library just has a lot of users or maybe some combination of the two. Either way it's much better for everyone involved if the code can be improved or extended without breaking things for people who are already using it. Standardising on simple practice that helps to make that happen is no bad thing.
Oscar _______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-leave@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/HYMDSA... Code of Conduct: http://python.org/psf/codeofconduct/