Dev

.github/workflows/aiosql-package.yml

@@ -21,9 +21,9 @@ jobs:
         # https://downloads.python.org/pypy/versions.json
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

Makefile

@@ -323,7 +323,7 @@ check.coverage.combine: $(VENV)
 	else
 	  $(COVERAGE) html
 	fi
-	$(COVERAGE) report --fail-under=100 --include='$(MODULE)/*'
+	$(COVERAGE) report --show-missing --precision=1 --fail-under=100.0 --include='$(MODULE)/*'
 
 #
 # Docker runs

aiosql/adapters/duckdb.py

@@ -37,7 +37,7 @@ def insert_returning(self, conn, _query_name, sql, parameters):  # pragma: no co
             res = res[0]
         return res[0] if res and len(res) == 1 else res
 
-    def select(self, conn, _query_name, sql, parameters, record_class=None):
+    def select(self, conn, _query_name: str, sql: str, parameters, record_class=None):
         column_names: List[str] = []
         cur = self._cursor(conn)
         try:

aiosql/adapters/generic.py

@@ -5,6 +5,8 @@
 class GenericAdapter:
     """
     Generic AioSQL Adapter suitable for `named` parameter style and no with support.
+
+    This class also serves as the base class for other adapters.
     """
 
     def __init__(self, driver=None):
@@ -18,7 +20,8 @@ def _cursor(self, conn):
         """Get a cursor from a connection."""
         return conn.cursor()
 
-    def select(self, conn, _query_name, sql, parameters, record_class=None):
+    def select(self, conn, _query_name: str, sql: str, parameters, record_class=None):
+        """Handle a relation-returning SELECT (no suffix)."""
         column_names: List[str] = []
         cur = self._cursor(conn)
         try:
@@ -37,6 +40,9 @@ def select(self, conn, _query_name, sql, parameters, record_class=None):
             cur.close()
 
     def select_one(self, conn, _query_name, sql, parameters, record_class=None):
+        """Handle a tuple-returning (one row) SELECT (``^`` suffix).
+
+        Return None if empty."""
         cur = self._cursor(conn)
         try:
             cur.execute(sql, parameters)
@@ -50,6 +56,9 @@ def select_one(self, conn, _query_name, sql, parameters, record_class=None):
         return result
 
     def select_value(self, conn, _query_name, sql, parameters):
+        """Handle a scalar-returning (one value) SELECT (``$`` suffix).
+
+        Return None if empty."""
         cur = self._cursor(conn)
         try:
             cur.execute(sql, parameters)
@@ -68,6 +77,7 @@ def select_value(self, conn, _query_name, sql, parameters):
 
     @contextmanager
     def select_cursor(self, conn, _query_name, sql, parameters):
+        """Return the raw cursor after a SELECT exec."""
         cur = self._cursor(conn)
         cur.execute(sql, parameters)
         try:
@@ -76,20 +86,24 @@ def select_cursor(self, conn, _query_name, sql, parameters):
             cur.close()
 
     def insert_update_delete(self, conn, _query_name, sql, parameters):
+        """Handle affected row counts (INSERT UPDATE DELETE) (``!`` suffix)."""
         cur = self._cursor(conn)
         cur.execute(sql, parameters)
         rc = cur.rowcount if hasattr(cur, "rowcount") else -1
         cur.close()
         return rc
 
     def insert_update_delete_many(self, conn, _query_name, sql, parameters):
+        """Handle affected row counts (INSERT UPDATE DELETE) (``*!`` suffix)."""
         cur = self._cursor(conn)
         cur.executemany(sql, parameters)
         rc = cur.rowcount if hasattr(cur, "rowcount") else -1
         cur.close()
         return rc
 
+    # FIXME this made sense when SQLite had no RETURNING prefix (v3.35, 2021-03-12)
     def insert_returning(self, conn, _query_name, sql, parameters):
+        """Special case for RETURNING (``<!`` suffix) with SQLite."""
         # very similar to select_one but the returned value
         cur = self._cursor(conn)
         cur.execute(sql, parameters)
@@ -98,6 +112,7 @@ def insert_returning(self, conn, _query_name, sql, parameters):
         return res[0] if res and len(res) == 1 else res
 
     def execute_script(self, conn, sql):
+        """Handle an SQL script (``#`` suffix)."""
         cur = self._cursor(conn)
         cur.execute(sql)
         msg = cur.statusmessage if hasattr(cur, "statusmessage") else "DONE"

aiosql/adapters/pyformat.py

@@ -3,17 +3,19 @@
 
 
 def _replacer(match):
+    """Regex hook for named to pyformat conversion."""
     gd = match.groupdict()
-    if gd["dquote"] is not None:
+    if gd["dquote"] is not None:  # "..."
         return gd["dquote"]
-    elif gd["squote"] is not None:
+    elif gd["squote"] is not None:  # '...'
         return gd["squote"]
-    else:
+    else:  # :something to %(something)s
         return f'{gd["lead"]}%({gd["var_name"]})s'
 
 
 class PyFormatAdapter(GenericAdapter):
-    """Convert from named to pyformat parameter style"""
+    """Convert from named to pyformat parameter style."""
 
     def process_sql(self, _query_name, _op_type, sql):
+        """From named to pyformat."""
         return VAR_REF.sub(_replacer, sql)

aiosql/aiosql.py

@@ -67,6 +67,7 @@ def from_str(
     sql: str,
     driver_adapter: Union[str, Callable[..., DriverAdapterProtocol]],
     record_classes: Optional[Dict] = None,
+    kwargs_only: bool = False,
     *,
     loader_cls: Type[QueryLoader] = QueryLoader,
     queries_cls: Type[Queries] = Queries,
@@ -79,6 +80,7 @@ def from_str(
     - **driver_adapter** - Either a string to designate one of the aiosql built-in database driver
       adapters. One of many available for SQLite, Postgres and MySQL. If you have defined your
       own adapter class, you can pass it's constructor.
+    - **kwargs_only** - Whether to only use named parameters on query execution.
     - **record_classes** - *(optional)* **DEPRECATED** Mapping of strings used in "record_class"
       declarations to the python classes which aiosql should use when marshaling SQL results.
     - **loader_cls** - *(optional)* Custom constructor for QueryLoader extensions.
@@ -113,14 +115,15 @@ def from_str(
     """
     adapter = _make_driver_adapter(driver_adapter)
     query_loader = loader_cls(adapter, record_classes)
-    query_data = query_loader.load_query_data_from_sql(sql)
-    return queries_cls(adapter).load_from_list(query_data)
+    query_data = query_loader.load_query_data_from_sql(sql, [])
+    return queries_cls(adapter, kwargs_only=kwargs_only).load_from_list(query_data)
 
 
 def from_path(
     sql_path: Union[str, Path],
     driver_adapter: Union[str, Callable[..., DriverAdapterProtocol]],
     record_classes: Optional[Dict] = None,
+    kwargs_only: bool = False,
     *,
     loader_cls: Type[QueryLoader] = QueryLoader,
     queries_cls: Type[Queries] = Queries,
@@ -135,6 +138,7 @@ def from_path(
     - **driver_adapter** - Either a string to designate one of the aiosql built-in database driver
       adapters. One of many available for SQLite, Postgres and MySQL. If you have defined your own
       adapter class, you may pass its constructor.
+    - **kwargs_only** - Whether to only use named parameters on query execution.
     - **record_classes** - *(optional)* **DEPRECATED** Mapping of strings used in "record_class"
       declarations to the python classes which aiosql should use when marshaling SQL results.
     - **loader_cls** - *(optional)* Custom constructor for `QueryLoader` extensions.
@@ -161,11 +165,11 @@ def from_path(
 
     if path.is_file():
         query_data = query_loader.load_query_data_from_file(path, encoding=encoding)
-        return queries_cls(adapter).load_from_list(query_data)
+        return queries_cls(adapter, kwargs_only=kwargs_only).load_from_list(query_data)
     elif path.is_dir():
         query_data_tree = query_loader.load_query_data_from_dir_path(
             path, ext=ext, encoding=encoding
         )
-        return queries_cls(adapter).load_from_tree(query_data_tree)
+        return queries_cls(adapter, kwargs_only=kwargs_only).load_from_tree(query_data_tree)
     else:  # pragma: no cover
         raise SQLLoadException(f"The sql_path must be a directory or file, got {sql_path}")