wetsuite.helpers.date

module documentation

Try to deal with varied forms of dates and times, and ease things like "I would like to specify a range of days in a particular format" (e.g. for bulk fetching), and such.

Note that this module is focused only on days, not on precise times. And, as a result (timezones), it may be a day off.

CONSIDER: making anything range-based be generators.

Class	`DutchParserInfo`	specific configuration for dateutil for dutch month and week names
Function	`date_first_day_in_month`	No summary
Function	`date_first_day_in_year`	No summary
Function	`date_last_day_in_year`	No summary
Function	`date_months_ago`	No summary
Function	`date_ranges`	Given a larger interval, return a series of shorter intervals no larger than increment_days long. (currently first and last days overlap; TODO: parameter to control that)
Function	`date_today`	No summary
Function	`date_weeks_ago`	No summary
Function	`days_in_range`	Given a start and end date, returns a list of all individual days in that range (including the last), as a datetime.date object. (Note that if you want something like this for pandas, it has its own date_range that may be nicer)...
Function	`find_dates_in_text`	Tries to fish out date-like strings from free-form text. Not general-purpose - it's targeted at some specific fields we know have mainly/only contain dates, and have relatively well formatted dates, mostly to normalize those.
Function	`format_date`	Takes a single datetime object, calls strftime on it.
Function	`format_date_list`	Takes a list of datetime objects, calls format_date() on each of that list.
Function	`parse`	Try to parse a string as a date.
Function	`yyyy_mm_dd`	Given a datetime or date like datetime.date(2024, 1, 1), returns a string like '2024-01-01' (strftime('%Y-%m-%d')
Function	`_date_from_date_datetime_or_parse`	Intended to normalzing date/datetime/date-as-string parameters into date objects.
Constant	`_MAAND_RES`	regexp fragment to match most month spellings, English and Dutch
Variable	`_re_dutch_date_1`	Undocumented
Variable	`_re_dutch_date_2`	Undocumented
Variable	`_re_isolike_date`	Undocumented

def date_first_day_in_month(yearnum=None, monthnum=None): ¶

Parameters
yearnum:`int`	the year you want the first day of, e.g. 2024. If not given, defaults to the current year.
monthnum:`int`	the year you want the first day of, e.g. 2024. If not given, defaults to the current month. (note that if you don't give month but do give year, you might get some behaviour you did not expect)
Returns
The first day of the month in the given year, as a datetime.date

def date_first_day_in_year(yearnum=None): ¶

Parameters
yearnum:`int`	the year you want the first day of, e.g. 2024. If not given, defaults to the current year.
Returns
January first of the given year, as a datetime.date

def date_last_day_in_year(yearnum=None): ¶

Parameters
yearnum:`int`	the year you want the first day of, e.g. 2024. If not given, defaults to the current year.
Returns
January first of the given year, as a datetime.date

def date_months_ago(amount=1): ¶

Parameters
amount:`float`	Undocumented
Returns
A date some amount of months ago from the day of calling this, as a datetime.date

def date_ranges(from_date, to_date, increment_days, strftime_format=None): ¶

Given a larger interval, return a series of shorter intervals no larger than increment_days long. (currently first and last days overlap; TODO: parameter to control that)

Parameters
from_date	start of range. Takes a date object, a datetime object, or string to parse (using dateutil library; please do not use ambiguous formats like 02/02/11)
to_date	end of range, inclusive
increment_days	size of each range
strftime_format	Undocumented
Returns
a list of tuples, which are either date objects (default or if you explicitly said strftime=None), or strings (if strftime is specified; you might want it to be "%Y-%m-%d")

def date_today(): ¶

Returns
today, as a datetime.date

def date_weeks_ago(amount=1): ¶

Parameters
amount:`float`	Undocumented
Returns
A date some amount of months ago from the day of calling this, as a datetime.date

def days_in_range(from_date, to_date, strftime_format=None): ¶

Given a start and end date, returns a list of all individual days in that range (including the last), as a datetime.date object. (Note that if you want something like this for pandas, it has its own date_range that may be nicer)

For example: :

    date_range( datetime.date(2022, 1, 29),   datetime.date(2022, 2, 2)  )

and :

    date_range( '29 jan 2022',  '2 feb 2022')

should both give: :

    [ datetime.date(2022, 1, 29),
      datetime.date(2022, 1, 30),
      datetime.date(2022, 1, 31),
      datetime.date(2022, 2, 1),
      datetime.date(2022, 2, 2)  ]

Parameters
from_date	start of range, as a date object, datetime object, or string to parse (using dateutil library) (please do not use formats like 02/02/11 and also expect the output to do what you want)
to_date	end of range, inclusive
strftime_format	Undocumented
Returns
a list of datetime.date objects

def find_dates_in_text(text): ¶

Tries to fish out date-like strings from free-form text. Not general-purpose - it's targeted at some specific fields we know have mainly/only contain dates, and have relatively well formatted dates, mostly to normalize those.

...because "try to find everthing, hope for the best" is likely to have false positives (identify things as dates that aren't) as well as false negatives (miss things that are ). CONSIDER: still, add such a freer mode in here anyway, just not as the default.

Currently looks only for three specific patterns:

1980-01-01
1 jan 1980
jan 1 1980

...the latter two with both Dutch and English month naming.

Parameters
text:`str`	the string to find dates in
Returns
two lists: list of each found date, as strings according list where each is a date object -- or None where dateutil didn't manage (it usually does, particularly if we pre-filter like this, but it's not a guarantee) CONSIDER: also match objects so that we have positions?

def format_date(dt, strftime_format='%Y-%m-%d'): ¶

Takes a single datetime object, calls strftime on it.

Parameters
dt	a datetime obkect
strftime_format	a string that tells strftime how to format the date Defaults to '%Y-%m-%d', which is a ISO8601-style YYYY-MM-DD thing
Returns
date string, formatted that way

def format_date_list(datelist, strftime_format='%Y-%m-%d'): ¶

Takes a list of datetime objects, calls format_date() on each of that list.

For example: :

    format_date_range(  date_range( datetime.date(2022, 1, 29),   datetime.date(2022, 2, 2) )  )

would return: :

    ['2022-01-29', '2022-01-30', '2022-01-31', '2022-02-01', '2022-02-02']

Parameters
datelist	a list of datetime objects
strftime_format	a string that tells strftime how to format the date (see also `format_date`)
Returns
a list of formatted date strings

def parse(text, as_date=False, exception_as_none=True): ¶

Try to parse a string as a date.

Mostly just calls dateutil.parser.parse(), a library that deals with more varied date formats ...but we have told it a litte more about Dutch, not just English. TODO: add French, there is some early legal text in French.

We try to be a little more robust here - and will try to return None instead of raising an exception (but no promises).

Parameters
text:`str`	Takes a string that you know contains just a date
as_date	return as date, not datetime.
exception_as_none	if invalid, return None rather than raise a ValueError
Returns
that date as a datetime (or date, if you prefer), or None

def yyyy_mm_dd(day): ¶

Given a datetime or date like datetime.date(2024, 1, 1), returns a string like '2024-01-01' (strftime('%Y-%m-%d')

Parameters
day:`datetime.date`	Undocumented

def _date_from_date_datetime_or_parse(a_date): ¶

Intended to normalzing date/datetime/date-as-string parameters into date objects.

Parameters
a_date	date as a date object, datetime object, or string to parse (using dateutil library)
Returns
date object

_MAAND_RES: str = ¶

regexp fragment to match most month spellings, English and Dutch

Value

'januar[iy]|jan|februar[yi]|feb|maart|march|mar|april|apr|mei|may|jun|jun[ei]|ju↵
l|jul[iy]|august|augustus|aug|o[ck]tober|o[ck]t|november|nov|december|dec'

_re_dutch_date_1 = ¶

Undocumented

_re_dutch_date_2 = ¶

Undocumented

_re_isolike_date = ¶

Undocumented