Gargoyle is designed to work around a very simple API. Generally, you pass in the switch key and a list of instances to check this key against.
The simplest way to use Gargoyle is as a decorator. The decorator will automatically integrate with filters registered
User model, as well as IP address (using
from gargoyle.decorators import switch_is_active @switch_is_active('my switch name') def my_view(request): return 'foo'
In the case of the switch being inactive and you are using the decorator, a 404 error is raised. You may also redirect the user to an absolute URL (relative to domain), or a named URL pattern:
# If redirect_to starts with a /, we assume it's a url path @switch_is_active('my switch name', redirect_to='/my/url/path') # Alternatively use a name that will be passed to reverse() @switch_is_active('my switch name', redirect_to='access_denied')
An alternative, more flexible use of Gargoyle is with the
is_active method. This allows you to perform validation
on your own custom objects:
from gargoyle import gargoyle def my_function(request): if gargoyle.is_active('my switch name', request): return 'foo' else: return 'bar' # with custom objects from gargoyle import gargoyle def my_method(user): if gargoyle.is_active('my switch name', user): return 'foo' else: return 'bar'
Switches utilizing the named pattern of
parent:child will automatically inherit state from their parents. For
example, if your switch,
parent:child is globally enabled, but
parent is disabled, when
is_active('parent:child') is called it will return
A parent switch that has its status set to ‘inherit’ will return the default value for a switch, which is
(the same as disabled).
Currently inheritance does not combine filters. If your child defines any filters, they will override all of the parents.
Gargoyle includes a context manager, which may optionally be used as a decorator, to give temporary state to a switch on the currently executing thread.
from gargoyle.testutils import switches @switches(my_switch_name=True) def test_switches_overrides(): assert gargoyle.is_active('my_switch_name') # passes def test_switches_context_manager(): with switches(my_switch_name=True): assert gargoyle.is_active('my_switch_name') # passes
You may also optionally pass an instance of
SwitchManager as the first argument:
def test_context_manager_alt_gargoyle(): with switches(gargoyle, my_switch_name=True): assert gargoyle.is_active('my_switch_name') # passes
Gargoyle includes management commands which can be useful for task automation (e.g. deployment automation)
Adds or updates the specified gargoyle switch.
To create a globally enabled switch or enable an existed switch:
manage.py add_switch switch_name
To create a disabled switch or disable an existed switch:
manage.py add_switch --disabled switch_name
Removes the specified gargoyle switch.
manage.py remove_switch switch_name