[Feature] Add equal_instant()

Bug: T325248
Change-Id: Ibd771356ae457145b6613822f256aff782b23d62
---
M tests/wikibase_tests.py
M pywikibot/_wbtypes.py
2 files changed, 82 insertions(+), 0 deletions(-)

diff --git a/pywikibot/_wbtypes.py b/pywikibot/_wbtypes.py
index e260de8..857ffa9 100644
--- a/pywikibot/_wbtypes.py
+++ b/pywikibot/_wbtypes.py
@@ -519,6 +519,19 @@
             return self._getSecondsAdjusted() >= other._getSecondsAdjusted()
         return NotImplemented
 
+    def equal_instant(self, other: WbTime) -> bool:
+        """Checks if the two times represent the same instant in time.
+
+        This is different from the equality operator, which will return false
+        for two times that are the same number of UTC seconds, but with
+        different timezone information.
+
+        For example, a time with at 10:00 UTC-5 would return false if checked
+        with == with a time at 15:00 UTC, but would return true with
+        this method.
+        """
+        return self._getSecondsAdjusted() == other._getSecondsAdjusted()
+
     @classmethod
     def fromTimestr(cls,
                     datetimestr: str,
diff --git a/tests/wikibase_tests.py b/tests/wikibase_tests.py
index b8b2399..5d689cc 100755
--- a/tests/wikibase_tests.py
+++ b/tests/wikibase_tests.py
@@ -589,6 +589,65 @@
         t2 = pywikibot.WbTime.fromTimestamp(ts2, timezone=0, site=repo)
         self.assertGreater(t1, t2)
 
+    def test_comparison_timezones_equal(self):
+        """Test when two WbTime's have equal instants but not the same tz."""
+        repo = self.get_repo()
+        ts1 = pywikibot.Timestamp(
+            year=2023, month=12, day=21, hour=13,
+            tzinfo=datetime.timezone(datetime.timedelta(hours=-5)))
+        ts2 = pywikibot.Timestamp(
+            year=2023, month=12, day=21, hour=18,
+            tzinfo=datetime.timezone.utc)
+        self.assertEqual(ts1.timestamp(), ts2.timestamp())
+
+        t1 = pywikibot.WbTime.fromTimestamp(ts1, timezone=-300, site=repo)
+        t2 = pywikibot.WbTime.fromTimestamp(ts2, timezone=0, site=repo)
+        self.assertGreaterEqual(t1, t2)
+        self.assertGreaterEqual(t2, t1)
+        self.assertNotEqual(t1, t2)
+        self.assertNotEqual(t2, t1)
+        # Ignore H205: We specifically want to test the operator
+        self.assertFalse(t1 > t2)  # noqa: H205
+        self.assertFalse(t2 > t1)  # noqa: H205
+        self.assertFalse(t1 < t2)  # noqa: H205
+        self.assertFalse(t2 < t1)  # noqa: H205
+
+    def test_comparison_equal_instant(self):
+        """Test the equal_instant method."""
+        repo = self.get_repo()
+
+        ts1 = pywikibot.Timestamp(
+            year=2023, month=12, day=21, hour=13,
+            tzinfo=datetime.timezone(datetime.timedelta(hours=-5)))
+        ts2 = pywikibot.Timestamp(
+            year=2023, month=12, day=21, hour=18,
+            tzinfo=datetime.timezone.utc)
+        ts3 = pywikibot.Timestamp(
+            year=2023, month=12, day=21, hour=19,
+            tzinfo=datetime.timezone(datetime.timedelta(hours=1)))
+        ts4 = pywikibot.Timestamp(
+            year=2023, month=12, day=21, hour=13,
+            tzinfo=datetime.timezone(datetime.timedelta(hours=-6)))
+
+        self.assertEqual(ts1.timestamp(), ts2.timestamp())
+        self.assertEqual(ts1.timestamp(), ts3.timestamp())
+        self.assertEqual(ts2.timestamp(), ts3.timestamp())
+        self.assertNotEqual(ts1.timestamp(), ts4.timestamp())
+        self.assertNotEqual(ts2.timestamp(), ts4.timestamp())
+        self.assertNotEqual(ts3.timestamp(), ts4.timestamp())
+
+        t1 = pywikibot.WbTime.fromTimestamp(ts1, timezone=-300, site=repo)
+        t2 = pywikibot.WbTime.fromTimestamp(ts2, timezone=0, site=repo)
+        t3 = pywikibot.WbTime.fromTimestamp(ts3, timezone=60, site=repo)
+        t4 = pywikibot.WbTime.fromTimestamp(ts4, timezone=-360, site=repo)
+
+        self.assertTrue(t1.equal_instant(t2))
+        self.assertTrue(t1.equal_instant(t3))
+        self.assertTrue(t2.equal_instant(t3))
+        self.assertFalse(t1.equal_instant(t4))
+        self.assertFalse(t2.equal_instant(t4))
+        self.assertFalse(t3.equal_instant(t4))
+
 
 class TestWbQuantity(WbRepresentationTestCase):
 

