feat: provide and use Python version support check #832

vchudnov-g · 2025-07-29T21:35:47Z

This exports a function check_python_version that dependent packages can use to verify the run-time version on which they are running and warn users when they need to upgrade their Python version. google.api_core also applies this function to itself.

vchudnov-g · 2025-07-29T21:37:29Z

Note that I've also made the Python 3.9 support window as conservative (short) as possible. We can extend it if that's the outcome of our discussions, but it's better to start restrictively and then extend than to start permissively and then contract.

vchudnov-g · 2025-09-24T23:47:53Z

Do not merge yet while I work out the final details of this initial implementation and we get approval on the design.

This checks the runtime versions. Note that the defaults mean - we get the correct behavior for 3.7 and 3.8: both of these became immediately unsupported; - we get the most conservative behavior for 3.9: it becomes immediately deprecated (desired, since Python 3.9 reaches its end of life in 2025-10), and will become unsupported once it reaches its end of life (which is a conservative policy that we may or may not want to relax in a follow-up) Still todo: echo the package name in the warning message.

The warning messages now mor eclosely match what we'we're deploying in the generator for those who don't update their api-core dependency

Sometimes the version we recommend is newer than the next non-deprecated version, so we want to inform users eagerly to reduce their toil

vchudnov-g · 2025-10-10T18:36:48Z

Removing do not merge, as the high-level policy has been approved.

daniel-sanche

Left a lot of comments, but many of them are me learning or leaving little optional suggestions. Let me know what you think

daniel-sanche · 2025-10-10T22:26:23Z

google/api_core/_python_package_support.py

+
+def get_dependency_version(
+ dependency_name: str,
+) -> Tuple[Optional[PackagingVersion], str]:


would a namedtuple be overkill here?

Good idea. Done.

daniel-sanche · 2025-10-10T22:36:14Z

google/api_core/_python_package_support.py

+ return (parse_version(version_string), version_string)
+
+ except Exception:
+ return (None, "--")


This magic "--" seems like it could cause trouble. Could we make the whole output optional if there's an exception, and let callers decide how to deal with an empty value? (or even just raise an exception here for the caller to handle?)

If we do keep the "--", can we make it a constant?

The semantics are conveyed by the first element of the pair, which is None. That's what users can check. If users blindly need a string, -- seems reasonable. We could use an exception, but these warnings are not meant to be blocking, so the exception would be caught and treated as this None would be anyway. IMO, this makes the code both clear and concise, so I'd prefer to keep this unless you feel strongly the other way.

I did make it into a constant.

daniel-sanche · 2025-10-10T22:37:25Z

google/api_core/_python_package_support.py

+
+def warn_deprecation_for_versions_less_than(
+ dependent_import_package: str,
+ dependency_import_package: str,


nit: it might be nice if these variables were more distinct. Maybe target_package?

daniel-sanche · 2025-10-10T22:38:31Z

google/api_core/_python_package_support.py

+ needs `dependency_import_package`.
+ dependency_import_package: The import name of the dependency to check.
+ next_supported_version: The dependency_import_package version number
+ below which a deprecation warning will be logged.


could this be minimum_supported_version? Or am I misunderstanding it?

daniel-sanche · 2025-10-10T22:41:38Z

google/api_core/_python_package_support.py

+ """
+ warn_deprecation_for_versions_less_than(
+ dependent_import_package, "google.protobuf", "4.25.8", recommended_version="6.x"
+ )


Is the idea that we will go back and manually add dependencies here in the future?

If so, this feels a little hidden. Can we read this from a config file, or declare it as a constant at the top of the file or something?

something like:

_DependencyConstraint = namedtuple("_DependencyConstraint", ["package_name", "min_version", "recommended_version"]) DEPENDENCIES = [ _DependencyConstraint("google.protobuf", min_version="4.25.8", recommended_version="6.x") ] def check_dependency_versions(dependent_import_package: str): for package_info in DEPENDENCIES: warn_deprecation_for_versions_less_than( dependent_import_package, package_info.package_name, package_info.min_version, recommended_version=package_info.recommended_version, )

I think what we have is simple and clear, though it does feel hidden just by the fact it's at the bottom of the file.

OK, I implemented the table at the top of the file.

It kind of feels like dependencies should be given as an argument too? Can was assume all sdks will want to check against the same ones?

daniel-sanche · 2025-10-10T23:18:24Z

google/api_core/_python_version_support.py

+ python_beta=None,
+ python_start=datetime.date(2018, 6, 27),
+ python_eol=datetime.date(2023, 6, 27),
+ ),


nit: it seems a little weird that the actual version identifier is held separate from the rest of the information. Maybe they should be combined?

PYTHON_VERSION_INFO: list[VersionInfo] = [ VersionInfo( "3.7", python_beta=None, python_start=datetime.date(2018, 6, 27), python_eol=datetime.date(2023, 6, 27), ), VersionInfo( "3.8", python_beta=None, python_start=datetime.date(2019, 10, 14), python_eol=datetime.date(2024, 10, 7), ), ... ] PYTHON_VERSION_MAP = {parse_version(info.version): info for info in PYTHON_VERSION_INFO}

I could see it either way, but ok, sure, done.

daniel-sanche · 2025-10-10T23:22:31Z

google/api_core/_python_version_support.py

+ python_beta=FAKE_FUTURE_DATE,
+ python_start=FAKE_FUTURE_DATE,
+ python_eol=FAKE_FUTURE_DATE,
+ )


are the fake versions necessary? It would be great if we could refactor to return a different template or something for an unknown Python version

If we do need to use fake ones, they might work better as a constant:

version_info = UNKNOWN_FUTURE_VERSION

Well, the point is that if we don't have the version info but can at least tell whether it's in the past or the future, we do the right thing. So I think these sentinel values are not a bad way to go.

I did make them into constants, and made them private.

daniel-sanche · 2025-10-10T23:26:44Z

google/api_core/_python_version_support.py

+ 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"


This string doesn't seem to fit to me. "... Please upgrade to the latest Python version, or at least Python at a supported version, and then update ..."

I tweaked it. WDYT?

daniel-sanche · 2025-10-10T23:32:17Z

google/api_core/_python_version_support.py

+
+LOWEST_TRACKED_VERSION = min(PYTHON_VERSION_INFO.keys())
+FAKE_PAST_DATE = datetime.date(1970, 1, 1)
+FAKE_FUTURE_DATE = datetime.date(9000, 1, 1)


I'd prefer if we could avoid these fake values, but if we need to, datetime.date.max would probably be a better fit

daniel-sanche · 2025-10-10T23:47:06Z

google/api_core/_python_package_support.py

+ version_string = pkg_resources.get_distribution(dependency_name).version
+ return (parse_version(version_string), version_string)
+
+ except Exception:


Do we know what exceptions to expect? Or does this need to be broad?

Any exception related that comes up trying to find the version. I could try to track them down, but at the end of the day I aim for the function to return without an error, but indicating if the version could not be found. So I lean towards catching broadly, but I'm open to counterarguments.

vchudnov-g

Responded to you comments. I pushed back on some, so feel free free to insist.

vchudnov-g · 2025-10-13T20:19:03Z

google/api_core/_python_package_support.py

+
+def get_dependency_version(
+ dependency_name: str,
+) -> Tuple[Optional[PackagingVersion], str]:


Good idea. Done.

vchudnov-g · 2025-10-13T20:28:14Z

google/api_core/_python_package_support.py

+ return (parse_version(version_string), version_string)
+
+ except Exception:
+ return (None, "--")


The semantics are conveyed by the first element of the pair, which is None. That's what users can check. If users blindly need a string, -- seems reasonable. We could use an exception, but these warnings are not meant to be blocking, so the exception would be caught and treated as this None would be anyway. IMO, this makes the code both clear and concise, so I'd prefer to keep this unless you feel strongly the other way.

I did make it into a constant.

vchudnov-g · 2025-10-13T20:45:31Z

google/api_core/_python_package_support.py

+ needs `dependency_import_package`.
+ dependency_import_package: The import name of the dependency to check.
+ next_supported_version: The dependency_import_package version number
+ below which a deprecation warning will be logged.


vchudnov-g · 2025-10-13T21:00:50Z

google/api_core/_python_package_support.py

+ (
+ dependent_package,
+ dependent_distribution_package,
+ ) = _get_distribution_and_import_packages(dependent_import_package)


They're the correct terms, but they are very similar. I changed the less common term (IMO), dependent, to consumer.

vchudnov-g · 2025-10-13T21:03:16Z

google/api_core/_python_package_support.py

+ least version {next_supported_version} of
+ {dependency_package}.
+ """
+ )


I would prefer not to because the message template is defined and directly used in one place, and it's closely coupled to the variables provided by the function. I think black-boxing it inside the function, and defining it where it's used, is clearer and more compact than defining a separate constant inside or outside the function.

vchudnov-g · 2025-10-13T23:20:23Z

google/api_core/_python_version_support.py

+ python_beta=None,
+ python_start=datetime.date(2018, 6, 27),
+ python_eol=datetime.date(2023, 6, 27),
+ ),


I could see it either way, but ok, sure, done.

vchudnov-g · 2025-10-13T23:57:31Z

google/api_core/_python_version_support.py

+ PYTHON_VERSION_UNSUPPORTED = "PYTHON_VERSION_UNSUPPORTED"
+ PYTHON_VERSION_EOL = "PYTHON_VERSION_EOL"
+ PYTHON_VERSION_DEPRECATED = "PYTHON_VERSION_DEPRECATED"
+ PYTHON_VERSION_SUPPORTED = "PYTHON_VERSION_SUPPORTED"


Deprecated is still supported for now. EOL will soon be unsupported.

You're right, as read naively, these are not mutually exclusive. But in this code I am using them in a mutually exclusive way, so I clarified the semantics in docstrings. WDYT?

vchudnov-g · 2025-10-14T00:04:53Z

google/api_core/_python_version_support.py

+ python_beta=FAKE_FUTURE_DATE,
+ python_start=FAKE_FUTURE_DATE,
+ python_eol=FAKE_FUTURE_DATE,
+ )


Well, the point is that if we don't have the version info but can at least tell whether it's in the past or the future, we do the right thing. So I think these sentinel values are not a bad way to go.

I did make them into constants, and made them private.

vchudnov-g · 2025-10-14T00:08:50Z

google/api_core/_python_version_support.py

+ 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"


I tweaked it. WDYT?

vchudnov-g · 2025-10-14T00:10:36Z

google/api_core/_python_version_support.py

+ {min_python(version_info.python_eol)}, to continue receiving updates
+ for {package_label} past that date.
+ """
+ )


No, for the same reason as the other case. They are defined and used directly only once, and the substitution strings and the text are closely related to the logic of the function. I think it reads more clearly to have them defined inline, as they are now.

vchudnov-g requested review from ohmayr and parthea July 29, 2025 21:35

vchudnov-g requested review from a team as code owners July 29, 2025 21:35

blunderbuss-gcf bot assigned ohmayr Jul 29, 2025

product-auto-label bot added the size: l Pull request size is large. label Jul 29, 2025

vchudnov-g marked this pull request as draft July 29, 2025 21:46

vchudnov-g force-pushed the python-version-support-check branch from 2139b90 to 4d49aa0 Compare July 30, 2025 20:39

vchudnov-g mentioned this pull request Jul 30, 2025

feat: check Python and dependency versions in generated GAPICs googleapis/gapic-generator-python#2419

Open

vchudnov-g force-pushed the python-version-support-check branch 2 times, most recently from d727f14 to 17ef4f0 Compare August 12, 2025 19:23

vchudnov-g force-pushed the python-version-support-check branch from ded3381 to 93a8e5a Compare September 5, 2025 19:53

vchudnov-g marked this pull request as ready for review September 9, 2025 20:33

vchudnov-g force-pushed the python-version-support-check branch 3 times, most recently from 5cfaf42 to 86b5710 Compare September 19, 2025 17:28

vchudnov-g added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Sep 24, 2025

vchudnov-g force-pushed the python-version-support-check branch from 86b5710 to fe6aa6d Compare October 1, 2025 18:06

vchudnov-g added 10 commits October 10, 2025 11:16

feat: apply Python version suport warnings to api_core

8d1ade4

feat: add deprecation check for the protobuf package

6d1058d

format files

0f8caa2

fix lint warning

3ec85a6

add docstring to warn_deprecation_for_versions_less_than

240baec

Add/fix docstrings

ee4d6b6

fix typo

0726cd2

add test for _python_package_support.py

8f54a81

add constants for various buffer periods

9f3d7ef

vchudnov-g added 12 commits October 10, 2025 11:16

chore: fix comments and exported function

d60d12d

fix lint

f3edf46

chore: fix unit test

d22c43c

chore: lint

0fdd8bc

Use warnings module instead of logging module

38ded4e

fix: print the current package versions correctly

7dc906d

wip: before gemini doc fixes

2de943a

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

e61455a

lint

ce216e4

feat: add grace period for 3.9; tweak warning

695bfcf

The warning messages now mor eclosely match what we'we're deploying in the generator for those who don't update their api-core dependency

lint

eebbe61

allow providing a recommended version

670ba62

Sometimes the version we recommend is newer than the next non-deprecated version, so we want to inform users eagerly to reduce their toil

vchudnov-g force-pushed the python-version-support-check branch from 0f07954 to 670ba62 Compare October 10, 2025 18:17

vchudnov-g removed the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Oct 10, 2025

vchudnov-g assigned daniel-sanche Oct 10, 2025

daniel-sanche reviewed Oct 10, 2025

View reviewed changes

vchudnov-g added 10 commits October 13, 2025 13:15

refactor: used namedtuple

2dc8f5f

refactor: s/"--"/UNKNOWN_VERSION_STRING/ in code, not test

f23c41b

refactor s/next_supported_version/minimum_fully_supported_version/

691981e

refactor: s/dependent_/consumer_/

d13feb1

refactor: add _PACKAGE_DEPENDENCY_WARNINGS

6493e33

refactor: reorder and comment on _init__ statements for clarity

c51d61b

fix: exapnd VersionInfo with version field; clarify fake dates

706518c

doc: document PythonVersionSupportStatus

a254693

refactor: make fake past and future versions into constants

8d19eb2

refactor: reword default string for min_python

8ad6f2b

vchudnov-g commented Oct 14, 2025

View reviewed changes

vchudnov-g added 2 commits October 13, 2025 17:30

fix: fix populating PYTHON_VERSION_INFO

a9c9f15

fix: type hints

aa41540

feat: provide and use Python version support check #832

Are you sure you want to change the base?

feat: provide and use Python version support check #832

Conversation

vchudnov-g commented Jul 29, 2025

vchudnov-g commented Jul 29, 2025

vchudnov-g commented Sep 24, 2025

vchudnov-g commented Oct 10, 2025

daniel-sanche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vchudnov-g left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Labels

3 participants