down-merge from tartararus-overhaul

shared/selene/util/db/connection.py

@@ -22,6 +22,7 @@ class DBConnectionError(Exception):
 
 @dataclass
 class DatabaseConnectionConfig(object):
+    """attributes required to connect to a Postgres database"""
     host: str
     db_name: str
     user: str
@@ -34,6 +35,10 @@ def connect_to_db(connection_config: DatabaseConnectionConfig):
     """
     Return a connection to the mycroft database for the specified user.
 
+    Use this function when connecting to a database in an application that
+    does not benefit from connection pooling (e.g. a batch script or a
+    python notebook)
+
     :param connection_config: data needed to establish a connection
     :return: database connection
     """

shared/selene/util/db/connection_pool.py

@@ -50,10 +50,17 @@ def allocate_db_connection_pool(
 
 @contextmanager
 def get_db_connection(connection_pool):
+    """Obtain a database connection from a pool and release it when finished
+
+    :param connection_pool: pool of connections used by the applications
+    :return: context object containing a database connection from the pool
+    """
     db_connection = None
     try:
         db_connection = connection_pool.getconn()
         yield db_connection
     finally:
+        # return the db connection to the pool when exiting the context
+        # manager's scope
         if db_connection is not None:
             connection_pool.putconn(db_connection)