Dates
==================

.. py:data:: model.DateTime

    :return: The current day and time
    :rtype: datetime (readonly)

.. py:data:: model.DayOfWeek

    :return: the day of the week represented by a number (``0-6``) 0=Sunday
    :rtype: int (readonly)

.. _ScheduledTime-Label:

.. py:data:: model.ScheduledTime

    :return: The 15 minute time frame for the TaskScheduler
    :rtype: str (readonly)

    This value is populated by the BatchProcess Service running on TouchPoint servers.
    It is not available at this time for non-TouchPoint clients.

    The format is "HHmm" e.g. "0930" for 9:30 AM or "1615" for 4:15 PM

    Example::

        if model.DayOfWeek == 2 and model.ScheduledTime == '1800':
            model.CallScript("EmailAttendanceReports")

        if model.DayOfWeek == 4 and model.ScheduledTime == '0930':
            model.CallScript("EmailReminders")

    This could would be located in a Python Script called ScheduledTasks.
    There would two additional scripts
    called EmailReminders and EmailAttendanceReports
    that would run on Thursday morning and Tuesday evening respectively.

.. py:function:: model.DateAddDays(date, days)

    :return: The new date.
    :rtype: datetime
    :param datetime date: The existing date
    :param int days: The number of days after or before (negative) the existing date.

    This function takes the existing date (dt) and adds the number of days and returns the resulting date.

.. py:function:: model.DateDiffDays(date1, date2)

    :return: The number of days between the two dates
    :rtype: int
    :param datetime date1: The beginning date
    :param datetime date2: The ending date

    The number of days between the two dates is returned.
    If the second date is less than the first date, the return value will be negative.

.. py:function:: model.DateAddHours(date, hours)

    :return: The new date.
    :rtype: datetime
    :param datetime date: The existing date and time.
    :param int hours: The number of hours after or before (negative) the existing date/time.

    This function takes the existing date/time (dt) and adds the number of hours and returns the result.

.. py:function:: model.MostRecentAttendedSunday(progid)

    :return: The date on which the most recent attendance occurred for the specified program.
    :rtype: date
    :param int progid: The id of the Program containing the orgs/meetings on which there is attendance.

.. py:function:: model.ParseDate(string dt)

    :return: The datetime object which is represented by the string.
    :rtype: datetime
    :param str dt: The string representing the date to be returned.

    If the string (dt) will be parsed and use various formats to discover the date.
    If it does not properly parse out to a date, a Python None value will be returned.

    Example::

        dt = model.ParseDate('5/30/{}'.format(model.DateTime.Year))
        print "Day of Week for my birthday ({:M/d/yyyy}) this year is {:dddd}".format(dt, dt)

.. py:function:: model.SetToday(dt)

    :param datetime dt: The date to simulate.

    This function is for debugging.
    You can make all functionality of the script behave as if hte date is the one set.
    All functions called during the script will also behave as if the date is the one set.
    This value is stored in the user's session and will not affect other users.
    This function should never be used in code that will be executed in the batch process.

.. py:function:: model.ResetToday()

    This function is for debugging.
    This will revert the current date back to the actual date.

.. py:function:: model.SundayForDate(dt)

    :return: The first day of the week (Sunday) in which the dt parameter occurs.
    :rtype: datetime
    :param datetime dt: The date for which to find it's corresponding Sunday (it can be a str or a datetime).

.. py:function:: model.SundayForWeek(year, week)

    :return: The Sunday for the numbered week in the specified. 
    :rtype: datetime
    :param int year: The year (e.g. 2016)
    :param int week: The numbered week, 1-52.

    For example::

        year = 2016
        print '<table class="table" style="width:auto">'
        row = '<tr><td>{}</td><td>{:MM/dd/yyyy}</td></tr>'
        for week in range(1, 53):
            print row.format(week, model.SundayForWeek(year, week))
        print '</table>'

    This prints the all the Sundays in the year 2016.

.. py:function:: model.WeekNumber(dt)

    :return: The week number (of the year) for the given date.
    :rtype: int
    :param datetime dt:

    Example::
        
        print model.WeekNumber('7/4/2016')

.. py:function:: model.WeekOfMonth(dt)

    :return: The week number of the month for the given date.
    :rtype: int
    :param datetime dt:

    The week number is determined by the Sunday on or before the given date.
    The first Sunday in a month is WeekOfMonth = 1

    If you only wanted to send emails on the Thursday before the first week of the month,
    you could do the following::

        orgids = [110, 120, 155]
        nextWeek = model.DateAddDays(model.DateTime, 7)
        nextWeekOfMonth = model.WeekOfMonth(nextWeek)
        if model.DayOfWeek == 4 and nextWeekOfMonth == 1:
            for orgid in orgids:
                model.EmailReminders(orgid)