Metadata-Version: 1.0
Name: timerange
Version: 1.07
Summary: Generates list of dates in various formats
Home-page: https://bitbucket.org/todor/timerange
Author: Todor Bukov
Author-email: Todor Bukov <dev.todor@gmail.com>
License: GNU General Public License (GPL)
Description: 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_).
        
        
        Installation instructions
        --------------------------
        
        Timerange is a single Python script with no external dependencies beyond
        standard Python library. Installing from source is the usual::
        
            python setup.py install
        
        
        Under Windows py2exe_ tool is used to generate singe exe binary::
        
            python setup.py py2exe
        
        
        The resulting timerange.exe is in the dist/ folder.
        
        
        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_).
        
        
        .. _py2exe: http://www.py2exe.org/
        
        .. _GPLv3: http://www.gnu.org/copyleft/gpl.html
        
        .. _`timerange website`: https://bitbucket.org/todor/timerange
        
        
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
