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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: google-cloud-spanner
-Version: 3.50.1
+Version: 3.51.0
 Summary: Google Cloud Spanner API client library
 Home-page: https://github.com/googleapis/python-spanner
 Author: Google LLC

{google_cloud_spanner-3.50.1 → google_cloud_spanner-3.51.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.50.1"  # {x-release-please-version}
+__version__ = "3.51.0"  # {x-release-please-version}

{google_cloud_spanner-3.50.1 → google_cloud_spanner-3.51.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.50.1"  # {x-release-please-version}
+__version__ = "3.51.0"  # {x-release-please-version}

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

@@ -89,9 +89,11 @@ class Connection:
         committed by other transactions since the start of the read-only transaction. Commit or rolling back
         the read-only transaction is semantically the same, and only indicates that the read-only transaction
         should end a that a new one should be started when the next statement is executed.
+
+    **kwargs: Initial value for connection variables.
     """
 
-    def __init__(self, instance, database=None, read_only=False):
+    def __init__(self, instance, database=None, read_only=False, **kwargs):
         self._instance = instance
         self._database = database
         self._ddl_statements = []
@@ -117,6 +119,7 @@ class Connection:
         self._batch_dml_executor: BatchDmlExecutor = None
         self._transaction_helper = TransactionRetryHelper(self)
         self._autocommit_dml_mode: AutocommitDmlMode = AutocommitDmlMode.TRANSACTIONAL
+        self._connection_variables = kwargs
 
     @property
     def spanner_client(self):
@@ -206,6 +209,10 @@ class Connection:
         """
         return (not self._autocommit) or self._transaction_begin_marked
 
+    @property
+    def _ignore_transaction_warnings(self):
+        return self._connection_variables.get("ignore_transaction_warnings", False)
+
     @property
     def instance(self):
         """Instance to which this connection relates.
@@ -232,7 +239,7 @@ class Connection:
         Args:
             value (bool): True for ReadOnly mode, False for ReadWrite.
         """
-        if self._spanner_transaction_started:
+        if self._read_only != value and self._spanner_transaction_started:
             raise ValueError(
                 "Connection read/write mode can't be changed while a transaction is in progress. "
                 "Commit or rollback the current transaction and try again."
@@ -270,7 +277,7 @@ class Connection:
         Args:
             value (dict): Staleness type and value.
         """
-        if self._spanner_transaction_started:
+        if self._spanner_transaction_started and value != self._staleness:
             raise ValueError(
                 "`staleness` option can't be changed while a transaction is in progress. "
                 "Commit or rollback the current transaction and try again."
@@ -398,9 +405,10 @@ class Connection:
         if self.database is None:
             raise ValueError("Database needs to be passed for this operation")
         if not self._client_transaction_started:
-            warnings.warn(
-                CLIENT_TRANSACTION_NOT_STARTED_WARNING, UserWarning, stacklevel=2
-            )
+            if not self._ignore_transaction_warnings:
+                warnings.warn(
+                    CLIENT_TRANSACTION_NOT_STARTED_WARNING, UserWarning, stacklevel=2
+                )
             return
 
         self.run_prior_DDL_statements()
@@ -418,9 +426,10 @@ class Connection:
         This is a no-op if there is no active client transaction.
         """
         if not self._client_transaction_started:
-            warnings.warn(
-                CLIENT_TRANSACTION_NOT_STARTED_WARNING, UserWarning, stacklevel=2
-            )
+            if not self._ignore_transaction_warnings:
+                warnings.warn(
+                    CLIENT_TRANSACTION_NOT_STARTED_WARNING, UserWarning, stacklevel=2
+                )
             return
         try:
             if self._spanner_transaction_started and not self._read_only:
@@ -654,6 +663,7 @@ def connect(
     user_agent=None,
     client=None,
     route_to_leader_enabled=True,
+    **kwargs,
 ):
     """Creates a connection to a Google Cloud Spanner database.
 
@@ -696,6 +706,8 @@ def connect(
         disable leader aware routing. Disabling leader aware routing would
         route all requests in RW/PDML transactions to the closest region.
 
+    **kwargs: Initial value for connection variables.
+
 
     :rtype: :class:`google.cloud.spanner_dbapi.connection.Connection`
     :returns: Connection object associated with the given Google Cloud Spanner

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

@@ -29,12 +29,19 @@ from .parsed_statement import ParsedStatement, StatementType, Statement
 from .types import DateStr, TimestampStr
 from .utils import sanitize_literals_for_upload
 
+# Note: This mapping deliberately does not contain a value for float.
+# The reason for that is that it is better to just let Spanner determine
+# the parameter type instead of specifying one explicitly. The reason for
+# this is that if the client specifies FLOAT64, and the actual column that
+# the parameter is used for is of type FLOAT32, then Spanner will return an
+# error. If however the client does not specify a type, then Spanner will
+# automatically choose the appropriate type based on the column where the
+# value will be inserted/updated or that it will be compared with.
 TYPES_MAP = {
     bool: spanner.param_types.BOOL,
     bytes: spanner.param_types.BYTES,
     str: spanner.param_types.STRING,
     int: spanner.param_types.INT64,
-    float: spanner.param_types.FLOAT64,
     datetime.datetime: spanner.param_types.TIMESTAMP,
     datetime.date: spanner.param_types.DATE,
     DateStr: spanner.param_types.DATE,

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

@@ -266,66 +266,69 @@ def _parse_value_pb(value_pb, field_type, field_name, column_info=None):
     :returns: value extracted from value_pb
     :raises ValueError: if unknown type is passed
     """
+    decoder = _get_type_decoder(field_type, field_name, column_info)
+    return _parse_nullable(value_pb, decoder)
+
+
+def _get_type_decoder(field_type, field_name, column_info=None):
+    """Returns a function that converts a Value protobuf to cell data.
+
+    :type field_type: :class:`~google.cloud.spanner_v1.types.Type`
+    :param field_type: type code for the value
+
+    :type field_name: str
+    :param field_name: column name
+
+    :type column_info: dict
+    :param column_info: (Optional) dict of column name and column information.
+            An object where column names as keys and custom objects as corresponding
+            values for deserialization. It's specifically useful for data types like
+            protobuf where deserialization logic is on user-specific code. When provided,
+            the custom object enables deserialization of backend-received column data.
+            If not provided, data remains serialized as bytes for Proto Messages and
+            integer for Proto Enums.
+
+    :rtype: a function that takes a single protobuf value as an input argument
+    :returns: a function that can be used to extract a value from a protobuf value
+    :raises ValueError: if unknown type is passed
+    """
+
     type_code = field_type.code
-    if value_pb.HasField("null_value"):
-        return None
     if type_code == TypeCode.STRING:
-        return value_pb.string_value
+        return _parse_string
     elif type_code == TypeCode.BYTES:
-        return value_pb.string_value.encode("utf8")
+        return _parse_bytes
     elif type_code == TypeCode.BOOL:
-        return value_pb.bool_value
+        return _parse_bool
     elif type_code == TypeCode.INT64:
-        return int(value_pb.string_value)
+        return _parse_int64
     elif type_code == TypeCode.FLOAT64:
-        if value_pb.HasField("string_value"):
-            return float(value_pb.string_value)
-        else:
-            return value_pb.number_value
+        return _parse_float
     elif type_code == TypeCode.FLOAT32:
-        if value_pb.HasField("string_value"):
-            return float(value_pb.string_value)
-        else:
-            return value_pb.number_value
+        return _parse_float
     elif type_code == TypeCode.DATE:
-        return _date_from_iso8601_date(value_pb.string_value)
+        return _parse_date
     elif type_code == TypeCode.TIMESTAMP:
-        DatetimeWithNanoseconds = datetime_helpers.DatetimeWithNanoseconds
-        return DatetimeWithNanoseconds.from_rfc3339(value_pb.string_value)
-    elif type_code == TypeCode.ARRAY:
-        return [
-            _parse_value_pb(
-                item_pb, field_type.array_element_type, field_name, column_info
-            )
-            for item_pb in value_pb.list_value.values
-        ]
-    elif type_code == TypeCode.STRUCT:
-        return [
-            _parse_value_pb(
-                item_pb, field_type.struct_type.fields[i].type_, field_name, column_info
-            )
-            for (i, item_pb) in enumerate(value_pb.list_value.values)
-        ]
+        return _parse_timestamp
     elif type_code == TypeCode.NUMERIC:
-        return decimal.Decimal(value_pb.string_value)
+        return _parse_numeric
     elif type_code == TypeCode.JSON:
-        return JsonObject.from_str(value_pb.string_value)
+        return _parse_json
     elif type_code == TypeCode.PROTO:
-        bytes_value = base64.b64decode(value_pb.string_value)
-        if column_info is not None and column_info.get(field_name) is not None:
-            default_proto_message = column_info.get(field_name)
-            if isinstance(default_proto_message, Message):
-                proto_message = type(default_proto_message)()
-                proto_message.ParseFromString(bytes_value)
-                return proto_message
-        return bytes_value
+        return lambda value_pb: _parse_proto(value_pb, column_info, field_name)
     elif type_code == TypeCode.ENUM:
-        int_value = int(value_pb.string_value)
-        if column_info is not None and column_info.get(field_name) is not None:
-            proto_enum = column_info.get(field_name)
-            if isinstance(proto_enum, EnumTypeWrapper):
-                return proto_enum.Name(int_value)
-        return int_value
+        return lambda value_pb: _parse_proto_enum(value_pb, column_info, field_name)
+    elif type_code == TypeCode.ARRAY:
+        element_decoder = _get_type_decoder(
+            field_type.array_element_type, field_name, column_info
+        )
+        return lambda value_pb: _parse_array(value_pb, element_decoder)
+    elif type_code == TypeCode.STRUCT:
+        element_decoders = [
+            _get_type_decoder(item_field.type_, field_name, column_info)
+            for item_field in field_type.struct_type.fields
+        ]
+        return lambda value_pb: _parse_struct(value_pb, element_decoders)
     else:
         raise ValueError("Unknown type: %s" % (field_type,))
 
@@ -351,6 +354,87 @@ def _parse_list_value_pbs(rows, row_type):
     return result
 
 
+def _parse_string(value_pb) -> str:
+    return value_pb.string_value
+
+
+def _parse_bytes(value_pb):
+    return value_pb.string_value.encode("utf8")
+
+
+def _parse_bool(value_pb) -> bool:
+    return value_pb.bool_value
+
+
+def _parse_int64(value_pb) -> int:
+    return int(value_pb.string_value)
+
+
+def _parse_float(value_pb) -> float:
+    if value_pb.HasField("string_value"):
+        return float(value_pb.string_value)
+    else:
+        return value_pb.number_value
+
+
+def _parse_date(value_pb):
+    return _date_from_iso8601_date(value_pb.string_value)
+
+
+def _parse_timestamp(value_pb):
+    DatetimeWithNanoseconds = datetime_helpers.DatetimeWithNanoseconds
+    return DatetimeWithNanoseconds.from_rfc3339(value_pb.string_value)
+
+
+def _parse_numeric(value_pb):
+    return decimal.Decimal(value_pb.string_value)
+
+
+def _parse_json(value_pb):
+    return JsonObject.from_str(value_pb.string_value)
+
+
+def _parse_proto(value_pb, column_info, field_name):
+    bytes_value = base64.b64decode(value_pb.string_value)
+    if column_info is not None and column_info.get(field_name) is not None:
+        default_proto_message = column_info.get(field_name)
+        if isinstance(default_proto_message, Message):
+            proto_message = type(default_proto_message)()
+            proto_message.ParseFromString(bytes_value)
+            return proto_message
+    return bytes_value
+
+
+def _parse_proto_enum(value_pb, column_info, field_name):
+    int_value = int(value_pb.string_value)
+    if column_info is not None and column_info.get(field_name) is not None:
+        proto_enum = column_info.get(field_name)
+        if isinstance(proto_enum, EnumTypeWrapper):
+            return proto_enum.Name(int_value)
+    return int_value
+
+
+def _parse_array(value_pb, element_decoder) -> []:
+    return [
+        _parse_nullable(item_pb, element_decoder)
+        for item_pb in value_pb.list_value.values
+    ]
+
+
+def _parse_struct(value_pb, element_decoders):
+    return [
+        _parse_nullable(item_pb, element_decoders[i])
+        for (i, item_pb) in enumerate(value_pb.list_value.values)
+    ]
+
+
+def _parse_nullable(value_pb, decoder):
+    if value_pb.HasField("null_value"):
+        return None
+    else:
+        return decoder(value_pb)
+
+
 class _SessionWrapper(object):
     """Base class for objects wrapping a session.
 

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

@@ -15,6 +15,8 @@
 """Manages OpenTelemetry trace creation and handling"""
 
 from contextlib import contextmanager
+from datetime import datetime
+import os
 
 from google.cloud.spanner_v1 import SpannerClient
 from google.cloud.spanner_v1 import gapic_version
@@ -33,6 +35,9 @@ except ImportError:
 
 TRACER_NAME = "cloud.google.com/python/spanner"
 TRACER_VERSION = gapic_version.__version__
+extended_tracing_globally_disabled = (
+    os.getenv("SPANNER_ENABLE_EXTENDED_TRACING", "").lower() == "false"
+)
 
 
 def get_tracer(tracer_provider=None):
@@ -51,13 +56,29 @@ def get_tracer(tracer_provider=None):
 
 
 @contextmanager
-def trace_call(name, session, extra_attributes=None):
+def trace_call(name, session, extra_attributes=None, observability_options=None):
+    if session:
+        session._last_use_time = datetime.now()
+
     if not HAS_OPENTELEMETRY_INSTALLED or not session:
         # Empty context manager. Users will have to check if the generated value is None or a span
         yield None
         return
 
-    tracer = get_tracer()
+    tracer_provider = None
+
+    # By default enable_extended_tracing=True because in a bid to minimize
+    # breaking changes and preserve legacy behavior, we are keeping it turned
+    # on by default.
+    enable_extended_tracing = True
+
+    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
+        )
+
+    tracer = get_tracer(tracer_provider)
 
     # Set base attributes that we know for every trace created
     attributes = {
@@ -72,6 +93,12 @@ def trace_call(name, session, extra_attributes=None):
     if extra_attributes:
         attributes.update(extra_attributes)
 
+    if extended_tracing_globally_disabled:
+        enable_extended_tracing = False
+
+    if not enable_extended_tracing:
+        attributes.pop("db.statement", False)
+
     with tracer.start_as_current_span(
         name, kind=trace.SpanKind.CLIENT, attributes=attributes
     ) as span:

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

@@ -205,7 +205,13 @@ class Batch(_BatchBase):
             max_commit_delay=max_commit_delay,
             request_options=request_options,
         )
-        with trace_call("CloudSpanner.Commit", self._session, trace_attributes):
+        observability_options = getattr(database, "observability_options", None)
+        with trace_call(
+            "CloudSpanner.Commit",
+            self._session,
+            trace_attributes,
+            observability_options=observability_options,
+        ):
             method = functools.partial(
                 api.commit,
                 request=request,
@@ -318,7 +324,13 @@ class MutationGroups(_SessionWrapper):
             request_options=request_options,
             exclude_txn_from_change_streams=exclude_txn_from_change_streams,
         )
-        with trace_call("CloudSpanner.BatchWrite", self._session, trace_attributes):
+        observability_options = getattr(database, "observability_options", None)
+        with trace_call(
+            "CloudSpanner.BatchWrite",
+            self._session,
+            trace_attributes,
+            observability_options=observability_options,
+        ):
             method = functools.partial(
                 api.batch_write,
                 request=request,

{google_cloud_spanner-3.50.1 → google_cloud_spanner-3.51.0}/google/cloud/spanner_v1/client.py

@@ -126,6 +126,16 @@ class Client(ClientWithProject):
             for all ReadRequests and ExecuteSqlRequests that indicates which replicas
             or regions should be used for non-transactional reads or queries.
 
+    :type observability_options: dict (str -> any) or None
+    :param observability_options: (Optional) the configuration to control
+           the tracer's behavior.
+           tracer_provider is the injected tracer provider
+           enable_extended_tracing: :type:boolean when set to true will allow for
+           spans that issue SQL statements to be annotated with SQL.
+           Default `True`, please set it to `False` to turn it off
+           or you can use the environment variable `SPANNER_ENABLE_EXTENDED_TRACING=<boolean>`
+           to control it.
+
     :raises: :class:`ValueError <exceptions.ValueError>` if both ``read_only``
              and ``admin`` are :data:`True`
     """
@@ -146,6 +156,7 @@ class Client(ClientWithProject):
         query_options=None,
         route_to_leader_enabled=True,
         directed_read_options=None,
+        observability_options=None,
     ):
         self._emulator_host = _get_spanner_emulator_host()
 
@@ -187,6 +198,7 @@ class Client(ClientWithProject):
 
         self._route_to_leader_enabled = route_to_leader_enabled
         self._directed_read_options = directed_read_options
+        self._observability_options = observability_options
 
     @property
     def credentials(self):
@@ -268,6 +280,15 @@ class Client(ClientWithProject):
         """
         return self._route_to_leader_enabled
 
+    @property
+    def observability_options(self):
+        """Getter for observability_options.
+
+        :rtype: dict
+        :returns: The configured observability_options if set.
+        """
+        return self._observability_options
+
     @property
     def directed_read_options(self):
         """Getter for directed_read_options.

{google_cloud_spanner-3.50.1 → google_cloud_spanner-3.51.0}/google/cloud/spanner_v1/database.py

@@ -142,7 +142,7 @@ class Database(object):
                               statements in 'ddl_statements' above.
     """
 
-    _spanner_api = None
+    _spanner_api: SpannerClient = None
 
     def __init__(
         self,
@@ -718,6 +718,7 @@ class Database(object):
                     method=method,
                     request=request,
                     transaction_selector=txn_selector,
+                    observability_options=self.observability_options,
                 )
 
                 result_set = StreamedResultSet(iterator)
@@ -1106,6 +1107,17 @@ class Database(object):
         response = api.set_iam_policy(request=request, metadata=metadata)
         return response
 
+    @property
+    def observability_options(self):
+        """
+        Returns the observability options that you set when creating
+        the SpannerClient.
+        """
+        if not (self._instance and self._instance._client):
+            return None
+
+        return getattr(self._instance._client, "observability_options", None)
+
 
 class BatchCheckout(object):
     """Context manager for using a batch from a database.

{google_cloud_spanner-3.50.1 → google_cloud_spanner-3.51.0}/google/cloud/spanner_v1/gapic_version.py

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

{google_cloud_spanner-3.50.1 → google_cloud_spanner-3.51.0}/google/cloud/spanner_v1/pool.py

@@ -145,7 +145,8 @@ class FixedSizePool(AbstractSessionPool):
     - Pre-allocates / creates a fixed number of sessions.
 
     - "Pings" existing sessions via :meth:`session.exists` before returning
-      them, and replaces expired sessions.
+      sessions that have not been used for more than 55 minutes and replaces
+      expired sessions.
 
     - Blocks, with a timeout, when :meth:`get` is called on an empty pool.
       Raises after timing out.
@@ -171,6 +172,7 @@ class FixedSizePool(AbstractSessionPool):
 
     DEFAULT_SIZE = 10
     DEFAULT_TIMEOUT = 10
+    DEFAULT_MAX_AGE_MINUTES = 55
 
     def __init__(
         self,
@@ -178,11 +180,13 @@ class FixedSizePool(AbstractSessionPool):
         default_timeout=DEFAULT_TIMEOUT,
         labels=None,
         database_role=None,
+        max_age_minutes=DEFAULT_MAX_AGE_MINUTES,
     ):
         super(FixedSizePool, self).__init__(labels=labels, database_role=database_role)
         self.size = size
         self.default_timeout = default_timeout
         self._sessions = queue.LifoQueue(size)
+        self._max_age = datetime.timedelta(minutes=max_age_minutes)
 
     def bind(self, database):
         """Associate the pool with a database.
@@ -230,8 +234,9 @@ class FixedSizePool(AbstractSessionPool):
             timeout = self.default_timeout
 
         session = self._sessions.get(block=True, timeout=timeout)
+        age = _NOW() - session.last_use_time
 
-        if not session.exists():
+        if age >= self._max_age and not session.exists():
             session = self._database.session()
             session.create()
 

{google_cloud_spanner-3.50.1 → google_cloud_spanner-3.51.0}/google/cloud/spanner_v1/session.py

@@ -17,6 +17,7 @@
 from functools import total_ordering
 import random
 import time
+from datetime import datetime
 
 from google.api_core.exceptions import Aborted
 from google.api_core.exceptions import GoogleAPICallError
@@ -69,6 +70,7 @@ class Session(object):
             labels = {}
         self._labels = labels
         self._database_role = database_role
+        self._last_use_time = datetime.utcnow()
 
     def __lt__(self, other):
         return self._session_id < other._session_id
@@ -78,6 +80,14 @@ class Session(object):
         """Read-only ID, set by the back-end during :meth:`create`."""
         return self._session_id
 
+    @property
+    def last_use_time(self):
+        """ "Approximate last use time of this session
+
+        :rtype: datetime
+        :returns: the approximate last use time of this session"""
+        return self._last_use_time
+
     @property
     def database_role(self):
         """User-assigned database-role for the session.
@@ -142,7 +152,13 @@ class Session(object):
         if self._labels:
             request.session.labels = self._labels
 
-        with trace_call("CloudSpanner.CreateSession", self, self._labels):
+        observability_options = getattr(self._database, "observability_options", None)
+        with trace_call(
+            "CloudSpanner.CreateSession",
+            self,
+            self._labels,
+            observability_options=observability_options,
+        ):
             session_pb = api.create_session(
                 request=request,
                 metadata=metadata,
@@ -169,7 +185,10 @@ class Session(object):
                 )
             )
 
-        with trace_call("CloudSpanner.GetSession", self) as span:
+        observability_options = getattr(self._database, "observability_options", None)
+        with trace_call(
+            "CloudSpanner.GetSession", self, observability_options=observability_options
+        ) as span:
             try:
                 api.get_session(name=self.name, metadata=metadata)
                 if span:
@@ -194,7 +213,12 @@ class Session(object):
             raise ValueError("Session ID not set by back-end")
         api = self._database.spanner_api
         metadata = _metadata_with_prefix(self._database.name)
-        with trace_call("CloudSpanner.DeleteSession", self):
+        observability_options = getattr(self._database, "observability_options", None)
+        with trace_call(
+            "CloudSpanner.DeleteSession",
+            self,
+            observability_options=observability_options,
+        ):
             api.delete_session(name=self.name, metadata=metadata)
 
     def ping(self):
@@ -208,6 +232,7 @@ class Session(object):
         metadata = _metadata_with_prefix(self._database.name)
         request = ExecuteSqlRequest(session=self.name, sql="SELECT 1")
         api.execute_sql(request=request, metadata=metadata)
+        self._last_use_time = datetime.now()
 
     def snapshot(self, **kw):
         """Create a snapshot to perform a set of reads with shared staleness.