From d99539794875062bbfead86f7d71588f5d091daa Mon Sep 17 00:00:00 2001
From: Chris Mungall <cjm@berkeleybop.org>
Date: Fri, 31 May 2024 16:06:15 -0700
Subject: [PATCH] docs

---
 src/oaklib/cli.py   |  2 +-
 src/oaklib/query.py | 14 +++++++++++++-
 tests/test_cli.py   |  4 +++-
 3 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/src/oaklib/cli.py b/src/oaklib/cli.py
index a71b1d38b..4e365ba6d 100644
--- a/src/oaklib/cli.py
+++ b/src/oaklib/cli.py
@@ -3503,7 +3503,7 @@ def _is_uri_or_curie(v):
 
     # batch query results: this allows us to produce buffered output
     # for a long-running query
-    for row_it in chunk(impl.onto_query(query, prefixes=prefixes)):
+    for row_it in chunk(impl.query(query, prefixes=prefixes)):
         rows = []
         # collect rows in batch, and set label_fields if not already set
         for r in row_it:
diff --git a/src/oaklib/query.py b/src/oaklib/query.py
index 68e272bb0..f6df52bc2 100644
--- a/src/oaklib/query.py
+++ b/src/oaklib/query.py
@@ -1,3 +1,8 @@
+"""Representation and execution of complex boolean queries.
+
+See also `<https://incatools.github.io/ontology-access-kit/howtos/use-oak-expression-language.html>`_.
+"""
+
 import itertools
 import logging
 import re
@@ -38,13 +43,19 @@
 
 
 class OperatorEnum(str, Enum):
+    """Boolean operators for queries."""
+
     AND = "and"
     OR = "or"
     NOT = "not"
 
 
 class FunctionEnum(str, Enum):
+    """Enumeration of types of functions for queries."""
+
     ANCESTOR = "anc"
+    """Ancestor query."""
+
     DESCENDANT = "desc"
     SUBCLASS = "sub"
     CHILD = "child"
@@ -53,6 +64,7 @@ class FunctionEnum(str, Enum):
     MRCA = "mrca"
     NON_REDUNDANT = "nr"
     GAP_FILL = "gap_fill"
+    QUERY = "query"
 
 
 class Query(BaseModel):
@@ -576,7 +588,7 @@ def chain_results(v):
             query_terms = query_terms[1:]
             chain_results(eval(expr, {"impl": adapter, "terms": results}))  # noqa
         elif term.startswith(".query"):
-            # arbitrary SPARQL query
+            # arbitrary SPARQL or SQL query (implementation specific)
             params = _parse_params(term)
             prefixes = params.get("prefixes", None)
             query = query_terms[0]
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 58c319c8d..da59c5979 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -1030,7 +1030,9 @@ def test_query(self):
                 reader = csv.DictReader(file, delimiter="\t")
                 rows = [row for row in reader]
                 for e in expected:
-                    self.assertIn(e, rows)
+                    self.assertIn(
+                        e, rows, f"Expected {expected} for {query} in {adapter} with args {args}"
+                    )
                 # for case in cases:
                 #    self.assertIn(case, rows)