docs: missing docstrings for functions & classes

google/cloud/spanner_dbapi/connection.py

@@ -15,13 +15,27 @@
 
 
 class Connection:
+    """
+    A wrap-around object for the existing
+    :class:`~google.cloud.spanner_v1.database.Database` and the corresponding
+    :class:`~google.cloud.spanner_admin_instance_v1.types.Instance` objects.
+
+    :type db_handle: :class:`Database`
+    :param db_handle: Database handle.
+    """
+
     def __init__(self, db_handle):
         self._dbhandle = db_handle
         self._ddl_statements = []
 
         self.is_closed = False
 
     def cursor(self):
+        """Factory to create a :class:`Cursor` linked to this Connection.
+
+        :rtype: :class:`Cursor`
+        :returns: :class:`Cursor` object.
+        """
         self._raise_if_closed()
 
         return Cursor(self)
@@ -41,28 +55,52 @@ 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.
+
+        :rtype: str
+        :returns: Result of the operation.
         """
         self._raise_if_closed()
         # Synchronously wait on the operation's completion.
         return self._dbhandle.update_ddl(ddl_statements).result()
 
     def read_snapshot(self):
+        """Returns 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._dbhandle.snapshot()
 
     def in_transaction(self, fn, *args, **kwargs):
+        """Perform a unit of work in a linked Transaction, retrying on abort.
+
+        :rtype: Any
+        :returns: Runs the given function as it would be a transaction.
+        """
         self._raise_if_closed()
         return self._dbhandle.run_in_transaction(fn, *args, **kwargs)
 
     def append_ddl_statement(self, ddl_statement):
+        """Appends DDL statement.
+
+        :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):
+        """Runs prior Operation.
+
+        :rtype: str
+        :returns: Updated statements.
+        """
         self._raise_if_closed()
 
         if not self._ddl_statements:
@@ -74,6 +112,11 @@ def run_prior_DDL_statements(self):
         return self.__handle_update_ddl(ddl_statements)
 
     def list_tables(self):
+        """Lists tables contained within the linked Database.
+
+        :rtype: list
+        :returns: Tables with corresponding information.
+        """
         return self.run_sql_in_snapshot(
             """
             SELECT
@@ -86,6 +129,21 @@ def list_tables(self):
         )
 
     def run_sql_in_snapshot(self, sql, params=None, param_types=None):
+        """Runs 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()
@@ -97,6 +155,14 @@ def run_sql_in_snapshot(self, sql, params=None, param_types=None):
             return list(res)
 
     def get_table_column_schema(self, table_name):
+        """Gets table column schema.
+
+        :type table_name: str
+        :param table_name: Name of the table.
+
+        :rtype: dict
+        :returns: Column description.
+        """
         rows = self.run_sql_in_snapshot(
             """SELECT
                 COLUMN_NAME, IS_NULLABLE, SPANNER_TYPE
@@ -120,13 +186,14 @@ 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.rollback()
         self.__dbhandle = None
         self.is_closed = True
 
     def commit(self):
+        """Commit all the pending transactions."""
         self._raise_if_closed()
 
         self.run_prior_DDL_statements()

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 a fetch operation.
 
     :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
+        """Abstracts and implements execute SQL statements on Cloud Spanner.
+
+        :type sql: str
+        :param sql: A SQL statement.
+
+        :type *args: list
+        :param *args: (Optional) variadic argument list.
+
+        :type **kwargs: list
+        :param **kwargs: (Optional) key worded arguments.
+
+        :raises: :class:`IntegrityError` if precondition failed or argument
+                 already exists, :class:`ProgrammingError` if there is
+                 invalid argument, :class:`OperationalError` if there is
+                 internal server error.
         """
         self._raise_if_closed()
 
@@ -212,6 +218,11 @@ def __exit__(self, etype, value, traceback):
 
     @property
     def description(self):
+        """Gives description of the table.
+
+        :rtype: tuple
+        :returns: A tuple of columns' information.
+        """
         if not (self._res and self._res.metadata):
             return None
 
@@ -232,13 +243,18 @@ def description(self):
 
     @property
     def rowcount(self):
+        """Returns number of rows in the table.
+
+        :rtype: int
+        :returns: Number of rows.
+        """
         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.
         """
@@ -257,22 +273,25 @@ def _raise_if_closed(self):
             raise InterfaceError("cursor is already closed")
 
     def close(self):
-        """Close this cursor.
+        """Close cursor of linked Database.
 
         The cursor will be unusable from this point forward.
         """
         self._is_closed = True
 
     def executemany(self, operation, seq_of_params):
         """
-        Execute the given SQL with every parameters set
-        from the given sequence of parameters.
+        Executes 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 cursor is not connected to
+                 database.
         """
         self._raise_if_closed()
 
@@ -290,6 +309,10 @@ def __iter__(self):
         return self._itr
 
     def fetchone(self):
+        """Fetch next element.
+
+        :returns: The next element if it is possible, None otherwise.
+        """
         self._raise_if_closed()
 
         try:
@@ -298,6 +321,11 @@ def fetchone(self):
             return None
 
     def fetchall(self):
+        """Fetches all elements.
+
+        :rtype: list
+        :returns: A list of fetched elements.
+        """
         self._raise_if_closed()
 
         return list(self.__iter__())
@@ -307,13 +335,12 @@ 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) 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: An error if the previous call to .execute*() did not produce
+                 any result set or if no call was issued yet.
         """
         self._raise_if_closed()
 
@@ -343,16 +370,61 @@ def _run_prior_DDL_statements(self):
         return self._connection.run_prior_DDL_statements()
 
     def list_tables(self):
+        """Lists tables of linked Database.
+
+        :rtype: str
+        :returns: Tables with theirs' corresponding information.
+        """
         return self._connection.list_tables()
 
     def run_sql_in_snapshot(self, sql):
+        """Runs SQL in snapshot.
+
+        :type sql: str
+        :param sql: SQL request.
+
+        :rtype: list
+        :returns: Result of operation.
+        """
         return self._connection.run_sql_in_snapshot(sql)
 
     def get_table_column_schema(self, table_name):
+        """Gets table column schema.
+
+        :type table_name: str
+        :param table_name: Name of the table.
+
+        :rtype: dict
+        :returns: A dictionary of table column schema.
+        """
         return self._connection.get_table_column_schema(table_name)
 
 
 class Column:
+    """Object defines column of the table in linked Database.
+
+    :type name: str
+    :param name: Name of the column.
+
+    :type type_code: int
+    :param type_code: Code of the value type.
+
+    :type display_size: int
+    :param display_size: (Optional) Display size.
+
+    :type internal_size: int
+    :param internal_size: (Optional) Internal size.
+
+    :type precision: int
+    :param precision: (Optional) Number of significant digits.
+
+    :type scale: float
+    :param scale: (Optional) Scale.
+
+    :type null_ok: bool
+    :param null_ok: (Optional) Allows column value to be None. Default is False.
+    """
+
     def __init__(
         self,
         name,