reactivex 4.1.0__py3-none-any.whl → 5.0.0a2__py3-none-any.whl

reactivex/observable/mixins/testing.py

@@ -0,0 +1,193 @@
+"""Testing operators mixin for Observable."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
+
+from reactivex import typing
+
+if TYPE_CHECKING:
+    from reactivex.observable import Observable
+
+_T = TypeVar("_T", covariant=True)
+
+
+class TestingMixin(Generic[_T]):
+    """Mixin providing testing operators for Observable.
+
+    This mixin adds operators that test properties of observable sequences,
+    including checking conditions, emptiness, and equality.
+    """
+
+    def _as_observable(self) -> Observable[_T]:
+        """Cast mixin instance to Observable preserving type parameter.
+
+        This is safe because this mixin is only ever used as part of the Observable
+        class through multiple inheritance. At runtime, `self` in mixin methods will
+        always be an Observable[_T] instance. The type checker cannot infer this
+        because it analyzes mixins in isolation.
+
+        Returns:
+            The instance cast to Observable[_T] for type-safe method access.
+        """
+        return cast("Observable[_T]", self)
+
+    def all(self, predicate: typing.Predicate[_T]) -> Observable[bool]:
+        """Check if all elements satisfy a condition.
+
+        Determines whether all elements of an observable sequence satisfy
+        a condition.
+
+        Examples:
+            Fluent style:
+            >>> result = source.all(lambda x: x > 0)
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.all(lambda x: x > 0))
+
+        Args:
+            predicate: A function to test each element for a condition.
+
+        Returns:
+            An observable sequence containing a single boolean value
+            indicating whether all elements in the source sequence pass
+            the test in the specified predicate.
+
+        See Also:
+            - :func:`all <reactivex.operators.all>`
+            - :meth:`some`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.all(predicate))
+
+    def some(self, predicate: typing.Predicate[_T] | None = None) -> Observable[bool]:
+        """Check if some elements satisfy a condition.
+
+        Determines whether some element of an observable sequence satisfies
+        a condition if present, else if some items are in the sequence.
+
+        Examples:
+            Fluent style:
+            >>> result = source.some(lambda x: x > 10)
+            >>> result = source.some()  # Check if sequence is not empty
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.some(lambda x: x > 10))
+
+        Args:
+            predicate: A function to test each element for a condition.
+                If not specified, checks if the sequence contains any elements.
+
+        Returns:
+            An observable sequence containing a single boolean value
+            indicating whether at least one element in the source sequence
+            passes the test (or whether the sequence is non-empty if no
+            predicate is specified).
+
+        See Also:
+            - :func:`some <reactivex.operators.some>`
+            - :meth:`all`
+            - :meth:`is_empty`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.some(predicate))
+
+    def is_empty(self) -> Observable[bool]:
+        """Check if the sequence is empty.
+
+        Determines whether an observable sequence is empty.
+
+        Examples:
+            Fluent style:
+            >>> result = source.is_empty()
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.is_empty())
+
+        Returns:
+            An observable sequence containing a single boolean value
+            indicating whether the source sequence is empty.
+
+        See Also:
+            - :func:`is_empty <reactivex.operators.is_empty>`
+            - :meth:`some`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.is_empty())
+
+    def contains(
+        self, value: Any, comparer: typing.Comparer[Any] | None = None
+    ) -> Observable[bool]:
+        """Check if the sequence contains a value.
+
+        Determines whether an observable sequence contains a specified
+        element with an optional equality comparer.
+
+        Examples:
+            Fluent style:
+            >>> result = source.contains(42)
+            >>> result = source.contains("hello", lambda a, b: a.lower() == b.lower())
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.contains(42))
+
+        Args:
+            value: The value to locate in the source sequence.
+            comparer: An equality comparer to compare elements.
+
+        Returns:
+            An observable sequence containing a single boolean value
+            indicating whether the source sequence contains an element
+            that has the specified value.
+
+        See Also:
+            - :func:`contains <reactivex.operators.contains>`
+            - :meth:`some`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.contains(value, comparer))
+
+    def sequence_equal(
+        self,
+        second: Observable[_T] | Iterable[_T],
+        comparer: typing.Comparer[_T] | None = None,
+    ) -> Observable[bool]:
+        """Check if two sequences are equal.
+
+        Determines whether two sequences are equal by comparing the
+        elements pairwise using a specified equality comparer.
+
+        Examples:
+            Fluent style:
+            >>> result = source.sequence_equal(other_observable)
+            >>> result = source.sequence_equal([1, 2, 3])
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.sequence_equal(other_observable))
+
+        Args:
+            second: Second observable sequence or iterable to compare.
+            comparer: Comparer used to compare elements of both sequences.
+
+        Returns:
+            An observable sequence that contains a single boolean value
+            which indicates whether both sequences are of equal length and
+            their corresponding elements are equal according to the
+            specified comparer.
+
+        See Also:
+            - :func:`sequence_equal <reactivex.operators.sequence_equal>`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.sequence_equal(second, comparer))

reactivex/observable/mixins/time_based.py

@@ -0,0 +1,209 @@
+"""Time-based operators mixin for Observable."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
+
+from reactivex import abc, typing
+
+if TYPE_CHECKING:
+    from reactivex.observable import Observable
+
+
+_T = TypeVar("_T", covariant=True)
+
+
+class TimeBasedMixin(Generic[_T]):
+    """Mixin providing time-based operators for Observable.
+
+    This mixin adds operators that work with time, including sampling and debouncing.
+    """
+
+    def _as_observable(self) -> Observable[_T]:
+        """Cast mixin instance to Observable preserving type parameter.
+
+        This is safe because this mixin is only ever used as part of the Observable
+        class through multiple inheritance. At runtime, `self` in mixin methods will
+        always be an Observable[_T] instance. The type checker cannot infer this
+        because it analyzes mixins in isolation.
+
+        Returns:
+            The instance cast to Observable[_T] for type-safe method access.
+        """
+        return cast("Observable[_T]", self)
+
+    def sample(
+        self,
+        sampler: typing.RelativeTime | Observable[Any],
+        scheduler: abc.SchedulerBase | None = None,
+    ) -> Observable[_T]:
+        """Sample the sequence at intervals.
+
+        Samples the observable sequence at each interval.
+
+        Examples:
+            Fluent style:
+            >>> result = source.sample(1.0)
+            >>> result = source.sample(trigger_observable)
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.sample(1.0))
+
+        Args:
+            sampler: Interval or observable that triggers sampling.
+            scheduler: Scheduler to use for timing intervals.
+
+        Returns:
+            Sampled observable sequence.
+
+        See Also:
+            - :func:`sample <reactivex.operators.sample>`
+            - :meth:`throttle_first`
+            - :meth:`debounce`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.sample(sampler, scheduler))
+
+    def debounce(
+        self,
+        duetime: typing.RelativeTime,
+        scheduler: abc.SchedulerBase | None = None,
+    ) -> Observable[_T]:
+        """Debounce the sequence.
+
+        Ignores values from an observable sequence which are followed by another
+        value before duetime.
+
+        Examples:
+            Fluent style:
+            >>> result = source.debounce(0.5)
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.debounce(0.5))
+
+        Args:
+            duetime: Duration of the debounce period for each value.
+            scheduler: Scheduler to use for timing debounce.
+
+        Returns:
+            The debounced sequence.
+
+        See Also:
+            - :func:`debounce <reactivex.operators.debounce>`
+            - :meth:`throttle_first`
+            - :meth:`sample`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.debounce(duetime, scheduler))
+
+    def throttle_first(
+        self,
+        window_duration: typing.RelativeTime,
+        scheduler: abc.SchedulerBase | None = None,
+    ) -> Observable[_T]:
+        """Emit only first item in each time window.
+
+        Returns an Observable that emits only the first item emitted by
+        the source Observable during sequential time windows of a specified
+        duration.
+
+        Examples:
+            Fluent style:
+            >>> result = source.throttle_first(1.0)
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.throttle_first(1.0))
+
+        Args:
+            window_duration: Time to wait before emitting another value.
+            scheduler: Scheduler to use for timing windows.
+
+        Returns:
+            An observable sequence that emits only the first item in each window.
+
+        See Also:
+            - :func:`throttle_first <reactivex.operators.throttle_first>`
+            - :meth:`debounce`
+            - :meth:`sample`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(
+            ops.throttle_first(window_duration, scheduler)
+        )
+
+    def throttle_with_mapper(
+        self,
+        throttle_duration_mapper: typing.Callable[[Any], Observable[Any]],
+    ) -> Observable[_T]:
+        """Throttle with custom duration selector.
+
+        Ignores values from an observable sequence which are followed by
+        another value within a computed throttle duration.
+
+        Examples:
+            Fluent style:
+            >>> result = source.throttle_with_mapper(lambda x: rx.timer(x * 0.1))
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(
+            ...     ops.throttle_with_mapper(lambda x: rx.timer(x * 0.1))
+            ... )
+
+        Args:
+            throttle_duration_mapper: Function to compute throttle duration
+                for each item.
+
+        Returns:
+            The throttled sequence.
+
+        See Also:
+            - :func:`throttle_with_mapper <reactivex.operators.throttle_with_mapper>`
+            - :meth:`debounce`
+            - :meth:`throttle_first`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(
+            ops.throttle_with_mapper(throttle_duration_mapper)
+        )
+
+    def throttle_with_timeout(
+        self,
+        duetime: typing.RelativeTime,
+        scheduler: abc.SchedulerBase | None = None,
+    ) -> Observable[_T]:
+        """Throttle with timeout (alias for debounce).
+
+        Ignores values from an observable sequence which are followed by another
+        value before duetime. This is an alias for debounce.
+
+        Examples:
+            Fluent style:
+            >>> result = source.throttle_with_timeout(0.5)
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.throttle_with_timeout(0.5))
+
+        Args:
+            duetime: Duration of the throttle period for each value.
+            scheduler: Scheduler to use for timing throttle.
+
+        Returns:
+            The throttled sequence.
+
+        See Also:
+            - :func:`throttle_with_timeout <reactivex.operators.throttle_with_timeout>`
+            - :meth:`debounce`
+            - :meth:`throttle_first`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.throttle_with_timeout(duetime, scheduler))