#!/usr/bin/env python

"""

Date processing functions.

Copyright (C) 2014, 2015, 2016 Paul Boddie <paul@boddie.org.uk>

This program is free software; you can redistribute it and/or modify it under

the terms of the GNU General Public License as published by the Free Software

Foundation; either version 3 of the License, or (at your option) any later

version.

This program is distributed in the hope that it will be useful, but WITHOUT

ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more

details.

You should have received a copy of the GNU General Public License along with

this program.  If not, see <http://www.gnu.org/licenses/>.

"""

from bisect import bisect_left

from datetime import date, datetime, timedelta

from os.path import exists

from pytz import timezone, UnknownTimeZoneError

import re

# iCalendar date and datetime parsing (from DateSupport in MoinSupport).

_date_icalendar_regexp_str = ur'(?P<year>[0-9]{4})(?P<month>[0-9]{2})(?P<day>[0-9]{2})'

date_icalendar_regexp_str = _date_icalendar_regexp_str + '$'

datetime_icalendar_regexp_str = _date_icalendar_regexp_str + \

    ur'(?:' \

    ur'T(?P<hour>[0-2][0-9])(?P<minute>[0-5][0-9])(?P<second>[0-6][0-9])' \

    ur'(?P<utc>Z)?' \

    ur')?$'

_duration_time_icalendar_regexp_str = \

    ur'T' \

    ur'(?:' \

    ur'([0-9]+H)(?:([0-9]+M)([0-9]+S)?)?' \

    ur'|' \

    ur'([0-9]+M)([0-9]+S)?' \

    ur'|' \

    ur'([0-9]+S)' \

    ur')'

duration_icalendar_regexp_str = ur'P' \

    ur'(?:' \

    ur'([0-9]+W)' \

    ur'|' \

    ur'(?:%s)' \

    ur'|' \

    ur'([0-9]+D)(?:%s)?' \

    ur')$' % (_duration_time_icalendar_regexp_str, _duration_time_icalendar_regexp_str)

match_date_icalendar = re.compile(date_icalendar_regexp_str, re.UNICODE).match

match_datetime_icalendar = re.compile(datetime_icalendar_regexp_str, re.UNICODE).match

match_duration_icalendar = re.compile(duration_icalendar_regexp_str, re.UNICODE).match

# Datetime formatting.

def format_datetime(dt):

    "Format 'dt' as an iCalendar-compatible string."

    if not dt:

        return None

    elif isinstance(dt, datetime):

        if dt.tzname() == "UTC":

            return dt.strftime("%Y%m%dT%H%M%SZ")

        else:

            return dt.strftime("%Y%m%dT%H%M%S")

    else:

        return dt.strftime("%Y%m%d")

def format_time(dt):

    "Format the time portion of 'dt' as an iCalendar-compatible string."

    if not dt:

        return None

    elif isinstance(dt, datetime):

        if dt.tzname() == "UTC":

            return dt.strftime("%H%M%SZ")

        else:

            return dt.strftime("%H%M%S")

    else:

        return None

def format_duration(td):

    "Format the timedelta 'td' as an iCalendar-compatible string."

    if not td:

        return None

    else:

        day_portion = td.days and "%dD" % td.days or ""

        time_portion = td.seconds and "T%dS" % td.seconds or ""

        if not day_portion and not time_portion:

            time_portion = "T0S"

        return "P%s%s" % (day_portion, time_portion)

# Parsing of datetime and related information.

def get_datetime(value, attr=None):

    """

    Return a datetime object from the given 'value' in iCalendar format, using

    the 'attr' mapping (if specified) to control the conversion.

    """

    if not value:

        return None

    if len(value) > 9 and (not attr or attr.get("VALUE") in (None, "DATE-TIME")):

        m = match_datetime_icalendar(value)

        if m:

            year, month, day, hour, minute, second = map(m.group, [

                "year", "month", "day", "hour", "minute", "second"

                ])

            if hour and minute and second:

                dt = datetime(

                    int(year), int(month), int(day), int(hour), int(minute), int(second)

                    )

                # Impose the indicated timezone.

                # NOTE: This needs an ambiguity policy for DST changes.

                return to_timezone(dt, m.group("utc") and "UTC" or attr and attr.get("TZID") or None)

        return None

    # Permit dates even if the VALUE is not set to DATE.

    if not attr or attr.get("VALUE") in (None, "DATE"):

        m = match_date_icalendar(value)

        if m:

            year, month, day = map(m.group, ["year", "month", "day"])

            return date(int(year), int(month), int(day))

    return None

def get_duration(value):

    """

    Return a duration for the given 'value' as a timedelta object.

    Where no valid duration is specified, None is returned.

    """

    if not value:

        return None

    m = match_duration_icalendar(value)

    if m:

        weeks, days, hours, minutes, seconds = 0, 0, 0, 0, 0

        for s in m.groups():

            if not s: continue

            if s[-1] == "W": weeks += int(s[:-1])

            elif s[-1] == "D": days += int(s[:-1])

            elif s[-1] == "H": hours += int(s[:-1])

            elif s[-1] == "M": minutes += int(s[:-1])

            elif s[-1] == "S": seconds += int(s[:-1])

        return timedelta(

            int(weeks) * 7 + int(days),

            (int(hours) * 60 + int(minutes)) * 60 + int(seconds)

            )

    else:

        return None

def get_period(value, attr=None):

    """

    Return a tuple of the form (start, end) for the given 'value' in iCalendar

    format, using the 'attr' mapping (if specified) to control the conversion.

    """

    if not value or attr and attr.get("VALUE") and attr.get("VALUE") != "PERIOD":

        return None

    t = value.split("/")

    if len(t) != 2:

        return None

    dtattr = {}

    if attr:

        dtattr.update(attr)

        if dtattr.has_key("VALUE"):

            del dtattr["VALUE"]

    start = get_datetime(t[0], dtattr)

    if t[1].startswith("P"):

        end = start + get_duration(t[1])

    else:

        end = get_datetime(t[1], dtattr)

    return start, end

# Time zone conversions and retrieval.

def ends_on_same_day(dt, end, tzid):

    """

    Return whether 'dt' ends on the same day as 'end', testing the date

    components of 'dt' and 'end' against each other, but also testing whether

    'end' is the actual end of the day in which 'dt' is positioned.

    Since time zone transitions may occur within a day, 'tzid' is required to

    determine the end of the day in which 'dt' is positioned, using the zone

    appropriate at that point in time, not necessarily the zone applying to

    'dt'.

    """

    return (

        to_timezone(dt, tzid).date() == to_timezone(end, tzid).date() or

        end == get_end_of_day(dt, tzid)

        )

def get_default_timezone():

    "Return the system time regime."

    filename = "/etc/timezone"

    if exists(filename):

        f = open(filename)

        try:

            return f.read().strip()

        finally:

            f.close()

    else:

        return None

def get_end_of_day(dt, tzid):

    """

    Get the end of the day in which 'dt' is positioned, using the given 'tzid'

    to obtain a datetime in the appropriate time zone. Where time zone

    transitions occur within a day, the zone of 'dt' may not be the eventual

    zone of the returned object.

    """

    return get_start_of_day(dt + timedelta(1), tzid)

def get_start_of_day(dt, tzid):

    """

    Get the start of the day in which 'dt' is positioned, using the given 'tzid'

    to obtain a datetime in the appropriate time zone. Where time zone

    transitions occur within a day, the zone of 'dt' may not be the eventual

    zone of the returned object.

    """

    start = datetime(dt.year, dt.month, dt.day, 0, 0)

    return to_timezone(start, tzid)

def get_start_of_next_day(dt, tzid):

    """

    Get the start of the day after the day in which 'dt' is positioned. This

    function is intended to extend either dates or datetimes to the end of a

    day for the purpose of generating a missing end date or datetime for an

    event.

    If 'dt' is a date and not a datetime, a plain date object for the next day

    will be returned.

    If 'dt' is a datetime, the given 'tzid' is used to obtain a datetime in the

    appropriate time zone. Where time zone transitions occur within a day, the

    zone of 'dt' may not be the eventual zone of the returned object.

    """

    if isinstance(dt, datetime):

        return get_end_of_day(dt, tzid)

    else:

        return dt + timedelta(1)

def get_datetime_tzid(dt):

    "Return the time zone identifier from 'dt' or None if unknown."

    if not isinstance(dt, datetime):

        return None

    elif dt.tzname() == "UTC":

        return "UTC"

    elif dt.tzinfo and hasattr(dt.tzinfo, "zone"):

        return dt.tzinfo.zone

    else:

        return None

def get_period_tzid(start, end):

    "Return the time zone identifier for 'start' and 'end' or None if unknown."

    if isinstance(start, datetime) or isinstance(end, datetime):

        return get_datetime_tzid(start) or get_datetime_tzid(end)

    else:

        return None

def to_date(dt):

    "Return the date of 'dt'."

    return date(dt.year, dt.month, dt.day)

def to_datetime(dt, tzid):

    """

    Return a datetime for 'dt', using the start of day for dates, and using the

    'tzid' for the conversion.

    """

    if isinstance(dt, datetime):

        return to_timezone(dt, tzid)

    else:

        return get_start_of_day(dt, tzid)

def to_utc_datetime(dt, tzid=None):

    """

    Return a datetime corresponding to 'dt' in the UTC time zone. If 'tzid'

    is specified, dates and floating datetimes are converted to UTC datetimes

    using the time zone information; otherwise, such dates and datetimes remain

    unconverted.

    """

    if not dt:

        return None

    elif get_datetime_tzid(dt):

        return to_timezone(dt, "UTC")

    elif tzid:

        return to_timezone(to_datetime(dt, tzid), "UTC")

    else:

        return dt

def to_timezone(dt, tzid):

    """

    Return a datetime corresponding to 'dt' in the time regime having the given

    'tzid'.

    """

    try:

        tz = tzid and timezone(tzid) or None

    except UnknownTimeZoneError:

        tz = None

    return to_tz(dt, tz)

def to_tz(dt, tz):

    "Return a datetime corresponding to 'dt' employing the pytz.timezone 'tz'."

    if tz is not None and isinstance(dt, datetime):

        if not dt.tzinfo:

            return tz.localize(dt)

        else:

            return dt.astimezone(tz)

    else:

        return dt

# iCalendar-related conversions.

def end_date_from_calendar(dt):

    """

    Change end dates to refer to the actual dates, not the iCalendar "next day"

    dates.

    """

    if not isinstance(dt, datetime):

        return dt - timedelta(1)

    else:

        return dt

def end_date_to_calendar(dt):

    """

    Change end dates to refer to the iCalendar "next day" dates, not the actual

    dates.

    """

    if not isinstance(dt, datetime):

        return dt + timedelta(1)

    else:

        return dt

def get_datetime_attributes(dt, tzid=None):

    """

    Return attributes for the 'dt' date or datetime object with 'tzid'

    indicating the time zone if not otherwise defined.

    """

    if isinstance(dt, datetime):

        attr = {"VALUE" : "DATE-TIME"}

        tzid = get_datetime_tzid(dt) or tzid

        if tzid:

            attr["TZID"] = tzid

        return attr

    else:

        return {"VALUE" : "DATE"}

def get_datetime_item(dt, tzid=None):

    """

    Return an iCalendar-compatible string and attributes for 'dt' using any

    specified 'tzid' to assert a particular time zone if not otherwise defined.

    """

    if not dt:

        return None, None

    if not get_datetime_tzid(dt):

        dt = to_timezone(dt, tzid)

    value = format_datetime(dt)

    attr = get_datetime_attributes(dt, tzid)

    return value, attr

def get_period_attributes(start, end, tzid=None):

    """

    Return attributes for the 'start' and 'end' datetime objects with 'tzid'

    indicating the time zone if not otherwise defined.

    """

    attr = {"VALUE" : "PERIOD"}

    tzid = get_period_tzid(start, end) or tzid

    if tzid:

        attr["TZID"] = tzid

    return attr

def get_period_item(start, end, tzid=None):

    """

    Return an iCalendar-compatible string and attributes for 'start', 'end' and

    'tzid'.

    """

    if start and end:

        attr = get_period_attributes(start, end, tzid)

        start_value = format_datetime(to_timezone(start, attr.get("TZID")))

        end_value = format_datetime(to_timezone(end, attr.get("TZID")))

        return "%s/%s" % (start_value, end_value), attr

    elif start:

        attr = get_datetime_attributes(start, tzid)

        start_value = format_datetime(to_timezone(start, attr.get("TZID")))

        return start_value, attr

    else:

        return None, None

def get_timestamp(offset=None):

    "Return the current time as an iCalendar-compatible string."

    offset = offset or timedelta(0)

    return format_datetime(to_timezone(datetime.utcnow(), "UTC") + offset)

def get_date(offset=None):

    """

    Return the current date, offset by the given timedelta 'offset' if

    specified. The returned date will not be positioned in any time zone.

    """

    offset = offset or timedelta(0)

    return date.today() + offset

def get_time(offset=None):

    """

    Return the current time, offset by the given timedelta 'offset' if

    specified. The returned time will be in the UTC time zone.

    """

    offset = offset or timedelta(0)

    return to_timezone(datetime.utcnow(), "UTC") + offset

def get_tzid(dtstart_attr, dtend_attr):

    """

    Return any time regime details from the given 'dtstart_attr' and

    'dtend_attr' attribute collections.

    """

    return dtstart_attr and dtstart_attr.get("TZID") or dtend_attr and dtend_attr.get("TZID") or None

def get_recurrence_start(recurrenceid):

    """

    Return 'recurrenceid' in a form suitable for comparison with period start

    dates or datetimes. The 'recurrenceid' should be an identifier normalised to

    a UTC datetime or employing a date or floating datetime representation where

    no time zone information was originally provided.

    """

    return get_datetime(recurrenceid)

def get_recurrence_start_point(recurrenceid, tzid):

    """

    Return 'recurrenceid' in a form suitable for comparison with free/busy start

    datetimes, using 'tzid' to convert recurrence identifiers that are dates.

    The 'recurrenceid' should be an identifier normalised to a UTC datetime or

    employing a date or floating datetime representation where no time zone

    information was originally provided.

    """

    return to_utc_datetime(get_datetime(recurrenceid), tzid)

# Time corrections.

class ValidityError(Exception):

    pass

def check_permitted_values(dt, permitted_values):

    "Check the datetime 'dt' against the 'permitted_values' list."

    if not isinstance(dt, datetime):

        raise ValidityError

    hours, minutes, seconds = permitted_values

    errors = []

    if hours and dt.hour not in hours:

        errors.append("hour")

    if minutes and dt.minute not in minutes:

        errors.append("minute")

    if seconds and dt.second not in seconds:

        errors.append("second")

    return errors

def correct_datetime(dt, permitted_values):

    "Correct 'dt' using the given 'permitted_values' details."

    carry, hour, minute, second = correct_value((dt.hour, dt.minute, dt.second), permitted_values)

    return datetime(dt.year, dt.month, dt.day, hour, minute, second, dt.microsecond, dt.tzinfo) + \

           (carry and timedelta(1) or timedelta(0))

def correct_value(value, permitted_values):

    """

    Correct the given (hour, minute, second) tuple 'value' according to the

    'permitted_values' details.

    """

    limits = 23, 59, 59

    corrected = []

    reset = False

    # Find invalid values and reset all following values.

    for v, values, limit in zip(value, permitted_values, limits):

        if reset:

            if values:

                v = values[0]

            else:

                v = 0

        elif values and v not in values:

            reset = True

        corrected.append(v)

    value = corrected

    corrected = []

    carry = 0

    # Find invalid values and update them to the next valid value, updating more

    # significant values if the next valid value is the first in the appropriate

    # series.

    for v, values, limit in zip(value, permitted_values, limits)[::-1]:

        if carry:

            v += 1

            if v > limit:

                if values:

                    v = values[0]

                else:

                    v = 0

                corrected.append(v)

                continue

            else:

                carry = 0

        if values:

            i = bisect_left(values, v)

            if i < len(values):

                v = values[i]

            else:

                v = values[0]

                carry = 1

        corrected.append(v)

    return [carry] + corrected[::-1]

# vim: tabstop=4 expandtab shiftwidth=4