Better docstring and variable names

Author: xispa

src/senaite/core/api/dtime.py

@@ -439,16 +439,24 @@ def to_localized_time(dt, long_format=None, time_only=None,
     return time_str
 
 
-def get_relative_delta(from_dtime, to_dtime=None):
-    """Returns the relative delta between two datetimes. If to_dtime is None,
-    compares current datetime with from_dtime
+def get_relative_delta(dt1, dt2=None):
+    """Calculates the relative delta between two dates or datetimes
+
+    If `dt2` is None, the current datetime is used.
+
+    :param dt1: the first date/time to compare
+    :type dt1: str/date/datetime/DateTime
+    :param dt2: the second date/time to compare
+    :type dt2: str/date/datetime/DateTime
+    :returns: interval of time (e.g. `relativedelta(hours=+3)`)
+    :rtype: dateutil.relativedelta
     """
-    if not to_dtime:
-        to_dtime = datetime.now()
+    if not dt2:
+        dt2 = datetime.now()
 
-    from_dtime = to_dt(from_dtime)
-    to_dtime = to_dt(to_dtime)
-    if not all([from_dtime, to_dtime]):
+    dt1 = to_dt(dt1)
+    dt2 = to_dt(dt2)
+    if not all([dt1, dt2]):
         return None
 
     def get_tzinfo(dt, default=pytz.UTC):
@@ -457,19 +465,19 @@ def get_tzinfo(dt, default=pytz.UTC):
         except pytz.UnknownTimeZoneError:
             return default
 
-    naives = [is_timezone_naive(dt) for dt in [from_dtime, to_dtime]]
+    naives = [is_timezone_naive(dt) for dt in [dt1, dt2]]
     if all(naives):
         # Both naive, no need to do anything special
-        return relativedelta(to_dtime, from_dtime)
+        return relativedelta(dt2, dt1)
 
-    elif is_timezone_naive(from_dtime):
+    elif is_timezone_naive(dt1):
         # From date is naive, assume same TZ as the to date
-        tzinfo = get_tzinfo(to_dtime)
-        from_dtime = from_dtime.replace(tzinfo=tzinfo)
+        tzinfo = get_tzinfo(dt2)
+        dt1 = dt1.replace(tzinfo=tzinfo)
 
-    elif is_timezone_naive(to_dtime):
+    elif is_timezone_naive(dt2):
         # To date is naive, assume same TZ as the from date
-        tzinfo = get_tzinfo(from_dtime)
-        to_dtime = to_dtime.replace(tzinfo=tzinfo)
+        tzinfo = get_tzinfo(dt1)
+        dt2 = dt2.replace(tzinfo=tzinfo)
 
-    return relativedelta(to_dtime, from_dtime)
+    return relativedelta(dt2, dt1)

src/senaite/core/tests/doctests/API_datetime.rst

@@ -626,50 +626,50 @@ Relative delta between two dates
 
 We can extract the relative delta between two dates:
 
-    >>> from_dtime = dtime.ansi_to_dt("20230515104405")
-    >>> to_dtime = dtime.ansi_to_dt("20230515114405")
-    >>> dtime.get_relative_delta(from_dtime, to_dtime)
+    >>> dt1 = dtime.ansi_to_dt("20230515104405")
+    >>> dt2 = dtime.ansi_to_dt("20230515114405")
+    >>> dtime.get_relative_delta(dt1, dt2)
     relativedelta(hours=+1)
 
 We can even compare two dates from two different timezones:
 
-    >>> from_dtime_cet = dtime.to_zone(from_dtime, "CET")
-    >>> to_dtime_utc = dtime.to_zone(to_dtime, "UTC")
-    >>> dtime.get_relative_delta(from_dtime_cet, to_dtime_utc)
+    >>> dt1_cet = dtime.to_zone(dt1, "CET")
+    >>> dt2_utc = dtime.to_zone(dt2, "UTC")
+    >>> dtime.get_relative_delta(dt1_cet, dt2_utc)
     relativedelta(hours=+3)
 
-    >>> from_dtime_cet = dtime.to_zone(from_dtime, "CET")
-    >>> to_dtime_pcf = dtime.to_zone(to_dtime, "Pacific/Fiji")
-    >>> dtime.get_relative_delta(from_dtime_cet, to_dtime_pcf)
+    >>> dt1_cet = dtime.to_zone(dt1, "CET")
+    >>> dt2_pcf = dtime.to_zone(dt2, "Pacific/Fiji")
+    >>> dtime.get_relative_delta(dt1_cet, dt2_pcf)
     relativedelta(hours=-9)
 
 If we compare a naive timezone, system uses the timezone of the other date:
 
-    >>> from_dtime_cet = dtime.to_zone(from_dtime, "CET")
-    >>> to_dtime_naive = to_dtime.replace(tzinfo=None)
-    >>> dtime.get_relative_delta(from_dtime_cet, to_dtime_naive)
+    >>> dt1_cet = dtime.to_zone(dt1, "CET")
+    >>> dt2_naive = dt2.replace(tzinfo=None)
+    >>> dtime.get_relative_delta(dt1_cet, dt2_naive)
     relativedelta(hours=+3)
 
 It also works when both are timezone naive:
 
-    >>> from_dtime_naive = from_dtime.replace(tzinfo=None)
-    >>> to_dtime_naive = to_dtime.replace(tzinfo=None)
-    >>> dtime.get_relative_delta(from_dtime_naive, to_dtime_naive)
+    >>> dt1_naive = dt1.replace(tzinfo=None)
+    >>> dt2_naive = dt2.replace(tzinfo=None)
+    >>> dtime.get_relative_delta(dt1_naive, dt2_naive)
     relativedelta(hours=+1)
 
-If we don't specify `to_dtime`, system simply uses current datetime:
+If we don't specify `dt2`, system simply uses current datetime:
 
-    >>> rel_now = dtime.get_relative_delta(from_dtime, datetime.now())
-    >>> rel_wo = dtime.get_relative_delta(from_dtime)
+    >>> rel_now = dtime.get_relative_delta(dt1, datetime.now())
+    >>> rel_wo = dtime.get_relative_delta(dt1)
     >>> rel_now = (rel_now.years, rel_now.months, rel_now.days, rel_now.hours)
     >>> rel_wo = (rel_wo.years, rel_wo.months, rel_wo.days, rel_wo.hours)
     >>> rel_now == rel_wo
     True
 
 We can even compare min and max dates:
 
-    >>> from_dtime = dtime.datetime.min
-    >>> to_dtime = dtime.datetime.max
+    >>> dt1 = dtime.datetime.min
+    >>> dt2 = dtime.datetime.max
     >>> dtime.get_relative_delta(dtime.datetime.min, dtime.datetime.max)
     relativedelta(years=+9998, months=+11, days=+30, hours=+23, minutes=+59, seconds=+59, microseconds=+999999)
 
@@ -698,3 +698,10 @@ Or compare two dates that are exactly the same:
 
     >>> dtime.get_relative_delta("20230515114400", "20230515114400")
     relativedelta()
+
+We can compare dates without time as well:
+
+    >>> from_date = dtime.date(2023, 5, 6)
+    >>> to_date = dtime.date(2023, 5, 7)
+    >>> dtime.get_relative_delta(from_date, to_date)
+    relativedelta(days=+1)