X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=datetime_utils.py;fp=datetime_utils.py;h=db5b2b5e19ba8e74fdf192dc122e518e90ec6bf9;hb=83c1e0d04fe2e78963c8b508e8b7d0ae03bfcb16;hp=7787c6f0b0b74b84b84fca28bba8d2381e1d8668;hpb=6f132c0342ab7aa438ed88d7c5f987cb52d8ca05;p=python_utils.git diff --git a/datetime_utils.py b/datetime_utils.py index 7787c6f..db5b2b5 100644 --- a/datetime_utils.py +++ b/datetime_utils.py @@ -18,18 +18,44 @@ logger = logging.getLogger(__name__) def replace_timezone(dt: datetime.datetime, tz: datetime.tzinfo) -> datetime.datetime: + """ + Replaces the timezone on a datetime object. + + >>> from pytz import UTC + >>> d = now_pacific() + >>> d.tzinfo.tzname(d)[0] # Note: could be PST or PDT + 'P' + >>> o = replace_timezone(d, UTC) + >>> o.tzinfo.tzname(o) + 'UTC' + + """ return dt.replace(tzinfo=None).astimezone(tz=tz) def now() -> datetime.datetime: + """ + What time is it? Result returned in UTC + """ return datetime.datetime.now() -def now_pst() -> datetime.datetime: +def now_pacific() -> datetime.datetime: + """ + What time is it? Result in US/Pacifit time (PST/PDT) + """ return replace_timezone(now(), pytz.timezone("US/Pacific")) def date_to_datetime(date: datetime.date) -> datetime.datetime: + """ + Given a date, return a datetime with hour/min/sec zero (midnight) + + >>> import datetime + >>> date_to_datetime(datetime.date(2021, 12, 25)) + datetime.datetime(2021, 12, 25, 0, 0) + + """ return datetime.datetime( date.year, date.month, @@ -40,6 +66,16 @@ def date_to_datetime(date: datetime.date) -> datetime.datetime: def date_and_time_to_datetime(date: datetime.date, time: datetime.time) -> datetime.datetime: + """ + Given a date and time, merge them and return a datetime. + + >>> import datetime + >>> d = datetime.date(2021, 12, 25) + >>> t = datetime.time(12, 30, 0, 0) + >>> date_and_time_to_datetime(d, t) + datetime.datetime(2021, 12, 25, 12, 30) + + """ return datetime.datetime( date.year, date.month, @@ -47,26 +83,53 @@ def date_and_time_to_datetime(date: datetime.date, time.hour, time.minute, time.second, - time.millisecond + time.microsecond, ) def datetime_to_date_and_time( dt: datetime.datetime ) -> Tuple[datetime.date, datetime.time]: + """Return the component date and time objects of a datetime. + + >>> import datetime + >>> dt = datetime.datetime(2021, 12, 25, 12, 30) + >>> (d, t) = datetime_to_date_and_time(dt) + >>> d + datetime.date(2021, 12, 25) + >>> t + datetime.time(12, 30) + + """ return (dt.date(), dt.timetz()) def datetime_to_date(dt: datetime.datetime) -> datetime.date: + """Return the date part of a datetime. + + >>> import datetime + >>> dt = datetime.datetime(2021, 12, 25, 12, 30) + >>> datetime_to_date(dt) + datetime.date(2021, 12, 25) + + """ return datetime_to_date_and_time(dt)[0] def datetime_to_time(dt: datetime.datetime) -> datetime.time: + """Return the time part of a datetime. + + >>> import datetime + >>> dt = datetime.datetime(2021, 12, 25, 12, 30) + >>> datetime_to_time(dt) + datetime.time(12, 30) + + """ return datetime_to_date_and_time(dt)[1] -# An enum to represent units with which we can compute deltas. class TimeUnit(enum.Enum): + """An enum to represent units with which we can compute deltas.""" MONDAYS = 0 TUESDAYS = 1 WEDNESDAYS = 2 @@ -101,6 +164,47 @@ def n_timeunits_from_base( unit: TimeUnit, base: datetime.datetime ) -> datetime.datetime: + """Return a datetime that is N units before/after a base datetime. + e.g. 3 Wednesdays from base datetime, 2 weeks from base date, 10 + years before base datetime, 13 minutes after base datetime, etc... + Note: to indicate before/after the base date, use a positive or + negative count. + + >>> base = string_to_datetime("2021/09/10 11:24:51AM-0700")[0] + + The next (1) Monday from the base datetime: + >>> n_timeunits_from_base(+1, TimeUnit.MONDAYS, base) + datetime.datetime(2021, 9, 13, 11, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + Ten (10) years after the base datetime: + >>> n_timeunits_from_base(10, TimeUnit.YEARS, base) + datetime.datetime(2031, 9, 10, 11, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + Fifty (50) working days (M..F, not counting holidays) after base datetime: + >>> n_timeunits_from_base(50, TimeUnit.WORKDAYS, base) + datetime.datetime(2021, 11, 23, 11, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + Fifty (50) days (including weekends and holidays) after base datetime: + >>> n_timeunits_from_base(50, TimeUnit.DAYS, base) + datetime.datetime(2021, 10, 30, 11, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + Fifty (50) months before (note negative count) base datetime: + >>> n_timeunits_from_base(-50, TimeUnit.MONTHS, base) + datetime.datetime(2017, 7, 10, 11, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + Fifty (50) hours after base datetime: + >>> n_timeunits_from_base(50, TimeUnit.HOURS, base) + datetime.datetime(2021, 9, 12, 13, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + Fifty (50) minutes before base datetime: + >>> n_timeunits_from_base(-50, TimeUnit.MINUTES, base) + datetime.datetime(2021, 9, 10, 10, 34, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + Fifty (50) seconds from base datetime: + >>> n_timeunits_from_base(50, TimeUnit.SECONDS, base) + datetime.datetime(2021, 9, 10, 11, 25, 41, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + """ assert TimeUnit.is_valid(unit) if count == 0: return base @@ -110,6 +214,21 @@ def n_timeunits_from_base( timedelta = datetime.timedelta(days=count) return base + timedelta + # N hours from base + elif unit == TimeUnit.HOURS: + timedelta = datetime.timedelta(hours=count) + return base + timedelta + + # N minutes from base + elif unit == TimeUnit.MINUTES: + timedelta = datetime.timedelta(minutes=count) + return base + timedelta + + # N seconds from base + elif unit == TimeUnit.SECONDS: + timedelta = datetime.timedelta(seconds=count) + return base + timedelta + # N workdays from base elif unit == TimeUnit.WORKDAYS: if count < 0: @@ -155,6 +274,7 @@ def n_timeunits_from_base( base.minute, base.second, base.microsecond, + base.tzinfo, ) # N years from base @@ -168,8 +288,18 @@ def n_timeunits_from_base( base.minute, base.second, base.microsecond, + base.tzinfo, ) + if unit not in set([TimeUnit.MONDAYS, + TimeUnit.TUESDAYS, + TimeUnit.WEDNESDAYS, + TimeUnit.THURSDAYS, + TimeUnit.FRIDAYS, + TimeUnit.SATURDAYS, + TimeUnit.SUNDAYS]): + raise ValueError(unit) + # N weekdays from base (e.g. 4 wednesdays from today) direction = 1 if count > 0 else -1 count = abs(count) @@ -177,7 +307,7 @@ def n_timeunits_from_base( start = base while True: dow = base.weekday() - if dow == unit and start != base: + if dow == unit.value and start != base: count -= 1 if count == 0: return base @@ -194,14 +324,31 @@ def get_format_string( include_fractional=False, twelve_hour=True, ) -> str: + """ + Helper to return a format string without looking up the documentation + for strftime. + + >>> get_format_string() + '%Y/%m/%d %I:%M:%S%p%z' + + >>> get_format_string(date_time_separator='@') + '%Y/%m/%d@%I:%M:%S%p%z' + + >>> get_format_string(include_dayname=True) + '%a/%Y/%m/%d %I:%M:%S%p%z' + + >>> get_format_string(include_dayname=True, twelve_hour=False) + '%a/%Y/%m/%d %H:%M:%S%z' + + """ fstring = "" if include_dayname: fstring += "%a/" if use_month_abbrevs: - fstring = f"%Y/%b/%d{date_time_separator}" + fstring = f"{fstring}%Y/%b/%d{date_time_separator}" else: - fstring = f"%Y/%m/%d{date_time_separator}" + fstring = f"{fstring}%Y/%m/%d{date_time_separator}" if twelve_hour: fstring += "%I:%M" if include_seconds: @@ -229,7 +376,21 @@ def datetime_to_string( include_fractional=False, twelve_hour=True, ) -> str: - """A nice way to convert a datetime into a string.""" + """ + A nice way to convert a datetime into a string; arguably better than + just printing it and relying on it __repr__(). + + >>> d = string_to_datetime( + ... "2021/09/10 11:24:51AM-0700", + ... )[0] + >>> d + datetime.datetime(2021, 9, 10, 11, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + >>> datetime_to_string(d) + '2021/09/10 11:24:51AM-0700' + >>> datetime_to_string(d, include_dayname=True, include_seconds=False) + 'Fri/2021/09/10 11:24AM-0700' + + """ fstring = get_format_string( date_time_separator=date_time_separator, include_timezone=include_timezone, @@ -251,8 +412,16 @@ def string_to_datetime( include_fractional=False, twelve_hour=True, ) -> Tuple[datetime.datetime, str]: - """A nice way to convert a string into a datetime. Also consider - dateparse.dateparse_utils for a full parser. + """A nice way to convert a string into a datetime. Returns both the + datetime and the format string used to parse it. Also consider + dateparse.dateparse_utils for a full parser alternative. + + >>> d = string_to_datetime( + ... "2021/09/10 11:24:51AM-0700", + ... ) + >>> d + (datetime.datetime(2021, 9, 10, 11, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))), '%Y/%m/%d %I:%M:%S%p%z') + """ fstring = get_format_string( date_time_separator=date_time_separator, @@ -268,7 +437,7 @@ def string_to_datetime( def timestamp() -> str: - """Return a timestamp for now in Pacific timezone.""" + """Return a timestamp for right now in Pacific timezone.""" ts = datetime.datetime.now(tz=pytz.timezone("US/Pacific")) return datetime_to_string(ts, include_timezone=True) @@ -281,7 +450,25 @@ def time_to_string( include_timezone=False, twelve_hour=True, ) -> str: - """A nice way to convert a datetime into a time (only) string.""" + """A nice way to convert a datetime into a time (only) string. + This ignores the date part of the datetime. + + >>> d = string_to_datetime( + ... "2021/09/10 11:24:51AM-0700", + ... )[0] + >>> d + datetime.datetime(2021, 9, 10, 11, 24, 51, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200))) + + >>> time_to_string(d) + '11:24:51AM' + + >>> time_to_string(d, include_seconds=False) + '11:24AM' + + >>> time_to_string(d, include_seconds=False, include_timezone=True) + '11:24AM-0700' + + """ fstring = "" if twelve_hour: fstring += "%l:%M" @@ -308,18 +495,62 @@ MinuteOfDay = NewType("MinuteOfDay", int) def minute_number(hour: int, minute: int) -> MinuteOfDay: - """Convert hour:minute into minute number from start of day.""" + """ + Convert hour:minute into minute number from start of day. + + >>> minute_number(0, 0) + 0 + + >>> minute_number(9, 15) + 555 + + >>> minute_number(23, 59) + 1439 + + """ return MinuteOfDay(hour * 60 + minute) def datetime_to_minute_number(dt: datetime.datetime) -> MinuteOfDay: - """Convert a datetime into a minute number (of the day)""" + """ + Convert a datetime into a minute number (of the day). Note that + this ignores the date part of the datetime and only uses the time + part. + + >>> d = string_to_datetime( + ... "2021/09/10 11:24:51AM-0700", + ... )[0] + + >>> datetime_to_minute_number(d) + 684 + + """ return minute_number(dt.hour, dt.minute) +def time_to_minute_number(t: datetime.time) -> MinuteOfDay: + """ + Convert a datetime.time into a minute number. + + >>> t = datetime.time(5, 15) + >>> time_to_minute_number(t) + 315 + + """ + return minute_number(t.hour, t.minute) + + def minute_number_to_time_string(minute_num: MinuteOfDay) -> str: - """Convert minute number from start of day into hour:minute am/pm + """ + Convert minute number from start of day into hour:minute am/pm string. + + >>> minute_number_to_time_string(315) + ' 5:15a' + + >>> minute_number_to_time_string(684) + '11:24a' + """ hour = minute_num // 60 minute = minute_num % 60 @@ -335,7 +566,22 @@ def minute_number_to_time_string(minute_num: MinuteOfDay) -> str: def parse_duration(duration: str) -> int: - """Parse a duration in string form.""" + """ + Parse a duration in string form into a delta seconds. + + >>> parse_duration('15 days, 2 hours') + 1303200 + + >>> parse_duration('15d 2h') + 1303200 + + >>> parse_duration('100s') + 100 + + >>> parse_duration('3min 2sec') + 182 + + """ if duration.isdigit(): return int(duration) seconds = 0 @@ -354,9 +600,24 @@ def parse_duration(duration: str) -> int: return seconds -def describe_duration(age: int) -> str: - """Describe a duration.""" - days = divmod(age, constants.SECONDS_PER_DAY) +def describe_duration(seconds: int, *, include_seconds = False) -> str: + """ + Describe a duration represented as a count of seconds nicely. + + >>> describe_duration(182) + '3 minutes' + + >>> describe_duration(182, include_seconds=True) + '3 minutes, and 2 seconds' + + >>> describe_duration(100, include_seconds=True) + '1 minute, and 40 seconds' + + describe_duration(1303200) + '15 days, 2 hours' + + """ + days = divmod(seconds, constants.SECONDS_PER_DAY) hours = divmod(days[1], constants.SECONDS_PER_HOUR) minutes = divmod(hours[1], constants.SECONDS_PER_MINUTE) @@ -365,30 +626,65 @@ def describe_duration(age: int) -> str: descr = f"{int(days[0])} days, " elif days[0] == 1: descr = "1 day, " + if hours[0] > 1: descr = descr + f"{int(hours[0])} hours, " elif hours[0] == 1: descr = descr + "1 hour, " - if len(descr) > 0: + + if not include_seconds and len(descr) > 0: descr = descr + "and " + if minutes[0] == 1: descr = descr + "1 minute" else: descr = descr + f"{int(minutes[0])} minutes" + + if include_seconds: + descr = descr + ', ' + if len(descr) > 0: + descr = descr + 'and ' + s = minutes[1] + if s == 1: + descr = descr + '1 second' + else: + descr = descr + f'{s} seconds' return descr -def describe_duration_briefly(age: int) -> str: - """Describe a duration briefly.""" - days = divmod(age, constants.SECONDS_PER_DAY) +def describe_duration_briefly(seconds: int, *, include_seconds=False) -> str: + """ + Describe a duration briefly. + + >>> describe_duration_briefly(182) + '3m' + + >>> describe_duration_briefly(182, include_seconds=True) + '3m 2s' + + >>> describe_duration_briefly(100, include_seconds=True) + '1m 40s' + + describe_duration_briefly(1303200) + '15d 2h' + + """ + days = divmod(seconds, constants.SECONDS_PER_DAY) hours = divmod(days[1], constants.SECONDS_PER_HOUR) minutes = divmod(hours[1], constants.SECONDS_PER_MINUTE) - descr = "" + descr = '' if days[0] > 0: - descr = f"{int(days[0])}d " + descr = f'{int(days[0])}d ' if hours[0] > 0: - descr = descr + f"{int(hours[0])}h " - if minutes[0] > 0 or len(descr) == 0: - descr = descr + f"{int(minutes[0])}m" + descr = descr + f'{int(hours[0])}h ' + if minutes[0] > 0 or (len(descr) == 0 and not include_seconds): + descr = descr + f'{int(minutes[0])}m ' + if minutes[1] > 0 and include_seconds: + descr = descr + f'{int(minutes[1])}s' return descr.strip() + + +if __name__ == '__main__': + import doctest + doctest.testmod()