> On Jul 13, 2019, at 1:56 PM, Serhiy Storchaka <storch...@gmail.com> wrote:
>
> I thought that the name in a module is in the public interface if:
>
> * It doesn't start with an underscore and the module does not have __all__.
> * It is included in the module's __all__ list.
> * It is explicitly documented as a part of the public interface.
>
> help() uses more complex rules, but it believes __all__ if it defined.
>
> But seems there are different views on this.
>
> * Raymond suggested to add an underscore the two dozens of names in the
> calendar module not included in __all__.
> https://bugs.python.org/issue28292#msg347758
>
> I do not like this idea, because it looks like a code churn and makes the
> code less readable.
>
> * Gregory suggests to document codecs.escape_decode() despite it is not
> included in __all__.
> https://bugs.python.org/issue30588
>
> I do not like this idea, because this function always was internal, its only
> purpose was implementing the "string-escape" codec which was removed in
> Python 3 (for reasons). In Python 3 it is only used for supporting the old
> pickle protocol 0.
>
> Could we strictly define what is considered a public module interface in
> Python?
My apologies for not having read this very large thread before posting, but
hopefully this small note won't be adding too much fuel to the fire:
Earlier this year I created an extremely small project called "publication"
(https://pypi.org/project/publication/ <https://pypi.org/project/publication/>,
https://github.com/glyph/publication <https://github.com/glyph/publication>)
which attempts to harmonize the lofty ideal of "only the names explicitly
mentioned in __all__ and in the documentation!" with the realpolitik of
"anything I can reach where I don't have to type a leading underscore is fair
game". It simply removes the ability to externally invoke non-__all__-exported
names without importing an explicitly named "._private" namespace. It does not
add any new syntactic idiom like a @public decorator (despite the aesthetic
benefits of doing something like that) so that existing IDEs, type checkers,
refactoring tools, code browsers etc can use the existing __all__ idiom and not
break. It intentionally doesn't try hard to hide the implementation; it's
still Python and if you demonstrate that you know what you're doing you're
welcome to all the fiddly internals, it just makes sure you know that that's
what you're getting.
While I am perhaps infamously a stdlib contrarian ;-) this project is a single
module with extremely straightforward, stable semantics which I would
definitely not mind being copy/pasted into the stdlib wholesale, either under a
different (private, experimental) name, or even under its current one if folks
like it. I'd be very pleased if this could solve the issue for the calendar
module.
Thanks for reading,
-glyph
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at
https://mail.python.org/archives/list/python-dev@python.org/message/O3BKNPBV5AW7TS2C5NLPEI2TZGJOKDGP/
