PyPlumIO 0.6.1__py3-none-any.whl → 0.6.2__py3-none-any.whl

pyplumio/filters.py

@@ -7,6 +7,7 @@ from collections.abc import Callable
 from contextlib import suppress
 from copy import copy
 from decimal import Decimal
+from functools import wraps
 import logging
 import math
 import time
@@ -21,8 +22,8 @@ from typing import (
     runtime_checkable,
 )
 
-from pyplumio.helpers.event_manager import Callback
-from pyplumio.parameters import Parameter
+from pyplumio.helpers.event_manager import EventCallback
+from pyplumio.parameters import Number, Parameter
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -62,38 +63,41 @@ class SupportsComparison(Protocol):
         """Compare a value."""
 
 
-Comparable = TypeVar("Comparable", Parameter, SupportsFloat, SupportsComparison)
+_ComparableT = TypeVar("_ComparableT", Parameter, SupportsFloat, SupportsComparison)
 
 DEFAULT_TOLERANCE: Final = 1e-6
 
 
 @overload
-def is_close(old: Parameter, new: Parameter, tolerance: None = None) -> bool: ...
+def is_close(old: Parameter, new: Parameter, *, tolerance: None = None) -> bool: ...
 
 
 @overload
 def is_close(
-    old: SupportsFloat, new: SupportsFloat, tolerance: float = DEFAULT_TOLERANCE
+    old: SupportsFloat, new: SupportsFloat, *, tolerance: float = DEFAULT_TOLERANCE
 ) -> bool: ...
 
 
 @overload
 def is_close(
-    old: SupportsComparison, new: SupportsComparison, tolerance: None = None
+    old: SupportsComparison, new: SupportsComparison, *, tolerance: None = None
 ) -> bool: ...
 
 
 def is_close(
-    old: Comparable, new: Comparable, tolerance: float | None = DEFAULT_TOLERANCE
+    old: _ComparableT, new: _ComparableT, *, tolerance: float | None = DEFAULT_TOLERANCE
 ) -> bool:
     """Check if value is significantly changed."""
-    if isinstance(old, Parameter) and isinstance(new, Parameter):
-        return new.update_pending.is_set() or old.values.__ne__(new.values)
+    if isinstance(new, Parameter) and new.update_pending.is_set():
+        return False
 
     if tolerance and isinstance(old, SupportsFloat) and isinstance(new, SupportsFloat):
-        return not math.isclose(old, new, abs_tol=tolerance)
+        return math.isclose(old, new, abs_tol=tolerance)
+
+    if isinstance(old, Parameter) and isinstance(new, Parameter):
+        return old.values.__eq__(new.values)
 
-    return old.__ne__(new)
+    return old.__eq__(new)
 
 
 @overload
@@ -119,18 +123,40 @@ def diffence_between(
     return None
 
 
+_Numeric: TypeAlias = float | int | Decimal | Number
+
+
+def numeric_only(func: Callable) -> Callable:
+    """Mark filter as numeric only.
+
+    Ensure that value passed to filter when used as callable is numeric
+    otherwise raise TypeError.
+    """
+
+    @wraps(func)
+    def wrapper(instance: Filter, new_value: _Numeric) -> Any:
+        """Wrap __call__ method and add numeric check to it."""
+        if not isinstance(new_value, _Numeric):
+            raise TypeError(
+                f"{instance.__class__.__name__.capitalize()} filter can only be used "
+                f"with numeric values, got {type(new_value).__name__}: {new_value}"
+            )
+
+        return func(instance, new_value)
+
+    return wrapper
+
+
 class Filter(ABC):
     """Represents a filter."""
 
-    __slots__ = ("_callback", "_value")
+    __slots__ = ("_callback",)
 
-    _callback: Callback
-    _value: Any
+    _callback: EventCallback
 
-    def __init__(self, callback: Callback) -> None:
+    def __init__(self, callback: EventCallback) -> None:
         """Initialize a new filter."""
         self._callback = callback
-        self._value = UNDEFINED
 
     def __hash__(self) -> int:
         """Return a hash of the filter based on its callback."""
@@ -160,12 +186,14 @@ class _Aggregate(Filter):
 
     __slots__ = ("_values", "_sample_size", "_timeout", "_last_call_time")
 
-    _values: list[float | int | Decimal]
+    _values: list[_Numeric]
     _sample_size: int
     _timeout: float
     _last_call_time: float
 
-    def __init__(self, callback: Callback, seconds: float, sample_size: int) -> None:
+    def __init__(
+        self, callback: EventCallback, seconds: float, sample_size: int
+    ) -> None:
         """Initialize a new aggregate filter."""
         super().__init__(callback)
         self._last_call_time = time.monotonic()
@@ -173,14 +201,9 @@ class _Aggregate(Filter):
         self._sample_size = sample_size
         self._values = []
 
-    async def __call__(self, new_value: Any) -> Any:
+    @numeric_only
+    async def __call__(self, new_value: _Numeric) -> Any:
         """Set a new value for the callback."""
-        if not isinstance(new_value, float | int | Decimal):
-            raise TypeError(
-                "Aggregate filter can only be used with numeric values, got "
-                f"{type(new_value).__name__}: {new_value}"
-            )
-
         current_time = time.monotonic()
         self._values.append(new_value)
         time_since_call = current_time - self._last_call_time
@@ -194,7 +217,7 @@ class _Aggregate(Filter):
             return result
 
 
-def aggregate(callback: Callback, seconds: float, sample_size: int) -> _Aggregate:
+def aggregate(callback: EventCallback, seconds: float, sample_size: int) -> _Aggregate:
     """Create a new aggregate filter.
 
     A callback function will be called with a sum of values collected
@@ -203,7 +226,7 @@ def aggregate(callback: Callback, seconds: float, sample_size: int) -> _Aggregat
 
     :param callback: A callback function to be awaited once filter
         conditions are fulfilled
-    :type callback: Callback
+    :type callback: EventCallback
     :param seconds: A callback will be awaited with a sum of values
         aggregated over this amount of seconds.
     :type seconds: float
@@ -222,19 +245,34 @@ class _Clamp(Filter):
     Calls callback with a value clamped between specified boundaries.
     """
 
-    __slots__ = ("_min_value", "_max_value")
+    __slots__ = ("_min_value", "_max_value", "_ignore_out_of_range")
 
     _min_value: float
     _max_value: float
-
-    def __init__(self, callback: Callback, min_value: float, max_value: float) -> None:
+    _ignore_out_of_range: bool
+
+    def __init__(
+        self,
+        callback: EventCallback,
+        min_value: float,
+        max_value: float,
+        *,
+        ignore_out_of_range: bool = False,
+    ) -> None:
         """Initialize a new Clamp filter."""
         super().__init__(callback)
         self._min_value = min_value
         self._max_value = max_value
+        self._ignore_out_of_range = ignore_out_of_range
 
-    async def __call__(self, new_value: Any) -> Any:
+    @numeric_only
+    async def __call__(self, new_value: _Numeric) -> Any:
         """Set a new value for the callback."""
+        if self._ignore_out_of_range and (
+            new_value < self._min_value or new_value > self._max_value
+        ):
+            return
+
         if new_value < self._min_value:
             return await self._callback(self._min_value)
 
@@ -244,25 +282,36 @@ class _Clamp(Filter):
         return await self._callback(new_value)
 
 
-def clamp(callback: Callback, min_value: float, max_value: float) -> _Clamp:
+def clamp(
+    callback: EventCallback,
+    min_value: float,
+    max_value: float,
+    *,
+    ignore_out_of_range: bool = False,
+) -> _Clamp:
     """Create a new clamp filter.
 
     A callback function will be called and passed value clamped
     between specified boundaries.
 
     :param callback: A callback function to be awaited on new value
-    :type callback: Callback
+    :type callback: EventCallback
     :param min_value: A lower boundary
     :type min_value: float
     :param max_value: An upper boundary
     :type max_value: float
+    :param ignore_out_of_range: If `True`, values outside of
+        specified boundaries will be ignored, defaults to `False`
+    :type ignore_out_of_range: bool, optional
     :return: An instance of callable filter
     :rtype: _Clamp
     """
-    return _Clamp(callback, min_value, max_value)
+    return _Clamp(
+        callback, min_value, max_value, ignore_out_of_range=ignore_out_of_range
+    )
 
 
-_FilterT: TypeAlias = Callable[[Any], bool]
+_FilterFunc: TypeAlias = Callable[[Any], bool]
 
 
 class _Custom(Filter):
@@ -273,22 +322,22 @@ class _Custom(Filter):
     returns true.
     """
 
-    __slots__ = ("_filter_fn",)
+    __slots__ = ("_filter_func",)
 
-    _filter_fn: _FilterT
+    _filter_func: _FilterFunc
 
-    def __init__(self, callback: Callback, filter_fn: _FilterT) -> None:
+    def __init__(self, callback: EventCallback, filter_func: _FilterFunc) -> None:
         """Initialize a new custom filter."""
         super().__init__(callback)
-        self._filter_fn = filter_fn
+        self._filter_func = filter_func
 
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        if self._filter_fn(new_value):
+        if self._filter_func(new_value):
             await self._callback(new_value)
 
 
-def custom(callback: Callback, filter_fn: _FilterT) -> _Custom:
+def custom(callback: EventCallback, filter_func: _FilterFunc) -> _Custom:
     """Create a new custom filter.
 
     A callback function will be called when a user-defined filter
@@ -298,16 +347,93 @@ def custom(callback: Callback, filter_fn: _FilterT) -> _Custom:
     :param callback: A callback function to be awaited when
         filter function return true
     :type callback: Callback
-    :param filter_fn: Filter function, that will be called with a
+    :param filter_func: Filter function, that will be called with a
         value and should return `True` to await filter's callback
-    :type filter_fn: Callable[[Any], bool]
+    :type filter_func: Callable[[Any], bool]
     :return: An instance of callable filter
     :rtype: _Custom
     """
-    return _Custom(callback, filter_fn)
+    return _Custom(callback, filter_func)
+
+
+class _Throttle(Filter):
+    """Represents a throttle filter.
+
+    Calls a callback only when certain amount of seconds passed
+    since the last call.
+    """
+
+    __slots__ = ("_last_called", "_timeout")
+
+    _last_called: float | None
+    _timeout: float
+
+    def __init__(self, callback: EventCallback, seconds: float) -> None:
+        """Initialize a new throttle filter."""
+        super().__init__(callback)
+        self._last_called = None
+        self._timeout = seconds
+
+    async def __call__(self, new_value: Any) -> Any:
+        """Set a new value for the callback."""
+        current_timestamp = time.monotonic()
+        if (
+            self._last_called is None
+            or (current_timestamp - self._last_called) >= self._timeout
+        ):
+            self._last_called = current_timestamp
+            return await self._callback(new_value)
+
+
+def throttle(callback: EventCallback, seconds: float) -> _Throttle:
+    """Create a new throttle filter.
+
+    A callback function will only be called once a certain amount of
+    seconds passed since the last call.
+
+    :param callback: A callback function that will be awaited once
+        filter conditions are fulfilled
+    :type callback: EventCallback
+    :param seconds: A callback will be awaited at most once per
+        this amount of seconds
+    :type seconds: float
+    :return: An instance of callable filter
+    :rtype: _Throttle
+    """
+    return _Throttle(callback, seconds)
 
 
-class _Deadband(Filter):
+class ComparisonFilter(Filter):
+    """Represents a filter that compares current and previous values."""
+
+    __slots__ = ("_value",)
+
+    _value: Any
+
+    def __init__(self, callback: EventCallback) -> None:
+        """Initialize a new comparison filter."""
+        self._value = UNDEFINED
+        super().__init__(callback)
+
+    def is_undefined(self) -> bool:
+        """Check if current value is undefined."""
+        return True if self._value == UNDEFINED else False
+
+    @property
+    def value(self) -> Any:
+        """Return filter value."""
+        return self._value
+
+    @value.setter
+    def value(self, value: Any) -> None:
+        """Set filter value."""
+        if isinstance(value, Parameter):
+            self._value = copy(value)
+        else:
+            self._value = value
+
+
+class _Deadband(ComparisonFilter):
     """Represents a deadband filter.
 
     Calls a callback only when value is significantly changed from the
@@ -318,34 +444,29 @@ class _Deadband(Filter):
 
     _tolerance: float
 
-    def __init__(self, callback: Callback, tolerance: float) -> None:
+    def __init__(self, callback: EventCallback, tolerance: float) -> None:
         """Initialize a new value changed filter."""
         self._tolerance = tolerance
         super().__init__(callback)
 
-    async def __call__(self, new_value: Any) -> Any:
+    @numeric_only
+    async def __call__(self, new_value: _Numeric) -> Any:
         """Set a new value for the callback."""
-        if not isinstance(new_value, float | int | Decimal):
-            raise TypeError(
-                "Deadband filter can only be used with numeric values, got "
-                f"{type(new_value).__name__}: {new_value}"
-            )
-
-        if self._value == UNDEFINED or is_close(
-            self._value, new_value, tolerance=self._tolerance
+        if self.is_undefined() or not is_close(
+            self.value, new_value, tolerance=self._tolerance
         ):
-            self._value = new_value
+            self.value = new_value
             return await self._callback(new_value)
 
 
-def deadband(callback: Callback, tolerance: float) -> _Deadband:
+def deadband(callback: EventCallback, tolerance: float) -> _Deadband:
     """Create a new deadband filter.
 
     A callback function will only be called when the value is significantly changed
     from the previous callback call.
 
     :param callback: A callback function to be awaited on significant value change
-    :type callback: Callback
+    :type callback: EventCallback
     :param tolerance: The minimum difference required to trigger the callback
     :type tolerance: float
     :return: An instance of callable filter
@@ -354,7 +475,7 @@ def deadband(callback: Callback, tolerance: float) -> _Deadband:
     return _Deadband(callback, tolerance)
 
 
-class _Debounce(Filter):
+class _Debounce(ComparisonFilter):
     """Represents a debounce filter.
 
     Calls a callback only when value is stabilized across multiple
@@ -366,7 +487,7 @@ class _Debounce(Filter):
     _calls: int
     _min_calls: int
 
-    def __init__(self, callback: Callback, min_calls: int) -> None:
+    def __init__(self, callback: EventCallback, min_calls: int) -> None:
         """Initialize a new debounce filter."""
         super().__init__(callback)
         self._calls = 0
@@ -374,27 +495,25 @@ class _Debounce(Filter):
 
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        if self._value == UNDEFINED or is_close(self._value, new_value):
+        if self.is_undefined() or not is_close(self.value, new_value):
             self._calls += 1
         else:
             self._calls = 0
 
-        if self._value == UNDEFINED or self._calls >= self._min_calls:
-            self._value = (
-                copy(new_value) if isinstance(new_value, Parameter) else new_value
-            )
+        if self.is_undefined() or self._calls >= self._min_calls:
+            self.value = new_value
             self._calls = 0
             return await self._callback(new_value)
 
 
-def debounce(callback: Callback, min_calls: int) -> _Debounce:
+def debounce(callback: EventCallback, min_calls: int) -> _Debounce:
     """Create a new debounce filter.
 
     A callback function will only be called once the value is stabilized
     across multiple filter calls.
 
     :param callback: A callback function to be awaited on value change
-    :type callback: Callback
+    :type callback: EventCallback
     :param min_calls: Value shouldn't change for this amount of
         filter calls
     :type min_calls: int
@@ -404,7 +523,7 @@ def debounce(callback: Callback, min_calls: int) -> _Debounce:
     return _Debounce(callback, min_calls)
 
 
-class _Delta(Filter):
+class _Delta(ComparisonFilter):
     """Represents a difference filter.
 
     Calls a callback with a difference between two subsequent values.
@@ -414,19 +533,14 @@ class _Delta(Filter):
 
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        if self._value == UNDEFINED or is_close(self._value, new_value):
-            old_value = self._value
-            self._value = (
-                copy(new_value) if isinstance(new_value, Parameter) else new_value
-            )
-            if (
-                self._value != UNDEFINED
-                and (difference := diffence_between(old_value, new_value)) is not None
-            ):
+        if self.is_undefined() or not is_close(self.value, new_value):
+            old_value = self.value
+            self.value = new_value
+            if (difference := diffence_between(old_value, new_value)) is not None:
                 return await self._callback(difference)
 
 
-def delta(callback: Callback) -> _Delta:
+def delta(callback: EventCallback) -> _Delta:
     """Create a new difference filter.
 
     A callback function will be called with a difference between two
@@ -434,14 +548,14 @@ def delta(callback: Callback) -> _Delta:
 
     :param callback: A callback function that will be awaited with
         difference between values in two subsequent calls
-    :type callback: Callback
+    :type callback: EventCallback
     :return: An instance of callable filter
     :rtype: _Delta
     """
     return _Delta(callback)
 
 
-class _OnChange(Filter):
+class _OnChange(ComparisonFilter):
     """Represents a value changed filter.
 
     Calls a callback only when value is changed from the
@@ -450,20 +564,14 @@ class _OnChange(Filter):
 
     __slots__ = ()
 
-    def __init__(self, callback: Callback) -> None:
-        """Initialize a new value changed filter."""
-        super().__init__(callback)
-
     async def __call__(self, new_value: Any) -> Any:
         """Set a new value for the callback."""
-        if self._value == UNDEFINED or is_close(self._value, new_value):
-            self._value = (
-                copy(new_value) if isinstance(new_value, Parameter) else new_value
-            )
+        if self.is_undefined() or not is_close(self.value, new_value):
+            self.value = new_value
             return await self._callback(new_value)
 
 
-def on_change(callback: Callback) -> _OnChange:
+def on_change(callback: EventCallback) -> _OnChange:
     """Create a new value changed filter.
 
     A callback function will only be called if the value is changed from the
@@ -477,55 +585,10 @@ def on_change(callback: Callback) -> _OnChange:
     return _OnChange(callback)
 
 
-class _Throttle(Filter):
-    """Represents a throttle filter.
-
-    Calls a callback only when certain amount of seconds passed
-    since the last call.
-    """
-
-    __slots__ = ("_last_called", "_timeout")
-
-    _last_called: float | None
-    _timeout: float
-
-    def __init__(self, callback: Callback, seconds: float) -> None:
-        """Initialize a new throttle filter."""
-        super().__init__(callback)
-        self._last_called = None
-        self._timeout = seconds
-
-    async def __call__(self, new_value: Any) -> Any:
-        """Set a new value for the callback."""
-        current_timestamp = time.monotonic()
-        if (
-            self._last_called is None
-            or (current_timestamp - self._last_called) >= self._timeout
-        ):
-            self._last_called = current_timestamp
-            return await self._callback(new_value)
-
-
-def throttle(callback: Callback, seconds: float) -> _Throttle:
-    """Create a new throttle filter.
-
-    A callback function will only be called once a certain amount of
-    seconds passed since the last call.
-
-    :param callback: A callback function that will be awaited once
-        filter conditions are fulfilled
-    :type callback: Callback
-    :param seconds: A callback will be awaited at most once per
-        this amount of seconds
-    :type seconds: float
-    :return: An instance of callable filter
-    :rtype: _Throttle
-    """
-    return _Throttle(callback, seconds)
-
-
 __all__ = [
     "Filter",
+    "ComparisonFilter",
+    "numeric_only",
     "aggregate",
     "clamp",
     "custom",