Add an alias that makes dateutil optional. (#999)

* Add an alias that makes dateutil optional.

* fix test

* remove fallback to dateutil by default

* flake8 + doc

* doc

Author: Wauplin

Makefile

@@ -1,7 +1,7 @@
 .PHONY: quality style test
 
 
-check_dirs := tests src
+check_dirs := tests src setup.py
 
 
 quality:

src/huggingface_hub/community.py

@@ -9,7 +9,7 @@
 from datetime import datetime
 from typing import List, Optional
 
-from dateutil.parser import parse as parse_datetime
+from .utils import parse_datetime
 
 
 if sys.version_info >= (3, 8):

src/huggingface_hub/hf_api.py

@@ -22,7 +22,6 @@
 from urllib.parse import quote
 
 import requests
-from dateutil.parser import parse as parse_datetime
 from requests.exceptions import HTTPError
 
 from ._commit_api import (
@@ -51,7 +50,7 @@
     REPO_TYPES_URL_PREFIXES,
     SPACES_SDK_TYPES,
 )
-from .utils import filter_repo_objects, logging
+from .utils import filter_repo_objects, logging, parse_datetime
 from .utils._deprecation import _deprecate_positional_args
 from .utils._errors import (
     _raise_convert_bad_request,

src/huggingface_hub/utils/__init__.py

@@ -16,6 +16,7 @@
 # limitations under the License
 
 from . import tqdm as _tqdm  # _tqdm is the module
+from ._datetime import parse_datetime
 from ._errors import (
     EntryNotFoundError,
     LocalEntryNotFoundError,

src/huggingface_hub/utils/_datetime.py

@@ -0,0 +1,65 @@
+# coding=utf-8
+# Copyright 2022-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains utilities to handle datetimes in Huggingface Hub."""
+from datetime import datetime, timezone
+
+
+# Local machine offset compared to UTC
+# Taken from https://stackoverflow.com/a/3168394.
+UTC_OFFSET = datetime.now(timezone.utc).astimezone().utcoffset()
+
+
+def parse_datetime(date_string: str) -> datetime:
+    """
+    Parses a date_string returned from the server to a datetime object.
+
+    This parser is a weak-parser is the sense that it handles only a single format of
+    date_string. It is expected that the server format will never change. The
+    implementation depends only on the standard lib to avoid an external dependency
+    (python-dateutil). See full discussion about this decision on PR:
+    https://github.com/huggingface/huggingface_hub/pull/999.
+
+    Usage:
+        ```py
+        > parse_datetime('2022-08-19T07:19:38.123Z')
+        datetime.datetime(2022, 8, 19, 7, 19, 38, 123000, tzinfo=timezone.utc)
+        ```
+
+    Args:
+        date_string (`str`):
+            A string representing a datetime returned by the Hub server.
+            String is expected to follow '%Y-%m-%dT%H:%M:%S.%fZ' pattern.
+
+    Returns:
+        A python datetime object.
+
+    Raises:
+        :class:`ValueError`:
+            If `date_string` cannot be parsed.
+    """
+    try:
+        # Datetime ending with a Z means "UTC". Here we parse the date as local machine
+        # timezone and then move it to the appropriate UTC timezone.
+        # See https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)
+        # Taken from https://stackoverflow.com/a/3168394.
+
+        dt = datetime.strptime(date_string, "%Y-%m-%dT%H:%M:%S.%fZ")
+        dt += UTC_OFFSET  # By default, datetime is not timezoned -> move to UTC time
+        return dt.astimezone(timezone.utc)  # Set explicit timezone
+    except ValueError as e:
+        raise ValueError(
+            f"Cannot parse '{date_string}' as a datetime. Date string is expected to"
+            " follow '%Y-%m-%dT%H:%M:%S.%fZ' pattern."
+        ) from e

tests/test_utils_datetime.py

@@ -0,0 +1,32 @@
+import unittest
+from datetime import datetime, timezone
+
+import pytest
+
+from huggingface_hub.utils import parse_datetime
+
+
+class TestDatetimeUtils(unittest.TestCase):
+    def test_parse_datetime(self):
+        """Test `parse_datetime` works correctly on datetimes returned by server."""
+        self.assertEqual(
+            parse_datetime("2022-08-19T07:19:38.123Z"),
+            datetime(2022, 8, 19, 7, 19, 38, 123000, tzinfo=timezone.utc),
+        )
+
+        with pytest.raises(
+            ValueError, match=r".*Cannot parse '2022-08-19T07:19:38' as a datetime.*"
+        ):
+            parse_datetime("2022-08-19T07:19:38")
+
+        with pytest.raises(
+            ValueError,
+            match=r".*Cannot parse '2022-08-19T07:19:38.123' as a datetime.*",
+        ):
+            parse_datetime("2022-08-19T07:19:38.123")
+
+        with pytest.raises(
+            ValueError,
+            match=r".*Cannot parse '2022-08-19 07:19:38.123Z\+6:00' as a datetime.*",
+        ):
+            parse_datetime("2022-08-19 07:19:38.123Z+6:00")