simetri.helpers.modifiers

  1from random import random, choice
  2import inspect
  3
  4from ..graphics.all_enums import Control, State
  5
  6
  7class Modifier:
  8    """Used to modify the properties of a Batch object.
  9
 10    Attributes:
 11        function (callable): The function to modify the property.
 12        life_span (int): The number of times the modifier can be applied.
 13        randomness (float or callable): Determines the randomness of the modification.
 14        condition (bool or callable): Condition to apply the modification.
 15        state (State): The current state of the modifier.
 16        _d_state (dict): Mapping of control states to modifier states.
 17        count (int): Counter for the number of times the modifier has been applied.
 18        args (tuple): Additional arguments for the function.
 19        kwargs (dict): Additional keyword arguments for the function.
 20    """
 21
 22    def __init__(
 23        self, function, life_span=10000, randomness=1.0, condition=True, *args, **kwargs
 24    ):
 25        """
 26        Args:
 27            function (callable): The function to modify the property.
 28            life_span (int, optional): The number of times the modifier can be applied. Defaults to 10000.
 29            randomness (float or callable, optional): Determines the randomness of the modification. Defaults to 1.0.
 30            condition (bool or callable, optional): Condition to apply the modification. Defaults to True.
 31            *args: Additional arguments for the function.
 32            **kwargs: Additional keyword arguments for the function.
 33        """
 34        self.function = function  # it can be a list of functions
 35        signature = inspect.signature(function)
 36        self.n_func_args = len(signature.parameters)
 37        self.life_span = life_span
 38        self.randomness = randomness
 39        self.condition = condition
 40        self.state = State.INITIAL
 41        self._d_state = {
 42            Control.INITIAL: State.INITIAL,
 43            Control.STOP: State.STOPPED,
 44            Control.PAUSE: State.PAUSED,
 45            Control.RESUME: State.RUNNING,
 46            Control.RESTART: State.RESTARTING,
 47        }
 48        self.count = 0
 49        self.args = args
 50        self.kwargs = kwargs
 51
 52    def __repr__(self):
 53        """Returns a string representation of the Modifier object.
 54
 55        Returns:
 56            str: String representation of the Modifier object.
 57        """
 58        return (
 59            f"Modifier(function:{self.function}, lifespan:{self.life_span},"
 60            f"randomness:{self.randomness})"
 61        )
 62
 63    def __str__(self):
 64        """Returns a string representation of the Modifier object.
 65
 66        Returns:
 67            str: String representation of the Modifier object.
 68        """
 69        return self.__repr__()
 70
 71    def set_state(self, control):
 72        """Sets the state of the modifier based on the control value.
 73
 74        Args:
 75            control (Control): The control value to set the state.
 76        """
 77        self.state = self._d_state[control]
 78
 79    def get_value(self, obj, target, *args, **kwargs):
 80        """Gets the value from an object or callable.
 81
 82        Args:
 83            obj (object or callable): The object or callable to get the value from.
 84            target (object): The target object.
 85            *args: Additional arguments for the callable.
 86            **kwargs: Additional keyword arguments for the callable.
 87
 88        Returns:
 89            object: The value obtained from the object or callable.
 90        """
 91        if callable(obj):
 92            res = obj(target, *args, **kwargs)
 93            if res in Control:
 94                self.set_state(res)
 95        else:
 96            res = obj
 97        return res
 98
 99    def apply(self, element):
100        """Applies the modifier to an element.
101
102        If a function returns a control value, it will be applied to the modifier.
103        Control.STOP, Control.PAUSE, Control.RESUME, and Control.RESTART are the only control values.
104        Functions should have the following signature:
105        def funct(target, modifier, *args, **kwargs):
106
107        Args:
108            element (object): The element to apply the modifier to.
109        """
110        if self.can_continue(element):
111            if self.n_func_args == 1:
112                self.function(element)
113            else:
114                self.function(element, self, *self.args, **self.kwargs)
115            self._update_state()
116        else:
117            self.state = State.STOPPED
118
119    def can_continue(self, target):
120        """Checks if the modifier can continue to be applied.
121
122        Args:
123            target (object): The target object.
124
125        Returns:
126            bool: True if the modifier can continue, False otherwise.
127        """
128        if callable(self.randomness):
129            randomness = self.get_value(self.randomness, target)
130        elif type(self.randomness) == float:
131            randomness = self.randomness >= random()
132        elif type(self.randomness) in [list, tuple]:
133            randomness = choice(self.randomness)
134
135        if callable(self.condition):
136            condition = self.get_value(self.condition, target)
137        else:
138            condition = self.condition
139
140        if callable(self.life_span):
141            life_span = self.get_value(self.life_span, target)
142        else:
143            life_span = self.life_span
144
145        if life_span > 0 and condition and randomness:
146            if self.state in [State.INITIAL, State.RUNNING, State.RESTARTING]:
147                res = True
148            else:
149                res = False
150        else:
151            res = False
152        return res
153
154    def _update_state(self):
155        """Updates the state of the modifier based on its life span and count."""
156        self.count += 1
157        if self.count == 1:
158            self.state = State.RUNNING
159        if self.life_span > 0:
160            if self.state == State.RESTARTING:
161                self.state = State.RUNNING
162            elif self.state == State.RUNNING:
163                self.life_span -= 1
164                if self.life_span == 0:
165                    self.state = State.STOPPED
166        else:
167            self.state = State.STOPPED
168
169    def stop(self):
170        """Stops the modifier."""
171        self.state = State.STOPPED