Reduce the doctest lease duration...

[python_utils.git] / datetime_utils.py

diff --git a/datetime_utils.py b/datetime_utils.py
index b05097a909a53a1a39836dffbd91e02887b8aabd..55e0ffab3b0dcedf1e6830aef38cd387d736fde0 100644 (file)
--- a/datetime_utils.py
+++ b/datetime_utils.py
@@ -2,7 +2,7 @@
 
 # © Copyright 2021-2022, Scott Gasch
 
-"""Utilities related to dates and times and datetimes."""
+"""Utilities related to dates, times, and datetimes."""
 
 import datetime
 import enum
@@ -19,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
@@ -33,7 +39,14 @@ def is_timezone_aware(dt: datetime.datetime) -> bool:
 
 
 def is_timezone_naive(dt: datetime.datetime) -> bool:
-    """Inverse of is_timezone_aware.
+    """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
@@ -46,10 +59,14 @@ def is_timezone_naive(dt: datetime.datetime) -> bool:
 
 
 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.
+    """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
@@ -104,7 +121,7 @@ def add_timezone(dt: datetime.datetime, tz: datetime.tzinfo) -> datetime.datetim
             return dt
         raise Exception(
             f'{dt} is already timezone aware; use replace_timezone or translate_timezone '
-            + 'depending on the semantics you want.'
+            + 'depending on the semantics you want.  See the pydocs / code.'
         )
     return dt.replace(tzinfo=tz)
 
@@ -119,7 +136,9 @@ def replace_timezone(dt: datetime.datetime, tz: Optional[datetime.tzinfo]) -> da
     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.
+    .. warning::
+
+        This changes the instant to which this dt refers.
 
     >>> from pytz import UTC
     >>> d = now_pacific()
@@ -156,10 +175,13 @@ def replace_timezone(dt: datetime.datetime, tz: Optional[datetime.tzinfo]) -> da
 
 
 def replace_time_timezone(t: datetime.time, tz: datetime.tzinfo) -> datetime.time:
-    """
-    Replaces the timezone on a datetime.time directly without performing
-    any translation.  Note that, as above, this will change the instant
-    to which the time refers.
+    """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()
@@ -168,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)
 
@@ -196,7 +217,7 @@ def translate_timezone(dt: datetime.datetime, tz: datetime.tzinfo) -> datetime.d
 
 def now() -> datetime.datetime:
     """
-    What time is it?  Returned as a timezone naive datetime.
+    What time is it?  Result is a timezone naive datetime.
     """
     return datetime.datetime.now()
 
@@ -280,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)
@@ -295,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)
@@ -307,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)