Update warning code to only require import package names

We automatically get the distribution package names under the hood.

google/api_core/__init__.py

@@ -24,7 +24,7 @@
 __version__ = api_core_version.__version__
 
 check_python_version = _python_version_support.check_python_version
-check_python_version(package="package google-api-core (google.api_core)")
+check_python_version(package="google.api_core")
 
 check_dependency_versions = _python_package_support.check_dependency_versions
-check_dependency_versions("google-api-core (google.api_core)")
+check_dependency_versions("google.api_core")

google/api_core/_python_package_support.py

@@ -17,7 +17,10 @@
 import logging
 import sys
 from typing import Optional
-from ._python_version_support import _flatten_message
+from ._python_version_support import (
+    _flatten_message,
+    _get_distribution_and_import_packages,
+)
 
 # It is a good practice to alias the Version class for clarity in type hints.
 from packaging.version import parse as parse_version, Version as PackagingVersion
@@ -57,73 +60,90 @@ def get_dependency_version(dependency_name: str) -> Optional[PackagingVersion]:
 
 
 def warn_deprecation_for_versions_less_than(
-    dependent_package: str,
-    dependency_name: str,
+    dependent_import_package: str,
+    dependency_import_package: str,
     next_supported_version: str,
     message_template: Optional[str] = None,
 ):
-    """Issue a deprecation warning for outdated versions of `dependency_name`.
+    """Issue any needed deprecation warnings for `dependency_import_package`.
 
-    If `dependency_name` is installed at a version less than
+    If `dependency_import_package` is installed at a version less than
     `next_supported_versions`, this issues a warning using either a
     default `message_template` or one provided by the user. The
     default `message_template informs users that they will not receive
-    future updates `dependent_package` if `dependency_name` is somehow
-    pinned to a version lower than `next_supported_version`.
+    future updates `dependent_import_package` if
+    `dependency_import_package` is somehow pinned to a version lower
+    than `next_supported_version`.
 
     Args:
-      dependent_package: The distribution name of the package that
-        needs `dependency_name`.
-      dependency_name: The distribution name oft he dependency to check.
+      dependent_import_package: The import name of the package that
+        needs `dependency_import_package`.
+      dependency_import_package: The import name of the dependency to check.
       next_supported_version: The version number below which a deprecation
         warning will be logged.
       message_template: A custom default message template to replace
         the default. This `message_template` is treated as an
         f-string, where the following variables are defined:
-        `dependency_name`, `dependent_package`,
-        `next_supported_version`, and `version_used`.
+        `dependency_import_package`, `dependent_import_package`;
+        `dependency_packages` and `dependent_packages`, which contain 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.
+
     """
-    if not dependent_package or not dependency_name or not next_supported_version:
+    if (
+        not dependent_import_package
+        or not dependency_import_package
+        or not next_supported_version
+    ):
         return
-    version_used = get_dependency_version(dependency_name)
+    version_used = get_dependency_version(dependency_import_package)
     if not version_used:
         return
     if version_used < parse_version(next_supported_version):
+        (
+            dependency_packages,
+            dependency_distribution_package,
+        ) = _get_distribution_and_import_packages(dependency_import_package)
+        (
+            dependent_packages,
+            dependent_distribution_package,
+        ) = _get_distribution_and_import_packages(dependent_import_package)
         message_template = message_template or _flatten_message(
-            """DEPRECATION: Package {dependent_package} depends on
-            {dependency_name}, currently installed at version
+            """DEPRECATION: Package {dependent_packages} depends on
+            {dependency_packages}, currently installed at version
             {version_used.__str__}. Future updates to
-            {dependent_package} will require {dependency_name} at
+            {dependent_packages} will require {dependency_packages} at
             version {next_supported_version} or higher. Please ensure
             that either (a) your Python environment doesn't pin the
-            version of {dependency_name}, so that updates to
-            {dependent_package} can require the higher version, or (b)
-            you manually update your Python environment to use at
+            version of {dependency_packages}, so that updates to
+            {dependent_packages} can require the higher version, or
+            (b) you manually update your Python environment to use at
             least version {next_supported_version} of
-            {dependency_name}."""
+            {dependency_packages}."""
         )
         logging.warning(
             message_template.format(
-                dependent_package=dependent_package,
-                dependency_name=dependency_name,
+                dependent_import_package=dependent_import_package,
+                dependency_import_package=dependency_import_package,
                 next_supported_version=next_supported_version,
                 version_used=version_used,
             )
         )
 
 
-def check_dependency_versions(dependent_package: str):
+def check_dependency_versions(dependent_import_package: str):
     """Bundle checks for all package dependencies.
 
     This function can be called by all dependents of google.api_core,
     to emit needed deprecation warnings for any of their
     dependencies. The dependencies to check should be updated here.
 
     Args:
-      dependent_package: The distribution name of the calling package, whose
+      dependent_import_package: The distribution name of the calling package, whose
         dependencies we're checking.
 
     """
     warn_deprecation_for_versions_less_than(
-        dependent_package, "protobuf (google.protobuf)", "4.25.8"
+        dependent_import_package, "google.protobuf", "4.25.8"
     )

google/api_core/_python_version_support.py

@@ -99,6 +99,44 @@ def _flatten_message(text: str) -> str:
     return textwrap.dedent(text).strip().replace("\n", " ")
 
 
+# TODO: Remove once we no longer support Python3.7
+if sys.version_info < (3, 8):
+
+    def _get_pypi_package_name(module_name):
+        """Determine the PyPI package name for a given module name."""
+        return None
+
+else:
+    from importlib import metadata
+
+    def _get_pypi_package_name(module_name):
+        """Determine the PyPI package name for a given module name."""
+        try:
+            # Get the mapping of modules to distributions
+            module_to_distributions = metadata.packages_distributions()
+
+            # Check if the module is found in the mapping
+            if module_name in module_to_distributions:
+                # The value is a list of distribution names, take the first one
+                return module_to_distributions[module_name][0]
+            else:
+                return None  # Module not found in the mapping
+        except Exception as e:
+            print(f"An error occurred: {e}")
+            return None
+
+
+def _get_distribution_and_import_packages(import_package: str) -> Optional[str]:
+    """Return a pretty string with distribution & import package names."""
+    distribution_package = _get_pypi_package_name(import_package)
+    dependency_distribution_and_import_packages = (
+        f"package {distribution_package} ({import_package})"
+        if distribution_package
+        else import_package
+    )
+    return dependency_distribution_and_import_packages, distribution_package
+
+
 def check_python_version(
     package: Optional[str] = "this package", today: Optional[datetime.date] = None
 ) -> PythonVersionStatus:
@@ -111,6 +149,7 @@ def check_python_version(
         The support status of the current Python version.
     """
     today = today or datetime.date.today()
+    package_label, _ = _get_distribution_and_import_packages(package)
 
     python_version = sys.version_info
     version_tuple = (python_version.major, python_version.minor)
@@ -135,9 +174,7 @@ def check_python_version(
     gapic_deprecation = version_info.gapic_deprecation or (
         version_info.python_eol - DEPRECATION_WARNING_PERIOD
     )
-    gapic_end = version_info.gapic_end or (
-        version_info.python_eol + EOL_GRACE_PERIOD
-    )
+    gapic_end = version_info.gapic_end or (version_info.python_eol + EOL_GRACE_PERIOD)
 
     def min_python(date: datetime.date) -> str:
         """Find the minimum supported Python version for a given date."""
@@ -148,42 +185,38 @@ def min_python(date: datetime.date) -> str:
 
     if gapic_end < today:
         message = _flatten_message(
-            f"""
-            You are using a non-supported Python version ({py_version_str}).
-            Google will not post any further updates to {package}. We suggest
-            you upgrade to the latest Python version, or at least Python
-            {min_python(today)}, and then update {package}.
-            """
+            f"""You are using a non-supported Python version
+            ({py_version_str}).  Google will not post any further
+            updates to {package_label}. We suggest you upgrade to the
+            latest Python version, or at least Python
+            {min_python(today)}, and then update {package_label}. """
         )
         logging.warning(message)
         return PythonVersionStatus.PYTHON_VERSION_UNSUPPORTED
 
     eol_date = version_info.python_eol + EOL_GRACE_PERIOD
     if eol_date <= today <= gapic_end:
         message = _flatten_message(
-            f"""
-            You are using a Python version ({py_version_str}) past its end
-            of life. Google will update {package} with critical
-            bug fixes on a best-effort basis, but not with any other fixes or
-            features. We suggest you upgrade to the latest Python version,
-            or at least Python {min_python(today)}, and then update {package}.
-            """
+            f"""You are using a Python version ({py_version_str})
+            past its end of life. Google will update {package_label}
+            with critical bug fixes on a best-effort basis, but not
+            with any other fixes or features. We suggest you upgrade
+            to the latest Python version, or at least Python
+            {min_python(today)}, and then update {package_label}."""
         )
         logging.warning(message)
         return PythonVersionStatus.PYTHON_VERSION_EOL
 
     if gapic_deprecation <= today <= gapic_end:
         message = _flatten_message(
-            f"""
-            You are using a Python version ({py_version_str}),
-            which Google will stop supporting in {package} when it
-            reaches its end of life ({version_info.python_eol}). We
+            f"""You are using a Python version ({py_version_str}),
+            which Google will stop supporting in {package_label} when
+            it reaches its end of life ({version_info.python_eol}). We
             suggest you upgrade to the latest Python version, or at
             least Python {min_python(version_info.python_eol)}, and
-            then update {package}.
-            """
+            then update {package_label}."""
         )
         logging.warning(message)
         return PythonVersionStatus.PYTHON_VERSION_DEPRECATED
 
-    return PythonVersionStatus.PYTHON_VERSION_SUPPORTED
+    return PythonVersionStatus.PYTHON_VERSION_SUPPORTED

tests/unit/test_python_package_support.py

@@ -48,7 +48,9 @@ def test_get_dependency_version_py37(mock_get_distribution):
     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
+    mock_get_distribution.side_effect = (
+        Exception  # pkg_resources has its own exception types
+    )
     assert get_dependency_version("not-a-package") is None
 
 
@@ -58,34 +60,29 @@ def test_warn_deprecation_for_versions_less_than(mock_log_warning, mock_get_vers
     """Test the deprecation warning logic."""
     # Case 1: Installed version is less than required, should warn.
     mock_get_version.return_value = parse_version("1.0.0")
-    warn_deprecation_for_versions_less_than(
-        "my-package", "dep-package", "2.0.0"
-    )
+    warn_deprecation_for_versions_less_than("my-package", "dep-package", "2.0.0")
     mock_log_warning.assert_called_once()
-    assert "DEPRECATION: Package my-package depends on dep-package" in mock_log_warning.call_args[0][0]
+    assert (
+        "DEPRECATION: Package my-package depends on dep-package"
+        in mock_log_warning.call_args[0][0]
+    )
 
     # Case 2: Installed version is equal to required, should not warn.
     mock_log_warning.reset_mock()
     mock_get_version.return_value = parse_version("2.0.0")
-    warn_deprecation_for_versions_less_than(
-        "my-package", "dep-package", "2.0.0"
-    )
+    warn_deprecation_for_versions_less_than("my-package", "dep-package", "2.0.0")
     mock_log_warning.assert_not_called()
 
     # Case 3: Installed version is greater than required, should not warn.
     mock_log_warning.reset_mock()
     mock_get_version.return_value = parse_version("3.0.0")
-    warn_deprecation_for_versions_less_than(
-        "my-package", "dep-package", "2.0.0"
-    )
+    warn_deprecation_for_versions_less_than("my-package", "dep-package", "2.0.0")
     mock_log_warning.assert_not_called()
 
     # Case 4: Dependency not found, should not warn.
     mock_log_warning.reset_mock()
     mock_get_version.return_value = None
-    warn_deprecation_for_versions_less_than(
-        "my-package", "dep-package", "2.0.0"
-    )
+    warn_deprecation_for_versions_less_than("my-package", "dep-package", "2.0.0")
     mock_log_warning.assert_not_called()
 
     # Case 5: Custom message template.
@@ -96,4 +93,7 @@ def test_warn_deprecation_for_versions_less_than(mock_log_warning, mock_get_vers
         "my-package", "dep-package", "2.0.0", message_template=template
     )
     mock_log_warning.assert_called_once()
-    assert "Custom warning for dep-package used by my-package." in mock_log_warning.call_args[0][0]
+    assert (
+        "Custom warning for dep-package used by my-package."
+        in mock_log_warning.call_args[0][0]
+    )