Merge pull request #106 from Miksus/dev/scheduler_cycle

ENH: Add scheduler_cycles

docs/code/conds/api/scheduler_cycles.py

@@ -0,0 +1,6 @@
+from rocketry import Rocketry
+from rocketry.conds import scheduler_cycles
+
+app = Rocketry(config={
+    "shut_cond": scheduler_cycles(more_than=1)
+})

docs/handbooks/conditions/api/scheduler.rst

@@ -12,5 +12,16 @@ if the scheduler has been running more than
 given in ``more_than`` argument. There is also
 an argument ``less_than`` to specify the maximum.
 
-.. literalinclude:: /code/conds/api/scheduler.py
+.. literalinclude:: /code/conds/api/scheduler_running.py
+    :language: py
+
+There is also a condition ``scheduler_cycles`` that
+also takes ``more_than`` and ``less_than`` arguments
+which are both integers. This condition checks whether 
+the scheduler has looped through the tasks for given
+number of time. This is useful for testing to, for example,
+do a short test that the scheduler launches your task.
+It is extensively used in Rocketry's unit tests.
+
+.. literalinclude:: /code/conds/api/scheduler_cycles.py
     :language: py

docs/versions.rst

@@ -6,6 +6,7 @@ Version history
 
     - Add: New condition, ``Retry``
     - Add: New condition to condition API, ``crontime``
+    - Add: New condition to condition API, ``scheduler_cycles`` (useful for testing)
     - Add: New arguments, ``EnvArg`` and ``CliArg``
     - Add: Argument pipelining, ``Arg('missing') >> Arg('found')``
     - Add: Now tasks can be set running with parameters using ``task.run(arg="value")``

rocketry/conditions/api.py

@@ -4,7 +4,7 @@
     TaskFinished, TaskRunnable, 
     TaskStarted, TaskSucceeded,
     Retry,
-    SchedulerStarted,
+    SchedulerStarted, SchedulerCycles,
 )
 from rocketry.core import (
     BaseCondition
@@ -235,5 +235,13 @@ def running(more_than:str=None, less_than=None, task=None):
 # Scheduler
 # ---------
 
-def scheduler_running(more_than:str=None, less_than=None):
+def scheduler_running(more_than:str=None, less_than:str=None):
     return SchedulerStarted(period=TimeSpanDelta(near=more_than, far=less_than))
+
+def scheduler_cycles(more_than:int=None, less_than:int=None):
+    kwds = {}
+    if more_than is not None:
+        kwds['__gt__'] = more_than
+    if less_than is not None:
+        kwds['__lt__'] = less_than
+    return SchedulerCycles.from_magic(**kwds)

rocketry/conditions/scheduler.py

@@ -10,15 +10,6 @@ class SchedulerCycles(BaseComparable):
     """Condition for whether the scheduler have had
     more/less/equal given amount of cycles of executing
     tasks.
-
-    Examples
-    --------
-
-    **Parsing example:**
-
-    >>> from rocketry.parse import parse_condition
-    >>> parse_condition("scheduler had more than 3 cycles")
-    SchedulerCycles(_gt_=3)
     """
 
     def get_measurement(self, session=Session()) -> int:

rocketry/conds/__init__.py

@@ -13,7 +13,7 @@
     started, succeeded, failed, finished,
     retry,
 
-    scheduler_running,
+    scheduler_running, scheduler_cycles,
     running,
     cron, 
     crontime,

rocketry/test/condition/test_api.py

@@ -1,5 +1,5 @@
 import pytest
-from rocketry.conditions.scheduler import SchedulerStarted
+from rocketry.conditions.scheduler import SchedulerCycles, SchedulerStarted
 from rocketry.conditions.task.task import TaskFailed, TaskFinished, TaskRunning, TaskStarted, TaskSucceeded
 
 from rocketry.conds import (
@@ -11,7 +11,7 @@
 
     after_all_success, after_any_success, after_all_fail, after_any_fail, after_all_finish, after_any_finish,
 
-    scheduler_running,
+    scheduler_running, scheduler_cycles,
 
     succeeded, failed, finished, started,
     running,
@@ -128,6 +128,9 @@
 
 params_schedule = [
     pytest.param(scheduler_running("10 mins"), SchedulerStarted(period=TimeSpanDelta("10 mins")), id="scheduler running (at least)"),
+    pytest.param(scheduler_cycles(5), SchedulerCycles() > 5, id="scheduler cycles (at least)"),
+    pytest.param(scheduler_cycles(less_than=5), SchedulerCycles() < 5, id="scheduler cycles (less than)"),
+    pytest.param(scheduler_cycles(1, 5), (SchedulerCycles() > 1) < 5, id="scheduler cycles (between)"),
 ]
 
 cron_like = [