urwid 2.6.0.post0__py3-none-any.whl

urwid/event_loop/trio_loop.py

@@ -0,0 +1,302 @@
+# Urwid main loop code using Python-3.5 features (Trio, Curio, etc)
+#    Copyright (C) 2018 Toshio Kuratomi
+#    Copyright (C) 2019 Tamas Nepusz
+#
+#    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/
+
+"""Trio Runner based urwid EventLoop implementation.
+
+Trio library is required.
+"""
+
+from __future__ import annotations
+
+import logging
+import typing
+
+import exceptiongroup
+import trio
+
+from .abstract_loop import EventLoop, ExitMainLoop
+
+if typing.TYPE_CHECKING:
+    import io
+    from collections.abc import Awaitable, Callable, Hashable, Mapping
+
+    from typing_extensions import Concatenate, ParamSpec
+
+    _Spec = ParamSpec("_Spec")
+
+__all__ = ("TrioEventLoop",)
+
+
+class _TrioIdleCallbackInstrument(trio.abc.Instrument):
+    """IDLE callbacks emulation helper."""
+
+    __slots__ = ("idle_callbacks",)
+
+    def __init__(self, idle_callbacks: Mapping[Hashable, Callable[[], typing.Any]]):
+        self.idle_callbacks = idle_callbacks
+
+    def before_io_wait(self, timeout: float) -> None:
+        if timeout > 0:
+            for idle_callback in self.idle_callbacks.values():
+                idle_callback()
+
+
+class TrioEventLoop(EventLoop):
+    """
+    Event loop based on the ``trio`` module.
+
+    ``trio`` is an async library for Python 3.5 and later.
+    """
+
+    def __init__(self) -> None:
+        """Constructor."""
+        super().__init__()
+        self.logger = logging.getLogger(__name__).getChild(self.__class__.__name__)
+
+        self._idle_handle = 0
+        self._idle_callbacks: dict[int, Callable[[], typing.Any]] = {}
+        self._pending_tasks: list[tuple[Callable[_Spec, Awaitable], trio.CancelScope, _Spec.args]] = []
+
+        self._nursery: trio.Nursery | None = None
+
+        self._sleep = trio.sleep
+        self._wait_readable = trio.lowlevel.wait_readable
+
+    def alarm(
+        self,
+        seconds: float,
+        callback: Callable[[], typing.Any],
+    ) -> trio.CancelScope:
+        """Calls `callback()` a given time from now.
+
+        :param seconds: time in seconds to wait before calling the callback
+        :type seconds: float
+        :param callback: function to call from the event loop
+        :type callback: Callable[[], typing.Any]
+        :return: a handle that may be passed to `remove_alarm()`
+        :rtype: trio.CancelScope
+
+        No parameters are passed to the callback.
+        """
+        return self._start_task(self._alarm_task, seconds, callback)
+
+    def enter_idle(self, callback: Callable[[], typing.Any]) -> int:
+        """Calls `callback()` when the event loop enters the idle state.
+
+        There is no such thing as being idle in a Trio event loop so we
+        simulate it by repeatedly calling `callback()` with a short delay.
+        """
+        self._idle_handle += 1
+        self._idle_callbacks[self._idle_handle] = callback
+        return self._idle_handle
+
+    def remove_alarm(self, handle: trio.CancelScope) -> bool:
+        """Removes an alarm.
+
+        Parameters:
+            handle: the handle of the alarm to remove
+        """
+        return self._cancel_scope(handle)
+
+    def remove_enter_idle(self, handle: int) -> bool:
+        """Removes an idle callback.
+
+        Parameters:
+            handle: the handle of the idle callback to remove
+        """
+        try:
+            del self._idle_callbacks[handle]
+        except KeyError:
+            return False
+        return True
+
+    def remove_watch_file(self, handle: trio.CancelScope) -> bool:
+        """Removes a file descriptor being watched for input.
+
+        Parameters:
+            handle: the handle of the file descriptor callback to remove
+
+        Returns:
+            True if the file descriptor was watched, False otherwise
+        """
+        return self._cancel_scope(handle)
+
+    def _cancel_scope(self, scope: trio.CancelScope) -> bool:
+        """Cancels the given Trio cancellation scope.
+
+        Returns:
+            True if the scope was cancelled, False if it was cancelled already
+            before invoking this function
+        """
+        existed = not scope.cancel_called
+        scope.cancel()
+        return existed
+
+    def run(self) -> None:
+        """Starts the event loop. Exits the loop when any callback raises an
+        exception. If ExitMainLoop is raised, exits cleanly.
+        """
+
+        emulate_idle_callbacks = _TrioIdleCallbackInstrument(self._idle_callbacks)
+
+        with exceptiongroup.catch({BaseException: self._handle_main_loop_exception}):
+            trio.run(self._main_task, instruments=[emulate_idle_callbacks])
+
+    async def run_async(self) -> None:
+        """Starts the main loop and blocks asynchronously until the main loop
+        exits. This allows one to embed an urwid app in a Trio app even if the
+        Trio event loop is already running. Example::
+
+            with trio.open_nursery() as nursery:
+                event_loop = urwid.TrioEventLoop()
+
+                # [...launch other async tasks in the nursery...]
+
+                loop = urwid.MainLoop(widget, event_loop=event_loop)
+                with loop.start():
+                    await event_loop.run_async()
+
+                nursery.cancel_scope.cancel()
+        """
+
+        emulate_idle_callbacks = _TrioIdleCallbackInstrument(self._idle_callbacks)
+
+        with exceptiongroup.catch({BaseException: self._handle_main_loop_exception}):
+            trio.lowlevel.add_instrument(emulate_idle_callbacks)
+            try:
+                await self._main_task()
+            finally:
+                trio.lowlevel.remove_instrument(emulate_idle_callbacks)
+
+    def watch_file(
+        self,
+        fd: int | io.IOBase,
+        callback: Callable[[], typing.Any],
+    ) -> trio.CancelScope:
+        """Calls `callback()` when the given file descriptor has some data
+        to read. No parameters are passed to the callback.
+
+        Parameters:
+            fd: file descriptor to watch for input
+            callback: function to call when some input is available
+
+        Returns:
+            a handle that may be passed to `remove_watch_file()`
+        """
+        return self._start_task(self._watch_task, fd, callback)
+
+    async def _alarm_task(
+        self,
+        scope: trio.CancelScope,
+        seconds: float,
+        callback: Callable[[], typing.Any],
+    ) -> None:
+        """Asynchronous task that sleeps for a given number of seconds and then
+        calls the given callback.
+
+        Parameters:
+            scope: the cancellation scope that can be used to cancel the task
+            seconds: the number of seconds to wait
+            callback: the callback to call
+        """
+        with scope:
+            await self._sleep(seconds)
+            callback()
+
+    def _handle_main_loop_exception(self, exc: BaseException) -> None:
+        """Handles exceptions raised from the main loop, catching ExitMainLoop
+        instead of letting it propagate through.
+
+        Note that since Trio may collect multiple exceptions from tasks into a
+        Trio MultiError, we cannot simply use a try..catch clause, we need a
+        helper function like this.
+        """
+        self._idle_callbacks.clear()
+        if isinstance(exc, exceptiongroup.BaseExceptionGroup) and len(exc.exceptions) == 1:
+            exc = exc.exceptions[0]
+
+        if isinstance(exc, ExitMainLoop):
+            return
+
+        raise exc.with_traceback(exc.__traceback__) from None
+
+    async def _main_task(self) -> None:
+        """Main Trio task that opens a nursery and then sleeps until the user
+        exits the app by raising ExitMainLoop.
+        """
+        try:
+            async with trio.open_nursery() as self._nursery:
+                self._schedule_pending_tasks()
+                await trio.sleep_forever()
+        finally:
+            self._nursery = None
+
+    def _schedule_pending_tasks(self) -> None:
+        """Schedules all pending asynchronous tasks that were created before
+        the nursery to be executed on the nursery soon.
+        """
+        for task, scope, args in self._pending_tasks:
+            self._nursery.start_soon(task, scope, *args)
+        del self._pending_tasks[:]
+
+    def _start_task(
+        self,
+        task: Callable[Concatenate[trio.CancelScope, _Spec], Awaitable],
+        *args: _Spec.args,
+    ) -> trio.CancelScope:
+        """Starts an asynchronous task in the Trio nursery managed by the
+        main loop. If the nursery has not started yet, store a reference to
+        the task and the arguments so we can start the task when the nursery
+        is open.
+
+        Parameters:
+            task: a Trio task to run
+
+        Returns:
+            a cancellation scope for the Trio task
+        """
+        scope = trio.CancelScope()
+        if self._nursery:
+            self._nursery.start_soon(task, scope, *args)
+        else:
+            self._pending_tasks.append((task, scope, args))
+        return scope
+
+    async def _watch_task(
+        self,
+        scope: trio.CancelScope,
+        fd: int | io.IOBase,
+        callback: Callable[[], typing.Any],
+    ) -> None:
+        """Asynchronous task that watches the given file descriptor and calls
+        the given callback whenever the file descriptor becomes readable.
+
+        Parameters:
+            scope: the cancellation scope that can be used to cancel the task
+            fd: the file descriptor to watch
+            callback: the callback to call
+        """
+        with scope:
+            # We check for the scope being cancelled before calling
+            # wait_readable because if callback cancels the scope, fd might be
+            # closed and calling wait_readable with a closed fd does not work.
+            while not scope.cancel_called:
+                await self._wait_readable(fd)
+                callback()

urwid/event_loop/twisted_loop.py

@@ -0,0 +1,269 @@
+# 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/
+
+"""Twisted Reactor based urwid EventLoop implementation.
+
+Twisted library is required.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import sys
+import typing
+
+from twisted.internet.abstract import FileDescriptor
+from twisted.internet.error import AlreadyCalled, AlreadyCancelled
+
+from .abstract_loop import EventLoop, ExitMainLoop
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Callable
+    from concurrent.futures import Executor, Future
+
+    from twisted.internet.base import DelayedCall, ReactorBase
+    from typing_extensions import ParamSpec
+
+    _Spec = ParamSpec("_Spec")
+    _T = typing.TypeVar("_T")
+
+__all__ = ("TwistedEventLoop",)
+
+
+class _TwistedInputDescriptor(FileDescriptor):
+    def __init__(self, reactor: ReactorBase, fd: int, cb: Callable[[], typing.Any]) -> None:
+        self._fileno = fd
+        self.cb = cb
+        super().__init__(reactor)  # ReactorBase implement full API as required in interfaces
+
+    def fileno(self) -> int:
+        return self._fileno
+
+    def doRead(self):
+        return self.cb()
+
+    def getHost(self):
+        raise NotImplementedError("No network operation expected")
+
+    def getPeer(self):
+        raise NotImplementedError("No network operation expected")
+
+    def writeSomeData(self, data: bytes) -> None:
+        raise NotImplementedError("Reduced functionality: read-only")
+
+
+class TwistedEventLoop(EventLoop):
+    """
+    Event loop based on Twisted_
+    """
+
+    _idle_emulation_delay = 1.0 / 256  # a short time (in seconds)
+
+    def __init__(self, reactor: ReactorBase | None = None, manage_reactor: bool = True) -> None:
+        """
+        :param reactor: reactor to use
+        :type reactor: :class:`twisted.internet.reactor`.
+        :param: manage_reactor: `True` if you want this event loop to run
+                                and stop the reactor.
+        :type manage_reactor: boolean
+
+        .. WARNING::
+           Twisted's reactor doesn't like to be stopped and run again.  If you
+           need to stop and run your :class:`MainLoop`, consider setting
+           ``manage_reactor=False`` and take care of running/stopping the reactor
+           at the beginning/ending of your program yourself.
+
+           You can also forego using :class:`MainLoop`'s run() entirely, and
+           instead call start() and stop() before and after starting the
+           reactor.
+
+        .. _Twisted: https://twisted.org/
+        """
+        super().__init__()
+        self.logger = logging.getLogger(__name__).getChild(self.__class__.__name__)
+        if reactor is None:
+            import twisted.internet.reactor
+
+            reactor = twisted.internet.reactor
+        self.reactor: ReactorBase = reactor
+        self._watch_files: dict[int, _TwistedInputDescriptor] = {}
+        self._idle_handle: int = 0
+        self._twisted_idle_enabled = False
+        self._idle_callbacks: dict[int, Callable[[], typing.Any]] = {}
+        self._exc: BaseException | None = None
+        self.manage_reactor = manage_reactor
+        self._enable_twisted_idle()
+
+    def run_in_executor(
+        self,
+        executor: Executor,
+        func: Callable[..., _T],
+        *args: object,
+    ) -> Future[_T]:
+        raise NotImplementedError(
+            "Twisted implement it's own ThreadPool executor. Please use native API for call:\n"
+            "'threads.deferToThread(Callable[..., Any], *args, **kwargs)'\n"
+            "And use 'addCallback' api for callbacks:\n"
+            "'threads.deferToThread(Callable[..., T], *args, **kwargs).addCallback(Callable[[T], None])'"
+        )
+
+    def alarm(self, seconds: float, callback: Callable[[], typing.Any]) -> DelayedCall:
+        """
+        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
+        """
+        handle = self.reactor.callLater(seconds, self.handle_exit(callback))
+        return handle
+
+    def remove_alarm(self, handle: DelayedCall) -> bool:
+        """
+        Remove an alarm.
+
+        Returns True if the alarm exists, False otherwise
+        """
+        try:
+            handle.cancel()
+
+        except (AlreadyCancelled, AlreadyCalled):
+            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
+        """
+        ind = _TwistedInputDescriptor(self.reactor, fd, self.handle_exit(callback))
+        self._watch_files[fd] = ind
+        self.reactor.addReader(ind)
+        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:
+            self.reactor.removeReader(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_twisted_idle(self) -> None:
+        """
+        Twisted's reactors don't have an idle or enter-idle callback
+        so the best we can do for now is to set a timer event in a very
+        short time to approximate an enter-idle callback.
+
+        .. WARNING::
+           This will perform worse than the other event loops until we can find a
+           fix or workaround
+        """
+        if self._twisted_idle_enabled:
+            return
+        self.reactor.callLater(
+            self._idle_emulation_delay,
+            self.handle_exit(self._twisted_idle_callback, enable_idle=False),
+        )
+        self._twisted_idle_enabled = True
+
+    def _twisted_idle_callback(self) -> None:
+        for callback in self._idle_callbacks.values():
+            callback()
+        self._twisted_idle_enabled = False
+
+    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 run(self) -> None:
+        """
+        Start the event loop.  Exit the loop when any callback raises
+        an exception.  If ExitMainLoop is raised, exit cleanly.
+        """
+        if not self.manage_reactor:
+            return
+        self.reactor.run()
+        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], enable_idle: bool = True) -> Callable[_Spec, _T | None]:
+        """
+        Decorator that cleanly exits the :class:`TwistedEventLoop` if
+        :class:`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 | None:
+            rval = None
+            try:
+                rval = f(*args, **kwargs)
+            except ExitMainLoop:
+                if self.manage_reactor:
+                    self.reactor.stop()
+            except BaseException as exc:
+                print(sys.exc_info())
+                self._exc = exc
+                if self.manage_reactor:
+                    self.reactor.crash()
+            if enable_idle:
+                self._enable_twisted_idle()
+            return rval
+
+        return wrapper