add ignore option to get_version and add shortcut

dunamai/__init__.py

@@ -978,6 +978,7 @@ def get_version(
     first_choice: Callable[[], Optional[Version]] = None,
     third_choice: Callable[[], Optional[Version]] = None,
     fallback: Version = Version("0.0.0"),
+    ignore: Union[str, Version] = "0",
 ) -> Version:
     """
     Check pkg_resources info or a fallback function to determine the version.
@@ -990,29 +991,62 @@ def get_version(
     :param third_choice: Callback to determine a version if the installed
         package cannot be found by name.
     :param fallback: If no other matches found, use this version.
+    :param ignore: Ignore this version if it is found.
     """
+    if isinstance(ignore, str):
+        ignore = Version(ignore)
+
     if first_choice:
         first_ver = first_choice()
-        if first_ver:
+        if first_ver and first_ver != ignore:
             return first_ver
 
     try:
         import importlib.metadata as ilm
     except ImportError:
         import importlib_metadata as ilm  # type: ignore
     try:
-        return Version(ilm.version(name))
+        ilm_version = Version(ilm.version(name))
+        if ilm_version != ignore:
+            return ilm_version
     except ilm.PackageNotFoundError:
         pass
 
     if third_choice:
         third_ver = third_choice()
-        if third_ver:
+        if third_ver and third_ver != ignore:
             return third_ver
 
     return fallback
 
 
+def get_version_from_vcs(
+    name: str,
+    first_choice: Callable[[], Optional[Version]] = None,
+    third_choice: Callable[[], Optional[Version]] = Version.from_any_vcs,
+    fallback: Version = Version("0.0.0"),
+    ignore: Union[str, Version] = "0",
+) -> Version:
+    """
+    A shortcut call on the `get_version` function with the third choice any vcs.
+
+    Check pkg_resources info or a fallback function to determine the version.
+    This is intended as a convenient default for setting your `__version__` if
+    you do not want to include a generated version statically during packaging.
+
+    :param name: Installed package name.
+    :param first_choice: Callback to determine a version before checking
+        to see if the named package is installed.
+    :param third_choice: Callback to determine a version if the installed
+        package cannot be found by name.
+    :param fallback: If no other matches found, use this version.
+    :param ignore: Ignore this version if it is found.
+    """
+    return get_version(
+        name, first_choice=first_choice, third_choice=third_choice, fallback=fallback, ignore=ignore
+    )
+
+
 def serialize_pep440(
     base: str,
     stage: str = None,

tests/unit/test_dunamai.py

@@ -442,6 +442,47 @@ def test__get_version__fallback() -> None:
     assert get_version("dunamai_nonexistent_test") == Version("0.0.0")
 
 
+def test__get_version__from_name__ignore() -> None:
+    assert get_version(
+        "dunamai", ignore=pkg_resources.get_distribution("dunamai").version, fallback=Version("2")
+    ) == Version("2")
+    assert get_version(
+        "dunamai",
+        ignore=Version(pkg_resources.get_distribution("dunamai").version),
+        fallback=Version("2"),
+    ) == Version("2")
+
+
+def test__get_version__first_choice__ignore() -> None:
+    assert get_version(
+        "dunamai_nonexistent_test",
+        first_choice=lambda: Version("1"),
+        ignore="1",
+        fallback=Version("2"),
+    ) == Version("2")
+    assert get_version(
+        "dunamai_nonexistent_test",
+        first_choice=lambda: Version("1"),
+        ignore=Version("1"),
+        fallback=Version("2"),
+    ) == Version("2")
+
+
+def test__get_version__third_choice__ignore() -> None:
+    assert get_version(
+        "dunamai_nonexistent_test",
+        third_choice=lambda: Version("3"),
+        ignore="3",
+        fallback=Version("2"),
+    ) == Version("2")
+    assert get_version(
+        "dunamai_nonexistent_test",
+        third_choice=lambda: Version("3"),
+        ignore=Version("3"),
+        fallback=Version("2"),
+    ) == Version("2")
+
+
 def test__version__from_any_vcs(tmp_path) -> None:
     with chdir(tmp_path):
         with pytest.raises(RuntimeError):