rendercanvas 2.2.0__tar.gz → 2.3.0__tar.gz

{rendercanvas-2.2.0 → rendercanvas-2.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: rendercanvas
-Version: 2.2.0
+Version: 2.3.0
 Summary: One canvas API, multiple backends
 Keywords: canvas,rendering,graphics,wgpu,qt,wx,glfw,jupyter
 Author: Almar Klein, Korijn van Golen
-Requires-Python: >= 3.9
+Requires-Python: >= 3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: sniffio
@@ -45,8 +45,7 @@ Provides-Extra: tests
 [![PyPI version](https://badge.fury.io/py/rendercanvas.svg)](https://badge.fury.io/py/rendercanvas)
 [![EffVer Versioning](https://img.shields.io/badge/version_scheme-EffVer-0097a7)](https://jacobtomlinson.dev/effver)
 
-
-# rendercanvas
+<h1 align="center"><img src="https://github.com/user-attachments/assets/74ddfc1e-03ae-4965-afe9-8697ec4614b5" height="128"><br>rendercanvas</h1>
 
 One canvas API, multiple backends 🚀
 

{rendercanvas-2.2.0 → rendercanvas-2.3.0}/README.md

@@ -3,8 +3,7 @@
 [![PyPI version](https://badge.fury.io/py/rendercanvas.svg)](https://badge.fury.io/py/rendercanvas)
 [![EffVer Versioning](https://img.shields.io/badge/version_scheme-EffVer-0097a7)](https://jacobtomlinson.dev/effver)
 
-
-# rendercanvas
+<h1 align="center"><img src="https://github.com/user-attachments/assets/74ddfc1e-03ae-4965-afe9-8697ec4614b5" height="128"><br>rendercanvas</h1>
 
 One canvas API, multiple backends 🚀
 

{rendercanvas-2.2.0 → rendercanvas-2.3.0}/pyproject.toml

@@ -17,7 +17,7 @@ keywords = [
     "glfw",
     "jupyter",
 ]
-requires-python = ">= 3.9"
+requires-python = ">= 3.10"
 dependencies = ["sniffio"]
 [project.optional-dependencies]
 # For users

{rendercanvas-2.2.0 → rendercanvas-2.3.0}/rendercanvas/__init__.py

@@ -6,8 +6,7 @@ RenderCanvas: one canvas API, multiple backends.
 
 from ._version import __version__, version_info
 from . import _coreutils
-from ._events import EventType
-from ._scheduler import UpdateMode
-from .base import BaseRenderCanvas, BaseLoop, CursorShape
+from ._enums import CursorShape, EventType, UpdateMode
+from .base import BaseRenderCanvas, BaseLoop
 
 __all__ = ["BaseLoop", "BaseRenderCanvas", "CursorShape", "EventType", "UpdateMode"]

{rendercanvas-2.2.0 → rendercanvas-2.3.0}/rendercanvas/_coreutils.py

@@ -5,7 +5,7 @@ Core utilities that are loaded into the root namespace or used internally.
 import os
 import re
 import sys
-import types
+import time
 import weakref
 import logging
 import ctypes.util
@@ -19,7 +19,7 @@ logger = logging.getLogger("rendercanvas")
 logger.setLevel(logging.WARNING)
 
 
-err_hashes = {}
+err_hashes = {}  # hash -> [short-message, count, next-time]
 
 _re_wgpu_ob = re.compile(r"`<[a-z|A-Z]+-\([0-9]+, [0-9]+, [a-z|A-Z]+\)>`")
 
@@ -42,22 +42,37 @@ def log_exception(kind):
     except Exception as err:
         # Store exc info for postmortem debugging
         exc_info = list(sys.exc_info())
-        exc_info[2] = exc_info[2].tb_next  # skip *this* function
+        exc_info[2] = exc_info[2].tb_next  # type: ignore | skip *this* function
         sys.last_type, sys.last_value, sys.last_traceback = exc_info
         # Show traceback, or a one-line summary
         msg = str(err)
         msgh = error_message_hash(msg)
         if msgh not in err_hashes:
+            # Prepare a short variant of the message for later use
+            short_msg = kind + ": " + msg.split("\n")[0].strip()
+            short_msg = short_msg if len(short_msg) <= 70 else short_msg[:69] + "…"
+            err_hashes[msgh] = [short_msg, 1, 0]
             # Provide the exception, so the default logger prints a stacktrace.
             # IDE's can get the exception from the root logger for PM debugging.
-            err_hashes[msgh] = 1
             logger.error(kind, exc_info=err)
         else:
             # We've seen this message before, return a one-liner instead.
-            err_hashes[msgh] = count = err_hashes[msgh] + 1
-            msg = kind + ": " + msg.split("\n")[0].strip()
-            msg = msg if len(msg) <= 70 else msg[:69] + "…"
-            logger.error(msg + f" ({count})")
+            short_count_tm = err_hashes[msgh]
+            short, count, tm = short_count_tm
+            short_count_tm[1] = count = count + 1
+            # Show the message now?
+            show_message = False
+            cur_time = time.perf_counter()
+            if count <= 5:
+                show_message = True
+            else:
+                if cur_time > tm:
+                    show_message = True
+            # Log the messages and schedule when to show it next.
+            # Next message is after 1-3 seconds (3 when count reaches 300).
+            if show_message:
+                short_count_tm[2] = cur_time + min(max(count / 100, 1), 3)
+                logger.error(f"{short} ({count})")
 
 
 # %% Weak bindings
@@ -78,78 +93,6 @@ def weakbind(method):
     return proxy
 
 
-# %% Enum
-
-# We implement a custom enum class that's much simpler than Python's enum.Enum,
-# and simply maps to strings or ints. The enums are classes, so IDE's provide
-# autocompletion, and documenting with Sphinx is easy. That does mean we need a
-# metaclass though.
-
-
-class EnumType(type):
-    """Metaclass for enums and flags."""
-
-    def __new__(cls, name, bases, dct):
-        # Collect and check fields
-        member_map = {}
-        for key, val in dct.items():
-            if not key.startswith("_"):
-                val = key if val is None else val
-                if not isinstance(val, (int, str)):
-                    raise TypeError("Enum fields must be str or int.")
-                member_map[key] = val
-        # Some field values may have been updated
-        dct.update(member_map)
-        # Create class
-        klass = super().__new__(cls, name, bases, dct)
-        # Attach some fields
-        klass.__fields__ = tuple(member_map)
-        klass.__members__ = types.MappingProxyType(member_map)  # enums.Enum compat
-        # Create bound methods
-        for name in ["__dir__", "__iter__", "__getitem__", "__setattr__", "__repr__"]:
-            setattr(klass, name, types.MethodType(getattr(cls, name), klass))
-        return klass
-
-    def __dir__(cls):
-        # Support dir(enum). Note that this order matches the definition, but dir() makes it alphabetic.
-        return cls.__fields__
-
-    def __iter__(cls):
-        # Support list(enum), iterating over the enum, and doing ``x in enum``.
-        return iter([getattr(cls, key) for key in cls.__fields__])
-
-    def __getitem__(cls, key):
-        # Support enum[key]
-        return cls.__dict__[key]
-
-    def __repr__(cls):
-        if cls is BaseEnum:
-            return "<rendercanvas.BaseEnum>"
-        pkg = cls.__module__.split(".")[0]
-        name = cls.__name__
-        options = []
-        for key in cls.__fields__:
-            val = cls[key]
-            options.append(f"'{key}' ({val})" if isinstance(val, int) else f"'{val}'")
-        return f"<{pkg}.{name} enum with options: {', '.join(options)}>"
-
-    def __setattr__(cls, name, value):
-        if name.startswith("_"):
-            super().__setattr__(name, value)
-        else:
-            raise RuntimeError("Cannot set values on an enum.")
-
-
-class BaseEnum(metaclass=EnumType):
-    """Base class for flags and enums.
-
-    Looks like Python's builtin Enum class, but is simpler; fields are simply ints or strings.
-    """
-
-    def __init__(self):
-        raise RuntimeError("Cannot instantiate an enum.")
-
-
 # %% lib support
 
 

rendercanvas-2.3.0/rendercanvas/_enums.py

@@ -0,0 +1,176 @@
+import types
+from typing import Literal
+
+# ----- Base enum class
+
+# We implement a custom enum class that's much simpler than Python's enum.Enum,
+# and simply maps to strings or ints. The enums are classes, so IDE's provide
+# autocompletion, and documenting with Sphinx is easy. That does mean we need a
+# metaclass though.
+
+
+class EnumType(type):
+    """Metaclass for enums and flags."""
+
+    def __new__(cls, name, bases, dct):
+        # Collect and check fields
+        member_map = {}
+        for key, val in dct.items():
+            if not key.startswith("_"):
+                val = key if val is None else val
+                if not isinstance(val, (int, str)):
+                    raise TypeError("Enum fields must be str or int.")
+                member_map[key] = val
+        # Some field values may have been updated
+        dct.update(member_map)
+        # Create class
+        klass = super().__new__(cls, name, bases, dct)
+        # Attach some fields
+        klass.__fields__ = tuple(member_map)
+        klass.__members__ = types.MappingProxyType(member_map)  # enums.Enum compat
+        # Create bound methods
+        for name in ["__dir__", "__iter__", "__getitem__", "__setattr__", "__repr__"]:
+            setattr(klass, name, types.MethodType(getattr(cls, name), klass))
+        return klass
+
+    def __dir__(cls):
+        # Support dir(enum). Note that this order matches the definition, but dir() makes it alphabetic.
+        return cls.__fields__
+
+    def __iter__(cls):
+        # Support list(enum), iterating over the enum, and doing ``x in enum``.
+        return iter([getattr(cls, key) for key in cls.__fields__])
+
+    def __getitem__(cls, key):
+        # Support enum[key]
+        return cls.__dict__[key]
+
+    def __repr__(cls):
+        if cls is BaseEnum:
+            return "<rendercanvas.BaseEnum>"
+        pkg = cls.__module__.split(".")[0]
+        name = cls.__name__
+        options = []
+        for key in cls.__fields__:
+            val = cls[key]
+            options.append(f"'{key}' ({val})" if isinstance(val, int) else f"'{val}'")
+        return f"<{pkg}.{name} enum with options: {', '.join(options)}>"
+
+    def __setattr__(cls, name, value):
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+        else:
+            raise RuntimeError("Cannot set values on an enum.")
+
+
+class BaseEnum(metaclass=EnumType):
+    """Base class for flags and enums.
+
+    Looks like Python's builtin Enum class, but is simpler; fields are simply ints or strings.
+    """
+
+    def __init__(self):
+        raise RuntimeError("Cannot instantiate an enum.")
+
+
+# ----- The enums
+
+# The Xxxx(BaseEnum) classes are for Sphynx docs, and maybe discovery in interactive sessions.
+# The XxxxEnum Literals are for type checking, and static autocompletion of string args in funcs that accept an enum.
+
+
+CursorShapeEnum = Literal[
+    "default",
+    "text",
+    "crosshair",
+    "pointer",
+    "ew_resize",
+    "ns_resize",
+    "nesw_resize",
+    "nwse_resize",
+    "not_allowed",
+    "none",
+]
+
+
+class CursorShape(BaseEnum):
+    """The CursorShape enum specifies the suppported cursor shapes, following CSS cursor names."""
+
+    default = None  #: The platform-dependent default cursor, typically an arrow.
+    text = None  #: The text input I-beam cursor shape.
+    crosshair = None  #:
+    pointer = None  #: The pointing hand cursor shape.
+    ew_resize = "ew-resize"  #: The horizontal resize/move arrow shape.
+    ns_resize = "ns-resize"  #: The vertical resize/move arrow shape.
+    nesw_resize = (
+        "nesw-resize"  #: The top-left to bottom-right diagonal resize/move arrow shape.
+    )
+    nwse_resize = (
+        "nwse-resize"  #: The top-right to bottom-left diagonal resize/move arrow shape.
+    )
+    not_allowed = "not-allowed"  #: The operation-not-allowed shape.
+    none = "none"  #: The cursor is hidden.
+
+
+EventTypeEnum = Literal[
+    "*",
+    "resize",
+    "close",
+    "pointer_down",
+    "pointer_up",
+    "pointer_move",
+    "pointer_enter",
+    "pointer_leave",
+    "double_click",
+    "wheel",
+    "key_down",
+    "key_up",
+    "char",
+    "before_draw",
+    "animate",
+]
+
+
+class EventType(BaseEnum):
+    """The EventType enum specifies the possible events for a RenderCanvas.
+
+    This includes the events from the jupyter_rfb event spec (see
+    https://jupyter-rfb.readthedocs.io/en/stable/events.html) plus some
+    rendercanvas-specific events.
+    """
+
+    # Jupter_rfb spec
+
+    resize = None  #: The canvas has changed size. Has 'width' and 'height' in logical pixels, 'pixel_ratio'.
+    close = None  #: The canvas is closed. No additional fields.
+    pointer_down = None  #: The pointing device is pressed down. Has 'x', 'y', 'button', 'butons', 'modifiers', 'ntouches', 'touches'.
+    pointer_up = None  #: The pointing device is released. Same fields as pointer_down. Can occur outside of the canvas.
+    pointer_move = None  #: The pointing device is moved. Same fields as pointer_down. Can occur outside of the canvas if the pointer is currently down.
+    pointer_enter = None  #: The pointing device is moved into the canvas.
+    pointer_leave = None  #: The pointing device is moved outside of the canvas (regardless of a button currently being pressed).
+    double_click = None  #: A double-click / long-tap. This event looks like a pointer event, but without the touches.
+    wheel = None  #: The mouse-wheel is used (scrolling), or the touchpad/touchscreen is scrolled/pinched. Has 'dx', 'dy', 'x', 'y', 'modifiers'.
+    key_down = None  #: A key is pressed down. Has 'key', 'modifiers'.
+    key_up = None  #: A key is released. Has 'key', 'modifiers'.
+
+    # Pending for the spec, may become part of key_down/key_up
+    char = None  #: Experimental
+
+    # Our extra events
+
+    before_draw = (
+        None  #: Event emitted right before a draw is performed. Has no extra fields.
+    )
+    animate = None  #: Animation event. Has 'step' representing the step size in seconds. This is stable, except when the 'catch_up' field is nonzero.
+
+
+UpdateModeEnum = Literal["manual", "ondemand", "continuous", "fastest"]
+
+
+class UpdateMode(BaseEnum):
+    """The UpdateMode enum specifies the different modes to schedule draws for the canvas."""
+
+    manual = None  #: Draw events are never scheduled. Draws only happen when you ``canvas.force_draw()``, and maybe when the GUI system issues them (e.g. when resizing).
+    ondemand = None  #: Draws are only scheduled when ``canvas.request_draw()`` is called when an update is needed. Safes your laptop battery. Honours ``min_fps`` and ``max_fps``.
+    continuous = None  #: Continuously schedules draw events, honouring ``max_fps``. Calls to ``canvas.request_draw()`` have no effect.
+    fastest = None  #: Continuously schedules draw events as fast as possible. Gives high FPS (and drains your battery).

{rendercanvas-2.2.0 → rendercanvas-2.3.0}/rendercanvas/_events.py

@@ -5,41 +5,10 @@ The event system.
 import time
 from inspect import iscoroutinefunction
 from collections import defaultdict, deque
+from typing import Callable
 
-from ._coreutils import log_exception, BaseEnum
-
-
-class EventType(BaseEnum):
-    """The EventType enum specifies the possible events for a RenderCanvas.
-
-    This includes the events from the jupyter_rfb event spec (see
-    https://jupyter-rfb.readthedocs.io/en/stable/events.html) plus some
-    rendercanvas-specific events.
-    """
-
-    # Jupter_rfb spec
-
-    resize = None  #: The canvas has changed size. Has 'width' and 'height' in logical pixels, 'pixel_ratio'.
-    close = None  #: The canvas is closed. No additional fields.
-    pointer_down = None  #: The pointing device is pressed down. Has 'x', 'y', 'button', 'butons', 'modifiers', 'ntouches', 'touches'.
-    pointer_up = None  #: The pointing device is released. Same fields as pointer_down. Can occur outside of the canvas.
-    pointer_move = None  #: The pointing device is moved. Same fields as pointer_down. Can occur outside of the canvas if the pointer is currently down.
-    pointer_enter = None  #: The pointing device is moved into the canvas.
-    pointer_leave = None  #: The pointing device is moved outside of the canvas (regardless of a button currently being pressed).
-    double_click = None  #: A double-click / long-tap. This event looks like a pointer event, but without the touches.
-    wheel = None  #: The mouse-wheel is used (scrolling), or the touchpad/touchscreen is scrolled/pinched. Has 'dx', 'dy', 'x', 'y', 'modifiers'.
-    key_down = None  #: A key is pressed down. Has 'key', 'modifiers'.
-    key_up = None  #: A key is released. Has 'key', 'modifiers'.
-
-    # Pending for the spec, may become part of key_down/key_up
-    char = None  #: Experimental
-
-    # Our extra events
-
-    before_draw = (
-        None  #: Event emitted right before a draw is performed. Has no extra fields.
-    )
-    animate = None  #: Animation event. Has 'step' representing the step size in seconds. This is stable, except when the 'catch_up' field is nonzero.
+from ._coreutils import log_exception
+from ._enums import EventType
 
 
 valid_event_types = set(EventType)
@@ -76,14 +45,12 @@ class EventEmitter:
         self._pending_events.clear()
         self._event_handlers.clear()
 
-    def add_handler(self, *args, order: float = 0):
+    def add_handler(self, *args, order: float = 0) -> Callable:
         """Register an event handler to receive events.
 
         Arguments:
-            callback (callable): The event handler. Must accept a single event argument.
-                Can be a plain function or a coroutine function.
-                If you use async callbacks, see :ref:`async` for the limitations.
-            *types (list of strings): A list of event types.
+            callback (callable, optional): The event handler. Must accept a single event argument.
+            *types (list of EventType): A list of event types.
             order (float): Set callback priority order. Callbacks with lower priorities
                 are called first. Default is 0. When an event is emitted, callbacks with
                 the same priority are called in the order that they were added.
@@ -121,9 +88,11 @@ class EventEmitter:
 
         """
         order = float(order)
-        decorating = not callable(args[0])
-        callback = None if decorating else args[0]
-        types = args if decorating else args[1:]
+        callback = None
+        types = args
+        if len(args) > 0 and callable(args[0]):
+            callback = args[0]
+            types = args[1:]
 
         if not types:
             raise TypeError("No event types are given to add_event_handler.")
@@ -133,15 +102,19 @@ class EventEmitter:
             if not (type == "*" or type in valid_event_types):
                 raise ValueError(f"Adding handler with invalid event_type: '{type}'")
 
-        def decorator(_callback):
+        def decorator(_callback: Callable):
             self._add_handler(_callback, order, *types)
             return _callback
 
-        if decorating:
+        if callback is None:
             return decorator
         return decorator(callback)
 
     def _add_handler(self, callback, order, *types):
+        if iscoroutinefunction(callback):
+            raise TypeError(
+                "Coroutines cannot be callbacks (anymore). Instead, you can use a regular callback that calls `loop.add_task(coro)`."
+            )
         if self._closed:
             return
         self.remove_handler(callback, *types)
@@ -195,7 +168,7 @@ class EventEmitter:
 
         self._pending_events.append(event)
 
-    async def flush(self):
+    def flush(self):
         """Dispatch all pending events.
 
         This should generally be left to the scheduler.
@@ -205,9 +178,9 @@ class EventEmitter:
                 event = self._pending_events.popleft()
             except IndexError:
                 break
-            await self.emit(event)
+            self.emit(event)
 
-    async def emit(self, event):
+    def emit(self, event):
         """Directly emit the given event.
 
         In most cases events should be submitted, so that they are flushed
@@ -221,15 +194,12 @@ class EventEmitter:
             if event.get("stop_propagation", False):
                 break
             with log_exception(f"Error during handling {event_type} event"):
-                if iscoroutinefunction(callback):
-                    await callback(event)
-                else:
-                    callback(event)
+                callback(event)
         # Close?
         if event_type == "close":
             self._release()
 
-    async def close(self):
+    def close(self):
         """Close the event handler.
 
         Drops all pending events, send the close event, and disables the emitter.
@@ -238,4 +208,4 @@ class EventEmitter:
         if not self._closed:
             self._pending_events.clear()
             self.submit({"event_type": "close"})
-            await self.flush()
+            self.flush()

{rendercanvas-2.2.0 → rendercanvas-2.3.0}/rendercanvas/_loop.py

@@ -117,7 +117,7 @@ class BaseLoop:
                 closed_canvas_ids = set(event_emitters) - set(new_event_emitters)
                 for canvas_id in closed_canvas_ids:
                     events = event_emitters[canvas_id]
-                    await events.close()
+                    events.close()
 
                 # Keep canvases alive
                 for canvas in canvases:
@@ -139,9 +139,14 @@ class BaseLoop:
                     break
                 elif self.__should_stop:
                     # Close all remaining canvases. Loop will stop in a next iteration.
+                    # We store a flag on the canvas, that we only use here.
                     for canvas in self.get_canvases():
-                        if not getattr(canvas, "_rc_closed_by_loop", False):
-                            canvas._rc_closed_by_loop = True
+                        try:
+                            closed_by_loop = canvas._rc_closed_by_loop  # type: ignore
+                        except AttributeError:
+                            closed_by_loop = False
+                        if not closed_by_loop:
+                            canvas._rc_closed_by_loop = True  # type: ignore
                             canvas.close()
                         del canvas
 
@@ -372,7 +377,7 @@ class BaseLoop:
         This method is optional. A subclass must either implement ``_rc_add_task`` or ``_rc_call_later``.
 
         * If you implememt this, make ``_rc_add_task()`` call ``super()._rc_add_task()``.
-        * If delay is zero, this should behave like "call_later".
+        * If delay is zero, this should behave like "call_soon".
         * No need to catch errors from the callback; that's dealt with internally.
         * Return None.
         """