Metadata-Version: 1.1
Name: cronex
Version: 0.1.3.1
Summary: This module provides an easy to use interface for cron-like task scheduling.
Home-page: https://github.com/ericpruitt/cronex
Author: Eric Pruitt
Author-email: eric.pruitt@gmail.com
License: MIT
Description: CronExpression
        ==============
        
        This module provides an easy to use interface for cron-like task
        scheduling. The cron expression evaluation implemented by this library
        is 100% Vixie Cron compatible and also supports `Java
        Quartz's <http://www.quartz-scheduler.org/documentation/quartz-1.x/tutorials/crontrigger>`__
        non-standard "L", "W" and "#" characters.
        
        One other useful feature this library provides is the ability to set
        triggers at arbitrary intervals such as every 9 hours, every 11 minutes,
        etc., without the issues caused by using asterisk-slash notation; using
        ``*/9`` in the hours field of most cron implementations would result in
        a trigger firing at 9:XX AM at 6:XX PM each day, but with
        CronExpresssions, the trigger would fire at 9:XX AM, 6:XX PM then, on
        the following day 3:XX AM, 12:XX PM, 9:XX PM and so.
        
        Examples
        --------
        
        Standard Cron Fields
        ~~~~~~~~~~~~~~~~~~~~
        
        This example shows basic instantiation of a CronExpression and how to
        check to see if a trigger should fire at a given time. The time tuples
        consist of the year, month, date, hour and minute in that order.
        
        ::
        
            >>> job = CronExpression("0 0 * * 1-5/2 find /var/log -delete")
            >>> job.check_trigger((2010, 11, 17, 0, 0))
            True
            >>> job.check_trigger((2012, 12, 21, 0 , 0))
            False
        
        Periodic Trigger
        ~~~~~~~~~~~~~~~~
        
        This trigger is a reminder to feed the kitten every 9 hours starting
        from May 1st, 2010 at 7 AM, GMT -6:00.
        
        ::
        
            >>> job = CronExpression("0 %9 * * * Feed kitten", (2010, 5, 1, 7, 0, -6))
            >>> job.comment
            "Feed kitten"
            >>> job.check_trigger((2010, 5, 1, 7, 0), utc_offset=-6)
            True
            >>> job.check_trigger((2010, 5, 1, 16, 0), utc_offset=-6)
            True
            >>> job.check_trigger((2010, 5, 2, 1, 0), utc_offset=-6)
            True
        
        Simple cron scheduler in less than ten lines
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        With CronExpressions, a very basic task scheduler can be created with
        only a handful of lines.
        
        ::
        
            import time
            import os
            import cronex
        
            while True:
                for line in open("crontab"):
                    job = cronex.CronExpression(line.strip())
        
                    if job.check_trigger(time.gmtime(time.time())[:5]):
                        os.system("(" + job.comment + ") & disown")
        
                time.sleep(60)
        
        Expression Syntax
        -----------------
        
        Readers that are already familiar with cron should skip down to the
        section titled *Repeaters*. Aside from the repeaters, the only other
        notable difference in this implementation of cron expression evaluation
        from Vixie Cron's is that ranges wrap around: 22-2 in the hours field is
        the same as ``22,23,0,1,2``. Everything else is standard
        ``man 5 crontab``.
        
        Each cron trigger is specified with a combination of five white-space
        separated fields that dictate when the event should occur. In order the
        fields specify trigger times for minutes past the hour, hour of the day,
        day of the month, month, and day of the week.
        
        ::
        
            .--------------- minute (0 - 59)
            |   .------------ hour (0 - 23)
            |   |   .--------- day of month (1 - 31)
            |   |   |   .------ month (1 - 12) or Jan, Feb ... Dec
            |   |   |   |  .---- day of week (0 - 6) or Sun(0 or 7), Mon(1) ... Sat(6)
            V   V   V   V  V
            *   *   *   *  *  command to be executed / trigger comment
        
        There are four ways of specifying valid values for each field, all of
        which can be combined with each other using commas. There are ranges,
        wild-cards, steps, and repeaters. Repeaters are a non-standard addition
        to cron expressions that allow specification of events with arbitrary
        periods.
        
        If the hour, minute, and month of a given time period are valid values
        as specified in the trigger and *either* the day of the month *or* the
        day of the week is a valid value, the trigger fires.
        
        Ranges and Wild-cards
        ~~~~~~~~~~~~~~~~~~~~~
        
        Ranges specify a starting and ending time period. It includes all values
        from the starting value to and including the ending value.
        
        Wild-cards, indicated with a "\*", in a field represents all valid
        values. It is *almost* the same as specifying the range 0-59 in the
        minutes field, 0-23 in the hours, 1-31 in days, 1-12 in months and 0-6
        for weekdays.
        
        The following cron expression is triggered every day at noon from June
        through September:
        
        ::
        
            0 12 * 6-9 * * remind "Walk the ducks"
        
        If the day of the week field is a wild card, but the day of the month is
        an explicit range, the day of the week will be ignored and the trigger
        will only be activated on the specified days of the month. If the day of
        the month is a wild card, the same principal applies.
        
        This expression is triggered every week day at 4:00 PM: ``0 16 * * 1-5``
        
        This one is triggered the first nine days of the month: ``0 16 1-9 * *``
        
        This one is triggered every day for the first week, but only on
        Saturdays thereafter: ``0 16 1-7 * 6``
        
        Steps
        ~~~~~
        
        Steps are specified with a "/" and number following a range or
        wild-card. When iterating through a range with a step, the specified
        number of values will be skipped each time. ``1-10/2`` is the functional
        equivalent to ``1,3,5,7,9``.
        
        The following cron expression is triggered on the first day of every
        quarter (Jan., Apr., ... Oct.) at midnight:
        
        ::
        
            0 0 1 */2 * * delete log.txt
        
        Repeaters
        ~~~~~~~~~
        
        Repeaters cause an event to trigger after arbitrary periods of time from
        a given moment which will be hitherto referred to as the epoch. By
        default, the epoch is January 1st, 1970 at 0:00. Triggers in different
        fields operate independently of each other: ``%10 %10 * * *`` would
        trigger at 00:00, 00:10, ... 00:50, 10:00, 10:10, etc...
        
        The following cron expression is triggered at noon on the 10th every 5
        months:
        
        ::
        
            0 12 10 %5 * Something amazing happens at noon...
        
        Special Symbols
        ~~~~~~~~~~~~~~~
        
        There are three additional special symbols: "L", "W" and "#".
        
        When used in the day of the month field, a number followed by "L"
        represents the occurrence of a day of the week represented by the value
        preceding "L". In the day of the month field, "L" without a prefixed
        integer represents the last day of the month. ``0 0 * * 5L`` represent a
        midnight trigger for the last Friday of each month whereas ``0 0 L 2 *``
        represents a midnight trigger for the last day of every February.
        
        "W" is only valid for the field representing days of the month, and must
        be prefixed with an integer. It specifies the weekday (Monday-Friday)
        nearest the given day. In the construct ``0 0 7W * *``, when the 7th
        falls on a Saturday, the trigger will be active on the 6th. If the 7th
        falls on a Sunday, the trigger will be active on the 8th.
        
        "#" is only valid for the field representing days of the week. The "#"
        has a prefix and suffix that represent the day of the week and the Nth
        occurrence of that day of the week. ``0 0 * * 0#5`` would trigger every
        5th Sunday.
        
        Miscellaneous
        ~~~~~~~~~~~~~
        
        All of the constructs above can be combined in individual fields using
        commas: ``0,30 */7,5 1,%90,L 9-4/6,5-8 4#2`` is a completely valid,
        albeit it hideous, expression.
        
        In addition to the atoms above, there are several special strings that
        can substitute common cron expressions. These strings *replace*, not
        augment the cron fields.
        
        ::
        
            String      Equivalent
            ------      ----------
            @yearly     0 0 1 1 *
            @annually   0 0 1 1 *
            @monthly    0 0 1 * *
            @weekly     0 0 * * 0
            @daily      0 0 * * *
            @midnight   0 0 * * *
            @hourly     0 * * * *
        
Keywords: cron,scheduler,triggers,time,quartz
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.4
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
