__all__ is well :)

lang.py

from __future__ import absolute_import

import inspect
from contextlib import contextmanager

class PublicDecorator(object):
    """
    The global instance of this class, public, provides the mechanism
    for managing __all__ list, thus liberating developers from
    error-prone maintenance of __all__ by hand.

    Usage example:

    from lang import public

    @public
    def a_public_func():
        # this function will be added to the module's __all__
        pass

    def other_func():
        # this function is for internal use in this module
        # and won't be added to __all__
        pass

    # defines a global var 'answer' in this module, and adds it
    # to __all__
    public.var('answer', 42)

    """
    def __call__(self, thing):
        """
        Ensure the specified class or function (aka 'thing') is added
        to the calling module's __all__ list.

        Based on:
        http://code.activestate.com/recipes/576993/
        """
        try:
            name = thing.__name__
            module_name = thing.__module__
        except AttributeError as ex:
            raise TypeError(str(ex))
        else:
            module = inspect.getmodule(thing)
            self._add_to_all(module, name)
            return thing

    @classmethod
    def var(cls, name, value):
        """
        Set the global var and add it to the calling module's __all__
        list.
        """
        try:
            frame = inspect.stack()[1]
            module = inspect.getmodule(frame[0])
            cls._add_to_all(module, name)
            module.__dict__[name] = value
            return value
        finally:
            # Forget these objects ASAP.
            # See admonition here:
            # http://docs.python.org/library/inspect.html#the-interpreter-stack
            del frame
            del module

    @classmethod
    def _add_to_all(cls, module, name):
        all_list = module.__dict__.setdefault('__all__', [])
        if name not in all_list:
            all_list.append(name)

# Drink our own champagne: declare a global var named 'public', and
# set it to an instance of PublicDecorator().
# NOTE: this is not the normal usage example, don't try this at home.
public = PublicDecorator.var('public', PublicDecorator())

test_lang.py

from __future__ import absolute_import

import sys
import unittest
from lang import public

def a_function():
    pass

class AClass(object):
    pass

class PublicDecoratorTests(unittest.TestCase):
    def setUp(self):
        self.module_dict = sys.modules[self.__class__.__module__].__dict__
        self.module_dict.pop('aaa', None)
        self.module_dict['__all__'] = []

    def test_public_adds_distinct_things_to_all(self):
        public(a_function)
        public(a_function)
        public(AClass)
        public(AClass)
        self.assertEqual(['a_function', 'AClass'], __all__)

    def test_public_must_be_used_on_a_thing_with_name_and_module(self):
        with self.assertRaises(TypeError):
            public(5)

    def test_public_var(self):
        self.assertNotIn('aaa', __all__)
        # Ensure aaa is not a defined global in this module
        with self.assertRaises(NameError):
            type(aaa)

        self.assertEqual(5, public.var('aaa', 5))

        self.assertIn('aaa', __all__)
        # By now, aaa a global in this module.
        self.assertEqual(aaa, 5)