Add docstrings to the tests

Author: Cito

pyproject.toml

@@ -125,11 +125,19 @@ max-statements = 95
   "T201",  # allow print statements
 ]
 "tests/*" = [
-  "D",  # no docstrings necessary here
+  "D413",  # allow plain notes in the module docstrings
   "PLC0415",  # allow imports in tests functions
   "PLR2004",  # allow magic values
   "S101",  # allow assert statements
 ]
+"tests/mock_*.py" = [
+  # the mock objects only mimic a foreign API, docstrings would add nothing
+  "D101",  # missing docstring in public class
+  "D102",  # missing docstring in public method
+  "D103",  # missing docstring in public function
+  "D105",  # missing docstring in magic method
+  "D107",  # missing docstring in __init__
+]
 
 [tool.codespell]
 skip = '.git,.tox,.venv,*.de.html,*.de.rst,build,dist,local'

tests/mock_db.py

@@ -1,4 +1,4 @@
-"""This module serves as a mock object for the DB-API 2 module"""
+"""Mock object for the DB-API 2 module."""
 
 import sys
 

tests/mock_pg.py

@@ -1,4 +1,4 @@
-"""This module serves as a mock object for the pg API module"""
+"""Mock object for the pg API module."""
 
 import sys
 

tests/test_persistent_db.py

@@ -21,20 +21,23 @@
 
 
 def test_version():
+    """Check that the module and class versions are in sync."""
     from dbutils import __version__, persistent_db
     assert persistent_db.__version__ == __version__
     assert PersistentDB.version == __version__
 
 
 @pytest.mark.parametrize("threadsafety", [None, 0])
 def test_no_threadsafety(dbapi, threadsafety):  # noqa: F811
+    """Check that a database module that is not thread-safe is rejected."""
     dbapi.threadsafety = threadsafety
     with pytest.raises(NotSupportedError):
         PersistentDB(dbapi)
 
 
 @pytest.mark.parametrize("closeable", [False, True])
 def test_close(dbapi, closeable):  # noqa: F811
+    """Check that closing is only allowed when the connection is closeable."""
     persist = PersistentDB(dbapi, closeable=closeable)
     db = persist.connection()
     assert db._con.valid is True
@@ -49,6 +52,7 @@ def test_close(dbapi, closeable):  # noqa: F811
 
 
 def test_connection(dbapi):  # noqa: F811
+    """Check that the same thread always gets the same connection."""
     persist = PersistentDB(dbapi)
     db = persist.connection()
     db_con = db._con
@@ -64,6 +68,7 @@ def test_connection(dbapi):  # noqa: F811
 
 
 def test_threads(dbapi):  # noqa: F811
+    """Check that every thread keeps its own persistent connection."""
     num_threads = 3
     persist = PersistentDB(dbapi, closeable=True)
     query_queue, result_queue = [], []
@@ -137,6 +142,7 @@ def run_queries(idx):
 
 
 def test_maxusage(dbapi):  # noqa: F811
+    """Check that the connection is reset when used too often."""
     persist = PersistentDB(dbapi, 20)
     db = persist.connection()
     assert db._maxusage == 20
@@ -154,6 +160,7 @@ def test_maxusage(dbapi):  # noqa: F811
 
 
 def test_setsession(dbapi):  # noqa: F811
+    """Check that the session is prepared after every reopening."""
     persist = PersistentDB(dbapi, 3, ('set datestyle',))
     db = persist.connection()
     assert db._maxusage == 3
@@ -173,6 +180,7 @@ def test_setsession(dbapi):  # noqa: F811
 
 
 def test_threadlocal(dbapi):  # noqa: F811
+    """Check that the class for thread-local data can be replaced."""
     persist = PersistentDB(dbapi)
     assert isinstance(persist.thread, local)
 
@@ -184,6 +192,7 @@ class Threadlocal:
 
 
 def test_ping_check(dbapi):  # noqa: F811
+    """Check that connections are pinged as configured."""
     con_cls = dbapi.Connection
     con_cls.has_ping = True
     con_cls.num_pings = 0
@@ -237,6 +246,7 @@ def test_ping_check(dbapi):  # noqa: F811
 
 
 def test_failed_transaction(dbapi):  # noqa: F811
+    """Check that a failed transaction is reported and recovered from."""
     persist = PersistentDB(dbapi)
     db = persist.connection()
     cursor = db.cursor()
@@ -254,6 +264,7 @@ def test_failed_transaction(dbapi):  # noqa: F811
 
 
 def test_context_manager(dbapi):  # noqa: F811
+    """Check that connection and cursor can be used as context managers."""
     persist = PersistentDB(dbapi)
     with persist.connection() as db:
         with db.cursor() as cursor:
@@ -263,18 +274,20 @@ def test_context_manager(dbapi):  # noqa: F811
 
 
 def timeout_is_not_fatal(error):
-    """A deliberate server side timeout does not break the connection."""
+    """Treat a deliberate server side timeout as not fatal."""
     return not error.args or error.args[0] != 3024
 
 
 def test_isfatal_default(dbapi):  # noqa: F811
+    """Check that no error check is configured by default."""
     persist = PersistentDB(dbapi)
     assert persist._isfatal is None
     db = persist.connection()
     assert db._isfatal is None
 
 
 def test_isfatal(dbapi):  # noqa: F811
+    """Check that isfatal is passed on and can veto the failover."""
     persist = PersistentDB(dbapi, isfatal=timeout_is_not_fatal)
     assert persist._isfatal is timeout_is_not_fatal
     db = persist.connection()
@@ -291,6 +304,7 @@ def test_isfatal(dbapi):  # noqa: F811
 
 
 def test_no_failover(dbapi):  # noqa: F811
+    """Check that no_failover() suspends the failover mechanism."""
     persist = PersistentDB(dbapi)
     db = persist.connection()
     dbapi.Connection.num_timeouts = 0
@@ -303,6 +317,7 @@ def test_no_failover(dbapi):  # noqa: F811
 
 
 def test_dbapi_connection(dbapi):  # noqa: F811
+    """Check that the underlying DB-API 2 objects are accessible."""
     persist = PersistentDB(dbapi)
     db = persist.connection()
     con = db.dbapi_connection

tests/test_persistent_pg.py

@@ -20,13 +20,15 @@
 
 
 def test_version():
+    """Check that the module and class versions are in sync."""
     from dbutils import __version__, persistent_pg
     assert persistent_pg.__version__ == __version__
     assert PersistentPg.version == __version__
 
 
 @pytest.mark.parametrize("closeable", [False, True])
 def test_close(closeable):
+    """Check that closing is only allowed when the connection is closeable."""
     persist = PersistentPg(closeable=closeable)
     db = persist.connection()
     assert db._con.db
@@ -42,6 +44,7 @@ def test_close(closeable):
 
 
 def test_threads():
+    """Check that every thread keeps its own persistent connection."""
     num_threads = 3
     persist = PersistentPg()
     query_queue, result_queue = [], []
@@ -112,6 +115,7 @@ def run_queries(idx):
 
 
 def test_maxusage():
+    """Check that the connection is reset when used too often."""
     persist = PersistentPg(20)
     db = persist.connection()
     assert db._maxusage == 20
@@ -125,6 +129,7 @@ def test_maxusage():
 
 
 def test_setsession():
+    """Check that the session is prepared after every reopening."""
     persist = PersistentPg(3, ('set datestyle',))
     db = persist.connection()
     assert db._maxusage == 3
@@ -138,6 +143,7 @@ def test_setsession():
 
 
 def test_failed_transaction():
+    """Check that a failed transaction is reported and recovered from."""
     persist = PersistentPg()
     db = persist.connection()
     db._con.close()
@@ -155,6 +161,7 @@ def test_failed_transaction():
 
 
 def test_context_manager():
+    """Check that the connection can be used as a context manager."""
     persist = PersistentPg()
     with persist.connection() as db:
         db.query('select test')