pyglet 2.1.dev5__py3-none-any.whl → 2.1.dev7__py3-none-any.whl

pyglet/__init__.py

@@ -8,14 +8,14 @@ import os
 import sys
 from collections.abc import ItemsView, Sequence
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 if TYPE_CHECKING:
     from types import FrameType
     from typing import Any, Callable, ItemsView, Sized
 
 #: The release version
-version = '2.1.dev5'
+version = '2.1.dev7'
 __version__ = version
 
 MIN_PYTHON_VERSION = 3, 8
@@ -25,9 +25,6 @@ if sys.version_info < MIN_PYTHON_VERSION:
     msg = f"pyglet {version} requires Python {MIN_PYTHON_VERSION_STR} or newer."
     raise Exception(msg)
 
-if "sphinx" in sys.modules:
-    sys.is_pyglet_doc_run = True
-
 # pyglet platform treats *BSD systems as Linux
 compat_platform = sys.platform
 if "bsd" in compat_platform:
@@ -48,6 +45,7 @@ _OPTION_TYPE_VALIDATORS = {
     "int": lambda x: isinstance(x, int),
 }
 
+
 @dataclass
 class Options:
     """Dataclass for global pyglet options."""
@@ -249,16 +247,29 @@ class Options:
 
     .. versionadded:: 2.0.5"""
 
-    scale_with_dpi: bool = False
-    """For 'HiDPI' ('Retina') displays, scale Window creation size with desktop scaling. Defaults to ``False``. 
-        
-    For high pixel density displays, it is common for the desktop to have some form of application window scaling.
-    Setting this option to ``True`` will make pyglet aware of these settings when Windows are created. For instance,
-    if the desktop scaling factor is set to 150%, a Window created with a resolution of 1000x1000 will have an actual
-    framebuffer size of 1500x1500. Keep in mind that pyglet objects may not be scaled proportionately, so this is left
-    up to the developer. The :py:attr:`~pyglet.window.Window.scale` & :py:attr:`~pyglet.window.Window.dpi` attributes
-    can be queried as a reference when determining object creation. By default, windows are created with the actual
-    number of pixels requested.
+    dpi_scaling: Literal["real", "scaled", "stretch"] = "real"
+    """For 'HiDPI' displays, Window behavior can differ between operating systems. Defaults to `'real'`.
+
+    The current options are an attempt to create consistent behavior across all of the operating systems.
+
+    `'real'` (default): Provides a 1:1 pixel for Window frame size and framebuffer. Primarily used for game applications
+    to ensure you are getting the exact pixels for the resolution. If you provide an 800x600 window, you can ensure it
+    will be 800x600 pixels when the user chooses it.
+
+    `'scaled'`: Window size is scaled based on the DPI ratio. Window size and content (projection) size matches the full
+    framebuffer. Primarily used for any applications that wish to become DPI aware. You must rescale and reposition your
+    content to take advantage of the larger framebuffer. An 800x600 with a 150% DPI scaling would be changed to
+    1200x900 for both `window.get_size` and `window.get_framebuffer_size()`.
+
+    Keep in mind that pyglet objects may not be scaled proportionately, so this is left up to the developer.
+    The :py:attr:`~pyglet.window.Window.scale` & :py:attr:`~pyglet.window.Window.dpi` attributes can be queried as a
+    reference when determining object creation.
+
+    `'stretch'`:  Window is scaled based on the DPI ratio. However, content size matches original requested size of the
+    window, and is stretched to fit the full framebuffer. This mimics behavior of having no DPI scaling at all. No
+    rescaling and repositioning of content will be necessary, but at the cost of blurry content depending on the extent
+    of the stretch. For example, 800x600 at 150% DPI will be 800x600 for `window.get_size()` and 1200x900 for
+    `window.get_framebuffer_size()`.
     """
 
     shader_bind_management: bool = True
@@ -282,7 +293,7 @@ class Options:
 
     def __setitem__(self, key: str, value: Any) -> None:
         assert key in self.__annotations__, f"Invalid option name: '{key}'"
-        assert (_SPECIAL_OPTION_VALIDATORS.get(key, None) or _OPTION_TYPE_VALIDATORS[self.__annotations__[key]])(value), \
+        assert (_SPECIAL_OPTION_VALIDATORS.get(key) or _OPTION_TYPE_VALIDATORS[self.__annotations__[key]])(value), \
             f"Invalid type: '{type(value)}' for '{key}'"
         self.__dict__[key] = value
 
@@ -290,11 +301,16 @@ class Options:
 #: Instance of :py:class:`~pyglet.Options` used to set runtime options.
 options: Options = Options()
 
+_OPTION_TYPE_REMAPS = {
+    "audio": "sequence",
+    "vsync": "bool",
+}
 
 for _key, _type in options.__annotations__.items():
     """Check Environment Variables for pyglet options"""
     if _value := os.environ.get(f"PYGLET_{_key.upper()}"):
-        if _type == 'tuple':
+        _type = _OPTION_TYPE_REMAPS.get(_key, _type)
+        if _type == 'sequence':
             options[_key] = _value.split(",")
         elif _type == 'bool':
             options[_key] = _value in ("true", "TRUE", "True", "1")

pyglet/__init__.pyi

@@ -1,6 +1,6 @@
 
 from dataclasses import dataclass
-from typing import Sequence
+from typing import Any, ItemsView, Literal, Sequence
 
 from . import app as app
 from . import clock as clock
@@ -62,6 +62,20 @@ class Options:
     win32_disable_xinput: bool
     com_mta: bool
     osx_alt_loop: bool
+    dpi_scaling: Literal["real", "scaled", "stretch"]
+    scale_with_dpi: bool
     shader_bind_management: bool
 
+    def get(self, item: str, default: Any = None) -> Any:
+        ...
+
+    def items(self) -> ItemsView[str, Any]:
+        ...
+
+    def __getitem__(self, item: str) -> Any:
+        ...
+
+    def __setitem__(self, key: str, item: Any) -> None:
+        ...
+
 options: Options

pyglet/app/__init__.py

@@ -68,7 +68,7 @@ the set when they are no longer referenced or are closed explicitly.
 """
 
 
-def run(interval: None | float = 1/60) -> None:
+def run(interval: float | None = 1 / 60) -> None:
     """Begin processing events, scheduled functions and window updates.
 
     This is a convenience function, equivalent to::

pyglet/app/base.py

@@ -112,7 +112,7 @@ class EventLoop(event.EventDispatcher):
         for window in app.windows:
             window.draw(dt)
 
-    def run(self, interval: None | float = 1/60) -> None:
+    def run(self, interval: float | None = 1/60) -> None:
         """Begin processing events, scheduled functions and window updates.
 
         This method enters into the main event loop and, if the ``interval``

pyglet/app/cocoa.py

@@ -1,4 +1,6 @@
 import signal
+import time
+
 from pyglet import app
 from pyglet.app.base import PlatformEventLoop, EventLoop
 from pyglet.libs.darwin import cocoapy, AutoReleasePool, ObjCSubclass, PyObjectEncoding, ObjCInstance, send_super, \
@@ -11,7 +13,7 @@ NSDate = cocoapy.ObjCClass('NSDate')
 NSEvent = cocoapy.ObjCClass('NSEvent')
 NSUserDefaults = cocoapy.ObjCClass('NSUserDefaults')
 NSTimer = cocoapy.ObjCClass('NSTimer')
-
+NSRunningApplication = cocoapy.ObjCClass('NSRunningApplication')
 
 
 def add_menu_item(menu, title, action, key):
@@ -71,6 +73,34 @@ class _AppDelegate_Implementation:
     def applicationDidFinishLaunching_(self, notification):
         self._pyglet_loop._finished_launching = True
 
+        # Force App to activate to the foreground due to being an unbundled CLI program.
+        # This prevents an issue where if you move the mouse when launching the program, it's focus can be stolen
+        # by an app under/behind it leading to a weird state of input and the menu bar being greyed out until
+        # reactivating it.
+        NSApp = NSApplication.sharedApplication()
+
+        # Activate dock to ensure all other apps are deactivated.
+        dock_str = cocoapy.get_NSString("com.apple.dock")
+        running_apps = NSRunningApplication.runningApplicationsWithBundleIdentifier_(dock_str)
+        app_count = running_apps.count()
+        for i in range(app_count):
+            running_app = running_apps.objectAtIndex_(i)
+            running_app.activateWithOptions_(cocoapy.NSApplicationActivateIgnoringOtherApps)
+            break
+
+        # Doesn't seem to work unless we add a small sleep for some reason...
+        time.sleep(0.01)
+
+        NSApp.activateIgnoringOtherApps_(True)
+
+    @_AppDelegate.method('v@')
+    def applicationWillFinishLaunching_(self, notification):
+        pass
+
+    @_AppDelegate.method('B')
+    def applicationSupportsSecureRestorableState_(self):
+        return True
+
 _AppDelegate = ObjCClass('_AppDelegate')  # the actual class
 
 class CocoaAlternateEventLoop(EventLoop):
@@ -125,7 +155,9 @@ class CocoaAlternateEventLoop(EventLoop):
 class CocoaPlatformEventLoop(PlatformEventLoop):
 
     def __init__(self):
-        super(CocoaPlatformEventLoop, self).__init__()
+        super().__init__()
+        self._timer = None
+
         with AutoReleasePool():
             # Prepare the default application.
             self.NSApp = NSApplication.sharedApplication()
@@ -147,8 +179,23 @@ class CocoaPlatformEventLoop(PlatformEventLoop):
             if not defaults.objectForKey_(holdEnabled):
                 defaults.setBool_forKey_(False, holdEnabled)
 
+            self.appdelegate = _AppDelegate.alloc().init(self)
+            self.NSApp.setDelegate_(self.appdelegate)
+
             self._finished_launching = False
 
+        def term_received(*args):
+            if self._timer:
+                self._timer.invalidate()
+                self._timer = None
+
+            if self.NSApp:
+                self.NSApp.terminate_(None)
+
+        # Force NSApp to close if Python receives sig events.
+        signal.signal(signal.SIGINT, term_received)
+        signal.signal(signal.SIGTERM, term_received)
+
     def start(self):
         with AutoReleasePool():
             if not self.NSApp.isRunning() and not self._finished_launching:
@@ -163,38 +210,31 @@ class CocoaPlatformEventLoop(PlatformEventLoop):
         from pyglet.app import event_loop
         self._event_loop = event_loop
 
-        def term_received(*args):
-            if self.timer:
-                self.timer.invalidate()
-                self.timer = None
+        assert self._timer is None
 
-            self.nsapp_stop()
-
-        # Force NSApp to close if Python receives sig events.
-        signal.signal(signal.SIGINT, term_received)
-        signal.signal(signal.SIGTERM, term_received)
-
-        self.appdelegate = _AppDelegate.alloc().init(self)
-        self.NSApp.setDelegate_(self.appdelegate)
-
-        self.timer = NSTimer.scheduledTimerWithTimeInterval_target_selector_userInfo_repeats_(
-             interval,  # Clamped internally to 0.0001 (including 0)
-             self.appdelegate,
-             get_selector('updatePyglet:'),
-             False,
-             True
-         )
+        self._timer = NSTimer.scheduledTimerWithTimeInterval_target_selector_userInfo_repeats_(
+            interval,  # Clamped internally to 0.0001 (including 0)
+            self.appdelegate,
+            get_selector('updatePyglet:'),
+            False,
+            True
+        )
 
         self.NSApp.run()
 
     def nsapp_step(self):
         """Used only for CocoaAlternateEventLoop"""
         self._event_loop.idle()
-        self.dispatch_posted_events()
+        with AutoReleasePool():
+            self.dispatch_posted_events()
 
     def nsapp_stop(self):
         """Used only for CocoaAlternateEventLoop"""
-        self.NSApp.terminate_(None)
+        self.NSApp.stop_(None)
+
+        if self._timer:
+            self._timer.invalidate()
+            self._timer = None
 
     def step(self, timeout=None):
         with AutoReleasePool():
@@ -206,7 +246,7 @@ class CocoaPlatformEventLoop(PlatformEventLoop):
                 # will wait until the next event comes along.
                 timeout_date = NSDate.distantFuture()
             elif timeout == 0.0:
-                timeout_date = NSDate.distantPast()
+                timeout_date = None
             else:
                 timeout_date = NSDate.dateWithTimeIntervalSinceNow_(timeout)
 

pyglet/customtypes.py

@@ -14,7 +14,7 @@ else:
 HorizontalAlign = Literal["left", "center", "right"]
 AnchorX = Literal["left", "center", "right"]
 AnchorY = Literal["top", "bottom", "center", "baseline"]
-ContentVAlign = Literal["left", "center", "top"]
+ContentVAlign = Literal["bottom", "center", "top"]
 
 
 

pyglet/display/__init__.py

@@ -44,10 +44,13 @@ else:
         from pyglet.display.win32 import Win32Display as Display
         from pyglet.display.win32 import Win32Screen as Screen
         from pyglet.display.win32 import Win32Canvas as Canvas
-    else:
+    elif compat_platform == 'linux':
         from pyglet.display.xlib import XlibDisplay as Display
         from pyglet.display.xlib import XlibScreen as Screen
         from pyglet.display.xlib import XlibCanvas as Canvas
+    else:
+        msg = f"A display interface for '{compat_platform}' is not yet implemented."
+        raise NotImplementedError(msg)
 
 
 _displays: weakref.WeakSet = weakref.WeakSet()
@@ -73,4 +76,5 @@ def get_display() -> Display:
     # Otherwise, create a new display and return it.
     return Display()
 
+
 __all__ = ['Display', 'Screen', 'Canvas', 'ScreenMode', 'get_display']

pyglet/display/__init__.pyi

@@ -0,0 +1,4 @@
+from .base import Display
+
+def get_display() -> Display:
+    ...

pyglet/event.py

@@ -120,23 +120,19 @@ from __future__ import annotations
 
 import inspect
 import os.path
-
 from functools import partial
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal, Union
 from weakref import WeakMethod
 
 if TYPE_CHECKING:
-    import sys
     from typing import Any, Callable, Generator
-    if sys.version_info >= (3, 11):
-        from typing import Self
-    else:
-        Self = Any
 
 
 EVENT_HANDLED = True
 EVENT_UNHANDLED = None
 
+EVENT_HANDLE_STATE = Union[Literal[True], None]
+
 
 class EventException(Exception):  # noqa: N818
     """An exception raised when an event handler could not be attached."""
@@ -152,7 +148,7 @@ class EventDispatcher:
     _event_stack: tuple | list = ()
 
     @classmethod
-    def register_event_type(cls: type[Self], name: str) -> str:
+    def register_event_type(cls: type[object], name: str) -> str:
         """Register an event type with the dispatcher.
 
         Before dispatching events, they must first be registered by name.
@@ -161,8 +157,8 @@ class EventDispatcher:
         for suitable handlers.
         """
         if not hasattr(cls, 'event_types'):
-            cls.event_types = []
-        cls.event_types.append(name)
+            cls.event_types = []  # type: ignore reportAttributeAccessIssue
+        cls.event_types.append(name)  # type: ignore reportAttributeAccessIssue
         return name
 
     def push_handlers(self, *args: Any, **kwargs: Any) -> None:
@@ -181,15 +177,15 @@ class EventDispatcher:
             self._event_stack = []
 
         # Place dict full of new handlers at beginning of stack
-        self._event_stack.insert(0, {})
+        self._event_stack.insert(0, {})  # type: ignore reportAttributeAccessIssue
         self.set_handlers(*args, **kwargs)
 
-    def _get_handlers(self, args: list, kwargs: dict) -> Generator[str, Callable]:
+    def _get_handlers(self, args: list, kwargs: dict) -> Generator[tuple[str, Callable], None, None]:
         """Implement handler matching on arguments for set_handlers and remove_handlers."""
         for obj in args:
             if inspect.isroutine(obj):
                 # Single magically named function
-                name = obj.__name__
+                name: str = obj.__name__
                 if name not in self.event_types:
                     msg = f'Unknown event "{name}"'
                     raise EventException(msg)
@@ -438,10 +434,10 @@ class EventDispatcher:
     def _dump_handlers(self) -> None:
 
         for level, handlers in enumerate(self._event_stack):
-            print(f"level: {level}") 
+            print(f"level: {level}")
 
             for event_type, handler in handlers.items():
-                print(f" - '{event_type}': {handler}") 
+                print(f" - '{event_type}': {handler}")
 
     # Decorator
 

pyglet/experimental/geoshader_sprite.py

@@ -1,12 +1,10 @@
+from __future__ import annotations
+
 import sys
 
 import pyglet
-
+from pyglet import clock, event, graphics, image
 from pyglet.gl import *
-from pyglet import clock
-from pyglet import event
-from pyglet import graphics
-from pyglet import image
 
 _is_pyglet_doc_run = hasattr(sys, "is_pyglet_doc_run") and sys.is_pyglet_doc_run
 
@@ -209,7 +207,7 @@ class SpriteGroup(graphics.Group):
         self.program.stop()
 
     def __repr__(self):
-        return "{0}({1})".format(self.__class__.__name__, self.texture)
+        return f"{self.__class__.__name__}({self.texture})"
 
     def __eq__(self, other):
         return (other.__class__ is self.__class__ and
@@ -328,8 +326,14 @@ class Sprite(event.EventDispatcher):
                                        self._group.blend_dest,
                                        program,
                                        self._user_group)
-        self._batch.migrate(self._vertex_list, GL_POINTS, self._group, self._batch)
-        self._program = program
+        if (self._batch and
+                self._batch.update_shader(self._vertex_list, GL_POINTS, self._group, program)):
+            # Exit early if changing domain is not needed.
+            return
+
+        # Recreate vertex list.
+        self._vertex_list.delete()
+        self._create_vertex_list()
 
     def delete(self):
         """Force immediate removal of the sprite from video memory.
@@ -596,7 +600,6 @@ class Sprite(event.EventDispatcher):
             `scale_y` : float
                 Vertical scaling factor.
         """
-
         translations_outdated = False
 
         # only bother updating if the translation actually changed

pyglet/experimental/jobs.py

@@ -0,0 +1,124 @@
+"""Experimental multithreaded Job system.
+
+This module provides the `JobExecutor` class, which allows submitting
+batches of highly parallizable work in the form of functions and arguments.
+This is commonly known as "task-based multithreading" or a "multithreaded
+job system".
+
+..note:: This module is only really useful with the recent Python 3.13
+         releases that are built with experimental free-threading support.
+         With typical Python releases that contain a GIL, this is not of
+         much practical use.
+"""
+
+from __future__ import annotations
+
+import os
+
+from queue import Queue
+from threading import Event, Thread
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Callable, Any
+
+
+class _Worker(Thread):
+    """A worker thread to pop and run jobs."""
+    def __init__(self, workqueue: Queue, exitevent: Event, name: str) -> None:
+        super().__init__(name=name, daemon=True)
+        self.queue = workqueue
+        self.exit = exitevent
+        self.start()
+
+    def run(self) -> None:
+        """Parallel thread of execution."""
+        _exit = self.exit
+        _queue = self.queue
+        while not _exit.is_set():
+            func, args = _queue.get()
+            func(*args)
+            _queue.task_done()
+
+    def __repr__(self) -> str:
+        return f"{self.name}(id={self.native_id})"
+
+
+class JobExecutor:
+    """A light-weight multithreaded job system.
+
+    A JobExecutor loosely mimics the design of the Executor classes from the
+    `concurrent.futures` module, but does not share any code with those classes.
+    Instead, it is a more light-weight implementation intended for execution of
+    highly parallizable functions (jobs). A key difference is that JobExecutor
+    does not return `Futures`, and instead depends on the submitted jobs to
+    self-contained.
+    """
+
+    def __init__(self, max_workers: int | None = None) -> None:
+        """Create an instance of a JobExecutor.
+
+        Args:
+            max_workers: The number of threads to use. If `None`, will
+                         create half as many threads as reported CPU cores.
+        """
+        self._max_workers = max_workers or os.cpu_count() // 2
+        self._exitevent = Event()
+        self._queue = Queue()
+        self._threads = [_Worker(self._queue, self._exitevent, f"Thread{i+1}") for i in range(self._max_workers)]
+
+    def submit(self, func: Callable, *args: Any) -> None:
+        """Submit a job to be executed on .
+
+        A "job" consists of a function to be called, alone with any arguments
+        that should be passed to it. Jobs are automatically executed by the next
+        free worker thread. No values are returned when jobs are submitted,
+        and the functions should also not return any values; return values are
+        lost.
+
+        Args:
+            func: A function to execute.
+            *args: Any arguments to pass to the function.
+        """
+        try:
+            self._queue.put((func, args))
+        except AttributeError:
+            raise RuntimeError("cannot submit new tasks after shutdown")
+
+    def shutdown(self) -> None:
+        """Shut down the JobExecutor, terminating all worker threads.
+
+        All JobExecutor workers are Daemon Threads, so it is not strictly
+        necessary to call shutdown() at program termination. However, if
+        it is no longer needed, shutdown() can be called ot free up the
+        thread resources.
+        """
+        if not self._queue:
+            return
+        self._exitevent.set()
+        for _ in range(self._max_workers):
+            self.submit(lambda: None)
+        self._threads.clear()
+        self._exitevent = None
+        self._queue = None
+
+    def sync(self) -> None:
+        """Wait for all currently submitted jobs to complete.
+
+        This method will wait until the internal queue is empty, AND all
+        currently submitted jobs have completed execution. It can be used
+        to fence between separate batches of jobs that should not be run
+        at the same time. For example::
+
+            for chunk in worklist:
+                executor.submit(some_function, chunk)
+
+            executor.sync()
+
+            window.draw()
+
+        """
+        self._queue.join()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(workers={self._threads})"