amulet-core 2.0a5__cp311-cp311-macosx_10_9_universal2.whl

amulet/utils/signal/_signal.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import logging
+from typing import (
+    Callable,
+    Any,
+    overload,
+    Protocol,
+    TYPE_CHECKING,
+    TypeVarTuple,
+    Generic,
+)
+from collections.abc import Sequence
+from weakref import WeakMethod
+from inspect import ismethod
+
+
+if TYPE_CHECKING:
+    import PySide6.QtCore  # type: ignore  # noqa
+
+
+CallArgs = TypeVarTuple("CallArgs")
+
+
+class SignalInstance(Protocol[*CallArgs]):
+    def connect(
+        self,
+        slot: Callable[[*CallArgs], None] | SignalInstance[*CallArgs] | None,
+        type: PySide6.QtCore.Qt.ConnectionType | None = ...,
+    ) -> None: ...
+
+    def disconnect(
+        self,
+        slot: Callable[[*CallArgs], None] | SignalInstance[*CallArgs] | None = None,
+    ) -> None: ...
+
+    def emit(self, *args: *CallArgs) -> None: ...
+
+
+_signal_instance_constructor: SignalInstanceConstructor | None = None
+
+
+# TODO: https://github.com/python/typing/issues/1216
+
+
+def create_signal_instance(
+    *types: type, instance: Any, name: str = "", arguments: Sequence[str] = ()
+) -> SignalInstance[*CallArgs]:
+    """Create a new signal instance"""
+    if _signal_instance_constructor is None:
+        set_signal_instance_constructor(get_fallback_signal_instance_constructor())
+        assert _signal_instance_constructor is not None
+    return _signal_instance_constructor(
+        types=types,
+        name=name,
+        arguments=arguments,
+        instance=instance,
+    )
+
+
+SignalInstanceCacheName = "_SignalCache"
+
+
+def _get_signal_instances(instance: Any) -> dict[Signal, SignalInstance]:
+    signal_instances: dict[Any, SignalInstance]
+    try:
+        signal_instances = getattr(instance, SignalInstanceCacheName)
+    except AttributeError:
+        signal_instances = {}
+        setattr(instance, SignalInstanceCacheName, signal_instances)
+    return signal_instances
+
+
+class Signal(Generic[*CallArgs]):
+    def __init__(self, *types: type, name: str = "", arguments: Sequence[str] = ()):
+        self._types = types
+        self._name = name
+        self._arguments = arguments
+
+    @overload
+    def __get__(self, instance: None, owner: Any | None) -> Signal[*CallArgs]: ...
+
+    @overload
+    def __get__(
+        self, instance: Any, owner: Any | None
+    ) -> SignalInstance[*CallArgs]: ...
+
+    def __get__(self, instance: Any, owner: Any) -> Any:
+        if instance is None:
+            return self
+        signal_instances = _get_signal_instances(instance)
+        if self not in signal_instances:
+            signal_instances[self] = create_signal_instance(
+                *self._types,
+                name=self._name,
+                arguments=self._arguments,
+                instance=instance,
+            )
+        return signal_instances[self]
+
+
+class SignalInstanceConstructor(Protocol[*CallArgs]):
+    def __call__(
+        self,
+        *,
+        types: tuple[type, ...],
+        name: str,
+        arguments: Sequence[str],
+        instance: Any,
+    ) -> SignalInstance[*CallArgs]: ...
+
+
+def set_signal_instance_constructor(constructor: SignalInstanceConstructor) -> None:
+    global _signal_instance_constructor
+    if _signal_instance_constructor is not None:
+        raise RuntimeError("Signal instance constructor has already been set.")
+    _signal_instance_constructor = constructor
+
+
+def get_fallback_signal_instance_constructor() -> SignalInstanceConstructor:
+    class FallbackSignalInstance(SignalInstance[*CallArgs]):
+        _callbacks: set[
+            Callable[[*CallArgs], None]
+            | WeakMethod[Callable[[*CallArgs], None]]
+            | FallbackSignalInstance[*CallArgs]
+        ]
+
+        def __init__(self, *types: type):
+            self._types = types
+            self._callbacks = set()
+
+        @staticmethod
+        def _wrap_slot(
+            slot: Callable[[*CallArgs], None] | SignalInstance[*CallArgs] | None
+        ) -> (
+            Callable[[*CallArgs], None]
+            | WeakMethod[Callable[[*CallArgs], None]]
+            | FallbackSignalInstance[*CallArgs]
+        ):
+            if ismethod(slot):
+                return WeakMethod(slot)  # type: ignore
+            elif isinstance(slot, FallbackSignalInstance) or callable(slot):
+                return slot  # type: ignore
+            else:
+                raise RuntimeError(f"{slot} is not a supported slot type.")
+
+        def connect(
+            self,
+            slot: Callable[[*CallArgs], None] | SignalInstance[*CallArgs] | None,
+            type: PySide6.QtCore.Qt.ConnectionType | None = None,
+        ) -> None:
+            if type is not None:
+                logging.warning(
+                    "FallbackSignalInstance does not support custom connection types. Using DirectConnection"
+                )
+            self._callbacks.add(self._wrap_slot(slot))
+
+        def disconnect(
+            self,
+            slot: Callable[[*CallArgs], None] | SignalInstance[*CallArgs] | None = None,
+        ) -> None:
+            self._callbacks.remove(self._wrap_slot(slot))
+
+        def emit(self, *args: *CallArgs) -> None:
+            if len(args) != len(self._types):
+                raise TypeError(
+                    f"SignalInstance{self._types}.emit expected {len(self._types)} argument(s), {len(args)} given."
+                )
+            for slot in self._callbacks:
+                try:
+                    if isinstance(slot, FallbackSignalInstance):
+                        slot.emit(*args)  # type: ignore
+                    elif isinstance(slot, WeakMethod):
+                        method = slot()
+                        if method is not None:
+                            method(*args)
+                    else:
+                        slot(*args)
+                except Exception as e:
+                    logging.error(e)
+
+    def fallback_signal_instance_constructor(
+        *,
+        types: tuple[type, ...],
+        name: str,
+        arguments: Sequence[str],
+        instance: Any,
+    ) -> FallbackSignalInstance[*CallArgs]:
+        return FallbackSignalInstance(*types)
+
+    return fallback_signal_instance_constructor
+
+
+def get_pyside6_signal_instance_constructor() -> SignalInstanceConstructor:
+    try:
+        from PySide6.QtCore import (
+            QObject,
+            Signal as PySide6_Signal,
+            SignalInstance as PySide6_SignalInstance,
+        )
+    except ImportError as e:
+        raise ImportError("Could not import PySide6") from e
+
+    QObjectCacheName = "_QObjectCache"
+
+    def pyside6_signal_instance_constructor(
+        *,
+        types: tuple[type, ...],
+        name: str,
+        arguments: Sequence[str],
+        instance: Any,
+    ) -> PySide6_SignalInstance:
+        if isinstance(instance, QObject):
+            return PySide6_Signal(
+                *types, name=name, arguments=list(arguments) if arguments else None
+            ).__get__(instance, QObject)
+        else:
+            signal_instances = _get_signal_instances(instance)
+            if QObjectCacheName not in signal_instances:
+                signal_instances[QObjectCacheName] = QObject()  # type: ignore
+            obj = signal_instances[QObjectCacheName]  # type: ignore
+            if not isinstance(obj, QObject):
+                raise RuntimeError
+            return PySide6_Signal(*types, name=name, arguments=arguments).__get__(
+                obj, QObject
+            )
+
+    return pyside6_signal_instance_constructor  # type: ignore

amulet/utils/signal/_signal.pyi

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import logging as logging
+import typing
+from collections.abc import Sequence
+from inspect import ismethod
+from typing import Any, Generic, Protocol, TypeVarTuple, overload
+from weakref import WeakMethod
+
+__all__ = [
+    "Any",
+    "CallArgs",
+    "Generic",
+    "Protocol",
+    "Sequence",
+    "Signal",
+    "SignalInstance",
+    "SignalInstanceCacheName",
+    "SignalInstanceConstructor",
+    "TypeVarTuple",
+    "WeakMethod",
+    "create_signal_instance",
+    "get_fallback_signal_instance_constructor",
+    "get_pyside6_signal_instance_constructor",
+    "ismethod",
+    "logging",
+    "overload",
+    "set_signal_instance_constructor",
+]
+
+class Signal(typing.Generic):
+    def __get__(self, instance: typing.Any, owner: typing.Any) -> typing.Any: ...
+    def __init__(
+        self, *types: type, name: str, arguments: typing.Sequence[str] = tuple()
+    ): ...
+
+class SignalInstance(typing.Protocol):
+    @classmethod
+    def __subclasshook__(cls, other): ...
+    def __init__(self, *args, **kwargs): ...
+    def connect(
+        self,
+        slot: typing.Callable[[*CallArgs], None] | SignalInstance[*CallArgs,] | None,
+        type: PySide6.QtCore.Qt.ConnectionType | None = ...,
+    ) -> None: ...
+    def disconnect(
+        self,
+        slot: (
+            typing.Callable[[*CallArgs], None] | SignalInstance[*CallArgs,] | None
+        ) = None,
+    ) -> None: ...
+    def emit(self, *args: *CallArgs) -> None: ...
+
+class SignalInstanceConstructor(typing.Protocol):
+    @classmethod
+    def __subclasshook__(cls, other): ...
+    def __call__(
+        self,
+        *,
+        types: tuple[type, ...],
+        name: str,
+        arguments: typing.Sequence[str],
+        instance: typing.Any,
+    ) -> SignalInstance[*CallArgs,]: ...
+    def __init__(self, *args, **kwargs): ...
+
+def _get_signal_instances(instance: typing.Any) -> dict[Signal, SignalInstance]: ...
+def create_signal_instance(
+    *types: type,
+    instance: typing.Any,
+    name: str,
+    arguments: typing.Sequence[str] = tuple(),
+) -> SignalInstance[*CallArgs,]:
+    """
+    Create a new signal instance
+    """
+
+def get_fallback_signal_instance_constructor() -> SignalInstanceConstructor: ...
+def get_pyside6_signal_instance_constructor() -> SignalInstanceConstructor: ...
+def set_signal_instance_constructor(constructor: SignalInstanceConstructor) -> None: ...
+
+CallArgs: typing.TypeVarTuple  # value = CallArgs
+SignalInstanceCacheName: str
+_signal_instance_constructor = None

amulet/utils/task_manager.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+from typing import Generic, TypeVar, Callable
+from abc import ABC, abstractmethod
+
+from .signal import Signal, SignalInstance
+
+
+T = TypeVar("T")
+
+
+class TaskCancelled(Exception):
+    """Exception to be raised by the callee when a task is cancelled.
+
+    The callee may define a custom return instead of using this.
+    """
+
+
+class AbstractCancelManager(ABC):
+    @abstractmethod
+    def cancel(self) -> None:
+        """Request the operation be canceled.
+
+        It is down to the operation to implement support for this.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def is_cancel_requested(self) -> bool:
+        """Has cancel been called to signal that the operation should be canceled."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def register_on_cancel(self, callback: Callable[[], None]) -> None:
+        """Register a function to get called when :meth:`cancel` is called."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def unregister_on_cancel(self, callback: Callable[[], None]) -> None:
+        """Unregister a registered function from being called when :meth:`cancel` is called."""
+        raise NotImplementedError
+
+
+class VoidCancelManager(AbstractCancelManager):
+    def cancel(self) -> None:
+        pass
+
+    def is_cancel_requested(self) -> bool:
+        return False
+
+    def register_on_cancel(self, callback: Callable[[], None]) -> None:
+        pass
+
+    def unregister_on_cancel(self, callback: Callable[[], None]) -> None:
+        pass
+
+
+class Pointer(Generic[T]):
+    value: T
+
+    def __init__(self, value: T) -> None:
+        self.value = value
+
+
+class _CancelManager(AbstractCancelManager):
+    def __init__(
+        self,
+        cancelled: Pointer[bool],
+        cancel_signal: SignalInstance[()],
+    ) -> None:
+        self._cancelled = cancelled
+        self._on_cancel = cancel_signal
+
+    def cancel(self) -> None:
+        self._cancelled.value = True
+        self._on_cancel.emit()
+
+    def is_cancel_requested(self) -> bool:
+        return self._cancelled.value
+
+    def register_on_cancel(self, callback: Callable[[], None]) -> None:
+        self._on_cancel.connect(callback)
+
+    def unregister_on_cancel(self, callback: Callable[[], None]) -> None:
+        self._on_cancel.disconnect(callback)
+
+
+class CancelManager(_CancelManager):
+    _cancel_signal = Signal[()]()
+
+    def __init__(self) -> None:
+        super().__init__(
+            Pointer[bool](False),
+            self._cancel_signal,
+        )
+
+
+class AbstractProgressManager(ABC):
+    @abstractmethod
+    def update_progress(self, progress: float) -> None:
+        """Notify the caller of the updated progress.
+
+        :param progress: The new progress to relay to the caller. 0.0-1.0
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def update_progress_text(self, text: str) -> None:
+        """Notify the caller of the updated progress.
+
+        :param text: The new message to relay to the caller.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_child(
+        self, progress_min: float, progress_max: float
+    ) -> AbstractProgressManager:
+        """Get a child ExecutionContext.
+
+        If calling multiple functions, this allows segmenting the reported time.
+
+        :param progress_min: The minimum progress for the child to use 0.0-1.0
+        :param progress_max: The maximum progress for the child to use 0.0-1.0
+        :return: A new ExecutionContext
+        """
+        raise NotImplementedError
+
+
+class VoidProgressManager(AbstractProgressManager):
+    def update_progress(self, progress: float) -> None:
+        pass
+
+    def update_progress_text(self, text: str) -> None:
+        pass
+
+    def get_child(
+        self, progress_min: float, progress_max: float
+    ) -> VoidProgressManager:
+        return self
+
+
+class _ProgressManager(AbstractProgressManager):
+    def __init__(
+        self,
+        progress_change: SignalInstance[float],
+        progress_text_change: SignalInstance[str],
+        progress_min: float,
+        progress_max: float,
+    ) -> None:
+        self._progress_change = progress_change
+        self._progress_text_change = progress_text_change
+        assert 0.0 <= progress_min <= progress_max <= 1.0
+        self._progress_min = progress_min
+        self._progress_delta = progress_max - progress_min
+
+    def update_progress(self, progress: float) -> None:
+        assert 0.0 <= progress <= 1.0
+        self._progress_change.emit(self._progress_min + progress * self._progress_delta)
+
+    def update_progress_text(self, text: str) -> None:
+        self._progress_text_change.emit(text)
+
+    def get_child(self, progress_min: float, progress_max: float) -> _ProgressManager:
+        assert 0.0 <= progress_min <= progress_max <= 1.0
+        return _ProgressManager(
+            self._progress_change,
+            self._progress_text_change,
+            self._progress_min + progress_min * self._progress_delta,
+            self._progress_min + progress_max * self._progress_delta,
+        )
+
+
+class ProgressManager(_ProgressManager):
+    progress_change = Signal[float](float)
+    progress_text_change = Signal[str](str)
+
+    def __init__(self) -> None:
+        super().__init__(
+            self.progress_change,
+            self.progress_text_change,
+            0.0,
+            1.0,
+        )
+
+
+class AbstractTaskManager(AbstractCancelManager, AbstractProgressManager, ABC):
+    pass
+
+
+class VoidTaskManager(VoidCancelManager, VoidProgressManager, AbstractTaskManager):
+    """An empty Execution Context that ignores all calls."""
+
+
+class _TaskManager(CancelManager, ProgressManager, AbstractTaskManager):
+    def __init__(
+        self,
+        cancelled: Pointer[bool],
+        cancel_signal: SignalInstance[()],
+        progress_change: SignalInstance[float],
+        progress_text_change: SignalInstance[str],
+        progress_min: float,
+        progress_max: float,
+    ) -> None:
+        _CancelManager.__init__(self, cancelled, cancel_signal)
+        _ProgressManager.__init__(
+            self,
+            progress_change,
+            progress_text_change,
+            progress_min,
+            progress_max,
+        )
+
+    def get_child(self, progress_min: float, progress_max: float) -> _TaskManager:
+        assert 0.0 <= progress_min <= progress_max <= 1.0
+        return _TaskManager(
+            self._cancelled,
+            self._on_cancel,
+            self._progress_change,
+            self._progress_text_change,
+            self._progress_min + progress_min * self._progress_delta,
+            self._progress_min + progress_max * self._progress_delta,
+        )
+
+
+class TaskManager(_TaskManager):
+    def __init__(self) -> None:
+        super().__init__(
+            Pointer[bool](False),
+            self._cancel_signal,
+            self.progress_change,
+            self.progress_text_change,
+            0.0,
+            1.0,
+        )

amulet/utils/task_manager.pyi

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import abc
+import typing
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+from amulet.utils.signal._signal import Signal, SignalInstance
+
+__all__ = [
+    "ABC",
+    "AbstractCancelManager",
+    "AbstractProgressManager",
+    "AbstractTaskManager",
+    "CancelManager",
+    "Generic",
+    "Pointer",
+    "ProgressManager",
+    "Signal",
+    "SignalInstance",
+    "T",
+    "TaskCancelled",
+    "TaskManager",
+    "TypeVar",
+    "VoidCancelManager",
+    "VoidProgressManager",
+    "VoidTaskManager",
+    "abstractmethod",
+]
+
+class AbstractCancelManager(abc.ABC):
+    def cancel(self) -> None:
+        """
+        Request the operation be canceled.
+
+                It is down to the operation to implement support for this.
+
+        """
+
+    def is_cancel_requested(self) -> bool:
+        """
+        Has cancel been called to signal that the operation should be canceled.
+        """
+
+    def register_on_cancel(self, callback: typing.Callable[[], None]) -> None:
+        """
+        Register a function to get called when :meth:`cancel` is called.
+        """
+
+    def unregister_on_cancel(self, callback: typing.Callable[[], None]) -> None:
+        """
+        Unregister a registered function from being called when :meth:`cancel` is called.
+        """
+
+class AbstractProgressManager(abc.ABC):
+    def get_child(
+        self, progress_min: float, progress_max: float
+    ) -> AbstractProgressManager:
+        """
+        Get a child ExecutionContext.
+
+                If calling multiple functions, this allows segmenting the reported time.
+
+                :param progress_min: The minimum progress for the child to use 0.0-1.0
+                :param progress_max: The maximum progress for the child to use 0.0-1.0
+                :return: A new ExecutionContext
+
+        """
+
+    def update_progress(self, progress: float) -> None:
+        """
+        Notify the caller of the updated progress.
+
+                :param progress: The new progress to relay to the caller. 0.0-1.0
+
+        """
+
+    def update_progress_text(self, text: str) -> None:
+        """
+        Notify the caller of the updated progress.
+
+                :param text: The new message to relay to the caller.
+
+        """
+
+class AbstractTaskManager(AbstractCancelManager, AbstractProgressManager, abc.ABC):
+    pass
+
+class CancelManager(_CancelManager):
+    @staticmethod
+    def _cancel_signal(*args, **kwargs): ...
+    def __init__(self) -> None: ...
+
+class Pointer(typing.Generic):
+    def __init__(self, value: T) -> None: ...
+
+class ProgressManager(_ProgressManager):
+    @staticmethod
+    def progress_change(*args, **kwargs): ...
+    @staticmethod
+    def progress_text_change(*args, **kwargs): ...
+    def __init__(self) -> None: ...
+
+class TaskCancelled(Exception):
+    """
+    Exception to be raised by the callee when a task is cancelled.
+
+        The callee may define a custom return instead of using this.
+
+    """
+
+class TaskManager(_TaskManager):
+    def __init__(self) -> None: ...
+
+class VoidCancelManager(AbstractCancelManager):
+    def cancel(self) -> None: ...
+    def is_cancel_requested(self) -> bool: ...
+    def register_on_cancel(self, callback: typing.Callable[[], None]) -> None: ...
+    def unregister_on_cancel(self, callback: typing.Callable[[], None]) -> None: ...
+
+class VoidProgressManager(AbstractProgressManager):
+    def get_child(
+        self, progress_min: float, progress_max: float
+    ) -> VoidProgressManager: ...
+    def update_progress(self, progress: float) -> None: ...
+    def update_progress_text(self, text: str) -> None: ...
+
+class VoidTaskManager(VoidCancelManager, VoidProgressManager, AbstractTaskManager):
+    """
+    An empty Execution Context that ignores all calls.
+    """
+
+class _CancelManager(AbstractCancelManager):
+    def __init__(
+        self, cancelled: Pointer[bool], cancel_signal: SignalInstance[()]
+    ) -> None: ...
+    def cancel(self) -> None: ...
+    def is_cancel_requested(self) -> bool: ...
+    def register_on_cancel(self, callback: typing.Callable[[], None]) -> None: ...
+    def unregister_on_cancel(self, callback: typing.Callable[[], None]) -> None: ...
+
+class _ProgressManager(AbstractProgressManager):
+    def __init__(
+        self,
+        progress_change: SignalInstance[float],
+        progress_text_change: SignalInstance[str],
+        progress_min: float,
+        progress_max: float,
+    ) -> None: ...
+    def get_child(
+        self, progress_min: float, progress_max: float
+    ) -> _ProgressManager: ...
+    def update_progress(self, progress: float) -> None: ...
+    def update_progress_text(self, text: str) -> None: ...
+
+class _TaskManager(CancelManager, ProgressManager, AbstractTaskManager):
+    def __init__(
+        self,
+        cancelled: Pointer[bool],
+        cancel_signal: SignalInstance[()],
+        progress_change: SignalInstance[float],
+        progress_text_change: SignalInstance[str],
+        progress_min: float,
+        progress_max: float,
+    ) -> None: ...
+    def get_child(self, progress_min: float, progress_max: float) -> _TaskManager: ...
+
+T: typing.TypeVar  # value = ~T