fix: return tuple of version tuple and version string, fix tests

Author: vchudnov-g

google/api_core/_python_package_support.py

@@ -16,7 +16,7 @@
 
 import warnings
 import sys
-from typing import Optional
+from typing import Optional, Tuple
 from ._python_version_support import (
     _flatten_message,
     _get_distribution_and_import_packages,
@@ -25,7 +25,9 @@
 from packaging.version import parse as parse_version, Version as PackagingVersion
 
 
-def get_dependency_version(dependency_name: str) -> Optional[PackagingVersion]:
+def get_dependency_version(
+    dependency_name: str,
+) -> Tuple[Optional[PackagingVersion], str]:
     """Get the parsed version of an installed package dependency.
 
     This function checks for an installed package and returns its version
@@ -36,8 +38,9 @@ def get_dependency_version(dependency_name: str) -> Optional[PackagingVersion]:
         dependency_name: The distribution name of the package (e.g., 'requests').
 
     Returns:
-        A `packaging.version.Version` object, or `None` if the package
-        is not found or another error occurs during version discovery.
+        A tuple containing the `packaging.version.Version` object and the
+        version string, or `(None, '--')` if the package is not found or
+        another error occurs during version discovery.
     """
     try:
         if sys.version_info >= (3, 8):
@@ -90,9 +93,9 @@ def warn_deprecation_for_versions_less_than(
         `dependent_package` , which contain the import packages, the
         distribution packages, and pretty string with both the
         distribution and import packages for the dependency and the
-        dependent, respectively; and `next_supported_version` and
-        `version_used`, which refer to supported and currently-used
-        versions of the dependency.
+        dependent, respectively; and `next_supported_version`,
+        `version_used`, and `version_used_string`, which refer to supported
+        and currently-used versions of the dependency.
 
     """
     if (
@@ -138,7 +141,9 @@ def warn_deprecation_for_versions_less_than(
                 dependent_package=dependent_package,
                 next_supported_version=next_supported_version,
                 version_used=version_used,
-            )
+                version_used_string=version_used_string
+            ),
+            FutureWarning
         )
 
 

google/api_core/_python_version_support.py

@@ -195,7 +195,7 @@ def min_python(date: datetime.date) -> str:
             {min_python(today)}, and then update {package_label}.
             """
         )
-        warnings.warn(message)
+        warnings.warn(message, FutureWarning)
         return PythonVersionStatus.PYTHON_VERSION_UNSUPPORTED
 
     eol_date = version_info.python_eol + EOL_GRACE_PERIOD
@@ -210,7 +210,7 @@ def min_python(date: datetime.date) -> str:
             {min_python(today)}, and then update {package_label}.
             """
         )
-        warnings.warn(message)
+        warnings.warn(message, FutureWarning)
         return PythonVersionStatus.PYTHON_VERSION_EOL
 
     if gapic_deprecation <= today <= gapic_end:
@@ -224,7 +224,7 @@ def min_python(date: datetime.date) -> str:
             then update {package_label}.
             """
         )
-        warnings.warn(message)
+        warnings.warn(message, FutureWarning)
         return PythonVersionStatus.PYTHON_VERSION_DEPRECATED
 
     return PythonVersionStatus.PYTHON_VERSION_SUPPORTED

tests/unit/test_python_package_support.py

@@ -32,12 +32,12 @@
 def test_get_dependency_version_py38_plus(mock_version):
     """Test get_dependency_version on Python 3.8+."""
     mock_version.return_value = "1.2.3"
-    assert get_dependency_version("some-package") == parse_version("1.2.3")
+    assert get_dependency_version("some-package") == (parse_version("1.2.3"), "1.2.3")
     mock_version.assert_called_once_with("some-package")
 
     # Test package not found
     mock_version.side_effect = ImportError
-    assert get_dependency_version("not-a-package") is None
+    assert get_dependency_version("not-a-package") == (None, "--")
 
 
 # TODO(https://github.com/googleapis/python-api-core/issues/835): Remove
@@ -49,14 +49,14 @@ def test_get_dependency_version_py37(mock_get_distribution):
     mock_dist = MagicMock()
     mock_dist.version = "4.5.6"
     mock_get_distribution.return_value = mock_dist
-    assert get_dependency_version("another-package") == parse_version("4.5.6")
+    assert get_dependency_version("another-package") == (parse_version("4.5.6"), "4.5.6")
     mock_get_distribution.assert_called_once_with("another-package")
 
     # Test package not found
     mock_get_distribution.side_effect = (
         Exception  # pkg_resources has its own exception types
     )
-    assert get_dependency_version("not-a-package") is None
+    assert get_dependency_version("not-a-package") == (None, "--")
 
 
 @patch("google.api_core._python_package_support._get_distribution_and_import_packages")
@@ -71,9 +71,8 @@ def test_warn_deprecation_for_versions_less_than(
         ("my-package (my.package)", "my-package"),
     ]
 
-    # Case 1: Installed version is less than required, should warn.
-    mock_get_version.return_value = parse_version("1.0.0")
-    with pytest.warns(UserWarning) as record:
+    mock_get_version.return_value = (parse_version("1.0.0"), "1.0.0")
+    with pytest.warns(FutureWarning) as record:
         warn_deprecation_for_versions_less_than("my.package", "dep.package", "2.0.0")
     assert len(record) == 1
     assert (
@@ -87,17 +86,17 @@ def test_warn_deprecation_for_versions_less_than(
 
         # Case 2: Installed version is equal to required, should not warn.
         mock_get_packages.reset_mock()
-        mock_get_version.return_value = parse_version("2.0.0")
+        mock_get_version.return_value = (parse_version("2.0.0"), "2.0.0")
         warn_deprecation_for_versions_less_than("my.package", "dep.package", "2.0.0")
 
         # Case 3: Installed version is greater than required, should not warn.
         mock_get_packages.reset_mock()
-        mock_get_version.return_value = parse_version("3.0.0")
+        mock_get_version.return_value = (parse_version("3.0.0"), "3.0.0")
         warn_deprecation_for_versions_less_than("my.package", "dep.package", "2.0.0")
 
         # Case 4: Dependency not found, should not warn.
         mock_get_packages.reset_mock()
-        mock_get_version.return_value = None
+        mock_get_version.return_value = (None, "--")
         warn_deprecation_for_versions_less_than("my.package", "dep.package", "2.0.0")
 
         # Assert that no warnings were recorded
@@ -109,9 +108,9 @@ def test_warn_deprecation_for_versions_less_than(
         ("dep-package (dep.package)", "dep-package"),
         ("my-package (my.package)", "my-package"),
     ]
-    mock_get_version.return_value = parse_version("1.0.0")
+    mock_get_version.return_value = (parse_version("1.0.0"), "1.0.0")
     template = "Custom warning for {dependency_package} used by {dependent_package}."
-    with pytest.warns(UserWarning) as record:
+    with pytest.warns(FutureWarning) as record:
         warn_deprecation_for_versions_less_than(
             "my.package", "dep.package", "2.0.0", message_template=template
         )

tests/unit/test_python_version_support.py

@@ -129,7 +129,7 @@ def test_all_tracked_versions_and_date_scenarios(
                 assert len(w) == 0
         # All other statuses should issue a warning
         else:
-            with pytest.warns(UserWarning) as record:
+            with pytest.warns(FutureWarning) as record:
                 result = check_python_version(today=mock_date)
             assert len(record) == 1
 
@@ -216,7 +216,7 @@ def test_untracked_older_version_is_unsupported():
     with patch(
         "google.api_core._python_version_support.sys.version_info", mock_py_version
     ):
-        with pytest.warns(UserWarning) as record:
+        with pytest.warns(FutureWarning) as record:
             mock_date = datetime.date(2025, 1, 15)
             result = check_python_version(today=mock_date)