google-cloud-spanner 3.51.0__tar.gz → 3.52.0__tar.gz

{google_cloud_spanner-3.51.0/google_cloud_spanner.egg-info → google_cloud_spanner-3.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: google-cloud-spanner
-Version: 3.51.0
+Version: 3.52.0
 Summary: Google Cloud Spanner API client library
 Home-page: https://github.com/googleapis/python-spanner
 Author: Google LLC
@@ -34,6 +34,7 @@ Provides-Extra: tracing
 Requires-Dist: opentelemetry-api>=1.22.0; extra == "tracing"
 Requires-Dist: opentelemetry-sdk>=1.22.0; extra == "tracing"
 Requires-Dist: opentelemetry-semantic-conventions>=0.43b0; extra == "tracing"
+Requires-Dist: google-cloud-monitoring>=2.16.0; extra == "tracing"
 Provides-Extra: libcst
 Requires-Dist: libcst>=0.2.5; extra == "libcst"
 

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_admin_database_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "3.51.0"  # {x-release-please-version}
+__version__ = "3.52.0"  # {x-release-please-version}

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_admin_instance_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "3.51.0"  # {x-release-please-version}
+__version__ = "3.52.0"  # {x-release-please-version}

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_dbapi/connection.py

@@ -113,7 +113,7 @@ class Connection:
         self.request_priority = None
         self._transaction_begin_marked = False
         # whether transaction started at Spanner. This means that we had
-        # made atleast one call to Spanner.
+        # made at least one call to Spanner.
         self._spanner_transaction_started = False
         self._batch_mode = BatchMode.NONE
         self._batch_dml_executor: BatchDmlExecutor = None
@@ -261,6 +261,28 @@ class Connection:
         self.request_priority = None
         return req_opts
 
+    @property
+    def transaction_tag(self):
+        """The transaction tag that will be applied to the next read/write
+        transaction on this `Connection`. This property is automatically cleared
+        when a new transaction is started.
+
+        Returns:
+            str: The transaction tag that will be applied to the next read/write transaction.
+        """
+        return self._connection_variables.get("transaction_tag", None)
+
+    @transaction_tag.setter
+    def transaction_tag(self, value):
+        """Sets the transaction tag for the next read/write transaction on this
+        `Connection`. This property is automatically cleared when a new transaction
+        is started.
+
+        Args:
+            value (str): The transaction tag for the next read/write transaction.
+        """
+        self._connection_variables["transaction_tag"] = value
+
     @property
     def staleness(self):
         """Current read staleness option value of this `Connection`.
@@ -340,6 +362,8 @@ class Connection:
         if not self.read_only and self._client_transaction_started:
             if not self._spanner_transaction_started:
                 self._transaction = self._session_checkout().transaction()
+                self._transaction.transaction_tag = self.transaction_tag
+                self.transaction_tag = None
                 self._snapshot = None
                 self._spanner_transaction_started = True
                 self._transaction.begin()
@@ -458,7 +482,9 @@ class Connection:
 
             return self.database.update_ddl(ddl_statements).result()
 
-    def run_statement(self, statement: Statement):
+    def run_statement(
+        self, statement: Statement, request_options: RequestOptions = None
+    ):
         """Run single SQL statement in begun transaction.
 
         This method is never used in autocommit mode. In
@@ -472,6 +498,9 @@ class Connection:
         :param retried: (Optional) Retry the SQL statement if statement
                         execution failed. Defaults to false.
 
+        :type request_options: :class:`RequestOptions`
+        :param request_options: Request options to use for this statement.
+
         :rtype: :class:`google.cloud.spanner_v1.streamed.StreamedResultSet`,
                 :class:`google.cloud.spanner_dbapi.checksum.ResultsChecksum`
         :returns: Streamed result set of the statement and a
@@ -482,7 +511,7 @@ class Connection:
             statement.sql,
             statement.params,
             param_types=statement.param_types,
-            request_options=self.request_options,
+            request_options=request_options or self.request_options,
         )
 
     @check_not_closed

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_dbapi/cursor.py

@@ -50,6 +50,7 @@ from google.cloud.spanner_dbapi.parsed_statement import (
 from google.cloud.spanner_dbapi.transaction_helper import CursorStatementType
 from google.cloud.spanner_dbapi.utils import PeekIterator
 from google.cloud.spanner_dbapi.utils import StreamedManyResultSets
+from google.cloud.spanner_v1 import RequestOptions
 from google.cloud.spanner_v1.merged_result_set import MergedResultSet
 
 ColumnDetails = namedtuple("column_details", ["null_ok", "spanner_type"])
@@ -97,6 +98,39 @@ class Cursor(object):
         self._parsed_statement: ParsedStatement = None
         self._in_retry_mode = False
         self._batch_dml_rows_count = None
+        self._request_tag = None
+
+    @property
+    def request_tag(self):
+        """The request tag that will be applied to the next statement on this
+        cursor. This property is automatically cleared when a statement is
+        executed.
+
+        Returns:
+            str: The request tag that will be applied to the next statement on
+                 this cursor.
+        """
+        return self._request_tag
+
+    @request_tag.setter
+    def request_tag(self, value):
+        """Sets the request tag for the next statement on this cursor. This
+        property is automatically cleared when a statement is executed.
+
+        Args:
+            value (str): The request tag for the statement.
+        """
+        self._request_tag = value
+
+    @property
+    def request_options(self):
+        options = self.connection.request_options
+        if self._request_tag:
+            if not options:
+                options = RequestOptions()
+            options.request_tag = self._request_tag
+            self._request_tag = None
+        return options
 
     @property
     def is_closed(self):
@@ -284,7 +318,7 @@ class Cursor(object):
                     sql,
                     params=args,
                     param_types=self._parsed_statement.statement.param_types,
-                    request_options=self.connection.request_options,
+                    request_options=self.request_options,
                 )
                 self._result_set = None
             else:
@@ -318,7 +352,9 @@ class Cursor(object):
         if self.connection._client_transaction_started:
             while True:
                 try:
-                    self._result_set = self.connection.run_statement(statement)
+                    self._result_set = self.connection.run_statement(
+                        statement, self.request_options
+                    )
                     self._itr = PeekIterator(self._result_set)
                     return
                 except Aborted:
@@ -478,7 +514,7 @@ class Cursor(object):
             sql,
             params,
             get_param_types(params),
-            request_options=self.connection.request_options,
+            request_options=self.request_options,
         )
         # Read the first element so that the StreamedResultSet can
         # return the metadata after a DQL statement.

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_dbapi/parse_utils.py

@@ -155,7 +155,7 @@ STMT_UPDATING = "UPDATING"
 STMT_INSERT = "INSERT"
 
 # Heuristic for identifying statements that don't need to be run as updates.
-RE_NON_UPDATE = re.compile(r"^\W*(SELECT)", re.IGNORECASE)
+RE_NON_UPDATE = re.compile(r"^\W*(SELECT|GRAPH|FROM)", re.IGNORECASE)
 
 RE_WITH = re.compile(r"^\s*(WITH)", re.IGNORECASE)
 

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_dbapi/transaction_helper.py

@@ -20,7 +20,7 @@ import time
 
 from google.cloud.spanner_dbapi.batch_dml_executor import BatchMode
 from google.cloud.spanner_dbapi.exceptions import RetryAborted
-from google.cloud.spanner_v1.session import _get_retry_delay
+from google.cloud.spanner_v1._helpers import _get_retry_delay
 
 if TYPE_CHECKING:
     from google.cloud.spanner_dbapi import Connection, Cursor

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_v1/_helpers.py

@@ -19,6 +19,7 @@ import decimal
 import math
 import time
 import base64
+import threading
 
 from google.protobuf.struct_pb2 import ListValue
 from google.protobuf.struct_pb2 import Value
@@ -26,10 +27,15 @@ from google.protobuf.message import Message
 from google.protobuf.internal.enum_type_wrapper import EnumTypeWrapper
 
 from google.api_core import datetime_helpers
+from google.api_core.exceptions import Aborted
 from google.cloud._helpers import _date_from_iso8601_date
 from google.cloud.spanner_v1 import TypeCode
 from google.cloud.spanner_v1 import ExecuteSqlRequest
 from google.cloud.spanner_v1 import JsonObject
+from google.cloud.spanner_v1.request_id_header import with_request_id
+from google.rpc.error_details_pb2 import RetryInfo
+
+import random
 
 # Validation error messages
 NUMERIC_MAX_SCALE_ERR_MSG = (
@@ -458,11 +464,29 @@ def _metadata_with_prefix(prefix, **kw):
     return [("google-cloud-resource-prefix", prefix)]
 
 
+def _retry_on_aborted_exception(
+    func,
+    deadline,
+):
+    """
+    Handles retry logic for Aborted exceptions, considering the deadline.
+    """
+    attempts = 0
+    while True:
+        try:
+            attempts += 1
+            return func()
+        except Aborted as exc:
+            _delay_until_retry(exc, deadline=deadline, attempts=attempts)
+            continue
+
+
 def _retry(
     func,
     retry_count=5,
     delay=2,
     allowed_exceptions=None,
+    beforeNextRetry=None,
 ):
     """
     Retry a function with a specified number of retries, delay between retries, and list of allowed exceptions.
@@ -479,6 +503,9 @@ def _retry(
     """
     retries = 0
     while retries <= retry_count:
+        if retries > 0 and beforeNextRetry:
+            beforeNextRetry(retries, delay)
+
         try:
             return func()
         except Exception as exc:
@@ -521,3 +548,99 @@ def _metadata_with_leader_aware_routing(value, **kw):
         List[Tuple[str, str]]: RPC metadata with leader aware routing header
     """
     return ("x-goog-spanner-route-to-leader", str(value).lower())
+
+
+def _delay_until_retry(exc, deadline, attempts):
+    """Helper for :meth:`Session.run_in_transaction`.
+
+    Detect retryable abort, and impose server-supplied delay.
+
+    :type exc: :class:`google.api_core.exceptions.Aborted`
+    :param exc: exception for aborted transaction
+
+    :type deadline: float
+    :param deadline: maximum timestamp to continue retrying the transaction.
+
+    :type attempts: int
+    :param attempts: number of call retries
+    """
+
+    cause = exc.errors[0]
+    now = time.time()
+    if now >= deadline:
+        raise
+
+    delay = _get_retry_delay(cause, attempts)
+    if delay is not None:
+        if now + delay > deadline:
+            raise
+
+        time.sleep(delay)
+
+
+def _get_retry_delay(cause, attempts):
+    """Helper for :func:`_delay_until_retry`.
+
+    :type exc: :class:`grpc.Call`
+    :param exc: exception for aborted transaction
+
+    :rtype: float
+    :returns: seconds to wait before retrying the transaction.
+
+    :type attempts: int
+    :param attempts: number of call retries
+    """
+    if hasattr(cause, "trailing_metadata"):
+        metadata = dict(cause.trailing_metadata())
+    else:
+        metadata = {}
+    retry_info_pb = metadata.get("google.rpc.retryinfo-bin")
+    if retry_info_pb is not None:
+        retry_info = RetryInfo()
+        retry_info.ParseFromString(retry_info_pb)
+        nanos = retry_info.retry_delay.nanos
+        return retry_info.retry_delay.seconds + nanos / 1.0e9
+
+    return 2**attempts + random.random()
+
+
+class AtomicCounter:
+    def __init__(self, start_value=0):
+        self.__lock = threading.Lock()
+        self.__value = start_value
+
+    @property
+    def value(self):
+        with self.__lock:
+            return self.__value
+
+    def increment(self, n=1):
+        with self.__lock:
+            self.__value += n
+            return self.__value
+
+    def __iadd__(self, n):
+        """
+        Defines the inplace += operator result.
+        """
+        with self.__lock:
+            self.__value += n
+            return self
+
+    def __add__(self, n):
+        """
+        Defines the result of invoking: value = AtomicCounter + addable
+        """
+        with self.__lock:
+            n += self.__value
+            return n
+
+    def __radd__(self, n):
+        """
+        Defines the result of invoking: value = addable + AtomicCounter
+        """
+        return self.__add__(n)
+
+
+def _metadata_with_request_id(*args, **kwargs):
+    return with_request_id(*args, **kwargs)

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_v1/_opentelemetry_tracing.py

@@ -56,11 +56,11 @@ def get_tracer(tracer_provider=None):
 
 
 @contextmanager
-def trace_call(name, session, extra_attributes=None, observability_options=None):
+def trace_call(name, session=None, extra_attributes=None, observability_options=None):
     if session:
         session._last_use_time = datetime.now()
 
-    if not HAS_OPENTELEMETRY_INSTALLED or not session:
+    if not (HAS_OPENTELEMETRY_INSTALLED and name):
         # Empty context manager. Users will have to check if the generated value is None or a span
         yield None
         return
@@ -72,11 +72,16 @@ def trace_call(name, session, extra_attributes=None, observability_options=None)
     # on by default.
     enable_extended_tracing = True
 
+    db_name = ""
+    if session and getattr(session, "_database", None):
+        db_name = session._database.name
+
     if isinstance(observability_options, dict):  # Avoid false positives with mock.Mock
         tracer_provider = observability_options.get("tracer_provider", None)
         enable_extended_tracing = observability_options.get(
             "enable_extended_tracing", enable_extended_tracing
         )
+        db_name = observability_options.get("db_name", db_name)
 
     tracer = get_tracer(tracer_provider)
 
@@ -84,10 +89,14 @@ def trace_call(name, session, extra_attributes=None, observability_options=None)
     attributes = {
         "db.type": "spanner",
         "db.url": SpannerClient.DEFAULT_ENDPOINT,
-        "db.instance": session._database.name,
+        "db.instance": db_name,
         "net.host.name": SpannerClient.DEFAULT_ENDPOINT,
         OTEL_SCOPE_NAME: TRACER_NAME,
         OTEL_SCOPE_VERSION: TRACER_VERSION,
+        # Standard GCP attributes for OTel, attributes are used for internal purpose and are subjected to change
+        "gcp.client.service": "spanner",
+        "gcp.client.version": TRACER_VERSION,
+        "gcp.client.repo": "googleapis/python-spanner",
     }
 
     if extra_attributes:
@@ -106,7 +115,30 @@ def trace_call(name, session, extra_attributes=None, observability_options=None)
             yield span
         except Exception as error:
             span.set_status(Status(StatusCode.ERROR, str(error)))
-            span.record_exception(error)
+            # OpenTelemetry-Python imposes invoking span.record_exception on __exit__
+            # on any exception. We should file a bug later on with them to only
+            # invoke .record_exception if not already invoked, hence we should not
+            # invoke .record_exception on our own else we shall have 2 exceptions.
             raise
         else:
-            span.set_status(Status(StatusCode.OK))
+            # All spans still have set_status available even if for example
+            # NonRecordingSpan doesn't have "_status".
+            absent_span_status = getattr(span, "_status", None) is None
+            if absent_span_status or span._status.status_code == StatusCode.UNSET:
+                # OpenTelemetry-Python only allows a status change
+                # if the current code is UNSET or ERROR. At the end
+                # of the generator's consumption, only set it to OK
+                # it wasn't previously set otherwise.
+                # https://github.com/googleapis/python-spanner/issues/1246
+                span.set_status(Status(StatusCode.OK))
+
+
+def get_current_span():
+    if not HAS_OPENTELEMETRY_INSTALLED:
+        return None
+    return trace.get_current_span()
+
+
+def add_span_event(span, event_name, event_attributes=None):
+    if span:
+        span.add_event(event_name, event_attributes)

{google_cloud_spanner-3.51.0 → google_cloud_spanner-3.52.0}/google/cloud/spanner_v1/batch.py

@@ -29,8 +29,12 @@ from google.cloud.spanner_v1._helpers import (
 from google.cloud.spanner_v1._opentelemetry_tracing import trace_call
 from google.cloud.spanner_v1 import RequestOptions
 from google.cloud.spanner_v1._helpers import _retry
+from google.cloud.spanner_v1._helpers import _retry_on_aborted_exception
 from google.cloud.spanner_v1._helpers import _check_rst_stream_error
 from google.api_core.exceptions import InternalServerError
+import time
+
+DEFAULT_RETRY_TIMEOUT_SECS = 30
 
 
 class _BatchBase(_SessionWrapper):
@@ -70,6 +74,8 @@ class _BatchBase(_SessionWrapper):
         :param values: Values to be modified.
         """
         self._mutations.append(Mutation(insert=_make_write_pb(table, columns, values)))
+        # TODO: Decide if we should add a span event per mutation:
+        # https://github.com/googleapis/python-spanner/issues/1269
 
     def update(self, table, columns, values):
         """Update one or more existing table rows.
@@ -84,6 +90,8 @@ class _BatchBase(_SessionWrapper):
         :param values: Values to be modified.
         """
         self._mutations.append(Mutation(update=_make_write_pb(table, columns, values)))
+        # TODO: Decide if we should add a span event per mutation:
+        # https://github.com/googleapis/python-spanner/issues/1269
 
     def insert_or_update(self, table, columns, values):
         """Insert/update one or more table rows.
@@ -100,6 +108,8 @@ class _BatchBase(_SessionWrapper):
         self._mutations.append(
             Mutation(insert_or_update=_make_write_pb(table, columns, values))
         )
+        # TODO: Decide if we should add a span event per mutation:
+        # https://github.com/googleapis/python-spanner/issues/1269
 
     def replace(self, table, columns, values):
         """Replace one or more table rows.
@@ -114,6 +124,8 @@ class _BatchBase(_SessionWrapper):
         :param values: Values to be modified.
         """
         self._mutations.append(Mutation(replace=_make_write_pb(table, columns, values)))
+        # TODO: Decide if we should add a span event per mutation:
+        # https://github.com/googleapis/python-spanner/issues/1269
 
     def delete(self, table, keyset):
         """Delete one or more table rows.
@@ -126,6 +138,8 @@ class _BatchBase(_SessionWrapper):
         """
         delete = Mutation.Delete(table=table, key_set=keyset._to_pb())
         self._mutations.append(Mutation(delete=delete))
+        # TODO: Decide if we should add a span event per mutation:
+        # https://github.com/googleapis/python-spanner/issues/1269
 
 
 class Batch(_BatchBase):
@@ -152,6 +166,7 @@ class Batch(_BatchBase):
         request_options=None,
         max_commit_delay=None,
         exclude_txn_from_change_streams=False,
+        **kwargs,
     ):
         """Commit mutations to the database.
 
@@ -207,7 +222,7 @@ class Batch(_BatchBase):
         )
         observability_options = getattr(database, "observability_options", None)
         with trace_call(
-            "CloudSpanner.Commit",
+            f"CloudSpanner.{type(self).__name__}.commit",
             self._session,
             trace_attributes,
             observability_options=observability_options,
@@ -217,9 +232,12 @@ class Batch(_BatchBase):
                 request=request,
                 metadata=metadata,
             )
-            response = _retry(
+            deadline = time.time() + kwargs.get(
+                "timeout_secs", DEFAULT_RETRY_TIMEOUT_SECS
+            )
+            response = _retry_on_aborted_exception(
                 method,
-                allowed_exceptions={InternalServerError: _check_rst_stream_error},
+                deadline=deadline,
             )
         self.committed = response.commit_timestamp
         self.commit_stats = response.commit_stats
@@ -326,7 +344,7 @@ class MutationGroups(_SessionWrapper):
         )
         observability_options = getattr(database, "observability_options", None)
         with trace_call(
-            "CloudSpanner.BatchWrite",
+            "CloudSpanner.batch_write",
             self._session,
             trace_attributes,
             observability_options=observability_options,
@@ -338,7 +356,9 @@ class MutationGroups(_SessionWrapper):
             )
             response = _retry(
                 method,
-                allowed_exceptions={InternalServerError: _check_rst_stream_error},
+                allowed_exceptions={
+                    InternalServerError: _check_rst_stream_error,
+                },
             )
         self.committed = True
         return response