Ensure equal versions have equal hashes (#283)

sbrudenell · web-flow · commit db55f27cb7c3 · 2020-10-20T19:44:53.000+02:00
* Version equality means for semver, that `major`, `minor`, `patch`, and `prerelease`
  parts are equal in both versions you compare. The `build` part is ignored.
* Improve docs to describe version comparison
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -467,6 +467,32 @@ functions that leverage this capability; builtins including, but not limited to:
 (for examples, see :ref:`sec_max_min`) and :func:`sorted`.
 
 
+Determining Version Equality
+----------------------------
+
+Version equality means for semver, that major, minor, patch, and prerelease
+parts are equal in both versions you compare. The build part is ignored.
+For example::
+
+    >>> v = semver.VersionInfo.parse("1.2.3-rc4+1e4664d")
+    >>> v == "1.2.3-rc4+dedbeef"
+    True
+
+This also applies when a :class:`semver.VersionInfo` is a member of a set, or a
+dictionary key::
+
+    >>> d = {}
+    >>> v1 = semver.VersionInfo.parse("1.2.3-rc4+1e4664d")
+    >>> v2 = semver.VersionInfo.parse("1.2.3-rc4+dedbeef")
+    >>> d[v1] = 1
+    >>> d[v2]
+    1
+    >>> s = set()
+    >>> s.add(v1)
+    >>> v2 in s
+    True
+
+
 
 Comparing Versions through an Expression
 ----------------------------------------
diff --git a/semver.py b/semver.py
@@ -641,7 +641,7 @@ def __str__(self):
         return version
 
     def __hash__(self):
-        return hash(self.to_tuple())
+        return hash(self.to_tuple()[:4])
 
     def finalize_version(self):
         """
diff --git a/test_semver.py b/test_semver.py
@@ -693,6 +693,20 @@ def test_parse_version_info_str_hash():
     d[v] = ""  # to ensure that VersionInfo are hashable
 
 
+def test_equal_versions_have_equal_hashes():
+    v1 = parse_version_info("1.2.3-alpha.1.2+build.11.e0f985a")
+    v2 = parse_version_info("1.2.3-alpha.1.2+build.22.a589f0e")
+    assert v1 == v2
+    assert hash(v1) == hash(v2)
+    d = {}
+    d[v1] = 1
+    d[v2] = 2
+    assert d[v1] == 2
+    s = set()
+    s.add(v1)
+    assert v2 in s
+
+
 def test_parse_method_for_version_info():
     s_version = "1.2.3-alpha.1.2+build.11.e0f985a"
     v = VersionInfo.parse(s_version)
