Check and improve docstrings

Author: Cito

dbutils/__init__.py

@@ -1,4 +1,4 @@
-# DBUtils main package
+"""The DBUtils main package."""
 
 __all__ = [
     '__version__',

dbutils/pooled_db.py

@@ -146,6 +146,7 @@
 Licensed under the MIT license.
 """
 
+from functools import total_ordering
 from threading import Condition
 
 from . import __version__
@@ -450,6 +451,7 @@ def __exit__(self, *exc):
         self.close()
 
 
+@total_ordering
 class SharedDBConnection:
     """Auxiliary class for shared connections."""
 
@@ -462,28 +464,16 @@ def __init__(self, con):
         self.shared = 1
 
     def __lt__(self, other):
+        """Check whether this connection should come before the other one."""
         if self.con._transaction == other.con._transaction:
             return self.shared < other.shared
         return not self.con._transaction
 
-    def __le__(self, other):
-        if self.con._transaction == other.con._transaction:
-            return self.shared <= other.shared
-        return not self.con._transaction
-
     def __eq__(self, other):
+        """Check whether this connection is the same as the other one."""
         return (self.con._transaction == other.con._transaction
                 and self.shared == other.shared)
 
-    def __ne__(self, other):
-        return not self.__eq__(other)
-
-    def __gt__(self, other):
-        return other.__lt__(self)
-
-    def __ge__(self, other):
-        return other.__le__(self)
-
     def share(self):
         """Increase the share of this connection."""
         self.shared += 1

dbutils/simple_pooled_db.py

@@ -91,6 +91,7 @@ class PooledDBConnection:
     """
 
     def __init__(self, pool, con):
+        """Initialize pooled connection."""
         self._con = con
         self._pool = pool
 
@@ -103,10 +104,12 @@ def close(self):
             self._con = None
 
     def __getattr__(self, name):
-        # All other members are the same.
+        """Get the attribute with the given name."""
+        # All other attributes are the same.
         return getattr(self._con, name)
 
     def __del__(self):
+        """Delete the pooled connection."""
         self.close()
 
 

dbutils/simple_pooled_pg.py

@@ -80,6 +80,7 @@ class PooledPgConnection:
     """
 
     def __init__(self, pool, con):
+        """Initialize pooled connection."""
         self._con = con
         self._pool = pool
 
@@ -92,10 +93,12 @@ def close(self):
             self._con = None
 
     def __getattr__(self, name):
-        # All other members are the same.
+        """Get the attribute with the given name."""
+        # All other attributes are the same.
         return getattr(self._con, name)
 
     def __del__(self):
+        """Delete the pooled connection."""
         self.close()
 
 

dbutils/steady_db.py

@@ -109,7 +109,9 @@ class InvalidCursorError(SteadyDBError):
 def connect(
         creator, maxusage=None, setsession=None,
         failures=None, ping=1, closeable=True, *args, **kwargs):
-    """A tough version of the connection constructor of a DB-API 2 module.
+    """Create a "tough" connection.
+
+    A hardened version of the connection function of a DB-API 2 module.
 
     creator: either an arbitrary function returning new DB-API 2 compliant
         connection objects or a DB-API 2 compliant database module
@@ -138,7 +140,7 @@ def connect(
 
 
 class SteadyDBConnection:
-    """A "tough" version of DB-API 2 connections."""
+    """A hardened version of DB-API 2 connections."""
 
     version = __version__
 
@@ -477,7 +479,10 @@ def ping(self, *args, **kwargs):
         return self._con.ping(*args, **kwargs)
 
     def _cursor(self, *args, **kwargs):
-        """A "tough" version of the method cursor()."""
+        """Create a "tough" cursor.
+
+        This is a hardened version of the method cursor().
+        """
         # The args and kwargs are not part of the standard,
         # but some database modules seem to use these.
         transaction = self._transaction
@@ -527,7 +532,7 @@ def __del__(self):
 
 
 class SteadyDBCursor:
-    """A "tough" version of DB-API 2 cursors."""
+    """A hardened version of DB-API 2 cursors."""
 
     def __init__(self, con, *args, **kwargs):
         """Create a "tough" DB-API 2 cursor."""

dbutils/steady_pg.py

@@ -105,6 +105,8 @@ def __init__(
             *args, **kwargs):
         """Create a "tough" PostgreSQL connection.
 
+        A hardened version of the DB wrapper class of PyGreSQL.
+
         maxusage: maximum usage limit for the underlying PyGreSQL connection
             (number of uses, 0 or None means unlimited usage)
             When this limit is reached, the connection is automatically reset.

pyproject.toml

@@ -65,6 +65,7 @@ select = [
   "C4",     # flake8-comprehensions
   "C90",    # McCabe cyclomatic complexity
   "COM",    # flake8-commas
+  "D",      # pydocstyle
   "DTZ",    # flake8-datetimez
   "E",      # pycodestyle
   "EXE",    # flake8-executable
@@ -94,8 +95,6 @@ select = [
   "YTT",    # flake8-2020
   # "ANN",  # flake8-annotations
   # "BLE",  # flake8-blind-except
-  # "D",    # pydocstyle
-  # "DJ",   # flake8-django
   # "EM",   # flake8-errmsg
   # "ERA",  # eradicate
   # "FBT",  # flake8-boolean-trap
@@ -109,6 +108,8 @@ select = [
 ]
 # Note: use `ruff rule ...` to see explanations of rules
 ignore = [
+  "D203",  # no blank linke before class docstring
+  "D213",  # multi-line docstrings should not start at second line
   "S110",  # allow silently catching errors
 ]
 line-length = 79
@@ -127,6 +128,7 @@ max-statements = 100
   "INP001",  # allow stand-alone scripts
 ]
 "tests/*" = [
+  "D",  # no docstrings necessary here
   "PLR2004",  # allow magic values
   "S101",  # allow assert statements
 ]

tests/__init__.py

@@ -1,4 +1,4 @@
-"""DBUtils tests"""
+"""The DBUtils tests package."""
 
 # make sure the mock pg module is installed
 from . import mock_pg as pg  # noqa: F401