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

reactivex/observable/mixins/conditional.py

@@ -0,0 +1,135 @@
+"""Conditional operators mixin for Observable."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast, overload
+
+if TYPE_CHECKING:
+    from reactivex.observable import Observable
+
+
+_T = TypeVar("_T", covariant=True)
+_A = TypeVar("_A")
+
+
+class ConditionalMixin(Generic[_T]):
+    """Mixin providing conditional operators for Observable.
+
+    This mixin adds operators that conditionally process or emit elements
+    based on various conditions.
+    """
+
+    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)
+
+    @overload
+    def default_if_empty(self, default_value: _A) -> Observable[_T | _A]: ...
+
+    @overload
+    def default_if_empty(self) -> Observable[_T | None]: ...
+
+    def default_if_empty(self, default_value: Any = None) -> Observable[Any]:
+        """Return default value if observable is empty.
+
+        Returns the elements of the specified sequence or the specified value in
+        a singleton sequence if the sequence is empty.
+
+        Examples:
+            Fluent style:
+            >>> result = source.default_if_empty(42)
+            >>> result = source.default_if_empty()  # Defaults to None
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.default_if_empty(42))
+
+        Args:
+            default_value: The value to return if the sequence is empty.
+
+        Returns:
+            An observable sequence that contains the specified default value if
+            the source is empty; otherwise, the elements of the source.
+
+        See Also:
+            - :func:`default_if_empty <reactivex.operators.default_if_empty>`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.default_if_empty(default_value))
+
+    def find(
+        self, predicate: Callable[[_T, int, Observable[_T]], bool]
+    ) -> Observable[_T | None]:
+        """Find first element matching predicate.
+
+        Searches for an element that matches the conditions defined by the
+        specified predicate, and returns the first occurrence within the entire
+        Observable sequence.
+
+        Examples:
+            Fluent style:
+            >>> result = source.find(lambda x, i, obs: x > 3)
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.find(lambda x, i, obs: x > 3))
+
+        Args:
+            predicate: The predicate that defines the conditions of the element to
+                search for. Takes (value, index, source).
+
+        Returns:
+            An observable sequence with the first element that matches the conditions
+            defined by the specified predicate, if found; otherwise, None.
+
+        See Also:
+            - :func:`find <reactivex.operators.find>`
+            - :meth:`find_index`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.find(predicate))
+
+    def find_index(
+        self, predicate: Callable[[_T, int, Observable[_T]], bool]
+    ) -> Observable[int | None]:
+        """Find index of first element matching predicate.
+
+        Searches for an element that matches the conditions defined by the specified
+        predicate, and returns an Observable sequence with the zero-based index of
+        the first occurrence within the entire Observable sequence.
+
+        Examples:
+            Fluent style:
+            >>> result = source.find_index(lambda x, i, obs: x > 3)
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.find_index(lambda x, i, obs: x > 3))
+
+        Args:
+            predicate: The predicate that defines the conditions of the element to
+                search for. Takes (value, index, source).
+
+        Returns:
+            An observable sequence with the zero-based index of the first element
+            that matches the conditions; if not found, returns -1.
+
+        See Also:
+            - :func:`find_index <reactivex.operators.find_index>`
+            - :meth:`find`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.find_index(predicate))

reactivex/observable/mixins/error_handling.py

@@ -0,0 +1,130 @@
+"""Error handling operators mixin for Observable."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Generic, TypeVar, cast
+
+if TYPE_CHECKING:
+    from reactivex.observable import Observable
+
+
+_T = TypeVar("_T", covariant=True)
+
+
+class ErrorHandlingMixin(Generic[_T]):
+    """Mixin providing error handling operators for Observable.
+
+    This mixin adds operators that handle errors, retries, and fallback behavior
+    when observables encounter exceptions.
+    """
+
+    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 catch(
+        self,
+        handler: Observable[_T] | Callable[[Exception, Observable[_T]], Observable[_T]],
+    ) -> Observable[_T]:
+        """Handle errors by switching to another observable.
+
+        Continues an observable sequence that is terminated by an exception with
+        the next observable sequence.
+
+        Examples:
+            Fluent style:
+            >>> result = source.catch(fallback_observable)
+            >>> result = source.catch(lambda ex, src: handle_error(ex))
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.catch(fallback_observable))
+
+        Args:
+            handler: Exception handler function or a second observable sequence
+                used to produce results when an error occurs.
+
+        Returns:
+            An observable sequence containing the source sequence's elements,
+            followed by the elements of the handler sequence in case an exception
+            occurred.
+
+        See Also:
+            - :func:`catch <reactivex.operators.catch>`
+            - :meth:`retry`
+            - :meth:`on_error_resume_next`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.catch(handler))
+
+    def retry(self, retry_count: int | None = None) -> Observable[_T]:
+        """Retry on error.
+
+        Repeats the source observable sequence the specified number of times or
+        until it successfully terminates.
+
+        Examples:
+            Fluent style:
+            >>> result = source.retry(3)
+            >>> result = source.retry()  # Retry indefinitely
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.retry(3))
+
+        Args:
+            retry_count: Number of times to retry. If not specified, retries
+                indefinitely.
+
+        Returns:
+            An observable sequence producing the elements of the given sequence
+            repeatedly until it terminates successfully.
+
+        See Also:
+            - :func:`retry <reactivex.operators.retry>`
+            - :meth:`catch`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.retry(retry_count))
+
+    def on_error_resume_next(self, second: Observable[_T]) -> Observable[_T]:
+        """Continue with another observable on error or completion.
+
+        Continues an observable sequence that is terminated normally or by an
+        exception with the next observable sequence.
+
+        Examples:
+            Fluent style:
+            >>> result = source.on_error_resume_next(fallback)
+
+            Equivalent pipe style:
+            >>> from reactivex import operators as ops
+            >>> result = source.pipe(ops.on_error_resume_next(fallback))
+
+        Args:
+            second: Second observable sequence used to produce results after the
+                first sequence terminates.
+
+        Returns:
+            An observable sequence that concatenates the first and second sequence,
+            even if the first sequence terminates exceptionally.
+
+        See Also:
+            - :func:`on_error_resume_next <reactivex.operators.on_error_resume_next>`
+            - :meth:`catch`
+        """
+        from reactivex import operators as ops
+
+        return self._as_observable().pipe(ops.on_error_resume_next(second))