tiny-datalog 0.2.0__tar.gz → 0.3.0__tar.gz

{tiny_datalog-0.2.0/tiny_datalog.egg-info → tiny_datalog-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-datalog
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Datalog engine small enough to read in an afternoon
 Author: Andrew Goodchild
 License-Expression: MIT
@@ -126,7 +126,7 @@ Nothing to install:
 
 ```sh
 git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
-python3 tests.py        # 246 tests, ~12s
+python3 tests.py        # 254 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -289,7 +289,9 @@ regression test without writing Python.
 
 Not an engine to build a product on. Joins are nested-loop,
 stable-model search is exhaustive, evaluation is batch. For real
-workloads see Soufflé, clingo, RDFox or Feldera.
+workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
+Python application, with arithmetic and queries over SQL databases,
+see [pyDatalog](https://pypi.org/project/pyDatalog/).
 
 Deliberate omissions, because saying why teaches more than lacking them
 quietly:
@@ -306,7 +308,7 @@ quietly:
   (disjointness and unsatisfiability detection included). SNOMED needs
   ELH (EL plus role hierarchies) with right identities, which is what
   the ELK and Snorocket reasoners implement and this does not.
-- **A REPL (interactive prompt) and packaging.** `git clone` and run.
+- **A REPL (interactive prompt).** Run a file, or call it from Python.
 
 Aggregation used to be on this list;
 [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
@@ -324,8 +326,27 @@ pip install tiny-datalog
 from tiny_datalog import run_program, explain
 
 engine = run_program(open("supply-chain.dl").read())
-for service, cve in sorted(engine.rels["exposed"]):
-    print("\n".join(explain(engine, "exposed", (service, cve))))
+for answer in engine.query("exposed(S, C)"):
+    print(answer)                     # {'S': 'pkg0', 'C': 'cve_2026_0001'}
+print("\n".join(explain(engine, "exposed", ("pkg0", "cve_2026_0001"))))
+```
+
+Facts can come straight from Python data (a CSV file, a database
+query) instead of program text. Each row is checked as if it had been
+parsed:
+
+```python
+rules = """
+uses(X, Y) :- depends(X, Y).
+uses(X, Z) :- depends(X, Y), uses(Y, Z).
+exposed(S, C) :- service(S), uses(S, L), vulnerable(L, C).
+"""
+engine = run_program(rules, facts={
+    "depends": [("app", "lib"), ("lib", "core")],
+    "service": ["app"],                         # one-column rows may be bare
+    "vulnerable": [("core", "cve_2026_0001")],
+})
+engine.query("exposed(S, C)")       # [{'S': 'app', 'C': 'cve_2026_0001'}]
 ```
 
 The command-line interface installs too, as `tiny-datalog` (and
@@ -365,7 +386,7 @@ cases/          golden test cases — add one without writing Python
 conformance/    the external datalog-conformance corpus (Soufflé, Nemo,
                 Crepe, SPINdle), run against every evaluation strategy
 benchmarks/     scaled input generators (chain/tree/clique/grid)
-tests.py        246 tests: every shipped program and exercise answer is
+tests.py        254 tests: every shipped program and exercise answer is
                 executed, a conformance suite runs every query through
                 every applicable strategy, and a seeded fuzzer checks
                 the same property on random programs

{tiny_datalog-0.2.0 → tiny_datalog-0.3.0}/README.md

@@ -93,7 +93,7 @@ Nothing to install:
 
 ```sh
 git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
-python3 tests.py        # 246 tests, ~12s
+python3 tests.py        # 254 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -256,7 +256,9 @@ regression test without writing Python.
 
 Not an engine to build a product on. Joins are nested-loop,
 stable-model search is exhaustive, evaluation is batch. For real
-workloads see Soufflé, clingo, RDFox or Feldera.
+workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
+Python application, with arithmetic and queries over SQL databases,
+see [pyDatalog](https://pypi.org/project/pyDatalog/).
 
 Deliberate omissions, because saying why teaches more than lacking them
 quietly:
@@ -273,7 +275,7 @@ quietly:
   (disjointness and unsatisfiability detection included). SNOMED needs
   ELH (EL plus role hierarchies) with right identities, which is what
   the ELK and Snorocket reasoners implement and this does not.
-- **A REPL (interactive prompt) and packaging.** `git clone` and run.
+- **A REPL (interactive prompt).** Run a file, or call it from Python.
 
 Aggregation used to be on this list;
 [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
@@ -291,8 +293,27 @@ pip install tiny-datalog
 from tiny_datalog import run_program, explain
 
 engine = run_program(open("supply-chain.dl").read())
-for service, cve in sorted(engine.rels["exposed"]):
-    print("\n".join(explain(engine, "exposed", (service, cve))))
+for answer in engine.query("exposed(S, C)"):
+    print(answer)                     # {'S': 'pkg0', 'C': 'cve_2026_0001'}
+print("\n".join(explain(engine, "exposed", ("pkg0", "cve_2026_0001"))))
+```
+
+Facts can come straight from Python data (a CSV file, a database
+query) instead of program text. Each row is checked as if it had been
+parsed:
+
+```python
+rules = """
+uses(X, Y) :- depends(X, Y).
+uses(X, Z) :- depends(X, Y), uses(Y, Z).
+exposed(S, C) :- service(S), uses(S, L), vulnerable(L, C).
+"""
+engine = run_program(rules, facts={
+    "depends": [("app", "lib"), ("lib", "core")],
+    "service": ["app"],                         # one-column rows may be bare
+    "vulnerable": [("core", "cve_2026_0001")],
+})
+engine.query("exposed(S, C)")       # [{'S': 'app', 'C': 'cve_2026_0001'}]
 ```
 
 The command-line interface installs too, as `tiny-datalog` (and
@@ -332,7 +353,7 @@ cases/          golden test cases — add one without writing Python
 conformance/    the external datalog-conformance corpus (Soufflé, Nemo,
                 Crepe, SPINdle), run against every evaluation strategy
 benchmarks/     scaled input generators (chain/tree/clique/grid)
-tests.py        246 tests: every shipped program and exercise answer is
+tests.py        254 tests: every shipped program and exercise answer is
                 executed, a conformance suite runs every query through
                 every applicable strategy, and a seeded fuzzer checks
                 the same property on random programs

{tiny_datalog-0.2.0 → tiny_datalog-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tiny-datalog"
-version = "0.2.0"
+version = "0.3.0"
 description = "A Datalog engine small enough to read in an afternoon"
 readme = "README.md"
 license = "MIT"

{tiny_datalog-0.2.0 → tiny_datalog-0.3.0}/tiny_datalog/__init__.py

@@ -30,7 +30,7 @@ from tiny_datalog.datalog import (
     format_atom, format_fact,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "Var", "Const", "Struct", "Atom", "Literal", "Rule",

{tiny_datalog-0.2.0 → tiny_datalog-0.3.0}/tiny_datalog/datalog.py

@@ -821,6 +821,27 @@ class Engine:
             groups[key].append(s[var.name])
         return groups
 
+    def query(self, goal):
+        """The answers to a query, one dict per answer, in sorted order:
+
+            engine.query("exposed(S, C)")
+            -> [{"S": "pkg0", "C": "cve_2026_0001"}, ...]
+
+        `goal` is query text or an Atom.  Anonymous variables are left
+        out of the answers; a query with no variables answers [{}] if it
+        holds and [] if it does not."""
+        atom = parse_goal(goal) if isinstance(goal, str) else goal
+        check_query_atom(atom, self.program.arity)
+        names = []
+        for a in atom.args:
+            if isinstance(a, Var) and not a.anonymous and a.name not in names:
+                names.append(a.name)
+        rows = {tuple(s[n] for n in names)
+                for s in (_match(atom.args, tup, {})
+                          for tup in self.rels.get(atom.pred, ()))
+                if s is not None}
+        return [dict(zip(names, row)) for row in sorted(rows, key=_sort_key)]
+
     @staticmethod
     def _instantiate(atom, subst):
         return tuple(a.value if isinstance(a, Const) else subst[a.name]
@@ -851,13 +872,50 @@ def _fold(func, values, rule):
     return agg
 
 
-def run_program(text):
-    """Parse, stratify, and evaluate a program; return the Engine."""
-    engine = Engine(Program(parse(text)))
+def run_program(text, facts=None):
+    """Parse, stratify, and evaluate a program; return the Engine.
+
+    `facts` adds base facts from Python data, so rows from a CSV file or
+    a database query can feed the rules without first being written out
+    as Datalog text:
+
+        run_program(rules, facts={"depends": [("pkg4", "pkg13")],
+                                  "service": ["pkg4"]})
+
+    Each row is a tuple of str, int or float (a bare value is a one-
+    column row), and every fact is checked exactly as if it had been
+    parsed: arity, groundness, and agreement with the rules."""
+    engine = Engine(Program(parse(text) + python_facts(facts or {})))
     engine.run()
     return engine
 
 
+_PREDICATE = re.compile(r"[a-z][A-Za-z0-9_]*\Z")
+
+
+def python_facts(facts):
+    """{predicate: rows} as fact clauses (see run_program)."""
+    clauses = []
+    for pred, rows in facts.items():
+        if not isinstance(pred, str) or not _PREDICATE.match(pred) \
+                or pred == "not":
+            raise DatalogError("%r cannot name a predicate: a predicate is "
+                               "a lowercase identifier" % (pred,))
+        for row in rows:
+            if not isinstance(row, (tuple, list)):
+                row = (row,)
+            for v in row:
+                # bool is an int in Python, and would print as a constant
+                # named True; nan and inf print as constants too
+                if (isinstance(v, bool) or not isinstance(v, (str, int, float))
+                        or (isinstance(v, float) and not math.isfinite(v))):
+                    raise DatalogError(
+                        "fact %s%r: values must be str, int or finite float, "
+                        "not %r" % (pred, tuple(row), v))
+            clauses.append(Rule(Atom(pred, tuple(Const(v) for v in row)), ()))
+    return clauses
+
+
 # ---------------------------------------------------------------------------
 # CLI
 # ---------------------------------------------------------------------------

{tiny_datalog-0.2.0 → tiny_datalog-0.3.0}/tiny_datalog/tabling.py

@@ -30,9 +30,15 @@ the magic predicates' contents.  They are the same sets — magic sets is
 tabling performed at compile time, tabling is magic sets performed at
 run time.
 
-Positive programs only (tabling under negation is SLG resolution, which
-computes the well-founded semantics — XSB's whole claim to fame — and
-is beyond this teaching module).
+Negation is supported when the program is stratified, which is the
+simplification pyDatalog also makes.  A negated subgoal `not q(a)`
+belongs to a lower stratum, so q's tables can be *completed* first —
+grown to fixpoint on their own, since nothing in them depends on the
+rule asking — and then looked up.  Negation through recursion needs
+full SLG resolution (Chen & Warren 1996), which suspends calls instead
+of re-running them, detects when a group of tables is complete, and
+*delays* negative literals it cannot yet decide; it computes the
+well-founded semantics, and Lesson 15 says why it is not here.
 
 CLI
 ---
@@ -47,12 +53,14 @@ import sys
 from collections import defaultdict
 
 from tiny_datalog.datalog import (
-    check_query_atom, Const, DatalogError, format_fact, parse, parse_goal,
-    read_program, validate, _aggregate_of, _match, _sort_key)
+    check_query_atom, Const, DatalogError, StratificationError, format_fact,
+    parse, parse_goal, read_program, stratify, validate, _aggregate_of,
+    _match, _sort_key)
 
 
 class TabledEngine:
-    """Iterative QSQR: tables keyed by call pattern, filled to fixpoint.
+    """Iterative QSQR: tables keyed by call pattern, filled to fixpoint;
+    a negated subgoal's tables are completed first, one stratum down.
 
     After query(), `tables` maps (pred, pattern) — pattern has a constant
     per bound argument and None per free one — to the set of full answer
@@ -65,18 +73,27 @@ class TabledEngine:
                 raise DatalogError("retraction is incremental.py's job: %s" % c)
             if c.body and _aggregate_of(c.head):
                 raise DatalogError(
-                    "tabled aggregation needs completion detection (real "
-                    "SLG); this module is positive-rules-only: %s" % c)
-            for lit in c.body:
-                if lit.negated:
-                    raise DatalogError(
-                        "tabling under negation is SLG resolution (the "
-                        "well-founded semantics, XSB) — beyond this "
-                        "module: %s" % c)
+                    "tabled aggregation is not implemented here — use "
+                    "datalog.py: %s" % c)
+        try:
+            self.strata = stratify(clauses)
+        except StratificationError as exc:
+            raise StratificationError(
+                "%s.  Tabling under unstratified negation is full SLG "
+                "resolution, which computes the well-founded semantics "
+                "(Lesson 15); datalog.py --models computes it bottom-up."
+                % str(exc).rstrip("."), exc.cycle) from exc
         self.by_pred = defaultdict(list)   # (pred, arity) -> clauses
         for c in clauses:
-            self.by_pred[(c.head.pred, len(c.head.args))].append(c)
+            # positive literals first: they bind; negations then test
+            # ground atoms (safety guarantees they are ground by then)
+            body = tuple(sorted(c.body, key=lambda lit: lit.negated))
+            self.by_pred[(c.head.pred, len(c.head.args))].append(
+                (c.head, body))
         self.tables = {}
+        self.complete = set()   # tables known to hold every answer
+        self.open = {}          # ...and the rest, in creation order (a
+                                # dict: a set's order would vary per run)
         self.rounds = 0
 
     # -- call patterns ------------------------------------------------------
@@ -98,8 +115,8 @@ class TabledEngine:
     def _table(self, pred, pattern):
         key = (pred, pattern)
         if key not in self.tables:
-            self.tables[key] = set()   # discovered a new subgoal
-            self._grew = True          # ...which the fixpoint must revisit
+            self.tables[key] = set()   # discovered a new subgoal, which
+            self.open[key] = None      # the fixpoint will now revisit
         return self.tables[key]
 
     # -- one round of top-down solving --------------------------------------
@@ -112,8 +129,17 @@ class TabledEngine:
             yield subst
             return
         lit, rest = body[0], body[1:]
-        table = self._table(lit.atom.pred, self._pattern(lit.atom, subst))
-        for ans in table:
+        key = (lit.atom.pred, self._pattern(lit.atom, subst))
+        table = self._table(*key)
+        if lit.negated:
+            # `not q(a)` may only read a finished table.  q sits in a
+            # lower stratum, so finishing it cannot need this rule.
+            if key not in self.complete:
+                self._fixpoint(below=self.strata.get(lit.atom.pred, 0))
+            if key[1] not in table:     # the pattern is the ground atom
+                yield from self._prove(rest, subst)
+            return
+        for ans in list(table):         # a negation below may add to it
             s = _match(lit.atom.args, ans, subst)
             if s is not None:
                 yield from self._prove(rest, s)
@@ -122,11 +148,11 @@ class TabledEngine:
         """Re-derive a subgoal's answers from its clauses, one step of
         head unification plus a tabled body proof."""
         pred, pattern = key
-        for clause in self.by_pred.get((pred, len(pattern)), ()):
+        for head, body in self.by_pred.get((pred, len(pattern)), ()):
             # unify the head with the call pattern (bound args only)
             seed = {}
             ok = True
-            for a, v in zip(clause.head.args, pattern):
+            for a, v in zip(head.args, pattern):
                 if v is None:
                     continue
                 if isinstance(a, Const):
@@ -140,9 +166,9 @@ class TabledEngine:
                     seed[a.name] = v
             if not ok:
                 continue
-            for s in self._prove(list(clause.body), seed):
+            for s in self._prove(body, seed):
                 yield tuple(a.value if isinstance(a, Const) else s[a.name]
-                            for a in clause.head.args)
+                            for a in head.args)
 
     # -- the fixpoint --------------------------------------------------------
 
@@ -152,21 +178,39 @@ class TabledEngine:
         check_query_atom(atom, self.arity)
         root = (atom.pred, self._pattern(atom, {}))
         self.tables = {root: set()}
+        self.complete = set()
+        self.open = {root: None}
         self.rounds = 0
+        self._fixpoint()
+        return {t for t in self.tables[root]
+                if _match(atom.args, t, {}) is not None}
+
+    def _fixpoint(self, below=None):
+        """Re-solve tables until none grows and no new subgoal appears.
+        With `below`, only the tables of strata up to that one — the
+        nested fixpoint a negation runs to complete what it reads; they
+        are then marked complete.  Without, every table: the query's
+        own fixpoint, whose rounds are the ones counted."""
         changed = True
         while changed:
+            known = len(self.tables)
             changed = False
-            self._grew = False
-            self.rounds += 1
-            for key in list(self.tables):
+            if below is None:
+                self.rounds += 1
+            for key in list(self.open):       # complete tables cannot grow
+                if below is not None and self.strata.get(key[0], 0) > below:
+                    continue
                 table = self.tables[key]
                 for ans in list(self._answers_for(key)):
                     if ans not in table:
                         table.add(ans)
                         changed = True
-            changed = changed or self._grew
-        return {t for t in self.tables[root]
-                if _match(atom.args, t, {}) is not None}
+            changed = changed or len(self.tables) != known
+        done = {k for k in self.open
+                if below is None or self.strata.get(k[0], 0) <= below}
+        self.complete |= done
+        for k in done:
+            del self.open[k]
 
 
 # ---------------------------------------------------------------------------
@@ -175,9 +219,9 @@ class TabledEngine:
 
 def main(argv=None):
     ap = argparse.ArgumentParser(
-        description="Tabled top-down (QSQR) evaluation of positive "
+        description="Tabled top-down (QSQR) evaluation of stratified "
                     "Datalog — handles left recursion SLD cannot.")
-    ap.add_argument("file", help="Datalog program (.dl), positive rules only")
+    ap.add_argument("file", help="Datalog program (.dl), stratified")
     ap.add_argument("-q", "--query", action="append", default=[],
                     metavar="ATOM", help="goal to solve (repeatable)")
     ap.add_argument("-t", "--tables", action="store_true",

{tiny_datalog-0.2.0 → tiny_datalog-0.3.0/tiny_datalog.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-datalog
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Datalog engine small enough to read in an afternoon
 Author: Andrew Goodchild
 License-Expression: MIT
@@ -126,7 +126,7 @@ Nothing to install:
 
 ```sh
 git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
-python3 tests.py        # 246 tests, ~12s
+python3 tests.py        # 254 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -289,7 +289,9 @@ regression test without writing Python.
 
 Not an engine to build a product on. Joins are nested-loop,
 stable-model search is exhaustive, evaluation is batch. For real
-workloads see Soufflé, clingo, RDFox or Feldera.
+workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
+Python application, with arithmetic and queries over SQL databases,
+see [pyDatalog](https://pypi.org/project/pyDatalog/).
 
 Deliberate omissions, because saying why teaches more than lacking them
 quietly:
@@ -306,7 +308,7 @@ quietly:
   (disjointness and unsatisfiability detection included). SNOMED needs
   ELH (EL plus role hierarchies) with right identities, which is what
   the ELK and Snorocket reasoners implement and this does not.
-- **A REPL (interactive prompt) and packaging.** `git clone` and run.
+- **A REPL (interactive prompt).** Run a file, or call it from Python.
 
 Aggregation used to be on this list;
 [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
@@ -324,8 +326,27 @@ pip install tiny-datalog
 from tiny_datalog import run_program, explain
 
 engine = run_program(open("supply-chain.dl").read())
-for service, cve in sorted(engine.rels["exposed"]):
-    print("\n".join(explain(engine, "exposed", (service, cve))))
+for answer in engine.query("exposed(S, C)"):
+    print(answer)                     # {'S': 'pkg0', 'C': 'cve_2026_0001'}
+print("\n".join(explain(engine, "exposed", ("pkg0", "cve_2026_0001"))))
+```
+
+Facts can come straight from Python data (a CSV file, a database
+query) instead of program text. Each row is checked as if it had been
+parsed:
+
+```python
+rules = """
+uses(X, Y) :- depends(X, Y).
+uses(X, Z) :- depends(X, Y), uses(Y, Z).
+exposed(S, C) :- service(S), uses(S, L), vulnerable(L, C).
+"""
+engine = run_program(rules, facts={
+    "depends": [("app", "lib"), ("lib", "core")],
+    "service": ["app"],                         # one-column rows may be bare
+    "vulnerable": [("core", "cve_2026_0001")],
+})
+engine.query("exposed(S, C)")       # [{'S': 'app', 'C': 'cve_2026_0001'}]
 ```
 
 The command-line interface installs too, as `tiny-datalog` (and
@@ -365,7 +386,7 @@ cases/          golden test cases — add one without writing Python
 conformance/    the external datalog-conformance corpus (Soufflé, Nemo,
                 Crepe, SPINdle), run against every evaluation strategy
 benchmarks/     scaled input generators (chain/tree/clique/grid)
-tests.py        246 tests: every shipped program and exercise answer is
+tests.py        254 tests: every shipped program and exercise answer is
                 executed, a conformance suite runs every query through
                 every applicable strategy, and a seeded fuzzer checks
                 the same property on random programs