X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=datetime_utils.py;h=b05097a909a53a1a39836dffbd91e02887b8aabd;hb=532df2c5b57c7517dfb3dddd8c1358fbadf8baf3;hp=fb859719796c5cc377e328bacf2aecf2b6bb81f6;hpb=6ba90a1f30f1c0cf4df12fcd0c62181f29bc3668;p=python_utils.git diff --git a/datetime_utils.py b/datetime_utils.py index fb85971..b05097a 100644 --- a/datetime_utils.py +++ b/datetime_utils.py @@ -1,12 +1,14 @@ #!/usr/bin/env python3 +# © Copyright 2021-2022, Scott Gasch + """Utilities related to dates and times and datetimes.""" import datetime import enum import logging import re -from typing import Any, NewType, Tuple +from typing import Any, NewType, Optional, Tuple import holidays # type: ignore import pytz @@ -31,13 +33,92 @@ def is_timezone_aware(dt: datetime.datetime) -> bool: def is_timezone_naive(dt: datetime.datetime) -> bool: + """Inverse of is_timezone_aware. + + >>> is_timezone_naive(datetime.datetime.now()) + True + + >>> is_timezone_naive(now_pacific()) + False + + """ return not is_timezone_aware(dt) -def replace_timezone(dt: datetime.datetime, tz: datetime.tzinfo) -> datetime.datetime: +def strip_timezone(dt: datetime.datetime) -> datetime.datetime: + """Remove the timezone from a datetime. Does not change the + hours, minutes, seconds, months, days, years, etc... Thus the + instant to which this timestamp refers will change. Silently + ignores datetimes which are already timezone naive. + + >>> now = now_pacific() + >>> now.tzinfo == None + False + + >>> dt = strip_timezone(now) + >>> dt == now + False + + >>> dt.tzinfo == None + True + + >>> dt.hour == now.hour + True + + """ + if is_timezone_naive(dt): + return dt + return replace_timezone(dt, None) + + +def add_timezone(dt: datetime.datetime, tz: datetime.tzinfo) -> datetime.datetime: + """ + Adds a timezone to a timezone naive datetime. This does not + change the instant to which the timestamp refers. See also: + replace_timezone. + + >>> now = datetime.datetime.now() + >>> is_timezone_aware(now) + False + + >>> now_pacific = add_timezone(now, pytz.timezone('US/Pacific')) + >>> is_timezone_aware(now_pacific) + True + + >>> now.hour == now_pacific.hour + True + >>> now.minute == now_pacific.minute + True + """ - Replaces the timezone on a datetime object directly (leaving - the year, month, day, hour, minute, second, micro, etc... alone). + + # This doesn't work, tz requires a timezone naive dt. Two options + # here: + # 1. Use strip_timezone and try again. + # 2. Replace the timezone on your dt object via replace_timezone. + # Be aware that this changes the instant to which the dt refers + # and, further, can introduce weirdness like UTC offsets that + # are weird (e.g. not an even multiple of an hour, etc...) + if is_timezone_aware(dt): + if dt.tzinfo == tz: + return dt + raise Exception( + f'{dt} is already timezone aware; use replace_timezone or translate_timezone ' + + 'depending on the semantics you want.' + ) + return dt.replace(tzinfo=tz) + + +def replace_timezone(dt: datetime.datetime, tz: Optional[datetime.tzinfo]) -> datetime.datetime: + """Replaces the timezone on a timezone aware datetime object directly + (leaving the year, month, day, hour, minute, second, micro, + etc... alone). + + Works with timezone aware and timezone naive dts but for the + latter it is probably better to use add_timezone or just create it + with a tz parameter. Using this can have weird side effects like + UTC offsets that are not an even multiple of an hour, etc... + Note: this changes the instant to which this dt refers. >>> from pytz import UTC @@ -52,22 +133,33 @@ def replace_timezone(dt: datetime.datetime, tz: datetime.tzinfo) -> datetime.dat True """ - return datetime.datetime( - dt.year, - dt.month, - dt.day, - dt.hour, - dt.minute, - dt.second, - dt.microsecond, - tzinfo=tz, - ) + if is_timezone_aware(dt): + logger.warning( + '%s already has a timezone; klobbering it anyway.\n Be aware that this operation changed the instant to which the object refers.', + dt, + ) + return datetime.datetime( + dt.year, + dt.month, + dt.day, + dt.hour, + dt.minute, + dt.second, + dt.microsecond, + tzinfo=tz, + ) + else: + if tz: + return add_timezone(dt, tz) + else: + return dt def replace_time_timezone(t: datetime.time, tz: datetime.tzinfo) -> datetime.time: """ Replaces the timezone on a datetime.time directly without performing - any translation. + any translation. Note that, as above, this will change the instant + to which the time refers. >>> t = datetime.time(8, 15, 12, 0, pytz.UTC) >>> t.tzname() @@ -104,7 +196,7 @@ def translate_timezone(dt: datetime.datetime, tz: datetime.tzinfo) -> datetime.d def now() -> datetime.datetime: """ - What time is it? Result returned in UTC + What time is it? Returned as a timezone naive datetime. """ return datetime.datetime.now() @@ -159,14 +251,11 @@ def time_to_datetime_today(time: datetime.time) -> datetime.datetime: False """ - now = now_pacific() tz = time.tzinfo - return datetime.datetime.combine(now, time, tz) + return datetime.datetime.combine(now_pacific(), time, tz) -def date_and_time_to_datetime( - date: datetime.date, time: datetime.time -) -> 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. @@ -250,20 +339,18 @@ class TimeUnit(enum.IntEnum): @classmethod def is_valid(cls, value: Any): - if type(value) is int: - return value in cls._value2member_map_ - elif type(value) is TimeUnit: - return value.value in cls._value2member_map_ - elif type(value) is str: - return value in cls._member_names_ + if isinstance(value, int): + return cls(value) is not None + elif isinstance(value, TimeUnit): + return cls(value.value) is not None + elif isinstance(value, str): + return cls.__members__[value] is not None else: print(type(value)) return False -def n_timeunits_from_base( - count: int, unit: TimeUnit, base: datetime.datetime -) -> datetime.datetime: +def n_timeunits_from_base(count: int, 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... @@ -353,10 +440,7 @@ def n_timeunits_from_base( base += timedelta if base.year != old_year: skips = holidays.US(years=base.year).keys() - if ( - base.weekday() < 5 - and datetime.date(base.year, base.month, base.day) not in skips - ): + if base.weekday() < 5 and datetime.date(base.year, base.month, base.day) not in skips: count -= 1 return base @@ -515,6 +599,7 @@ def datetime_to_string( date_time_separator=date_time_separator, include_timezone=include_timezone, include_dayname=include_dayname, + use_month_abbrevs=use_month_abbrevs, include_seconds=include_seconds, include_fractional=include_fractional, twelve_hour=twelve_hour, @@ -548,6 +633,7 @@ def string_to_datetime( date_time_separator=date_time_separator, include_timezone=include_timezone, include_dayname=include_dayname, + use_month_abbrevs=use_month_abbrevs, include_seconds=include_seconds, include_fractional=include_fractional, twelve_hour=twelve_hour, @@ -825,9 +911,7 @@ def describe_timedelta_briefly(delta: datetime.timedelta) -> str: '1d 10m' """ - return describe_duration_briefly( - int(delta.total_seconds()) - ) # Note: drops milliseconds + return describe_duration_briefly(int(delta.total_seconds())) # Note: drops milliseconds if __name__ == '__main__':