fred-oss 0.21.0__tar.gz → 0.22.0__tar.gz

{fred_oss-0.21.0/src/main/fred_oss.egg-info → fred_oss-0.22.0}/PKG-INFO

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

fred_oss-0.22.0/src/main/fred/future/__init__.py

@@ -0,0 +1,12 @@
+from fred.maturity import Maturity, MaturityLevel
+from fred.future.impl import Future
+
+
+module_maturity = Maturity(
+    level=MaturityLevel.ALPHA,
+    reference=__name__,
+    message=(
+        "Fred-Futures implementation is in early development "
+        "and therefore currently with incomplete and unstable features."
+    )
+)

fred_oss-0.22.0/src/main/fred/future/impl.py

@@ -0,0 +1,204 @@
+from threading import Thread
+from typing import (
+    Callable,
+    Optional,
+    TypeVar,
+)
+
+from fred.settings import logger_manager
+from fred.monad.interface import MonadInterface
+from fred.monad.catalog import EitherMonad
+from fred.future.result import (
+    FutureResult,
+    FutureUndefinedPending,
+    FutureUndefinedInProgress,
+    FutureDefined,
+)
+
+A = TypeVar("A")
+B = TypeVar("B")
+
+logger = logger_manager.get_logger(__name__)
+
+
+class Future(MonadInterface[A]):
+    """A Future represents a computation that will complete at some point in the future,
+    yielding a result of type A or failing with an exception. It allows for asynchronous
+    programming by enabling non-blocking operations and chaining of computations.
+    This implementation uses threading to execute the computation in a separate thread.
+
+    The Future class provides methods to wait for the computation to complete,
+    retrieve the result, and chain further computations using flat_map and map.
+
+    Note: This implementation is a simplified version and may not cover all edge cases
+    or provide advanced features found in more comprehensive concurrency libraries.
+
+    Note: The Future class is designed to work with the Either monad to encapsulate
+    successful results (Right) and exceptions (Left).
+
+    Note: The Future class uses a backend storage system to persist the state
+    and result of the computation, allowing for distributed or long-running tasks.
+
+    Note: The Future class is generic and can be used with any type A, allowing for
+    flexibility in the types of computations it can represent.
+
+    Note: Even though the Future class implements the MonadInterface, it is not a full monad
+    in the traditional sense, as it represents an asynchronous computation rather than
+    a pure value. However, it provides similar capabilities for chaining and transforming
+    computations in a functional style.
+
+    TODO: Consider adding cancellation support to allow aborting ongoing computations.
+    
+    TODO: Analyze impact on performance and resource usage when using many Futures. Specially
+    on garbage collection and memory leaks.
+    
+    TODO: Consider using more advanced concurrency primitives for better control and efficiency.
+    """
+
+    def __init__(self, function: Callable[..., A], **kwargs):
+        """Initializes a Future with the provided function to be executed asynchronously.
+        The function is executed in a separate thread, allowing for non-blocking operations.
+        Args:
+            function (Callable[..., A]): The function to be executed asynchronously.
+            **kwargs: Additional keyword arguments to be passed to the function when executed.
+        """
+        # Create a new available future
+        future = FutureUndefinedPending.auto()
+        # 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.
+        self.future_id = future.future_id
+        self.thread = Thread(
+            target=lambda: future.apply(function=function, **kwargs),
+            daemon=True,
+        )
+        # Start the thread to execute the function asynchronously
+        self.thread.start()
+
+    @property
+    def _result(self) -> Optional[FutureResult[A]]:
+        return FutureResult.from_backend(future_id=self.future_id)
+    
+    @property
+    def _status(self) -> Optional[str]:
+        return FutureResult._get_status_key(future_id=self.future_id).get()
+
+    @property
+    def _output(self) -> Optional[str]:
+        return FutureResult._get_output_key(future_id=self.future_id).get()
+
+    def wait(self, timeout: Optional[float] = None) -> EitherMonad.Either[A]:
+        """Waits for the future to complete and returns the result as an Either monad.
+
+        TL;DR Waiting will collapse the future into a concrete result
+        which can be either a value (Right) or an exception (Left).
+
+        * If the future completes successfully, returns Right(value).
+        * If the future fails, returns Left(exception).
+        * If the timeout is reached before completion, raises a TimeoutError.
+        Args:
+            timeout (Optional[float]): Maximum time to wait for the future to complete.
+                                       If None, waits indefinitely.
+        Returns:
+            Either[A]: An Either monad containing the result or exception.
+        Raises:
+            TimeoutError: If the future does not complete within the specified timeout.
+            RuntimeError: If the future status is inconsistent after waiting.
+            TypeError: If the future result type is unknown.
+        """
+        # Wait for the thread to complete or timeout
+        self.thread.join(timeout=timeout)
+        if self.thread.is_alive():
+            raise TimeoutError("Future did not complete within the specified timeout.")
+        # After the thread has completed, check the status consistency
+        if not self._status:
+            raise RuntimeError("Future status should be set but isn't.")
+        if not self._status.startswith("DEFINED"):
+            raise RuntimeError("Future status should be DEFINED after wait.")
+        # Check the result-type consistency
+        # If the future is still pending or in-progress, it's an error and should not happen
+        # If the future is defined, return the contained value or exception
+        match self._result:
+            case FutureUndefinedPending():
+                raise RuntimeError("Future is still pending after wait.")
+            case FutureUndefinedInProgress():
+                raise RuntimeError("Future is still in progress after wait.")
+            case FutureDefined(value=value):
+                return value
+            case _:
+                raise TypeError("Unknown FutureResult type")
+
+    @property
+    def state(self) -> Optional[str]:
+        """Returns the current state of the future as a string.
+        The state is derived from the status key in the backend storage.
+        Returns:
+            Optional[str]: The current state of the future, or None if not available.
+                           Possible states include:
+                           - "UNDEFINED:PENDING"
+                           - "UNDEFINED:IN_PROGRESS"
+                           - "DEFINED:SUCCESS"
+                           - "DEFINED:FAILURE"
+        """
+        return ":".join(self._status.split(":")[:2]) if self._status else None
+
+    def __repr__(self) -> str:
+        return f"FUTURE[{self.state}]('{self.future_id}')"
+    
+    def __str__(self) -> str:
+        return self.future_id
+
+    def wait_and_resolve(self, timeout: Optional[float] = None) -> A:
+        """Waits for the future to complete and resolves the result into
+        the expected output type of the function call; raises if the future failed.
+        This is a convenience method that combines waiting for the future to complete
+        and resolving the result, raising any exceptions that occurred during execution.
+        Args:
+            timeout (Optional[float]): Maximum time to wait for the future to complete.
+                                       If None, waits indefinitely.
+        Returns:
+            A: The resolved value of the future if it completed successfully.
+        Raises:
+            TimeoutError: If the future does not complete within the specified timeout.
+            Exception: If the future failed during execution, the original exception is raised.
+        """
+        return self.wait(timeout=timeout).resolve()
+
+    @classmethod
+    def from_value(cls, val: A) -> 'Future[A]':
+        return Future(function=lambda: val)
+    
+    def flat_map(self, function: Callable[[A], 'Future[B]'], timeout: Optional[float] = None) -> 'Future[B]':
+        """Chains the current future with another future-producing function.
+        This method allows for sequential asynchronous operations where the output
+        of one future is used as the input to another.
+
+        The simple implementation of this method is: function(self.wait_and_resolve())
+        Nonetheless, the simple implementation would block the current thread
+        until the first future is resolved, which is not ideal in an asynchronous context.
+        Instead, we create a new Future that encapsulates the entire operation,
+        allowing it to be executed asynchronously.
+
+        Args:
+            function (Callable[[A], Future[B]]): A function that takes the result of the
+                                                  current future and returns a new Future.
+            timeout (Optional[float]): Maximum time to wait for the current future to complete.
+                                       If None, waits indefinitely.
+        Returns:
+            Future[B]: A new Future representing the chained operation."""
+        # TODO: Is there a more efficient implementation?
+        return Future(
+            function=lambda:
+                function(self.wait_and_resolve(timeout=timeout))
+                .wait_and_resolve(timeout=timeout)
+        )
+
+    def map(self, function: Callable[[A], B]) -> 'Future[B]':
+        """Applies a function to the result of the future, returning a new future.
+        This method allows for transforming the result of a future without blocking.
+        Args:
+            function (Callable[[A], B]): A function that takes the result of the current future
+                                          and returns a new value.
+        Returns: Future[B]: A new Future containing the transformed result.
+        """
+        return self.flat_map(function=lambda value: type(self).from_value(function(value)))

fred_oss-0.22.0/src/main/fred/future/result.py

@@ -0,0 +1,271 @@
+import json
+from time import perf_counter
+from dataclasses import dataclass
+from typing import (
+    Callable,
+    Generic,
+    Optional,
+    TypeVar,
+)
+
+from fred.settings import (
+    get_environ_variable,
+    logger_manager,
+)
+from fred.future.settings import (
+    FRD_FUTURE_BACKEND,
+    FRD_FUTURE_DEFAULT_EXPIRATION,
+    FRD_FUTURE_DEFAULT_TIMEOUT,
+)
+from fred.utils.dateops import datetime_utcnow
+from fred.dao.service.catalog import ServiceCatalog
+from fred.dao.comp.catalog import FredKeyVal
+from fred.monad.catalog import EitherMonad
+
+logger = logger_manager.get_logger(__name__)
+
+A = TypeVar("A")
+
+
+class FutureBackend:
+    keyval: type[FredKeyVal]
+
+    @classmethod
+    def with_backend(cls, service: ServiceCatalog, **kwargs) -> type['FutureBackend']:
+        """Dynamically creates a FutureBackend subclass with the specified service backend.
+        This method uses the service catalog to fetch the appropriate components for the
+        given service and constructs a new subclass of FutureBackend with those components.
+        Args:
+            service (ServiceCatalog): The service catalog entry representing the backend service.
+            **kwargs: Additional keyword arguments to pass to the component catalog.
+        Returns:
+            type[FutureBackend]: A new subclass of FutureBackend configured with the specified backend.
+        """
+        components = service.component_catalog(**kwargs)
+        return type(
+            f"{service.name.title()}{cls.__name__}",
+            (cls,),
+            {
+                "keyval": components.KEYVAL.value
+            },
+        )
+
+    @classmethod
+    def infer_backend(cls, env: Optional[str] = None, **kwargs) -> type['FutureBackend']:
+        """Infers the backend service from the environment variable or defaults to FRD_FUTURE_BACKEND.
+        This method checks for an environment variable to determine the backend service. If the
+        environment variable is not set, it defaults to the value of FRD_FUTURE_BACKEND. It then
+        uses the inferred service to create a FutureBackend subclass with the appropriate components.
+        Args:
+            env (Optional[str]): The name of the environment variable to check for the backend service.
+                                 If None, defaults to FRD_FUTURE_BACKEND.
+            **kwargs: Additional keyword arguments to pass to the component catalog.
+        Returns:
+            type[FutureBackend]: A new subclass of FutureBackend configured with the inferred backend.
+        """
+        service_key = get_environ_variable(env, default=ServiceCatalog.STDLIB.name) \
+            if env else FRD_FUTURE_BACKEND
+        return cls.with_backend(
+            service=ServiceCatalog[service_key.upper()],
+            **kwargs
+        )
+
+
+@dataclass(frozen=True, slots=False)
+class FutureResult(Generic[A], FutureBackend.infer_backend()):
+    """Represents the result of an asynchronous computation (Future).
+    This class provides methods to manage and retrieve the status and output of a Future.
+    It uses a key-value store to persist the state and result of the Future, allowing for
+    retrieval and management of asynchronous tasks."""
+    future_id: str
+
+    @staticmethod
+    def _get_future_keyname(future_id: str) -> str:
+        return ":".join(["frd", "future", future_id])
+
+    @property
+    def future_keyname(self) -> str:
+        return self._get_future_keyname(future_id=self.future_id)
+    
+    @classmethod
+    def _get_status_key(cls, future_id: str) -> FredKeyVal:
+        return cls.keyval(key=":".join([cls._get_future_keyname(future_id=future_id), "status"]))
+
+    @property
+    def status(self) -> FredKeyVal:
+        return self._get_status_key(future_id=self.future_id)
+    
+    @classmethod
+    def _get_output_key(cls, future_id: str) -> FredKeyVal:
+        return cls.keyval(key=":".join([cls._get_future_keyname(future_id=future_id), "output"]))
+
+    @property
+    def output(self) -> FredKeyVal:
+        return self._get_output_key(future_id=self.future_id)
+    
+    @classmethod
+    def _get_obj_key(cls, future_id: str) -> FredKeyVal:
+        return cls.keyval(key=":".join([cls._get_future_keyname(future_id=future_id), "obj"]))
+
+    @property
+    def obj(self) -> FredKeyVal:
+        return self._get_obj_key(future_id=self.future_id)
+
+    def stringify(self) -> str:
+        import pickle
+        import base64
+        return base64.b64encode(pickle.dumps(self)).decode("ascii")
+
+    @classmethod
+    def from_string(cls, payload: str) -> 'FutureResult[A]':
+        import pickle
+        import base64
+        return pickle.loads(base64.b64decode(payload))
+    
+    def _from_backend(self) -> Optional['FutureResult[A]']:
+        payload = self.obj.get()
+        if not payload:
+            return
+        return self.from_string(payload=payload)
+
+    @classmethod
+    def from_backend(cls, future_id: str) -> Optional['FutureResult[A]']:
+        return FutureResult(future_id=future_id)._from_backend()
+
+
+@dataclass(frozen=True, slots=False)
+class FutureUndefinedPending(FutureResult[A]):
+
+    @classmethod
+    def auto(cls, **kwargs) -> 'FutureUndefinedPending[A]':
+        """Creates a FutureUndefinedPending instance with an auto-generated future_id.
+        This method generates a unique identifier for the future_id if one is not provided
+        in the keyword arguments. It ensures that each instance has a distinct future_id,
+        which is essential for tracking and managing asynchronous tasks.
+        Args:
+            **kwargs: Additional keyword arguments to pass to the FutureUndefinedPending constructor.
+        Returns:
+            FutureUndefinedPending[A]: A new instance of FutureUndefinedPending with a unique future_id.
+        """
+        import uuid
+        future_id = kwargs.pop("future_id", None) or str(uuid.uuid4())
+        return FutureUndefinedPending[A](future_id=future_id, **kwargs)
+
+    def __post_init__(self):
+        logger.debug(f"Future[{self.future_id}] initialized and pending execution")
+        self.status.set(
+            value=f"UNDEFINED:PENDING:{datetime_utcnow().isoformat()}",
+            expire=FRD_FUTURE_DEFAULT_EXPIRATION
+        )
+        self.obj.set(
+            value=self.stringify(),
+            expire=FRD_FUTURE_DEFAULT_EXPIRATION
+        )
+
+    def apply(self, function: Callable[..., A], **kwargs) -> 'FutureDefined[A]':
+        """Applies a function to the Future, transitioning it from pending to in-progress and finalizing as defined.
+        This method executes the provided function with the given keyword arguments,
+        transitioning the Future from a pending state to an in-progress state. It captures
+        the result of the function execution, which can be either a successful value or an
+        exception, and returns a FutureDefined instance representing the completed state.
+        Args:
+            function (Callable[..., A]): The function to execute, which should return a value of type A.
+            **kwargs: Additional keyword arguments to pass to the function during execution.
+        Returns:
+            FutureDefined[A]: A new instance of FutureDefined representing the completed state of the Future.
+        """
+        fip = FutureUndefinedInProgress[A](
+            future_id=self.future_id,
+            started_at=perf_counter(),
+            function_name=function.__name__,
+        )
+        return fip.exec(function=function, **kwargs)
+
+
+@dataclass(frozen=True, slots=False)
+class FutureUndefinedInProgress(FutureResult[A]):
+    started_at: float
+    function_name: str
+    
+
+    def __post_init__(self):
+        logger.debug(f"Future[{self.future_id}] started execution of function '{self.function_name}'")
+        self.status.set(
+            value=f"UNDEFINED:IN_PROGRESS:{datetime_utcnow().isoformat()}",
+            expire=FRD_FUTURE_DEFAULT_EXPIRATION
+        )
+        self.obj.set(
+            value=self.stringify(),
+            expire=FRD_FUTURE_DEFAULT_EXPIRATION
+        )
+
+    def exec(self, function: Callable[..., A], fail: bool = False, **kwargs) -> 'FutureDefined[A]':
+        """Executes the function associated with the Future, capturing its result or exception.
+        This method runs the provided function with the given keyword arguments, capturing
+        its output. If the function executes successfully, it wraps the result in a Right
+        monad; if it raises an exception, it captures the exception in a Left monad.
+        The method returns a FutureDefined instance containing the result of the execution.
+        If the 'fail' parameter is set to True, any exception raised during function execution
+        will be propagated instead of being captured in the Left monad.
+        Args:
+            function (Callable[..., A]): The function to execute, which should return a value of type A.
+            fail (bool): If True, exceptions raised during function execution will be propagated. Defaults to False.
+            **kwargs: Additional keyword arguments to pass to the function during execution.
+        Returns:
+            FutureDefined[A]: A new instance of FutureDefined representing the completed state of the Future.
+        """
+        try:
+            ok = False
+            match function(**kwargs):
+                case EitherMonad.Right(value=value):
+                    ok = True
+                    value =EitherMonad.Right.from_value(val=value)
+                case EitherMonad.Left(exception=exception):
+                    ok = False
+                    value = EitherMonad.Left.from_value(val=exception)
+                case value:
+                    ok = True
+                    value = EitherMonad.Right.from_value(val=value)      
+        except Exception as e:
+            ok = False
+            value = EitherMonad.Left.from_value(val=e)
+            if fail:
+                raise e
+        return FutureDefined(
+            future_id=self.future_id,
+            value=value,
+            ok=ok,
+        )
+
+
+@dataclass(frozen=True, slots=False)
+class FutureDefined(FutureResult[A]):
+    value: EitherMonad.Either[A]
+    ok: bool
+
+    def __post_init__(self):
+        state = "SUCCESS" if self.ok else "FAILURE"
+        logger.debug(f"FutureDefined[{self.future_id}] completed with state: {state}")
+        self.status.set(
+            value=f"DEFINED:{state}:{datetime_utcnow().isoformat()}",
+            expire=FRD_FUTURE_DEFAULT_EXPIRATION
+        )
+        self.obj.set(
+            value=self.stringify(),
+            expire=FRD_FUTURE_DEFAULT_EXPIRATION
+        )
+        match self.value:
+            case EitherMonad.Right(value=value):
+                # TODO: Consider using a more robust serialization method...
+                # TODO: Should we consider collapsing nested-futures? i.e., Future[Future[A]] => Future[A]
+                payload = json.dumps(value)
+                self.output.set(
+                    value=payload,
+                    expire=FRD_FUTURE_DEFAULT_EXPIRATION
+                )
+            case EitherMonad.Left(exception=exception):
+                payload = json.dumps({"error": str(exception)})
+                self.output.set(
+                    value=str(exception),
+                    expire=FRD_FUTURE_DEFAULT_EXPIRATION
+                )

fred_oss-0.22.0/src/main/fred/future/settings.py

@@ -0,0 +1,18 @@
+from fred.settings import get_environ_variable
+
+
+FRD_FUTURE_BACKEND = get_environ_variable(
+    "FRD_FUTURE_BACKEND",
+    default="STDLIB",
+)
+
+FRD_FUTURE_DEFAULT_EXPIRATION = int(get_environ_variable(
+    "FRD_FUTURE_DEFAULT_EXPIRATION",
+    default="3600",  # 1 hour
+))
+
+# TODO: This is currently not used, but reserved for future use...
+FRD_FUTURE_DEFAULT_TIMEOUT = int(get_environ_variable(
+    "FRD_FUTURE_DEFAULT_TIMEOUT",
+    default="900",  # 15 minutes
+))

fred_oss-0.22.0/src/main/fred/version

@@ -0,0 +1 @@
+0.22.0

{fred_oss-0.21.0 → fred_oss-0.22.0/src/main/fred_oss.egg-info}/PKG-INFO

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

{fred_oss-0.21.0 → fred_oss-0.22.0}/src/main/fred_oss.egg-info/SOURCES.txt

@@ -23,6 +23,10 @@ src/main/fred/dao/service/_stdlib.py
 src/main/fred/dao/service/catalog.py
 src/main/fred/dao/service/interface.py
 src/main/fred/dao/service/utils.py
+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/integrations/databricks/__init__.py
 src/main/fred/integrations/databricks/cli_ext.py
 src/main/fred/integrations/databricks/runtime.py

fred_oss-0.21.0/src/main/fred/version

@@ -1 +0,0 @@
-0.21.0