On 16.07.19 00:32, Barry Warsaw wrote:
On Jul 13, 2019, at 19:09, Raymond Hettinger <raymond.hettinger@gmail.com> wrote:
In some modules, we've been careful to use both __all__ and to use an underscore prefix to indicate private variables and helper functions (collections and random for example). IMO, when a module has shown that care, future maintainers should stick with that practice.
The calendar module is an example of where that care was taken for many years and then a recent patch went against that practice. This came to my attention when an end-user questioned which functions were for internal use only and posted their question on Twitter. On the tracker, I then made a simple request to restore the module's convention but you seem steadfastly resistant to the suggestion.
When we do have evidence of user confusion (as in the case with the calendar module), we should just fix it. IMO, it would be an undue burden on the user to have to check every method in dir() against the contents of __all__ to determine what is public (see below). Also, as a maintainer of the module, I would not have found it obvious whether the functions were public or not. The non-public functions look just like the public ones.
It's true that the practices across the standard library have historically been loose and varied (__all__ wasn't always used and wasn't always kept up-to-date, some modules took care with private underscore names and some didn't). To me this has mostly worked out fine and didn't require a strict rule for all modules everywhere. IMO, there is no need to sweep through the library and change long-standing policies on existing modules.
EIBTI <wink>
Shameless plug: https://public.readthedocs.io/en/latest/
Hey, what a fantastic little module! I'll hurry and use that a lot! Especially the builtins idea is really great :-P Cheers - Chris p.s.: How about adding @private as well? There are cases where I would like to do the opposite: __all__ = dir() @private _some_private_func_1(...): ... ... @private _some_private_func_n(...): ... not-too-seriously yours - Chris -- Christian Tismer :^) tismer@stackless.com Software Consulting : http://www.stackless.com/ Karl-Liebknecht-Str. 121 : https://github.com/PySide 14482 Potsdam : GPG key -> 0xFB7BEE0E phone +49 173 24 18 776 fax +49 (30) 700143-0023