__all__ attribute: bug and proposal

[Ethan Furman]

On 06/27/2016 09:31 PM, Zachary Ware wrote:
> On Mon, Jun 27, 2016 at 7:32 PM, Chris Angelico wrote:

>> If you're primarily worried about classes and functions, here's a neat
>> trick you can use:
>>
>> __all__ = []
>> def all(thing):
>>      __all__.append(thing.__name__)
>>      return thing
>
> Barry Warsaw has written a nice decorator called 'public' that can be
> installed from PyPI as 'atpublic'[0].  It was proposed for inclusion
> as a builtin in 3.6 [1], but a less-than-enthusiastic response at the
> 2016 Language Summit has put that off indefinitely.  I, for one, would
> like to see it happen anyway [2], and public support may make it
> possible.
>
> The '@public' decorator works like so:
>
> """
> # spam.py
>
> @public
> def spam():
>      return ' '.join(['spam']*10)
>
> @public
> def eggs():
>      return 'bacon'
>
> public(HAM=4)
> assert HAM == 4
>
> assert sorted(__all__) == sorted(['spam', 'eggs', 'HAM'])
> """
>
> This strikes me as being a cleaner approach than what the OP
> suggested, easier to use than Chris' simple decorator, and a nice way
> to bring an end to outdated __all__ lists (which is a problem
> currently plaguing the standard library, and probably many other
> libraries).

I agree.  But lets all do:

   from atpublic import public as api

as using 'public' for the name is bound to lead to confusion with other 
languages that use public to mean something else, and __all__ is really 
defining the public _API_ of that module.

--
~Ethan~