dtree-explorer 1.0.0__tar.gz

dtree_explorer-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enis Olgac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dtree_explorer-1.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: dtree-explorer
+Version: 1.0.0
+Summary: DTree Explorer: encode a directed tree with DTree's two projections (Q1, Q2) and watch it step by step, in the browser
+Author-email: Enis Olgac <enis@digraphs.info>
+License: MIT
+Project-URL: Homepage, https://github.com/EnisOlgac/DTree-Explorer
+Project-URL: Library, https://github.com/EnisOlgac/DTree
+Project-URL: Online, https://digraphs.blog/dtree-demo/
+Project-URL: Paper, https://doi.org/10.5772/intechopen.1013408
+Keywords: directed tree,tree topology,reachability,visualization,incremental encoding,teaching
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: dtree-encoding>=1.8.0
+Dynamic: license-file
+
+# DTree Explorer
+
+Encode a directed tree with [DTree](https://github.com/EnisOlgac/DTree)'s two projections Q1 and Q2 and watch it happen, edge by edge. The Explorer draws the tree, places every node in the plane at its rank in Q1 and Q2, lists both projections with the positions the library stores, and answers reachability questions by clicking: *u* reaches *v* exactly when *u* comes before *v* in both lists.
+
+Every tree is computed by the published library, [dtree-encoding](https://pypi.org/project/dtree-encoding/); the Explorer only shows what it computes.
+
+## Three ways to use it
+
+**Online:** [digraphs.blog/dtree-demo](https://digraphs.blog/dtree-demo/), nothing to install.
+
+**As a Python program**, offline, with the library installed on your machine:
+
+```
+pip install dtree-explorer
+dtree-explorer
+```
+
+The command starts a small server on 127.0.0.1 and opens the page in your browser; stop it with Ctrl+C. Options: `--port 8765`, `--no-browser`, `--save explorer.html` (write the page as one file).
+
+**As a single file:** download `DTree-Explorer.html` from the [latest release](https://github.com/EnisOlgac/DTree-Explorer/releases/latest) and open it in a browser. It loads Python (Pyodide) from cdn.jsdelivr.net and dtree-encoding from pypi.org, so it needs an internet connection.
+
+## Input
+
+One line per instruction; lines starting with `#` are comments.
+
+| Line | Meaning |
+|---|---|
+| `p: c1; c2` | c1 and c2 become the last children of p |
+| `s > c1; c2` | c1 goes directly after its sibling s, then c2 after c1 |
+| `s < c1; c2` | c1 and c2 go directly before s, in that order |
+
+The examples include the trees of the paper: the introductory example, Figure 1, the generalized insertion of Section 4.1 (Case A, before; Case B, after) and Appendix A, whose three variants appear twice: once by the order of the input lines, once with `<` and `>`. Both give the same projections.
+
+## Privacy
+
+Your tree stays on your computer. The page counts visits only in the copy on digraphs.blog, with Google Analytics and only after you agree; the package and the release file count nothing.
+
+## Building
+
+Working in this repository needs the library installed: `pip install dtree-encoding`. `src/template.html` is the page, `dtree_explorer/bridge.py` the Python part it runs, `src/build.py` assembles `dtree_explorer/explorer.html` (package and release) and `site/index.html` (digraphs.blog) with the installed dtree-encoding. Tests: `python -m unittest discover -s tests`.
+
+## Background
+
+E. Olgac, "Topology and Structure of Directed Trees: An Incremental Encoding," IntechOpen, 2025. doi: [10.5772/intechopen.1013408](https://doi.org/10.5772/intechopen.1013408).
+
+## License
+
+MIT. Design and concept: Enis Olgac. The Explorer was written with Claude (Anthropic).

dtree_explorer-1.0.0/README.md

@@ -0,0 +1,48 @@
+# DTree Explorer
+
+Encode a directed tree with [DTree](https://github.com/EnisOlgac/DTree)'s two projections Q1 and Q2 and watch it happen, edge by edge. The Explorer draws the tree, places every node in the plane at its rank in Q1 and Q2, lists both projections with the positions the library stores, and answers reachability questions by clicking: *u* reaches *v* exactly when *u* comes before *v* in both lists.
+
+Every tree is computed by the published library, [dtree-encoding](https://pypi.org/project/dtree-encoding/); the Explorer only shows what it computes.
+
+## Three ways to use it
+
+**Online:** [digraphs.blog/dtree-demo](https://digraphs.blog/dtree-demo/), nothing to install.
+
+**As a Python program**, offline, with the library installed on your machine:
+
+```
+pip install dtree-explorer
+dtree-explorer
+```
+
+The command starts a small server on 127.0.0.1 and opens the page in your browser; stop it with Ctrl+C. Options: `--port 8765`, `--no-browser`, `--save explorer.html` (write the page as one file).
+
+**As a single file:** download `DTree-Explorer.html` from the [latest release](https://github.com/EnisOlgac/DTree-Explorer/releases/latest) and open it in a browser. It loads Python (Pyodide) from cdn.jsdelivr.net and dtree-encoding from pypi.org, so it needs an internet connection.
+
+## Input
+
+One line per instruction; lines starting with `#` are comments.
+
+| Line | Meaning |
+|---|---|
+| `p: c1; c2` | c1 and c2 become the last children of p |
+| `s > c1; c2` | c1 goes directly after its sibling s, then c2 after c1 |
+| `s < c1; c2` | c1 and c2 go directly before s, in that order |
+
+The examples include the trees of the paper: the introductory example, Figure 1, the generalized insertion of Section 4.1 (Case A, before; Case B, after) and Appendix A, whose three variants appear twice: once by the order of the input lines, once with `<` and `>`. Both give the same projections.
+
+## Privacy
+
+Your tree stays on your computer. The page counts visits only in the copy on digraphs.blog, with Google Analytics and only after you agree; the package and the release file count nothing.
+
+## Building
+
+Working in this repository needs the library installed: `pip install dtree-encoding`. `src/template.html` is the page, `dtree_explorer/bridge.py` the Python part it runs, `src/build.py` assembles `dtree_explorer/explorer.html` (package and release) and `site/index.html` (digraphs.blog) with the installed dtree-encoding. Tests: `python -m unittest discover -s tests`.
+
+## Background
+
+E. Olgac, "Topology and Structure of Directed Trees: An Incremental Encoding," IntechOpen, 2025. doi: [10.5772/intechopen.1013408](https://doi.org/10.5772/intechopen.1013408).
+
+## License
+
+MIT. Design and concept: Enis Olgac. The Explorer was written with Claude (Anthropic).

dtree_explorer-1.0.0/dtree_explorer/__init__.py

@@ -0,0 +1,3 @@
+"""DTree Explorer: encode a directed tree with DTree's projections Q1 and Q2 and watch it, step by step."""
+
+__version__ = "1.0.0"

dtree_explorer-1.0.0/dtree_explorer/__main__.py

@@ -0,0 +1,105 @@
+"""Start the DTree Explorer: a local web page that computes with the installed dtree-encoding.
+
+    dtree-explorer                 open the Explorer in the browser
+    dtree-explorer --port 8765     use a fixed port (default: a free one)
+    dtree-explorer --no-browser    only start the server and print its address
+    dtree-explorer --save FILE     write the page as one HTML file and exit
+
+The server listens on 127.0.0.1 only and serves the page and one computing endpoint;
+nothing leaves your machine. Stop it with Ctrl+C.
+"""
+
+import argparse
+import json
+import platform
+import sys
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import resources
+
+import dtree
+
+from . import __version__, bridge
+
+MAX_INPUT = 4 * 1024 * 1024  # bytes of tree description per request
+
+
+def page() -> bytes:
+    return resources.files(__package__).joinpath("explorer.html").read_bytes()
+
+
+class Handler(BaseHTTPRequestHandler):
+    server_version = "DTreeExplorer/" + __version__
+
+    def _local_host(self) -> bool:
+        host = (self.headers.get("Host") or "").rsplit(":", 1)[0]
+        return host in ("127.0.0.1", "localhost")       # refuses requests under other host names
+
+    def _send(self, code, kind, body: bytes):
+        self.send_response(code)
+        self.send_header("Content-Type", kind)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        if not self._local_host():
+            return self._send(403, "text/plain", b"forbidden")
+        path = self.path.split("?", 1)[0]
+        if path in ("/", "/index.html"):
+            return self._send(200, "text/html; charset=utf-8", page())
+        if path == "/api/info":
+            info = {"dtree": dtree.__version__, "python": platform.python_version(), "explorer": __version__}
+            return self._send(200, "application/json", json.dumps(info).encode())
+        self._send(404, "text/plain", b"not found")
+
+    def do_POST(self):
+        if not self._local_host():
+            return self._send(403, "text/plain", b"forbidden")
+        if self.path.split("?", 1)[0] != "/api/encode":
+            return self._send(404, "text/plain", b"not found")
+        n = int(self.headers.get("Content-Length") or 0)
+        if n > MAX_INPUT:
+            return self._send(413, "text/plain", b"description too large")
+        text = self.rfile.read(n).decode("utf-8", "replace")
+        self._send(200, "application/json", bridge.encode(text).encode())
+
+    def log_message(self, *args):  # quiet
+        pass
+
+
+def serve(port=0):
+    """Create the server (not yet running); port 0 picks a free port."""
+    return ThreadingHTTPServer(("127.0.0.1", port), Handler)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="dtree-explorer", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--port", type=int, default=0, help="port on 127.0.0.1 (default: a free one)")
+    ap.add_argument("--no-browser", action="store_true", help="do not open the browser")
+    ap.add_argument("--save", metavar="FILE", help="write the page as one HTML file and exit")
+    ap.add_argument("--version", action="version", version=f"DTree Explorer {__version__}, dtree-encoding {dtree.__version__}")
+    args = ap.parse_args(argv)
+    if args.save:
+        with open(args.save, "wb") as fh:
+            fh.write(page())
+        print(f"Wrote {args.save}. Open it in a browser; it loads Python (Pyodide) from the internet.")
+        return 0
+    httpd = serve(args.port)
+    url = f"http://127.0.0.1:{httpd.server_address[1]}/"
+    print(f"DTree Explorer {__version__} with dtree-encoding {dtree.__version__} at {url}")
+    print("Press Ctrl+C to stop.")
+    if not args.no_browser:
+        webbrowser.open(url)
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopped.")
+    finally:
+        httpd.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dtree_explorer-1.0.0/dtree_explorer/bridge.py

@@ -0,0 +1,87 @@
+"""Bridge between the DTree Explorer page and the dtree package.
+
+The page runs this module in the browser (Pyodide) with the published dtree-encoding
+package; the same code runs under CPython for the tests and to precompute the example
+that is shown while the Python runtime loads. Everything the page displays about the
+encoding (the order of Q1 and Q2, the positions, the parents) comes from here.
+"""
+
+import json
+
+import dtree
+from dtree import DTree
+
+LIMIT = 300  # insertions recorded step by step; larger trees show the final state only
+
+
+def _split(line):
+    at = min((i for i in (line.find(":"), line.find(">"), line.find("<")) if i >= 0), default=-1)
+    if at < 0:
+        return None
+    return line[at], line[:at].strip(), [c.strip() for c in line[at + 1:].split(";") if c.strip()]
+
+
+def _state(t):
+    q1, q2 = t.q1, t.q2
+    pos = {v: [str(t.Q1.index(v)), str(t.Q2.index(v))] for v in q1}
+    return {"q1": q1, "q2": q2, "pos": pos}
+
+
+def encode(text, limit=LIMIT):
+    """Build a tree from the description and return the steps as JSON.
+
+    Each step is one inserted node: the operation, its line, the new node and its parent,
+    and (up to ``limit`` insertions) the full state after it: Q1, Q2 and the positions.
+    """
+    t = DTree("E")
+    steps, errors, parents = [], [], {}
+    recording = True
+    for no, raw in enumerate(text.splitlines(), 1):
+        line = raw.strip().lstrip("")
+        if not line or line.startswith(("#", "--", "**")):
+            continue
+        if line.startswith("@@"):
+            break
+        parts = _split(line)
+        if parts is None:
+            errors.append({"line": no, "text": line, "msg": "expected ':', '>' or '<'"})
+            continue
+        op, anchor, kids = parts
+        for child in kids:
+            try:
+                if op == ":":
+                    t.insert(anchor, child)
+                    shown = f"{anchor}:{child}"
+                elif op == ">":
+                    t.insert_after(anchor, child)
+                    shown = f"{anchor}>{child}"
+                    anchor = child
+                else:
+                    t.insert_before(anchor, child)
+                    shown = f"{anchor}<{child}"
+            except (KeyError, ValueError) as e:
+                msg = e.args[0] if e.args else str(e)
+                errors.append({"line": no, "text": line, "msg": f"{child}: {msg}"})
+                continue
+            parents[child] = t.get_parent(child)
+            step = {"line": no, "op": shown, "new": child}
+            if recording and len(steps) < limit:
+                step.update(_state(t))
+            elif recording:
+                recording = False
+                for s in steps:
+                    for k in ("q1", "q2", "pos"):
+                        s.pop(k, None)
+            steps.append(step)
+    final = _state(t) if t.root is not None else {"q1": [], "q2": [], "pos": {}}
+    return json.dumps({
+        "version": dtree.__version__,
+        "root": t.root,
+        "parents": parents,
+        "steps": steps,
+        "final": final,
+        "stepwise": recording,
+        "limit": limit,
+        "renumber": [t.Q1.renumber_count, t.Q2.renumber_count],
+        "errors": errors,
+    })