Date Tools (regolith.dates)

Date based tools

regolith.dates.convert_doc_iso_to_date(doc)

regolith.dates.date_to_float(y, m, d=0)

Converts years / months / days to a float, eg 2015.0818 is August 18th 2015.

regolith.dates.day_to_str_int(d)

Converts a day to an int form, str type, with a leading zero

regolith.dates.find_gaps_overlaps(dateslist, overlaps_ok=False)

Find whether there is a gap or an overlap in a list of date-ranges

Parameters:

• dateslist (list of tuples of datetime.date objects) – The list of date-ranges.

• overlaps_ok (bool) – Returns false if there are gaps but true if there are overlaps but no gaps

Return type:

True if there are no gaps or overlaps else False

regolith.dates.get_dates(thing, date_field_prefix=None)

given a dict like thing, return the date items

Parameters:

• thing (dict) – the dict that contains the dates

• date_field_prefix (string (optional)) – the prefix to look for before the date parameter. For example given “submission” the function will search for submission_day, submission_year, etc.

Returns:

• dict containing datetime.date objects for valid begin_date end_date and date, and

• prefix_date if a prefix string was passed. Missing and empty dates and

• date items that contain the string ‘tbd’ are not returned. If no valid

• date items are found, an empty dict is returned

If “begin_date”, “end_date” or “date” values are found, if these are are in an ISO format string they will be converted to datetime.date objects and returned in the dictionary under keys of the same name. A specified date will override any date built from year/month/day data.

If they are not found the function will look for begin_year, end_year and year.

If “year”, “month” and “day” are found the function will return these in the “date” field and begin_date and end_date will match the “date” field. If only a “year” is found, then the date attribute will be none but the begin and end dates will be the first and last day of that respective year.

If year is found but no month or day are found the function will return begin_date and end_date with the beginning and the end of the given year/month. The returned date will be None.

If end_year is found, the end month and end day are missing they are set to 12 and 31, respectively

If begin_year is found, the begin month and begin day are missing they are set to 1 and 1, respectively

If a date field prefix is passed in this function will search for prefix_year as well as prefix_month, prefix_day, and prefix_date. For example, if the prefix string passed in is “submitted” then this function will look for submitted_date instead of just date.

Examples

>>> get_dates({'submission_day': 10, 'submission_year': 2020, 'submission_month': 'Feb'}, "submission")

This would return a dictionary consisting of the begin date, end, date, and date for the given input. Instead of searching for “day” in the thing, it would search for “submission_day” since a prefix was given. The following dictionary is returned (note that a submission_date and a date key are in the dictionary): {‘begin_date’: datetime.date(2020, 2, 10),

‘end_date’: datetime.date(2020, 2, 10), ‘submission_date’: datetime.date(2020, 2, 10), ‘date’: datetime.date(2020, 2, 10)

}

>>> get_dates({'begin_year': 2019, 'end_year': 2020, 'end_month': 'Feb'})

This will return a dictionary consisting of the begin date, end date, and date for the given input. Because no prefix string was passed in, the function will search for “date” in the input instead of prefix_input. The following dictionary is returned: {‘begin_date’: datetime.date(2019, 1, 1),

‘end_date’: datetime.date(2020, 2, 29),

}

regolith.dates.get_due_date(thing)

Parameters:

thing (dict) – gets the field named ‘due_date’ from doc and ensurese it is a datetime.date object

Return type:

The due date as a datetime.date object

regolith.dates.has_finished(thing, now=None)

given a thing with dates, returns true if the thing has finished

Parameters:

• thing (dict) – the thing that we want to know whether or not it has finished

• now (datetime.date object) – a date for now. If it is None it uses the current date. Default is None

Return type:

True if the thing has finished and false otherwise

regolith.dates.has_started(thing, now=None)

given a thing with dates, returns true if the thing has started

Parameters:

• thing (dict) – the thing that we want to know whether or not it is has started

• now (datetime.date object) – a date for now. If it is None it uses the current date. Default is None

Return type:

True if the thing has started and false otherwise

regolith.dates.is_after(thing, now=None)

given a thing with a date, returns true if the thing is after the input date

Parameters:

• thing (dict) – the thing that we want to know whether or not is after a date

• now (datetime.date object) – a date for now. If it is None it uses the current date. Default is None

Return type:

True if the thing is after the date

regolith.dates.is_before(thing, now=None)

given a thing with a date, returns true if the thing is before the input date

Parameters:

• thing (dict) – the thing that we want to know whether or not is before a date

• now (datetime.date object) – a date for now. If it is None it uses the current date. Default is None

Return type:

True if the thing is before the date

regolith.dates.is_between(thing, start=None, end=None)

given a thing with a date, returns true if the thing is between the start and end date

Parameters:

• thing (dict) – the thing that we want to know whether or not is after a date

• start (datetime.date object) – a date for the start. If it is None it uses the current date. Default is None

• end (datetime.date object) – a date for the end. If it is None it uses the current date. Default is None

Return type:

True if the thing is between the start and end

regolith.dates.is_current(thing, now=None)

given a thing with dates, returns true if the thing is current looks for begin_ and end_ daty things (date, year, month, day), or just the daty things themselves. e.g., begin_date, end_month, month, and so on.

Parameters:

• thing (dict) – the thing that we want to know whether or not it is current

• now (datetime.date object) – a date for now. If it is None it uses the current date. Default is None

Return type:

True if the thing is current and false otherwise

regolith.dates.last_day(year, month)

Returns the last day of the month for the month given

Parameters:

• year (integer) – the year that the month is in

• month (integer or string) – the month. if a string should be resolvable using regolith month_to_int

Return type:

The last day of that month

regolith.dates.month_to_int(m)

Converts a month to an integer.

regolith.dates.month_to_str_int(m)

Converts a month to an int form, str type, with a leading zero