X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=datetime_utils.py;h=55e0ffab3b0dcedf1e6830aef38cd387d736fde0;hb=02302bbd9363facb59c4df2c1f4013087702cfa6;hp=fc1ca4ed9e07e407554da7e300f53ca58f98661a;hpb=0d63d44ac89aab38fe95f36497adaf95110ab949;p=python_utils.git diff --git a/datetime_utils.py b/datetime_utils.py index fc1ca4e..55e0ffa 100644 --- a/datetime_utils.py +++ b/datetime_utils.py @@ -1,12 +1,14 @@ #!/usr/bin/env python3 -"""Utilities related to dates and times and datetimes.""" +# © Copyright 2021-2022, Scott Gasch + +"""Utilities related to dates, 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 @@ -17,8 +19,14 @@ logger = logging.getLogger(__name__) def is_timezone_aware(dt: datetime.datetime) -> bool: - """See: https://docs.python.org/3/library/datetime.html - #determining-if-an-object-is-aware-or-naive + """Returns true if the datetime argument is timezone aware or + False if not. + + See: https://docs.python.org/3/library/datetime.html + #determining-if-an-object-is-aware-or-naive + + Args: + dt: The datetime object to check >>> is_timezone_aware(datetime.datetime.now()) False @@ -31,14 +39,106 @@ def is_timezone_aware(dt: datetime.datetime) -> bool: def is_timezone_naive(dt: datetime.datetime) -> bool: + """Inverse of is_timezone_aware -- returns true if the dt argument + is timezone naive. + + See: https://docs.python.org/3/library/datetime.html + #determining-if-an-object-is-aware-or-naive + + Args: + dt: The datetime object to check + + >>> 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. + + .. warning:: + + This 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: """ - Replaces the timezone on a datetime object directly (leaving - the year, month, day, hour, minute, second, micro, etc... alone). - Note: this changes the instant to which this dt refers. + 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 + + """ + + # 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. See the pydocs / code.' + ) + 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... + + .. warning:: + + This changes the instant to which this dt refers. >>> from pytz import UTC >>> d = now_pacific() @@ -52,23 +152,37 @@ 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 + """Replaces the timezone on a datetime.time directly without performing any translation. + .. warning:: + + 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() 'UTC' @@ -76,7 +190,6 @@ def replace_time_timezone(t: datetime.time, tz: datetime.tzinfo) -> datetime.tim >>> t = replace_time_timezone(t, pytz.timezone('US/Pacific')) >>> t.tzname() 'US/Pacific' - """ return t.replace(tzinfo=tz) @@ -104,7 +217,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? Result is a timezone naive datetime. """ return datetime.datetime.now() @@ -188,7 +301,8 @@ def date_and_time_to_datetime(date: datetime.date, time: datetime.time) -> datet def datetime_to_date_and_time( dt: datetime.datetime, ) -> Tuple[datetime.date, datetime.time]: - """Return the component date and time objects of a datetime. + """Return the component date and time objects of a datetime in a + Tuple given a datetime. >>> import datetime >>> dt = datetime.datetime(2021, 12, 25, 12, 30) @@ -203,7 +317,7 @@ def datetime_to_date_and_time( def datetime_to_date(dt: datetime.datetime) -> datetime.date: - """Return the date part of a datetime. + """Return just the date part of a datetime. >>> import datetime >>> dt = datetime.datetime(2021, 12, 25, 12, 30) @@ -215,7 +329,7 @@ def datetime_to_date(dt: datetime.datetime) -> datetime.date: def datetime_to_time(dt: datetime.datetime) -> datetime.time: - """Return the time part of a datetime. + """Return just the time part of a datetime. >>> import datetime >>> dt = datetime.datetime(2021, 12, 25, 12, 30)