google-api-core 2.27.0__tar.gz → 2.28.0__tar.gz

{google_api_core-2.27.0/google_api_core.egg-info → google_api_core-2.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-api-core
-Version: 2.27.0
+Version: 2.28.0
 Summary: Google API client core library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0

google_api_core-2.28.0/google/api_core/__init__.py

@@ -0,0 +1,40 @@
+# Copyright 2017 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.
+
+"""Google API Core.
+
+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__
+
+# NOTE: Until dependent artifacts require this version of
+# google.api_core, the functionality below must be made available
+# manually in those artifacts.
+
+# expose dependency checks for external callers
+check_python_version = _python_version_support.check_python_version
+check_dependency_versions = _python_package_support.check_dependency_versions
+warn_deprecation_for_versions_less_than = (
+    _python_package_support.warn_deprecation_for_versions_less_than
+)
+DependencyConstraint = _python_package_support.DependencyConstraint
+
+# perform version checks against api_core, and emit warnings if needed
+check_python_version(package="google.api_core")
+check_dependency_versions("google.api_core")

google_api_core-2.28.0/google/api_core/_python_package_support.py

@@ -0,0 +1,209 @@
+# 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 warnings
+import sys
+from typing import Optional
+
+from collections import namedtuple
+
+from ._python_version_support import (
+    _flatten_message,
+    _get_distribution_and_import_packages,
+)
+
+from packaging.version import parse as parse_version
+
+# Here we list all the packages for which we want to issue warnings
+# about deprecated and unsupported versions.
+DependencyConstraint = namedtuple(
+    "DependencyConstraint",
+    ["package_name", "minimum_fully_supported_version", "recommended_version"],
+)
+_PACKAGE_DEPENDENCY_WARNINGS = [
+    DependencyConstraint(
+        "google.protobuf",
+        minimum_fully_supported_version="4.25.8",
+        recommended_version="6.x",
+    )
+]
+
+
+DependencyVersion = namedtuple("DependencyVersion", ["version", "version_string"])
+# Version string we provide in a DependencyVersion when we can't determine the version of a
+# package.
+UNKNOWN_VERSION_STRING = "--"
+
+
+def get_dependency_version(
+    dependency_name: str,
+) -> DependencyVersion:
+    """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 DependencyVersion namedtuple with `version` and
+        `version_string` attributes, or `DependencyVersion(None,
+        UNKNOWN_VERSION_STRING)` 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 DependencyVersion(parse_version(version_string), version_string)
+
+        # TODO(https://github.com/googleapis/python-api-core/issues/835): Remove
+        # this code path once we drop support for Python 3.7
+        else:  # pragma: NO COVER
+            # Use pkg_resources, which is part of setuptools.
+            import pkg_resources
+
+            version_string = pkg_resources.get_distribution(dependency_name).version
+            return DependencyVersion(parse_version(version_string), version_string)
+
+    except Exception:
+        return DependencyVersion(None, UNKNOWN_VERSION_STRING)
+
+
+def warn_deprecation_for_versions_less_than(
+    consumer_import_package: str,
+    dependency_import_package: str,
+    minimum_fully_supported_version: str,
+    recommended_version: Optional[str] = None,
+    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
+    `minimum_fully_supported_version`, this issues a warning using either a
+    default `message_template` or one provided by the user. The
+    default `message_template` informs the user that they will not receive
+    future updates for `consumer_import_package` if
+    `dependency_import_package` is somehow pinned to a version lower
+    than `minimum_fully_supported_version`.
+
+    Args:
+      consumer_import_package: The import name of the package that
+        needs `dependency_import_package`.
+      dependency_import_package: The import name of the dependency to check.
+      minimum_fully_supported_version: The dependency_import_package version number
+        below which a deprecation warning will be logged.
+      recommended_version: If provided, the recommended next version, which
+        could be higher than `minimum_fully_supported_version`.
+      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`, `consumer_import_package` and
+        `dependency_distribution_package` and
+        `consumer_distribution_package` and `dependency_package`,
+        `consumer_package` , which contain the import packages, the
+        distribution packages, and pretty string with both the
+        distribution and import packages for the dependency and the
+        consumer, respectively; and `minimum_fully_supported_version`,
+        `version_used`, and `version_used_string`, which refer to supported
+        and currently-used versions of the dependency.
+
+    """
+    if (
+        not consumer_import_package
+        or not dependency_import_package
+        or not minimum_fully_supported_version
+    ):  # pragma: NO COVER
+        return
+    dependency_version = get_dependency_version(dependency_import_package)
+    if not dependency_version.version:
+        return
+    if dependency_version.version < parse_version(minimum_fully_supported_version):
+        (
+            dependency_package,
+            dependency_distribution_package,
+        ) = _get_distribution_and_import_packages(dependency_import_package)
+        (
+            consumer_package,
+            consumer_distribution_package,
+        ) = _get_distribution_and_import_packages(consumer_import_package)
+
+        recommendation = (
+            " (we recommend {recommended_version})" if recommended_version else ""
+        )
+        message_template = message_template or _flatten_message(
+            """
+            DEPRECATION: Package {consumer_package} depends on
+            {dependency_package}, currently installed at version
+            {version_used_string}. Future updates to
+            {consumer_package} will require {dependency_package} at
+            version {minimum_fully_supported_version} or
+            higher{recommendation}. Please ensure that either (a) your
+            Python environment doesn't pin the version of
+            {dependency_package}, so that updates to
+            {consumer_package} can require the higher version, or (b)
+            you manually update your Python environment to use at
+            least version {minimum_fully_supported_version} of
+            {dependency_package}.
+            """
+        )
+        warnings.warn(
+            message_template.format(
+                consumer_import_package=consumer_import_package,
+                dependency_import_package=dependency_import_package,
+                consumer_distribution_package=consumer_distribution_package,
+                dependency_distribution_package=dependency_distribution_package,
+                dependency_package=dependency_package,
+                consumer_package=consumer_package,
+                minimum_fully_supported_version=minimum_fully_supported_version,
+                recommendation=recommendation,
+                version_used=dependency_version.version,
+                version_used_string=dependency_version.version_string,
+            ),
+            FutureWarning,
+        )
+
+
+def check_dependency_versions(
+    consumer_import_package: str, *package_dependency_warnings: DependencyConstraint
+):
+    """Bundle checks for all package dependencies.
+
+    This function can be called by all consumers of google.api_core,
+    to emit needed deprecation warnings for any of their
+    dependencies. The dependencies to check can be passed as arguments, or if
+    none are provided, it will default to the list in
+    `_PACKAGE_DEPENDENCY_WARNINGS`.
+
+    Args:
+      consumer_import_package: The distribution name of the calling package, whose
+        dependencies we're checking.
+      *package_dependency_warnings: A variable number of DependencyConstraint
+        objects, each specifying a dependency to check.
+    """
+    if not package_dependency_warnings:
+        package_dependency_warnings = tuple(_PACKAGE_DEPENDENCY_WARNINGS)
+    for package_info in package_dependency_warnings:
+        warn_deprecation_for_versions_less_than(
+            consumer_import_package,
+            package_info.package_name,
+            package_info.minimum_fully_supported_version,
+            recommended_version=package_info.recommended_version,
+        )

google_api_core-2.28.0/google/api_core/_python_version_support.py

@@ -0,0 +1,269 @@
+# 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 warnings
+import sys
+import textwrap
+from typing import Any, List, NamedTuple, Optional, Dict, Tuple
+
+
+class PythonVersionStatus(enum.Enum):
+    """Support status of a Python version in this client library artifact release.
+
+    "Support", in this context, means that this release of a client library
+    artifact is configured to run on the currently configured version of
+    Python.
+    """
+
+    PYTHON_VERSION_STATUS_UNSPECIFIED = "PYTHON_VERSION_STATUS_UNSPECIFIED"
+
+    PYTHON_VERSION_SUPPORTED = "PYTHON_VERSION_SUPPORTED"
+    """This Python version is fully supported, so the artifact running on this
+    version will have all features and bug fixes."""
+
+    PYTHON_VERSION_DEPRECATED = "PYTHON_VERSION_DEPRECATED"
+    """This Python version is still supported, but support will end within a
+    year. At that time, there will be no more releases for this artifact
+    running under this Python version."""
+
+    PYTHON_VERSION_EOL = "PYTHON_VERSION_EOL"
+    """This Python version has reached its end of life in the Python community
+    (see https://devguide.python.org/versions/), and this artifact will cease
+    supporting this Python version within the next few releases."""
+
+    PYTHON_VERSION_UNSUPPORTED = "PYTHON_VERSION_UNSUPPORTED"
+    """This release of the client library artifact may not be the latest, since
+    current releases no longer support this Python version."""
+
+
+class VersionInfo(NamedTuple):
+    """Hold release and support date information for a Python version."""
+
+    version: str
+    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_VERSIONS: List[VersionInfo] = [
+    # Refer to https://devguide.python.org/versions/ and the PEPs linked therefrom.
+    VersionInfo(
+        version="3.7",
+        python_beta=None,
+        python_start=datetime.date(2018, 6, 27),
+        python_eol=datetime.date(2023, 6, 27),
+    ),
+    VersionInfo(
+        version="3.8",
+        python_beta=None,
+        python_start=datetime.date(2019, 10, 14),
+        python_eol=datetime.date(2024, 10, 7),
+    ),
+    VersionInfo(
+        version="3.9",
+        python_beta=datetime.date(2020, 5, 18),
+        python_start=datetime.date(2020, 10, 5),
+        python_eol=datetime.date(2025, 10, 5),
+        gapic_end=datetime.date(2025, 10, 5) + datetime.timedelta(days=90),
+    ),
+    VersionInfo(
+        version="3.10",
+        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
+    ),
+    VersionInfo(
+        version="3.11",
+        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
+    ),
+    VersionInfo(
+        version="3.12",
+        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
+    ),
+    VersionInfo(
+        version="3.13",
+        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
+    ),
+    VersionInfo(
+        version="3.14",
+        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
+    ),
+]
+
+PYTHON_VERSION_INFO: Dict[Tuple[int, int], VersionInfo] = {}
+for info in PYTHON_VERSIONS:
+    major, minor = map(int, info.version.split("."))
+    PYTHON_VERSION_INFO[(major, minor)] = info
+
+
+LOWEST_TRACKED_VERSION = min(PYTHON_VERSION_INFO.keys())
+_FAKE_PAST_DATE = datetime.date.min + datetime.timedelta(days=900)
+_FAKE_PAST_VERSION = VersionInfo(
+    version="0.0",
+    python_beta=_FAKE_PAST_DATE,
+    python_start=_FAKE_PAST_DATE,
+    python_eol=_FAKE_PAST_DATE,
+)
+_FAKE_FUTURE_DATE = datetime.date.max - datetime.timedelta(days=900)
+_FAKE_FUTURE_VERSION = VersionInfo(
+    version="999.0",
+    python_beta=_FAKE_FUTURE_DATE,
+    python_start=_FAKE_FUTURE_DATE,
+    python_eol=_FAKE_FUTURE_DATE,
+)
+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 flatten it into a single line."""
+    return " ".join(textwrap.dedent(text).strip().split())
+
+
+# TODO(https://github.com/googleapis/python-api-core/issues/835): Remove once we
+# no longer support Python 3.7
+if sys.version_info < (3, 8):
+
+    def _get_pypi_package_name(module_name):  # pragma: NO COVER
+        """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:  # pragma: NO COVER
+                # 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 = sys.version.split()[0]
+
+    version_info = PYTHON_VERSION_INFO.get(version_tuple)
+
+    if not version_info:
+        if version_tuple < LOWEST_TRACKED_VERSION:
+            version_info = _FAKE_PAST_VERSION
+        else:
+            version_info = _FAKE_FUTURE_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)
+
+    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 currently supported version [https://devguide.python.org/versions]"
+
+    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}
+            supporting this Python version. Please upgrade to the latest Python
+            version, or at least Python {min_python(today)}, and then update
+            {package_label}.
+            """
+        )
+        warnings.warn(message, FutureWarning)
+        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}.
+            """
+        )
+        warnings.warn(message, FutureWarning)
+        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 new releases of {package_label} once 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)}, to continue receiving updates
+            for {package_label} past that date.
+            """
+        )
+        warnings.warn(message, FutureWarning)
+        return PythonVersionStatus.PYTHON_VERSION_DEPRECATED
+
+    return PythonVersionStatus.PYTHON_VERSION_SUPPORTED

{google_api_core-2.27.0 → google_api_core-2.28.0}/google/api_core/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2.27.0"
+__version__ = "2.28.0"

{google_api_core-2.27.0 → google_api_core-2.28.0/google_api_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-api-core
-Version: 2.27.0
+Version: 2.28.0
 Summary: Google API client core library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0

{google_api_core-2.27.0 → google_api_core-2.28.0}/google_api_core.egg-info/SOURCES.txt

@@ -5,6 +5,8 @@ pyproject.toml
 setup.cfg
 setup.py
 google/api_core/__init__.py
+google/api_core/_python_package_support.py
+google/api_core/_python_version_support.py
 google/api_core/_rest_streaming_base.py
 google/api_core/bidi.py
 google/api_core/bidi_async.py
@@ -103,6 +105,8 @@ tests/unit/test_packaging.py
 tests/unit/test_page_iterator.py
 tests/unit/test_path_template.py
 tests/unit/test_protobuf_helpers.py
+tests/unit/test_python_package_support.py
+tests/unit/test_python_version_support.py
 tests/unit/test_rest_helpers.py
 tests/unit/test_rest_streaming.py
 tests/unit/test_timeout.py

{google_api_core-2.27.0 → google_api_core-2.28.0}/tests/unit/gapic/test_method.py

@@ -186,7 +186,9 @@ def test_wrap_method_with_overriding_retry_timeout_compression(unused_sleep):
     assert result == 42
     assert method.call_count == 2
     method.assert_called_with(
-        timeout=22, compression=grpc.Compression.Deflate, metadata=mock.ANY
+        timeout=22,
+        compression=grpc.Compression.Deflate,
+        metadata=mock.ANY,
     )
 
 

{google_api_core-2.27.0 → google_api_core-2.28.0}/tests/unit/test_bidi.py

@@ -828,7 +828,13 @@ class TestBackgroundConsumer(object):
         bidi_rpc._start_rpc.side_effect = expected_exception
 
         consumer = bidi.BackgroundConsumer(bidi_rpc, on_response=None)
+
         consumer.start()
+
+        # Wait for the consumer's thread to exit.
+        while consumer.is_active:
+            pass  # pragma: NO COVER
+
         assert callback.call_args.args[0] == grpc.StatusCode.INVALID_ARGUMENT
 
     def test_consumer_expected_error(self, caplog):