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.benja...@gmail.com> wrote: > On Mon, 12 Apr 2021 at 21:27, Brendan Barnwell <brenb...@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-le...@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/HYMDSAFXYAOKY62DSRBUI5QJ4IZDEGVF/ > Code of Conduct: http://python.org/psf/codeofconduct/ >
_______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-le...@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/HZU7IFIUR4YXCTMRB5LWFRRZOLZNDYJJ/ Code of Conduct: http://python.org/psf/codeofconduct/