#!/usr/bin/env python
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
# 
#   http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
# $Id: $
# $Change: $
# $DateTime: $
# $Author: $
"""
Date and time input conversion

Module contents:

    ---- common
    class DatetimeValueError - subclass of ValueError

    ---- datetime or date
    datetime_syntax_msg - a string briefly describing the input format
    str_to_datetime() - Interprets a string as a date and (optional) time.
    scan_datetime() - Consumes a date and time from a string.

    ---- timedelta
    signed_duration_syntax_msg - a string briefly describing the input format
    unsigned_duration_syntax_msg - a string briefly describing the input format
    str_to_duration() - Interprets a string as a duration or length of time.
    scan_duration() - Consumes a duration from a string.

Examples:
    from lib.datetimeutils import str_to_datetime
    import datetime
    dt = str_to_datetime('2008-07-13 14:15:16.1')
    dt = str_to_datetime('20080713 141516.123456')
    dt = str_to_datetime('  20080713T1415  ')
    d = str_to_datetime('2008-7-4')

    from lib.datetimeutils import str_to_duration
    import timedelta
    td = str_to_duration('1')            # one hour
    td = str_to_duration('  1:2:3  ')    # one hour, two minutes and three seconds
    td = str_to_duration(':2:3.4')       # two minutes and 3.4 seconds
    td = str_to_duration('-72')          # negative 72 hours (normalized to -3 days)

The datetime syntax is based on ISO 8601 and RFC 3339.  See...
    http://www.rfc.net/rfc3339.html
    http://hydracen.com/dx/iso8601.htm
    http://www.cl.cam.ac.uk/~mgk25/iso-time.html

In the docstrings, the examples preceded by '>>>' can be executed and verified
automatically by the 'doctest' package of the Python standard library.
"""

from datetime import date, datetime, timedelta
import re


#--------------------------------- common ---------------------------------

class DatetimeValueError (ValueError):
    """
    Error on conversion from string to date, datetime, or timedelta.

    DatetimeValueError fields:
        description
        pos
        endpos
        badness
    """
    def __init__(self, description, string, pos=None, endpos=None):
        # Save enough info in the exception object so that a caller's
        # exception handler can create a differently formatted message
        # in case they don't like the format we provide.
        global _spacepat
        if endpos is None:
            endpos = len(string or '')
        if pos and string:
            # avoid copying all of string[pos:endpos], in case it is big
            p = _spacepat.match(string, pos, endpos).end()
            if endpos > p+30:
                badness = string[p:p+27].rstrip(' \t') + '...'
            else:
                badness = string[p:endpos].rstrip(' \t')
        else:
            badness = string
        self.description, self.pos, self.endpos, self.badness = description, pos, endpos, badness
        if badness:
            description = '"%s" ... %s' % (badness, description)
        ValueError.__init__(self, description)


#-------------------------------- datetime --------------------------------

datetime_syntax_msg = ('Specify date and time as "YYYY-MM-DD[ HH:MM[:SS[.S]]" '
                       'or "YYYYMMDD[ HHMM[SS[.S]]]".  If both date and time '
                       'are given, a space or letter "T" must separate them.')

def str_to_datetime(string, pos=0, endpos=None):
    """
    Interprets string[pos:endpos] as a date and (optional) time.

    Returns a datetime.datetime object if string[pos:endpos] contains a valid
    date and time.  Returns a datetime.date object for a date with no time.

    Raises DatetimeValueError if string does not contain a valid date, or
    contains an invalid time or anything else other than whitespace.

    Examples...

    # delimited format
    >>> str_to_datetime('2008-7-13')
    datetime.date(2008, 7, 13)
    >>> str_to_datetime('2008-7-13 2:15')
    datetime.datetime(2008, 7, 13, 2, 15)
    >>> str_to_datetime(' 2008-07-13  14:15:16.123456789 ')
    datetime.datetime(2008, 7, 13, 14, 15, 16, 123456)

    # numeric format
    >>> str_to_datetime('  20080713  ')
    datetime.date(2008, 7, 13)
    >>> str_to_datetime('20080713 141516.123')
    datetime.datetime(2008, 7, 13, 14, 15, 16, 123000)

    # slicing
    >>> str_to_datetime('9200807139', 1, 9)
    datetime.date(2008, 7, 13)

    # 'T' can separate date and time
    >>> str_to_datetime('2008-7-3t2:15')
    datetime.datetime(2008, 7, 3, 2, 15)
    >>> str_to_datetime('  20080713T1415 ')
    datetime.datetime(2008, 7, 13, 14, 15)

    Errors...  (for more, see scan_datetime() below)

    >>> str_to_datetime('')
    Traceback (most recent call last):
    DatetimeValueError: Specify date and time as "YYYY-MM-DD[ HH:MM[:SS[.S]]" or "YYYYMMDD[ HHMM[SS[.S]]]".  If both date and time are given, a space or letter "T" must separate them.
    >>> str_to_datetime('nogood')
    Traceback (most recent call last):
    DatetimeValueError: "nogood" ... Specify date and time as "YYYY-MM-DD[ HH:MM[:SS[.S]]" or "YYYYMMDD[ HHMM[SS[.S]]]".  If both date and time are given, a space or letter "T" must separate them.
    >>> str_to_datetime(' 20080713 T1415 ')      # can't have spaces around 'T'
    Traceback (most recent call last):
    DatetimeValueError: " 20080713 T1415 " ... date is followed by unrecognized "T1415"
    >>> str_to_datetime('2008-7-13 2:15 &')
    Traceback (most recent call last):
    DatetimeValueError: "2008-7-13 2:15 &" ... date and time are followed by unrecognized "&"
    >>> str_to_datetime('2008-7-13 abcdefghijklmnop')
    Traceback (most recent call last):
    DatetimeValueError: "2008-7-13 abcdefghijklmnop" ... date is followed by unrecognized "abcdefghi"
    """
    global datetime_syntax_msg
    if endpos is None:
        endpos = len(string)
    value, nextpos = scan_datetime(string, pos, endpos)
    if value is None:
        # string is empty or doesn't conform to the date syntax we require
        raise DatetimeValueError(datetime_syntax_msg, string, pos, endpos)
    elif nextpos < endpos and not string[nextpos:endpos].isspace():
        # got valid date or datetime, but there is something more after it
        if hasattr(value, 'hour'):
            msg = 'date and time are followed by unrecognized "%s"'
        else:
            msg = 'date is followed by unrecognized "%s"'
        msg %= string[nextpos:min(nextpos+10,endpos)].strip()
        raise DatetimeValueError(msg, string, pos, endpos)
    return value


def scan_datetime(string, pos=0, endpos=None):
    """
    Consumes an initial substring of the slice string[pos:endpos] which
    represents a date and (optional) time.  Leading whitespace is ignored.

    Raises DatetimeValueError if the text syntactically resembles a date or
    datetime but fails semantic checks (e.g. field out of range, such as the
    day in '2008-02-30').

    Otherwise returns a tuple (value, nextpos) in which 'value' is either a
    datetime.datetime object, a datetime.date object, or None; and 'nextpos'
    is the index of the next character of string (pos <= nextpos <= endpos).

    (None, pos) is returned if the beginning of the string (or slice) does
    not conform to either the delimited date format YYYY-[M]M-[D]D or the
    numeric date format YYYYMMDD.

    (dt, nextpos) in which dt is a datetime.datetime object, is returned if
    a valid date and time are found.  At least one space or tab, or else the
    single letter 'T' or 't' with no whitespace, must separate date and time.
    Time must be delimited using colons [H]H:MM:[SS[.fraction]] if the
    date is delimited, or must be numeric HHMM[SS[.fraction]] if the date is
    numeric.  The fraction may be any number of digits (at most 6 are kept).

    (d, nextpos) in which d is a datetime.date object, is returned if a
    valid date is found but the subsequent characters do not syntactically
    resemble a time in the required format.

    Examples...  (for other syntax examples, see str_to_datetime() above)

    >>> scan_datetime('2008-6-30')
    (datetime.date(2008, 6, 30), 9)
    >>> scan_datetime(' 2008-07-13 14:15:16  ')
    (datetime.datetime(2008, 7, 13, 14, 15, 16), 20)
    >>> scan_datetime(' nogood ')
    (None, 0)

    Errors...

    >>> scan_datetime('2008-06-31')
    Traceback (most recent call last):
    DatetimeValueError: "2008-06-31" ... day is out of range for month
    >>> scan_datetime('2008-07-13 24:00')
    Traceback (most recent call last):
    DatetimeValueError: "2008-07-13 24:00" ... hour must be in 0..23
    >>> scan_datetime('2008-07-13 14:15:1  ')
    Traceback (most recent call last):
    DatetimeValueError: "2008-07-13 14:15:1  " ... second should have 2 digits
    >>> scan_datetime('2008-07-13 14:5:16  ')
    Traceback (most recent call last):
    DatetimeValueError: "2008-07-13 14:5:16  " ... minute should have 2 digits
    >>> scan_datetime('20080713 14151  ')
    Traceback (most recent call last):
    DatetimeValueError: "20080713 14151  " ... time should have 4 or 6 digits (HHMM or HHMMSS)
    >>> scan_datetime('20080713 1.234')
    Traceback (most recent call last):
    DatetimeValueError: "20080713 1.234" ... time should have 6 digits before decimal point (HHMMSS.sss)
    """
    global _datepat, _colontimepat, _numerictimepat
    if endpos is None:
        endpos = len(string)
    datematch = _datepat.match(string, pos, endpos)
    if datematch is None:
        return None, pos
    try:
        nextpos = datematch.end()
        yyyy, m, d, mm, dd = datematch.groups()
        if m:
            # delimited format
            if len(d) <> 2 and len(d) <> 1:
                raise ValueError, 'day should have 1 or 2 digits'
            year, month, day = int(yyyy), int(m), int(d)
            timepat = _colontimepat
        else:
            # numeric format
            if len(dd) > 2:
                raise ValueError, 'date should have 8 digits (YYYYMMDD)'
            year, month, day = int(yyyy), int(mm), int(dd)
            timepat = _numerictimepat

        timematch = timepat.match(string, nextpos, endpos)
        if timematch is None:
            return date(year, month, day), nextpos
        nextpos = timematch.end()

        if m:
            # delimited format
            hh, mm, ss, frac = timematch.groups()
            if len(hh) > 2:
                raise ValueError, 'hour should have 1 or 2 digits'
            if len(mm) <> 2:
                raise ValueError, 'minute should have 2 digits'
            if ss is not None and len(ss) <> 2:
                raise ValueError, 'second should have 2 digits'
        else:
            # numeric format
            hhmmss, frac = timematch.groups()
            if len(hhmmss) == 6:
                hh, mm, ss = hhmmss[:2], hhmmss[2:4], hhmmss[4:]
            elif frac:
                raise ValueError, 'time should have 6 digits before decimal point (HHMMSS.sss)'
            elif len(hhmmss) == 4:
                hh, mm, ss = hhmmss[:2], hhmmss[2:], None
            else:
                raise ValueError, 'time should have 4 or 6 digits (HHMM or HHMMSS)'

        if frac:
            microsecond = int((frac + '000000')[1:7])
            dt = datetime(year, month, day, int(hh), int(mm), int(ss), microsecond)
        elif ss:
            dt = datetime(year, month, day, int(hh), int(mm), int(ss))
        else:
            dt = datetime(year, month, day, int(hh), int(mm))
        return dt, nextpos
    except ValueError, e:
        # Nonsensical date or time (e.g. field out of range, such as month > 12)
        raise DatetimeValueError(str(e), string, pos, nextpos)


#------------------------------- timedelta -------------------------------

signed_duration_syntax_msg = 'Specify duration as [hours][:minutes[:seconds[.fraction]]]'
unsigned_duration_syntax_msg = 'Specify duration as [+|-][hours][:minutes[:seconds[.fraction]]]'

def str_to_duration(string, pos=0, endpos=None, signed=True):
    """
    Interprets string[pos:endpos] as a duration or length of time in the form:
        [+|-][hours][:minutes[:seconds[.fraction]]]

    If string[pos:endpos] contains a valid duration, it is converted to a
    datetime.timedelta object, which is returned.

    Raises DatetimeValueError if string[pos:endpos] does not contain a
    valid duration; or if the duration includes a '+' or '-' sign and the
    caller specifies signed=False; or if the duration is preceded or
    followed by anything but whitespace.

    Examples...

    >>> str_to_duration('48')
    datetime.timedelta(2)
    >>> str_to_duration(' :120 ')
    datetime.timedelta(0, 7200)
    >>> str_to_duration(':0:72')
    datetime.timedelta(0, 72)
    >>> str_to_duration(':1:30')
    datetime.timedelta(0, 90)
    >>> str_to_duration('1:2:3.123456789')
    datetime.timedelta(0, 3723, 123456)

    # slicing
    >>> str_to_duration('9249', 1, 3)
    datetime.timedelta(1)

    # duration can be negative if signed=True
    >>> str_to_duration('-1')
    datetime.timedelta(-1, 82800)
    >>> str_to_duration('-:1')
    datetime.timedelta(-1, 86340)

    Errors...  (for more, see scan_duration() below)

    >>> str_to_duration('')
    Traceback (most recent call last):
    DatetimeValueError: Specify duration as [hours][:minutes[:seconds[.fraction]]]
    >>> str_to_duration(':')
    Traceback (most recent call last):
    DatetimeValueError: ":" ... Specify duration as [hours][:minutes[:seconds[.fraction]]]
    >>> str_to_duration('1:2: 3')
    Traceback (most recent call last):
    DatetimeValueError: "1:2: 3" ... duration is followed by unrecognized ": 3"
    """
    global duration_syntax_msg
    if endpos is None:
        endpos = len(string)
    value, nextpos = scan_duration(string, pos, endpos, signed)
    if value is None:
        # string is empty or doesn't conform to the syntax we require
        if signed:
            raise DatetimeValueError(signed_duration_syntax_msg, string, pos, endpos)
        else:
            raise DatetimeValueError(unsigned_duration_syntax_msg, string, pos, endpos)
    elif nextpos < endpos and not string[nextpos:endpos].isspace():
        # got valid duration, but there is something more after it
        msg = ('duration is followed by unrecognized "%s"'
               % string[nextpos:min(nextpos+10,endpos)].strip())
        raise DatetimeValueError(msg, string, pos, endpos)
    return value


def scan_duration(string, pos=0, endpos=None, signed=True):
    """
    Consumes an initial substring of the slice string[pos:endpos]
    representing a duration of time.  Leading whitespace is ignored.

    If 'signed' is True, a '+' or '-' sign may precede the duration.
    Note that a negative duration stored in a datetime.timedelta object
    is normalized so that only the 'days' field is negative; for example,
    '-:0:0.000001' is represented as datetime.timedelta(days=-1,
    seconds=86399, microseconds=999999).

    (None, pos) is returned if the input does not conform to the
    [+|-][hours][:minutes[:seconds[.fraction]]] format.

    If a valid duration is found, a tuple (td, nextpos) is returned,
    where 'td' is a datetime.timedelta object, and 'nextpos' is the
    index of the next character of the string (pos <= nextpos <= endpos).

    Raises DatetimeValueError if the text syntactically resembles a
    duration but fails semantic checks (e.g. field out of range, such
    as minutes > 59 in '100:60:00'); or if 'signed' is False and a
    '+' or '-' sign is found.

    Examples...  (for other syntax examples, see str_to_duration() above)

    >>> scan_duration('1:2:3.4')
    (datetime.timedelta(0, 3723, 400000), 7)
    >>> scan_duration('')
    (None, 0)
    >>> scan_duration('bad')
    (None, 0)

    Errors...

    >>> scan_duration('100:200:300')
    Traceback (most recent call last):
    DatetimeValueError: "100:200:300" ... minutes should be in 0..59
    >>> scan_duration('-:1', signed=False)
    Traceback (most recent call last):
    DatetimeValueError: "-:1" ... duration should be unsigned
    """
    global _durationpat
    if endpos is None:
        endpos = len(string)
    match = _durationpat.match(string, pos, endpos)
    sign, h, m, s, f = match.groups()
    if not h and not m:
        return None, pos
    try:
        hours = minutes = seconds = microseconds = 0
        if h:
            hours = int(h)
        if m:
            minutes = int(m)
            if s:
                seconds = int(s)
                if f and len(f) > 1:
                    microseconds = int((f + '000000')[1:7])
        if hours > 0 and minutes > 59:
            raise ValueError('minutes should be in 0..59')
        minutes += hours * 60
        if minutes > 0 and seconds > 59:
            raise ValueError('seconds should be in 0..59')
        seconds += minutes * 60
        td = timedelta(seconds=seconds, microseconds=microseconds)
        if sign:
            if not signed:
                raise ValueError('duration should be unsigned')
            if sign == '-':
                td = -td
        return td, match.end()
    except OverflowError, e:
        # Nonsensical duration (e.g. field out of range)
        raise DatetimeValueError(str(e), string, pos, match.end())
    except ValueError, e:
        # Nonsensical duration (e.g. field out of range)
        raise DatetimeValueError(str(e), string, pos, match.end())


#-------------------------------- private --------------------------------

_datepat = (r'\s*'                           # skip any leading whitespace
            r'(\d\d\d\d)'                    # yyyy                     \1
            r'(?:'                           # followed by either
            r'(?:-(\d\d?)-(\d*))|'           # -m[m]-d[d] or            \2 \3
            r'(?:(\d\d)(\d\d+))'             # mmdd                     \4 \5
            r')')                            # note dd absorbs excess digits
_colontimepat = (r'(?:\s+|[Tt])'             # whitespace or 'T'
                 r'(\d+)'                    # [h]h                     \1
                 r':(\d+)'                   # :mm                      \2
                 r'(?::(\d*)(\.\d*)?)?')     # [:ss[.frac]]             \3 \4
                                             # hh, mm, ss absorb excess digits
_numerictimepat = (r'(?:\s+|[Tt])'           # whitespace or 'T'
                   r'(\d+)'                  # hhmmss                   \1
                   r'(\.\d*)?')              # [.frac]                  \2
                                             # hhmmss absorbs excess digits
_durationpat = (r'\s*'                       # skip any leading whitespace
                r'([+-])?'                   # [+|-]                    \1
                r'(\d*)'                     # [hours]                  \2
                r'(?:'                       # [
                r':(\d+)'                    # :minutes                 \3
                r'(?::(\d+)(\.\d*)?)?'       # [:seconds[.frac]]        \4 \5
                r')?')                       # ]
_spacepat = r'\s*'                           # whitespace

_datepat = re.compile(_datepat)
_colontimepat = re.compile(_colontimepat)
_numerictimepat = re.compile(_numerictimepat)
_durationpat = re.compile(_durationpat)
_spacepat = re.compile(_spacepat)

# If invoked as a script, execute the examples in each function's docstring
# and verify the expected output.  Produces no output if verification is
# successful, unless -v is specified.  Use -v option for verbose test output.
def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()