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 <[email protected]>
wrote:
> On Mon, 12 Apr 2021 at 21:27, Brendan Barnwell <[email protected]>
> 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 -- [email protected]
> To unsubscribe send an email to [email protected]
> https://mail.python.org/mailman3/lists/python-ideas.python.org/
> Message archived at
> https://mail.python.org/archives/list/[email protected]/message/HYMDSAFXYAOKY62DSRBUI5QJ4IZDEGVF/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
_______________________________________________
Python-ideas mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/[email protected]/message/HZU7IFIUR4YXCTMRB5LWFRRZOLZNDYJJ/
Code of Conduct: http://python.org/psf/codeofconduct/
