AutoAndroidController/py/venv/Lib/site-packages/PySide6/QtAsyncio/tasks.py

# Copyright (C) 2023 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
from __future__ import annotations

from . import events
from . import futures
import traceback

from typing import Any, Optional

import asyncio
import collections.abc
import concurrent.futures
import contextvars


class QAsyncioTask(futures.QAsyncioFuture):
    """ https://docs.python.org/3/library/asyncio-task.html """

    def __init__(self, coro: collections.abc.Generator | collections.abc.Coroutine, *,
                 loop: "events.QAsyncioEventLoop | None" = None, name: str | None = None,
                 context: contextvars.Context | None = None) -> None:
        super().__init__(loop=loop, context=context)
        self._source_traceback = None  # required for Python < 3.11

        self._state: futures.QAsyncioFuture.FutureState = futures.QAsyncioFuture.FutureState.PENDING
        self._exception: Optional[BaseException] = None

        self._coro = coro  # The coroutine for which this task was created.
        self._name = name if name else "QtTask"

        # The task creates a handle for its coroutine. The handle enqueues the
        # task's step function as its callback in the event loop.
        self._loop.call_soon(self._step, context=self._context)

        # The task step function executes the coroutine until it finishes,
        # raises an exception or returns a future. If a future was returned,
        # the task will await its completion (or exception). If the task is
        # cancelled while it awaits a future, this future must also be
        # cancelled in order for the cancellation to be successful.
        self._future_to_await: asyncio.Future | None = None

        self._cancelled = False  # PYSIDE-2644; see _step
        self._cancel_count = 0
        self._cancel_message: str | None = None
        # Store traceback in case of Exception. Useful when exception happens in coroutine
        self._tb: str | None = None

        # https://docs.python.org/3/library/asyncio-extending.html#task-lifetime-support
        asyncio._register_task(self)  # type: ignore[arg-type]

    def __repr__(self) -> str:
        state: str = "Unknown"
        if self._state == futures.QAsyncioFuture.FutureState.PENDING:
            state = "Pending"
        elif self._state == futures.QAsyncioFuture.FutureState.DONE_WITH_RESULT:
            state = "Done"
        elif self._state == futures.QAsyncioFuture.FutureState.DONE_WITH_EXCEPTION:
            state = f"Done with exception ({repr(self._exception)})"
        elif self._state == futures.QAsyncioFuture.FutureState.CANCELLED:
            state = "Cancelled"

        return f"Task '{self.get_name()}' with state: {state}"

    class QtTaskApiMisuseError(Exception):
        pass

    def set_result(self, result: Any) -> None:  # type: ignore[override]
        # This function is not inherited from the Future APIs.
        raise QAsyncioTask.QtTaskApiMisuseError("Tasks cannot set results")

    def set_exception(self, exception: Any) -> None:  # type: ignore[override]
        # This function is not inherited from the Future APIs.
        raise QAsyncioTask.QtTaskApiMisuseError("Tasks cannot set exceptions")

    def _step(self,
              exception_or_future: BaseException | futures.QAsyncioFuture | None = None) -> None:
        """
        The step function is the heart of a task. It is scheduled in the event
        loop repeatedly, executing the coroutine "step" by "step" (i.e.,
        iterating through the asynchronous generator) until it finishes with an
        exception or successfully. Each step can optionally receive an
        exception or a future as a result from a previous step to handle.
        """

        if self.done():
            return
        result = None
        self._future_to_await = None

        if self._cancelled:
            exception_or_future = asyncio.CancelledError(self._cancel_message)
            self._cancelled = False

        if asyncio.futures.isfuture(exception_or_future):
            try:
                exception_or_future.result()
            except BaseException as e:
                exception_or_future = e

        try:
            asyncio._enter_task(self._loop, self)  # type: ignore[arg-type]

            # It is at this point that the coroutine is resumed for the current
            # step (i.e. asynchronous generator iteration). It will now be
            # executed until it yields (and potentially returns a future),
            # raises an exception, is cancelled, or finishes successfully.

            if isinstance(exception_or_future, BaseException):
                # If the coroutine doesn't handle this exception, it propagates
                # to the caller.
                result = self._coro.throw(exception_or_future)
            else:
                result = self._coro.send(None)
        except StopIteration as e:
            self._state = futures.QAsyncioFuture.FutureState.DONE_WITH_RESULT
            self._result = e.value
        except (concurrent.futures.CancelledError, asyncio.exceptions.CancelledError) as e:
            self._state = futures.QAsyncioFuture.FutureState.CANCELLED
            self._exception = e
        except BaseException as e:
            self._state = futures.QAsyncioFuture.FutureState.DONE_WITH_EXCEPTION
            self._exception = e
            self._tb = traceback.format_exc()
        else:
            if asyncio.futures.isfuture(result):
                # If the coroutine yields a future, the task will await its
                # completion, and at that point the step function will be
                # called again.
                result.add_done_callback(
                    self._step, context=self._context)  # type: ignore[arg-type]

                # The task will await the completion (or exception) of this
                # future. If the task is cancelled while it awaits a future,
                # this future must also be cancelled.
                self._future_to_await = result

                if self._cancelled:
                    # PYSIDE-2644: If the task was cancelled at this step and a
                    # new future was created to be awaited, then it should be
                    # cancelled as well. Otherwise, in some scenarios like a
                    # loop inside the task and with bad timing, if the new
                    # future is not cancelled, the task would continue running
                    # in this loop despite having been cancelled. This bad
                    # timing can occur especially if the first future finishes
                    # very quickly.
                    self._future_to_await.cancel(self._cancel_message)
            elif result is None:
                # If no future was yielded, we schedule the step function again
                # without any arguments.
                self._loop.call_soon(self._step, context=self._context)
            else:
                # This is not supposed to happen.
                exception = RuntimeError(f"Bad task result: {result}")
                self._loop.call_soon(self._step, exception, context=self._context)
        finally:
            asyncio._leave_task(self._loop, self)  # type: ignore[arg-type]

            if self._exception:
                message = str(self._exception)
                if message == "None":
                    message = ""
                else:
                    message = "An exception occurred during task execution"
                self._loop.call_exception_handler({
                    "message": message,
                    "exception": self._exception,
                    "task": self,
                    "future": (exception_or_future
                               if asyncio.futures.isfuture(exception_or_future)
                               else None),
                    "traceback": self._tb
                })

            if self.done():
                self._schedule_callbacks()

                # https://docs.python.org/3/library/asyncio-extending.html#task-lifetime-support
                asyncio._unregister_task(self)  # type: ignore[arg-type]

    def get_stack(self, *, limit=None) -> list[Any]:
        # TODO
        raise NotImplementedError("QtTask.get_stack is not implemented")

    def print_stack(self, *, limit=None, file=None) -> None:
        # TODO
        raise NotImplementedError("QtTask.print_stack is not implemented")

    def get_coro(self) -> collections.abc.Generator | collections.abc.Coroutine:
        return self._coro

    def get_name(self) -> str:
        return self._name

    def set_name(self, value) -> None:
        self._name = str(value)

    def cancel(self, msg: str | None = None) -> bool:
        if self.done():
            return False
        self._cancel_count += 1
        self._cancel_message = msg
        if self._future_to_await is not None:
            # A task that is awaiting a future must also cancel this future in
            # order for the cancellation to be successful.
            self._future_to_await.cancel(msg)
        self._cancelled = True  # PYSIDE-2644; see _step
        return True

    def uncancel(self) -> int:
        if self._cancel_count > 0:
            self._cancel_count -= 1
        return self._cancel_count

    def cancelling(self) -> int:
        return self._cancel_count