dateblock 1.0.3

Python Cron-like date mainpulation

[](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.

## Dateblock
Dateblock allows you to block (exactly how a Linux/Unix Cron might) _until_ a
specific 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) version
does not (refering to /etc/crontab style). Dateblock specifically offers the ability
to wake/unblock on a _specific second_ and/or _drift_ for certain period afterwards
your calculated time is met (kind of like combining _sleep_ and _ICS Cron_ into one).

Python bindings are additionally included supporting all of the standard datetime
formats 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 not
interested in. Asterisks are automatically placed in strings missing all 6
arguments (separated by white space).

The __--isc__ (__-i__) switch makes the cron interpretation equivalent to
what 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 build
and test your crons to find out when they __would have__ blocked until without
actually blocking. If you pair the the test with the __--ics__ (__-i__), then
you can use this tool to help construct regular crons for _/etc/crontab_ if
you'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 some
additional time. Lets say you wanted the application to wake up on the 1st
minute 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 at
every minute. You could however achieve the previous example using a drift
value of '60' (seconds) and a cron (minute) entry of '*/10'.

In a way, drifting is a little like executing a cron and then sleeping for
an additional period right afterwards. However this is a much more elegant
solution 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.

### Examples
The following would block until a minute divisible by 10 was reached. Minutes
divisible by 10 are: 0,10,20,30,40 and 50.
```bash
dateblock -n /10
```

The following would block until a second is divisible by 5 was reached and
only on hours 3 and 4. This can also be written as such:
```bash
dateblock -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:
```bash
dateblock -c "* 5"

# you can rewrite the above like this too:
dateblock -n 5
dateblock -c "* 5 * * * *"
```

The following would block until a hour divisible by 5 was reached on the first
half of the month as well as the 20th of the month) Hours divisible by 5 are:
0, 5,10,15 and 20.
```bash
dateblock -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 the
cron string is the ability to chain them with multiple drift times using
a 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 seconds
past)
```bash
dateblock -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 drift
period. However this is still valid:
```bash
dateblock -c "* 5 * * * * +20"
```

### DateBlock Python Bindings
The DateBlock python bindings are really easy to use too:
```python
from dateblock import dateblock
from datetime import datetime

# Returns the date object it will unblock at
result = 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 date
result = dateblock("/5", ref=date(2017, 4, 22))

# Time: (hh, mm, ss)
from dateblock import time
result = dateblock("/5", ref=time(10, 5, 0))

# Epoch: seconds
result = dateblock("/5", ref=13424236)

```

## Datemath
Datemath allows you to manipulate a date and or time by adding
and or subtracting to it. It can help with scripting and calculating
a 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
```

## Installation
Assuming you have GNU C++ compiler and the standard development tools that
usually go with it (make, autoconf, automake, etc) then the following will
install everything for you.

```bash
autogen.sh
./configure
make
sudo make install
```