From 33b660adf6fa17475531bef18e4794072bf0e2a5 Mon Sep 17 00:00:00 2001
From: Robert Forkel <xrotwang@googlemail.com>
Date: Mon, 20 Jan 2025 15:03:08 +0100
Subject: [PATCH] docs

---
 src/pycldf/db.py | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/src/pycldf/db.py b/src/pycldf/db.py
index 71b10b0..08586f1 100644
--- a/src/pycldf/db.py
+++ b/src/pycldf/db.py
@@ -42,6 +42,7 @@
 import typing
 import inspect
 import pathlib
+import sqlite3
 import functools
 import collections
 
@@ -372,12 +373,27 @@ def to_cldf(self, dest, mdname='cldf-metadata.json', coordinate_precision=4) ->
         return self.dataset.write_metadata(dest / mdname)
 
 
-def query(conn,
+class AggregateClass(typing.Protocol):  # pragma: no cover
+    def step(self, value):
+        ...
+
+    def finalize(self):
+        ...
+
+
+def query(conn: sqlite3.Connection,
           sql: str,
           params=None,
-          functions=None,
-          aggregates=None,
-          collations=None) -> typing.Generator[typing.Any, None, None]:
+          functions: typing.Optional[typing.List[typing.Callable]] = None,
+          aggregates: typing.Optional[typing.List[AggregateClass]] = None,
+          collations: typing.Optional[typing.List[typing.Callable]] = None) \
+        -> typing.Generator[typing.Any, None, None]:
+    """
+    Note: Passing lambdas or functools.partial objects as function requires passing an explicit name
+    as well.
+
+    :return: A generator of result rows for the query.
+    """
     for func in functions or []:
         if isinstance(func, tuple):
             name, func = func