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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-datalog
-Version: 0.1.2
+Version: 0.3.0
 Summary: A Datalog engine small enough to read in an afternoon
 Author: Andrew Goodchild
 License-Expression: MIT
@@ -9,7 +9,7 @@ Project-URL: Source, https://github.com/andrewgoodchild/tiny-datalog
 Project-URL: Issues, https://github.com/andrewgoodchild/tiny-datalog/issues
 Project-URL: Changelog, https://github.com/andrewgoodchild/tiny-datalog/releases
 Project-URL: Lessons, https://github.com/andrewgoodchild/tiny-datalog/tree/main/lessons
-Keywords: datalog,logic programming,deductive database,semi-naive evaluation,magic sets,provenance,stable models,teaching
+Keywords: datalog,logic programming,deductive database,semi-naive evaluation,magic sets,provenance,stable models,defeasible logic,teaching
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
@@ -126,7 +126,7 @@ Nothing to install:
 
 ```sh
 git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
-python3 tests.py        # 235 tests, ~12s
+python3 tests.py        # 254 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -235,8 +235,10 @@ Answers are also checked against engines this repository did not write.
 [`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
 runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
 corpus, harvested from Soufflé, Nemo and Crepe, through all four
-strategies: 89 cases pass. The 25 it skips need arithmetic or 10⁵-fact
-joins, and both are omissions this course makes on purpose.
+strategies, and its defeasible theories, from SPINdle and the papers,
+through `defeasible.py`: 195 cases pass. Every skip is named with its
+reason: arithmetic and 10⁵-fact joins, which this course omits on
+purpose, or cases written for a different logic.
 
 ## Learning Datalog
 
@@ -246,7 +248,8 @@ the current research threads. The field's own recent lecture notes
 observe that the literature advises people building Datalog engines
 better than people trying to *use* one; this course does both halves
 on purpose — sixteen lessons where the engine is the explanation, then
-a lesson on authoring rules that survive review. And it is built to be
+a lesson on authoring rules that survive review, and one on a logic
+built for rules with exceptions. And it is built to be
 inherited: `git clone`, no dependencies, no hosted anything, and every
 quoted transcript re-verified by CI — the exercises cannot rot. (For where each
 technique ships — CodeQL, RDFox, Feldera, SNOMED and the rest —
@@ -286,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:
@@ -303,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
@@ -321,13 +326,32 @@ 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
 `tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
-`-containment`, `-prolog` for the satellites):
+`-containment`, `-defeasible`, `-prolog` for the satellites):
 
 ```sh
 tiny-datalog -q 'exposed(S, C)' supply-chain.dl
@@ -351,17 +375,18 @@ tiny_datalog/   the engine and its satellites — the code you read:
   tabling.py    tabled top-down evaluation (iterative QSQR)
   subsumption.py  KL-ONE-style EL classifier, compiled to Datalog
   containment.py  query containment and minimisation by homomorphism
+  defeasible.py   defeasible logic: exceptions, priorities, defeaters
 *.py            three-line launchers, so `python3 datalog.py ...` works
                 straight from a checkout with nothing installed
 programs/       teaching programs, numbered by the lesson that uses
                 them (00-* are the README's examples)
-lessons/        getting started, glossary, and lessons 0–18
+lessons/        getting started, glossary, and lessons 0–19
 exercises/      worked answers, verified by the test suite
 cases/          golden test cases — add one without writing Python
 conformance/    the external datalog-conformance corpus (Soufflé, Nemo,
-                Crepe), run against all four evaluation strategies
+                Crepe, SPINdle), run against every evaluation strategy
 benchmarks/     scaled input generators (chain/tree/clique/grid)
-tests.py        235 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
@@ -375,13 +400,13 @@ used.
 ### How big is it, honestly
 
 The evaluator is about 850 lines (`tiny_datalog/datalog.py`, up to the
-command-line interface), the CLI, `--explain` and why-not another 600, and the eight satellite modules about
-2,400. Call it 3.9k lines of toolkit and 2.6k of tests, roughly a
+command-line interface), the CLI, `--explain` and why-not another 600, and the nine satellite modules about
+2,900. Call it 4.3k lines of toolkit and 2.7k of tests, roughly a
 quarter of it commentary.
 
 "Tiny" is a claim about the evaluator, and about each satellite module
-singly: none of the eight exceeds 500 lines, which a test asserts. It is not a claim about
-the repository, which is nine modules because it teaches nine things.
+singly: none of the nine exceeds 500 lines, which a test asserts. It is not a claim about
+the repository, which is ten modules because it teaches ten things.
 
 There is no dead code to golf away (checked); shrinking further means
 deleting either a technique or an explanation.

{tiny_datalog-0.1.2 → 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        # 235 tests, ~12s
+python3 tests.py        # 254 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -202,8 +202,10 @@ Answers are also checked against engines this repository did not write.
 [`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
 runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
 corpus, harvested from Soufflé, Nemo and Crepe, through all four
-strategies: 89 cases pass. The 25 it skips need arithmetic or 10⁵-fact
-joins, and both are omissions this course makes on purpose.
+strategies, and its defeasible theories, from SPINdle and the papers,
+through `defeasible.py`: 195 cases pass. Every skip is named with its
+reason: arithmetic and 10⁵-fact joins, which this course omits on
+purpose, or cases written for a different logic.
 
 ## Learning Datalog
 
@@ -213,7 +215,8 @@ the current research threads. The field's own recent lecture notes
 observe that the literature advises people building Datalog engines
 better than people trying to *use* one; this course does both halves
 on purpose — sixteen lessons where the engine is the explanation, then
-a lesson on authoring rules that survive review. And it is built to be
+a lesson on authoring rules that survive review, and one on a logic
+built for rules with exceptions. And it is built to be
 inherited: `git clone`, no dependencies, no hosted anything, and every
 quoted transcript re-verified by CI — the exercises cannot rot. (For where each
 technique ships — CodeQL, RDFox, Feldera, SNOMED and the rest —
@@ -253,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:
@@ -270,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
@@ -288,13 +293,32 @@ 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
 `tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
-`-containment`, `-prolog` for the satellites):
+`-containment`, `-defeasible`, `-prolog` for the satellites):
 
 ```sh
 tiny-datalog -q 'exposed(S, C)' supply-chain.dl
@@ -318,17 +342,18 @@ tiny_datalog/   the engine and its satellites — the code you read:
   tabling.py    tabled top-down evaluation (iterative QSQR)
   subsumption.py  KL-ONE-style EL classifier, compiled to Datalog
   containment.py  query containment and minimisation by homomorphism
+  defeasible.py   defeasible logic: exceptions, priorities, defeaters
 *.py            three-line launchers, so `python3 datalog.py ...` works
                 straight from a checkout with nothing installed
 programs/       teaching programs, numbered by the lesson that uses
                 them (00-* are the README's examples)
-lessons/        getting started, glossary, and lessons 0–18
+lessons/        getting started, glossary, and lessons 0–19
 exercises/      worked answers, verified by the test suite
 cases/          golden test cases — add one without writing Python
 conformance/    the external datalog-conformance corpus (Soufflé, Nemo,
-                Crepe), run against all four evaluation strategies
+                Crepe, SPINdle), run against every evaluation strategy
 benchmarks/     scaled input generators (chain/tree/clique/grid)
-tests.py        235 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
@@ -342,13 +367,13 @@ used.
 ### How big is it, honestly
 
 The evaluator is about 850 lines (`tiny_datalog/datalog.py`, up to the
-command-line interface), the CLI, `--explain` and why-not another 600, and the eight satellite modules about
-2,400. Call it 3.9k lines of toolkit and 2.6k of tests, roughly a
+command-line interface), the CLI, `--explain` and why-not another 600, and the nine satellite modules about
+2,900. Call it 4.3k lines of toolkit and 2.7k of tests, roughly a
 quarter of it commentary.
 
 "Tiny" is a claim about the evaluator, and about each satellite module
-singly: none of the eight exceeds 500 lines, which a test asserts. It is not a claim about
-the repository, which is nine modules because it teaches nine things.
+singly: none of the nine exceeds 500 lines, which a test asserts. It is not a claim about
+the repository, which is ten modules because it teaches ten things.
 
 There is no dead code to golf away (checked); shrinking further means
 deleting either a technique or an explanation.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tiny-datalog"
-version = "0.1.2"
+version = "0.3.0"
 description = "A Datalog engine small enough to read in an afternoon"
 readme = "README.md"
 license = "MIT"
@@ -14,7 +14,7 @@ authors = [{name = "Andrew Goodchild"}]
 dependencies = []
 keywords = ["datalog", "logic programming", "deductive database",
             "semi-naive evaluation", "magic sets", "provenance",
-            "stable models", "teaching"]
+            "stable models", "defeasible logic", "teaching"]
 # No "License ::" classifier: `license` above is an SPDX expression, and
 # setuptools refuses a build that declares the licence both ways.
 classifiers = [
@@ -51,6 +51,7 @@ tiny-datalog-tabling = "tiny_datalog.tabling:main"
 tiny-datalog-incremental = "tiny_datalog.incremental:main"
 tiny-datalog-subsumption = "tiny_datalog.subsumption:main"
 tiny-datalog-containment = "tiny_datalog.containment:main"
+tiny-datalog-defeasible = "tiny_datalog.defeasible:main"
 
 [tool.setuptools.packages.find]
 include = ["tiny_datalog*"]

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

@@ -10,7 +10,8 @@ Everything else in the package is a satellite built on top of it:
 models), `semiring` (provenance-weighted evaluation), `incremental`
 (maintenance under updates), `tabling` (top-down with memoing),
 `subsumption` (KL-ONE style classification), `containment` (query
-containment), and `prolog` (a Prolog reader for the same syntax).
+containment), `defeasible` (rules with exceptions and priorities), and
+`prolog` (a Prolog reader for the same syntax).
 Import those by name: `from tiny_datalog import semiring`.
 """
 
@@ -29,7 +30,7 @@ from tiny_datalog.datalog import (
     format_atom, format_fact,
 )
 
-__version__ = "0.1.2"
+__version__ = "0.3.0"
 
 __all__ = [
     "Var", "Const", "Struct", "Atom", "Literal", "Rule",

{tiny_datalog-0.1.2 → 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.3.0/tiny_datalog/defeasible.py

@@ -0,0 +1,462 @@
+#!/usr/bin/env python3
+"""
+defeasible.py — defeasible logic: rules with exceptions and priorities.
+(Lesson 18, which ends with a tour of this module.)
+
+Lesson 3 met defaults through `not`: birds fly unless abnormal.  That
+works for one exception, written by hand into the rule it overrides.
+Real rule sets — statutes, policies, eligibility criteria — are made of
+generalisations, exceptions to them, exceptions to the exceptions, and
+an order saying which wins.  Defeasible logic (Nute, 1994) makes all of
+that first-class:
+
+    r1: penguin(X) -> bird(X).        % strict: no exceptions, ever
+    r2: bird(X) => flies(X).          % defeasible: usually
+    r3: penguin(X) => ~flies(X).      % a rule for the opposite
+    r4: injured(X) ~> ~flies(X).      % a defeater: can only block
+    r3 > r2.                          % superiority: r3 beats r2
+
+`~` is *strong* negation — `~flies(opus)` is a claim, not an absence —
+and a conflict is exactly a pair of complementary literals.  There is
+no `not` here at all: exceptions are rules that attack, priorities say
+who wins, and an unresolved conflict yields neither side instead of
+whichever rule happened to have the `not` written into it.
+
+Conclusions carry four tags (Antoniou, Billington, Governatori & Maher
+2001):
+
+    +Δ q   q is definitely provable: facts and strict rules alone
+    −Δ q   q is demonstrably not definitely provable
+    +∂ q   q is defeasibly provable: some applicable rule supports q,
+           ~q is not definite, and every rule for ~q is either
+           inapplicable or beaten by an applicable rule for q
+    −∂ q   q is demonstrably not defeasibly provable
+
+"Demonstrably": a −tag is a finite proof of failure, not the mere
+absence of a +tag.  On a loop like `a => b. b => a.` neither +∂ b nor
+−∂ b is ever established, and the module reports b as *undecided* —
+where Lesson 5's well-founded semantics would settle it false, as does
+the well-founded variant of this logic (Maher & Governatori 1999).
+Standard defeasible logic is characterised instead by Kunen's
+three-valued semantics of a logic program that encodes the theory —
+which is why it cannot see that such a loop has no foundation.
+
+The proof conditions are implemented one-to-one in `_conclude`, over
+the theory's grounding, as a fixpoint: tags are only ever added, so
+iteration stops.  Grounding reuses the core engine.  Every rule, read
+as if strict, is a positive Datalog rule, and its least model bounds
+everything a +tag could be about; see `Theory.ground` for the one
+consequence of grounding that way.  `--propagating` switches from
+ambiguity blocking to ambiguity propagation (`programs/ambiguity.dfl`
+shows the difference).
+"""
+
+import argparse
+import re
+import sys
+from collections import defaultdict
+from itertools import combinations
+
+from tiny_datalog.datalog import (
+    Atom, DatalogError, Engine, Literal, ParseError, Program, Rule,
+    SafetyError, Var, format_atom, match_answers, parse_goal, read_program,
+    _sort_key)
+
+STRICT, DEFEASIBLE, DEFEATER = "->", "=>", "~>"
+
+_TOKEN = re.compile(r"""
+    (?P<comment>%[^\n]*) | (?P<space>\s+)
+  | (?P<string>"[^"\n]*"|'[^'\n]*')
+  | (?P<number>-?[0-9]+(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?)
+  | (?P<arrow>->|=>|~>) | (?P<punct>[:,.()>~])
+  | (?P<name>[A-Za-z_][A-Za-z0-9_]*)
+""", re.VERBOSE)
+
+
+def complement(lit):
+    """`p` <-> `~p`.  A literal is (pred, args); strong negation lives
+    in the predicate name, so the core engine stores ~p as a relation
+    of its own and never needs to know it is special."""
+    pred, args = lit
+    return (pred[1:] if pred.startswith("~") else "~" + pred), args
+
+
+def show(lit):
+    return format_atom(*lit)
+
+
+class Theory:
+    """A parsed defeasible theory: facts, labelled rules, superiority."""
+
+    def __init__(self):
+        self.facts = []         # core Atoms; a ~ fact has pred "~p"
+        self.rules = []         # (label, kind, head Atom, body Atoms)
+        self.superior = set()   # (stronger label, weaker label)
+
+    # -- reading ------------------------------------------------------------
+
+    @classmethod
+    def parse(cls, text):
+        theory = cls()
+        tokens = _tokens(text)
+        statement = []
+        for tok in tokens:
+            statement.append(tok)
+            if tok[1] == "." and _depth(statement) == 0:
+                theory._statement(statement[:-1], tok[2])
+                statement = []
+        if statement:
+            raise ParseError("line %d: expected '.', got end of input"
+                             % statement[-1][2])
+        theory._check()
+        return theory
+
+    def _statement(self, toks, line):
+        text = [t[1] for t in toks]
+        if len(toks) == 3 and text[1] == ">":           # r3 > r2.
+            self.superior.add((text[0], text[2]))
+            return
+        label = None
+        if len(toks) > 1 and toks[0][0] == "name" and text[1] == ":":
+            label, toks = text[0], toks[2:]
+        arrows = [i for i, t in enumerate(toks) if t[0] == "arrow"]
+        if not arrows:
+            if label is not None:
+                raise ParseError("line %d: a labelled statement must be a "
+                                 "rule (->, => or ~>)" % line)
+            self.facts.append(_atom(toks, line))
+            return
+        if len(arrows) > 1:
+            raise ParseError("line %d: one arrow per rule" % line)
+        i = arrows[0]
+        body = [_atom(part, line) for part in _split(toks[:i])]
+        head = _atom(toks[i + 1:], line)
+        self.rules.append((label or "_r%d" % (len(self.rules) + 1),
+                           toks[i][1], head, tuple(_fresh_anonymous(body))))
+
+    def _check(self):
+        labels = [r[0] for r in self.rules]
+        dup = {l for l in labels if labels.count(l) > 1}
+        if dup:
+            raise ParseError("rule label used twice: %s" % ", ".join(sorted(dup)))
+        for pair in self.superior:
+            for l in pair:
+                if l not in labels:
+                    raise ParseError("superiority names unknown rule %s" % l)
+        # the superiority relation must be acyclic, or "r beats s"
+        # could end up meaning r beats itself
+        beats = defaultdict(set)
+        for a, b in self.superior:
+            beats[a].add(b)
+        for start in list(beats):
+            stack, seen = list(beats[start]), set()
+            while stack:
+                x = stack.pop()
+                if x == start:
+                    raise SafetyError("superiority is cyclic through %s"
+                                      % start)
+                if x not in seen:
+                    seen.add(x)
+                    stack.extend(beats[x])
+
+    # -- grounding ----------------------------------------------------------
+
+    def ground(self):
+        """Ground rules (label, kind, head, body) over literals, and the
+        set of facts.
+
+        Every rule is first read as a strict positive Datalog rule; the
+        core engine's least model of that program — the *envelope* —
+        holds every literal any rule could ever establish.  A rule
+        instance is kept when its variables can all be bound by body
+        literals inside the envelope; the body literals it does not
+        match there simply fail.  So `p, q => r` with q underivable is
+        kept, and r is refuted (−∂) as the proof theory says, while an
+        instance no derivable literal could bind at all is never made.
+
+        That is the one place this departs from the proof theory, which
+        ranges over every constant.  A loop nothing starts, written with
+        variables — `a(X) => b(X). b(X) => a(X).` — is not reported at
+        all, where the proof theory would leave each instance undecided.
+        Written without variables it needs no binding, is kept, and
+        comes out undecided (`programs/loops.dfl`)."""
+        rules = [Rule(head, tuple(Literal(b, False) for b in body))
+                 for _l, _k, head, body in self.rules]
+        program = Program([Rule(a, ()) for a in self.facts] + rules)
+        arities = defaultdict(set)
+        for pred, n in program.arity.items():
+            arities[pred.lstrip("~")].add(n)
+        for pred, ns in sorted(arities.items()):
+            if len(ns) > 1:
+                raise SafetyError("predicate %s used with arities %s (its "
+                                  "negation counts too)"
+                                  % (pred, " and ".join(map(str, sorted(ns)))))
+        engine = Engine(program)
+        engine.run()
+        facts = {(a.pred, tuple(x.value for x in a.args)) for a in self.facts}
+        ground, seen = [], set()
+        for label, kind, head, body in self.rules:
+            needed = _variables(body)
+            # match every subset of the body that binds all variables
+            for n in range(len(body) + 1):
+                for part in combinations(body, n):
+                    if _variables(part) != needed:
+                        continue
+                    sub = Rule(head, tuple(Literal(b, False) for b in part))
+                    for subst in engine._rule_substitutions(sub):
+                        g = (label, kind,
+                             (head.pred, engine._instantiate(head, subst)),
+                             tuple((b.pred, engine._instantiate(b, subst))
+                                   for b in body))
+                        if g not in seen:
+                            seen.add(g)
+                            ground.append(g)
+        return facts, ground
+
+    # -- the proof theory ---------------------------------------------------
+
+    def conclusions(self, policy="blocking"):
+        """{tag: set of literals} for the tags +Δ, −Δ, +∂, −∂, and
+        'undecided' for literals that got neither +∂ nor −∂."""
+        if policy not in ("blocking", "propagating"):
+            raise DatalogError("unknown policy %r: use 'blocking' or "
+                               "'propagating'" % (policy,))
+        facts, ground = self.ground()
+        return _conclude(facts, ground, self.superior, policy)
+
+
+def _tokens(text):
+    """(kind, text, line) triples; comments and whitespace dropped."""
+    tokens, pos = [], 0
+    while pos < len(text):
+        m = _TOKEN.match(text, pos)
+        if m is None:
+            raise ParseError("line %d: unexpected character %r"
+                             % (text.count("\n", 0, pos) + 1, text[pos]))
+        if m.lastgroup not in ("space", "comment"):
+            tokens.append((m.lastgroup, m.group(),
+                           text.count("\n", 0, pos) + 1))
+        pos = m.end()
+    return tokens
+
+
+def _variables(atoms):
+    return {a.name for atom in atoms for a in atom.args if isinstance(a, Var)}
+
+
+def _depth(toks):
+    return sum({"(": 1, ")": -1}.get(t[1], 0) for t in toks)
+
+
+def _split(toks):
+    """Comma-separated parts at bracket depth 0."""
+    parts, cur, depth = [], [], 0
+    for t in toks:
+        depth += {"(": 1, ")": -1}.get(t[1], 0)
+        if t[1] == "," and depth == 0:
+            parts.append(cur)
+            cur = []
+        else:
+            cur.append(t)
+    return parts + [cur] if cur else parts
+
+
+def _atom(toks, line):
+    """`[~] atom` -> core Atom, pred prefixed '~' when negated.  The atom
+    itself goes through the core parser, so constants, strings,
+    variables and its error messages are the ones the course knows."""
+    if not toks:
+        raise ParseError("line %d: expected a literal" % line)
+    neg = toks[0][1] == "~"
+    toks = toks[1:] if neg else toks
+    if not toks or toks[0][0] != "name" or toks[0][1][0].isupper():
+        raise ParseError("line %d: expected a literal, got %r"
+                         % (line, " ".join(t[1] for t in toks) or "nothing"))
+    atom = parse_goal(" ".join(t[1] for t in toks))
+    return Atom(("~" if neg else "") + atom.pred, atom.args)
+
+
+def _fresh_anonymous(atoms):
+    """Each literal was parsed on its own, so each numbered its `_`s from
+    1; renumber so two `_` in one rule stay two different variables."""
+    n = 0
+    out = []
+    for a in atoms:
+        args = []
+        for x in a.args:
+            if isinstance(x, Var) and x.anonymous:
+                n += 1
+                x = Var("_#%d" % n)
+            args.append(x)
+        out.append(Atom(a.pred, tuple(args)))
+    return out
+
+
+def _conclude(facts, ground, superior, policy):
+    """The proof conditions, as a fixpoint (Antoniou, Billington,
+    Governatori & Maher 2001).  For a literal q, R[q] is every rule for
+    q, Rs[q] the strict ones, Rsd[q] strict or defeasible — defeaters
+    may attack, never support — and A(r) is rule r's body:
+
+      +Δq  q is a fact, or some r in Rs[q] has A(r) all +Δ.
+      −Δq  q is not a fact, and every r in Rs[q] has some a in A(r) −Δ.
+      +∂q  +Δq; or (1) some r in Rsd[q] has A(r) all +∂, (2) ~q is −Δ,
+           and (3) every attacker s in R[~q] is either dead — some a in
+           A(s) is −∂ — or beaten: some t in Rsd[q] with A(t) all +∂
+           and t > s.  The t may differ per attacker: team defeat.
+      −∂q  −Δq, and: every r in Rsd[q] has some a in A(r) −∂; or ~q is
+           +Δ; or some attacker s in R[~q] is live — A(s) all +∂ — and
+           every t in Rsd[q] has a body literal −∂ or is not above s.
+
+    That is ambiguity *blocking*: an attacker only counts once its body
+    is proved.  Under ambiguity *propagation* (Maher 2012) the same
+    conditions hold with attackers judged by mere *support*, σ:
+
+      +σq  +Δq, or some r in Rsd[q] has A(r) all +σ, and no attacker
+           s in R[~q] with no −∂ body literal is above r.
+      −σq  −Δq, and every r in Rsd[q] has a body literal −σ, or is
+           below some attacker s in R[~q] with A(s) all +∂.
+
+    and in +∂ an attacker is dead only if a body literal is −σ, while in
+    −∂ it is live as soon as A(s) is all +σ.  Supported-but-unproved
+    attackers then still block, so doubt spreads downstream."""
+    by_head = defaultdict(list)
+    for rule in ground:
+        by_head[rule[2]].append(rule)
+    # report on every literal the theory mentions; decide its complement
+    # too, since every +∂ / −∂ condition looks at ~q
+    mentioned = set(facts) | set(by_head) | {a for r in ground for a in r[3]}
+    universe = mentioned | {complement(q) for q in mentioned}
+
+    def strict(q):
+        return [r for r in by_head[q] if r[1] == STRICT]
+
+    def supporting(q):
+        return [r for r in by_head[q] if r[1] != DEFEATER]
+
+    def body_in(r, tagged):
+        return all(a in tagged for a in r[3])
+
+    def body_hits(r, tagged):
+        return any(a in tagged for a in r[3])
+
+    def above(t, s):
+        return (t[0], s[0]) in superior
+
+    plus_d, minus_d = set(), set()       # +Δ, −Δ: the strict part first
+    changed = True
+    while changed:
+        changed = False
+        for q in universe:
+            if q not in plus_d and (q in facts or any(
+                    body_in(r, plus_d) for r in strict(q))):
+                plus_d.add(q)
+                changed = True
+            if q not in minus_d and q not in facts and all(
+                    body_hits(r, minus_d) for r in strict(q)):
+                minus_d.add(q)
+                changed = True
+
+    plus, minus = set(), set()           # +∂, −∂
+    if policy == "propagating":
+        s_plus, s_minus = set(), set()   # +σ, −σ: who is merely supported
+    else:
+        s_plus, s_minus = plus, minus    # blocking: support = proof
+    changed = True
+    while changed:
+        changed = False
+        for q in universe:
+            nq = complement(q)
+            attackers = by_head[nq]
+            if q not in plus and (q in plus_d or (
+                    any(body_in(r, plus) for r in supporting(q))
+                    and nq in minus_d
+                    and all(body_hits(s, s_minus) or any(
+                        body_in(t, plus) and above(t, s)
+                        for t in supporting(q)) for s in attackers))):
+                plus.add(q)
+                changed = True
+            if q not in minus and q in minus_d and (
+                    all(body_hits(r, minus) for r in supporting(q))
+                    or nq in plus_d
+                    or any(body_in(s, s_plus) and all(
+                        body_hits(t, minus) or not above(t, s)
+                        for t in supporting(q)) for s in attackers)):
+                minus.add(q)
+                changed = True
+            if policy != "propagating":
+                continue
+            if q not in s_plus and (q in plus_d or any(
+                    body_in(r, s_plus) and all(
+                        body_hits(s, minus) or not above(s, r)
+                        for s in attackers)
+                    for r in supporting(q))):
+                s_plus.add(q)
+                changed = True
+            if q not in s_minus and q in minus_d and all(
+                    body_hits(r, s_minus) or any(
+                        body_in(s, plus) and above(s, r) for s in attackers)
+                    for r in supporting(q)):
+                s_minus.add(q)
+                changed = True
+    return {"+Δ": plus_d & mentioned, "−Δ": minus_d & mentioned,
+            "+∂": plus & mentioned, "−∂": minus & mentioned,
+            "undecided": mentioned - plus - minus}
+
+
+def load(text):
+    return Theory.parse(text)
+
+
+TAG_NAMES = [("+Δ", "definitely"), ("+∂", "defeasibly"),
+             ("−∂", "not defeasibly"), ("undecided", "undecided")]
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Defeasible logic: strict rules (->), defeasible rules "
+                    "(=>), defeaters (~>), superiority (r1 > r2).")
+    ap.add_argument("file", help="defeasible theory")
+    ap.add_argument("-q", "--query", action="append", default=[],
+                    metavar="LITERAL",
+                    help="show the tags of matching literals (repeatable), "
+                         "e.g. -q 'flies(X)' or -q '~flies(X)'")
+    ap.add_argument("--propagating", action="store_true",
+                    help="ambiguity propagating instead of blocking")
+    args = ap.parse_args(argv)
+    try:
+        theory = load(read_program(args.file))
+        result = theory.conclusions(
+            "propagating" if args.propagating else "blocking")
+        queries = [_atom(_tokens(q.rstrip(". ")), 1) for q in args.query]
+    except DatalogError as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 1
+
+    def ordered(lits):
+        return sorted(lits, key=lambda l: (l[0].lstrip("~"), l[0],
+                                           _sort_key(l[1])))
+
+    if queries:
+        for q in queries:
+            print("?- %s" % (q.pred if not q.args else "%s(%s)" % (
+                q.pred, ", ".join(str(a) for a in q.args))))
+            hits = [l for l in ordered(set().union(*result.values()))
+                    if l[0] == q.pred and match_answers(q, [l[1]])]
+            for lit in hits:
+                tags = [t for t, _n in TAG_NAMES if lit in result[t]]
+                print("   %-28s %s" % (show(lit), "  ".join(tags)))
+            if not hits:
+                print("   (no rule or fact mentions it)")
+        return 0
+    for tag, name in TAG_NAMES:
+        lits = ordered(result[tag])
+        print("%s %s (%d)" % (tag, name, len(lits)) if tag != "undecided"
+              else "%s (%d)" % (name, len(lits)))
+        for lit in lits:
+            print("   " + show(lit))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{tiny_datalog-0.1.2 → 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.1.2 → tiny_datalog-0.3.0/tiny_datalog.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-datalog
-Version: 0.1.2
+Version: 0.3.0
 Summary: A Datalog engine small enough to read in an afternoon
 Author: Andrew Goodchild
 License-Expression: MIT
@@ -9,7 +9,7 @@ Project-URL: Source, https://github.com/andrewgoodchild/tiny-datalog
 Project-URL: Issues, https://github.com/andrewgoodchild/tiny-datalog/issues
 Project-URL: Changelog, https://github.com/andrewgoodchild/tiny-datalog/releases
 Project-URL: Lessons, https://github.com/andrewgoodchild/tiny-datalog/tree/main/lessons
-Keywords: datalog,logic programming,deductive database,semi-naive evaluation,magic sets,provenance,stable models,teaching
+Keywords: datalog,logic programming,deductive database,semi-naive evaluation,magic sets,provenance,stable models,defeasible logic,teaching
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
@@ -126,7 +126,7 @@ Nothing to install:
 
 ```sh
 git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
-python3 tests.py        # 235 tests, ~12s
+python3 tests.py        # 254 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -235,8 +235,10 @@ Answers are also checked against engines this repository did not write.
 [`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
 runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
 corpus, harvested from Soufflé, Nemo and Crepe, through all four
-strategies: 89 cases pass. The 25 it skips need arithmetic or 10⁵-fact
-joins, and both are omissions this course makes on purpose.
+strategies, and its defeasible theories, from SPINdle and the papers,
+through `defeasible.py`: 195 cases pass. Every skip is named with its
+reason: arithmetic and 10⁵-fact joins, which this course omits on
+purpose, or cases written for a different logic.
 
 ## Learning Datalog
 
@@ -246,7 +248,8 @@ the current research threads. The field's own recent lecture notes
 observe that the literature advises people building Datalog engines
 better than people trying to *use* one; this course does both halves
 on purpose — sixteen lessons where the engine is the explanation, then
-a lesson on authoring rules that survive review. And it is built to be
+a lesson on authoring rules that survive review, and one on a logic
+built for rules with exceptions. And it is built to be
 inherited: `git clone`, no dependencies, no hosted anything, and every
 quoted transcript re-verified by CI — the exercises cannot rot. (For where each
 technique ships — CodeQL, RDFox, Feldera, SNOMED and the rest —
@@ -286,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:
@@ -303,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
@@ -321,13 +326,32 @@ 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
 `tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
-`-containment`, `-prolog` for the satellites):
+`-containment`, `-defeasible`, `-prolog` for the satellites):
 
 ```sh
 tiny-datalog -q 'exposed(S, C)' supply-chain.dl
@@ -351,17 +375,18 @@ tiny_datalog/   the engine and its satellites — the code you read:
   tabling.py    tabled top-down evaluation (iterative QSQR)
   subsumption.py  KL-ONE-style EL classifier, compiled to Datalog
   containment.py  query containment and minimisation by homomorphism
+  defeasible.py   defeasible logic: exceptions, priorities, defeaters
 *.py            three-line launchers, so `python3 datalog.py ...` works
                 straight from a checkout with nothing installed
 programs/       teaching programs, numbered by the lesson that uses
                 them (00-* are the README's examples)
-lessons/        getting started, glossary, and lessons 0–18
+lessons/        getting started, glossary, and lessons 0–19
 exercises/      worked answers, verified by the test suite
 cases/          golden test cases — add one without writing Python
 conformance/    the external datalog-conformance corpus (Soufflé, Nemo,
-                Crepe), run against all four evaluation strategies
+                Crepe, SPINdle), run against every evaluation strategy
 benchmarks/     scaled input generators (chain/tree/clique/grid)
-tests.py        235 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
@@ -375,13 +400,13 @@ used.
 ### How big is it, honestly
 
 The evaluator is about 850 lines (`tiny_datalog/datalog.py`, up to the
-command-line interface), the CLI, `--explain` and why-not another 600, and the eight satellite modules about
-2,400. Call it 3.9k lines of toolkit and 2.6k of tests, roughly a
+command-line interface), the CLI, `--explain` and why-not another 600, and the nine satellite modules about
+2,900. Call it 4.3k lines of toolkit and 2.7k of tests, roughly a
 quarter of it commentary.
 
 "Tiny" is a claim about the evaluator, and about each satellite module
-singly: none of the eight exceeds 500 lines, which a test asserts. It is not a claim about
-the repository, which is nine modules because it teaches nine things.
+singly: none of the nine exceeds 500 lines, which a test asserts. It is not a claim about
+the repository, which is ten modules because it teaches ten things.
 
 There is no dead code to golf away (checked); shrinking further means
 deleting either a technique or an explanation.

{tiny_datalog-0.1.2 → tiny_datalog-0.3.0}/tiny_datalog.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 tiny_datalog/__init__.py
 tiny_datalog/containment.py
 tiny_datalog/datalog.py
+tiny_datalog/defeasible.py
 tiny_datalog/incremental.py
 tiny_datalog/magic.py
 tiny_datalog/prolog.py

{tiny_datalog-0.1.2 → tiny_datalog-0.3.0}/tiny_datalog.egg-info/entry_points.txt

@@ -1,6 +1,7 @@
 [console_scripts]
 tiny-datalog = tiny_datalog.datalog:main
 tiny-datalog-containment = tiny_datalog.containment:main
+tiny-datalog-defeasible = tiny_datalog.defeasible:main
 tiny-datalog-incremental = tiny_datalog.incremental:main
 tiny-datalog-prolog = tiny_datalog.prolog:main
 tiny-datalog-semiring = tiny_datalog.semiring:main