Add `Version.truncate()`.

This simplifies computing neighbouring versions.

3 files changed, 51 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 7a7128c..8ad05dc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -8,6 +8,7 @@ ChangeLog
 
     * Allow creation of a ``Version`` directly from parsed components, as keyword arguments
       (``Version(major=1, minor=2, patch=3)``)
+    * Add ``Version.truncate()`` to build a truncated copy of a ``Version``
 
 *Removed:*
 
diff --git a/docs/reference.rst b/docs/reference.rst
index 58aa320..f9b4aed 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -181,6 +181,20 @@ Representing a version (the Version class)
                      :attr:`prerelease` component: it's the smallest "pure"
                      patch version strictly greater than that version.
 
+    .. method:: truncate(self, level='patch']):
+
+        Returns a similar level, but truncated at the provided level.
+
+        .. code-block:: pycon
+
+            >>> Version('1.0.2-rc1+b43.24').truncate()
+            Version('1.0.2')
+            >>> Version('1.0.2-rc1+b43.24').truncate('minor')
+            Version('1.0.0')
+            >>> Version('1.0.2-rc1+b43.24').truncate('prerelease')
+            Version('1.0.2-rc1')
+
+
     .. method:: __iter__(self)
 
         Iterates over the version components (:attr:`major`, :attr:`minor`,
diff --git a/semantic_version/base.py b/semantic_version/base.py
index 48fdfbf..8251efa 100644
--- a/semantic_version/base.py
+++ b/semantic_version/base.py
@@ -165,6 +165,42 @@ class Version:
                 partial=self.partial,
             )
 
+    def truncate(self, level='patch'):
+        """Return a new Version object, truncated up to the selected level."""
+        if level == 'build':
+            return self
+        elif level == 'prerelease':
+            return Version(
+                major=self.major,
+                minor=self.minor,
+                patch=self.patch,
+                prerelease=self.prerelease,
+                partial=self.partial,
+            )
+        elif level == 'patch':
+            return Version(
+                major=self.major,
+                minor=self.minor,
+                patch=self.patch,
+                partial=self.partial,
+            )
+        elif level == 'minor':
+            return Version(
+                major=self.major,
+                minor=self.minor,
+                patch=None if self.partial else 0,
+                partial=self.partial,
+            )
+        elif level == 'major':
+            return Version(
+                major=self.major,
+                minor=None if self.partial else 0,
+                patch=None if self.partial else 0,
+                partial=self.partial,
+            )
+        else:
+            raise ValueError("Invalid truncation level `%s`." % level)
+
     @classmethod
     def coerce(cls, version_string, partial=False):
         """Coerce an arbitrary version string into a semver-compatible one.