Document how to create subclass from VersionInfo

tomschr · tomschr · commit 37ce07b41c5b · 2020-10-17T00:10:45.000+02:00
Related to issue #276
diff --git a/conftest.py b/conftest.py
@@ -5,9 +5,11 @@
 sys.path.insert(0, "docs")
 
 from coerce import coerce  # noqa:E402
+from semverwithvprefix import SemVerWithVPrefix
 
 
 @pytest.fixture(autouse=True)
 def add_semver(doctest_namespace):
     doctest_namespace["semver"] = semver
     doctest_namespace["coerce"] = coerce
+    doctest_namespace["SemVerWithVPrefix"] = SemVerWithVPrefix
diff --git a/docs/semverwithvprefix.py b/docs/semverwithvprefix.py
@@ -0,0 +1,31 @@
+from semver import VersionInfo
+
+
+class SemVerWithVPrefix(VersionInfo):
+    """
+    A subclass of VersionInfo which allows a "v" prefix
+    """
+
+    @classmethod
+    def parse(cls, version):
+        """
+        Parse version string to a VersionInfo instance.
+
+        :param version: version string with "v" or "V" prefix
+        :type version: str
+        :raises ValueError: when version does not start with "v" or "V"
+        :return: a new instance
+        :rtype: :class:`SemVerWithVPrefix`
+        """
+        if not version[0] in ("v", "V"):
+            raise ValueError(
+                "{v!r}: not a valid semantic version tag. Must start with 'v' or 'V'".format(
+                    v=version
+                )
+            )
+        self = super(SemVerWithVPrefix, cls).parse(version[1:])
+        return self
+
+    def __str__(self):
+        # Reconstruct the tag
+        return "v" + super(SemVerWithVPrefix, self).__str__()
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -530,6 +530,8 @@ The "old way" with :func:`semver.max_ver` or :func:`semver.min_ver` is still ava
     '1.0.0'
 
 
+.. _sec_dealing_with_invalid_versions:
+
 Dealing with Invalid Versions
 -----------------------------
 
@@ -708,3 +710,39 @@ the following methods:
    For further details, see the section
    `Overriding the default filter <https://docs.python.org/3/library/warnings.html#overriding-the-default-filter>`_
    of the Python documentation.
+
+
+.. _sec_creating_subclasses_from_versioninfo:
+
+Creating Subclasses from VersionInfo
+------------------------------------
+
+If you do not like creating functions to modify the behavior of semver
+(as shown in section :ref:`sec_dealing_with_invalid_versions`), you can
+also create a subclass of the :class:`VersionInfo` class.
+
+For example, if you want to output a "v" prefix before a version,
+but the other behavior is the same, use the following code:
+
+.. literalinclude:: semverwithvprefix.py
+   :language: python
+   :lines: 4-
+
+
+The derived class :class:`SemVerWithVPrefix` can be used like
+the original class:
+
+.. code-block:: python
+
+     >>> v1 = SemVerWithVPrefix.parse("v1.2.3")
+     >>> assert str(v1) == "v1.2.3"
+     >>> print(v1)
+     v1.2.3
+     >>> v2 = SemVerWithVPrefix.parse("v2.3.4")
+     >>> v2 > v1
+     True
+     >>> bad = SemVerWithVPrefix.parse("1.2.4")
+     Traceback (most recent call last):
+     ...
+     ValueError: '1.2.4': not a valid semantic version tag. Must start with 'v' or 'V'
+
diff --git a/setup.cfg b/setup.cfg
@@ -21,3 +21,5 @@ exclude =
     __pycache__,
     build,
     dist
+    docs
+    conftest.py
