google-cloud-testutils 1.6.1__py3-none-any.whl

test_utils/retry.py

@@ -0,0 +1,228 @@
+# Copyright 2016 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 functools
+import time
+
+MAX_TRIES = 4
+DELAY = 1
+BACKOFF = 2
+
+
+def _retry_all(_):
+    """Retry all caught exceptions."""
+    return True
+
+
+class BackoffFailed(Exception):
+    """Retry w/ backoffs did not complete successfully."""
+
+
+class RetryBase(object):
+    """Base for retrying calling a decorated function w/ exponential backoff.
+
+    :type max_tries: int
+    :param max_tries: Number of times to try (not retry) before giving up.
+
+    :type delay: int
+    :param delay: Initial delay between retries in seconds.
+
+    :type backoff: int
+    :param backoff: Backoff multiplier e.g. value of 2 will double the
+                    delay each retry.
+
+    :type logger: logging.Logger instance
+    :param logger: Logger to use. If None, print.
+    """
+
+    def __init__(self, max_tries=MAX_TRIES, delay=DELAY, backoff=BACKOFF, logger=None):
+        self.max_tries = max_tries
+        self.delay = delay
+        self.backoff = backoff
+        self.logger = logger.warning if logger else print
+
+
+class RetryErrors(RetryBase):
+    """Decorator for retrying given exceptions in testing.
+
+    :type exception: Exception or tuple of Exceptions
+    :param exception: The exception to check or may be a tuple of
+                      exceptions to check.
+
+    :type error_predicate: function, takes caught exception, returns bool
+    :param error_predicate: Predicate evaluating whether to retry after a
+                            caught exception.
+
+    :type max_tries: int
+    :param max_tries: Number of times to try (not retry) before giving up.
+
+    :type delay: int
+    :param delay: Initial delay between retries in seconds.
+
+    :type backoff: int
+    :param backoff: Backoff multiplier e.g. value of 2 will double the
+                    delay each retry.
+
+    :type logger: logging.Logger instance
+    :param logger: Logger to use. If None, print.
+    """
+
+    def __init__(
+        self,
+        exception,
+        error_predicate=_retry_all,
+        max_tries=MAX_TRIES,
+        delay=DELAY,
+        backoff=BACKOFF,
+        logger=None,
+    ):
+        super(RetryErrors, self).__init__(max_tries, delay, backoff, logger)
+        self.exception = exception
+        self.error_predicate = error_predicate
+
+    def __call__(self, to_wrap):
+        @functools.wraps(to_wrap)
+        def wrapped_function(*args, **kwargs):
+            tries = 0
+            while tries < self.max_tries:
+                try:
+                    return to_wrap(*args, **kwargs)
+                except self.exception as caught_exception:
+                    if not self.error_predicate(caught_exception):
+                        raise
+
+                    delay = self.delay * self.backoff**tries
+                    msg = "%s, Trying again in %d seconds..." % (
+                        caught_exception,
+                        delay,
+                    )
+                    self.logger(msg)
+
+                    time.sleep(delay)
+                    tries += 1
+            return to_wrap(*args, **kwargs)
+
+        return wrapped_function
+
+
+class RetryResult(RetryBase):
+    """Decorator for retrying based on non-error result.
+
+    :type result_predicate: function, takes result, returns bool
+    :param result_predicate: Predicate evaluating whether to retry after a
+                             result is returned.
+
+    :type max_tries: int
+    :param max_tries: Number of times to try (not retry) before giving up.
+
+    :type delay: int
+    :param delay: Initial delay between retries in seconds.
+
+    :type backoff: int
+    :param backoff: Backoff multiplier e.g. value of 2 will double the
+                    delay each retry.
+
+    :type logger: logging.Logger instance
+    :param logger: Logger to use. If None, print.
+    """
+
+    def __init__(
+        self,
+        result_predicate,
+        max_tries=MAX_TRIES,
+        delay=DELAY,
+        backoff=BACKOFF,
+        logger=None,
+    ):
+        super(RetryResult, self).__init__(max_tries, delay, backoff, logger)
+        self.result_predicate = result_predicate
+
+    def __call__(self, to_wrap):
+        @functools.wraps(to_wrap)
+        def wrapped_function(*args, **kwargs):
+            tries = 0
+            while tries < self.max_tries:
+                result = to_wrap(*args, **kwargs)
+                if self.result_predicate(result):
+                    return result
+
+                delay = self.delay * self.backoff**tries
+                msg = "%s. Trying again in %d seconds..." % (
+                    self.result_predicate.__name__,
+                    delay,
+                )
+                self.logger(msg)
+
+                time.sleep(delay)
+                tries += 1
+            raise BackoffFailed()
+
+        return wrapped_function
+
+
+class RetryInstanceState(RetryBase):
+    """Decorator for retrying based on instance state.
+
+    :type instance_predicate: function, takes instance, returns bool
+    :param instance_predicate: Predicate evaluating whether to retry after an
+                               API-invoking method is called.
+
+    :type max_tries: int
+    :param max_tries: Number of times to try (not retry) before giving up.
+
+    :type delay: int
+    :param delay: Initial delay between retries in seconds.
+
+    :type backoff: int
+    :param backoff: Backoff multiplier e.g. value of 2 will double the
+                    delay each retry.
+
+    :type logger: logging.Logger instance
+    :param logger: Logger to use. If None, print.
+    """
+
+    def __init__(
+        self,
+        instance_predicate,
+        max_tries=MAX_TRIES,
+        delay=DELAY,
+        backoff=BACKOFF,
+        logger=None,
+    ):
+        super(RetryInstanceState, self).__init__(max_tries, delay, backoff, logger)
+        self.instance_predicate = instance_predicate
+
+    def __call__(self, to_wrap):
+        instance = to_wrap.__self__  # only instance methods allowed
+
+        @functools.wraps(to_wrap)
+        def wrapped_function(*args, **kwargs):
+            tries = 0
+            while tries < self.max_tries:
+                result = to_wrap(*args, **kwargs)
+                if self.instance_predicate(instance):
+                    return result
+
+                delay = self.delay * self.backoff**tries
+                msg = "%s. Trying again in %d seconds..." % (
+                    self.instance_predicate.__name__,
+                    delay,
+                )
+                self.logger(msg)
+
+                time.sleep(delay)
+                tries += 1
+            raise BackoffFailed()
+
+        return wrapped_function

test_utils/system.py

@@ -0,0 +1,80 @@
+# Copyright 2014 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.
+
+from __future__ import print_function
+import os
+import sys
+import time
+
+import google.auth.credentials  # type: ignore
+from google.auth.environment_vars import CREDENTIALS as TEST_CREDENTIALS  # type: ignore
+
+
+# From shell environ. May be None.
+CREDENTIALS = os.getenv(TEST_CREDENTIALS)
+
+ENVIRON_ERROR_MSG = """\
+To run the system tests, you need to set some environment variables.
+Please check the CONTRIBUTING guide for instructions.
+"""
+
+
+class EmulatorCreds(google.auth.credentials.Credentials):
+    """A mock credential object.
+
+    Used to avoid unnecessary token refreshing or reliance on the network
+    while an emulator is running.
+    """
+
+    def __init__(self):  # pylint: disable=super-init-not-called
+        self.token = b"seekrit"
+        self.expiry = None
+
+    @property
+    def valid(self):
+        """Would-be validity check of the credentials.
+
+        Always is :data:`True`.
+        """
+        return True
+
+    def refresh(self, unused_request):  # pylint: disable=unused-argument
+        """Off-limits implementation for abstract method."""
+        raise RuntimeError("Should never be refreshed.")
+
+
+def check_environ():
+    err_msg = None
+    if CREDENTIALS is None:
+        err_msg = "\nMissing variables: " + TEST_CREDENTIALS
+    elif not os.path.isfile(CREDENTIALS):
+        err_msg = "\nThe %s path %r is not a file." % (TEST_CREDENTIALS, CREDENTIALS)
+
+    if err_msg is not None:
+        msg = ENVIRON_ERROR_MSG + err_msg
+        print(msg, file=sys.stderr)
+        sys.exit(1)
+
+
+def unique_resource_id(delimiter="_"):
+    """A unique identifier for a resource.
+
+    Intended to help locate resources created in particular
+    testing environments and at particular times.
+    """
+    build_id = os.getenv("CIRCLE_BUILD_NUM", "")
+    if build_id == "":
+        return "%s%d" % (delimiter, 1000 * time.time())
+    else:
+        return "%s%s%s%d" % (delimiter, build_id, delimiter, time.time())

test_utils/version.py

@@ -0,0 +1,15 @@
+# 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.
+#
+__version__ = "1.6.1"

test_utils/vpcsc_config.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2019 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
+#
+#     https://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 os
+
+import pytest  # type: ignore
+
+
+INSIDE_VPCSC_ENVVAR = "GOOGLE_CLOUD_TESTS_IN_VPCSC"
+PROJECT_INSIDE_ENVVAR = "PROJECT_ID"
+PROJECT_OUTSIDE_ENVVAR = "GOOGLE_CLOUD_TESTS_VPCSC_OUTSIDE_PERIMETER_PROJECT"
+BUCKET_OUTSIDE_ENVVAR = "GOOGLE_CLOUD_TESTS_VPCSC_OUTSIDE_PERIMETER_BUCKET"
+
+
+class VPCSCTestConfig(object):
+    """System test utility for VPCSC detection.
+
+    See: https://cloud.google.com/vpc-service-controls/docs/
+    """
+
+    @property
+    def inside_vpcsc(self):
+        """Test whether the test environment is configured to run inside VPCSC.
+
+        Returns:
+            bool:
+                true if the environment is configured to run inside VPCSC,
+                else false.
+        """
+        return INSIDE_VPCSC_ENVVAR in os.environ
+
+    @property
+    def project_inside(self):
+        """Project ID for testing outside access.
+
+        Returns:
+            str: project ID used for testing outside access; None if undefined.
+        """
+        return os.environ.get(PROJECT_INSIDE_ENVVAR, None)
+
+    @property
+    def project_outside(self):
+        """Project ID for testing inside access.
+
+        Returns:
+            str: project ID used for testing inside access; None if undefined.
+        """
+        return os.environ.get(PROJECT_OUTSIDE_ENVVAR, None)
+
+    @property
+    def bucket_outside(self):
+        """GCS bucket for testing inside access.
+
+        Returns:
+            str: bucket ID used for testing inside access; None if undefined.
+        """
+        return os.environ.get(BUCKET_OUTSIDE_ENVVAR, None)
+
+    def skip_if_inside_vpcsc(self, testcase):
+        """Test decorator: skip if running inside VPCSC."""
+        reason = (
+            "Running inside VPCSC.  "
+            "Unset the {} environment variable to enable this test."
+        ).format(INSIDE_VPCSC_ENVVAR)
+        skip = pytest.mark.skipif(self.inside_vpcsc, reason=reason)
+        return skip(testcase)
+
+    def skip_unless_inside_vpcsc(self, testcase):
+        """Test decorator: skip if running outside VPCSC."""
+        reason = (
+            "Running outside VPCSC.  "
+            "Set the {} environment variable to enable this test."
+        ).format(INSIDE_VPCSC_ENVVAR)
+        skip = pytest.mark.skipif(not self.inside_vpcsc, reason=reason)
+        return skip(testcase)
+
+    def skip_unless_inside_project(self, testcase):
+        """Test decorator: skip if inside project env var not set."""
+        reason = (
+            "Project ID for running inside VPCSC not set.  "
+            "Set the {} environment variable to enable this test."
+        ).format(PROJECT_INSIDE_ENVVAR)
+        skip = pytest.mark.skipif(self.project_inside is None, reason=reason)
+        return skip(testcase)
+
+    def skip_unless_outside_project(self, testcase):
+        """Test decorator: skip if outside project env var not set."""
+        reason = (
+            "Project ID for running outside VPCSC not set. "
+            "Set the {} environment variable to enable this test."
+        ).format(PROJECT_OUTSIDE_ENVVAR)
+        skip = pytest.mark.skipif(self.project_outside is None, reason=reason)
+        return skip(testcase)
+
+    def skip_unless_outside_bucket(self, testcase):
+        """Test decorator: skip if outside bucket env var not set."""
+        reason = (
+            "Bucket ID for running outside VPCSC not set. "
+            "Set the {} environment variable to enable this test."
+        ).format(BUCKET_OUTSIDE_ENVVAR)
+        skip = pytest.mark.skipif(self.bucket_outside is None, reason=reason)
+        return skip(testcase)
+
+
+vpcsc_config = VPCSCTestConfig()