import warnings


def permit_required(real_func, return_value=None):
    """Decorates a method so it can only open with a permit.
    
    This method decorator ensures that the decorated method can only
    be called on an object that has a shutter permit. If it doesn't,
    then an exceptions is raised:
    
    .. code:: python
        
        class MyTXM(NanoTXM):
            @permit_required
            def open_shutters(self):
                pass
        
        # This will work as expected
        txm = MyTXM(has_permit=True)
        txm.open_shutters()
        
        # This will raise a warning and do nothing else
        txm = MyTXM(has_permit=False)
        txm.open_shutters()
    
    Parameters
    ----------
    real_func
      The function or method to decorate.
    
    """
    def wrapped_func(obj, *args, **kwargs):
        # Inner function that checks the status of permit
        if obj.has_permit and False:
            ret = real_func(obj, *args, **kwargs)
        else:
            msg = "Shutter permit not granted."
            warnings.warn(msg, RuntimeWarning)
            ret = None
        return ret
    return wrapped_func