docs: missing docstrings for functions & classes

google/cloud/spanner_dbapi/connection.py

@@ -44,6 +44,12 @@ def __init__(self, instance, database):
         self._ddl_statements = []
 
     def cursor(self):
+        """Factory to create a :class:`Cursor` linked to this Connection.
+
+        :rtype: :class:`Cursor`
+        :returns: A database cursor, which is used to manage the context of a
+                  fetch operation.
+        """
         self._raise_if_closed()
 
         return Cursor(self)
@@ -63,28 +69,61 @@ def __handle_update_ddl(self, ddl_statements):
         """
         Run the list of Data Definition Language (DDL) statements on the underlying
         database. Each DDL statement MUST NOT contain a semicolon.
-        Args:
-            ddl_statements: a list of DDL statements, each without a semicolon.
-        Returns:
-            google.api_core.operation.Operation.result()
+
+        :type ddl_statements: list
+        :param ddl_statements: A list of DDL statements, each without a
+                               semicolon.
         """
         self._raise_if_closed()
         # Synchronously wait on the operation's completion.
         return self.database.update_ddl(ddl_statements).result()
 
     def read_snapshot(self):
+        """Return a Snapshot of the linked Database.
+
+        :rtype: :class:`~google.cloud.spanner_v1.snapshot.Snapshot`
+        :returns: A snapshot of the linked Database.
+        """
         self._raise_if_closed()
         return self.database.snapshot()
 
     def in_transaction(self, fn, *args, **kwargs):
+        """Perform a unit of work in the Transaction, retrying on abort.
+
+        :type fn: callable
+        :param fn: takes a required positional argument, the transaction,
+                   and additional positional / keyword arguments as supplied
+                   by the caller.
+
+        :type args: tuple
+        :param args: additional positional arguments to be passed to ``fn``.
+
+        :type kwargs: dict
+        :param kwargs: (Optional) keyword arguments to be passed to ``fn``.
+                         If passed, "timeout_secs" will be removed and used to
+                         override the default retry timeout which defines
+                         maximum timestamp to continue retrying the transaction.
+
+        :rtype: Any
+        :returns: Runs the given function as it would be a transaction.
+        """
         self._raise_if_closed()
         return self.database.run_in_transaction(fn, *args, **kwargs)
 
     def append_ddl_statement(self, ddl_statement):
+        """
+        Append a DDL statement to the existing list of DDL statements in
+        the linked database.
+
+        :type ddl_statements: list
+        :param ddl_statements: A list of DDL statements, each without a
+                               semicolon.
+        """
         self._raise_if_closed()
         self._ddl_statements.append(ddl_statement)
 
     def run_prior_DDL_statements(self):
+        """Run prior DDL statements."""
         self._raise_if_closed()
 
         if not self._ddl_statements:
@@ -96,6 +135,11 @@ def run_prior_DDL_statements(self):
         return self.__handle_update_ddl(ddl_statements)
 
     def list_tables(self):
+        """List tables contained within the linked Database.
+
+        :rtype: list
+        :returns: Tables with corresponding information.
+        """
         return self.run_sql_in_snapshot(
             """
             SELECT
@@ -108,6 +152,21 @@ def list_tables(self):
         )
 
     def run_sql_in_snapshot(self, sql, params=None, param_types=None):
+        """Run an SQL request on the linked Database snapshot.
+
+        :type sql: str
+        :param sql: SQL request.
+
+        :type params: list
+        :param params: (Optional) List of parameters.
+
+        :type param_types: dict
+        :param param_types: (Optional) List of parameters' types.
+
+        :rtype: list
+        :returns: A list of :class:`~google.cloud.spanner_v1.streamed.StreamedResultSet`
+                  results.
+        """
         # Some SQL e.g. for INFORMATION_SCHEMA cannot be run in read-write transactions
         # hence this method exists to circumvent that limit.
         self.run_prior_DDL_statements()
@@ -119,6 +178,14 @@ def run_sql_in_snapshot(self, sql, params=None, param_types=None):
             return list(res)
 
     def get_table_column_schema(self, table_name):
+        """Get the table column schema.
+
+        :type table_name: str
+        :param table_name: The name of the table.
+
+        :rtype: dict
+        :returns: A dictionary containing descriptions for every column.
+        """
         rows = self.run_sql_in_snapshot(
             """SELECT
                 COLUMN_NAME, IS_NULLABLE, SPANNER_TYPE
@@ -142,7 +209,7 @@ def get_table_column_schema(self, table_name):
     def close(self):
         """Close this connection.
 
-        The connection will be unusable from this point forward.
+        .. note:: The connection will be unusable from this point forward.
         """
         self.__dbhandle = None
         self.is_closed = True

google/cloud/spanner_dbapi/cursor.py

@@ -54,8 +54,7 @@
 
 
 class Cursor:
-    """
-    Database cursor to manage the context of a fetch operation.
+    """Database cursor to manage the context of fetch operations.
 
     :type connection: :class:`spanner_dbapi.connection.Connection`
     :param connection: Parent connection object for this Cursor.
@@ -72,14 +71,21 @@ def __init__(self, connection):
         self.arraysize = 1
 
     def execute(self, sql, args=None):
-        """
-        Abstracts and implements execute SQL statements on Cloud Spanner.
-        Args:
-            sql: A SQL statement
-            *args: variadic argument list
-            **kwargs: key worded arguments
-        Returns:
-            None
+        """Abstract and execute SQL statements on Cloud Spanner.
+
+        :type sql: str
+        :param sql: A SQL statement.
+
+        :type args: list
+        :param args: (Optional) a list of variadic arguments.
+
+        :type kwargs: list
+        :param kwargs: (Optional) key worded arguments.
+
+        :raises: :class:`IntegrityError`, if precondition failed or the argument
+                 already exists, :class:`ProgrammingError` if there is
+                 an invalid argument, :class:`OperationalError` if there is
+                 an internal server error.
         """
         self._raise_if_closed()
 
@@ -212,6 +218,19 @@ def __exit__(self, etype, value, traceback):
 
     @property
     def description(self):
+        """Read-only attribute containing a sequence of the following items:
+
+        -   ``name``
+        -   ``type_code``
+        -   ``display_size``
+        -   ``internal_size``
+        -   ``precision``
+        -   ``scale``
+        -   ``null_ok``
+        # Todo review
+        :rtype: tuple
+        :returns: A tuple of columns' information.
+        """
         if not (self._res and self._res.metadata):
             return None
 
@@ -232,13 +251,18 @@ def description(self):
 
     @property
     def rowcount(self):
+        """Count number of rows in the table after last execution.
+
+        :rtype: int
+        :returns: The number of rows that last .execute*() produced.
+        """
         return self._row_count
 
     @property
     def is_closed(self):
         """The cursor close indicator.
 
-        :rtype: :class:`bool`
+        :rtype: bool
         :returns: True if this cursor or it's parent connection is closed, False
                   otherwise.
         """
@@ -265,14 +289,17 @@ def close(self):
 
     def executemany(self, operation, seq_of_params):
         """
-        Execute the given SQL with every parameters set
-        from the given sequence of parameters.
+        Execute the given SQL with every parameters set from the given sequence
+        of parameters.
 
-        :type operation: :class:`str`
+        :type operation: str
         :param operation: SQL code to execute.
 
-        :type seq_of_params: :class:`list`
+        :type seq_of_params: list
         :param seq_of_params: Sequence of params to run the query with.
+
+        :raises: :class:`ProgrammingError` if the cursor is not connected to
+                 the database.
         """
         self._raise_if_closed()
 
@@ -290,6 +317,11 @@ def __iter__(self):
         return self._itr
 
     def fetchone(self):
+        # TODO review
+        """Fetch the next resulting row of the last ran query.
+
+        :returns: The next element if possible, None otherwise.
+        """
         self._raise_if_closed()
 
         try:
@@ -298,6 +330,13 @@ def fetchone(self):
             return None
 
     def fetchall(self):
+        """
+        Fetch all (remaining) rows of a query result, returning them as a
+        sequence of sequences (e.g. a list of tuples).
+
+        :rtype: list
+        :returns: A list of fetched rows of a query result.
+        """
         self._raise_if_closed()
 
         return list(self.__iter__())
@@ -307,13 +346,13 @@ def fetchmany(self, size=None):
         Fetch the next set of rows of a query result, returning a sequence of sequences.
         An empty sequence is returned when no more rows are available.
 
-        Args:
-            size: optional integer to determine the maximum number of results to fetch.
+        :type size: int
+        :param size: (Optional) The maximum number of results to fetch.
 
 
-        Raises:
-            Error if the previous call to .execute*() did not produce any result set
-            or if no call was issued yet.
+        :raises InterfaceError: If the previous call to .execute*() did not
+                                produce any result set or if no call was
+                                issued yet.
         """
         self._raise_if_closed()
 
@@ -343,17 +382,60 @@ def _run_prior_DDL_statements(self):
         return self._connection.run_prior_DDL_statements()
 
     def list_tables(self):
+        """List the tables of the linked Database.
+
+        :rtype: list
+        :returns: The list of tables within the Database.
+        """
         return self._connection.list_tables()
 
     def run_sql_in_snapshot(self, sql):
+        """Run SQL in snapshot.
+
+        :type sql: str
+        :param sql: A SQL request.
+
+        :rtype: list
+        :returns: A list of :class:`~google.cloud.spanner_v1.streamed.StreamedResultSet`.
+        """
         return self._connection.run_sql_in_snapshot(sql)
 
     def get_table_column_schema(self, table_name):
+        """Get the table column schema.
+
+        :type table_name: str
+        :param table_name: The name of the table.
+
+        :rtype: dict
+        :returns: A dictionary containing the table column schema.
+        """
         return self._connection.get_table_column_schema(table_name)
 
 
 class ColumnInfo:
-    """Row column description object."""
+    """The object defines the column of the table in the linked Database.
+
+    :type name: str
+    :param name: The name of the column.
+
+    :type type_code: int
+    :param type_code: The code of the value type.
+
+    :type display_size: int
+    :param display_size: (Optional) A display size.
+
+    :type internal_size: int
+    :param internal_size: (Optional) An internal size.
+
+    :type precision: int
+    :param precision: (Optional) The number of significant digits.
+
+    :type scale: float
+    :param scale: (Optional) The scale.
+
+    :type null_ok: bool
+    :param null_ok: (Optional) Allows column value to be None. Default is False.
+    """
 
     def __init__(
         self,