docs: fix docstring types and typos (#259)

larkee · web-flow · commit 1b0ce1d29860 · 2021-03-17T23:48:48.000+11:00
* docs: fix docstring types

* docs: fix typos

* docs: correctly reference logging.Logger type

* docs: fix pool bind parameter docstring

Co-authored-by: larkee &lt;larkee@users.noreply.github.com&gt;
diff --git a/google/cloud/spanner_v1/_helpers.py b/google/cloud/spanner_v1/_helpers.py
@@ -53,19 +53,19 @@ def _merge_query_options(base, merge):
     """Merge higher precedence QueryOptions with current QueryOptions.
 
     :type base:
-        :class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
+        :class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
         or :class:`dict` or None
     :param base: The current QueryOptions that is intended for use.
 
     :type merge:
-        :class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
+        :class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
         or :class:`dict` or None
     :param merge:
         The QueryOptions that have a higher priority than base. These options
         should overwrite the fields in base.
 
     :rtype:
-        :class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
+        :class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
         or None
     :returns:
         QueryOptions object formed by merging the two given QueryOptions.
@@ -167,7 +167,7 @@ def _parse_value_pb(value_pb, field_type):
     :type value_pb: :class:`~google.protobuf.struct_pb2.Value`
     :param value_pb: protobuf to convert
 
-    :type field_type: :class:`~google.cloud.spanner_v1.Type`
+    :type field_type: :class:`~google.cloud.spanner_v1.types.Type`
     :param field_type: type code for the value
 
     :rtype: varies on field_type
@@ -220,7 +220,7 @@ def _parse_list_value_pbs(rows, row_type):
     :type rows: list of :class:`~google.protobuf.struct_pb2.ListValue`
     :param rows: row data returned from a read/query
 
-    :type row_type: :class:`~google.cloud.spanner_v1.StructType`
+    :type row_type: :class:`~google.cloud.spanner_v1.types.StructType`
     :param row_type: row schema specification
 
     :rtype: list of list of cell data
diff --git a/google/cloud/spanner_v1/backup.py b/google/cloud/spanner_v1/backup.py
@@ -141,7 +141,7 @@ def size_bytes(self):
     def state(self):
         """State of this backup.
 
-        :rtype: :class:`~google.cloud.spanner_admin_database_v1.Backup.State`
+        :rtype: :class:`~google.cloud.spanner_admin_database_v1.types.Backup.State`
         :returns: an enum describing the state of the backup
         """
         return self._state
@@ -160,7 +160,7 @@ def referencing_databases(self):
     def from_pb(cls, backup_pb, instance):
         """Create an instance of this class from a protobuf message.
 
-        :type backup_pb: :class:`~google.spanner.admin.database.v1.Backup`
+        :type backup_pb: :class:`~google.cloud.spanner_admin_database_v1.types.Backup`
         :param backup_pb: A backup protobuf object.
 
         :type instance: :class:`~google.cloud.spanner_v1.instance.Instance`
diff --git a/google/cloud/spanner_v1/batch.py b/google/cloud/spanner_v1/batch.py
@@ -179,7 +179,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):
 
 
 def _make_write_pb(table, columns, values):
-    """Helper for :meth:`Batch.insert` et aliae.
+    """Helper for :meth:`Batch.insert` et al.
 
     :type table: str
     :param table: Name of the table to be modified.
@@ -190,7 +190,7 @@ def _make_write_pb(table, columns, values):
     :type values: list of lists
     :param values: Values to be modified.
 
-    :rtype: :class:`google.cloud.spanner_v1.Mutation.Write`
+    :rtype: :class:`google.cloud.spanner_v1.types.Mutation.Write`
     :returns: Write protobuf
     """
     return Mutation.Write(
diff --git a/google/cloud/spanner_v1/client.py b/google/cloud/spanner_v1/client.py
@@ -108,12 +108,12 @@ class Client(ClientWithProject):
         on the client. API Endpoint should be set through client_options.
 
     :type query_options:
-        :class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
+        :class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
         or :class:`dict`
     :param query_options:
         (Optional) Query optimizer configuration to use for the given query.
         If a dict is provided, it must be of the same form as the protobuf
-        message :class:`~google.cloud.spanner_v1.QueryOptions`
+        message :class:`~google.cloud.spanner_v1.types.QueryOptions`
 
     :raises: :class:`ValueError <exceptions.ValueError>` if both ``read_only``
              and ``admin`` are :data:`True`
@@ -348,7 +348,7 @@ def list_instances(self, filter_="", page_size=None):
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns:
-            Iterator of :class:`~google.cloud.spanner_v1.instance.Instance`
+            Iterator of :class:`~google.cloud.spanner_admin_instance_v1.types.Instance`
             resources within the client's project.
         """
         metadata = _metadata_with_prefix(self.project_name)
diff --git a/google/cloud/spanner_v1/database.py b/google/cloud/spanner_v1/database.py
@@ -103,7 +103,7 @@ class Database(object):
                  passed, the database will construct an instance of
                  :class:`~google.cloud.spanner_v1.pool.BurstyPool`.
 
-    :type logger: `logging.Logger`
+    :type logger: :class:`logging.Logger`
     :param logger: (Optional) a custom logger that is used if `log_commit_stats`
                    is `True` to log commit statistics. If not passed, a logger
                    will be created when needed that will log the commit statistics
@@ -138,7 +138,7 @@ def from_pb(cls, database_pb, instance, pool=None):
         """Creates an instance of this class from a protobuf.
 
         :type database_pb:
-            :class:`~google.cloud.spanner_admin_instance_v1.Instance`
+            :class:`~google.cloud.spanner_admin_instance_v1.types.Instance`
         :param database_pb: A instance protobuf object.
 
         :type instance: :class:`~google.cloud.spanner_v1.instance.Instance`
@@ -199,7 +199,7 @@ def name(self):
     def state(self):
         """State of this database.
 
-        :rtype: :class:`~google.cloud.spanner_admin_database_v1.Database.State`
+        :rtype: :class:`~google.cloud.spanner_admin_database_v1.types.Database.State`
         :returns: an enum describing the state of the database
         """
         return self._state
@@ -218,7 +218,7 @@ def create_time(self):
     def restore_info(self):
         """Restore info for this database.
 
-        :rtype: :class:`~google.cloud.spanner_v1.database.RestoreInfo`
+        :rtype: :class:`~google.cloud.spanner_v1.types.RestoreInfo`
         :returns: an object representing the restore info for this database
         """
         return self._restore_info
@@ -310,7 +310,7 @@ def __ne__(self, other):
     def create(self):
         """Create this database within its instance
 
-        Inclues any configured schema assigned to :attr:`ddl_statements`.
+        Includes any configured schema assigned to :attr:`ddl_statements`.
 
         See
         https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase
@@ -429,12 +429,12 @@ def execute_partitioned_dml(
             required if parameters are passed.
 
         :type query_options:
-            :class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
+            :class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
             or :class:`dict`
         :param query_options:
                 (Optional) Query optimizer configuration to use for the given query.
                 If a dict is provided, it must be of the same form as the protobuf
-                message :class:`~google.cloud.spanner_v1.QueryOptions`
+                message :class:`~google.cloud.spanner_v1.types.QueryOptions`
 
         :rtype: int
         :returns: Count of rows affected by the DML statement.
@@ -568,7 +568,7 @@ def run_in_transaction(self, func, *args, **kw):
         :returns: The return value of ``func``.
 
         :raises Exception:
-            reraises any non-ABORT execptions raised by ``func``.
+            reraises any non-ABORT exceptions raised by ``func``.
         """
         # Sanity check: Is there a transaction already running?
         # If there is, then raise a red flag. Otherwise, mark that this one
@@ -895,7 +895,7 @@ def generate_read_batches(
 
         :rtype: iterable of dict
         :returns:
-            mappings of information used peform actual partitioned reads via
+            mappings of information used perform actual partitioned reads via
             :meth:`process_read_batch`.
         """
         partitions = self._get_snapshot().partition_read(
@@ -945,7 +945,7 @@ def generate_query_batches(
 
         Uses the ``PartitionQuery`` API request to start a partitioned
         query operation.  Returns a list of batch information needed to
-        peform the actual queries.
+        perform the actual queries.
 
         :type sql: str
         :param sql: SQL query statement
@@ -976,16 +976,16 @@ def generate_query_batches(
             differ.
 
         :type query_options:
-            :class:`~google.cloud.spanner_v1.ExecuteSqlRequest.QueryOptions`
+            :class:`~google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions`
             or :class:`dict`
         :param query_options:
                 (Optional) Query optimizer configuration to use for the given query.
                 If a dict is provided, it must be of the same form as the protobuf
-                message :class:`~google.cloud.spanner_v1.QueryOptions`
+                message :class:`~google.cloud.spanner_v1.types.QueryOptions`
 
         :rtype: iterable of dict
         :returns:
-            mappings of information used peform actual partitioned reads via
+            mappings of information used perform actual partitioned reads via
             :meth:`process_read_batch`.
         """
         partitions = self._get_snapshot().partition_query(
@@ -1065,7 +1065,7 @@ def _check_ddl_statements(value):
     https://cloud.google.com/spanner/docs/data-definition-language
 
     :type value: list of string
-    :param value: DDL statements, excluding the 'CREATE DATABSE' statement
+    :param value: DDL statements, excluding the 'CREATE DATABASE' statement
 
     :rtype: tuple
     :returns: tuple of validated DDL statement strings.
diff --git a/google/cloud/spanner_v1/instance.py b/google/cloud/spanner_v1/instance.py
@@ -349,7 +349,7 @@ def delete(self):
 
         Soon afterward:
 
-        * The instance and all databases within the instance will be deleteed.
+        * The instance and all databases within the instance will be deleted.
           All data in the databases will be permanently deleted.
         """
         api = self._client.instance_admin_api
@@ -365,13 +365,13 @@ def database(self, database_id, ddl_statements=(), pool=None, logger=None):
 
         :type ddl_statements: list of string
         :param ddl_statements: (Optional) DDL statements, excluding the
-                               'CREATE DATABSE' statement.
+                               'CREATE DATABASE' statement.
 
         :type pool: concrete subclass of
                     :class:`~google.cloud.spanner_v1.pool.AbstractSessionPool`.
         :param pool: (Optional) session pool to be used by database.
 
-        :type logger: `logging.Logger`
+        :type logger: :class:`logging.Logger`
         :param logger: (Optional) a custom logger that is used if `log_commit_stats`
                        is `True` to log commit statistics. If not passed, a logger
                        will be created when needed that will log the commit statistics
@@ -398,7 +398,7 @@ def list_databases(self, page_size=None):
 
         :rtype: :class:`~google.api._ore.page_iterator.Iterator`
         :returns:
-            Iterator of :class:`~google.cloud.spanner_v1.database.Database`
+            Iterator of :class:`~google.cloud.spanner_admin_database_v1.types.Database`
             resources within the current instance.
         """
         metadata = _metadata_with_prefix(self.name)
@@ -429,6 +429,9 @@ def backup(self, backup_id, database="", expire_time=None, version_time=None):
             Optional. The version time that will be used to create the externally
             consistent copy of the database. If not present, it is the same as
             the `create_time` of the backup.
+
+        :rtype: :class:`~google.cloud.spanner_v1.backup.Backup`
+        :returns: a backup owned by this instance.
         """
         try:
             return Backup(
@@ -462,7 +465,7 @@ def list_backups(self, filter_="", page_size=None):
 
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns:
-            Iterator of :class:`~google.cloud.spanner_v1.backup.Backup`
+            Iterator of :class:`~google.cloud.spanner_admin_database_v1.types.Backup`
             resources within the current instance.
         """
         metadata = _metadata_with_prefix(self.name)
diff --git a/google/cloud/spanner_v1/keyset.py b/google/cloud/spanner_v1/keyset.py
@@ -68,7 +68,7 @@ def __init__(
     def _to_pb(self):
         """Construct a KeyRange protobuf.
 
-        :rtype: :class:`~google.cloud.spanner_v1.KeyRange`
+        :rtype: :class:`~google.cloud.spanner_v1.types.KeyRange`
         :returns: protobuf corresponding to this instance.
         """
         kwargs = {}
@@ -88,7 +88,7 @@ def _to_pb(self):
         return KeyRangePB(**kwargs)
 
     def _to_dict(self):
-        """Return keyrange's state as a dict.
+        """Return the state of the keyrange as a dict.
 
         :rtype: dict
         :returns: state of this instance.
@@ -139,7 +139,7 @@ def __init__(self, keys=(), ranges=(), all_=False):
     def _to_pb(self):
         """Construct a KeySet protobuf.
 
-        :rtype: :class:`~google.cloud.spanner_v1.KeySet`
+        :rtype: :class:`~google.cloud.spanner_v1.types.KeySet`
         :returns: protobuf corresponding to this instance.
         """
         if self.all_:
@@ -155,7 +155,7 @@ def _to_pb(self):
         return KeySetPB(**kwargs)
 
     def _to_dict(self):
-        """Return keyset's state as a dict.
+        """Return the state of the keyset as a dict.
 
         The result can be used to serialize the instance and reconstitute
         it later using :meth:`_from_dict`.
diff --git a/google/cloud/spanner_v1/param_types.py b/google/cloud/spanner_v1/param_types.py
@@ -33,10 +33,10 @@
 def Array(element_type):  # pylint: disable=invalid-name
     """Construct an array parameter type description protobuf.
 
-    :type element_type: :class:`~google.cloud.spanner_v1.Type`
+    :type element_type: :class:`~google.cloud.spanner_v1.types.Type`
     :param element_type: the type of elements of the array
 
-    :rtype: :class:`google.cloud.spanner_v1.Type`
+    :rtype: :class:`google.cloud.spanner_v1.types.Type`
     :returns: the appropriate array-type protobuf
     """
     return Type(code=TypeCode.ARRAY, array_element_type=element_type)
@@ -48,10 +48,10 @@ def StructField(name, field_type):  # pylint: disable=invalid-name
     :type name: str
     :param name: the name of the field
 
-    :type field_type: :class:`google.cloud.spanner_v1.Type`
+    :type field_type: :class:`google.cloud.spanner_v1.types.Type`
     :param field_type: the type of the field
 
-    :rtype: :class:`google.cloud.spanner_v1.StructType.Field`
+    :rtype: :class:`google.cloud.spanner_v1.types.StructType.Field`
     :returns: the appropriate struct-field-type protobuf
     """
     return StructType.Field(name=name, type_=field_type)
@@ -60,7 +60,7 @@ def StructField(name, field_type):  # pylint: disable=invalid-name
 def Struct(fields):  # pylint: disable=invalid-name
     """Construct a struct parameter type description protobuf.
 
-    :type fields: list of :class:`google.cloud.spanner_v1.StructType.Field`
+    :type fields: list of :class:`google.cloud.spanner_v1.types.StructType.Field`
     :param fields: the fields of the struct
 
     :rtype: :class:`type_pb2.Type`
diff --git a/google/cloud/spanner_v1/pool.py b/google/cloud/spanner_v1/pool.py
@@ -42,7 +42,7 @@ def __init__(self, labels=None):
 
     @property
     def labels(self):
-        """User-assigned labels for sesions created by the pool.
+        """User-assigned labels for sessions created by the pool.
 
         :rtype: dict (str -> str)
         :returns: labels assigned by the user
@@ -53,7 +53,7 @@ def bind(self, database):
         """Associate the pool with a database.
 
         :type database: :class:`~google.cloud.spanner_v1.database.Database`
-        :param database: database used by the pool:  used to create sessions
+        :param database: database used by the pool to create sessions
                          when needed.
 
         Concrete implementations of this method may pre-fill the pool
@@ -162,7 +162,7 @@ def bind(self, database):
         """Associate the pool with a database.
 
         :type database: :class:`~google.cloud.spanner_v1.database.Database`
-        :param database: database used by the pool:  used to create sessions
+        :param database: database used by the pool to used to create sessions
                          when needed.
         """
         self._database = database
@@ -256,7 +256,7 @@ def bind(self, database):
         """Associate the pool with a database.
 
         :type database: :class:`~google.cloud.spanner_v1.database.Database`
-        :param database: database used by the pool:  used to create sessions
+        :param database: database used by the pool to create sessions
                          when needed.
         """
         self._database = database
@@ -354,7 +354,7 @@ def bind(self, database):
         """Associate the pool with a database.
 
         :type database: :class:`~google.cloud.spanner_v1.database.Database`
-        :param database: database used by the pool:  used to create sessions
+        :param database: database used by the pool to create sessions
                          when needed.
         """
         self._database = database
@@ -486,7 +486,7 @@ def bind(self, database):
         """Associate the pool with a database.
 
         :type database: :class:`~google.cloud.spanner_v1.database.Database`
-        :param database: database used by the pool:  used to create sessions
+        :param database: database used by the pool to create sessions
                          when needed.
         """
         super(TransactionPingingPool, self).bind(database)
diff --git a/google/cloud/spanner_v1/session.py b/google/cloud/spanner_v1/session.py
diff --git a/google/cloud/spanner_v1/snapshot.py b/google/cloud/spanner_v1/snapshot.py
diff --git a/google/cloud/spanner_v1/streamed.py b/google/cloud/spanner_v1/streamed.py
diff --git a/google/cloud/spanner_v1/transaction.py b/google/cloud/spanner_v1/transaction.py
