Since this thing is on the innerwebs I suppose it should have a

[python_utils.git] / datetime_utils.py

diff --git a/datetime_utils.py b/datetime_utils.py
index 6f504f6c304b850e830cffab08d0ed8be67fed39..b05097a909a53a1a39836dffbd91e02887b8aabd 100644 (file)
--- a/datetime_utils.py
+++ b/datetime_utils.py
@@ -1,12 +1,14 @@
 #!/usr/bin/env python3
 
 #!/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
 """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
 
 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:
 
 
 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)
 
 
     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
     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
 
     """
     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
 
 
 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()
 
     >>> 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:
     """
 
 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()
 
     """
     return datetime.datetime.now()
 


@@ -159,14 +251,11 @@ def time_to_datetime_today(time: datetime.time) -> datetime.datetime:
     False
 
     """
     False
 
     """

-    now = now_pacific()

     tz = time.tzinfo
     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.
 
     """
     Given a date and time, merge them and return a datetime.
 


@@ -229,7 +318,7 @@ def datetime_to_time(dt: datetime.datetime) -> datetime.time:
     return datetime_to_date_and_time(dt)[1]
 
 
     return datetime_to_date_and_time(dt)[1]
 
 

-class TimeUnit(enum.Enum):
+class TimeUnit(enum.IntEnum):

     """An enum to represent units with which we can compute deltas."""
 
     MONDAYS = 0
     """An enum to represent units with which we can compute deltas."""
 
     MONDAYS = 0


@@ -250,20 +339,18 @@ class TimeUnit(enum.Enum):
 
     @classmethod
     def is_valid(cls, value: Any):
 
     @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
 
 
         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...
     """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()
             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
 
                 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,
         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,
         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,
         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,
         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'
 
     """
     '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__':
 
 
 if __name__ == '__main__':