fix(spanner): comment refactoring

google/cloud/spanner_v1/_helpers.py

@@ -254,7 +254,13 @@ def _parse_value_pb(value_pb, field_type, field_name, column_info=None):
     :param field_name: column name
 
     :type column_info: dict
-    :param column_info: (Optional) dict of column name and column information
+    :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: varies on field_type
     :returns: value extracted from value_pb

google/cloud/spanner_v1/session.py

@@ -248,7 +248,13 @@ def read(self, table, columns, keyset, index="", limit=0, column_info=None):
         :param limit: (Optional) maximum number of rows to return
 
         :type column_info: dict
-        :param column_info: (Optional) dict of mapping between column names and additional column information
+        :param column_info: (Optional) dict of mapping between column names and additional 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: :class:`~google.cloud.spanner_v1.streamed.StreamedResultSet`
         :returns: a result set instance which can be used to consume rows.
@@ -308,7 +314,13 @@ def execute_sql(
         :param timeout: (Optional) The timeout for this request.
 
         :type column_info: dict
-        :param column_info: (Optional) dict of mapping between column names and additional column information
+        :param column_info: (Optional) dict of mapping between column names and additional 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: :class:`~google.cloud.spanner_v1.streamed.StreamedResultSet`
         :returns: a result set instance which can be used to consume rows.

google/cloud/spanner_v1/snapshot.py

@@ -233,7 +233,13 @@ def read(
             or regions should be used for non-transactional reads or queries.
 
         :type column_info: dict
-        :param column_info: (Optional) dict of mapping between column names and additional column information
+        :param column_info: (Optional) dict of mapping between column names and additional 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: :class:`~google.cloud.spanner_v1.streamed.StreamedResultSet`
         :returns: a result set instance which can be used to consume rows.
@@ -407,7 +413,13 @@ def execute_sql(
             or regions should be used for non-transactional reads or queries.
 
         :type column_info: dict
-        :param column_info: (Optional) dict of mapping between column names and additional column information
+        :param column_info: (Optional) dict of mapping between column names and additional 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.
 
         :raises ValueError:
             for reuse of single-use snapshots, or if a transaction ID is

samples/samples/snippets.py

@@ -3356,6 +3356,12 @@ def query_data_with_proto_types_parameter(instance_id, database_id):
                 "country": param_types.STRING,
                 "singerGenre": param_types.ProtoEnum(singer_pb2.Genre),
             },
+            # column_info is an optional parameter and is used to deserialize
+            # the proto message and enum object back from bytearray and
+            # int respectively.
+            # If column_info is not passed for proto messages and enums, then
+            # the data types for these columns will be bytes and int
+            # respectively.
             column_info={
                 "SingerInfo": singer_pb2.SingerInfo(),
                 "SingerInfoArray": singer_pb2.SingerInfo(),
@@ -3366,8 +3372,10 @@ def query_data_with_proto_types_parameter(instance_id, database_id):
 
         for row in results:
             print(
-                "SingerId: {}, SingerInfo: {}, SingerGenre: {}, "
-                "SingerInfoArray: {}, SingerGenreArray: {}".format(*row)
+                "SingerId: {}, SingerInfo: {}, SingerInfoNationality: {}, "
+                "SingerInfoArray: {}, SingerGenre: {}, SingerGenreArray: {}".format(
+                    *row
+                )
             )
     # [END spanner_query_with_proto_types_parameter]
 

tests/_fixtures.py

@@ -91,8 +91,6 @@
     ) PRIMARY KEY (CartId);
 """
 
-# TODO: Add Proto Bundle DDL statement in EMULATOR_DDL once b/338557401
-# is fixed.
 EMULATOR_DDL = """\
 CREATE TABLE contacts (
     contact_id INT64,