rendercanvas 1.0.0__py3-none-any.whl

rendercanvas/__init__.py

@@ -0,0 +1,17 @@
+"""
+RenderCanvas: one canvas API, multiple backends.
+"""
+
+# ruff: noqa: F401
+
+from ._version import __version__, version_info
+from . import _coreutils
+from ._events import EventType
+from .base import BaseRenderCanvas, BaseLoop, BaseTimer
+
+__all__ = [
+    "BaseRenderCanvas",
+    "EventType",
+    "BaseLoop",
+    "BaseTimer",
+]

rendercanvas/__pyinstaller/__init__.py

@@ -0,0 +1,12 @@
+from os.path import dirname
+
+
+HERE = dirname(__file__)
+
+
+def get_hook_dirs():
+    return [HERE]
+
+
+def get_test_dirs():
+    return [HERE]

rendercanvas/__pyinstaller/conftest.py

@@ -0,0 +1 @@
+from PyInstaller.utils.conftest import *  # noqa: F403

rendercanvas/__pyinstaller/hook-rendercanvas.py

@@ -0,0 +1,22 @@
+# ruff: noqa: N999
+
+from PyInstaller.utils.hooks import collect_dynamic_libs
+
+# Init variables that PyInstaller will pick up.
+hiddenimports = []
+datas = []
+binaries = []
+
+# Add modules that are safe to add, i.e. don't pull in dependencies that we don't want.
+hiddenimports += ["rendercanvas.offscreen"]
+
+# Since glfw does not have a hook like this, it does not include the glfw binary
+# when freezing. We can solve this with the code below. Makes the binary a bit
+# larger, but only marginally (less than 300kb).
+try:
+    import glfw  # noqa: F401
+except ImportError:
+    pass
+else:
+    hiddenimports += ["rendercanvas.glfw"]
+    binaries += collect_dynamic_libs("glfw")

rendercanvas/__pyinstaller/test_rendercanvas.py

@@ -0,0 +1,47 @@
+script = """
+# The script part
+import sys
+import importlib
+
+from rendercanvas.auto import RenderCanvas
+
+if "glfw" not in RenderCanvas.__name__.lower():
+    raise RuntimeError(f"Expected a glfw canvas, got {RenderCanvas.__name__}")
+
+# The test part
+if "is_test" in sys.argv:
+    included_modules = [
+        "rendercanvas.glfw",
+        "rendercanvas.offscreen",
+        "glfw",
+    ]
+    excluded_modules = [
+        "PySide6.QtGui",
+        "PyQt6.QtGui",
+    ]
+    for module_name in included_modules:
+        importlib.import_module(module_name)
+    for module_name in excluded_modules:
+        try:
+            importlib.import_module(module_name)
+        except ModuleNotFoundError:
+            continue
+        raise RuntimeError(module_name + " is not supposed to be importable.")
+"""
+
+
+def test_pyi_rendercanvas(pyi_builder):
+    pyi_builder.test_source(script, app_args=["is_test"])
+
+
+# We could also test the script below, but it's not that interesting since it uses direct imports.
+# To safe CI-time we don't actively test it.
+script_qt = """
+import sys
+import importlib
+
+import PySide6
+from rendercanvas.qt import RenderCanvas
+
+assert "qt" in RenderCanvas.__name__.lower()
+"""

rendercanvas/_context.py

@@ -0,0 +1,78 @@
+"""
+A stub context implementation for documentation purposes.
+It does actually work, but presents nothing.
+"""
+
+import weakref
+
+
+def rendercanvas_context_hook(canvas, present_methods):
+    """Hook function to allow ``rendercanvas`` to detect your context implementation.
+
+    If you make a function with this name available in the module ``your.module``,
+    ``rendercanvas`` will detect and call this function in order to obtain the canvas object.
+    That way, anyone can use ``canvas.get_context("your.module")`` to use your context.
+    The arguments are the same as for ``ContextInterface``.
+    """
+    return ContextInterface(canvas, present_methods)
+
+
+class ContextInterface:
+    """The interface that a context must implement, to be usable with a ``RenderCanvas``.
+
+    Arguments:
+        canvas (BaseRenderCanvas): the canvas to render to.
+        present_methods (dict): The supported present methods of the canvas.
+
+    The ``present_methods`` dict has a field for each supported present-method. A
+    canvas must support either "screen" or "bitmap". It may support both, as well as
+    additional (specialized) present methods. Below we list the common methods and
+    what fields the subdicts have.
+
+    * Render method "screen":
+        * "window": the native window id.
+        * "display": the native display id (Linux only).
+        * "platform": to determine between "x11" and "wayland" (Linux only).
+    * Render method "bitmap":
+        * "formats": a list of supported formats. It should always include "rgba-u8".
+          Other options can be be "i-u8" (intensity/grayscale), "i-f32", "bgra-u8", "rgba-u16", etc.
+
+    """
+
+    def __init__(self, canvas, present_methods):
+        self._canvas_ref = weakref.ref(canvas)
+        self._present_methods = present_methods
+
+    @property
+    def canvas(self):
+        """The associated canvas object. Internally, this should preferably be stored using a weakref."""
+        return self._canvas_ref()
+
+    def present(self):
+        """Present the result to the canvas.
+
+        This is called by the canvas, and should not be called by user-code.
+
+        The implementation should always return a present-result dict, which
+        should have at least a field 'method'. The value of 'method' must be
+        one of the methods that the canvas supports, i.e. it must be in ``present_methods``.
+
+        * If there is nothing to present, e.g. because nothing was rendered yet:
+            * return ``{"method": "skip"}`` (special case).
+        * If presentation could not be done for some reason:
+            * return ``{"method": "fail", "message": "xx"}`` (special case).
+        * If ``present_method`` is "screen":
+            * Render to screen using the info in ``present_methods['screen']``).
+            * Return ``{"method", "screen"}`` as confirmation.
+        * If ``present_method`` is "bitmap":
+            * Return ``{"method": "bitmap", "data": data, "format": format}``.
+            * 'data' is a memoryview, or something that can be converted to a memoryview, like a numpy array.
+            * 'format' is the format of the bitmap, must be in ``present_methods['bitmap']['formats']`` ("rgba-u8" is always supported).
+        * If ``present_method`` is something else:
+            * Return ``{"method": "xx", ...}``.
+            * It's the responsibility of the context to use a render method that is supported by the canvas,
+              and that the appropriate arguments are supplied.
+        """
+
+        # This is a stub
+        return {"method": "skip"}

rendercanvas/_coreutils.py

@@ -0,0 +1,264 @@
+"""
+Core utilities that are loaded into the root namespace or used internally.
+"""
+
+import os
+import re
+import sys
+import types
+import weakref
+import logging
+import ctypes.util
+from contextlib import contextmanager
+
+
+# %% Logging
+
+
+logger = logging.getLogger("rendercanvas")
+logger.setLevel(logging.WARNING)
+
+
+err_hashes = {}
+
+_re_wgpu_ob = re.compile(r"`<[a-z|A-Z]+-\([0-9]+, [0-9]+, [a-z|A-Z]+\)>`")
+
+
+def error_message_hash(message):
+    # Remove wgpu object representations, because they contain id's that may change at each draw.
+    # E.g. `<CommandBuffer- (12, 4, Metal)>`
+    message = _re_wgpu_ob.sub("WGPU_OBJECT", message)
+    return hash(message)
+
+
+@contextmanager
+def log_exception(kind):
+    """Context manager to log any exceptions, but only log a one-liner
+    for subsequent occurrences of the same error to avoid spamming by
+    repeating errors in e.g. a draw function or event callback.
+    """
+    try:
+        yield
+    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
+        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:
+            # 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})")
+
+
+# %% Weak bindings
+
+
+def weakbind(method):
+    """Replace a bound method with a callable object that stores the `self` using a weakref."""
+    ref = weakref.ref(method.__self__)
+    class_func = method.__func__
+    del method
+
+    def proxy(*args, **kwargs):
+        self = ref()
+        if self is not None:
+            return class_func(self, *args, **kwargs)
+
+    proxy.__name__ = class_func.__name__
+    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
+
+
+QT_MODULE_NAMES = ["PySide6", "PyQt6", "PySide2", "PyQt5"]
+
+
+def select_qt_lib():
+    """Select the qt lib to use, used by qt.py"""
+    # Check the override. This env var is meant for internal use only.
+    # Otherwise check imported libs.
+
+    libname = os.getenv("_RENDERCANVAS_QT_LIB")
+    if libname:
+        return libname, qt_lib_has_app(libname)
+    else:
+        return get_imported_qt_lib()
+
+
+def get_imported_qt_lib():
+    """Get the name of the currently imported qt lib.
+
+    Returns (name, has_application). The name is None when no qt lib is currently imported.
+    """
+
+    # Get all imported qt libs
+    imported_libs = []
+    for libname in QT_MODULE_NAMES:
+        qtlib = sys.modules.get(libname, None)
+        if qtlib is not None:
+            imported_libs.append(libname)
+
+    # Get which of these have an application object
+    imported_libs_with_app = [
+        libname for libname in imported_libs if qt_lib_has_app(libname)
+    ]
+
+    # Return findings
+    if imported_libs_with_app:
+        return imported_libs_with_app[0], True
+    elif imported_libs:
+        return imported_libs[0], False
+    else:
+        return None, False
+
+
+def qt_lib_has_app(libname):
+    QtWidgets = sys.modules.get(libname + ".QtWidgets", None)  # noqa: N806
+    if QtWidgets:
+        app = QtWidgets.QApplication.instance()
+        return app is not None
+
+
+def asyncio_is_running():
+    """Get whether there is currently a running asyncio loop."""
+    asyncio = sys.modules.get("asyncio", None)
+    if asyncio is None:
+        return False
+    try:
+        loop = asyncio.get_running_loop()
+    except Exception:
+        loop = None
+    return loop is not None
+
+
+# %% Linux window managers
+
+
+SYSTEM_IS_WAYLAND = "wayland" in os.getenv("XDG_SESSION_TYPE", "").lower()
+
+if sys.platform.startswith("linux") and SYSTEM_IS_WAYLAND:
+    # Force glfw to use X11. Note that this does not work if glfw is already imported.
+    if "glfw" not in sys.modules:
+        os.environ["PYGLFW_LIBRARY_VARIANT"] = "x11"
+    # Force Qt to use X11. Qt is more flexible - it ok if e.g. PySide6 is already imported.
+    os.environ["QT_QPA_PLATFORM"] = "xcb"
+    # Force wx to use X11, probably.
+    os.environ["GDK_BACKEND"] = "x11"
+
+
+_x11_display = None
+
+
+def get_alt_x11_display():
+    """Get (the pointer to) a process-global x11 display instance."""
+    # Ideally we'd get the real display object used by the backend.
+    # But this is not always possible. In that case, using an alt display
+    # object can be used.
+    global _x11_display
+    assert sys.platform.startswith("linux")
+    if _x11_display is None:
+        x11 = ctypes.CDLL(ctypes.util.find_library("X11"))
+        x11.XOpenDisplay.restype = ctypes.c_void_p
+        _x11_display = x11.XOpenDisplay(None)
+    return _x11_display
+
+
+_wayland_display = None
+
+
+def get_alt_wayland_display():
+    """Get (the pointer to) a process-global Wayland display instance."""
+    # Ideally we'd get the real display object used by the backend.
+    # This creates a global object, similar to what we do for X11.
+    # Unfortunately, this segfaults, so it looks like the real display object
+    # is needed? Leaving this here for reference.
+    global _wayland_display
+    assert sys.platform.startswith("linux")
+    if _wayland_display is None:
+        wl = ctypes.CDLL(ctypes.util.find_library("wayland-client"))
+        wl.wl_display_connect.restype = ctypes.c_void_p
+        _wayland_display = wl.wl_display_connect(None)
+    return _wayland_display

rendercanvas/_events.py

@@ -0,0 +1,218 @@
+"""
+The event system.
+"""
+
+import time
+from collections import defaultdict, deque
+
+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.
+    pointer_move = None  #: The  pointing device is moved. Same fields as pointer_down.
+    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.
+
+
+class EventEmitter:
+    """The EventEmitter stores event handlers, collects incoming events, and dispatched them.
+
+    Subsequent events of ``event_type`` 'pointer_move' and 'wheel' are merged.
+    """
+
+    _EVENTS_THAT_MERGE = {
+        "pointer_move": {
+            "match_keys": {"buttons", "modifiers", "ntouches"},
+            "accum_keys": {},
+        },
+        "wheel": {
+            "match_keys": {"modifiers"},
+            "accum_keys": {"dx", "dy"},
+        },
+        "resize": {
+            "match_keys": {},
+            "accum_keys": {},
+        },
+    }
+
+    def __init__(self):
+        self._pending_events = deque()
+        self._event_handlers = defaultdict(list)
+        self._closed = False
+
+    def add_handler(self, *args, order: float = 0):
+        """Register an event handler to receive events.
+
+        Arguments:
+            callback (callable): The event handler. Must accept a single event argument.
+            *types (list of strings): A list of event types.
+            order (float): Set callback priority order. Callbacks with lower priorities
+                are called first. Default is 0.
+
+        For the available events, see
+        https://jupyter-rfb.readthedocs.io/en/stable/events.html.
+
+        When an event is emitted, callbacks with the same priority are called in
+        the order that they were added.
+
+        The callback is stored, so it can be a lambda or closure. This also
+        means that if a method is given, a reference to the object is held,
+        which may cause circular references or prevent the Python GC from
+        destroying that object.
+
+        Example:
+
+        .. code-block:: py
+
+            def my_handler(event):
+                print(event)
+
+            canvas.add_event_handler(my_handler, "pointer_up", "pointer_down")
+
+        Can also be used as a decorator:
+
+        .. code-block:: py
+
+            @canvas.add_event_handler("pointer_up", "pointer_down") def
+            my_handler(event):
+                print(event)
+
+        Catch 'm all:
+
+        .. code-block:: py
+
+            canvas.add_event_handler(my_handler, "*")
+
+        """
+        order = float(order)
+        decorating = not callable(args[0])
+        callback = None if decorating else args[0]
+        types = args if decorating else args[1:]
+
+        if not types:
+            raise TypeError("No event types are given to add_event_handler.")
+        for type in types:
+            if not isinstance(type, str):
+                raise TypeError(f"Event types must be str, but got {type}")
+            if not (type == "*" or type in EventType):
+                raise ValueError(f"Adding handler with invalid event_type: '{type}'")
+
+        def decorator(_callback):
+            self._add_handler(_callback, order, *types)
+            return _callback
+
+        if decorating:
+            return decorator
+        return decorator(callback)
+
+    def _add_handler(self, callback, order, *types):
+        self.remove_handler(callback, *types)
+        for type in types:
+            self._event_handlers[type].append((order, callback))
+            self._event_handlers[type].sort(key=lambda x: x[0])
+            # Note: that sort is potentially expensive. I tried an approach with a custom dequeu to add the handler
+            # at the correct position, but the overhead was apparently larger than the benefit of avoiding sort.
+
+    def remove_handler(self, callback, *types):
+        """Unregister an event handler.
+
+        Arguments:
+            callback (callable): The event handler.
+            *types (list of strings): A list of event types.
+        """
+        for type in types:
+            self._event_handlers[type] = [
+                (o, cb) for o, cb in self._event_handlers[type] if cb is not callback
+            ]
+
+    def submit(self, event):
+        """Submit an event.
+
+        Events are emitted later by the scheduler.
+        """
+        event_type = event["event_type"]
+        if event_type not in EventType:
+            raise ValueError(f"Submitting with invalid event_type: '{event_type}'")
+        if event_type == "close":
+            self._closed = True
+
+        event.setdefault("time_stamp", time.perf_counter())
+        event_merge_info = self._EVENTS_THAT_MERGE.get(event_type, None)
+
+        if event_merge_info and self._pending_events:
+            # Try merging the event with the last one
+            last_event = self._pending_events[-1]
+            if last_event["event_type"] == event_type:
+                match_keys = event_merge_info["match_keys"]
+                accum_keys = event_merge_info["accum_keys"]
+                if all(
+                    event.get(key, None) == last_event.get(key, None)
+                    for key in match_keys
+                ):
+                    # Merge-able event
+                    self._pending_events.pop()  # remove last_event
+                    # Update new event
+                    for key in accum_keys:
+                        event[key] += last_event[key]
+
+        self._pending_events.append(event)
+
+    def flush(self):
+        """Dispatch all pending events.
+
+        This should generally be left to the scheduler.
+        """
+        while True:
+            try:
+                event = self._pending_events.popleft()
+            except IndexError:
+                break
+            self.emit(event)
+
+    def emit(self, event):
+        """Directly emit the given event.
+
+        In most cases events should be submitted, so that they are flushed
+        with the rest at a good time.
+        """
+        # Collect callbacks
+        event_type = event.get("event_type")
+        callbacks = self._event_handlers[event_type] + self._event_handlers["*"]
+        # Dispatch
+        for _order, callback in callbacks:
+            if event.get("stop_propagation", False):
+                break
+            with log_exception(f"Error during handling {event_type} event"):
+                callback(event)
+
+    def _rc_close(self):
+        """Wrap up when the scheduler detects the canvas is closed/dead."""
+        # This is a little feature because detecting a widget from closing can be tricky.
+        if not self._closed:
+            self.submit({"event_type": "close"})
+        self.flush()