smallib 1.0.0__py3-none-any.whl

small/__init__.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+#
+#   SMALL: State Machine, Async Lock, Logger
+#
+#                                Written in 2026 by Moky <albert.moky@gmail.com>
+#
+# ==============================================================================
+# MIT License
+#
+# Copyright (c) 2026 Albert Moky
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ==============================================================================
+
+
+name = "SMALL"
+
+__author__ = 'Albert Moky'
+
+
+__all__ = [
+
+]

small/fsm/__init__.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+#
+#   Finite State Machine
+#
+#                                Written in 2021 by Moky <albert.moky@gmail.com>
+#
+# ==============================================================================
+# MIT License
+#
+# Copyright (c) 2021 Albert Moky
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ==============================================================================
+
+"""
+    Finite State Machine
+    ~~~~~~~~~~~~~~~~~~~~
+"""
+
+from .machine import Context, Transition, State, Machine, Delegate
+from .base import BaseTransition, BaseState, BaseMachine
+from .auto import AutoMachine
+
+
+name = "FSM"
+
+__author__ = 'Albert Moky'
+
+__all__ = [
+
+    'Context', 'Transition', 'State', 'Machine', 'Delegate',
+    'BaseTransition', 'BaseState', 'BaseMachine',
+    'AutoMachine',
+]

small/fsm/auto.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+#
+#   Finite State Machine
+#
+#                                Written in 2021 by Moky <albert.moky@gmail.com>
+#
+# ==============================================================================
+# MIT License
+#
+# Copyright (c) 2021 Albert Moky
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ==============================================================================
+
+from abc import ABC  # , abstractmethod
+
+from ..skywalker import PrimeMetronome
+
+from .machine import S, C, U, T
+from .base import BaseMachine
+
+
+# noinspection PyAbstractClass
+class AutoMachine(BaseMachine[C, T, S], ABC):
+
+    # @property  # Override
+    # @abstractmethod
+    # def context(self) -> C:
+    #     """ machine itself """
+    #     raise NotImplementedError(
+    #         f'Not implemented: {type(self).__module__}.{type(self).__name__}.context getter'
+    #     )
+
+    # Override
+    async def start(self) -> bool:
+        ok = await super().start()
+        timer = PrimeMetronome()
+        timer.add_ticker(ticker=self)
+        return ok
+
+    # Override
+    async def stop(self) -> bool:
+        timer = PrimeMetronome()
+        timer.remove_ticker(ticker=self)
+        return await super().stop()
+
+    # Override
+    async def pause(self) -> bool:
+        timer = PrimeMetronome()
+        timer.remove_ticker(ticker=self)
+        return await super().pause()
+
+    # Override
+    async def resume(self) -> bool:
+        ok = await super().resume()
+        timer = PrimeMetronome()
+        timer.add_ticker(ticker=self)
+        return ok

small/fsm/base.py

@@ -0,0 +1,290 @@
+# -*- coding: utf-8 -*-
+#
+#   Finite State Machine
+#
+#                                Written in 2021 by Moky <albert.moky@gmail.com>
+#
+# ==============================================================================
+# MIT License
+#
+# Copyright (c) 2021 Albert Moky
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ==============================================================================
+
+import time
+import weakref
+from abc import ABC, abstractmethod
+from enum import IntEnum
+from typing import List, Optional
+
+from ..utils import Timestamp, Duration
+
+from .machine import S, C, U, T
+from .machine import Transition, State, Machine, Delegate
+
+
+# noinspection PyAbstractClass
+class BaseTransition(Transition[C], ABC):
+    """ Transition with the index of target state """
+
+    def __init__(self, target: int):
+        super().__init__()
+        self.__target = target
+
+    @property
+    def target(self) -> int:
+        """ target state index """
+        return self.__target
+
+
+# noinspection PyAbstractClass
+class BaseState(State[C, T], ABC):
+    """ State with transitions """
+
+    def __init__(self, index: int):
+        super().__init__()
+        self.__index = index
+        self.__transitions: List[Transition[C]] = []
+
+    @property
+    def index(self) -> int:
+        return self.__index
+
+    def add_transition(self, transition: Transition[C]):
+        assert transition not in self.__transitions, 'transition exists: %s' % transition
+        self.__transitions.append(transition)
+
+    # Override
+    def evaluate(self, ctx: C, now: Timestamp) -> Optional[T]:
+        for trans in self.__transitions:
+            if trans.evaluate(ctx, now=now):
+                # OK, get target state from this transition
+                return trans
+
+
+class MachineStatus(IntEnum):
+    """ Machine Status """
+    STOPPED = 0
+    RUNNING = 1
+    PAUSED = 2
+
+
+class BaseMachine(Machine[C, T, S], ABC):
+
+    def __init__(self):
+        super().__init__()
+        self.__states: List[S] = []
+        self.__current = -1  # current state index
+        self.__status = MachineStatus.STOPPED
+        self.__delegate_ref: Optional[weakref.ReferenceType] = None
+
+    @property
+    def delegate(self) -> Optional[Delegate[C, T, S]]:
+        ref = self.__delegate_ref
+        if ref is not None:
+            return ref()
+
+    @delegate.setter
+    def delegate(self, handler: Delegate[C, T, S]):
+        self.__delegate_ref = None if handler is None else weakref.ref(handler)
+
+    @property  # protected
+    @abstractmethod
+    def context(self) -> C:
+        """ machine itself """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.context getter'
+        )
+
+    #
+    #   States
+    #
+    def add_state(self, state: BaseState[C, T]) -> Optional[S]:
+        index = state.index
+        assert index >= 0, 'state index error: %d' % index
+        count = len(self.__states)
+        if index < count:
+            # WARNING: return old state that was replaced
+            old = self.__states[index]
+            self.__states[index] = state
+            return old
+        # filling empty spaces
+        spaces = index - count
+        for i in range(spaces):
+            self.__states.append(None)
+        # append the new state to the tail
+        self.__states.append(state)
+
+    def get_state(self, index: int) -> Optional[State[C, T]]:
+        return self.__states[index]
+
+    @property  # protected
+    def default_state(self) -> Optional[State[C, T]]:
+        return self.__states[0]
+
+    # protected
+    def get_target_state(self, transition: BaseTransition[C]) -> State[C, T]:
+        # Get target state of this transition
+        return self.__states[transition.target]
+
+    @property  # Override
+    def current_state(self) -> Optional[State[C, T]]:
+        index = self.__current
+        if 0 <= index:  # and index < len(self.__states):
+            return self.__states[index]
+
+    @current_state.setter  # private
+    def current_state(self, state: BaseState[C, T]):
+        self.__current = -1 if state is None else state.index
+
+    async def __change_state(self, state: Optional[State[C, T]], now: Timestamp) -> bool:
+        """
+        Exit current state, and enter new state
+
+        :param state:   next state
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        old = self.current_state
+        if old == state:
+            # Log.info('[FSM] state not change: %s', state)
+            return False
+        machine = self.context
+        delegate = self.delegate
+        #
+        #  Events before state changed
+        #
+        if delegate is not None:
+            # prepare for changing current state to the new one,
+            # the delegate can get old state via ctx if need
+            await delegate.enter_state(state, machine, now=now)
+        if old is not None:
+            await old.on_exit(state, machine, now=now)
+        #
+        #  Change current state
+        #
+        self.current_state = state
+        #
+        #  Events after state changed
+        #
+        if state is not None:
+            await state.on_enter(old, machine, now=now)
+        if delegate is not None:
+            # handle after the current state changed,
+            # the delegate can get new state via ctx if need
+            await delegate.exit_state(old, machine, now=now)
+        return True
+
+    #
+    #   Actions
+    #
+
+    # Override
+    async def start(self) -> bool:
+        if self.__status != MachineStatus.STOPPED:
+            # running or paused
+            # cannot start again
+            return False
+        now = time.time()
+        ok = await self.__change_state(state=self.default_state, now=now)
+        # assert ok, 'failed to change default state'
+        self.__status = MachineStatus.RUNNING
+        return ok
+
+    # Override
+    async def stop(self) -> bool:
+        if self.__status == MachineStatus.STOPPED:
+            # stopped,
+            # cannot stop again
+            return False
+        self.__status = MachineStatus.STOPPED
+        now = time.time()
+        return await self.__change_state(state=None, now=now)  # force current state to None
+
+    # Override
+    async def pause(self) -> bool:
+        if self.__status != MachineStatus.RUNNING:
+            # paused or stopped,
+            # cannot pause now
+            return False
+        now = time.time()
+        machine = self.context
+        current = self.current_state
+        #
+        #  Events before state paused
+        #
+        if current is not None:
+            await current.on_pause(machine, now=now)
+        #
+        #  Pause state
+        #
+        self.__status = MachineStatus.PAUSED
+        #
+        #  Events after state paused
+        #
+        delegate = self.delegate
+        if delegate is not None:
+            await delegate.pause_state(current, machine, now=now)
+        return True
+
+    # Override
+    async def resume(self) -> bool:
+        if self.__status != MachineStatus.PAUSED:
+            # running or stopped,
+            # cannot resume now
+            return False
+        now = time.time()
+        machine = self.context
+        current = self.current_state
+        #
+        #  Events before state resumed
+        #
+        delegate = self.delegate
+        if delegate is not None:
+            await delegate.resume_state(current, machine, now=now)
+        #
+        #  Resume state
+        #
+        self.__status = MachineStatus.RUNNING
+        #
+        #  Events after state resumed
+        #
+        if current is not None:
+            await current.on_resume(machine, now=now)
+        return True
+
+    #
+    #   Ticker
+    #
+
+    # Override
+    async def tick(self, now: Timestamp, elapsed: Duration):
+        if self.__status != MachineStatus.RUNNING:
+            # paused or stopped,
+            # cannot evaluate the transitions of current state
+            return
+        current = self.current_state
+        if current is not None:
+            machine = self.context
+            trans = current.evaluate(machine, now=now)
+            if trans is not None:
+                # assert isinstance(trans, BaseTransition), 'transition error: %s' % trans
+                target = self.get_target_state(transition=trans)
+                assert target is not None, 'target state error: %s' % trans.target
+                await self.__change_state(state=target, now=now)

small/fsm/machine.py

@@ -0,0 +1,226 @@
+# -*- coding: utf-8 -*-
+#
+#   Finite State Machine
+#
+#                                Written in 2021 by Moky <albert.moky@gmail.com>
+#
+# ==============================================================================
+# MIT License
+#
+# Copyright (c) 2021 Albert Moky
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ==============================================================================
+
+from abc import ABC, abstractmethod
+from typing import Optional, TypeVar, Generic
+
+from ..utils import Timestamp
+from ..skywalker import Ticker
+
+S = TypeVar('S')  # State
+C = TypeVar('C')  # Context
+U = TypeVar('U')
+T = TypeVar('T')  # Transition
+
+
+class Context(ABC):
+    """ State Machine Context """
+    pass
+
+
+class Transition(ABC, Generic[C]):
+    """ State Transition """
+
+    @abstractmethod
+    def evaluate(self, ctx: C, now: Timestamp) -> bool:
+        """
+        Evaluate the current state
+
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        :return True when current state should be changed
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.evaluate()'
+        )
+
+
+class State(ABC, Generic[C, T]):
+    """ Finite State """
+
+    @abstractmethod
+    def evaluate(self, ctx: C, now: Timestamp) -> Optional[T]:
+        """
+        Called by machine.tick() to evaluate each transitions
+
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        :return success transition, or None to stay the current state
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.evaluate()'
+        )
+
+    @abstractmethod
+    async def on_enter(self, old, ctx: C, now: Timestamp):
+        """
+        Called after new state entered
+
+        :param old:     previous state
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.on_enter()'
+        )
+
+    @abstractmethod
+    async def on_exit(self, new, ctx: C, now: Timestamp):
+        """
+        Called before old state exited
+
+        :param new:     next state
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.on_exit()'
+        )
+
+    @abstractmethod
+    async def on_pause(self, ctx: C, now: Timestamp):
+        """
+        Called before current state paused
+
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.on_pause()'
+        )
+
+    @abstractmethod
+    async def on_resume(self, ctx: C, now: Timestamp):
+        """
+        Called after current state resumed
+
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.on_resume()'
+        )
+
+
+class Delegate(ABC, Generic[C, T, S]):
+    """ State Machine Delegate """
+
+    @abstractmethod
+    async def enter_state(self, state: Optional[S], ctx: C, now: Timestamp):
+        """
+        Called before enter new state
+        (get current state from context)
+
+        :param state:   new state
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.enter_state()'
+        )
+
+    @abstractmethod
+    async def exit_state(self, state: Optional[S], ctx: C, now: Timestamp):
+        """
+        Called after exit old state
+        (get current state from context)
+
+        :param state:   old state
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.exit_state()'
+        )
+
+    @abstractmethod
+    async def pause_state(self, state: Optional[S], ctx: C, now: Timestamp):
+        """
+        Called after pause this state
+
+        :param state:   current state
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.pause_state()'
+        )
+
+    @abstractmethod
+    async def resume_state(self, state: Optional[S], ctx: C, now: Timestamp):
+        """
+        Called before resume this state
+
+        :param state:   current state
+        :param ctx:     context (machine)
+        :param now:     current time (seconds from Jan 1, 1970 UTC)
+        """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.resume_state()'
+        )
+
+
+class Machine(Ticker, ABC, Generic[C, T, S]):
+    """ State Machine """
+
+    @property
+    @abstractmethod
+    def current_state(self) -> Optional[S]:
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.current_state getter'
+        )
+
+    @abstractmethod
+    async def start(self) -> bool:
+        """ Change current state to 'default' """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.start()'
+        )
+
+    @abstractmethod
+    async def stop(self) -> bool:
+        """ Change current state to null """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.stop()'
+        )
+
+    @abstractmethod
+    async def pause(self) -> bool:
+        """ Pause machine, current state not change """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.pause()'
+        )
+
+    @abstractmethod
+    async def resume(self) -> bool:
+        """ Resume machine with current state """
+        raise NotImplementedError(
+            f'Not implemented: {type(self).__module__}.{type(self).__name__}.resume()'
+        )