

## Singleton Class define a pattern to limit the number of instance
#  in run at once.
#  A non-thread-safe helper class to ease implementing singletons.
#  This should be used as a decorator -- not a metaclass -- to the
#  class that should be a singleton.
#
#  The decorated class can define one `__init__` function that
#  takes only the `self` argument. Other than that, there are
#  no restrictions that apply to the decorated class.
#
#  To get the singleton instance, use the `Instance` method. Trying
#  to use `__call__` will result in a `TypeError` being raised.
#
#  Limitations: The decorated class cannot be inherited from.
class Singleton:

    ## The Constructor
    #  @param decorated is the class to decorate with this pattern
    def __init__(self, decorated):
        self._decorated = decorated

    ## Instance method
    #  Returns the singleton instance. Upon its first call, it creates a
    #  new instance of the decorated class and calls its `__init__` method.
    #  On all subsequent calls, the already created instance is returned.
    def instance(self):
        try:
            return self._instance
        except AttributeError:
            self._instance = self._decorated()
            return self._instance

    ## Call method
    #  @return an error if they are called
    def __call__(self):
        raise TypeError('Singletons must be accessed through `Instance()`.')

    ## Instance check
    #  @param inst an instance to check
    #  @return if an instance already exists
    def __instancecheck__(self, inst):
        return isinstance(inst, self._decorated)
