Ticket #2474: cron-doc.patch

tgscheduler/kronos.py

@@ -557 +557 @@
 
 
 class CronLikeTask(Task):
-    """A class that is scheduled with a cron-like syntax.
     """
+    A task that is scheduled based on a cron-like string.
+    
+    A Cron string is composed of **five** time and date fields, 
+    **separated by spaces**.
+    
+    Note: Tasks are executed when **all** the time and date fields match
+    the current time. This is an important difference with the UNIX Cron.
+    
+    The time and date fields are:
+
+    =============  ==================================
+        field                allowed values
+    =============  ==================================
+    minute         0-59
+    hour           0-23
+    day of month   1-31
+    month          1-12 (or names, see below)
+    day of week    0-7 (0 or 7 is Sun, or use names)
+    =============  ==================================
+
+    A field may be an **asterisk** (``*``), which always stands for
+    *first-last*.
+
+    **Ranges** of numbers are allowed. Ranges are two numbers separated with
+    a hyphen. The specified range is inclusive. For example, ``8-11`` for
+    an "hours" entry specifies *execution at hours 8, 9, 10 and 11*.
+
+    **Lists** are allowed. A list is a set of numbers (or ranges) separated
+    by commas. Examples: ``1,2,5,9``, ``0-4,8-12``.
+
+    **Step values** can be used in conjunction with ranges. Following a
+    range with  ``/<number>`` specifies skips of the number's value through
+    the range. For example,``0-23/2`` can be used in the "hours" field to
+    specify task execution *every other hour* (the alternative in the V7
+    standard is ``0,2,4,6,8,10,12,14,16,18,20,22``). Steps are also
+    permitted after an asterisk, so if you want to say *every two hours*,
+    just use ``*/2``.
+
+    **Names** can also be used for the "month" and "day of week" fields. Use
+    the first three letters of the particular day or month (case doesn't
+    matter). Ranges of mixed names and integer are not permitted.
+    """
     def __init__(self, name, action, cron_str, args=None, kw=None):
+        """Initializes the task."""
         Task.__init__(self, name, action, args, kw)
 
         self.cron_str = cron_str
@@ -588 +630 @@
     def __process_str(self, time_str, bounds, mapping=None):
         """Transforms a field of the cron-like string into a list
 
-        Note: specifying a range as a mix of integers and names
-              (months and dows) is NOT supported
-
         @param time_str: a field in the cron-like string
         @type time_str: string