[issue26632] __all__ decorator

[Franklin? Lee]

Franklin? Lee added the comment:

>I don't know, but what practical effect will this have?  I.e. under what
>conditions would you @public wrap a @functools.wraps function and want it to
>show up in __all__?  Do you have a specific use case?

I sometimes wrap functions that return iterators to make functions that return lists, because I work on the interpreter a lot. From there, it's not much of a stretch to imagine functions which are implemented as decorated versions of other functions.

If @public were only to be used as a decorator, it would not be possible to have `public` called on a function outside of its definition. But someone might call `public(some_decorator(some_function))`.

(@public is really a macro, if you think about it.)

>It would be possible.

(I meant, is it possible for someone to have a non-list __all__?)

If the `.append` fails, I think there should be a meaningful error. Perhaps "'__all__' is not a list."

>Sure, we could probably add some heuristics, but I still don't see the need
>for the extra complexity.  The error will be far from the declaration, but the
>exception should make it relatively obvious what's going on.  I also really
>don't think folks would naturally be inclined to put @public on anything but a
>top-level definition.  You wouldn't ever put such a thing in your __all__ so
>why would you decorate it with @public?

I'm thinking of the people who don't read docs and are coming from other languages. They'd put `@public` over their method, and one day they'd `import *` from that file (whereas they used to only import explicitly), getting an error about a name not being defined in their module. "But why would that name need to be defined? It's a method."

Or worse, the name of the method just happens to be the same as something in some other file, so they'll focus on why that NAME is being expected in THIS file.

>Also, I know that I have several cases where constants are actually
>instances.  They could be marker objects like::
>
>    MARKER = object()

(Here's food for thought: A MARKER could be a one-element enum, both conceptually and by implementation. Just like how the "bool enum" is {True,False} and the "None enum" is {None}.)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue26632>
_______________________________________