feat: docstrings for django-spanner

django_spanner/base.py

@@ -103,6 +103,11 @@ class DatabaseWrapper(BaseDatabaseWrapper):
 
  @property
  def instance(self):
+ """Reference to a Cloud Spanner Instance containing the Database.
+
+ :rtype: :class:`~google.cloud.spanner_v1.instance.Instance`
+ :returns: A new instance owned by the existing Spanner Client.
+ """
  return spanner.Client().instance(self.settings_dict["INSTANCE"])
 
  @property
@@ -112,6 +117,12 @@ def _nodb_connection(self):
  )
 
  def get_connection_params(self):
+ """Retrieve the connection parameters.
+
+ :rtype: dict
+ :returns: A dictionary containing the Spanner connection parameters
+ in Django Spanner format.
+ """
  return {
  "project": self.settings_dict["PROJECT"],
  "instance_id": self.settings_dict["INSTANCE"],
@@ -120,20 +131,52 @@ def get_connection_params(self):
  **self.settings_dict["OPTIONS"],
  }
 
- def get_new_connection(self, conn_params):
+ def get_new_connection(self, **conn_params):
+ """Create a new connection with corresponding connection parameters.
+
+ :type conn_params: list
+ :param conn_params: A List of the connection parameters for
+ :class:`~google.cloud.spanner_dbapi.connection.Connection`
+
+ :rtype: :class:`google.cloud.spanner_dbapi.connection.Connection`
+ :returns: A new Spanner DB API Connection object associated with the
+ given Google Cloud Spanner resource.
+
+ :raises: :class:`ValueError` in case the given instance/database
+ doesn't exist.
+ """
  return Database.connect(**conn_params)
 
  def init_connection_state(self):
+ """Initialize the state of the existing connection."""
  pass
 
  def create_cursor(self, name=None):
+ """Create a new Database cursor.
+
+ :type name: str
+ :param name: Currently not used.
+
+ :rtype: :class:`~google.cloud.spanner_dbapi.cursor.Cursor`
+ :returns: The Cursor for this connection.
+ """
  return self.connection.cursor()
 
  def _set_autocommit(self, autocommit):
+ """Set the Spanner transaction autocommit flag.
+
+ :type autocommit: bool
+ :param autocommit: The new value of the autocommit flag.
+ """
  with self.wrap_database_errors:
  self.connection.autocommit = autocommit
 
  def is_usable(self):
+ """Check whether the connection is valid.
+
+ :rtype: bool
+ :returns: True if the connection is open, otherwise False.
+ """
  if self.connection is None:
  return False
  try:

django_spanner/client.py

@@ -9,5 +9,7 @@
 
 
 class DatabaseClient(BaseDatabaseClient):
+ """Wrap the Django base class."""
+
  def runshell(self, parameters):
  raise NotSupportedError("This method is not supported.")

django_spanner/compiler.py

@@ -17,11 +17,27 @@
 
 
 class SQLCompiler(BaseSQLCompiler):
+ """
+ A variation of the Django SQL compiler, adjusted for Spanner-specific
+ functionality.
+ """
+
  def get_combinator_sql(self, combinator, all):
- """
+ """Override the native Django method.
+
  Copied from the base class except for:
  combinator_sql += ' ALL' if all else ' DISTINCT'
  Cloud Spanner requires ALL or DISTINCT.
+
+ :type combinator: str
+ :param combinator: A type of the combinator for the operation.
+
+ :type all: bool
+ :param all: Bool option for the SQL statement.
+
+ :rtype: tuple
+ :returns: A tuple containing SQL statement(s) with some additional
+ parameters.
  """
  features = self.connection.features
  compilers = [
@@ -97,16 +113,20 @@ def get_combinator_sql(self, combinator, all):
 
 
 class SQLInsertCompiler(BaseSQLInsertCompiler, SQLCompiler):
+ """A wrapper class for compatibility with Django specifications."""
  pass
 
 
 class SQLDeleteCompiler(BaseSQLDeleteCompiler, SQLCompiler):
+ """A wrapper class for compatibility with Django specifications."""
  pass
 
 
 class SQLUpdateCompiler(BaseSQLUpdateCompiler, SQLCompiler):
+ """A wrapper class for compatibility with Django specifications."""
  pass
 
 
 class SQLAggregateCompiler(BaseSQLAggregateCompiler, SQLCompiler):
+ """A wrapper class for compatibility with Django specifications."""
  pass

django_spanner/creation.py

@@ -14,6 +14,11 @@
 
 
 class DatabaseCreation(BaseDatabaseCreation):
+ """
+ Spanner-specific wrapper for Django class encapsulating methods for
+ creation and destruction of the underlying test database.
+ """
+
  def mark_skips(self):
  """Skip tests that don't work on Spanner."""
  for test_name in self.connection.features.skip_tests:
@@ -30,13 +35,23 @@ def mark_skips(self):
  )
 
  def create_test_db(self, *args, **kwargs):
+ """Create a test database.
+
+ :rtype: str
+ :returns: The name of the newly created test Database.
+ """
  # This environment variable is set by the Travis build script or
  # by a developer running the tests locally.
  if os.environ.get("RUNNING_SPANNER_BACKEND_TESTS") == "1":
  self.mark_skips()
  super().create_test_db(*args, **kwargs)
 
  def _create_test_db(self, verbosity, autoclobber, keepdb=False):
+ """
+ Create dummy test tables. This method is mostly copied from the
+ base class but removes usage of `_nodb_connection` since Spanner doesn't
+ have or need one.
+ """
  # Mostly copied from the base class but removes usage of
  # _nodb_connection since Spanner doesn't have or need one.
  test_database_name = self._get_test_db_name()

django_spanner/expressions.py

@@ -8,8 +8,16 @@
 
 
 def order_by(self, compiler, connection, **extra_context):
- # In Django 3.1, this can be replaced with
- # DatabaseFeatures.supports_order_by_nulls_modifier = False.
+ """
+ Order expressions in the SQL query and generate a new query using
+ Spanner-specific templates.
+
+ :rtype: str
+ :returns: A SQL query.
+ """
+ # TODO: In Django 3.1, this can be replaced with
+ # DatabaseFeatures.supports_order_by_nulls_modifier = False.
+ # Also, consider making this a class method.
  template = None
  if self.nulls_last:
  template = "%(expression)s IS NULL, %(expression)s %(ordering)s"
@@ -21,4 +29,5 @@ def order_by(self, compiler, connection, **extra_context):
 
 
 def register_expressions():
+ """Add Spanner-specific attribute to the Django OrderBy class."""
  OrderBy.as_spanner = order_by

django_spanner/features.py

@@ -11,6 +11,7 @@
 
 
 class DatabaseFeatures(BaseDatabaseFeatures):
+ """An extension to Django database feature descriptor."""
  can_introspect_big_integer_field = False
  can_introspect_duration_field = False
  can_introspect_foreign_keys = False