webpygame 1.0.0__py3-none-any.whl

webpy/__init__.py

@@ -0,0 +1,7 @@
+# engine first: it sets SDL_VIDEODRIVER=dummy before pygame is initialised
+from .engine import start_server, get_window_size, separate_tabs, share, settings, URLCHANGED
+
+# Re-export everything from pygame, so `webpy.Rect`, `webpy.draw`, `webpy.K_a`,
+# `webpy.MOUSEBUTTONDOWN` etc. all work. Also gives `webpy.pygame` itself.
+import pygame
+from pygame import *

webpy/engine.py

@@ -0,0 +1,847 @@
+import os
+os.environ.setdefault("SDL_VIDEODRIVER", "dummy")  # no real window needed
+
+import asyncio
+import atexit
+import io
+import json
+import platform
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+import urllib.request
+import webbrowser
+from http import HTTPStatus
+
+import pygame
+import websockets
+
+try:
+    from websockets.asyncio.server import serve as _ws_serve
+    from websockets.asyncio.client import connect as _ws_connect
+except ImportError:                                   # old websockets (before version 14)
+    raise ImportError("webpy needs websockets 14 or newer. Run:  pip install -U websockets")
+
+
+class _Settings:
+    """webpy.settings: change these at the top of your script, before display.set_mode()."""
+    port = 8766              # the one port for the page AND the live connection
+    fps = 30                 # frames per second sent to the browser
+    share = True             # True: other computers on your network can open the site
+    separate_tabs = True     # True: every tab gets its own copy of your script
+    new_terminal = False     # Windows: give each tab's copy its own console window
+    max_tabs = 10            # most separate copies allowed at once (protects your PC)
+    tunnel = "cloudflare"    # how display.public() makes a public link: "cloudflare" or "off"
+    public = True            # True: make a public link (works from anywhere) when the site starts
+
+
+settings = _Settings()
+WS_PATH = "/__webpy_ws"                                # the websocket lives on the same port
+_CHILD_PORT = os.environ.get("WEBPY_CHILD_PORT")       # set only inside a spawned tab process
+
+
+def share(enabled=True):
+    """Same as settings.share. True (default): other computers on your network can open the
+    site. False: only this computer can."""
+    settings.share = bool(enabled)
+
+
+def separate_tabs(enabled=True, new_terminal=False):
+    """Same as settings.separate_tabs / settings.new_terminal."""
+    settings.separate_tabs = bool(enabled)
+    settings.new_terminal = bool(new_terminal)
+
+
+def _bind_host():
+    return None if settings.share else "127.0.0.1"     # None = all network interfaces
+
+
+def _lan_ip():
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+            sock.connect(("10.255.255.255", 1))   # no packet is sent; just picks the right NIC
+            return sock.getsockname()[0]
+    except OSError:
+        try:
+            return socket.gethostbyname(socket.gethostname())
+        except OSError:
+            return "localhost"
+
+
+def url():
+    """The address for other computers on your network, e.g. 'http://192.168.1.23:8766'."""
+    return f"http://{_lan_ip() if settings.share else 'localhost'}:{settings.port}"
+
+
+# ---- public link (Cloudflare quick tunnel; free, no account) -----------------
+_tunnel = {"proc": None, "url": None}
+
+
+_CF_DIR = os.path.join(os.path.expanduser("~"), ".webpy")
+_CF_FILE = os.path.join(_CF_DIR, "cloudflared" + (".exe" if os.name == "nt" else ""))
+_CF_URL = "https://github.com/cloudflare/cloudflared/releases/latest/download/"
+
+
+def _find_cloudflared():
+    exe = shutil.which("cloudflared") or shutil.which("cloudflared.exe")
+    return exe or (_CF_FILE if os.path.exists(_CF_FILE) else None)
+
+
+def _download_cloudflared():
+    """Download Cloudflare's official program into ~/.webpy. Returns its path, or None."""
+    machine = platform.machine().lower()
+    names = {("Windows", "amd64"): "cloudflared-windows-amd64.exe",
+             ("Windows", "x86_64"): "cloudflared-windows-amd64.exe",
+             ("Linux", "x86_64"): "cloudflared-linux-amd64",
+             ("Linux", "amd64"): "cloudflared-linux-amd64",
+             ("Linux", "aarch64"): "cloudflared-linux-arm64",
+             ("Linux", "arm64"): "cloudflared-linux-arm64"}
+    name = names.get((platform.system(), machine))
+    if not name:
+        return None
+    try:
+        os.makedirs(_CF_DIR, exist_ok=True)
+        tmp = _CF_FILE + ".part"
+        print("webpy: downloading cloudflared (about 40 MB)...")
+        urllib.request.urlretrieve(_CF_URL + name, tmp)
+        os.replace(tmp, _CF_FILE)
+        os.chmod(_CF_FILE, 0o755)
+        print("webpy: cloudflared saved to", _CF_FILE)
+        return _CF_FILE
+    except Exception as e:
+        print("webpy: could not download cloudflared:", e)
+        return None
+
+
+def _offer_cloudflared():
+    """Ask once (in the terminal) before downloading anything."""
+    marker = os.path.join(_CF_DIR, "declined")
+    if os.path.exists(marker) or not sys.stdin or not sys.stdin.isatty():
+        return None
+    try:
+        ans = input("webpy: a public link needs Cloudflare's free 'cloudflared' program "
+                    "(about 40 MB, from github.com/cloudflare/cloudflared).\n"
+                    "       Download it now? [Y/n] ").strip().lower()
+    except EOFError:
+        return None
+    if ans in ("", "y", "yes"):
+        return _download_cloudflared()
+    try:
+        os.makedirs(_CF_DIR, exist_ok=True)
+        open(marker, "w").close()
+        print(f"webpy: OK, I won't ask again. (Delete {marker} to be asked again.)")
+    except OSError:
+        pass
+    return None
+
+
+def public():
+    """Make the site reachable from ANYWHERE (not just your network) and return the link,
+    e.g. 'https://random-words.trycloudflare.com'. Needs the free `cloudflared` program."""
+    if _CHILD_PORT is not None:             # a tab's copy: the launcher owns the tunnel
+        link = os.environ.get("WEBPY_PUBLIC_URL") or None
+        if not link:
+            print("webpy: to get a public link set  webpy.settings.public = True  at the top of your script.")
+        return link
+    if _tunnel["url"]:
+        return _tunnel["url"]
+    if settings.tunnel in (None, False, "", "off"):
+        print("webpy: public links are turned off (settings.tunnel = 'off').")
+        return None
+    if settings.tunnel != "cloudflare":
+        print(f"webpy: unknown tunnel {settings.tunnel!r}. Use 'cloudflare' or 'off'.")
+        return None
+    exe = _find_cloudflared()
+    if not exe:
+        exe = _offer_cloudflared()
+    if not exe:
+        print("webpy: public links need the free 'cloudflared' program. To install it yourself:\n"
+              "   Windows:  winget install --id Cloudflare.cloudflared   (then restart the terminal)\n"
+              "   Mac:      brew install cloudflared\n"
+              "   Linux:    https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/\n"
+              "   (or set webpy.settings.public = False to stop looking for a public link)")
+        return None
+    proc = subprocess.Popen([exe, "tunnel", "--url", f"http://127.0.0.1:{settings.port}", "--no-autoupdate"],
+                            stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                            text=True, encoding="utf-8", errors="replace")
+    atexit.register(lambda: proc.poll() is None and proc.terminate())
+    found = threading.Event()
+    tail = []
+
+    def reader():
+        for line in proc.stdout:            # keep draining so cloudflared never blocks
+            tail[:] = (tail + [line.strip()])[-3:]
+            m = re.search(r"https://(?!api\.)[a-z0-9-]+\.trycloudflare\.com", line)
+            if m and not _tunnel["url"]:
+                _tunnel["url"] = m.group(0)
+                found.set()
+    threading.Thread(target=reader, daemon=True).start()
+    _tunnel["proc"] = proc
+    if not found.wait(30):
+        print("webpy: could not get a public link from Cloudflare (is the network blocking it?).")
+        for line in tail[-2:]:
+            print("   cloudflared said:", line[:200])
+        proc.terminate()
+        return None
+    print(f"-> Public link (works from anywhere while this is running):  {_tunnel['url']}")
+    return _tunnel["url"]
+
+
+pygame.display.url = url
+pygame.display.public = public
+
+
+# --- JS key code -> pygame key -------------------------------------------
+KEY_MAP = {
+    'Space': pygame.K_SPACE, 'Enter': pygame.K_RETURN, 'Backspace': pygame.K_BACKSPACE,
+    'Escape': pygame.K_ESCAPE, 'Tab': pygame.K_TAB, 'Delete': pygame.K_DELETE,
+    'ArrowUp': pygame.K_UP, 'ArrowDown': pygame.K_DOWN,
+    'ArrowLeft': pygame.K_LEFT, 'ArrowRight': pygame.K_RIGHT,
+    'ShiftLeft': pygame.K_LSHIFT, 'ShiftRight': pygame.K_RSHIFT,
+    'ControlLeft': pygame.K_LCTRL, 'ControlRight': pygame.K_RCTRL,
+    'AltLeft': pygame.K_LALT, 'AltRight': pygame.K_RALT,
+    'Home': pygame.K_HOME, 'End': pygame.K_END,
+    'PageUp': pygame.K_PAGEUP, 'PageDown': pygame.K_PAGEDOWN,
+}
+for c in "abcdefghijklmnopqrstuvwxyz":
+    KEY_MAP['Key' + c.upper()] = getattr(pygame, 'K_' + c)
+for d in "0123456789":
+    KEY_MAP['Digit' + d] = getattr(pygame, 'K_' + d)
+
+
+# Posted when the person presses the browser's Back/Forward buttons: event.path is the new URL path.
+URLCHANGED = pygame.event.custom_type()
+
+
+class KeyState(dict):
+    """pygame key constants are huge ints (K_UP == 1073741906), so a fixed
+    list of 512 booleans raises IndexError. A dict that defaults to False works."""
+    def __missing__(self, key):
+        return False
+
+
+class TabInput:
+    """All input state for ONE browser tab."""
+    def __init__(self, size=(800, 600)):
+        self.surface = pygame.Surface(size)     # this tab's canvas (what gets streamed)
+        self.resizable = False                  # set by set_mode(..., pygame.RESIZABLE)
+        self.caption = "WebPy Viewport"
+        self.path = "/"                          # the browser's current URL path
+        self.url = None                         # class mode: URL path the site asked for
+        self.pos = (0, 0)
+        self.pressed = [False, False, False]
+        self.keys = KeyState()
+        self.events = []
+        self.window_size = (0, 0)   # browser viewport size, filled in by the page
+        self.script_mode = False    # True for the shared input used by plain scripts
+        self.pending_resize = None  # script mode: applied on the main thread
+
+    def feed(self, data):
+        t = data.get('type')
+        # BUG FIX: original used data.get('x', tab_mouse_pos) -> a tuple as default,
+        # which corrupted the position on key events.
+        if 'x' in data and 'y' in data:
+            self.pos = (int(data['x']), int(data['y']))
+
+        if t == 'resize':
+            self.window_size = (int(data.get('w', 0)), int(data.get('h', 0)))
+            if data.get('path'):
+                self.path = str(data['path'])
+            w, h = self.window_size
+            # RESIZABLE sites follow the browser window, like a real pygame window
+            if self.script_mode:
+                if self.resizable and w > 0 and h > 0:
+                    self.pending_resize = (w, h)
+            elif self.resizable and w > 0 and h > 0 and (w, h) != self.surface.get_size():
+                self.surface = pygame.Surface((w, h))
+                self.events.append(pygame.event.Event(pygame.VIDEORESIZE, size=(w, h), w=w, h=h))
+        elif t == 'path':                      # Back / Forward in the browser
+            self.path = str(data.get('path') or '/')
+            self.events.append(pygame.event.Event(URLCHANGED, path=self.path))
+        elif t in ('mousedown', 'mouseup'):
+            b = data.get('button', 0)
+            if b in (0, 1, 2):
+                down = t == 'mousedown'
+                self.pressed[b] = down
+                self.events.append(pygame.event.Event(
+                    pygame.MOUSEBUTTONDOWN if down else pygame.MOUSEBUTTONUP,
+                    button=b + 1, pos=self.pos))
+        elif t == 'scroll':
+            btn = 5 if data.get('delta', 0) > 0 else 4
+            for typ in (pygame.MOUSEBUTTONDOWN, pygame.MOUSEBUTTONUP):
+                self.events.append(pygame.event.Event(typ, button=btn, pos=self.pos))
+        elif t in ('keydown', 'keyup'):
+            k = KEY_MAP.get(data.get('code', ''))
+            if k is not None:
+                down = t == 'keydown'
+                self.keys[k] = down
+                if down:
+                    ch = data.get('key', '')
+                    self.events.append(pygame.event.Event(
+                        pygame.KEYDOWN, key=k, unicode=ch if len(ch) == 1 else ''))
+                else:
+                    self.events.append(pygame.event.Event(pygame.KEYUP, key=k))
+
+    def drain(self):
+        ev, self.events = self.events, []
+        return ev
+
+
+# =========================================================================
+#  Pygame patching.  Two ways to use webpy:
+#   * SCRIPT mode (default): a normal pygame loop that calls display.flip().
+#     One shared session; every open tab shows (and controls) the same site.
+#   * CLASS mode (start_server(MyClass)): one isolated instance per tab.
+# =========================================================================
+_shared = TabInput()          # the input state used in script mode
+_shared.script_mode = True
+_current = _shared            # whichever input state the running code should see
+_class_mode = False
+
+class _Real:                  # the genuine pygame functions, kept for script mode
+    set_mode = staticmethod(pygame.display.set_mode)
+    get_surface = staticmethod(pygame.display.get_surface)
+    set_caption = staticmethod(pygame.display.set_caption)
+
+pygame.mouse.get_pos = lambda: _current.pos
+pygame.mouse.get_pressed = lambda *a, **k: tuple(_current.pressed)
+pygame.key.get_pressed = lambda: _current.keys
+
+
+# ---- script-mode server (runs in a background thread) --------------------
+class _Hub:
+    def __init__(self):
+        self.loop = None
+        self.clients = set()                 # one asyncio.Event per connected tab
+        self.frame = None                    # latest JPEG bytes
+        self.title = "WebPy Viewport"
+        self.url = None
+        self.started = False
+        self.ready = threading.Event()
+        self.got_size = threading.Event()    # set once a browser reported its size
+        self.last_flip = 0.0
+        self.ever_connected = False
+
+hub = _Hub()
+
+
+def _wake():
+    if hub.loop:
+        hub.loop.call_soon_threadsafe(lambda: [e.set() for e in list(hub.clients)])
+
+
+async def _script_handler(ws):
+    print("Tab connected")
+    hub.ever_connected = True
+    ev = asyncio.Event()
+    ev.set()                                 # send the current frame straight away
+    hub.clients.add(ev)
+
+    async def reader():
+        async for msg in ws:
+            try:
+                _shared.feed(json.loads(msg))
+                if _shared.window_size[0] > 0:
+                    hub.got_size.set()
+            except Exception as e:
+                print("Bad input message:", e)
+
+    rt = asyncio.create_task(reader())
+    sent_title = sent_frame = sent_url = None
+    try:
+        while not rt.done():
+            try:
+                await asyncio.wait_for(ev.wait(), 0.5)
+            except asyncio.TimeoutError:
+                continue
+            ev.clear()
+            if hub.title != sent_title:
+                sent_title = hub.title
+                await ws.send(json.dumps({"type": "title", "title": sent_title}))
+            if hub.url is not None and hub.url != sent_url:
+                sent_url = hub.url
+                await ws.send(json.dumps({"type": "url", "url": sent_url}))
+            frame = hub.frame
+            if frame is not None and frame is not sent_frame:
+                sent_frame = frame
+                await ws.send(frame)
+    except websockets.exceptions.ConnectionClosed:
+        pass
+    finally:
+        rt.cancel()
+        hub.clients.discard(ev)
+        print("Tab closed")
+        if _CHILD_PORT is not None:          # this process only exists for that one tab
+            sys.stdout.flush()
+            os._exit(0)
+
+
+# ---- separate-tabs master: serves no site itself, just starts one process per tab ----
+def _free_port():
+    with socket.socket() as sock:
+        sock.bind(("localhost", 0))
+        return sock.getsockname()[1]
+
+
+def _spawn_child(port):
+    env = dict(os.environ, WEBPY_CHILD_PORT=str(port),
+               WEBPY_NEW_TERMINAL="1" if settings.new_terminal else "",
+               WEBPY_PUBLIC_URL=_tunnel["url"] or "")
+    kw = {}
+    if os.name == "nt" and settings.new_terminal:
+        kw["creationflags"] = subprocess.CREATE_NEW_CONSOLE    # a fresh terminal window
+    return subprocess.Popen([sys.executable] + sys.argv, env=env, **kw)
+
+
+async def _connect_local(port):
+    url_ = f"ws://127.0.0.1:{port}"
+    try:
+        return await _ws_connect(url_, max_size=None, proxy=None)    # never go via a proxy
+    except TypeError:                                                  # older websockets
+        return await _ws_connect(url_, max_size=None)
+
+
+def _process_request(connection, request):
+    """Same port serves the web page (any path, so /about works) and the websocket."""
+    path = request.path.split("?")[0]
+    if path == WS_PATH:
+        return None                                  # carry on with the websocket handshake
+    if path.startswith("/favicon"):
+        return connection.respond(HTTPStatus.NO_CONTENT, "")
+    resp = connection.respond(HTTPStatus.OK, HTML_TEMPLATE.replace("__PORT__", str(settings.port)).replace("__WSPATH__", WS_PATH))
+    del resp.headers["Content-Type"]
+    resp.headers["Content-Type"] = "text/html; charset=utf-8"
+    resp.headers["Cache-Control"] = "no-store"
+    return resp
+
+
+def _serve(handler):
+    return _ws_serve(handler, _bind_host(), settings.port,
+                     process_request=_process_request, max_size=None)
+
+
+def _announce():
+    """Open the browser here and print the addresses for other computers."""
+    webbrowser.open(f"http://localhost:{settings.port}")
+    if settings.share:
+        print(f"-> On another computer on your network, open:  {url()}")
+        print("   (if Windows asks, allow Python through the firewall on private networks)")
+    if settings.public:
+        public()
+
+
+def _run_master():
+    """Never returns. Each browser tab that connects gets its own copy of your script."""
+    children = []
+
+    def cleanup():
+        for p in children:
+            if p.poll() is None:
+                p.terminate()
+    atexit.register(cleanup)
+
+    async def handler(ws):
+        if len([p for p in children if p.poll() is None]) >= settings.max_tabs:
+            await ws.send(json.dumps({"type": "busy"}))
+            return
+        port = _free_port()
+        children.append(_spawn_child(port))
+        print(f"Tab connected -> started a new instance (#{len(children)})")
+        up = None
+        for _ in range(150):                         # the new copy takes a moment to start
+            try:
+                up = await _connect_local(port)
+                break
+            except OSError:
+                await asyncio.sleep(0.2)
+        if up is None:
+            return
+
+        async def pipe(src, dst):
+            try:
+                async for msg in src:
+                    await dst.send(msg)
+            except websockets.exceptions.ConnectionClosed:
+                pass
+
+        tasks = [asyncio.create_task(pipe(ws, up)), asyncio.create_task(pipe(up, ws))]
+        await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+        for t in tasks:
+            t.cancel()
+        await up.close()
+
+    async def main():
+        async with _serve(handler):
+            _announce()
+            print("-> webpy running; every tab you open starts its own copy of this script "
+                  "(Ctrl+C to stop)")
+            await asyncio.Future()
+
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass
+    except OSError as e:
+        print(f"webpy: could not start server on port {settings.port}: {e}")
+    sys.exit(0)
+
+
+def _ensure_server():
+    if hub.started:
+        return
+    hub.started = True
+    if _CHILD_PORT is None and settings.separate_tabs:
+        _run_master()                        # never returns
+    child = _CHILD_PORT is not None
+    pygame.init()
+    if child:
+        import traceback
+
+        def hook(t, v, tb):                  # keep the window open so you can read the error
+            traceback.print_exception(t, v, tb)
+            print("\nwebpy: this tab's copy of your site crashed (other tabs are unaffected).")
+            if os.environ.get("WEBPY_NEW_TERMINAL"):     # own window: keep it open to read
+                try:
+                    input("Press Enter to close this window...")
+                except EOFError:
+                    pass
+            sys.stdout.flush()
+            os._exit(1)
+        sys.excepthook = hook
+        threading.Timer(30, lambda: None if hub.ever_connected else os._exit(0)).start()
+
+    def run():
+        async def main():
+            hub.loop = asyncio.get_running_loop()
+            if child:      # only the launcher talks to us, from this same computer
+                server = _ws_serve(_script_handler, "127.0.0.1", int(_CHILD_PORT), max_size=None)
+            else:
+                server = _serve(_script_handler)
+            async with server:
+                hub.ready.set()
+                await asyncio.Future()
+        try:
+            asyncio.run(main())
+        except OSError as e:
+            print(f"webpy: could not start server on port {settings.port}: {e}")
+            hub.ready.set()
+
+    threading.Thread(target=run, daemon=True).start()
+    hub.ready.wait(5)
+    if not child:
+        print("-> webpy running; open as many tabs as you like (Ctrl+C to stop)")
+        _announce()
+
+
+def _apply_pending_resize():
+    """Main thread only: follow the browser window for RESIZABLE sites."""
+    p, _shared.pending_resize = _shared.pending_resize, None
+    if p and _Real.get_surface() is not None and p != _Real.get_surface().get_size():
+        _Real.set_mode(p)
+        _shared.events.append(pygame.event.Event(pygame.VIDEORESIZE, size=p, w=p[0], h=p[1]))
+
+
+def _script_flip():
+    _apply_pending_resize()
+    surf = _Real.get_surface()
+    if surf is None:
+        return
+    # frame limiter (also stops a busy loop from spinning the CPU)
+    rest = 1 / settings.fps - (time.perf_counter() - hub.last_flip)
+    if rest > 0:
+        time.sleep(rest)
+    hub.last_flip = time.perf_counter()
+    buf = io.BytesIO()
+    pygame.image.save(surf, buf, "frame.jpg")
+    frame = buf.getvalue()
+    if frame != hub.frame:
+        hub.frame = frame
+    _wake()
+
+
+# ---- display.* replacements ----------------------------------------------
+def _set_mode(size=(0, 0), flags=0, *args, **kwargs):
+    """Replacement for pygame.display.set_mode."""
+    w, h = size
+    resizable = bool(flags & pygame.RESIZABLE)
+
+    if _class_mode:                          # per-tab canvas
+        t = _current
+        t.resizable = resizable
+        ww, wh = t.window_size
+        if resizable and ww > 0 and wh > 0:
+            w, h = ww, wh                    # start filled to the browser window
+        elif not w or not h:                 # (0, 0) means "use the window size"
+            w, h = (ww, wh) if (ww > 0 and wh > 0) else t.surface.get_size()
+        if (w, h) != t.surface.get_size():
+            t.surface = pygame.Surface((int(w), int(h)))
+        return t.surface
+
+    _ensure_server()
+    _shared.resizable = resizable
+    if resizable or not w or not h:          # need the browser's window size
+        hub.got_size.wait(15)
+    ww, wh = _shared.window_size
+    if (resizable or not w or not h) and ww > 0 and wh > 0:
+        w, h = ww, wh
+    if not w or not h:
+        w, h = 800, 600
+    return _Real.set_mode((int(w), int(h)))
+
+
+def _set_caption(title, icontitle=None):
+    if _class_mode:
+        _current.caption = str(title)
+    else:
+        hub.title = str(title)
+        _Real.set_caption(str(title))
+        _wake()
+
+def _clean_url(path):
+    path = str(path).strip() or "/"
+    if not path.startswith("/"):
+        path = "/" + path
+    return "/" + path.lstrip("/")           # never "//host" (that would be another site)
+
+
+def _set_url(path):
+    """Change the address bar to this path, e.g. set_url("/about"), without reloading."""
+    if "://" in str(path):
+        print("webpy: set_url() only takes a path like '/about'. A browser can't switch a page "
+              "to a different domain without reloading, so full URLs are ignored.")
+        return
+    path = _clean_url(path)
+    if _class_mode:
+        _current.path = path
+        _current.url = path
+    elif _shared.path != path or hub.url != path:
+        _shared.path = path
+        hub.url = path
+        _wake()
+
+def _get_url():
+    """The URL path the browser is at, e.g. "/about" (so a site can open on the right page)."""
+    return _current.path
+
+def _get_surface():
+    return _current.surface if _class_mode else _Real.get_surface()
+
+def _get_size():
+    s = _get_surface()
+    return s.get_size() if s is not None else (0, 0)
+
+def _flip():
+    if not _class_mode:
+        _script_flip()                       # class mode: frames are streamed automatically
+
+pygame.display.set_mode = _set_mode
+pygame.display.get_surface = _get_surface
+pygame.display.set_caption = _set_caption
+pygame.display.set_url = _set_url
+pygame.display.get_url = _get_url
+pygame.display.get_caption = lambda: ((_current.caption if _class_mode else hub.title),) * 2
+pygame.display.get_window_size = _get_size
+pygame.display.flip = _flip
+pygame.display.update = lambda *a, **k: _flip()
+
+
+# ---- event.* replacements --------------------------------------------------
+def _event_get(*a, **k):
+    _apply_pending_resize()
+    return _current.drain()
+
+def _event_poll():
+    _apply_pending_resize()
+    t = _current
+    return t.events.pop(0) if t.events else pygame.event.Event(pygame.NOEVENT)
+
+def _event_wait(*a, **k):
+    while True:
+        _apply_pending_resize()
+        if _current.events:
+            return _current.events.pop(0)
+        time.sleep(0.005)
+
+pygame.event.get = _event_get
+pygame.event.poll = _event_poll
+pygame.event.wait = _event_wait
+pygame.event.clear = lambda *a, **k: _current.drain() and None
+
+
+def get_window_size():
+    """Size (width, height) in pixels of THIS tab's browser window (the viewport).
+    Call it from inside update(). Returns (0, 0) for the first frame or so,
+    until the browser has reported its size."""
+    return _current.window_size
+
+
+HTML_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>WebPy Viewport</title>
+<style>
+  body { background:#111; margin:0; display:flex; justify-content:center; align-items:center; height:100vh; overflow:hidden; }
+  #v { display:block; max-width:100vw; max-height:100vh; cursor:default; user-select:none; -webkit-user-drag:none; outline:none; }
+</style>
+</head>
+<body>
+<img id="v" draggable="false">
+<script>
+const img = document.getElementById('v');
+let ws;
+function curPath() { return location.pathname + location.search; }
+function sendSize() { send({type:'resize', w:window.innerWidth, h:window.innerHeight, path:curPath()}); }
+window.addEventListener('popstate', () => send({type:'path', path:curPath()}));
+window.addEventListener('resize', sendSize);
+function send(o) { if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(o)); }
+
+function overlay(text) {
+  const d = document.createElement('div');
+  d.textContent = text;
+  d.style.cssText = 'position:fixed;inset:0;display:flex;align-items:center;justify-content:center;color:#ccc;font:20px sans-serif;background:#000a;cursor:pointer;text-align:center;padding:20px';
+  d.onclick = () => location.reload();
+  document.body.appendChild(d);
+}
+
+function connect() {
+  const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+  const host = location.host || 'localhost:__PORT__';       // (opened as a file: local only)
+  const sock = new WebSocket(proto + '://' + host + '__WSPATH__');
+  let opened = false, busy = false;
+  ws = sock;
+  sock.onopen = () => { opened = true; sendSize(); };
+  sock.onmessage = e => {
+    if (typeof e.data === 'string') {
+      const m = JSON.parse(e.data);
+      if (m.type === 'title') document.title = m.title;
+      else if (m.type === 'url') { try { if (m.url !== curPath()) history.pushState(null, '', m.url); } catch (err) {} }
+      else if (m.type === 'busy') busy = true;
+    } else if (e.data instanceof Blob) {
+      const url = URL.createObjectURL(e.data);
+      img.onload = () => URL.revokeObjectURL(url);
+      img.src = url;
+    }
+  };
+  sock.onclose = () => {
+    if (busy) { document.title = 'Busy'; overlay('Too many visitors right now - click to try again'); }
+    else if (opened) { document.title = 'Session ended'; overlay('Session ended - click to start a new one'); }
+    else setTimeout(connect, 1000);                   // server not up yet: keep trying
+  };
+}
+connect();
+
+function coords(e) {
+  const r = img.getBoundingClientRect();
+  const nw = img.naturalWidth || r.width, nh = img.naturalHeight || r.height;   // canvas size
+  return { x: Math.round((e.clientX - r.left) * nw / r.width),
+           y: Math.round((e.clientY - r.top) * nh / r.height) };
+}
+img.addEventListener('mousemove', e => send({type:'move', ...coords(e)}));
+img.addEventListener('mousedown', e => send({type:'mousedown', ...coords(e), button:e.button}));
+window.addEventListener('mouseup', e => send({type:'mouseup', ...coords(e), button:e.button}));
+img.addEventListener('contextmenu', e => e.preventDefault());
+img.addEventListener('wheel', e => { e.preventDefault(); send({type:'scroll', delta: e.deltaY > 0 ? 1 : -1}); }, {passive:false});
+window.addEventListener('keydown', e => {
+  if (["Space","ArrowUp","ArrowDown","ArrowLeft","ArrowRight","Tab"].includes(e.code)) e.preventDefault();
+  if (!e.repeat) send({type:'keydown', code:e.code, key:e.key});
+});
+window.addEventListener('keyup', e => send({type:'keyup', code:e.code, key:e.key}));
+</script>
+</body>
+</html>
+"""
+
+
+def _write_html():
+    # Always regenerate so template changes aren't ignored by a stale file.
+    html = HTML_TEMPLATE.replace("__PORT__", str(settings.port)).replace("__WSPATH__", WS_PATH)
+    with open("index.html", "w", encoding="utf-8") as f:
+        f.write(html)
+
+
+def start_server(game_class, width=800, height=600):
+    """CLASS mode: pass your website CLASS (not an instance). Each browser tab gets its own
+    private instance. (For a plain pygame loop, skip this and just use display.flip().)"""
+    pygame.init()
+
+    global _class_mode
+    _class_mode = True
+    _write_html()
+
+    async def handler(websocket):
+        global _current
+        print("Tab connected")
+        inp = TabInput((width, height))             # private canvas per tab
+        reader_task = None
+        try:
+            # The page reports its window size as soon as it connects. Wait for that so
+            # get_window_size() / set_mode((0,0)) already work inside your __init__.
+            try:
+                inp.feed(json.loads(await asyncio.wait_for(websocket.recv(), 2)))
+            except asyncio.TimeoutError:
+                pass
+
+            _current = inp                          # no await until update() finishes: safe
+            instance = game_class()
+
+            async def reader():
+                async for msg in websocket:
+                    try:
+                        inp.feed(json.loads(msg))
+                    except Exception as e:
+                        print("Bad input message:", e)
+
+            reader_task = asyncio.create_task(reader())
+            last = None
+            last_caption = None
+            last_url = None
+            while not reader_task.done():
+                t0 = time.perf_counter()
+
+                _current = inp
+                instance.update(inp.surface)        # always the tab's CURRENT surface
+
+                if inp.caption != last_caption:     # set_caption() -> browser tab title
+                    await websocket.send(json.dumps({"type": "title", "title": inp.caption}))
+                    last_caption = inp.caption
+
+                if inp.url is not None and inp.url != last_url:   # set_url() -> address bar
+                    await websocket.send(json.dumps({"type": "url", "url": inp.url}))
+                    last_url = inp.url
+
+                buf = io.BytesIO()
+                pygame.image.save(inp.surface, buf, "frame.jpg")
+                frame = buf.getvalue()
+                if frame != last:                   # don't resend identical frames
+                    await websocket.send(frame)
+                    last = frame
+
+                # non-blocking frame limiter (clock.tick() would freeze every tab)
+                await asyncio.sleep(max(0.0, 1 / settings.fps - (time.perf_counter() - t0)))
+        except websockets.exceptions.ConnectionClosed:
+            pass
+        except SystemExit:                          # the site called sys.exit(): close just this tab
+            pass
+        except Exception:
+            import traceback; traceback.print_exc()   # surface errors from user code
+        finally:
+            if reader_task:
+                reader_task.cancel()
+            print("Tab closed")
+
+    async def main():
+        async with _serve(handler):
+            # open the page only once the server is actually listening
+            _announce()
+            print("-> webpy running; open as many tabs as you like (Ctrl+C to stop)")
+            await asyncio.Future()
+
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

webpygame-1.0.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: webpygame
+Version: 1.0.0
+Summary: Stream Pygame windows directly to an HTML browser viewport.
+Author: Brodie
+License-Expression: MIT
+Keywords: pygame,website,browser,websocket
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame>=2.0.0
+Requires-Dist: websockets>=14.0
+Dynamic: license-file
+
+# webpy
+
+Make a website with plain pygame. `webpy` streams your pygame window to any browser tab.
+
+```
+pip install webpygame
+```
+
+```python
+import webpy
+
+screen = webpy.display.set_mode((800, 500))
+clicks = 0
+button = webpy.Rect(300, 220, 200, 60)
+
+while True:
+    for event in webpy.event.get():
+        if event.type == webpy.MOUSEBUTTONDOWN and button.collidepoint(event.pos):
+            clicks += 1
+    screen.fill((30, 34, 48))
+    webpy.draw.rect(screen, (90, 94, 235), button, border_radius=12)
+    webpy.display.flip()      # sends the frame to the browser
+```
+
+Run it, and your browser opens. Every browser tab gets its own copy of your site.
+
+* `webpy.display.url()`: the address for other computers on your network
+* `webpy.display.public()`: a public link that works from anywhere (uses Cloudflare's free `cloudflared`)
+* `webpy.display.set_url("/about")`: change the address bar
+* `webpy.settings`: change defaults (`public`, `share`, `separate_tabs`, `max_tabs`, `fps`, ...)
+
+Everything from pygame is available as `webpy.something` too.

webpygame-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+webpy/__init__.py,sha256=9wKjxMDV9WmtpeniwkYgxv9s7aCgpzYc6ydkW-QOmJE,365
+webpy/engine.py,sha256=upL1n8p4B9CihmZtsrNuF2eUTuLKKU31zUM1aJI6uxs,34097
+webpygame-1.0.0.dist-info/licenses/LICENSE,sha256=NQAtkcreb1gF8aut5NvFnyPHstT0Fr8XObwXw0TyGjk,1063
+webpygame-1.0.0.dist-info/METADATA,sha256=cep4t2galNNTpHAs7OfvqsRBD72FEsRu7r8schFjqFQ,1625
+webpygame-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+webpygame-1.0.0.dist-info/top_level.txt,sha256=XrauGW3ycRhXQxIFTJM_J3JaoK53vtAHDC3pgvKOuLY,6
+webpygame-1.0.0.dist-info/RECORD,,

webpygame-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

webpygame-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brodie
+
+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.

webpygame-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+webpy