[dt] rename & reorganize functions

gallery_dl/dt.py

@@ -16,29 +16,18 @@ EPOCH = datetime(1970, 1, 1)
 SECOND = timedelta(0, 1)
 
 
-def parse_datetime(date_string, format="%Y-%m-%dT%H:%M:%S%z", utcoffset=0):
-    """Create a datetime object by parsing 'date_string'"""
-    try:
-        d = datetime.strptime(date_string, format)
-        o = d.utcoffset()
-        if o is not None:
-            # convert to naive UTC
-            d = d.replace(tzinfo=None, microsecond=0) - o
-        else:
-            if d.microsecond:
-                d = d.replace(microsecond=0)
-            if utcoffset:
-                # apply manual UTC offset
-                d += timedelta(0, utcoffset * -3600)
-        return d
-    except (TypeError, IndexError, KeyError):
-        return None
-    except (ValueError, OverflowError):
-        return date_string
+def normalize(dt):
+    #  if (o := dt.utcoffset()) is not None:
+    #      return dt.replace(tzinfo=None, microsecond=0) - o
+    if dt.tzinfo is not None:
+        return dt.astimezone(timezone.utc).replace(tzinfo=None, microsecond=0)
+    if dt.microsecond:
+        return dt.replace(microsecond=0)
+    return dt
 
 
-def to_datetime(value):
-    """Convert 'value' to a datetime object"""
+def convert(value):
+    """Convert 'value' to a naive UTC datetime object"""
     if not value:
         return EPOCH
 
@@ -50,59 +39,77 @@ def to_datetime(value):
             if value[-1] == "Z":
                 # compat for Python < 3.11
                 value = value[:-1]
-            dt = datetime.fromisoformat(value)
-            if dt.tzinfo is None:
-                if dt.microsecond:
-                    dt = dt.replace(microsecond=0)
-            else:
-                # convert to naive UTC
-                dt = dt.astimezone(timezone.utc).replace(
-                    microsecond=0, tzinfo=None)
-            return dt
+            return normalize(datetime.fromisoformat(value))
         except Exception:
             pass
 
-    return parse_timestamp(value, EPOCH)
+    return parse_ts(value)
 
 
-def datetime_to_timestamp(dt):
+def parse(dt_string, format):
+    """Parse 'dt_string' according to 'format'"""
+    try:
+        return normalize(datetime.strptime(dt_string, format))
+    except Exception:
+        return EPOCH
+
+
+if sys.hexversion < 0x30c0000:
+    # Python <= 3.11
+    def parse_iso(dt_string):
+        """Parse 'dt_string' as ISO 8601 value"""
+        try:
+            if dt_string[-1] == "Z":
+                # compat for Python < 3.11
+                dt_string = dt_string[:-1]
+            return normalize(datetime.fromisoformat(dt_string))
+        except Exception:
+            return EPOCH
+
+    def parse_compat(dt_string, format):
+        """Parse 'dt_string' as ISO 8601 value using 'format'"""
+        return parse(dt_string, format)
+
+    from_ts = datetime.utcfromtimestamp
+    now = datetime.utcnow
+
+else:
+    # Python >= 3.12
+    def parse_iso(dt_string):
+        """Parse 'dt_string' as ISO 8601 value"""
+        try:
+            return normalize(datetime.fromisoformat(dt_string))
+        except Exception:
+            return EPOCH
+
+    def parse_compat(dt_string, format):
+        """Parse 'dt_string' as ISO 8601 value"""
+        return parse_iso(dt_string)
+
+    def from_ts(ts=None):
+        """Convert Unix timestamp to naive UTC datetime"""
+        Y, m, d, H, M, S, _, _, _ = time.gmtime(ts)
+        return datetime(Y, m, d, H, M, S)
+
+    now = from_ts
+
+
+def parse_ts(ts, default=EPOCH):
+    """Create a datetime object from a Unix timestamp"""
+    try:
+        return from_ts(int(ts))
+    except Exception:
+        return default
+
+
+def to_ts(dt):
     """Convert naive UTC datetime to Unix timestamp"""
     return (dt - EPOCH) / SECOND
 
 
-def datetime_to_timestamp_string(dt):
+def to_ts_string(dt):
     """Convert naive UTC datetime to Unix timestamp string"""
     try:
         return str((dt - EPOCH) // SECOND)
     except Exception:
         return ""
-
-
-if sys.hexversion < 0x30c0000:
-    # Python <= 3.11
-    datetime_utcfromtimestamp = datetime.utcfromtimestamp
-    datetime_utcnow = datetime.utcnow
-    datetime_from_timestamp = datetime_utcfromtimestamp
-
-    def parse_timestamp(ts, default=None):
-        """Create a datetime object from a Unix timestamp"""
-        try:
-            return datetime_utcfromtimestamp(int(ts))
-        except Exception:
-            return default
-else:
-    # Python >= 3.12
-    def datetime_from_timestamp(ts=None):
-        """Convert Unix timestamp to naive UTC datetime"""
-        Y, m, d, H, M, S, _, _, _ = time.gmtime(ts)
-        return datetime(Y, m, d, H, M, S)
-
-    def parse_timestamp(ts, default=None):
-        """Create a datetime object from a Unix timestamp"""
-        try:
-            return datetime_from_timestamp(int(ts))
-        except Exception:
-            return default
-
-    datetime_utcfromtimestamp = datetime_from_timestamp
-    datetime_utcnow = datetime_from_timestamp