Description:

dateblock 1.0.3

[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=MHANV39UZNQ5E)[](https://www.patreon.com/lead2gold)Date/Time Manipulation======================Datetools packages itself with 2 tools, dateblock and datemath.## DateblockDateblock allows you to block (exactly how a Linux/Unix Cron might) _until_ aspecific point of time unlike 'sleep' which blocks _for_ a set period of time.The difference is very subtle but can prove to be very useful.It offers a few new features that the Internet Systems Consortium (ICS) versiondoes not (refering to /etc/crontab style). Dateblock specifically offers the abilityto wake/unblock on a _specific second_ and/or _drift_ for certain period afterwardsyour calculated time is met (kind of like combining _sleep_ and _ICS Cron_ into one).Python bindings are additionally included supporting all of the standard datetimeformats and objects!__Syntax__:dateblock [options]__Allowed options__:``` -h [ --help ] Show this help screen. -t [ --test ] Test (Do not block for the specified period) -v [ --verbose ] Verbose mode -i [ --isc ] ISC Mode -s [ --second ] arg Second (0-59) -n [ --minute ] arg Minute (0-59) -o [ --hour ] arg Hour (0-23) -d [ --dom ] arg Day of Month (1-31) -m [ --month ] arg Month (1-12) {Jan=1,...,Dec=12} -w [ --dow ] arg Day of Week (0-6) {Sun=0,...,Sat=6} -c [ --cron ] arg Cron string formatting -x [ --drift ] arg Additional drift time (in seconds).```A variety of syntax is accepted by this tool such as:``` x (Value) where 'x' is represented numerically. */x (or /x) (Modulus) where 'x' is represented numerically. x-y (or y-x) (Range) where 'x' and 'y' are are represented numerically. x,y (Separator) where 'x' and 'y' are are represented numerically.```__Note__: With the exception of the drift option (+), all variations of the syntax mentioned above can be mixed if separated using the 'comma' (Separator) operator. ie: */a,b,c-d,/e is valid. However: x-y-z is not valid, nor is /x/y or /x-y. All values must be within the range of it's time type. Thus 400-4000 would never work since no time constraint even resides within that range.The __--cron__(__-c__) switch allows one to specify the standard cron formatting:``` drift time ----------------------------------------------+ day of week (0 - 6) (Sunday=0) -----------------------+ | month (1 - 12) ------------------------------------+ | | day of month (1 - 31) --------------------------+ | | | hour (0 - 23) -------------------------------+ | | | | min (0 - 59) -----------------------------+ | | | | | sec (0 - 59) --------------------------- | | | | | | | | | | | | | - - - - - - - * * * * * * *```Substitute an asterisk (*) as a placeholder for arguments you are notinterested in. Asterisks are automatically placed in strings missing all 6arguments (separated by white space).The __--isc__ (__-i__) switch makes the cron interpretation equivalent towhat it is today (ISC stands for Internet Systems Consortium). Hence:``` ISC Format (no second or drift) +----------------------------- min (0 - 59) | +----------------------- hour (0 - 23) | | +----------------- day of month (1 - 31) | | | +----------- month (1 - 12) | | | | +----- day of week (0 - 6) (Sunday=0) | | | | | - - - - - * * * * *```The __--test__(__-t__) switch is your greatest ally. Use this to simply buildand test your crons to find out when they __would have__ blocked until withoutactually blocking. If you pair the the test with the __--ics__ (__-i__), thenyou can use this tool to help construct regular crons for _/etc/crontab_ ifyou're new to the idea and still learning how the crontabs work.### Drifting:Drifting is an option that allows you to adjust the calculated results by someadditional time. Lets say you wanted the application to wake up on the 1stminute of each 10 min interval (1, 11, 21, 31, 41, 51). Specifying the cron(minute) '*/1' would not work. In fact the cron of '*/1' would unblock atevery minute. You could however achieve the previous example using a driftvalue of '60' (seconds) and a cron (minute) entry of '*/10'.In a way, drifting is a little like executing a cron and then sleeping foran additional period right afterwards. However this is a much more elegantsolution with a more precise blocking period.Some things to consider about drifting:- Drifting is always calculated 'after' a specified cron.- You can not specify a drifting value on it's own without a cron entry to go with it.- A drift value is always specified in seconds.- You can not drift longer then the interval calculated by the cron itself. In the event this occurs, only the remainder (modulus) is kept; the rest is is considered overflow and will simply be ignored. Drifting behaves this way to prevent missing a segment of time that would have otherwise been calculated. For example... lets say you wanted to unblock every hour, your cron might look like this: ```dateblock --hour=/1```. With this cron in mind, you could never add a drift of a value larger then 1 hour minus 1 second (3659 seconds)... Why? Because the _--hour_ entry has already pre-defined the time (slice) bounds of 1, therefore a drift value of the same (or more) would cause the calculation to spill into _the next_ hour. An hour it was pre-calculated to wake on anyway. Let's say you wanted to wake ever 2 hours. Well your cron would look like this ```dateblock --hour=/2```. If you wanted to add a drift into this picture, you'd have up to 2 hours minus 1 second (7319) to work with. However... if you specify a a cron of '*/10' (which would equate to unblocking every 10 seconds), your drift window is only a maximum of 9. So if you specified a drift of of 11 (seconds), the overflow would leave you with an actual drift of '1' (not 11). If you specified 10, then you would not drift at all (would be the same as not setting anything at all). This is how the modulus works when you overflow the drift value.- You can use the shortcut character of a _plus_ (_+_) inline on a cron to immediately invoke the drift and spare you from writing the extra entries. Hence: ```dateblock -c '* */5 +60'``` is the same as writing ```dateblock -c '* */5 * * * * 60'``` Once you invoke the __+__ character however, any entries found afterwards will be treated as an error.### ExamplesThe following would block until a minute divisible by 10 was reached. Minutesdivisible by 10 are: 0,10,20,30,40 and 50.```bashdateblock -n /10```The following would block until a second is divisible by 5 was reached andonly on hours 3 and 4. This can also be written as such:```bashdateblock -s /5 -o 3,4# you can rewrite the above like this too:dateblock -c "/5 * 3,4 * * *"```The following would block until the 5 minute of every hour:```bashdateblock -c "* 5"# you can rewrite the above like this too:dateblock -n 5dateblock -c "* 5 * * * *"```The following would block until a hour divisible by 5 was reached on the firsthalf of the month as well as the 20th of the month) Hours divisible by 5 are:0, 5,10,15 and 20.```bashdateblock -o /5 -d 1-14,20```Drifting using the cron was added in v1.0.0 (but was always available using__-x__ or __--drift__). The advantage you get from using it inline with thecron string is the ability to chain them with multiple drift times usinga comma and or range operator. The modulus one will not work here.The following will block until the 5:20 minute mark of each hour (20 secondspast)```bashdateblock -c "* 5 * * * * 20"# you can rewrite the above like this too:dateblock -n 5# You can skip to the drift portion by just denoting a plus (+) as the last# entry specified. This is interpreted as a drift time.dateblock -c "* 5 +20"```The expression is considered invalid if more entries are found after the driftperiod. However this is still valid:```bashdateblock -c "* 5 * * * * +20"```### DateBlock Python BindingsThe DateBlock python bindings are really easy to use too:```pythonfrom dateblock import dateblockfrom datetime import datetime# Returns the date object it will unblock atresult = dateblock("* /20", block=False)print("Blocking until %s" % result.strftime("%Y-%m-%d %H:%M:%S"))dateblock("* /20")print("Unblocked at %s" % datetime.now().strftime("%Y-%m-%d %H:%M:%S"))# Perhaps you want to calculate a time relative to somewhere in the past?# No problem; lets get a relative time 4 days ago (from now)relative = datetime.now() - timedelta(days=4)result = dateblock("* /20", ref=relative, block=False)# To use the isc switch with the bindings, just set isc=True (by default# it is off). Below would block for the start of each minute (not second# had you not set the isc flag)result = dateblock("/1", isc=True)# Dateblock supports date, time and epoch time too!## Date: (yyyy, mm, dd)from dateblock import dateresult = dateblock("/5", ref=date(2017, 4, 22))# Time: (hh, mm, ss)from dateblock import timeresult = dateblock("/5", ref=time(10, 5, 0))# Epoch: secondsresult = dateblock("/5", ref=13424236)```## DatemathDatemath allows you to manipulate a date and or time by addingand or subtracting to it. It can help with scripting and calculatinga specific date.__Syntax__:datemath [options] [-f DateTimeFormat]__Options__:``` -h [ --help ] Show this help screen. -s [ --seconds ] arg Specify the offset (+/-) in seconds. -n [ --minutes ] arg Specify the offset (+/-) in minutes. -o [ --hours ] arg Specify the offset (+/-) in hours. -d [ --days ] arg Specify the offset (+/-) in days. -m [ --months ] arg Specify the offset (+/-) in months. -y [ --years ] arg Specify the offset (+/-) in years. -f [ --format ] arg Specify the desired output format (see $>man date). The default is: %Y-%m-%d %H:%M:%S```## InstallationAssuming you have GNU C++ compiler and the standard development tools thatusually go with it (make, autoconf, automake, etc) then the following willinstall everything for you.```bashautogen.sh./configuremakesudo make install```

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter