tkinter-web-backend 0.1.0__py3-none-any.whl

tkinter_web/__init__.py

@@ -0,0 +1,89 @@
+"""
+tkinter-web-backend: a web backend for tkinter.
+
+tkinter programs run unchanged; their windows are displayed in a web
+browser. A Tk engine written in Python replaces Tcl/Tk (the _tkinter
+module): it keeps the state of the windows, computes their geometry and
+sends display operations to the browser, which sends back user input.
+
+Use it with ``python -m tkinter_web script.py``, or connect it from the
+program (commenting the second line gives back the native Tk)::
+
+    import tkinter_web
+    tkinter_web.install()
+"""
+
+import sys
+
+__version__ = "0.1.0"
+__all__ = ["install", "uninstall", "is_installed"]
+
+
+def install():
+    """Make tkinter use tkinter-web-backend.
+
+    It can be called before or after importing tkinter, but before creating
+    any window.
+    """
+    from . import _tkinter
+
+    current = sys.modules.get("_tkinter")
+    if current is _tkinter:
+        return
+    tkinter = sys.modules.get("tkinter")
+    if tkinter is not None and current is not None:
+        if getattr(tkinter, "_default_root", None) is not None:
+            raise RuntimeError("a tkinter window already exists with the native Tk: "
+                               "call tkinter_web.install() before creating it")
+        _rebind(current, _tkinter)
+    sys.modules["_tkinter"] = _tkinter
+    _ensure_tkinter_package()
+
+
+def _rebind(old, new):
+    """Point the modules already imported (tkinter's, the program's after
+    ``from tkinter import *``...) at the new _tkinter."""
+    replace = {id(old): new}
+    for name, value in vars(old).items():
+        if not name.startswith("__") and hasattr(new, name) and \
+                not isinstance(value, (int, float, str)):
+            replace[id(value)] = getattr(new, name)
+    for name, module in list(sys.modules.items()):
+        namespace = getattr(module, "__dict__", None)
+        if namespace is None or module is old:
+            continue
+        for key, value in list(namespace.items()):
+            if id(value) in replace:
+                namespace[key] = replace[id(value)]
+    tkinter = sys.modules["tkinter"]
+    tkinter.TkVersion = float(new.TK_VERSION)
+    tkinter.TclVersion = float(new.TCL_VERSION)
+
+
+def uninstall():
+    from . import _tkinter
+
+    if sys.modules.get("_tkinter") is _tkinter:
+        del sys.modules["_tkinter"]
+        for name in [n for n in sys.modules if n == "tkinter" or n.startswith("tkinter.")]:
+            del sys.modules[name]
+
+
+def is_installed():
+    from . import _tkinter
+
+    return sys.modules.get("_tkinter") is _tkinter
+
+
+def _ensure_tkinter_package():
+    """Use the bundled copy of tkinter if the Python installation has none."""
+    import importlib.util
+    import os
+    from pathlib import Path
+
+    forced = os.environ.get("TKINTER_WEB_VENDORED", "") not in ("", "0")
+    if not forced and importlib.util.find_spec("tkinter") is not None:
+        return
+    vendor = str(Path(__file__).parent / "_vendor")
+    if vendor not in sys.path:
+        sys.path.insert(0, vendor)

tkinter_web/__main__.py

@@ -0,0 +1,69 @@
+"""
+Run a tkinter program with tkinter-web-backend:
+
+    python -m tkinter_web [options] script.py [args...]
+    python -m tkinter_web [options] -m module [args...]
+    python -m tkinter_web [options]            (interactive console)
+"""
+
+import argparse
+import code
+import os
+import runpy
+import sys
+
+from . import __version__, install
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = argparse.ArgumentParser(
+        prog="python -m tkinter_web",
+        description="Run a tkinter program in a web browser.",
+        usage="%(prog)s [options] [-m module | script] [args ...]")
+    parser.add_argument("-m", dest="module", help="run a library module as a script")
+    parser.add_argument("--port", type=int, help="port of the local server (default: any)")
+    parser.add_argument("--no-browser", action="store_true",
+                        help="do not open a web browser")
+    parser.add_argument("--version", action="version", version=f"tkinter-web-backend {__version__}")
+    # options end at the script or at the module name: what follows is theirs
+    options, rest = [], []
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "-m" and i + 1 < len(argv):
+            options += argv[i:i + 2]
+            rest = argv[i + 2:]
+            break
+        if a == "--port" and i + 1 < len(argv):
+            options += argv[i:i + 2]
+            i += 2
+            continue
+        if a.startswith("-") and a != "-":
+            options.append(a)
+            i += 1
+            continue
+        rest = argv[i:]
+        break
+    ns = parser.parse_args(options)
+    if ns.port is not None:
+        os.environ["TKINTER_WEB_PORT"] = str(ns.port)
+    if ns.no_browser:
+        os.environ["TKINTER_WEB_BROWSER"] = "0"
+    install()
+    if ns.module:
+        sys.argv = [ns.module] + rest
+        runpy.run_module(ns.module, run_name="__main__", alter_sys=True)
+    elif rest:
+        script = rest[0]
+        sys.argv = rest
+        sys.path.insert(0, os.path.dirname(os.path.abspath(script)))
+        runpy.run_path(script, run_name="__main__")
+    else:
+        sys.ps1 = ">>> "
+        code.interact(banner=f"tkinter-web-backend {__version__} (Python {sys.version.split()[0]})",
+                      local={"__name__": "__main__"})
+
+
+if __name__ == "__main__":
+    main()

tkinter_web/_tkinter.py

@@ -0,0 +1,321 @@
+"""
+A replacement of the _tkinter C extension module.
+
+tkinter (the pure Python part of the standard library) talks to Tcl/Tk
+through this module only: here, ``create()`` returns an application object
+whose commands are executed by the tkinter_web engine, rendered in a web
+browser instead of a native window.
+"""
+
+import sys
+import threading
+
+from .tk.tcl import TclError, get_boolean, get_double, get_int, split_list, to_str
+from .tk.interp import TK_VERSION
+
+__all__ = ["create", "TclError", "TkappType", "Tcl_Obj"]
+
+TK_VERSION = TK_VERSION
+TCL_VERSION = TK_VERSION
+
+READABLE = 2
+WRITABLE = 4
+EXCEPTION = 8
+
+WINDOW_EVENTS = 4
+FILE_EVENTS = 8
+TIMER_EVENTS = 16
+IDLE_EVENTS = 32
+ALL_EVENTS = -3
+DONT_WAIT = 2
+
+_busywaitinterval = 20
+
+
+def setbusywaitinterval(ms):
+    global _busywaitinterval
+    _busywaitinterval = int(ms)
+
+
+def getbusywaitinterval():
+    return _busywaitinterval
+
+
+class Tcl_Obj:
+    """Tcl objects returned without conversion (rare with tkinter_web)."""
+
+    def __init__(self, value, typename="string"):
+        self._value = value
+        self.typename = typename
+
+    @property
+    def string(self):
+        return to_str(self._value)
+
+    def __str__(self):
+        return to_str(self._value)
+
+    def __repr__(self):
+        return f"<{self.typename} object: {self.string!r}>"
+
+    def __eq__(self, other):
+        if isinstance(other, Tcl_Obj):
+            return self.string == other.string
+        return NotImplemented
+
+    def __hash__(self):
+        return hash(self.string)
+
+
+class TkttObject:
+    def __init__(self, interp, ident):
+        self._interp = interp
+        self._id = ident
+
+    def deletetimerhandler(self):
+        self._interp.call("after", "cancel", self._id)
+
+
+def _value(v):
+    """Values returned to tkinter (Python objects, as with wantobjects)."""
+    if isinstance(v, list):
+        return tuple(_value(x) for x in v)
+    if isinstance(v, tuple):
+        return tuple(_value(x) for x in v)
+    if v is None:
+        return ""
+    return v
+
+
+_NATIVE = (str, int, float, bytes, bytearray, Tcl_Obj)
+
+
+def _arg(a):
+    """Arguments of calls as _tkinter converts them (objects become strings)."""
+    if isinstance(a, _NATIVE):
+        return a
+    if isinstance(a, (tuple, list)):
+        return tuple(_arg(x) for x in a)
+    if a is None:
+        return ""
+    return str(a)
+
+
+class TkappType:
+    """The Tcl/Tk application of a Tk() window."""
+
+    def __init__(self, screenName=None, baseName=None, className="Tk", interactive=False,
+                 wantobjects=1, useTk=True, sync=False, use=None):
+        from .app import get_app
+        self._app = get_app()
+        self._interp = self._app.new_interp(className or "Tk", baseName or "tk")
+        if not useTk:
+            # Tcl(): an interpreter without a main window
+            self._interp.root.wm["state"] = "withdrawn"
+        self._wantobjects = wantobjects
+        self._trace = None
+        self._thread = threading.get_ident()
+
+    # -- evaluation
+
+    def call(self, *args):
+        if len(args) == 1 and isinstance(args[0], tuple):
+            args = args[0]
+        if None in args:
+            # as _tkinter: None ends the argument list
+            args = args[: args.index(None)]
+        args = tuple(_arg(a) for a in args)
+        if self._trace is not None:
+            self._trace(args)
+        with self._app.lock:
+            return _value(self._interp.call(*args))
+
+    def eval(self, script):
+        if self._trace is not None:
+            self._trace((script,))
+        with self._app.lock:
+            return _value(self._interp.eval(script))
+
+    def evalfile(self, filename):
+        return ""
+
+    def record(self, script):
+        return self.eval(script)
+
+    def adderrorinfo(self, msg):
+        pass
+
+    # -- variables
+
+    def _varname(self, args):
+        if len(args) >= 2 and isinstance(args[1], str) and args[1] and len(args) == 3:
+            return f"{args[0]}({args[1]})"
+        return to_str(args[0])
+
+    def setvar(self, *args):
+        if len(args) == 3:
+            name, value = f"{args[0]}({args[1]})", args[2]
+        elif len(args) == 2:
+            name, value = to_str(args[0]), args[1]
+        else:
+            raise TypeError("setvar requires 2 or 3 arguments")
+        with self._app.lock:
+            self._interp.variables.set(name, value)
+
+    globalsetvar = setvar
+
+    def getvar(self, *args):
+        name = f"{args[0]}({args[1]})" if len(args) == 2 and args[1] else to_str(args[0])
+        with self._app.lock:
+            return _value(self._interp.variables.get(name))
+
+    globalgetvar = getvar
+
+    def unsetvar(self, *args):
+        name = f"{args[0]}({args[1]})" if len(args) == 2 and args[1] else to_str(args[0])
+        with self._app.lock:
+            self._interp.variables.unset(name)
+
+    globalunsetvar = unsetvar
+
+    # -- conversions
+
+    def getint(self, arg):
+        if isinstance(arg, Tcl_Obj):
+            arg = arg.string
+        if isinstance(arg, float):
+            raise TypeError("getint() argument must be str or int")
+        return get_int(arg)
+
+    def getdouble(self, arg):
+        if isinstance(arg, Tcl_Obj):
+            arg = arg.string
+        return get_double(arg)
+
+    def getboolean(self, arg):
+        if isinstance(arg, Tcl_Obj):
+            arg = arg.string
+        return bool(get_boolean(arg))
+
+    def exprstring(self, s):
+        return to_str(s)
+
+    def exprlong(self, s):
+        return get_int(s)
+
+    def exprdouble(self, s):
+        return get_double(s)
+
+    def exprboolean(self, s):
+        return bool(get_boolean(s))
+
+    def splitlist(self, arg):
+        if isinstance(arg, Tcl_Obj):
+            arg = arg.string
+        if isinstance(arg, (tuple, list)):
+            return tuple(arg)
+        if isinstance(arg, str):
+            return split_list(arg)
+        if isinstance(arg, (bytes, bytearray)):
+            return split_list(arg.decode())
+        return (arg,)
+
+    def split(self, arg):
+        if isinstance(arg, str):
+            items = split_list(arg)
+            if len(items) == 1 and items[0] == arg:
+                return arg
+            return tuple(self.split(i) if " " in i else i for i in items)
+        return arg
+
+    # -- commands
+
+    def createcommand(self, name, func):
+        if not callable(func):
+            raise TypeError("command not callable")
+        with self._app.lock:
+            self._interp.commands[to_str(name)] = func
+
+    def deletecommand(self, name):
+        with self._app.lock:
+            if self._interp.commands.pop(to_str(name), None) is None:
+                raise TclError(f"can't delete Tcl command")
+
+    def createfilehandler(self, file, mask, func):
+        raise NotImplementedError("createfilehandler is not supported by tkinter-web-backend")
+
+    def deletefilehandler(self, file):
+        pass
+
+    def createtimerhandler(self, milliseconds, func):
+        name = f"::tkinter_web_timer{id(func)}"
+        interp = self._interp
+
+        def run():
+            interp.commands.pop(name, None)
+            func()
+
+        with self._app.lock:
+            interp.commands[name] = run
+            ident = interp.call("after", milliseconds, name)
+        return TkttObject(interp, ident)
+
+    # -- event loop
+
+    def mainloop(self, threshold=0):
+        if threading.get_ident() != self._thread:
+            raise RuntimeError("Calling Tcl from different apartment")
+        self._app.mainloop(self._interp, threshold)
+
+    def dooneevent(self, flags=0):
+        self._app.step(block=not flags & DONT_WAIT)
+        return 1
+
+    def quit(self):
+        self._app.quit()
+
+    def interpaddr(self):
+        return id(self._interp)
+
+    def loadtk(self):
+        pass
+
+    def willdispatch(self):
+        pass
+
+    def wantobjects(self, *args):
+        if args:
+            self._wantobjects = args[0]
+            return None
+        return self._wantobjects
+
+    def settrace(self, func):
+        self._trace = func
+
+    def gettrace(self):
+        return self._trace
+
+    # access to the engine (tests, debugging)
+    @property
+    def tkinter_web_interp(self):
+        return self._interp
+
+
+def create(screenName=None, baseName=None, className="Tk", interactive=False,
+           wantobjects=1, useTk=True, sync=False, use=None):
+    return TkappType(screenName, baseName, className, interactive, wantobjects,
+                     useTk, sync, use)
+
+
+def _flatten(item):
+    res = []
+
+    def walk(x):
+        if isinstance(x, (tuple, list)):
+            for y in x:
+                walk(y)
+        elif x is not None:
+            res.append(x)
+
+    walk(item)
+    return tuple(res)