fred-oss 0.43.0__tar.gz → 0.45.0__tar.gz

{fred_oss-0.43.0/src/main/fred_oss.egg-info → fred_oss-0.45.0}/PKG-INFO

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

{fred_oss-0.43.0 → fred_oss-0.45.0}/src/main/fred/future/impl.py

@@ -1,3 +1,4 @@
+import time
 from threading import Thread
 from typing import (
     Callable,
@@ -63,6 +64,7 @@ class Future(MonadInterface[A]):
             on_start: Optional[CallbackInterface] = None,
             on_complete: Optional[CallbackInterface] = None,
             parent_id: Optional[str] = None,
+            broadcast: bool = False,
             **kwargs
         ):
         """Initializes a Future with the provided function to be executed asynchronously.
@@ -77,7 +79,11 @@ class Future(MonadInterface[A]):
                 All keyword arguments except 'future_id' are forwarded to the target function.
         """
         # Create a new available future
-        future = FutureUndefinedPending.auto(parent_id=parent_id, future_id=kwargs.pop("future_id", None))
+        future = FutureUndefinedPending.auto(
+            parent_id=parent_id,
+            broadcast=broadcast,
+            future_id=kwargs.pop("future_id", None),
+        )
         # Register the Future-ID and define the available future via the provided function.
         # Note: The 'apply' method is blocking by itself; thus, we run it in a separate thread.
         # Note: The thread is a daemon to ensure it does not block program exit.
@@ -199,8 +205,22 @@ class Future(MonadInterface[A]):
         return self.wait(timeout=timeout).resolve()
 
     @classmethod
-    def from_value(cls, val: A) -> 'Future[A]':
-        return Future(function=lambda: val)
+    def from_value(cls, val: A, **kwargs) -> 'Future[A]':
+        """
+        Creates a Future that is immediately resolved with the given value.
+
+        Args:
+            val (A): The value to resolve the Future with.
+            **kwargs: Additional keyword arguments forwarded to the Future constructor.
+                These may include parameters such as:
+                    - parent_id (Optional[str]): The parent future's ID.
+                    - expiration (Optional[float]): Expiration time for the future.
+                    - callback (Optional[CallbackInterface]): Callback to invoke on completion.
+                For a full list of accepted parameters, see the Future class documentation.
+        Returns:
+            Future[A]: A Future instance resolved with the provided value.
+        """
+        return Future(function=lambda: val, **kwargs)
     
     def flat_map(self, function: Callable[[A], 'Future[B]'], timeout: Optional[float] = None) -> 'Future[B]':
         """Chains the current future with another future-producing function.
@@ -276,6 +296,10 @@ class Future(MonadInterface[A]):
         Returns:
             Future[A]: A Future instance representing the pulled future.
         """
+        logger.warning(
+            "The 'pullsync' method is scheduled for deprecation and will be removed in future versions. "
+            "Please use the 'subscribe' method instead that uses a pubsub mechanism."
+        )
         from fred.future.utils import pull_future_result
 
         return cls(
@@ -289,6 +313,87 @@ class Future(MonadInterface[A]):
             on_complete=on_complete,
             **kwargs
         )
+
+    @classmethod
+    def subscribe(
+            cls,
+            future_id: str,
+            on_start: Optional[CallbackInterface] = None,
+            on_complete: Optional[CallbackInterface] = None,
+            retry_delay: float = 0.2,
+            retry: int = 3,
+    ) -> 'Future[A]':
+        """Subscribes to updates for an existing future using a publish-subscribe mechanism.
+        This method allows for receiving real-time updates about the future's state
+        and result without blocking.
+        Args:
+            future_id (str): The unique identifier of the future to subscribe to.
+            on_start (Optional[CallbackInterface]): An optional callback to be executed
+                                                   when the subscription starts.
+            on_complete (Optional[CallbackInterface]): An optional callback to be executed
+                                                      when the future completes.
+        Returns:
+            Future[A]: A Future instance that will execute the subscription logic.
+        """
+        # TODO: Consider adding a timeout parameter to avoid waiting indefinitely...
+        # TODO: There's a known issue where if the future completes before we subscribe,
+        #       we might miss the completion message.
+        # Define a closure that will handle incoming messages from the pub-sub channel
+        def closure():
+            for payload in FutureResult._get_bcast_channel(future_id=future_id).subscribe():
+                logger.info(f"Received pubsub message for future '{future_id}': {payload}")
+                if payload.get("type") != "message":
+                    continue
+                message = payload.get("data")
+                if not message:
+                    continue
+                match FutureResult.from_string(message):
+                    case FutureDefined(value=value):
+                        return value.resolve()
+                    case FutureUndefinedPending():
+                        continue
+                    case FutureUndefinedInProgress():
+                        continue
+                    case _:
+                        raise TypeError("Unknown FutureResult type")
+        shared_params = {
+            "parent_id": future_id,
+            "broadcast": False,
+            "on_start": on_start,
+            "on_complete": on_complete,
+        }
+        # Depending on the current state of the future, either return the resolved value
+        # or subscribe to the broadcast channel to wait for updates (via closure).
+        match FutureResult.from_backend(future_id=future_id):
+            case FutureDefined(value=value):
+                return cls(
+                    function=lambda: value.resolve(),
+                    **shared_params
+                )
+            case instance:
+                # The future-result can be None if the future_id does not exist
+                if not instance:
+                    if retry <= 0:
+                        raise ValueError(f"Future with ID '{future_id}' does not exist.")
+                    logger.error(f"Future with ID '{future_id}' does not exist; attempting to retry ({retry} retries left).")
+                    time.sleep(retry_delay)
+                    return cls.subscribe(
+                        future_id=future_id,
+                        on_start=on_start,
+                        on_complete=on_complete,
+                        retry_delay=retry_delay,
+                        retry=max(0, retry - 1),
+                    )
+                # If the future exists, but is not configured for broadcast, raise an error...
+                if not instance.broadcast:
+                    raise ValueError("Future is not configured for broadcast; cannot subscribe.")
+                # If the future exists and is configured for broadcast, subscribe to updates...
+                logger.info(f"Subscribing to future '{future_id}' via broadcast channel.")
+                return cls(
+                    function=closure,
+                    **shared_params
+                )
+
     def lineage(self) -> list[str]:
         """Retrieves the lineage of the future, tracing back through its parent futures.
         This method is useful for debugging and understanding the sequence of computations

{fred_oss-0.43.0 → fred_oss-0.45.0}/src/main/fred/future/result.py

@@ -20,7 +20,7 @@ from fred.future.settings import (
 from fred.future.callback.interface import CallbackInterface
 from fred.dao.service.catalog import ServiceCatalog
 from fred.utils.dateops import datetime_utcnow
-from fred.dao.comp.catalog import FredKeyVal
+from fred.dao.comp.catalog import FredKeyVal, FredQueue, FredPubSub
 from fred.monad.catalog import EitherMonad
 
 logger = logger_manager.get_logger(__name__)
@@ -30,6 +30,8 @@ A = TypeVar("A")
 
 class FutureBackend:
     keyval: type[FredKeyVal]
+    queue: type[FredQueue]
+    pubsub: type[FredPubSub]
 
     @classmethod
     def with_backend(cls, service: ServiceCatalog, **kwargs) -> type['FutureBackend']:
@@ -47,7 +49,9 @@ class FutureBackend:
             f"{service.name.title()}{cls.__name__}",
             (cls,),
             {
-                "keyval": components.KEYVAL.value
+                "keyval": components.KEYVAL.value,
+                "queue": components.QUEUE.value,
+                "pubsub": components.PUBSUB.value,
             },
         )
 
@@ -80,6 +84,7 @@ class FutureResult(Generic[A], FutureBackend.infer_backend()):
     retrieval and management of asynchronous tasks."""
     future_id: str
     parent_id: Optional[str]
+    broadcast: bool
 
     @staticmethod
     def _get_future_keyname(future_id: str) -> str:
@@ -89,6 +94,20 @@ class FutureResult(Generic[A], FutureBackend.infer_backend()):
     def future_keyname(self) -> str:
         return self._get_future_keyname(future_id=self.future_id)
     
+    @classmethod
+    def _get_bcast_channel(cls, future_id: str) -> FredPubSub:
+        return cls.pubsub(name=":".join([cls._get_future_keyname(future_id=future_id), "bcast"]))
+
+    @property
+    def bcast_channel(self) -> FredPubSub:
+        return self._get_bcast_channel(future_id=self.future_id)
+
+    def bcast_now(self, item: Optional[str] = None, ignore_flag: bool = False) -> bool:
+        if ignore_flag or self.broadcast:
+            self.bcast_channel.publish(item=item or self.stringify())
+            return True
+        return False
+
     @classmethod
     def _get_status_key(cls, future_id: str) -> FredKeyVal:
         return cls.keyval(key=":".join([cls._get_future_keyname(future_id=future_id), "status"]))
@@ -132,7 +151,7 @@ class FutureResult(Generic[A], FutureBackend.infer_backend()):
 
     @classmethod
     def from_backend(cls, future_id: str) -> Optional['FutureResult[A]']:
-        return FutureResult(future_id=future_id, parent_id=None)._from_backend()
+        return FutureResult(future_id=future_id, parent_id=None, broadcast=False)._from_backend()
 
     @property
     def _pre(self) -> Optional['FutureResult']:
@@ -169,7 +188,8 @@ class FutureUndefinedPending(FutureResult[A]):
         import uuid
         parent_id = kwargs.pop("parent_id", None)
         future_id = kwargs.pop("future_id", None) or str(uuid.uuid4())
-        return FutureUndefinedPending[A](future_id=future_id, parent_id=parent_id, **kwargs)
+        broadcast = kwargs.pop("broadcast", False)
+        return FutureUndefinedPending[A](future_id=future_id, parent_id=parent_id, broadcast=broadcast, **kwargs)
 
     def __post_init__(self):
         logger.debug(f"Future[{self.future_id}] initialized and pending execution")
@@ -178,9 +198,10 @@ class FutureUndefinedPending(FutureResult[A]):
             expire=FRD_FUTURE_DEFAULT_EXPIRATION
         )
         self.obj.set(
-            value=self.stringify(),
+            value=(obj_payload := self.stringify()),
             expire=FRD_FUTURE_DEFAULT_EXPIRATION
         )
+        self.bcast_now(item=obj_payload, ignore_flag=False)
 
     def apply(
             self,
@@ -203,6 +224,7 @@ class FutureUndefinedPending(FutureResult[A]):
         fip = FutureUndefinedInProgress[A](
             future_id=self.future_id,
             parent_id=self.parent_id,
+            broadcast=self.broadcast,
             started_at=perf_counter(),
             function_name=function.__name__,
         )
@@ -227,9 +249,10 @@ class FutureUndefinedInProgress(FutureResult[A]):
             expire=FRD_FUTURE_DEFAULT_EXPIRATION
         )
         self.obj.set(
-            value=self.stringify(),
+            value=(obj_payload := self.stringify()),
             expire=FRD_FUTURE_DEFAULT_EXPIRATION
         )
+        self.bcast_now(item=obj_payload, ignore_flag=False)
 
     def exec(
             self,
@@ -278,6 +301,7 @@ class FutureUndefinedInProgress(FutureResult[A]):
         future_defined = FutureDefined(
             future_id=self.future_id,
             parent_id=self.parent_id,
+            broadcast=self.broadcast,
             value=value,
             ok=ok,
         )
@@ -308,9 +332,10 @@ class FutureDefined(FutureResult[A]):
             expire=FRD_FUTURE_DEFAULT_EXPIRATION
         )
         self.obj.set(
-            value=self.stringify(),
+            value=(obj_payload := self.stringify()),
             expire=FRD_FUTURE_DEFAULT_EXPIRATION
         )
+        self.bcast_now(item=obj_payload, ignore_flag=False)
         match self.value:
             case EitherMonad.Right(value=value):
                 # TODO: Consider using a more robust serialization method...

fred_oss-0.45.0/src/main/fred/version

@@ -0,0 +1 @@
+0.45.0

{fred_oss-0.43.0 → fred_oss-0.45.0/src/main/fred_oss.egg-info}/PKG-INFO

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

fred_oss-0.43.0/src/main/fred/version

@@ -1 +0,0 @@
-0.43.0