adding rules.

tests/decorators/test_rules.py

@@ -0,0 +1,60 @@
+from uranium import rule
+
+
+def test_rule_does_not_execute(build):
+
+    g = []
+
+    def rule_func(build):
+        return True
+
+    @rule(rule_func)
+    def main(build):
+        g.append("main")
+
+    main(build)
+    assert "main" not in g
+
+
+def test_all_true_multiple_rules(build):
+    """
+    if all rules return true, don't execute the task
+    """
+
+    g = []
+
+    def rule_func(build):
+        return True
+
+    def rule_func_2(build):
+        return True
+
+    @rule(rule_func)
+    @rule(rule_func_2)
+    def main(build):
+        g.append("main")
+
+    main(build)
+    assert "main" not in g
+
+
+def test_one_false_multiple_rules(build):
+    """
+    if one rule return false, execute the task
+    """
+
+    g = []
+
+    def rule_func(build):
+        return True
+
+    def rule_func_2(build):
+        return False
+
+    @rule(rule_func)
+    @rule(rule_func_2)
+    def main(build):
+        g.append("main")
+
+    main(build)
+    assert "main" in g

uranium/__init__.py

@@ -7,4 +7,4 @@
 import setuptools
 
 from .remote import get_remote_script
-from .decorators import task_requires
+from .decorators import task_requires, rule

uranium/decorators.py

@@ -1,4 +1,5 @@
 import functools
+from .experimental import experimental
 
 
 def task_requires(func_or_func_name):
@@ -23,3 +24,37 @@ def func(build):
         return func
 
     return decorator
+
+
+@experimental
+def rule(rule_func):
+    """
+    the rule decorator is used to add a rule function to the task.
+
+    the rule function should accept a build object, and should return
+    True in the case where a build is required.
+
+    multiple rules can be added to a task. If any of the rules return false,
+    the task will be re-executed.
+    """
+    key = "_uranium_rules"
+
+    def decorator(f):
+
+        if hasattr(f, key):
+            getattr(f, key).append(rule_func)
+            return f
+
+        rules = [rule_func]
+
+        @functools.wraps(f)
+        def func(build):
+            if all((r(build) for r in rules)):
+                return 0
+            return f(build)
+
+        setattr(func, key, rules)
+
+        return func
+
+    return decorator

uranium/experimental.py

@@ -0,0 +1,7 @@
+def experimental(func):
+    """
+    tag a function within uranium as experimental.
+    mainly for documentation purposes.
+    """
+    func.experimental = True
+    return func