dtree-explorer 1.0.0__py3-none-any.whl

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/__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/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,
+    })