fred-oss 0.25.0__tar.gz → 0.27.0__tar.gz

{fred_oss-0.25.0/src/main/fred_oss.egg-info → fred_oss-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-oss
-Version: 0.25.0
+Version: 0.27.0
 Summary: FREDOSS
 Home-page: https://fred.fahera.mx
 Author: Fahera Research, Education, and Development

{fred_oss-0.25.0 → fred_oss-0.27.0}/src/main/fred/future/callback/_function.py

@@ -1,4 +1,5 @@
 from typing import (
+    Any,
     Callable,
     TypeVar,
 )
@@ -15,5 +16,15 @@ class CallbackFunction(CallbackInterface[A]):
         self.function = function
         self.kwargs = kwargs
 
-    def execute(self, future_id: str, output: EitherMonad.Either[A]):
-        self.function(output, **self.kwargs)
+    def _on_start(self, future_id: str) -> Any:
+        return self.function(
+            future_id=future_id,
+            **self.kwargs
+        )
+
+    def _on_complete(self, future_id: str, output: EitherMonad.Either[A]) -> Any:
+        return self.function(
+            output=output,
+            future_id=future_id,
+            **self.kwargs
+        )

fred_oss-0.27.0/src/main/fred/future/callback/interface.py

@@ -0,0 +1,51 @@
+from threading import Thread
+from typing import (
+    Generic,
+    TypeVar,
+    Optional,
+)
+
+from fred.settings import logger_manager
+from fred.monad.catalog import EitherMonad
+
+logger = logger_manager.get_logger(__name__)
+
+A = TypeVar("A")
+
+
+class CallbackInterface(Generic[A]):
+    
+    def _on_start(self, future_id: str):
+        raise NotImplementedError
+    
+    def _on_complete(self, future_id: str, output: EitherMonad.Either[A]):
+        raise NotImplementedError
+    
+    def run(self, future_id: str, blocking: bool = False, output: Optional[EitherMonad.Either[A]] = None) -> Optional[Thread]:
+        """Executes the callback with the provided output and handles any exceptions.
+        Args:
+            output (EitherMonad.Either[A]): The output to be passed to the callback.
+        Returns:
+            bool: True if the callback executed successfully, False otherwise.
+        """
+        # TODO: Consider using a richer return type to capture more details about the execution
+        #  and optionally propagate the callback return value.
+        try:
+            match output:
+                case None:
+                    thread = Thread(
+                        target=lambda: self._on_start(future_id=future_id),
+                        daemon=True
+                    )
+                case EitherMonad.Either():
+                    thread = Thread(
+                        target=lambda: self._on_complete(future_id=future_id, output=output),
+                        daemon=True
+                    )
+            thread.start()
+            if blocking:
+                thread.join()
+            return thread
+        except Exception as e:
+            logger.error(f"Callback execution failed on future '{future_id}': {e}")
+            return None

{fred_oss-0.25.0 → fred_oss-0.27.0}/src/main/fred/future/impl.py

@@ -6,6 +6,7 @@ from typing import (
 )
 
 from fred.settings import logger_manager
+from fred.future.settings import FRD_FUTURE_DEFAULT_EXPIRATION
 from fred.future.callback.interface import CallbackInterface
 from fred.monad.interface import MonadInterface
 from fred.monad.catalog import EitherMonad
@@ -59,6 +60,7 @@ class Future(MonadInterface[A]):
     def __init__(
             self,
             function: Callable[..., A],
+            on_start: Optional[CallbackInterface] = None,
             on_complete: Optional[CallbackInterface] = None,
             **kwargs
         ):
@@ -83,6 +85,7 @@ class Future(MonadInterface[A]):
             target=lambda: future.apply(
                 function=function,
                 on_complete=on_complete,
+                on_start=on_start,
                 **kwargs
             ),
             daemon=True,
@@ -217,3 +220,44 @@ class Future(MonadInterface[A]):
         Returns: Future[B]: A new Future containing the transformed result.
         """
         return self.flat_map(function=lambda value: type(self).from_value(function(value)))
+
+    @classmethod
+    def pullsync(
+            cls,
+            future_id: str,
+            delay: float = 0.001,
+            delay_incr: float = 0.001,
+            delay_max: float = 30,
+            timeout: float = FRD_FUTURE_DEFAULT_EXPIRATION,
+            on_complete: Optional[CallbackInterface] = None,
+            **kwargs
+        ) -> 'Future[A]':
+        """Pulls an existing future from the backend storage by its ID.
+        This method allows for retrieving and interacting with a future
+        that was previously created and stored in the backend.
+
+        Args:
+            future_id (str): The unique identifier of the future to be pulled.
+            delay (float): Initial delay between checks for the future's completion.
+            delay_incr (float): Incremental increase in delay after each check.
+            delay_max (float): Maximum delay between checks.
+            timeout (float): Maximum time to wait for the future to complete.
+            on_complete (Optional[CallbackInterface]): An optional callback to be executed
+                                                      when the future completes.
+            **kwargs: Additional keyword arguments to be passed to the Future constructor.
+        Returns:
+            Future[A]: A Future instance representing the pulled future.
+        """
+        from fred.future.utils import pull_future_result
+
+        return cls(
+            function=lambda: pull_future_result(
+                future_id=future_id,
+                delay=delay,
+                delay_incr=delay_incr,
+                delay_max=delay_max,
+                timeout=timeout,
+            ),
+            on_complete=on_complete,
+            **kwargs
+        )

{fred_oss-0.25.0 → fred_oss-0.27.0}/src/main/fred/future/result.py

@@ -166,6 +166,7 @@ class FutureUndefinedPending(FutureResult[A]):
     def apply(
             self,
             function: Callable[..., A],
+            on_start: Optional[CallbackInterface] = None,
             on_complete: Optional[CallbackInterface] = None,
             **kwargs
         ) -> 'FutureDefined[A]':
@@ -187,6 +188,7 @@ class FutureUndefinedPending(FutureResult[A]):
         )
         return fip.exec(
             function=function,
+            on_start=on_start,
             on_complete=on_complete,
             **kwargs
         )
@@ -212,6 +214,7 @@ class FutureUndefinedInProgress(FutureResult[A]):
     def exec(
             self,
             function: Callable[..., A],
+            on_start: Optional[CallbackInterface] = None,
             on_complete: Optional[CallbackInterface] = None,
             fail: bool = False,
             **kwargs,
@@ -230,6 +233,11 @@ class FutureUndefinedInProgress(FutureResult[A]):
         Returns:
             FutureDefined[A]: A new instance of FutureDefined representing the completed state of the Future.
         """
+        # Execute on_start callback if provided
+        on_start_thread = (
+            logger.debug(f"Future[{self.future_id}] executing on_start callback")
+            or on_start.run(future_id=self.future_id, blocking=False)
+        ) if on_start else None
         try:
             ok = False
             match function(**kwargs):
@@ -260,7 +268,9 @@ class FutureUndefinedInProgress(FutureResult[A]):
         # wrapped on an Either monad so the user can handle success/failure as needed.
         if on_complete:
             logger.debug(f"Future[{self.future_id}] executing on_complete callback")
-            on_complete.run(future_id=self.future_id, output=value)
+            on_complete.run(future_id=self.future_id, output=value, blocking=True)
+        if on_start_thread:
+            on_start_thread.join()
         return future_defined
 
 

fred_oss-0.27.0/src/main/fred/future/utils.py

@@ -0,0 +1,39 @@
+import time
+from typing import TypeVar, Optional
+
+from fred.future.settings import FRD_FUTURE_DEFAULT_EXPIRATION
+
+A = TypeVar("A")
+
+
+def pull_future_result(
+        future_id: str,
+        delay: float = 0.001,
+        delay_incr: float = 0.001,
+        delay_max: float = 30,
+        timeout: float = FRD_FUTURE_DEFAULT_EXPIRATION,
+    ) -> A:
+    from fred.future.impl import FutureResult, FutureUndefinedInProgress, FutureUndefinedPending
+
+    if timeout <= 0:
+        raise ValueError(f"Pull operation for future_id '{future_id}' has timed out.")
+
+    match FutureResult.from_backend(future_id=future_id):
+        case None:
+            raise ValueError(f"No future found with ID '{future_id}'")
+        case FutureResult(value=value):
+            return value.resolve()
+        case FutureUndefinedPending() | FutureUndefinedInProgress():
+            # If the future is not yet defined, wait for it to complete
+            time.sleep(delay)
+            # Increase the delay for the next check to avoid busy waiting (exponential backoff) capped at delay_max
+            return pull_future_result(
+                future_id=future_id,
+                delay=(delay + delay_incr) if delay < delay_max else delay_max,
+                delay_incr=delay,
+                delay_max=delay_max,
+                # TODO: Consider using a more precise timeout mechanism based on elapsed time
+                timeout=timeout - delay,
+            )
+        case _:
+            raise ValueError(f"Unknown future state for ID '{future_id}'")

fred_oss-0.27.0/src/main/fred/version

@@ -0,0 +1 @@
+0.27.0

{fred_oss-0.25.0 → fred_oss-0.27.0/src/main/fred_oss.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-oss
-Version: 0.25.0
+Version: 0.27.0
 Summary: FREDOSS
 Home-page: https://fred.fahera.mx
 Author: Fahera Research, Education, and Development

{fred_oss-0.25.0 → fred_oss-0.27.0}/src/main/fred_oss.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ src/main/fred/future/__init__.py
 src/main/fred/future/impl.py
 src/main/fred/future/result.py
 src/main/fred/future/settings.py
+src/main/fred/future/utils.py
 src/main/fred/future/callback/__init__.py
 src/main/fred/future/callback/_function.py
 src/main/fred/future/callback/catalog.py

fred_oss-0.25.0/src/main/fred/future/callback/interface.py

@@ -1,33 +0,0 @@
-from typing import (
-    Generic,
-    TypeVar,
-)
-
-from fred.settings import logger_manager
-from fred.monad.catalog import EitherMonad
-
-logger = logger_manager.get_logger(__name__)
-
-A = TypeVar("A")
-
-
-class CallbackInterface(Generic[A]):
-    
-    def execute(self, future_id: str, output: EitherMonad.Either[A]):
-        raise NotImplementedError()
-    
-    def run(self, future_id: str, output: EitherMonad.Either[A]) -> bool:
-        """Executes the callback with the provided output and handles any exceptions.
-        Args:
-            output (EitherMonad.Either[A]): The output to be passed to the callback.
-        Returns:
-            bool: True if the callback executed successfully, False otherwise.
-        """
-        # TODO: Consider using a richer return type to capture more details about the execution
-        #  and optionally propagate the callback return value.
-        try:
-            self.execute(future_id=future_id, output=output)
-            return True
-        except Exception as e:
-            logger.error(f"Callback execution failed on future '{future_id}': {e}")
-            return False

fred_oss-0.25.0/src/main/fred/version

@@ -1 +0,0 @@
-0.25.0