timerange 1.07

Installing and using Timerange

timerange is a command line script to generate a range of date/times in various formats. It is used to produce list of date/times that can then be passed to other programs or used in shell/batch scripts where operations with date and times are required.

It can also be compiled for Windows (with py2exe).

python setup.py install

python setup.py py2exe

Usage

Getting help on the command line options:

C:\> timerange --help
usage: timerange [-h] [-d DEBUG_LEVEL] [-s START] [-e END] [-p PERIOD]
                 [-o OUTPUT_FORMAT] [-i INPUT_FORMAT] [-fh] [-v]

timerange - generates a range of date/times in various formats

optional arguments:
  -h, --help            show this help message and exit
  -d DEBUG_LEVEL, --debug DEBUG_LEVEL
                        Sets the debug level and adds debug messages to the
                        output
  -s START, --start START
                        Date to start from (format "YYYY-MM-DD", "today",
                        "+7days" or "-2hours")
  -e END, --end END     End date (format "YYYY-MM-DD", "today", "+7days" or
                        "-2days")
  -p PERIOD, --period PERIOD
                        Period term - examples: "1 hour", "-2 days", "3
                        months, 5 days"
  -o OUTPUT_FORMAT, --output-format OUTPUT_FORMAT
                        Output format string. Use --format-help option for
                        more details
  -i INPUT_FORMAT, --input-format INPUT_FORMAT
                        Input format string. Use --format-help option for more
                        details
  -fh, --format_help    Show the format strings available for date/time input
                        and output
  -v, --version         Show the version

author: Todor Bukov <dev.todor@gmail.com> ver.1.06

Getting help on the input and output formats:

Available arguments for the date/time format options (-i/-o)

%a  Locale's abbreviated weekday name.
%A  Locale's full weekday name.
%b  Locale's abbreviated month name.
%B  Locale's full month name.
%c  Locale's appropriate date and time representation.
%d  Day of the month as a decimal number [01,31].
%H  Hour (24-hour clock) as a decimal number [00,23].
%I  Hour (12-hour clock) as a decimal number [01,12].
%j  Day of the year as a decimal number [001,366].
%m  Month as a decimal number [01,12].
%M  Minute as a decimal number [00,59].
%p  Locale's equivalent of either AM or PM.         (1)
%S  Second as a decimal number [00,61].     (2)
%U  Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.    (3)
%w  Weekday as a decimal number [0(Sunday),6].
%W  Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.    (3)
%x  Locale's appropriate date representation.
%X  Locale's appropriate time representation.
%y  Year without century as a decimal number [00,99].
%Y  Year with century as a decimal number.
%Z  Time zone name (no characters if no time zone exists).
%%  A literal '%' character.

Notes:

(1) When used with the strptime() function, the %p directive only affects the output hour field if the %I directive is used to parse the hour.
(2) The range really is 0 to 61; this accounts for leap seconds and the (very rare) double leap seconds.
(3) When used with the strptime() function, %U and %W are only used in calculations when the day of the week and the year are specified.

Examples:
"%Y%-m-%d" results in something like "2012-01-01" (the actual date depends on the other parameters).

Dates can also be defined as relative to the current date/time using sign i.e. "+" and "-" or by using the keywords "from now" and "ago".

List of relative keywords:
- "now" - refers to the current time on the system
- "today" - same as "now", but with the time part zeroed (i.e. 00:00:00)
- "yesterday" - same as "now, -1 day"
- "tomorrow" - same as "now, +1 day"
- "ago" - refers to the period in the past e.g. "1 day ago" is the same as "-1 day"
- "from now" - refers to the period in the future (this is the default) e.g. "1 day", "+1 day", "1 day from now" are all the same.

Examples:
"1 day ago", "2 weeks from now", "-1 hour", "+2 minutes", "today", "tomorrow"

When using relative dates more than one keyword can be provided, seprated by comma.
Examples:
"1 day, 2 hours, 3 minutes" or "-3 days, -2 seconds"

NOTE: Combinations of keywords can sometimes lead to confusing results i.e. "+3days, -1 hour, 2 minutes ago".
These combinations are additive and the final results is the sum of the results yelded by the individual keywords.

Showing today’s date:

C:\> timerange
2012-01-29 00:00:00

C:\> timerange.exe -s "now" -e "now, 1 sec"
2012-01-29 11:21:10

Generating list of (relative) dates with specified period between them with the command line option -p/–period:

C:\> timerange -s "now" -e "tomorrow" -p "6 hours"
2012-01-29 11:23:04
2012-01-29 17:23:04
2012-01-29 23:23:04
2012-01-30 05:23:04
2012-01-30 11:23:04

The relative dates can be combined with the tokens separated by comma:

C:\> timerange -s "-3 days, -2 hours" -e "tomorrow, +1 day" -p "22 hours"
2012-01-26 09:24:06
2012-01-27 07:24:06
2012-01-28 05:24:06
2012-01-29 03:24:06
2012-01-30 01:24:06
2012-01-30 23:24:06

Generating a date range between two (absolute) dates:

C:\> timerange -s  2012-01-01 -e 2013-01-01 -p "2 months, 2 days"
ERROR: Could not convert the argument: '2012-01-01' using the format '%Y-%m-%d %H:%M:%S (time data '2012-01-01' does not match format '%Y-%m-%d %H:%M:%S')

The error is due to the dates being in format that is not expected by the script. The input format may be changed using -i/–input-format option (check the output from the -fh command option for the meaning of the format letters):

C:\> timerange -s  2012-01-01 -i "%Y-%m-%d" -e 2013-01-01 -p "2 months, 2 days"
2012-01-01 00:00:00
2012-03-03 00:00:00
2012-05-04 00:00:00
2012-07-05 00:00:00
2012-09-05 00:00:00
2012-11-06 00:00:00

The output format can also be changed using the -o/–output-format option:

C:\> timerange -s  2012-01-01 -i "%Y-%m-%d" -e 2013-01-01 -p "2 months, 2 days" -o "%b %d, %Y"
Jan 01, 2012
Mar 03, 2012
May 04, 2012
Jul 05, 2012
Sep 05, 2012
Nov 06, 2012

The dates can also be in descending order providing the period is negative:

C:\> timerange.exe -s "tomorrow" -e "-3 days" -p "-12 hours, -5 minute, -30 secs"
2012-01-30 11:26:10
2012-01-29 23:20:40
2012-01-29 11:15:10
2012-01-28 23:09:40
2012-01-28 11:04:10
2012-01-27 22:58:40
2012-01-27 10:53:10
2012-01-26 22:47:40

If the start/end date and the period as such that it may cause infinite loop, then an error will be thrown:

C:\> timerange.exe -s "tomorrow" -e "yesterday" -p "12 hours"
ERROR: The expression will never reach the final date with the given period

Making the period a negative value will make the above expression work as expected:

C:\> timerange.exe -s "tomorrow" -e "yesterday" -p "-12 hours"
2012-01-30 11:29:04
2012-01-29 23:29:04
2012-01-29 11:29:04
2012-01-28 23:29:04
2012-01-28 11:29:04

Development and bug reports

The latest version of the script can be obtained from timerange website. Please report any bugs or recommendations for improvements to the author.

License

The script is licensed under GNU General Public License version 3 or later (GPLv3).