tiny-datalog 0.2.0__tar.gz → 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {tiny_datalog-0.2.0/tiny_datalog.egg-info → tiny_datalog-0.4.0}/PKG-INFO +79 -26
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/README.md +77 -24
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/pyproject.toml +2 -2
- tiny_datalog-0.4.0/tiny_datalog/__init__.py +48 -0
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/containment.py +51 -62
- tiny_datalog-0.4.0/tiny_datalog/core.py +785 -0
- tiny_datalog-0.4.0/tiny_datalog/datalog.py +930 -0
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/defeasible.py +13 -16
- tiny_datalog-0.4.0/tiny_datalog/engines.py +125 -0
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/incremental.py +86 -89
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/magic.py +5 -4
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/prolog.py +12 -24
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/semantics.py +23 -48
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/semiring.py +13 -20
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/subsumption.py +19 -22
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/tabling.py +89 -61
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0/tiny_datalog.egg-info}/PKG-INFO +79 -26
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog.egg-info/SOURCES.txt +2 -0
- tiny_datalog-0.2.0/tiny_datalog/__init__.py +0 -43
- tiny_datalog-0.2.0/tiny_datalog/datalog.py +0 -1455
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/LICENSE +0 -0
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/setup.cfg +0 -0
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog.egg-info/dependency_links.txt +0 -0
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog.egg-info/entry_points.txt +0 -0
- {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog.egg-info/top_level.txt +0 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: tiny-datalog
|
|
3
|
-
Version: 0.
|
|
4
|
-
Summary: A Datalog engine
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: A Datalog engine whose core you can read in an afternoon, and a course built on it
|
|
5
5
|
Author: Andrew Goodchild
|
|
6
6
|
License-Expression: MIT
|
|
7
7
|
Project-URL: Homepage, https://github.com/andrewgoodchild/tiny-datalog
|
|
@@ -36,8 +36,9 @@ Dynamic: license-file
|
|
|
36
36
|
[](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml)
|
|
37
37
|
[](https://pypi.org/project/tiny-datalog/)
|
|
38
38
|
|
|
39
|
-
**A
|
|
40
|
-
that builds it up from nothing
|
|
39
|
+
**A Datalog engine whose core you can read in an afternoon, a course
|
|
40
|
+
that builds it up from nothing, and a module for every technique the
|
|
41
|
+
course teaches.**
|
|
41
42
|
|
|
42
43
|
## What is Datalog?
|
|
43
44
|
|
|
@@ -126,7 +127,7 @@ Nothing to install:
|
|
|
126
127
|
|
|
127
128
|
```sh
|
|
128
129
|
git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
|
|
129
|
-
python3 tests.py #
|
|
130
|
+
python3 tests.py # 303 tests, ~12s
|
|
130
131
|
```
|
|
131
132
|
|
|
132
133
|
## Why the language choice decides what you can ask later
|
|
@@ -193,7 +194,7 @@ the better tool, and that covers most problems.
|
|
|
193
194
|
|
|
194
195
|
## What else you can ask it
|
|
195
196
|
|
|
196
|
-
The worked example above is one row of a table. The full version —
|
|
197
|
+
The worked example above is one row of a table. The full version — 23
|
|
197
198
|
questions, each with the command that answers it and the lesson that
|
|
198
199
|
builds the machinery — is in
|
|
199
200
|
[getting started](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/getting-started.md), beside the reading
|
|
@@ -272,7 +273,7 @@ engine:
|
|
|
272
273
|
which is a real design-review question with a real answer.
|
|
273
274
|
- **[Lesson 16](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/16-containment.md)** shows that the containment
|
|
274
275
|
test you need for query minimisation is the search already sitting in
|
|
275
|
-
|
|
276
|
+
the core: `match` maps a rule body into a database,
|
|
276
277
|
`find_homomorphism` maps a rule body into another rule body. Same
|
|
277
278
|
backtracking, one level up.
|
|
278
279
|
- **[Lesson 4](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/04-closed-and-open-worlds.md)** contrasts the
|
|
@@ -289,7 +290,9 @@ regression test without writing Python.
|
|
|
289
290
|
|
|
290
291
|
Not an engine to build a product on. Joins are nested-loop,
|
|
291
292
|
stable-model search is exhaustive, evaluation is batch. For real
|
|
292
|
-
workloads see Soufflé, clingo, RDFox or Feldera
|
|
293
|
+
workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
|
|
294
|
+
Python application, with arithmetic and queries over SQL databases,
|
|
295
|
+
see [pyDatalog](https://pypi.org/project/pyDatalog/).
|
|
293
296
|
|
|
294
297
|
Deliberate omissions, because saying why teaches more than lacking them
|
|
295
298
|
quietly:
|
|
@@ -306,7 +309,7 @@ quietly:
|
|
|
306
309
|
(disjointness and unsatisfiability detection included). SNOMED needs
|
|
307
310
|
ELH (EL plus role hierarchies) with right identities, which is what
|
|
308
311
|
the ELK and Snorocket reasoners implement and this does not.
|
|
309
|
-
- **A REPL (interactive prompt)
|
|
312
|
+
- **A REPL (interactive prompt).** Run a file, or call it from Python.
|
|
310
313
|
|
|
311
314
|
Aggregation used to be on this list;
|
|
312
315
|
[lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
|
|
@@ -324,13 +327,33 @@ pip install tiny-datalog
|
|
|
324
327
|
from tiny_datalog import run_program, explain
|
|
325
328
|
|
|
326
329
|
engine = run_program(open("supply-chain.dl").read())
|
|
327
|
-
for
|
|
328
|
-
print(
|
|
330
|
+
for answer in engine.query("exposed(S, C)"):
|
|
331
|
+
print(answer) # {'S': 'pkg0', 'C': 'cve_2026_0001'}
|
|
332
|
+
print("\n".join(explain(engine, "exposed", ("pkg0", "cve_2026_0001"))))
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Facts can come straight from Python data (a CSV file, a database
|
|
336
|
+
query) instead of program text. Each row is checked as if it had been
|
|
337
|
+
parsed:
|
|
338
|
+
|
|
339
|
+
```python
|
|
340
|
+
rules = """
|
|
341
|
+
uses(X, Y) :- depends(X, Y).
|
|
342
|
+
uses(X, Z) :- depends(X, Y), uses(Y, Z).
|
|
343
|
+
exposed(S, C) :- service(S), uses(S, L), vulnerable(L, C).
|
|
344
|
+
"""
|
|
345
|
+
engine = run_program(rules, facts={
|
|
346
|
+
"depends": [("app", "lib"), ("lib", "core")],
|
|
347
|
+
"service": ["app"], # one-column rows may be bare
|
|
348
|
+
"vulnerable": [("core", "cve_2026_0001")],
|
|
349
|
+
})
|
|
350
|
+
engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
|
|
329
351
|
```
|
|
330
352
|
|
|
331
353
|
The command-line interface installs too, as `tiny-datalog` (and
|
|
332
354
|
`tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
|
|
333
|
-
`-containment`, `-defeasible`, `-prolog` for the
|
|
355
|
+
`-containment`, `-defeasible`, `-prolog` for the other engines and the
|
|
356
|
+
extensions):
|
|
334
357
|
|
|
335
358
|
```sh
|
|
336
359
|
tiny-datalog -q 'exposed(S, C)' supply-chain.dl
|
|
@@ -342,16 +365,22 @@ installed package; clone the repository for that.
|
|
|
342
365
|
## Layout
|
|
343
366
|
|
|
344
367
|
```
|
|
345
|
-
tiny_datalog/ the
|
|
346
|
-
|
|
347
|
-
|
|
368
|
+
tiny_datalog/ the code you read, in three tiers:
|
|
369
|
+
core.py the common core — the language every module shares:
|
|
370
|
+
AST, parser, safety checks, stratification, matching,
|
|
371
|
+
formatting, query helpers
|
|
372
|
+
engines — four strategies, one answer (engines.py lists them):
|
|
373
|
+
datalog.py the base engine: semi-naive and naive bottom-up
|
|
374
|
+
evaluation, aggregation, --explain / why-not, the CLI
|
|
348
375
|
magic.py the magic-sets rewriting (a program-to-program pass)
|
|
376
|
+
tabling.py tabled top-down evaluation (iterative QSQR)
|
|
377
|
+
engines.py the registry and the interface the four share
|
|
378
|
+
extensions — other questions asked of the same programs:
|
|
349
379
|
semantics.py grounding, stable models, the well-founded model
|
|
350
380
|
semiring.py semiring-valued evaluation (costs, counts, provenance,
|
|
351
381
|
probabilities)
|
|
352
382
|
incremental.py insertions + DRed deletions over a live materialisation
|
|
353
383
|
prolog.py top-down SLD resolution with function symbols
|
|
354
|
-
tabling.py tabled top-down evaluation (iterative QSQR)
|
|
355
384
|
subsumption.py KL-ONE-style EL classifier, compiled to Datalog
|
|
356
385
|
containment.py query containment and minimisation by homomorphism
|
|
357
386
|
defeasible.py defeasible logic: exceptions, priorities, defeaters
|
|
@@ -364,10 +393,11 @@ exercises/ worked answers, verified by the test suite
|
|
|
364
393
|
cases/ golden test cases — add one without writing Python
|
|
365
394
|
conformance/ the external datalog-conformance corpus (Soufflé, Nemo,
|
|
366
395
|
Crepe, SPINdle), run against every evaluation strategy
|
|
367
|
-
benchmarks/ scaled input generators (chain/tree/clique/grid
|
|
368
|
-
|
|
396
|
+
benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
|
|
397
|
+
ontology, and the N-queens puzzle)
|
|
398
|
+
tests.py 303 tests: every shipped program and exercise answer is
|
|
369
399
|
executed, a conformance suite runs every query through
|
|
370
|
-
every
|
|
400
|
+
every engine that handles it, and a seeded fuzzer checks
|
|
371
401
|
the same property on random programs
|
|
372
402
|
```
|
|
373
403
|
|
|
@@ -378,14 +408,37 @@ used.
|
|
|
378
408
|
|
|
379
409
|
### How big is it, honestly
|
|
380
410
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
411
|
+
This project started as an attempt at a tiny implementation of
|
|
412
|
+
Datalog, small enough to read in an afternoon. It grew with the
|
|
413
|
+
course. Each lesson that taught a new technique — magic sets, stable models,
|
|
414
|
+
semirings, incremental maintenance, tabling, subsumption, containment,
|
|
415
|
+
defeasible logic — brought a module to run it, and the repository is
|
|
416
|
+
now several thousand lines. The core idea stayed small, and the code
|
|
417
|
+
is laid out so you can still read just that: the common core and the
|
|
418
|
+
base engine, below, are the original tiny Datalog. Everything else is
|
|
419
|
+
an engine or extension you can take one lesson at a time.
|
|
385
420
|
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
421
|
+
Measured in lines, comments, docstrings and blank lines included:
|
|
422
|
+
|
|
423
|
+
| Tier | Lines |
|
|
424
|
+
|---|---|
|
|
425
|
+
| the common core (`core.py`: the language, evaluating nothing) | 785 |
|
|
426
|
+
| the base engine's evaluator (`datalog.py` up to its CLI section: the module docstring, the import list that re-exports the core, `Program`, `Engine`, aggregation folding, `run_program`) | 395 |
|
|
427
|
+
| `--explain`, why-not, printing and the CLI (the rest of `datalog.py`) | 535 |
|
|
428
|
+
| the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`), plus the `engines.py` registry (naive evaluation is a flag on the base engine) | 549 |
|
|
429
|
+
| the seven extensions | 2,425 |
|
|
430
|
+
|
|
431
|
+
So the smallest complete Datalog system here — parse, check, stratify,
|
|
432
|
+
evaluate semi-naively — is the core plus the evaluator, about 1,200
|
|
433
|
+
lines. All of it is 4.7k lines of toolkit (every module but the
|
|
434
|
+
re-export list in `__init__.py`), roughly a quarter of it commentary,
|
|
435
|
+
and 3.4k of tests.
|
|
436
|
+
|
|
437
|
+
"Tiny" is a claim about that core and evaluator, and about each module
|
|
438
|
+
built on them singly: none of the ten (`magic.py`, `tabling.py`,
|
|
439
|
+
`engines.py` and the seven extensions) exceeds 500 lines, which a test asserts. It is not a
|
|
440
|
+
claim about the repository, which is a dozen modules because it
|
|
441
|
+
teaches a dozen things.
|
|
389
442
|
|
|
390
443
|
There is no dead code to golf away (checked); shrinking further means
|
|
391
444
|
deleting either a technique or an explanation.
|
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
[](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml)
|
|
4
4
|
[](https://pypi.org/project/tiny-datalog/)
|
|
5
5
|
|
|
6
|
-
**A
|
|
7
|
-
that builds it up from nothing
|
|
6
|
+
**A Datalog engine whose core you can read in an afternoon, a course
|
|
7
|
+
that builds it up from nothing, and a module for every technique the
|
|
8
|
+
course teaches.**
|
|
8
9
|
|
|
9
10
|
## What is Datalog?
|
|
10
11
|
|
|
@@ -93,7 +94,7 @@ Nothing to install:
|
|
|
93
94
|
|
|
94
95
|
```sh
|
|
95
96
|
git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
|
|
96
|
-
python3 tests.py #
|
|
97
|
+
python3 tests.py # 303 tests, ~12s
|
|
97
98
|
```
|
|
98
99
|
|
|
99
100
|
## Why the language choice decides what you can ask later
|
|
@@ -160,7 +161,7 @@ the better tool, and that covers most problems.
|
|
|
160
161
|
|
|
161
162
|
## What else you can ask it
|
|
162
163
|
|
|
163
|
-
The worked example above is one row of a table. The full version —
|
|
164
|
+
The worked example above is one row of a table. The full version — 23
|
|
164
165
|
questions, each with the command that answers it and the lesson that
|
|
165
166
|
builds the machinery — is in
|
|
166
167
|
[getting started](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/getting-started.md), beside the reading
|
|
@@ -239,7 +240,7 @@ engine:
|
|
|
239
240
|
which is a real design-review question with a real answer.
|
|
240
241
|
- **[Lesson 16](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/16-containment.md)** shows that the containment
|
|
241
242
|
test you need for query minimisation is the search already sitting in
|
|
242
|
-
|
|
243
|
+
the core: `match` maps a rule body into a database,
|
|
243
244
|
`find_homomorphism` maps a rule body into another rule body. Same
|
|
244
245
|
backtracking, one level up.
|
|
245
246
|
- **[Lesson 4](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/04-closed-and-open-worlds.md)** contrasts the
|
|
@@ -256,7 +257,9 @@ regression test without writing Python.
|
|
|
256
257
|
|
|
257
258
|
Not an engine to build a product on. Joins are nested-loop,
|
|
258
259
|
stable-model search is exhaustive, evaluation is batch. For real
|
|
259
|
-
workloads see Soufflé, clingo, RDFox or Feldera
|
|
260
|
+
workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
|
|
261
|
+
Python application, with arithmetic and queries over SQL databases,
|
|
262
|
+
see [pyDatalog](https://pypi.org/project/pyDatalog/).
|
|
260
263
|
|
|
261
264
|
Deliberate omissions, because saying why teaches more than lacking them
|
|
262
265
|
quietly:
|
|
@@ -273,7 +276,7 @@ quietly:
|
|
|
273
276
|
(disjointness and unsatisfiability detection included). SNOMED needs
|
|
274
277
|
ELH (EL plus role hierarchies) with right identities, which is what
|
|
275
278
|
the ELK and Snorocket reasoners implement and this does not.
|
|
276
|
-
- **A REPL (interactive prompt)
|
|
279
|
+
- **A REPL (interactive prompt).** Run a file, or call it from Python.
|
|
277
280
|
|
|
278
281
|
Aggregation used to be on this list;
|
|
279
282
|
[lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
|
|
@@ -291,13 +294,33 @@ pip install tiny-datalog
|
|
|
291
294
|
from tiny_datalog import run_program, explain
|
|
292
295
|
|
|
293
296
|
engine = run_program(open("supply-chain.dl").read())
|
|
294
|
-
for
|
|
295
|
-
print(
|
|
297
|
+
for answer in engine.query("exposed(S, C)"):
|
|
298
|
+
print(answer) # {'S': 'pkg0', 'C': 'cve_2026_0001'}
|
|
299
|
+
print("\n".join(explain(engine, "exposed", ("pkg0", "cve_2026_0001"))))
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Facts can come straight from Python data (a CSV file, a database
|
|
303
|
+
query) instead of program text. Each row is checked as if it had been
|
|
304
|
+
parsed:
|
|
305
|
+
|
|
306
|
+
```python
|
|
307
|
+
rules = """
|
|
308
|
+
uses(X, Y) :- depends(X, Y).
|
|
309
|
+
uses(X, Z) :- depends(X, Y), uses(Y, Z).
|
|
310
|
+
exposed(S, C) :- service(S), uses(S, L), vulnerable(L, C).
|
|
311
|
+
"""
|
|
312
|
+
engine = run_program(rules, facts={
|
|
313
|
+
"depends": [("app", "lib"), ("lib", "core")],
|
|
314
|
+
"service": ["app"], # one-column rows may be bare
|
|
315
|
+
"vulnerable": [("core", "cve_2026_0001")],
|
|
316
|
+
})
|
|
317
|
+
engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
|
|
296
318
|
```
|
|
297
319
|
|
|
298
320
|
The command-line interface installs too, as `tiny-datalog` (and
|
|
299
321
|
`tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
|
|
300
|
-
`-containment`, `-defeasible`, `-prolog` for the
|
|
322
|
+
`-containment`, `-defeasible`, `-prolog` for the other engines and the
|
|
323
|
+
extensions):
|
|
301
324
|
|
|
302
325
|
```sh
|
|
303
326
|
tiny-datalog -q 'exposed(S, C)' supply-chain.dl
|
|
@@ -309,16 +332,22 @@ installed package; clone the repository for that.
|
|
|
309
332
|
## Layout
|
|
310
333
|
|
|
311
334
|
```
|
|
312
|
-
tiny_datalog/ the
|
|
313
|
-
|
|
314
|
-
|
|
335
|
+
tiny_datalog/ the code you read, in three tiers:
|
|
336
|
+
core.py the common core — the language every module shares:
|
|
337
|
+
AST, parser, safety checks, stratification, matching,
|
|
338
|
+
formatting, query helpers
|
|
339
|
+
engines — four strategies, one answer (engines.py lists them):
|
|
340
|
+
datalog.py the base engine: semi-naive and naive bottom-up
|
|
341
|
+
evaluation, aggregation, --explain / why-not, the CLI
|
|
315
342
|
magic.py the magic-sets rewriting (a program-to-program pass)
|
|
343
|
+
tabling.py tabled top-down evaluation (iterative QSQR)
|
|
344
|
+
engines.py the registry and the interface the four share
|
|
345
|
+
extensions — other questions asked of the same programs:
|
|
316
346
|
semantics.py grounding, stable models, the well-founded model
|
|
317
347
|
semiring.py semiring-valued evaluation (costs, counts, provenance,
|
|
318
348
|
probabilities)
|
|
319
349
|
incremental.py insertions + DRed deletions over a live materialisation
|
|
320
350
|
prolog.py top-down SLD resolution with function symbols
|
|
321
|
-
tabling.py tabled top-down evaluation (iterative QSQR)
|
|
322
351
|
subsumption.py KL-ONE-style EL classifier, compiled to Datalog
|
|
323
352
|
containment.py query containment and minimisation by homomorphism
|
|
324
353
|
defeasible.py defeasible logic: exceptions, priorities, defeaters
|
|
@@ -331,10 +360,11 @@ exercises/ worked answers, verified by the test suite
|
|
|
331
360
|
cases/ golden test cases — add one without writing Python
|
|
332
361
|
conformance/ the external datalog-conformance corpus (Soufflé, Nemo,
|
|
333
362
|
Crepe, SPINdle), run against every evaluation strategy
|
|
334
|
-
benchmarks/ scaled input generators (chain/tree/clique/grid
|
|
335
|
-
|
|
363
|
+
benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
|
|
364
|
+
ontology, and the N-queens puzzle)
|
|
365
|
+
tests.py 303 tests: every shipped program and exercise answer is
|
|
336
366
|
executed, a conformance suite runs every query through
|
|
337
|
-
every
|
|
367
|
+
every engine that handles it, and a seeded fuzzer checks
|
|
338
368
|
the same property on random programs
|
|
339
369
|
```
|
|
340
370
|
|
|
@@ -345,14 +375,37 @@ used.
|
|
|
345
375
|
|
|
346
376
|
### How big is it, honestly
|
|
347
377
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
378
|
+
This project started as an attempt at a tiny implementation of
|
|
379
|
+
Datalog, small enough to read in an afternoon. It grew with the
|
|
380
|
+
course. Each lesson that taught a new technique — magic sets, stable models,
|
|
381
|
+
semirings, incremental maintenance, tabling, subsumption, containment,
|
|
382
|
+
defeasible logic — brought a module to run it, and the repository is
|
|
383
|
+
now several thousand lines. The core idea stayed small, and the code
|
|
384
|
+
is laid out so you can still read just that: the common core and the
|
|
385
|
+
base engine, below, are the original tiny Datalog. Everything else is
|
|
386
|
+
an engine or extension you can take one lesson at a time.
|
|
352
387
|
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
388
|
+
Measured in lines, comments, docstrings and blank lines included:
|
|
389
|
+
|
|
390
|
+
| Tier | Lines |
|
|
391
|
+
|---|---|
|
|
392
|
+
| the common core (`core.py`: the language, evaluating nothing) | 785 |
|
|
393
|
+
| the base engine's evaluator (`datalog.py` up to its CLI section: the module docstring, the import list that re-exports the core, `Program`, `Engine`, aggregation folding, `run_program`) | 395 |
|
|
394
|
+
| `--explain`, why-not, printing and the CLI (the rest of `datalog.py`) | 535 |
|
|
395
|
+
| the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`), plus the `engines.py` registry (naive evaluation is a flag on the base engine) | 549 |
|
|
396
|
+
| the seven extensions | 2,425 |
|
|
397
|
+
|
|
398
|
+
So the smallest complete Datalog system here — parse, check, stratify,
|
|
399
|
+
evaluate semi-naively — is the core plus the evaluator, about 1,200
|
|
400
|
+
lines. All of it is 4.7k lines of toolkit (every module but the
|
|
401
|
+
re-export list in `__init__.py`), roughly a quarter of it commentary,
|
|
402
|
+
and 3.4k of tests.
|
|
403
|
+
|
|
404
|
+
"Tiny" is a claim about that core and evaluator, and about each module
|
|
405
|
+
built on them singly: none of the ten (`magic.py`, `tabling.py`,
|
|
406
|
+
`engines.py` and the seven extensions) exceeds 500 lines, which a test asserts. It is not a
|
|
407
|
+
claim about the repository, which is a dozen modules because it
|
|
408
|
+
teaches a dozen things.
|
|
356
409
|
|
|
357
410
|
There is no dead code to golf away (checked); shrinking further means
|
|
358
411
|
deleting either a technique or an explanation.
|
|
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "tiny-datalog"
|
|
7
|
-
version = "0.
|
|
8
|
-
description = "A Datalog engine
|
|
7
|
+
version = "0.4.0"
|
|
8
|
+
description = "A Datalog engine whose core you can read in an afternoon, and a course built on it"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
11
11
|
license-files = ["LICENSE"]
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""tiny-datalog — a Datalog engine whose core you can read in an afternoon.
|
|
2
|
+
|
|
3
|
+
The package has three tiers. `tiny_datalog.core` is the language —
|
|
4
|
+
AST, parser, validation, stratification — and `tiny_datalog.datalog` is
|
|
5
|
+
the base engine built on it, the bottom-up evaluator. The names below
|
|
6
|
+
are their public surface, re-exported here so that library use reads as
|
|
7
|
+
|
|
8
|
+
from tiny_datalog import Engine, Program, parse
|
|
9
|
+
|
|
10
|
+
`tiny_datalog.engines` lists the pluggable engines, which all give the
|
|
11
|
+
same answers: semi-naive and naive (`datalog`), `magic` (goal-directed
|
|
12
|
+
rewriting) and `tabling` (top-down with memoing).
|
|
13
|
+
|
|
14
|
+
Everything else is an extension built on the core, asking a different
|
|
15
|
+
question of a program: `semantics` (stable and well-founded models),
|
|
16
|
+
`semiring` (provenance-weighted evaluation), `incremental` (maintenance
|
|
17
|
+
under updates), `subsumption` (KL-ONE style classification),
|
|
18
|
+
`containment` (query containment), `defeasible` (rules with exceptions
|
|
19
|
+
and priorities), and `prolog` (a Prolog reader for the same syntax).
|
|
20
|
+
Import those by name: `from tiny_datalog import semiring`.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from tiny_datalog.datalog import (
|
|
24
|
+
# AST
|
|
25
|
+
Var, Const, Struct, Atom, Literal, Rule,
|
|
26
|
+
# errors
|
|
27
|
+
DatalogError, ParseError, SafetyError, StratificationError,
|
|
28
|
+
# front end
|
|
29
|
+
parse, validate, stratify, parse_goal, check_query_atom,
|
|
30
|
+
# evaluation
|
|
31
|
+
Program, Engine, run_program,
|
|
32
|
+
# answers and justification
|
|
33
|
+
match_answers, explain, whynot,
|
|
34
|
+
# formatting
|
|
35
|
+
format_atom, format_fact,
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
__version__ = "0.4.0"
|
|
39
|
+
|
|
40
|
+
__all__ = [
|
|
41
|
+
"Var", "Const", "Struct", "Atom", "Literal", "Rule",
|
|
42
|
+
"DatalogError", "ParseError", "SafetyError", "StratificationError",
|
|
43
|
+
"parse", "validate", "stratify", "parse_goal", "check_query_atom",
|
|
44
|
+
"Program", "Engine", "run_program",
|
|
45
|
+
"match_answers", "explain", "whynot",
|
|
46
|
+
"format_atom", "format_fact",
|
|
47
|
+
"__version__",
|
|
48
|
+
]
|
|
@@ -16,7 +16,7 @@ body** that fixes the head variables. Containment, a statement about
|
|
|
16
16
|
infinitely many databases, becomes a finite search for a variable
|
|
17
17
|
mapping.
|
|
18
18
|
|
|
19
|
-
The
|
|
19
|
+
The core already contains most of this. `core.match` maps a rule
|
|
20
20
|
body into the *database* — a set of ground atoms. A homomorphism here
|
|
21
21
|
maps a rule body into *another rule body*, whose variables act like
|
|
22
22
|
fresh constants ("freezing" the query into a canonical database). Same
|
|
@@ -40,8 +40,9 @@ from __future__ import annotations
|
|
|
40
40
|
import argparse
|
|
41
41
|
import sys
|
|
42
42
|
|
|
43
|
-
from tiny_datalog.
|
|
44
|
-
|
|
43
|
+
from tiny_datalog.core import (
|
|
44
|
+
aggregate_of, cli, Const, DatalogError, parse, read_program, validate,
|
|
45
|
+
Var)
|
|
45
46
|
|
|
46
47
|
|
|
47
48
|
def _extend(mapping, source_args, target_args):
|
|
@@ -64,7 +65,7 @@ def find_homomorphism(source, target, seed=None):
|
|
|
64
65
|
source atom lands on some target atom, or None.
|
|
65
66
|
|
|
66
67
|
Backtracking search: try every target atom for the first source
|
|
67
|
-
atom, recurse. This is exactly `
|
|
68
|
+
atom, recurse. This is exactly `match`'s job with a target of
|
|
68
69
|
non-ground atoms instead of tuples."""
|
|
69
70
|
mapping = dict(seed or {})
|
|
70
71
|
|
|
@@ -92,7 +93,7 @@ def _bodies(rule):
|
|
|
92
93
|
raise DatalogError(
|
|
93
94
|
"containment by homomorphism is a conjunctive-query "
|
|
94
95
|
"result; negation needs different theory: %s" % rule)
|
|
95
|
-
if
|
|
96
|
+
if aggregate_of(rule.head):
|
|
96
97
|
# sum/count see duplicates; Chandra–Merlin is about sets.
|
|
97
98
|
raise DatalogError(
|
|
98
99
|
"containment by homomorphism is a set-semantics result; "
|
|
@@ -101,18 +102,13 @@ def _bodies(rule):
|
|
|
101
102
|
|
|
102
103
|
|
|
103
104
|
def _head_seed(outer, inner):
|
|
104
|
-
"""Head variables correspond positionally and must be preserved
|
|
105
|
+
"""Head variables correspond positionally and must be preserved: the
|
|
106
|
+
homomorphism has to send outer's head onto inner's, which is one
|
|
107
|
+
more `_extend` (a variable binds or must agree; a constant must
|
|
108
|
+
match itself)."""
|
|
105
109
|
if len(outer.head.args) != len(inner.head.args):
|
|
106
110
|
return None
|
|
107
|
-
|
|
108
|
-
for a, b in zip(outer.head.args, inner.head.args):
|
|
109
|
-
if isinstance(a, Var):
|
|
110
|
-
if a.name in seed and seed[a.name] != b:
|
|
111
|
-
return None
|
|
112
|
-
seed[a.name] = b
|
|
113
|
-
elif a != b:
|
|
114
|
-
return None
|
|
115
|
-
return seed
|
|
111
|
+
return _extend({}, outer.head.args, inner.head.args)
|
|
116
112
|
|
|
117
113
|
|
|
118
114
|
def contains(outer, inner):
|
|
@@ -126,10 +122,6 @@ def contains(outer, inner):
|
|
|
126
122
|
return find_homomorphism(source, target, seed) is not None
|
|
127
123
|
|
|
128
124
|
|
|
129
|
-
def equivalent(a, b):
|
|
130
|
-
return contains(a, b) and contains(b, a)
|
|
131
|
-
|
|
132
|
-
|
|
133
125
|
def minimise(rule):
|
|
134
126
|
"""The smallest equivalent body: repeatedly drop an atom whose loss
|
|
135
127
|
a homomorphism can repair. For conjunctive queries this greedy
|
|
@@ -168,6 +160,7 @@ def _parse_query_rule(text):
|
|
|
168
160
|
# CLI
|
|
169
161
|
# ---------------------------------------------------------------------------
|
|
170
162
|
|
|
163
|
+
@cli
|
|
171
164
|
def main(argv=None):
|
|
172
165
|
ap = argparse.ArgumentParser(
|
|
173
166
|
description="Conjunctive-query containment and minimisation by "
|
|
@@ -178,49 +171,45 @@ def main(argv=None):
|
|
|
178
171
|
help="test whether OUTER contains INNER")
|
|
179
172
|
args = ap.parse_args(argv)
|
|
180
173
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
% (rule, _fmt(rule.head, atoms), before, len(atoms)))
|
|
221
|
-
except DatalogError as exc:
|
|
222
|
-
print("error: %s" % exc, file=sys.stderr)
|
|
223
|
-
return 1
|
|
174
|
+
if args.contains:
|
|
175
|
+
outer = _parse_query_rule(args.contains[0])
|
|
176
|
+
inner = _parse_query_rule(args.contains[1])
|
|
177
|
+
fwd, bwd = contains(outer, inner), contains(inner, outer)
|
|
178
|
+
print("outer: %s" % outer)
|
|
179
|
+
print("inner: %s" % inner)
|
|
180
|
+
if fwd and bwd:
|
|
181
|
+
print("=> equivalent (each contains the other)")
|
|
182
|
+
elif fwd:
|
|
183
|
+
print("=> outer contains inner, on every database")
|
|
184
|
+
elif bwd:
|
|
185
|
+
print("=> inner contains outer, on every database")
|
|
186
|
+
else:
|
|
187
|
+
print("=> neither contains the other")
|
|
188
|
+
return 0
|
|
189
|
+
|
|
190
|
+
if not args.file:
|
|
191
|
+
ap.error("give a program to minimise, or use --contains")
|
|
192
|
+
clauses = parse(read_program(args.file))
|
|
193
|
+
validate(clauses)
|
|
194
|
+
for rule in clauses:
|
|
195
|
+
if not rule.body:
|
|
196
|
+
continue
|
|
197
|
+
if any(lit.negated for lit in rule.body):
|
|
198
|
+
print("%s\n (skipped: negation is outside the theory)"
|
|
199
|
+
% rule)
|
|
200
|
+
continue
|
|
201
|
+
if aggregate_of(rule.head):
|
|
202
|
+
print("%s\n (skipped: aggregation is outside the theory)"
|
|
203
|
+
% rule)
|
|
204
|
+
continue
|
|
205
|
+
atoms = minimise(rule)
|
|
206
|
+
before = len(rule.body)
|
|
207
|
+
if len(atoms) == before:
|
|
208
|
+
print("%s\n already minimal (%d atom%s)"
|
|
209
|
+
% (rule, before, "" if before == 1 else "s"))
|
|
210
|
+
else:
|
|
211
|
+
print("%s\n minimises to %s (%d atoms -> %d)"
|
|
212
|
+
% (rule, _fmt(rule.head, atoms), before, len(atoms)))
|
|
224
213
|
return 0
|
|
225
214
|
|
|
226
215
|
|