Datetime versioning scheme

requirements.txt

@@ -4,3 +4,4 @@ pyparsing==2.4.7
 semantic-version==2.8.5
 semver==2.13.0
 isort==5.10.1
+python-dateutil==2.9.0.post0

setup.cfg

@@ -63,6 +63,7 @@ install_requires =
     packaging
     semantic-version
     semver
+    python-dateutil
 
 
 [options.packages.find]

src/univers/datetime.py

@@ -0,0 +1,51 @@
+#
+# SPDX-License-Identifier: MIT
+#
+# Visit https://aboutcode.org and https://github.com/aboutcode-org/univers for support and download.
+
+import re
+
+from dateutil.parser import isoparse
+
+
+class DatetimeVersion:
+    """
+    datetime version.
+
+    The timestamp must be RFC3339-compliant, i.e., a subset of ISO8601, where the date AND time are always specified. Therefore, we can use dateutil's ISO-parser but have to check for compliance with the RFC format first via a regex.
+    """
+
+    VERSION_PATTERN = re.compile(
+        r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$"
+    )
+
+    def __init__(self, version):
+        if not self.is_valid(version):
+            raise InvalidVersionError(version)
+
+        version = str(version).strip()
+        self.original = version
+        self.parsed_stamp = isoparse(version)
+
+    def __eq__(self, other):
+        return self.parsed_stamp == other.parsed_stamp
+
+    def __lt__(self, other):
+        return self.parsed_stamp < other.parsed_stamp
+
+    def __le__(self, other):
+        return self.parsed_stamp <= other.parsed_stamp
+
+    def __gt__(self, other):
+        return self.parsed_stamp > other.parsed_stamp
+
+    def __ge__(self, other):
+        return self.parsed_stamp >= other.parsed_stamp
+
+    @classmethod
+    def is_valid(cls, string):
+        return cls.VERSION_PATTERN.match(string)
+
+
+class InvalidVersionError(ValueError):
+    pass

src/univers/version_range.py

@@ -973,6 +973,11 @@ class IntdotVersionRange(VersionRange):
     version_class = versions.IntdotVersion
 
 
+class DatetimeVersionRange(VersionRange):
+    scheme = "datetime"
+    version_class = versions.DatetimeVersion
+
+
 class GenericVersionRange(VersionRange):
     scheme = "generic"
     version_class = versions.SemverVersion
@@ -1446,6 +1451,7 @@ def build_range_from_snyk_advisory_string(scheme: str, string: Union[str, List])
     "all": AllVersionRange,
     "none": NoneVersionRange,
     "intdot": IntdotVersionRange,
+    "datetime": DatetimeVersionRange,
 }
 
 PURL_TYPE_BY_GITLAB_SCHEME = {

src/univers/versions.py

@@ -9,6 +9,7 @@
 from packaging import version as packaging_version
 
 from univers import arch
+from univers import datetime
 from univers import debian
 from univers import gem
 from univers import gentoo
@@ -156,6 +157,16 @@ def is_valid(cls, string):
         return intdot.IntdotVersion.is_valid(string)
 
 
+class DatetimeVersion(Version):
+    @classmethod
+    def is_valid(cls, string):
+        return datetime.DatetimeVersion.is_valid(string)
+
+    @classmethod
+    def build_value(self, string):
+        return datetime.DatetimeVersion(string)
+
+
 class GenericVersion(Version):
     @classmethod
     def is_valid(cls, string):
@@ -726,4 +737,5 @@ def bump(self, index):
     LegacyOpensslVersion,
     AlpineLinuxVersion,
     IntdotVersion,
+    DatetimeVersion,
 ]

tests/test_version_range.py

@@ -13,6 +13,7 @@
 from univers.version_constraint import VersionConstraint
 from univers.version_range import PURL_TYPE_BY_GITLAB_SCHEME
 from univers.version_range import RANGE_CLASS_BY_SCHEMES
+from univers.version_range import DatetimeVersionRange
 from univers.version_range import IntdotVersionRange
 from univers.version_range import InvalidVersionRange
 from univers.version_range import MattermostVersionRange
@@ -21,6 +22,7 @@
 from univers.version_range import VersionRange
 from univers.version_range import build_range_from_snyk_advisory_string
 from univers.version_range import from_gitlab_native
+from univers.versions import DatetimeVersion
 from univers.versions import IntdotVersion
 from univers.versions import OpensslVersion
 from univers.versions import PypiVersion
@@ -366,3 +368,37 @@ def test_version_range_intdot():
     assert IntdotVersion("1.3.3alpha") in intdot_range
     assert IntdotVersion("1.2.2.pre") not in intdot_range
     assert IntdotVersion("1010.23.234203.0") in IntdotVersionRange.from_string("vers:intdot/*")
+
+
+def test_version_range_datetime():
+    assert DatetimeVersion("2021-05-05T01:02:03.1234Z") == DatetimeVersion(
+        "2021-05-05T01:02:03.1234Z"
+    )
+    assert DatetimeVersion("2021-05-05T01:02:03.1234Z") != DatetimeVersion(
+        "2022-05-05T01:02:03.1234Z"
+    )
+    assert DatetimeVersion("2021-05-05T01:02:03.1234Z") <= DatetimeVersion(
+        "2022-05-05T01:02:03.1234Z"
+    )
+    assert DatetimeVersion("2021-05-05T01:02:03.1234Z") >= DatetimeVersion(
+        "2020-05-05T01:02:03.1234Z"
+    )
+    assert DatetimeVersion("2000-01-01T01:02:03.1234Z") in DatetimeVersionRange.from_string(
+        "vers:datetime/*"
+    )
+    assert DatetimeVersion("2021-05-05T01:02:03Z") in DatetimeVersionRange.from_string(
+        "vers:datetime/>2021-01-01T01:02:03.1234Z|<2022-01-01T01:02:03.1234Z"
+    )
+    datetime_constraints = DatetimeVersionRange(
+        constraints=(
+            VersionConstraint(
+                comparator=">", version=DatetimeVersion(string="2000-01-01T01:02:03Z")
+            ),
+            VersionConstraint(
+                comparator="<", version=DatetimeVersion(string="2002-01-01T01:02:03Z")
+            ),
+        )
+    )
+    assert DatetimeVersion("2001-01-01T01:02:03Z") in datetime_constraints
+    with pytest.raises(Exception):
+        VersionRange.from_string("vers:datetime/2025-08-25")

tests/test_versions.py

@@ -8,6 +8,7 @@
 from univers.versions import AlpineLinuxVersion
 from univers.versions import ArchLinuxVersion
 from univers.versions import ComposerVersion
+from univers.versions import DatetimeVersion
 from univers.versions import DebianVersion
 from univers.versions import EnhancedSemanticVersion
 from univers.versions import GentooVersion
@@ -230,3 +231,12 @@ def test_intdot_version():
     assert IntdotVersion("1.2.3.4.6-pre") <= IntdotVersion("2.2.3.4.5.pre")
     assert IntdotVersion("1.2.3.4.6-pre") <= IntdotVersion("2.2.3.4.5-10")
     assert IntdotVersion("1.2.3.4.6-pre") <= IntdotVersion("2.2.3.4.5-10")
+
+
+def test_datetime_version():
+    assert DatetimeVersion("2023-10-28T18:30:00Z") == DatetimeVersion("2023-10-28T18:30:00Z")
+    assert DatetimeVersion("2023-01-11T10:10:10Z") > DatetimeVersion("2023-01-10T10:10:10Z")
+    assert DatetimeVersion("2022-10-28T18:30:00Z") < DatetimeVersion("2023-10-28T18:30:00Z")
+    assert DatetimeVersion("2022-10-28T18:30:00Z") <= DatetimeVersion("2023-10-28T18:30:00Z")
+    assert DatetimeVersion("2024-10-28T18:30:00Z") > DatetimeVersion("2023-10-28T18:30:00Z")
+    assert DatetimeVersion("2023-10-28T19:30:00+01:00") == DatetimeVersion("2023-10-28T18:30:00Z")