urwid 2.6.0.post0__py3-none-any.whl

urwid/event_loop/abstract_loop.py

@@ -0,0 +1,175 @@
+# Urwid main loop code
+#    Copyright (C) 2004-2012  Ian Ward
+#    Copyright (C) 2008 Walter Mundt
+#    Copyright (C) 2009 Andrew Psaltis
+#
+#    This library is free software; you can redistribute it and/or
+#    modify it under the terms of the GNU Lesser General Public
+#    License as published by the Free Software Foundation; either
+#    version 2.1 of the License, or (at your option) any later version.
+#
+#    This library is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#    Lesser General Public License for more details.
+#
+#    You should have received a copy of the GNU Lesser General Public
+#    License along with this library; if not, write to the Free Software
+#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# Urwid web site: https://urwid.org/
+
+"""Abstract shared code for urwid EventLoop implementation."""
+
+from __future__ import annotations
+
+import abc
+import logging
+import signal
+import typing
+
+if typing.TYPE_CHECKING:
+    import asyncio
+    from collections.abc import Callable
+    from concurrent.futures import Executor, Future
+    from types import FrameType
+
+    from typing_extensions import ParamSpec
+
+    _T = typing.TypeVar("_T")
+    _Spec = ParamSpec("_Spec")
+
+__all__ = ("EventLoop", "ExitMainLoop")
+
+
+class ExitMainLoop(Exception):
+    """
+    When this exception is raised within a main loop the main loop
+    will exit cleanly.
+    """
+
+
+class EventLoop(abc.ABC):
+    """
+    Abstract class representing an event loop to be used by :class:`MainLoop`.
+    """
+
+    __slots__ = ("logger",)
+
+    def __init__(self) -> None:
+        self.logger = logging.getLogger(__name__).getChild(self.__class__.__name__)
+
+    def run_in_executor(
+        self,
+        executor: Executor,
+        func: Callable[_Spec, _T],
+        *args: _Spec.args,
+    ) -> Future[_T] | asyncio.Future[_T]:
+        """Run callable in executor if supported.
+
+        :param executor: Executor to use for running the function
+        :type executor: concurrent.futures.Executor
+        :param func: function to call
+        :type func: Callable
+        :param args: arguments to function (positional only)
+        :type args: object
+        :return: future object for the function call outcome.
+                 (exact future type depends on the event loop type)
+        :rtype: concurrent.futures.Future | asyncio.Future
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def alarm(self, seconds: float, callback: Callable[[], typing.Any]) -> typing.Any:
+        """
+        Call callback() a given time from now.  No parameters are
+        passed to callback.
+
+        This method has no default implementation.
+
+        Returns a handle that may be passed to remove_alarm()
+
+        seconds -- floating point time to wait before calling callback
+        callback -- function to call from event loop
+        """
+
+    @abc.abstractmethod
+    def enter_idle(self, callback):
+        """
+        Add a callback for entering idle.
+
+        This method has no default implementation.
+
+        Returns a handle that may be passed to remove_idle()
+        """
+
+    @abc.abstractmethod
+    def remove_alarm(self, handle) -> bool:
+        """
+        Remove an alarm.
+
+        This method has no default implementation.
+
+        Returns True if the alarm exists, False otherwise
+        """
+
+    @abc.abstractmethod
+    def remove_enter_idle(self, handle) -> bool:
+        """
+        Remove an idle callback.
+
+        This method has no default implementation.
+
+        Returns True if the handle was removed.
+        """
+
+    @abc.abstractmethod
+    def remove_watch_file(self, handle) -> bool:
+        """
+        Remove an input file.
+
+        This method has no default implementation.
+
+        Returns True if the input file exists, False otherwise
+        """
+
+    @abc.abstractmethod
+    def run(self) -> None:
+        """
+        Start the event loop.  Exit the loop when any callback raises
+        an exception.  If ExitMainLoop is raised, exit cleanly.
+
+        This method has no default implementation.
+        """
+
+    @abc.abstractmethod
+    def watch_file(self, fd: int, callback: Callable[[], typing.Any]):
+        """
+        Call callback() when fd has some data to read.  No parameters
+        are passed to callback.
+
+        This method has no default implementation.
+
+        Returns a handle that may be passed to remove_watch_file()
+
+        fd -- file descriptor to watch for input
+        callback -- function to call when input is available
+        """
+
+    def set_signal_handler(
+        self,
+        signum: int,
+        handler: Callable[[int, FrameType | None], typing.Any] | int | signal.Handlers,
+    ) -> Callable[[int, FrameType | None], typing.Any] | int | signal.Handlers | None:
+        """
+        Sets the signal handler for signal signum.
+
+        The default implementation of :meth:`set_signal_handler`
+        is simply a proxy function that calls :func:`signal.signal()`
+        and returns the resulting value.
+
+        signum -- signal number
+        handler -- function (taking signum as its single argument),
+        or `signal.SIG_IGN`, or `signal.SIG_DFL`
+        """
+        return signal.signal(signum, handler)

urwid/event_loop/asyncio_loop.py

@@ -0,0 +1,231 @@
+# Urwid main loop code
+#    Copyright (C) 2004-2012  Ian Ward
+#    Copyright (C) 2008 Walter Mundt
+#    Copyright (C) 2009 Andrew Psaltis
+#
+#    This library is free software; you can redistribute it and/or
+#    modify it under the terms of the GNU Lesser General Public
+#    License as published by the Free Software Foundation; either
+#    version 2.1 of the License, or (at your option) any later version.
+#
+#    This library is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#    Lesser General Public License for more details.
+#
+#    You should have received a copy of the GNU Lesser General Public
+#    License along with this library; if not, write to the Free Software
+#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# Urwid web site: https://urwid.org/
+
+"""Asyncio based urwid EventLoop implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+import sys
+import typing
+
+from .abstract_loop import EventLoop, ExitMainLoop
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Callable
+    from concurrent.futures import Executor
+
+    from typing_extensions import ParamSpec
+
+    _Spec = ParamSpec("_Spec")
+    _T = typing.TypeVar("_T")
+
+__all__ = ("AsyncioEventLoop",)
+IS_WINDOWS = sys.platform == "win32"
+
+
+class AsyncioEventLoop(EventLoop):
+    """
+    Event loop based on the standard library ``asyncio`` module.
+
+    .. warning::
+        Under Windows, AsyncioEventLoop globally enforces WindowsSelectorEventLoopPolicy
+        as a side-effect of creating a class instance.
+        Original event loop policy is restored in destructor method.
+
+    .. note::
+        If you make any changes to the urwid state outside of it
+        handling input or responding to alarms (for example, from asyncio.Task
+        running in background), and wish the screen to be
+        redrawn, you must call :meth:`MainLoop.draw_screen` method of the
+        main loop manually.
+
+        A good way to do this:
+            asyncio.get_event_loop().call_soon(main_loop.draw_screen)
+    """
+
+    def __init__(self, *, loop: asyncio.AbstractEventLoop | None = None, **kwargs) -> None:
+        super().__init__()
+        self.logger = logging.getLogger(__name__).getChild(self.__class__.__name__)
+        if loop:
+            self._loop: asyncio.AbstractEventLoop = loop
+            self._event_loop_policy_altered: bool = False
+            self._original_event_loop_policy: asyncio.AbstractEventLoopPolicy | None = None
+        else:
+            self._original_event_loop_policy = asyncio.get_event_loop_policy()
+            if IS_WINDOWS and not isinstance(self._original_event_loop_policy, asyncio.WindowsSelectorEventLoopPolicy):
+                self.logger.debug("Set WindowsSelectorEventLoopPolicy as asyncio event loop policy")
+                asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+                self._event_loop_policy_altered = True
+            else:
+                self._event_loop_policy_altered = False
+
+            self._loop = asyncio.get_event_loop()
+
+        self._exc: BaseException | None = None
+
+        self._idle_asyncio_handle: asyncio.TimerHandle | None = None
+        self._idle_handle: int = 0
+        self._idle_callbacks: dict[int, Callable[[], typing.Any]] = {}
+
+    def __del__(self) -> None:
+        if self._event_loop_policy_altered:
+            asyncio.set_event_loop_policy(self._original_event_loop_policy)  # Restore default event loop policy
+
+    def _also_call_idle(self, callback: Callable[_Spec, _T]) -> Callable[_Spec, _T]:
+        """
+        Wrap the callback to also call _entering_idle.
+        """
+
+        @functools.wraps(callback)
+        def wrapper(*args: _Spec.args, **kwargs: _Spec.kwargs) -> _T:
+            if not self._idle_asyncio_handle:
+                self._idle_asyncio_handle = self._loop.call_later(0, self._entering_idle)
+            return callback(*args, **kwargs)
+
+        return wrapper
+
+    def _entering_idle(self) -> None:
+        """
+        Call all the registered idle callbacks.
+        """
+        try:
+            for callback in self._idle_callbacks.values():
+                callback()
+        finally:
+            self._idle_asyncio_handle = None
+
+    def run_in_executor(
+        self,
+        executor: Executor | None,
+        func: Callable[_Spec, _T],
+        *args: _Spec.args,
+    ) -> asyncio.Future[_T]:
+        """Run callable in executor.
+
+        :param executor: Executor to use for running the function. Default asyncio executor is used if None.
+        :type executor: concurrent.futures.Executor | None
+        :param func: function to call
+        :type func: Callable
+        :param args: arguments to function (positional only)
+        :type args: object
+        :return: future object for the function call outcome.
+        :rtype: asyncio.Future
+        """
+        return self._loop.run_in_executor(executor, func, *args)
+
+    def alarm(self, seconds: float, callback: Callable[[], typing.Any]) -> asyncio.TimerHandle:
+        """
+        Call callback() a given time from now.  No parameters are
+        passed to callback.
+
+        Returns a handle that may be passed to remove_alarm()
+
+        seconds -- time in seconds to wait before calling callback
+        callback -- function to call from event loop
+        """
+        return self._loop.call_later(seconds, self._also_call_idle(callback))
+
+    def remove_alarm(self, handle) -> bool:
+        """
+        Remove an alarm.
+
+        Returns True if the alarm exists, False otherwise
+        """
+        existed = not handle.cancelled()
+        handle.cancel()
+        return existed
+
+    def watch_file(self, fd: int, callback: Callable[[], typing.Any]) -> int:
+        """
+        Call callback() when fd has some data to read.  No parameters
+        are passed to callback.
+
+        Returns a handle that may be passed to remove_watch_file()
+
+        fd -- file descriptor to watch for input
+        callback -- function to call when input is available
+        """
+        self._loop.add_reader(fd, self._also_call_idle(callback))
+        return fd
+
+    def remove_watch_file(self, handle: int) -> bool:
+        """
+        Remove an input file.
+
+        Returns True if the input file exists, False otherwise
+        """
+        return self._loop.remove_reader(handle)
+
+    def enter_idle(self, callback: Callable[[], typing.Any]) -> int:
+        """
+        Add a callback for entering idle.
+
+        Returns a handle that may be passed to remove_enter_idle()
+        """
+        # XXX there's no such thing as "idle" in most event loops; this fakes
+        # it by adding extra callback to the timer and file watch callbacks.
+        self._idle_handle += 1
+        self._idle_callbacks[self._idle_handle] = callback
+        return self._idle_handle
+
+    def remove_enter_idle(self, handle: int) -> bool:
+        """
+        Remove an idle callback.
+
+        Returns True if the handle was removed.
+        """
+        try:
+            del self._idle_callbacks[handle]
+        except KeyError:
+            return False
+        return True
+
+    def _exception_handler(self, loop: asyncio.AbstractEventLoop, context):
+        exc = context.get("exception")
+        if exc:
+            loop.stop()
+
+            if self._idle_asyncio_handle:
+                # clean it up to prevent old callbacks
+                # from messing things up if loop is restarted
+                self._idle_asyncio_handle.cancel()
+                self._idle_asyncio_handle = None
+
+            if not isinstance(exc, ExitMainLoop):
+                # Store the exc_info so we can re-raise after the loop stops
+                self._exc = exc
+        else:
+            loop.default_exception_handler(context)
+
+    def run(self) -> None:
+        """
+        Start the event loop.  Exit the loop when any callback raises
+        an exception.  If ExitMainLoop is raised, exit cleanly.
+        """
+        self._loop.set_exception_handler(self._exception_handler)
+        self._loop.run_forever()
+        if self._exc:
+            exc = self._exc
+            self._exc = None
+            raise exc.with_traceback(exc.__traceback__)

urwid/event_loop/glib_loop.py

@@ -0,0 +1,294 @@
+# Urwid main loop code
+#    Copyright (C) 2004-2012  Ian Ward
+#    Copyright (C) 2008 Walter Mundt
+#    Copyright (C) 2009 Andrew Psaltis
+#
+#    This library is free software; you can redistribute it and/or
+#    modify it under the terms of the GNU Lesser General Public
+#    License as published by the Free Software Foundation; either
+#    version 2.1 of the License, or (at your option) any later version.
+#
+#    This library is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#    Lesser General Public License for more details.
+#
+#    You should have received a copy of the GNU Lesser General Public
+#    License along with this library; if not, write to the Free Software
+#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# Urwid web site: https://urwid.org/
+
+"""GLib based urwid EventLoop implementation.
+
+PyGObject library is required.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import signal
+import typing
+
+from gi.repository import GLib
+
+from .abstract_loop import EventLoop, ExitMainLoop
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Callable
+    from concurrent.futures import Executor, Future
+    from types import FrameType
+
+    from typing_extensions import Literal, ParamSpec
+
+    _Spec = ParamSpec("_Spec")
+    _T = typing.TypeVar("_T")
+
+__all__ = ("GLibEventLoop",)
+
+
+def _ignore_handler(_sig: int, _frame: FrameType | None = None) -> None:
+    return None
+
+
+class GLibEventLoop(EventLoop):
+    """
+    Event loop based on GLib.MainLoop
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.logger = logging.getLogger(__name__).getChild(self.__class__.__name__)
+        self._alarms: list[int] = []
+        self._watch_files: dict[int, int] = {}
+        self._idle_handle: int = 0
+        self._glib_idle_enabled = False  # have we called glib.idle_add?
+        self._idle_callbacks: dict[int, Callable[[], typing.Any]] = {}
+        self._loop = GLib.MainLoop()
+        self._exc: BaseException | None = None
+        self._enable_glib_idle()
+        self._signal_handlers: dict[int, int] = {}
+
+    def run_in_executor(
+        self,
+        executor: Executor,
+        func: Callable[_Spec, _T],
+        *args: _Spec.args,
+        **kwargs: _Spec.kwargs,
+    ) -> Future[_T]:
+        """Run callable in executor.
+
+        :param executor: Executor to use for running the function
+        :type executor: concurrent.futures.Executor
+        :param func: function to call
+        :type func: Callable
+        :param args: positional arguments to function
+        :type args: object
+        :param kwargs: keyword arguments to function
+        :type kwargs: object
+        :return: future object for the function call outcome.
+        :rtype: concurrent.futures.Future
+        """
+        return executor.submit(func, *args, **kwargs)
+
+    def alarm(
+        self,
+        seconds: float,
+        callback: Callable[[], typing.Any],
+    ) -> tuple[int, Callable[[], typing.Any]]:
+        """
+        Call callback() a given time from now.  No parameters are
+        passed to callback.
+
+        Returns a handle that may be passed to remove_alarm()
+
+        seconds -- floating point time to wait before calling callback
+        callback -- function to call from event loop
+        """
+
+        @self.handle_exit
+        def ret_false() -> Literal[False]:
+            callback()
+            self._enable_glib_idle()
+            return False
+
+        fd = GLib.timeout_add(int(seconds * 1000), ret_false)
+        self._alarms.append(fd)
+        return (fd, callback)
+
+    def set_signal_handler(
+        self,
+        signum: int,
+        handler: Callable[[int, FrameType | None], typing.Any] | int | signal.Handlers,
+    ) -> None:
+        """
+        Sets the signal handler for signal signum.
+
+        .. WARNING::
+            Because this method uses the `GLib`-specific `unix_signal_add`
+            function, its behaviour is different than `signal.signal().`
+
+            If `signum` is not `SIGHUP`, `SIGINT`, `SIGTERM`, `SIGUSR1`,
+            `SIGUSR2` or `SIGWINCH`, this method performs no actions and
+            immediately returns None.
+
+            Returns None in all cases (unlike :func:`signal.signal()`).
+        ..
+
+        signum -- signal number
+        handler -- function (taking signum as its single argument),
+        or `signal.SIG_IGN`, or `signal.SIG_DFL`
+        """
+        glib_signals = [
+            signal.SIGHUP,
+            signal.SIGINT,
+            signal.SIGTERM,
+            signal.SIGUSR1,
+            signal.SIGUSR2,
+        ]
+
+        # GLib supports SIGWINCH as of version 2.54.
+        if not GLib.check_version(2, 54, 0):
+            glib_signals.append(signal.SIGWINCH)
+
+        if signum not in glib_signals:
+            # The GLib event loop supports only the signals listed above
+            return
+
+        if signum in self._signal_handlers:
+            GLib.source_remove(self._signal_handlers.pop(signum))
+
+        if handler == signal.Handlers.SIG_IGN:
+            handler = _ignore_handler
+        elif handler == signal.Handlers.SIG_DFL:
+            return
+
+        def final_handler(signal_number: int):
+            # MyPy False-negative: signal.Handlers casted
+            handler(signal_number, None)  # type: ignore[operator]
+            return GLib.SOURCE_CONTINUE
+
+        source = GLib.unix_signal_add(GLib.PRIORITY_DEFAULT, signum, final_handler, signum)
+        self._signal_handlers[signum] = source
+
+    def remove_alarm(self, handle) -> bool:
+        """
+        Remove an alarm.
+
+        Returns True if the alarm exists, False otherwise
+        """
+        try:
+            self._alarms.remove(handle[0])
+            GLib.source_remove(handle[0])
+
+        except ValueError:
+            return False
+
+        return True
+
+    def watch_file(self, fd: int, callback: Callable[[], typing.Any]) -> int:
+        """
+        Call callback() when fd has some data to read.  No parameters
+        are passed to callback.
+
+        Returns a handle that may be passed to remove_watch_file()
+
+        fd -- file descriptor to watch for input
+        callback -- function to call when input is available
+        """
+
+        @self.handle_exit
+        def io_callback(source, cb_condition) -> Literal[True]:
+            callback()
+            self._enable_glib_idle()
+            return True
+
+        self._watch_files[fd] = GLib.io_add_watch(fd, GLib.IO_IN, io_callback)
+        return fd
+
+    def remove_watch_file(self, handle: int) -> bool:
+        """
+        Remove an input file.
+
+        Returns True if the input file exists, False otherwise
+        """
+        if handle in self._watch_files:
+            GLib.source_remove(self._watch_files[handle])
+            del self._watch_files[handle]
+            return True
+        return False
+
+    def enter_idle(self, callback: Callable[[], typing.Any]) -> int:
+        """
+        Add a callback for entering idle.
+
+        Returns a handle that may be passed to remove_enter_idle()
+        """
+        self._idle_handle += 1
+        self._idle_callbacks[self._idle_handle] = callback
+        return self._idle_handle
+
+    def _enable_glib_idle(self) -> None:
+        if self._glib_idle_enabled:
+            return
+        GLib.idle_add(self._glib_idle_callback)
+        self._glib_idle_enabled = True
+
+    def _glib_idle_callback(self):
+        for callback in self._idle_callbacks.values():
+            callback()
+        self._glib_idle_enabled = False
+        return False  # ask glib not to call again (or we would be called
+
+    def remove_enter_idle(self, handle) -> bool:
+        """
+        Remove an idle callback.
+
+        Returns True if the handle was removed.
+        """
+        try:
+            del self._idle_callbacks[handle]
+        except KeyError:
+            return False
+        return True
+
+    def run(self) -> None:
+        """
+        Start the event loop.  Exit the loop when any callback raises
+        an exception.  If ExitMainLoop is raised, exit cleanly.
+        """
+        try:
+            self._loop.run()
+        finally:
+            if self._loop.is_running():
+                self._loop.quit()
+        if self._exc:
+            # An exception caused us to exit, raise it now
+            exc = self._exc
+            self._exc = None
+            raise exc.with_traceback(exc.__traceback__)
+
+    def handle_exit(self, f: Callable[_Spec, _T]) -> Callable[_Spec, _T | Literal[False]]:
+        """
+        Decorator that cleanly exits the :class:`GLibEventLoop` if
+        :exc:`ExitMainLoop` is thrown inside of the wrapped function. Store the
+        exception info if some other exception occurs, it will be reraised after
+        the loop quits.
+
+        *f* -- function to be wrapped
+        """
+
+        @functools.wraps(f)
+        def wrapper(*args: _Spec.args, **kwargs: _Spec.kwargs) -> _T | Literal[False]:
+            try:
+                return f(*args, **kwargs)
+            except ExitMainLoop:
+                self._loop.quit()
+            except BaseException as exc:
+                self._exc = exc
+                if self._loop.is_running():
+                    self._loop.quit()
+            return False
+
+        return wrapper