add comments and docs

aiosql/aiosql.py

@@ -18,6 +18,7 @@
     "aiosqlite": AioSQLiteAdapter,  # type: ignore
     "apsw": GenericAdapter,
     "asyncpg": AsyncPGAdapter,  # type: ignore
+    "duckdb": DuckDBAdapter,
     "mariadb": BrokenMySQLAdapter,
     "mysqldb": BrokenMySQLAdapter,
     "mysql-connector": PyFormatAdapter,
@@ -27,8 +28,8 @@
     "pygresql": PyFormatAdapter,
     "pymysql": BrokenMySQLAdapter,
     "sqlite3": SQLite3Adapter,
-    "duckdb": DuckDBAdapter,
 }
+"""Map adapter names to their adapter class."""
 
 
 def register_adapter(name: str, adapter: Callable[..., DriverAdapterProtocol]):

aiosql/queries.py

@@ -40,7 +40,12 @@ def __init__(
     def _params(
         self, attributes, args: Union[List[Any], Tuple[Any]], kwargs: Dict[str, Any]
     ) -> Union[List[Any], Tuple[Any], Dict[str, Any]]:
-        """Execute parameter handling."""
+        """Handle query parameters.
+
+        - update attribute references ``:u.a`` to ``:u__a``.
+        - check whether non kwargs are allowed and other checks.
+        - return the parameters, either ``args`` or ``kwargs``.
+        """
 
         if attributes and kwargs:
 
@@ -231,13 +236,13 @@ def add_child_queries(self, child_name: str, child_queries: "Queries") -> None:
             self._available_queries.add(f"{child_name}.{child_query_name}")
 
     def load_from_list(self, query_data: List[QueryDatum]):
-        """Load Queries from a list of `QuaryDatum`"""
+        """Load Queries from a list of `QueryDatum`"""
         for query_datum in query_data:
             self.add_queries(self._create_methods(query_datum, self.is_aio))
         return self
 
     def load_from_tree(self, query_data_tree: QueryDataTree):
-        """Load Queries from a `QuaryDataTree`"""
+        """Load Queries from a `QueryDataTree`"""
         for key, value in query_data_tree.items():
             if isinstance(value, dict):
                 self.add_child_queries(key, Queries(self.driver_adapter).load_from_tree(value))

aiosql/query_loader.py

@@ -49,7 +49,7 @@
 
 def _remove_ml_comments(code: str) -> str:
     """Remove /* ... */ comments from code"""
-    # identify commented regions
+    # identify commented regions to be removed
     rm = []
     for m in _UNCOMMENT.finditer(code):
         ml = m.groupdict()["multiline"]
@@ -60,6 +60,7 @@ def _remove_ml_comments(code: str) -> str:
     for start, end in rm:
         ncode += code[current:start]
         current = end
+    # get tail
     ncode += code[current:]
     return ncode
 
@@ -90,6 +91,11 @@ def _replace(m):
 
 
 class QueryLoader:
+    """Load Queries.
+
+    This class holds the various utilities to read SQL files and build
+    QueryDatum, which will be transformed as functions in Queries.
+    """
 
     def __init__(
         self,

aiosql/utils.py

@@ -21,6 +21,7 @@
 """Pattern to identify colon-variables with a simple attribute in SQL code."""
 
 log = logging.getLogger("aiosql")
+"""Shared package logging."""
 # log.setLevel(logging.DEBUG)