pyglet 3.0.dev7__py3-none-any.whl → 3.0.dev9__py3-none-any.whl

pyglet/__init__.py

@@ -18,12 +18,15 @@ if TYPE_CHECKING:
     from typing import Any, Callable, ItemsView, Sized
 
 #: The release version
-version = '3.0.dev7'
+version = '3.0.dev9'
 __version__ = version
 
 MIN_PYTHON_VERSION = 3, 10
 MIN_PYTHON_VERSION_STR = ".".join([str(v) for v in MIN_PYTHON_VERSION])
 
+#: The Pyodide release used to develop and test pyglet's browser support.
+PYODIDE_VERSION = "0.29.4"
+
 if sys.version_info < MIN_PYTHON_VERSION:
     msg = f"pyglet {version} requires Python {MIN_PYTHON_VERSION_STR} or newer."
     raise Exception(msg)
@@ -56,7 +59,6 @@ class PyodideOptions:
     page, and do not want to alter your code, then modify this option.
     """
 
-
 @dataclass
 class Options:
     """Dataclass for global pyglet options."""
@@ -208,25 +210,30 @@ class Options:
     .. versionadded:: 2.0
     """
 
-    dw_legacy_naming: bool = False
-    """If ``True``, will enable legacy naming support for the default Windows font renderer (``DirectWrite``).
-    Attempt to parse fonts by the passed name, to best match legacy RBIZ naming.
+    font_name_compatibility: bool = False
+    """If ``True``, pyglet performs additional compatibility lookup for font names.
 
-    :see: https://learn.microsoft.com/en-us/windows/win32/directwrite/font-selection#rbiz-font-family-model
+    The portable spelling of a font is its family name with explicit ``weight``, ``style``, and ``stretch``. This
+    option additionally accepts OpenType full names and platform compatibility aliases where the backend supports
+    them. For example, it allows ``"Arial Narrow"`` rather than ``"Arial"`` with a ``"condensed"`` stretch, or
+    ``"Arial Black"`` instead of ``"Arial"`` with a weight of ``"black"``.
 
-    For example, this allows specifying ``"Arial Narrow"`` rather than ``"Arial"`` with a ``"condensed"`` stretch or
-    ``"Arial Black"`` instead of ``"Arial"`` with a weight of ``black``. This may enhance naming compatibility
-    cross-platform for select fonts as older font renderers went by this naming scheme.
+    This option does not reject full names when disabled: a platform font API may still accept them natively. It only
+    enables pyglet's extra compatibility lookup and mapping, which can improve cross-platform behavior at the cost of
+    slower font resolution.
 
-    Starts by parsing the string for any known style names, and searches all font collections for a matching RBIZ name.
-    If a perfect match is not found, it will choose a second best match.
+    On Windows with DirectWrite, GDI/RBIZ aliases are not indexed as family names. Resolving one requires enumerating
+    installed font families and faces, and can be noticeably slow on systems with many installed fonts. Results are
+    cached until a custom font is added.
+
+    :see: https://learn.microsoft.com/en-us/windows/win32/directwrite/font-selection#rbiz-font-family-model
 
     .. note:: Due to the high variation of styles and limited capability of some fonts, there is no guarantee the
-       second closest match will be exactly what the user wants.
+       selected face will be exactly what the user wants.
 
     .. note:: The ``debug_font`` option can provide information on what settings are being selected.
 
-    .. versionadded:: 2.0.3
+    .. versionadded:: 3.0
     """
 
     win32_disable_xinput: bool = False
@@ -502,6 +509,7 @@ if TYPE_CHECKING:
         resource,
         shapes,
         sprite,
+        storage,
         text,
         window,
     )
@@ -525,6 +533,7 @@ else:
     resource = _ModuleProxy("resource")  # type: ignore
     sprite = _ModuleProxy("sprite")  # type: ignore
     shapes = _ModuleProxy("shapes")  # type: ignore
+    storage = _ModuleProxy("storage")  # type: ignore
     text = _ModuleProxy("text")  # type: ignore
     window = _ModuleProxy("window")  # type: ignore
 

pyglet/__init__.pyi

@@ -64,7 +64,7 @@ class Options:
     headless: bool
     headless_device: int
     text_shaping: Literal["platform", "harfbuzz", False]
-    dw_legacy_naming: bool
+    font_name_compatibility: bool
     win32_disable_xinput: bool
     com_mta: bool
     osx_alt_loop: bool

pyglet/app/__init__.py

@@ -80,11 +80,7 @@ def run(interval: float | None = 1 / 60) -> None:
         pyglet.app.event_loop.run(interval)
 
     """
-    if pyglet.compat_platform == "emscripten":
-        import asyncio
-        asyncio.create_task(event_loop.run(interval))  # noqa: RUF006
-    else:
-        event_loop.run(interval)
+    event_loop.run(interval)
 
 
 def exit() -> None:
@@ -99,12 +95,7 @@ def exit() -> None:
         pyglet.app.event_loop.exit()
 
     """
-    if pyglet.compat_platform == "emscripten":
-        import asyncio
-
-        asyncio.create_task(event_loop.exit())
-    else:
-        event_loop.exit()
+    event_loop.exit()
 
 
 #: The global event loop. Applications can replace this

pyglet/app/async_app.py

@@ -1,39 +1,40 @@
+"""Asyncio event-loop support for the Emscripten platform."""
 from __future__ import annotations
 
 import asyncio
+from contextlib import suppress
 import sys
 from typing import Any, Callable, TYPE_CHECKING
 
 import pyglet
 from pyglet import app, clock, event
+from pyglet.app.base import ClockWindowDrawSource, WindowDrawSource
 
 if TYPE_CHECKING:
     from pyglet.event import EventDispatcher
     from pyglet.window import BaseWindow
 
-_is_pyglet_doc_run = hasattr(sys, "is_pyglet_doc_run") and sys.is_pyglet_doc_run
 try:
-    from js import requestAnimationFrame, performance  # noqa: F821
-    from pyodide.ffi import create_proxy  # noqa: F821
-except ImportError:
-    raise ImportError('Pyodide not available.')
+    from js import cancelAnimationFrame, requestAnimationFrame, performance
+except ImportError as exc:
+    raise ImportError('Pyodide not available.') from exc
+
+from pyglet.libs.emscripten.proxies import ProxyRegistry
 
 
 class AsyncEventLoop(event.EventDispatcher):
-    """Asyncio-based event loop for Pyglet."""
+    """Browser event loop which preserves pyglet's normal clock semantics."""
 
     def __init__(self) -> None:
+        """Create the browser clock and callback state."""
         self._has_exit_event = asyncio.Event()
-        # Change the default clock to use the javascript performance timer.
         self.clock = clock.Clock(self._get_js_time)
         pyglet.clock.set_default(self.clock)
         self.is_running = False
-        self._interval = None
-        self._last_ts = 0.0
-        self._frame_dt = 0.0
-
-        self._frame_future = None
-        self._frame_proxy = create_proxy(self._frame_cb)
+        self._interval: float | None = None
+        self._run_task: asyncio.Task[None] | None = None
+        self._window_draw_source: WindowDrawSource | None = None
+        self._window_draw_exception: tuple[type[BaseException], BaseException, Any] | None = None
 
     def _get_js_time(self) -> float:
         """Use Javascripts performance.now for the clock accuracy.
@@ -42,171 +43,245 @@ class AsyncEventLoop(event.EventDispatcher):
         """
         return performance.now() / 1000
 
-    @staticmethod
-    def _redraw_windows(dt: float) -> None:
-        # Redraw all windows
-        for window in app.windows:
+    def _redraw_windows(self, dt: float) -> None:
+        for window in tuple(app.windows):
+            self._dispatch_platform_draw(window, dt)
+
+    def _dispatch_platform_draw(self, window: BaseWindow, dt: float) -> None:
+        try:
             window.draw(dt)
+        except BaseException:  # noqa: BLE001 - JS callbacks cannot unwind Python exceptions.
+            self._window_draw_exception = sys.exc_info()
+            self.exit()
 
-    def _frame_cb(self, ts: float) -> None:
-        """Callback for the requestAnimationFrame."""
-        now = ts / 1000.0
-        _frame_dt = now - self._last_ts
+    def _raise_window_draw_exception(self) -> None:
+        if self._window_draw_exception is None:
+            return
 
-        self._last_ts = now
+        _, exception, traceback = self._window_draw_exception
+        self._window_draw_exception = None
+        raise exception.with_traceback(traceback)
 
-        if self._frame_future:
-            self._frame_future.set_result(_frame_dt)
-            self._frame_future = None
+    def _schedule_window_draw(self, interval: float | None) -> None:
+        self._interval = interval
+        if interval is None:
+            return
 
-    async def _next_animation_frame(self) -> float:
-        self._frame_future = asyncio.Future()
-        requestAnimationFrame(self._frame_proxy)
-        return await self._frame_future
+        draw_source = app.platform_event_loop.create_window_draw_source(self)
+        if draw_source is None:
+            draw_source = ClockWindowDrawSource(self.clock, self._redraw_windows)
 
-    async def draw_frame(self) -> None:
-        frame_dt = await self._next_animation_frame()
-        self._redraw_windows(frame_dt)
+        self._window_draw_source = draw_source
+        if not draw_source.start(interval):
+            draw_source.stop()
+            self._window_draw_source = ClockWindowDrawSource(self.clock, self._redraw_windows)
+            self._window_draw_source.start(interval)
 
-    async def run(self, interval: float | None = 1/60) -> None:
-        try:
-            """Begin processing events asynchronously."""
-            self._interval = interval
+    def _unschedule_window_draw(self) -> None:
+        if self._window_draw_source is not None:
+            self._window_draw_source.stop()
+            self._window_draw_source = None
 
-            self._has_exit_event.clear()
-            platform_event_loop = app.platform_event_loop
+    def run(self, interval: float | None = 1 / 60) -> None:
+        """Start processing browser events, scheduled functions, and window draws."""
+        if self._run_task is not None and not self._run_task.done():
+            raise RuntimeError("The pyglet event loop is already running.")
 
-            await platform_event_loop.start()
-            self.dispatch_event('on_enter')
-            self.is_running = True
+        task = asyncio.create_task(self._run(interval))
+        self._run_task = task
 
-            # Use the browser's requestAnimationFrame for the loop if None is used.
-            if self._interval is None:
-                while not self._has_exit_event.is_set():
-                    await self.draw_frame()
-                    self.idle()  # Ticks clock and runs scheduled functions.
-                    await platform_event_loop.dispatch_posted_events()
-            else:
-                _schedule_rate = self._interval / 1000.0
+        def clear_task(completed_task: asyncio.Task[None]) -> None:
+            if self._run_task is completed_task:
+                self._run_task = None
 
-                # Separate draw loop so clock timeout doesn't block rendering if it's slower.
-                async def _draw_loop() -> None:
-                    while not self._has_exit_event.is_set():
-                        await self.draw_frame()
+        task.add_done_callback(clear_task)
 
-                asyncio.create_task(_draw_loop())  # noqa: RUF006
+    async def _run(self, interval: float | None = 1 / 60) -> None:
+        """Process pyglet clock callbacks and browser events."""
+        if self.is_running:
+            raise RuntimeError("The pyglet event loop is already running.")
 
-                while not self._has_exit_event.is_set():
-                    timeout = self.idle()
-                    await platform_event_loop.dispatch_posted_events()
-                    await asyncio.sleep(0 if timeout is None else timeout)
+        self._interval = interval
+        self._has_exit_event.clear()
+        platform_event_loop = app.platform_event_loop
 
+        try:
+            platform_event_loop.start()
+            self._schedule_window_draw(interval)
+            self.dispatch_event('on_enter')
+            self.is_running = True
+
+            while not self._has_exit_event.is_set():
+                timeout = self.idle()
+                await platform_event_loop.wait(timeout)
+                platform_event_loop.dispatch_posted_events()
+        finally:
             self.is_running = False
+            platform_event_loop.stop()
+            self._unschedule_window_draw()
             self.dispatch_event('on_exit')
-            await platform_event_loop.stop()
-        except Exception as err:
-            import traceback
-            print("Error in wrapped task", err)
-            traceback.print_exc()
-
-    async def enter_blocking(self) -> None:
-        """Ensure `idle()` continues to be called during blocking operations."""
+
+        self._raise_window_draw_exception()
+
+    def enter_blocking(self) -> None:
         timeout = self.idle()
-        await app.platform_event_loop.set_timer(self._blocking_timer, timeout)
+        app.platform_event_loop.set_timer(self._blocking_timer, timeout)
 
-    async def exit_blocking(self) -> None:
-        """Stop the blocking timer."""
-        await app.platform_event_loop.set_timer(None, None)
+    def exit_blocking(self) -> None:
+        app.platform_event_loop.set_timer(None, None)
 
-    async def _blocking_timer(self) -> None:
-        """Called to process scheduled events during blocking operations."""
+    def _blocking_timer(self) -> None:
         dt = self.clock.update_time()
         self.clock.call_scheduled_functions(dt)
-        if self._interval is None:
-            self._redraw_windows(dt)
-
         timeout = self.clock.get_sleep_time(True)
-        await app.platform_event_loop.set_timer(self._blocking_timer, timeout)
+        app.platform_event_loop.set_timer(self._blocking_timer, timeout)
 
     def idle(self) -> float | None:
-        """Called each iteration to process events."""
         dt = self.clock.update_time()
         self.clock.call_scheduled_functions(dt)
         return self.clock.get_sleep_time(True)
 
-    async def exit(self) -> None:
-        """Exit the event loop asynchronously."""
+    def exit(self) -> None:
         self._has_exit_event.set()
         app.platform_event_loop.notify()
 
     async def sleep(self, timeout: float) -> bool:
-        """Pause execution for a given time unless `exit()` is called."""
         try:
             await asyncio.wait_for(self._has_exit_event.wait(), timeout)
             return True
         except asyncio.TimeoutError:
             return False
 
-    async def on_window_close(self, _window: BaseWindow) -> None:
-        """Exit when the last window is closed."""
+    def on_window_close(self, _window: BaseWindow) -> None:
         if len(app.windows) == 0:
-            await self.exit()
+            self.exit()
+
 
 AsyncEventLoop.register_event_type('on_window_close')
 AsyncEventLoop.register_event_type('on_enter')
 AsyncEventLoop.register_event_type('on_exit')
 
+
 class AsyncPlatformEventLoop:
-    """An asyncio-based platform event loop."""
+    """An asyncio-based platform event loop, currently for supporting Pyodide."""
 
     def __init__(self) -> None:
-        """Initialize the event loop with an asyncio queue and event."""
-        self._event_queue = asyncio.Queue()
-        self._is_running = asyncio.Event()
+        """Create the browser event queue and wakeup state."""
+        self._event_queue: asyncio.Queue[tuple[EventDispatcher, str, tuple[Any, ...]]] = asyncio.Queue()
+        self._is_running = False
+        self._wake_event = asyncio.Event()
+        self._timer_task: asyncio.Task[None] | None = None
 
     def is_running(self) -> bool:
-        """Check if the event loop is currently processing."""
-        return self._is_running.is_set()
+        return self._is_running
 
-    async def post_event(self, dispatcher: EventDispatcher, event: str, *args: Any) -> None:
-        """Post an event into the main application thread asynchronously."""
-        await self._event_queue.put((dispatcher, event, args))
+    def post_event(self, dispatcher: EventDispatcher, event: str, *args: Any) -> None:
+        self._event_queue.put_nowait((dispatcher, event, args))
         self.notify()
 
-    async def dispatch_posted_events(self) -> None:
-        """Dispatch all pending events asynchronously."""
-        while not self._event_queue.empty():
+    def dispatch_posted_events(self) -> None:
+        while True:
             try:
-                dispatcher, evnt, args = await self._event_queue.get()
-                dispatcher.dispatch_event(evnt, *args)
-            except asyncio.CancelledError:
-                break
-            except ReferenceError:
-                # weakly-referenced object no longer exists
-                pass
+                dispatcher, event, args = self._event_queue.get_nowait()
+            except asyncio.QueueEmpty:
+                return
+            with suppress(ReferenceError):
+                dispatcher.dispatch_event(event, *args)
 
     def notify(self) -> None:
-        """Trigger an iteration of the asyncio event loop."""
-        if self.is_running():
-            asyncio.create_task(self.dispatch_posted_events())
+        self._wake_event.set()
+
+    def start(self) -> None:
+        self._is_running = True
+
+    async def wait(self, timeout: float | None) -> None:
+        if not self._event_queue.empty():
+            return
 
-    async def start(self) -> None:
-        """Start the asyncio-based event loop."""
-        self._is_running.set()
+        self._wake_event.clear()
+        if not self._event_queue.empty():
+            return
+
+        if timeout is None:
+            await self._wake_event.wait()
+        elif timeout > 0:
+            with suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(self._wake_event.wait(), timeout)
+        else:
+            await asyncio.sleep(0)
 
     async def step(self, timeout: float | None = None) -> None:
-        """Run one iteration of the asyncio event loop with a timeout."""
-        try:
-            await asyncio.wait_for(self.dispatch_posted_events(), timeout)
-        except asyncio.TimeoutError:
-            pass
+        await self.wait(timeout)
+        self.dispatch_posted_events()
+
+    def set_timer(self, func: Callable | None, interval: float | None) -> None:
+        if self._timer_task is not None:
+            self._timer_task.cancel()
+            self._timer_task = None
+
+        if func is None or interval is None or not self.is_running():
+            return
+
+        async def timer() -> None:
+            while self.is_running():
+                await asyncio.sleep(interval)
+                if self.is_running():
+                    func()
+
+        self._timer_task = asyncio.create_task(timer())
+
+    def create_window_draw_source(self, event_loop: AsyncEventLoop) -> WindowDrawSource:
+        return RequestAnimationFrameDrawSource(event_loop)
+
+    def stop(self) -> None:
+        self._is_running = False
+        self.set_timer(None, None)
+        self.notify()
 
-    async def set_timer(self, func: Callable, interval: float) -> None:
-        """Schedule a timer function asynchronously."""
-        while self.is_running():
-            await asyncio.sleep(interval)
-            func()
 
-    async def stop(self) -> None:
-        """Stop the asyncio-based event loop."""
-        self._is_running.clear()
+class RequestAnimationFrameDrawSource(WindowDrawSource):
+    """Draw browser windows when the browser requests an animation frame."""
+
+    def __init__(self, event_loop: AsyncEventLoop) -> None:
+        """Attaches to the browser event loop."""
+        self._event_loop = event_loop
+        self._last_timestamp: float | None = None
+        self._request_id: int | None = None
+        self._running = False
+        self._callback = None
+        self._proxies = ProxyRegistry()
+
+    def start(self, _interval: float) -> bool:
+        self._running = True
+        self._last_timestamp = None
+        if self._callback is None:
+            self._callback = self._proxies.create(self._on_animation_frame)
+        self._request_next_frame()
+        return True
+
+    def stop(self) -> None:
+        if not self._running:
+            return
+
+        self._running = False
+        if self._request_id is not None:
+            cancelAnimationFrame(self._request_id)
+            self._request_id = None
+        self._proxies.destroy()
+        self._callback = None
+
+    def _request_next_frame(self) -> None:
+        self._request_id = requestAnimationFrame(self._callback)
+
+    def _on_animation_frame(self, timestamp: float) -> None:
+        if not self._running:
+            return
+
+        now = timestamp / 1000.0
+        dt = 0.0 if self._last_timestamp is None else now - self._last_timestamp
+        self._last_timestamp = now
+        self._request_id = None
+        self._event_loop._redraw_windows(dt)  # noqa: SLF001
+
+        if self._running:
+            self._request_next_frame()