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.
Files changed (25) hide show
  1. {tiny_datalog-0.2.0/tiny_datalog.egg-info → tiny_datalog-0.4.0}/PKG-INFO +79 -26
  2. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/README.md +77 -24
  3. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/pyproject.toml +2 -2
  4. tiny_datalog-0.4.0/tiny_datalog/__init__.py +48 -0
  5. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/containment.py +51 -62
  6. tiny_datalog-0.4.0/tiny_datalog/core.py +785 -0
  7. tiny_datalog-0.4.0/tiny_datalog/datalog.py +930 -0
  8. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/defeasible.py +13 -16
  9. tiny_datalog-0.4.0/tiny_datalog/engines.py +125 -0
  10. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/incremental.py +86 -89
  11. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/magic.py +5 -4
  12. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/prolog.py +12 -24
  13. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/semantics.py +23 -48
  14. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/semiring.py +13 -20
  15. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/subsumption.py +19 -22
  16. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog/tabling.py +89 -61
  17. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0/tiny_datalog.egg-info}/PKG-INFO +79 -26
  18. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog.egg-info/SOURCES.txt +2 -0
  19. tiny_datalog-0.2.0/tiny_datalog/__init__.py +0 -43
  20. tiny_datalog-0.2.0/tiny_datalog/datalog.py +0 -1455
  21. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/LICENSE +0 -0
  22. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/setup.cfg +0 -0
  23. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog.egg-info/dependency_links.txt +0 -0
  24. {tiny_datalog-0.2.0 → tiny_datalog-0.4.0}/tiny_datalog.egg-info/entry_points.txt +0 -0
  25. {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.2.0
4
- Summary: A Datalog engine small enough to read in an afternoon
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
  [![tests](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml/badge.svg)](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml)
37
37
  [![PyPI](https://img.shields.io/pypi/v/tiny-datalog)](https://pypi.org/project/tiny-datalog/)
38
38
 
39
- **A logic engine small enough to read in an afternoon, and a course
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 # 246 tests, ~12s
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 — 20
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
- `datalog.py`: `_match` maps a rule body into a database,
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) and packaging.** `git clone` and run.
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 service, cve in sorted(engine.rels["exposed"]):
328
- print("\n".join(explain(engine, "exposed", (service, cve))))
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 satellites):
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 engine and its satellites — the code you read:
346
- datalog.py the core: AST, parser, safety checks, stratification,
347
- the semi-naive evaluator, and the CLI
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
- tests.py 246 tests: every shipped program and exercise answer is
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 applicable strategy, and a seeded fuzzer checks
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
- The evaluator is about 850 lines (`tiny_datalog/datalog.py`, up to the
382
- command-line interface), the CLI, `--explain` and why-not another 600, and the nine satellite modules about
383
- 2,900. Call it 4.3k lines of toolkit and 2.7k of tests, roughly a
384
- quarter of it commentary.
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
- "Tiny" is a claim about the evaluator, and about each satellite module
387
- singly: none of the nine exceeds 500 lines, which a test asserts. It is not a claim about
388
- the repository, which is ten modules because it teaches ten things.
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
  [![tests](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml/badge.svg)](https://github.com/andrewgoodchild/tiny-datalog/actions/workflows/ci.yml)
4
4
  [![PyPI](https://img.shields.io/pypi/v/tiny-datalog)](https://pypi.org/project/tiny-datalog/)
5
5
 
6
- **A logic engine small enough to read in an afternoon, and a course
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 # 246 tests, ~12s
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 — 20
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
- `datalog.py`: `_match` maps a rule body into a database,
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) and packaging.** `git clone` and run.
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 service, cve in sorted(engine.rels["exposed"]):
295
- print("\n".join(explain(engine, "exposed", (service, cve))))
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 satellites):
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 engine and its satellites — the code you read:
313
- datalog.py the core: AST, parser, safety checks, stratification,
314
- the semi-naive evaluator, and the CLI
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
- tests.py 246 tests: every shipped program and exercise answer is
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 applicable strategy, and a seeded fuzzer checks
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
- The evaluator is about 850 lines (`tiny_datalog/datalog.py`, up to the
349
- command-line interface), the CLI, `--explain` and why-not another 600, and the nine satellite modules about
350
- 2,900. Call it 4.3k lines of toolkit and 2.7k of tests, roughly a
351
- quarter of it commentary.
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
- "Tiny" is a claim about the evaluator, and about each satellite module
354
- singly: none of the nine exceeds 500 lines, which a test asserts. It is not a claim about
355
- the repository, which is ten modules because it teaches ten things.
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.2.0"
8
- description = "A Datalog engine small enough to read in an afternoon"
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 engine already contains most of this. `datalog._match` maps a rule
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.datalog import (
44
- _aggregate_of, Const, DatalogError, parse, read_program, validate, Var)
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 `_match`'s job with a target of
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 _aggregate_of(rule.head):
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
- seed = {}
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
- try:
182
- if args.contains:
183
- outer = _parse_query_rule(args.contains[0])
184
- inner = _parse_query_rule(args.contains[1])
185
- fwd, bwd = contains(outer, inner), contains(inner, outer)
186
- print("outer: %s" % outer)
187
- print("inner: %s" % inner)
188
- if fwd and bwd:
189
- print("=> equivalent (each contains the other)")
190
- elif fwd:
191
- print("=> outer contains inner, on every database")
192
- elif bwd:
193
- print("=> inner contains outer, on every database")
194
- else:
195
- print("=> neither contains the other")
196
- return 0
197
-
198
- if not args.file:
199
- ap.error("give a program to minimise, or use --contains")
200
- clauses = parse(read_program(args.file))
201
- validate(clauses)
202
- for rule in clauses:
203
- if not rule.body:
204
- continue
205
- if any(lit.negated for lit in rule.body):
206
- print("%s\n (skipped: negation is outside the theory)"
207
- % rule)
208
- continue
209
- if _aggregate_of(rule.head):
210
- print("%s\n (skipped: aggregation is outside the theory)"
211
- % rule)
212
- continue
213
- atoms = minimise(rule)
214
- before = len(rule.body)
215
- if len(atoms) == before:
216
- print("%s\n already minimal (%d atom%s)"
217
- % (rule, before, "" if before == 1 else "s"))
218
- else:
219
- print("%s\n minimises to %s (%d atoms -> %d)"
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