diff --git a/google/api_core/__init__.py b/google/api_core/__init__.py index b80ea372..4f6c9bd3 100644 --- a/google/api_core/__init__.py +++ b/google/api_core/__init__.py @@ -17,6 +17,18 @@ This package contains common code and utilities used by Google client libraries. """ +from google.api_core import _python_package_support +from google.api_core import _python_version_support from google.api_core import version as api_core_version __version__ = api_core_version.__version__ + +# TODO: Until dependent artifacts require this version of +# google.api_core, the functionality below must be made available +# manually in those artifacts. + +check_python_version = _python_version_support.check_python_version +check_python_version(package="google.api_core") + +check_dependency_versions = _python_package_support.check_dependency_versions +check_dependency_versions("google.api_core") diff --git a/google/api_core/_python_package_support.py b/google/api_core/_python_package_support.py new file mode 100644 index 00000000..9cf86baf --- /dev/null +++ b/google/api_core/_python_package_support.py @@ -0,0 +1,153 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Code to check versions of dependencies used by Google Cloud Client Libraries.""" + +import logging +import sys +from typing import Optional +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 + + +def get_dependency_version(dependency_name: str) -> Optional[PackagingVersion]: + """Get the parsed version of an installed package dependency. + + This function checks for an installed package and returns its version + as a `packaging.version.Version` object for safe comparison. It handles + both modern (Python 3.8+) and legacy (Python 3.7) environments. + + Args: + 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. + """ + try: + if sys.version_info >= (3, 8): + from importlib import metadata + + version_string = metadata.version(dependency_name) + return parse_version(version_string) + + # TODO: Remove this code path once we drop support for Python 3.7 + else: + # Use pkg_resources, which is part of setuptools. + import pkg_resources + + version_string = pkg_resources.get_distribution(dependency_name).version + return parse_version(version_string) + + except Exception: + return None + + +def warn_deprecation_for_versions_less_than( + dependent_import_package: str, + dependency_import_package: str, + next_supported_version: str, + message_template: Optional[str] = None, +): + """Issue any needed deprecation warnings for `dependency_import_package`. + + 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_import_package` if + `dependency_import_package` is somehow pinned to a version lower + than `next_supported_version`. + + Args: + 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_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_import_package + or not dependency_import_package + or not next_supported_version + ): + return + 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_packages} depends on + {dependency_packages}, currently installed at version + {version_used.__str__}. Future updates to + {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_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_packages}. + """ + ) + logging.warning( + message_template.format( + dependent_import_package=dependent_import_package, + dependency_import_package=dependency_import_package, + dependency_packages=dependency_packages, + dependent_packages=dependent_packages, + next_supported_version=next_supported_version, + version_used=version_used, + ) + ) + + +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_import_package: The distribution name of the calling package, whose + dependencies we're checking. + + """ + warn_deprecation_for_versions_less_than( + dependent_import_package, "google.protobuf", "4.25.8" + ) diff --git a/google/api_core/_python_version_support.py b/google/api_core/_python_version_support.py new file mode 100644 index 00000000..f7d2d565 --- /dev/null +++ b/google/api_core/_python_version_support.py @@ -0,0 +1,228 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Code to check Python versions supported by Google Cloud Client Libraries.""" + +import datetime +import enum +import logging +import sys +import textwrap +from typing import Any, NamedTuple, Optional, Dict, Tuple + + +class PythonVersionStatus(enum.Enum): + """Represent the support status of a Python version.""" + + PYTHON_VERSION_UNSUPPORTED = "PYTHON_VERSION_UNSUPPORTED" + PYTHON_VERSION_EOL = "PYTHON_VERSION_EOL" + PYTHON_VERSION_DEPRECATED = "PYTHON_VERSION_DEPRECATED" + PYTHON_VERSION_SUPPORTED = "PYTHON_VERSION_SUPPORTED" + + +class VersionInfo(NamedTuple): + """Hold release and support date information for a Python version.""" + + python_beta: Optional[datetime.date] + python_start: datetime.date + python_eol: datetime.date + gapic_start: Optional[datetime.date] = None # unused + gapic_deprecation: Optional[datetime.date] = None + gapic_end: Optional[datetime.date] = None + dep_unpatchable_cve: Optional[datetime.date] = None # unused + + +PYTHON_VERSION_INFO: Dict[Tuple[int, int], VersionInfo] = { + # Refer to https://devguide.python.org/versions/ and the PEPs linked therefrom. + (3, 7): VersionInfo( + python_beta=None, + python_start=datetime.date(2018, 6, 27), + python_eol=datetime.date(2023, 6, 27), + ), + (3, 8): VersionInfo( + python_beta=None, + python_start=datetime.date(2019, 10, 14), + python_eol=datetime.date(2024, 10, 7), + ), + (3, 9): VersionInfo( + python_beta=datetime.date(2020, 5, 18), + python_start=datetime.date(2020, 10, 5), + python_eol=datetime.date(2025, 10, 5), # TODO: specify day when announced + ), + (3, 10): VersionInfo( + python_beta=datetime.date(2021, 5, 3), + python_start=datetime.date(2021, 10, 4), + python_eol=datetime.date(2026, 10, 4), # TODO: specify day when announced + ), + (3, 11): VersionInfo( + python_beta=datetime.date(2022, 5, 8), + python_start=datetime.date(2022, 10, 24), + python_eol=datetime.date(2027, 10, 24), # TODO: specify day when announced + ), + (3, 12): VersionInfo( + python_beta=datetime.date(2023, 5, 22), + python_start=datetime.date(2023, 10, 2), + python_eol=datetime.date(2028, 10, 2), # TODO: specify day when announced + ), + (3, 13): VersionInfo( + python_beta=datetime.date(2024, 5, 8), + python_start=datetime.date(2024, 10, 7), + python_eol=datetime.date(2029, 10, 7), # TODO: specify day when announced + ), + (3, 14): VersionInfo( + python_beta=datetime.date(2025, 5, 7), + python_start=datetime.date(2025, 10, 7), + python_eol=datetime.date(2030, 10, 7), # TODO: specify day when announced + ), +} + +LOWEST_TRACKED_VERSION = min(PYTHON_VERSION_INFO.keys()) +FAKE_PAST_DATE = datetime.date(1970, 1, 1) +FAKE_FUTURE_DATE = datetime.date(9000, 1, 1) +DEPRECATION_WARNING_PERIOD = datetime.timedelta(days=365) +EOL_GRACE_PERIOD = datetime.timedelta(weeks=1) + + +def _flatten_message(text: str) -> str: + """Dedent a multi-line string and flattens it into a single line.""" + 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) -> Tuple[str, Any]: + """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: str = "this package", today: Optional[datetime.date] = None +) -> PythonVersionStatus: + """Check the running Python version and issue a support warning if needed. + + Args: + today: The date to check against. Defaults to the current date. + + Returns: + 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) + py_version_str = f"{python_version.major}.{python_version.minor}" + + version_info = PYTHON_VERSION_INFO.get(version_tuple) + + if not version_info: + if version_tuple < LOWEST_TRACKED_VERSION: + version_info = VersionInfo( + python_beta=FAKE_PAST_DATE, + python_start=FAKE_PAST_DATE, + python_eol=FAKE_PAST_DATE, + ) + else: + version_info = VersionInfo( + python_beta=FAKE_FUTURE_DATE, + python_start=FAKE_FUTURE_DATE, + python_eol=FAKE_FUTURE_DATE, + ) + + 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) + + def min_python(date: datetime.date) -> str: + """Find the minimum supported Python version for a given date.""" + for version, info in sorted(PYTHON_VERSION_INFO.items()): + if info.python_start <= date < info.python_eol: + return f"{version[0]}.{version[1]}" + return "at a supported version" + + 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_label}. Please 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_label} + with critical bug fixes on a best-effort basis, but not + with any other fixes or features. Please 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_label} when + it reaches its end of life ({version_info.python_eol}). Please + upgrade to the latest Python version, or at + least Python {min_python(version_info.python_eol)}, and + then update {package_label}. + """ + ) + logging.warning(message) + return PythonVersionStatus.PYTHON_VERSION_DEPRECATED + + return PythonVersionStatus.PYTHON_VERSION_SUPPORTED diff --git a/tests/asyncio/test_operation_async.py b/tests/asyncio/test_operation_async.py index 9d9fb5d2..939be094 100644 --- a/tests/asyncio/test_operation_async.py +++ b/tests/asyncio/test_operation_async.py @@ -84,7 +84,6 @@ async def test_constructor(): assert await future.running() -@pytest.mark.asyncio def test_metadata(): expected_metadata = struct_pb2.Struct() future, _, _ = make_operation_future( @@ -177,7 +176,6 @@ async def test_unexpected_result(unused_sleep): assert "Unexpected state" in "{!r}".format(exception) -@pytest.mark.asyncio def test_from_gapic(): operation_proto = make_operation_proto(done=True) operations_client = mock.create_autospec( diff --git a/tests/unit/gapic/test_method.py b/tests/unit/gapic/test_method.py index 8896429c..3b31244b 100644 --- a/tests/unit/gapic/test_method.py +++ b/tests/unit/gapic/test_method.py @@ -177,16 +177,19 @@ def test_wrap_method_with_overriding_retry_timeout_compression(unused_sleep): method, default_retry, default_timeout, default_compression ) + specified_timeout = 22.0 result = wrapped_method( retry=retry.Retry(retry.if_exception_type(exceptions.NotFound)), - timeout=timeout.ConstantTimeout(22), + timeout=timeout.ConstantTimeout(specified_timeout), compression=grpc.Compression.Deflate, ) assert result == 42 assert method.call_count == 2 method.assert_called_with( - timeout=22, compression=grpc.Compression.Deflate, metadata=mock.ANY + timeout=specified_timeout, + compression=grpc.Compression.Deflate, + metadata=mock.ANY, ) @@ -198,10 +201,11 @@ def test_wrap_method_with_overriding_timeout_as_a_number(): method, default_retry, default_timeout ) - result = wrapped_method(timeout=22) + specified_timeout = 22.0 + result = wrapped_method(timeout=specified_timeout) assert result == 42 - method.assert_called_once_with(timeout=22, metadata=mock.ANY) + method.assert_called_once_with(timeout=specified_timeout, metadata=mock.ANY) def test_wrap_method_with_call(): diff --git a/tests/unit/test_python_package_support.py b/tests/unit/test_python_package_support.py new file mode 100644 index 00000000..b037a9d5 --- /dev/null +++ b/tests/unit/test_python_package_support.py @@ -0,0 +1,116 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import sys +from unittest.mock import patch, MagicMock + +import pytest +from packaging.version import parse as parse_version + +from google.api_core._python_package_support import ( + get_dependency_version, + warn_deprecation_for_versions_less_than, +) + + +@pytest.mark.skipif(sys.version_info < (3, 8), reason="requires python3.8 or higher") +@patch("importlib.metadata.version") +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") + 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 + + +@pytest.mark.skipif(sys.version_info >= (3, 8), reason="requires python3.7") +@patch("pkg_resources.get_distribution") +def test_get_dependency_version_py37(mock_get_distribution): + """Test get_dependency_version on Python 3.7.""" + 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") + 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 + + +@patch("google.api_core._python_package_support._get_distribution_and_import_packages") +@patch("google.api_core._python_package_support.get_dependency_version") +@patch("google.api_core._python_package_support.logging.warning") +def test_warn_deprecation_for_versions_less_than( + mock_log_warning, mock_get_version, mock_get_packages +): + """Test the deprecation warning logic.""" + # Mock the helper function to return predictable package strings + mock_get_packages.side_effect = [ + ("dep-package (dep.package)", "dep-package"), + ("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") + warn_deprecation_for_versions_less_than("my.package", "dep.package", "2.0.0") + mock_log_warning.assert_called_once() + assert ( + "DEPRECATION: Package my-package (my.package) depends on dep-package (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_packages.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") + mock_log_warning.assert_not_called() + + # Case 3: Installed version is greater than required, should not warn. + mock_log_warning.reset_mock() + mock_get_packages.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") + mock_log_warning.assert_not_called() + + # Case 4: Dependency not found, should not warn. + mock_log_warning.reset_mock() + mock_get_packages.reset_mock() + mock_get_version.return_value = None + warn_deprecation_for_versions_less_than("my.package", "dep.package", "2.0.0") + mock_log_warning.assert_not_called() + + # Case 5: Custom message template. + mock_log_warning.reset_mock() + mock_get_packages.reset_mock() + mock_get_packages.side_effect = [ + ("dep-package (dep.package)", "dep-package"), + ("my-package (my.package)", "my-package"), + ] + mock_get_version.return_value = parse_version("1.0.0") + template = "Custom warning for {dependency_packages} used by {dependent_packages}." + warn_deprecation_for_versions_less_than( + "my.package", "dep.package", "2.0.0", message_template=template + ) + mock_log_warning.assert_called_once() + assert ( + "Custom warning for dep-package (dep.package) used by my-package (my.package)." + in mock_log_warning.call_args[0][0] + ) diff --git a/tests/unit/test_python_version_support.py b/tests/unit/test_python_version_support.py new file mode 100644 index 00000000..9f609744 --- /dev/null +++ b/tests/unit/test_python_version_support.py @@ -0,0 +1,236 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import pytest +import datetime +import textwrap +from collections import namedtuple + +from unittest.mock import patch + +# Code to be tested +from google.api_core._python_version_support import ( + check_python_version, + PythonVersionStatus, + PYTHON_VERSION_INFO, +) + +# Helper object for mocking sys.version_info +VersionInfoMock = namedtuple("VersionInfoMock", ["major", "minor"]) + + +def _create_failure_message( + expected, result, py_version, date, gapic_dep, py_eol, eol_warn, gapic_end +): + """Create a detailed failure message for a test.""" + return textwrap.dedent( + f""" + --- Test Failed --- + Expected status: {expected.name} + Received status: {result.name} + --------------------- + Context: + - Mocked Python Version: {py_version} + - Mocked Today's Date: {date} + Calculated Dates: + - gapic_deprecation: {gapic_dep} + - python_eol: {py_eol} + - eol_warning_starts: {eol_warn} + - gapic_end: {gapic_end} + """ + ) + + +def generate_tracked_version_test_cases(): + """ + Yields test parameters for all tracked versions and boundary conditions. + """ + for version_tuple, version_info in PYTHON_VERSION_INFO.items(): + py_version_str = f"{version_tuple[0]}.{version_tuple[1]}" + gapic_dep = version_info.gapic_deprecation or ( + version_info.python_eol - datetime.timedelta(days=365) + ) + gapic_end = version_info.gapic_end or ( + version_info.python_eol + datetime.timedelta(weeks=1) + ) + eol_warning_starts = version_info.python_eol + datetime.timedelta(weeks=1) + + test_cases = { + "supported_before_deprecation_date": { + "date": gapic_dep - datetime.timedelta(days=1), + "expected": PythonVersionStatus.PYTHON_VERSION_SUPPORTED, + }, + "deprecated_on_deprecation_date": { + "date": gapic_dep, + "expected": PythonVersionStatus.PYTHON_VERSION_DEPRECATED, + }, + "deprecated_on_eol_date": { + "date": version_info.python_eol, + "expected": PythonVersionStatus.PYTHON_VERSION_DEPRECATED, + }, + "deprecated_before_eol_warning_starts": { + "date": eol_warning_starts - datetime.timedelta(days=1), + "expected": PythonVersionStatus.PYTHON_VERSION_DEPRECATED, + }, + "eol_on_eol_warning_date": { + "date": eol_warning_starts, + "expected": PythonVersionStatus.PYTHON_VERSION_EOL, + }, + "eol_on_gapic_end_date": { + "date": gapic_end, + "expected": PythonVersionStatus.PYTHON_VERSION_EOL, + }, + "unsupported_after_gapic_end_date": { + "date": gapic_end + datetime.timedelta(days=1), + "expected": PythonVersionStatus.PYTHON_VERSION_UNSUPPORTED, + }, + } + + for name, params in test_cases.items(): + yield pytest.param( + version_tuple, + params["date"], + params["expected"], + gapic_dep, + gapic_end, + eol_warning_starts, + id=f"{py_version_str}-{name}", + ) + + +@pytest.mark.parametrize( + "version_tuple, mock_date, expected_status, gapic_dep, gapic_end, eol_warning_starts", + generate_tracked_version_test_cases(), +) +def test_all_tracked_versions_and_date_scenarios( + version_tuple, mock_date, expected_status, gapic_dep, gapic_end, eol_warning_starts +): + """Test all outcomes for each tracked version using parametrization.""" + mock_py_v = VersionInfoMock(major=version_tuple[0], minor=version_tuple[1]) + + with patch("google.api_core._python_version_support.sys.version_info", mock_py_v): + with patch( + "google.api_core._python_version_support.logging.warning" + ) as mock_log: + result = check_python_version(today=mock_date) + + if ( + (result != expected_status) + or (result != PythonVersionStatus.PYTHON_VERSION_SUPPORTED) + and mock_log.call_count != 1 + ): + py_version_str = f"{version_tuple[0]}.{version_tuple[1]}" + version_info = PYTHON_VERSION_INFO[version_tuple] + + fail_msg = _create_failure_message( + expected_status, + result, + py_version_str, + mock_date, + gapic_dep, + version_info.python_eol, + eol_warning_starts, + gapic_end, + ) + pytest.fail(fail_msg, pytrace=False) + + +def test_override_gapic_end_only(): + """Test behavior when only gapic_end is manually overridden.""" + version_tuple = (3, 9) + original_info = PYTHON_VERSION_INFO[version_tuple] + mock_py_version = VersionInfoMock(major=version_tuple[0], minor=version_tuple[1]) + + custom_gapic_end = original_info.python_eol + datetime.timedelta(days=212) + overridden_info = original_info._replace(gapic_end=custom_gapic_end) + + with patch( + "google.api_core._python_version_support.sys.version_info", mock_py_version + ): + with patch.dict( + "google.api_core._python_version_support.PYTHON_VERSION_INFO", + {version_tuple: overridden_info}, + ): + result_at_boundary = check_python_version(today=custom_gapic_end) + assert result_at_boundary == PythonVersionStatus.PYTHON_VERSION_EOL + + result_after_boundary = check_python_version( + today=custom_gapic_end + datetime.timedelta(days=1) + ) + assert ( + result_after_boundary == PythonVersionStatus.PYTHON_VERSION_UNSUPPORTED + ) + + +def test_override_gapic_deprecation_only(): + """Test behavior when only gapic_deprecation is manually overridden.""" + version_tuple = (3, 9) + original_info = PYTHON_VERSION_INFO[version_tuple] + mock_py_version = VersionInfoMock(major=version_tuple[0], minor=version_tuple[1]) + + custom_gapic_dep = original_info.python_eol - datetime.timedelta(days=120) + overridden_info = original_info._replace(gapic_deprecation=custom_gapic_dep) + + with patch( + "google.api_core._python_version_support.sys.version_info", mock_py_version + ): + with patch.dict( + "google.api_core._python_version_support.PYTHON_VERSION_INFO", + {version_tuple: overridden_info}, + ): + result_before_boundary = check_python_version( + today=custom_gapic_dep - datetime.timedelta(days=1) + ) + assert ( + result_before_boundary == PythonVersionStatus.PYTHON_VERSION_SUPPORTED + ) + + result_at_boundary = check_python_version(today=custom_gapic_dep) + assert result_at_boundary == PythonVersionStatus.PYTHON_VERSION_DEPRECATED + + +def test_untracked_older_version_is_unsupported(): + """Test that an old, untracked version is unsupported and logs.""" + mock_py_version = VersionInfoMock(major=3, minor=6) + + with patch( + "google.api_core._python_version_support.sys.version_info", mock_py_version + ): + with patch( + "google.api_core._python_version_support.logging.warning" + ) as mock_log: + mock_date = datetime.date(2025, 1, 15) + result = check_python_version(today=mock_date) + + assert result == PythonVersionStatus.PYTHON_VERSION_UNSUPPORTED + mock_log.assert_called_once() + call_args = mock_log.call_args[0][0] + assert "non-supported" in call_args + + +def test_untracked_newer_version_is_supported(): + """Test that a new, untracked version is supported and does not log.""" + mock_py_version = VersionInfoMock(major=4, minor=0) + + with patch( + "google.api_core._python_version_support.sys.version_info", mock_py_version + ): + with patch( + "google.api_core._python_version_support.logging.warning" + ) as mock_log: + mock_date = datetime.date(2025, 1, 15) + result = check_python_version(today=mock_date) + + assert result == PythonVersionStatus.PYTHON_VERSION_SUPPORTED + mock_log.assert_not_called()