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

{tiny_datalog-0.1.1 → tiny_datalog-0.2.0}/PKG-INFO

@@ -1,10 +1,31 @@
 Metadata-Version: 2.4
 Name: tiny-datalog
-Version: 0.1.1
+Version: 0.2.0
 Summary: A Datalog engine small enough to read in an afternoon
 Author: Andrew Goodchild
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/andrewgoodchild/tiny-datalog
+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,defeasible logic,teaching
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -105,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        # 246 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -210,6 +231,15 @@ tabled evaluation all agree, and that incremental maintenance matches
 recomputation under random updates. 400 programs per run;
 `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
 
+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, 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
 
 `lessons/` is a complete course, no prior exposure assumed, every
@@ -218,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 —
@@ -299,7 +330,7 @@ for service, cve in sorted(engine.rels["exposed"]):
 
 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
@@ -323,15 +354,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, 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        246 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
@@ -345,13 +379,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.1/tiny_datalog.egg-info/PKG-INFO → tiny_datalog-0.2.0/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: tiny-datalog
-Version: 0.1.1
-Summary: A Datalog engine small enough to read in an afternoon
-Author: Andrew Goodchild
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/andrewgoodchild/tiny-datalog
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
 # tiny-datalog
 
 [![tests](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml/badge.svg)](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml)
@@ -105,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        # 246 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -210,6 +198,15 @@ tabled evaluation all agree, and that incremental maintenance matches
 recomputation under random updates. 400 programs per run;
 `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
 
+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, 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
 
 `lessons/` is a complete course, no prior exposure assumed, every
@@ -218,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 —
@@ -299,7 +297,7 @@ for service, cve in sorted(engine.rels["exposed"]):
 
 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
@@ -323,15 +321,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, 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        246 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
@@ -345,13 +346,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.2.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tiny-datalog"
+version = "0.2.0"
+description = "A Datalog engine small enough to read in an afternoon"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{name = "Andrew Goodchild"}]
+dependencies = []
+keywords = ["datalog", "logic programming", "deductive database",
+            "semi-naive evaluation", "magic sets", "provenance",
+            "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 = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Education",
+    "Topic :: Software Development :: Interpreters",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/andrewgoodchild/tiny-datalog"
+Source = "https://github.com/andrewgoodchild/tiny-datalog"
+Issues = "https://github.com/andrewgoodchild/tiny-datalog/issues"
+Changelog = "https://github.com/andrewgoodchild/tiny-datalog/releases"
+Lessons = "https://github.com/andrewgoodchild/tiny-datalog/tree/main/lessons"
+
+[project.scripts]
+tiny-datalog = "tiny_datalog.datalog:main"
+tiny-datalog-prolog = "tiny_datalog.prolog:main"
+tiny-datalog-semiring = "tiny_datalog.semiring:main"
+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.1 → tiny_datalog-0.2.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.1"
+__version__ = "0.2.0"
 
 __all__ = [
     "Var", "Const", "Struct", "Atom", "Literal", "Rule",

tiny_datalog-0.2.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.1/README.md → tiny_datalog-0.2.0/tiny_datalog.egg-info/PKG-INFO

@@ -1,3 +1,36 @@
+Metadata-Version: 2.4
+Name: tiny-datalog
+Version: 0.2.0
+Summary: A Datalog engine small enough to read in an afternoon
+Author: Andrew Goodchild
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/andrewgoodchild/tiny-datalog
+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,defeasible logic,teaching
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
 # tiny-datalog
 
 [![tests](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml/badge.svg)](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml)
@@ -93,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        # 246 tests, ~12s
 ```
 
 ## Why the language choice decides what you can ask later
@@ -198,6 +231,15 @@ tabled evaluation all agree, and that incremental maintenance matches
 recomputation under random updates. 400 programs per run;
 `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
 
+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, 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
 
 `lessons/` is a complete course, no prior exposure assumed, every
@@ -206,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 —
@@ -287,7 +330,7 @@ for service, cve in sorted(engine.rels["exposed"]):
 
 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
@@ -311,15 +354,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, 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        246 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
@@ -333,13 +379,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.1 → tiny_datalog-0.2.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.1 → tiny_datalog-0.2.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

tiny_datalog-0.1.1/pyproject.toml

@@ -1,29 +0,0 @@
-[build-system]
-requires = ["setuptools>=77"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "tiny-datalog"
-version = "0.1.1"
-description = "A Datalog engine small enough to read in an afternoon"
-readme = "README.md"
-license = "MIT"
-license-files = ["LICENSE"]
-requires-python = ">=3.9"
-authors = [{name = "Andrew Goodchild"}]
-dependencies = []
-
-[project.urls]
-Homepage = "https://github.com/andrewgoodchild/tiny-datalog"
-
-[project.scripts]
-tiny-datalog = "tiny_datalog.datalog:main"
-tiny-datalog-prolog = "tiny_datalog.prolog:main"
-tiny-datalog-semiring = "tiny_datalog.semiring:main"
-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"
-
-[tool.setuptools.packages.find]
-include = ["tiny_datalog*"]