buchelib 0.0.1__tar.gz

buchelib-0.0.1/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.3
+Name: buchelib
+Version: 0.0.1
+Summary: Add your description here
+Author: Olivier Breuleux
+Author-email: Olivier Breuleux <breuleux@gmail.com>
+Requires-Dist: hypetext>=0.0.4
+Requires-Dist: ovld>=0.5.17
+Requires-Dist: serieux>=0.3.13
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+
+# buchelib
+
+**WIP**
+
+A library to easily generate interface for the `buche` shell.

buchelib-0.0.1/README.md

@@ -0,0 +1,6 @@
+
+# buchelib
+
+**WIP**
+
+A library to easily generate interface for the `buche` shell.

buchelib-0.0.1/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "buchelib"
+version = "0.0.1"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Olivier Breuleux", email = "breuleux@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "hypetext>=0.0.4",
+    "ovld>=0.5.17",
+    "serieux>=0.3.13",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.3,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 99
+
+[tool.ruff.lint]
+extend-select = ["I"]
+ignore = ["F811", "F722"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true

buchelib-0.0.1/src/buchelib/__init__.py

@@ -0,0 +1,44 @@
+import os
+from pathlib import Path
+
+from serieux import Serieux
+
+from .bridge import Bridge, Cell
+from .htmlgen import BucheInterpreter
+from .srx import BucheSerieux
+
+here = Path(__file__).parent
+
+__bridge = None
+__main_cell = None
+
+
+def bridge():
+    global __bridge
+    if not __bridge:
+        __bridge = Bridge()
+    return __bridge
+
+
+def main_cell():
+    global __main_cell
+    if not __main_cell:
+        __main_cell = Cell(
+            bridge=bridge(),
+            interpreter_class=BucheInterpreter,
+            srx=(Serieux + BucheSerieux)(),
+            id="main",
+        )
+        __main_cell.body().exec(here / "lib.js")
+    return __main_cell
+
+
+def is_available():
+    fd_str = os.environ.get("BUCHE_CONTROL_FD")
+    if not fd_str:
+        return False
+    try:
+        os.fstat(int(fd_str))
+        return True
+    except ValueError, OSError:
+        return False

buchelib-0.0.1/src/buchelib/bridge.py

@@ -0,0 +1,294 @@
+import asyncio
+import json
+import os
+import select
+from dataclasses import dataclass, field
+from functools import cached_property
+from glob import glob
+from itertools import count
+from pathlib import Path
+from types import FunctionType
+from typing import Any, Iterable
+from uuid import uuid4
+
+from ovld import ovld, recurse
+from serieux import JSON, Context, Serieux, serieux
+from serieux.features.tagset import TagDict
+
+here = Path(__file__).parent
+
+_current_id = count()
+
+
+@ovld
+def _expand_paths(p: str):
+    if "*" in p:
+        for path in glob(p):
+            yield from recurse(Path(path))
+    else:
+        yield from recurse(Path(p))
+
+
+@ovld
+def _expand_paths(p: Path):
+    if p.is_dir():
+        raise Exception("Availing a directory is not allowed. Avail individual files.")
+    yield p
+
+
+@ovld
+def _expand_paths(p: Iterable):
+    for x in p:
+        yield from recurse(x)
+
+
+@dataclass
+class CellMessage:
+    message: JSON
+    cell: Cell
+
+    def parse(self):
+        return self.cell.deserialize(self.message)
+
+    async def dispatch(self):
+        await self.parse().call()
+
+
+@dataclass
+class PromptMessage:
+    message: JSON
+    prompt: Prompt
+
+    async def dispatch(self):
+        return await self.prompt.handler(self.prompt, self.message)
+
+
+class Bridge:
+    def __init__(self, fd=None):
+        if fd is None:
+            fd = int(os.environ.get("BUCHE_CONTROL_FD", 5))
+        self.ctlin = os.fdopen(fd, "r", buffering=1)
+        self._outfd = os.dup(fd)
+        self.catalogue = {}
+        self.cells = {}
+        self.prompts = {}
+
+    def send(self, payload):
+        data = (json.dumps(payload) + "\n").encode()
+        written = 0
+        while written < len(data):
+            select.select([], [self._outfd], [])
+            try:
+                written += os.write(self._outfd, data[written:])
+            except BlockingIOError:
+                pass
+
+    def _pack_file(self, nonce, rel, p):
+        match p.suffix:
+            case ".css":
+                packed = {"mimetype": "text/css", "content": p.read_text()}
+            case ".js":
+                packed = {"mimetype": "text/javascript", "content": p.read_text()}
+            case other:
+                raise Exception(f"Unsupported format: {other}")
+        self.catalogue[str(p)] = f"buche://nonce/{nonce}/{rel}"
+        return packed
+
+    def avail(self, *files):
+        concrete = list(_expand_paths(files))
+        paths = [Path(f).resolve() for f in concrete]
+        base = os.path.commonpath([str(p.parent) for p in paths])
+        nonce = str(uuid4())
+        self.send(
+            {
+                "type": "library",
+                "nonce": nonce,
+                "files": {
+                    str(rel := p.relative_to(base)): self._pack_file(nonce, rel, p) for p in paths
+                },
+            }
+        )
+
+    def url(self, p):
+        sp = str(Path(p).resolve())
+        if sp not in self.catalogue:
+            self.avail(p)
+        return self.catalogue[sp]
+
+    @cached_property
+    def srx(self):
+        from .srx import BucheSerieux
+
+        return (Serieux + BucheSerieux)()
+
+    def __setup_cell(self, cell):
+        self.cells[cell.id] = cell
+        cell.body().exec(here / "lib.js")
+        return cell
+
+    @cached_property
+    def main_cell(self):
+        from .htmlgen import BucheInterpreter
+
+        cell = Cell(
+            bridge=self,
+            interpreter_class=BucheInterpreter,
+            srx=self.srx,
+            id="main",
+        )
+        self.__setup_cell(cell)
+        return cell
+
+    def cell(self, echo=None):
+        from .htmlgen import BucheInterpreter
+
+        _id = uuid4().hex
+
+        cell = Cell(
+            bridge=self,
+            interpreter_class=BucheInterpreter,
+            srx=self.srx,
+            id=_id,
+        )
+        self.send(
+            {
+                "type": "cell_create",
+                "address": {"cell_id": _id},
+                "to": {"target": "terminal", "cell": _id},
+                "mode": "data",
+                "echo_html": echo,
+            }
+        )
+        self.__setup_cell(cell)
+        return cell
+
+    def prompt(self, label, handler=None, language=None):
+        prompt = Prompt(bridge=self, label=label, handler=handler)
+        self.send(
+            {
+                "type": "prompt_create",
+                "to": {"target": "terminal", "prompt": "python"},
+                "address": {"prompt_id": label},
+                "prompt": "<span style='color:#4ec9b0;'>sktk ]]]</span>",
+                "tab_html": label,
+                "name": label,
+                "tag": "python",
+                "language": language,
+            }
+        )
+        self.prompts[label] = prompt
+        return prompt
+
+    async def __aiter__(self):
+        loop = asyncio.get_event_loop()
+        reader = asyncio.StreamReader()
+        protocol = asyncio.StreamReaderProtocol(reader)
+        await loop.connect_read_pipe(lambda: protocol, self.ctlin)
+        async for line in reader:
+            data = json.loads(line)
+            to = data.pop("to", {})
+            if prid := to.get("prompt_id", None):
+                yield PromptMessage(message=data, prompt=self.prompts.get(prid, None))
+            else:
+                cell_id = to.get("cell_id", "main")
+                yield CellMessage(message=data, cell=self.cells.get(cell_id, None))
+
+
+_tagdict_defaults = {}
+
+
+@dataclass(kw_only=True)
+class Cell:
+    bridge: Bridge
+    id: str = "main"
+    interpreter_class: type
+    tagset: TagDict = field(default_factory=lambda: TagDict(_tagdict_defaults))
+    srx: Serieux = field(default_factory=lambda: serieux)
+    function_registry: dict = field(default_factory=dict)
+    handler: Any = None
+
+    def __post_init__(self):
+        self.address = {"cell_id": self.id} if self.id != "main" else {}
+        self.interpreter = self.interpreter_class(self)
+
+    @classmethod
+    def register_type_default(cls, fn):
+        _tagdict_defaults[f"{fn.__module__}:{fn.__qualname__}"] = fn
+
+    def register_type(self, *args, **kwargs):
+        self.tagset.register(*args, **kwargs)
+
+    def register_function(self, fn):
+        if fn not in self.function_registry:
+            self.function_registry[fn] = f"F{next(_current_id)}"
+        return self.function_registry[fn]
+
+    async def inputs(self):
+        loop = asyncio.get_event_loop()
+        reader = asyncio.StreamReader()
+        protocol = asyncio.StreamReaderProtocol(reader)
+        await loop.connect_read_pipe(lambda: protocol, self.bridge.ctlin)
+        async for line in reader:
+            data = json.loads(line)
+            data.pop("to", None)
+            yield self.deserialize(data)
+
+    def avail(self, *files):
+        return self.bridge.avail(*files)
+
+    def command(self, **args):
+        return self.bridge.send(
+            {
+                "type": "cell_send",
+                "message": args,
+                "address": self.address,
+                "to": {"target": "terminal", "cell": self.id},
+            }
+        )
+
+    def configure(self, **options):
+        self.bridge.send(
+            {
+                "type": "cell_configure",
+                "address": self.address,
+                "to": {"target": "terminal", "cell": self.id},
+                **options,
+            }
+        )
+
+    def close(self, return_code=0):
+        self.bridge.send(
+            {
+                "type": "cell_close",
+                "address": self.address,
+                "to": {"target": "terminal", "cell": self.id},
+                "return_code": return_code,
+            }
+        )
+
+    @ovld
+    def serialize(self, obj: FunctionType):
+        return t"embed({self.register_function(obj)})"
+
+    @ovld
+    def serialize(self, obj: object):
+        return self.srx.serialize(Any @ self.tagset, obj, CellContext(self))
+
+    def deserialize(self, data):
+        return self.srx.deserialize(Any @ self.tagset, data, CellContext(self))
+
+    def body(self):
+        from .selection import Selection
+
+        return Selection(cell=self)
+
+
+class CellContext(Context):
+    cell: Cell
+
+
+@dataclass(kw_only=True)
+class Prompt:
+    bridge: Bridge
+    label: str
+    handler: Any

buchelib-0.0.1/src/buchelib/htmlgen.py

@@ -0,0 +1,41 @@
+from html import escape
+from pathlib import Path
+from string.templatelib import Interpolation
+from typing import Any, Literal
+
+from hypetext import Interpreter
+from ovld import ovld
+from serieux import JSON
+
+from .bridge import Cell, CellContext
+from .js import js
+
+
+class BucheInterpreter(Interpreter):
+    cell: Cell
+
+    def _js_serialize(self, value):
+        t = type(value)
+        if t in (list, dict):
+            t = JSON
+        return js(self.cell.srx.serialize(t, value, CellContext(self.cell)))
+
+    def gen(self, value: Path, fmt: str, tag: str, attr: object):
+        yield ("lit", str(self.cell.bridge.url(value)))
+
+    @ovld(priority=1)
+    def gen(self, value: object, fmt: Literal["js"], tag: str, attr: str):
+        yield ("lit", escape(self._js_serialize(value)))
+
+    @ovld(priority=1)
+    def gen(self, value: object, fmt: Literal["js"], tag: str, attr: None):
+        yield ("lit", self._js_serialize(value))
+
+    @ovld(priority=1)
+    def gen(self, value: Interpolation, fmt: str, tag: Literal["script"], attr: Any):
+        if isinstance(value.value, Path):
+            yield ("lit", repr(self.cell.bridge.url(value.value)))
+        elif value.format_spec == "raw":
+            yield ("lit", str(value.value))
+        else:
+            yield ("lit", self._js_serialize(value.value))

buchelib-0.0.1/src/buchelib/interpreter.py

@@ -0,0 +1,36 @@
+class Interpreter:
+    async def eval(self, cell, command):
+        raise NotImplementedError()
+
+    async def on_error(self, cell, error):
+        raise error
+
+    async def handle_parse(self, prompt, message):
+        pass
+
+    async def handle_prompt_submit(self, prompt, message):
+        cell = prompt.bridge.cell(echo=message.get("echo_html", None))
+        try:
+            result = await self.eval(cell, message["text"])
+            if result is not None:
+                cell.body().print(result)
+            cell.close()
+        except Exception as exc:
+            await self.on_error(cell, exc)
+            cell.close(1)
+
+    async def handle_prompt_close(self, prompt, message):
+        raise SystemExit(0)
+
+    async def __call__(self, prompt, message):
+        msg_type = message.get("type")
+        handler_name = f"handle_{msg_type}"
+        handler = getattr(self, handler_name, None)
+        if handler is not None and callable(handler):
+            return await handler(prompt, message)
+
+
+class PythonInterpreter:
+    async def eval(self, cell, command):
+        result = eval(command)
+        return result if result is None else str(result)

buchelib-0.0.1/src/buchelib/js.py

@@ -0,0 +1,75 @@
+import json
+from dataclasses import dataclass
+from string.templatelib import Template
+
+from ovld import ovld, recurse
+
+
+@dataclass
+class SerializationState:
+    indent: int = 0
+    prefix: str = ""
+
+    def deeper(self):
+        ind = " " * self.indent
+        return SerializationState(self.indent, self.prefix + ind)
+
+
+@ovld
+def js(x: object, *, indent: int = 0):
+    return recurse(x, SerializationState(indent))
+
+
+@ovld
+def js(x: None, state: SerializationState):
+    return "null"
+
+
+@ovld
+def js(x: bool, state: SerializationState):
+    return "true" if x else "false"
+
+
+@ovld
+def js(x: int, state: SerializationState):
+    return str(x)
+
+
+@ovld
+def js(x: float, state: SerializationState):
+    return str(x)
+
+
+@ovld
+def js(x: str, state: SerializationState):
+    return json.dumps(x)
+
+
+@ovld
+def js(x: list, state: SerializationState):
+    if not state.indent:
+        return "[" + ", ".join(recurse(item, state) for item in x) + "]"
+    inner = state.deeper()
+    items = (",\n" + inner.prefix).join(recurse(item, inner) for item in x)
+    return f"[\n{inner.prefix}{items}\n{state.prefix}]"
+
+
+@ovld
+def js(x: dict, state: SerializationState):
+    if not state.indent:
+        return "{" + ", ".join(f"{json.dumps(k)}: {recurse(v, state)}" for k, v in x.items()) + "}"
+    inner = state.deeper()
+    items = (",\n" + inner.prefix).join(
+        f"{json.dumps(k)}: {recurse(v, inner)}" for k, v in x.items()
+    )
+    return f"{{\n{inner.prefix}{items}\n{state.prefix}}}"
+
+
+@ovld
+def js(x: Template, state: SerializationState):
+    parts = []
+    for s, i in zip(x.strings, x.interpolations):
+        parts.append(s)
+        parts.append(recurse(i.value, state))
+    parts.append(x.strings[-1])
+    return "".join(parts)

buchelib-0.0.1/src/buchelib/lib.js

@@ -0,0 +1,46 @@
+async function indicate(f, args, eventTarget, selector, indicatorClass = "buche-indicator") {
+    if (!selector) {
+        selector = eventTarget.getAttribute("indicator-selector") || null;
+    }
+
+    let targets;
+    if (!selector) {
+        targets = [eventTarget];
+    } else if (selector.startsWith("closest ")) {
+        const closestSelector = selector.slice(8);
+        const found = eventTarget.closest(closestSelector);
+        targets = found ? [found] : [];
+    } else {
+        targets = Array.from(document.querySelectorAll(selector));
+    }
+
+    for (const el of targets) {
+        el.classList.add(indicatorClass);
+    }
+
+    try {
+        return await f(...args);
+    } finally {
+        for (const el of targets) {
+            el.classList.remove(indicatorClass);
+        }
+    }
+}
+
+function embed(function_id) {
+    return async (...args) => {
+        const serial = JSON.parse(JSON.stringify(args));
+        return await window.buche.request({
+            $class: "buchelib.srx:Call",
+            function: function_id,
+            args: serial
+        });
+    }
+}
+
+Event.prototype.indicate = function(fn, ...args) {
+    return indicate(fn, args, this.currentTarget || this.target);
+};
+
+window.indicate = indicate;
+window.embed = embed;

buchelib-0.0.1/src/buchelib/selection.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+from pathlib import Path
+from string.templatelib import Template
+
+from hypetext import html
+from ovld import ovld, recurse
+
+from .bridge import Cell
+
+
+@dataclass(kw_only=True)
+class Selection:
+    cell: Cell
+    selector: str = None
+
+    def __getitem__(self, selector):
+        sel = f"{self.selector} {selector}" if self.selector else selector
+        return type(self)(cell=self.cell, selector=sel)
+
+    @ovld
+    def exec(self, code: Path):
+        recurse(code.read_text())
+
+    @ovld
+    def exec(self, code: Template):
+        scode = "".join(self.cell.interpreter.string_parts(code, "", "script"))
+        recurse(scode)
+
+    @ovld
+    def exec(self, code: str):
+        self.cell.command(type="exec", code=code, selector=self.selector)
+
+    def print(self, tpl):
+        node = html(tpl)
+        self.cell.command(
+            type="html",
+            mode="append",
+            selector=self.selector,
+            content="".join(self.cell.interpreter.string_parts(node)),
+        )
+
+    def set(self, tpl):
+        node = html(tpl)
+        self.cell.command(
+            type="html",
+            mode="set",
+            selector=self.selector,
+            content="".join(self.cell.interpreter.string_parts(node)),
+        )

buchelib-0.0.1/src/buchelib/srx.py

@@ -0,0 +1,72 @@
+import inspect
+from dataclasses import dataclass
+from types import FunctionType
+
+from ovld import Medley
+from serieux import JSON
+
+from .bridge import Cell, CellContext
+
+
+@dataclass
+class ResponseId:
+    id: str
+    cell: Cell
+
+    def resolve(self, value):
+        self.cell.command(type="resolve", value=value, response_id=self.id)
+
+    def reject(self, error):
+        self.cell.command(type="resolve", error=str(error), response_id=self.id)
+
+
+@Cell.register_type_default
+@dataclass
+class Call:
+    function: FunctionType
+    args: list[JSON]
+    response_id: ResponseId
+
+    def __post_init__(self):
+        self.cell = self.response_id.cell
+
+    async def call(self):
+        try:
+            params = list(inspect.signature(self.function).parameters.values())
+            for p in params:
+                if p.annotation is inspect.Parameter.empty:
+                    raise TypeError(
+                        f"Parameter '{p.name}' of {self.function.__name__} has no type annotation"
+                    )
+            deserialized = [
+                self.cell.srx.deserialize(p.annotation, arg) for p, arg in zip(params, self.args)
+            ]
+            result = await self.function(*deserialized)
+            self.response_id.resolve(result)
+            return result
+        except Exception as exc:
+            self.response_id.reject(exc)
+            raise
+
+
+class BucheSerieux(Medley):
+    ######################
+    # Custom serializers #
+    ######################
+
+    def serialize(self, t: type[FunctionType], obj: FunctionType, ctx: CellContext):
+        return t"embed({ctx.cell.register_function(obj)})"
+
+    ########################
+    # Custom deserializers #
+    ########################
+
+    def deserialize(self, t: type[FunctionType], obj: str, ctx: CellContext):
+        for fn, tag in ctx.cell.function_registry.items():
+            if tag == obj:
+                return fn
+        else:
+            raise Exception(f"No function with tag: {obj}")
+
+    def deserialize(self, t: type[ResponseId], obj: str, ctx: CellContext):
+        return ResponseId(obj, ctx.cell)