Author aeros
Recipients aeros, belopolsky, jiangping.li, rhettinger, serhiy.storchaka, xiang.zhang
Date 2019-07-14.04:00:16
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1563076817.66.0.869956316292.issue28292@roundup.psfhosted.org>
In-reply-to
Content
>But we have precedent in this module and should maintain it.

In general, applying different rules to standard library modules and changing private function naming conventions on a case-by-case basis creates rather drastic inconsistency. There definitely should be a universal standard across stdlib, especially for something as fundamental as private function naming. The precedent really should not be on a per-module basis.

As someone who joined the Python development community only a month ago but was a user of the language for 5 years, the most common convention to denote privation functions was a preceding underscore. In a perfect world where simplicity is the only concern, this should be the guideline in which stdlib follow consistently across the modules. However, Serhiy makes a very valid point:

> There are hundreds or thousands of private names in other modules. Do you propose to change them all? I afraid that this will cause more harm than benefit.

__all__ has been far easier to maintain since functions can be added or removed without issue and there's no need to rename them. However, as far as I am aware, this is no clear documentation that membership on the __all__ list denotes whether or not a function is public. Also, any user using "import module" instead of "from module import *" may not be aware they are accessing a private function.

Here's a few solutions I thought of (not mutually exclusive):

1) Document that "The list from __all__ is the universal stdlib convention for marking functions as public, and any not on the list are considered private. When possible, underscore is preferred as well, but the lack of an underscore does not necessarily mean the function is public."

2) When a user attempts to import or use a function that is not in __all__, a minimally intrusive warning message is shown upon execution to notify them that they are using a private function which is not officially supported for external usage. There should be a way to easily suppress this message if the user desires.

3) Add a new syntax similar to "import module" that only imports public functions. Currently, "from module import *" somewhat provides this, but does not allow for using the "module.function" syntax for referencing the functions.

The exact convention for marking functions as public or private is not nearly as important as having universal consistency across stdlib and clear communication to the users. This does not seem to be the case at the moment.
History
Date User Action Args
2019-07-14 04:00:17aerossetrecipients: + aeros, rhettinger, belopolsky, serhiy.storchaka, xiang.zhang, jiangping.li
2019-07-14 04:00:17aerossetmessageid: <1563076817.66.0.869956316292.issue28292@roundup.psfhosted.org>
2019-07-14 04:00:17aeroslinkissue28292 messages
2019-07-14 04:00:16aeroscreate