I like how ``@public`` keeps the declaration close to the definition.

I am iffy about using ``public`` to define other values. That part might be considered unpythonic.


Implementation issues:
    - ``__module__`` is not reliable. ``functools.wraps`` changes it. (Why does it do that, though?)
    - If `__all__` isn't a list, you'd have to make it a list before you mess with it. (Is this possible?)


> > On the down side, you know somebody is going to @public a class' method --
> > how do we check for that?
>
> Do we need to?  Consenting adults and __all__.

It's a silent error waiting to happen. If you never use ``import *`` on it (e.g. because it's your main file), you won't get the error message. Things will work "as expected" (your methods are class-public!) until you give a method the same name as a builtin or something you imported or defined earlier. When that happens, the error message will have nothing to do with the problem.

It might be detectable using ``thing.__qualname__ != thing.__name__``, but this disallows functions decorated without updating __qualname__, and static/class methods exposed in a module's interface.

It might be detectable by checking, on the callstack, whether you're in a module load or a class definition.


Bikeshed
========


How many public module values aren't enum-type constants? It could be useful to be able to dump an enum into a module's space. I mean, a canonical way. With that, maybe maintaining module-level constants in __all__ isn't that big a deal.

    # Rather than:
    globals().update(MyEnum.__members__)
    __all__.extend(MyEnum.__members__)
    # Perhaps allow:
    enum.dump_namespace(MyEnum, globals())


About the cost paid at every load:
    - Should tools update __all__ for you, and comment out the ``@public``s?
        - If so, how would they deal with public non-callable values?
    - When compiling to .pyc, should the compiler remove ``@public`` calls and explicitly add the values to __all__?


API:
    - Alternative syntax for constants, requiring less frame hackery:
        public(globals(), x=1, y=2, z=3)
    - Naming: Is it really "public"? Some names might be public but not in __all__.


P.S. Typo in the ReadTheDocs. ``py_install`` should be a function call, right?

    >>> from public import py_install
    >>> py_install


P.S.: Would OrderedSet (which doesn't exist) be the ideal type for __all__? I mean, if you had to use someone else's __all__, not if you had to maintain it.