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

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

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

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

@@ -63,6 +63,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 +78,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.
@@ -276,6 +281,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 +298,70 @@ 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,
+    ) -> '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.
+        """
+        # 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():
+                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:
+                    raise ValueError(f"Future with ID '{future_id}' does not exist.")
+                # 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...
+                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.44.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,21 @@ 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 +152,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 +189,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 +199,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 +225,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 +250,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 +302,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 +333,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.44.0/src/main/fred/version

@@ -0,0 +1 @@
+0.44.0

{fred_oss-0.43.0 → fred_oss-0.44.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.44.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