fred-oss 0.14.0__tar.gz → 0.16.0__tar.gz

{fred_oss-0.14.0/src/main/fred_oss.egg-info → fred_oss-0.16.0}/PKG-INFO

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

fred_oss-0.16.0/src/main/fred/dao/__init__.py

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

fred_oss-0.16.0/src/main/fred/dao/comp/_keyval.py

@@ -0,0 +1,76 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from fred.dao.service.catalog import ServiceCatalog
+from fred.dao.comp.interface import ComponentInterface
+
+
+@dataclass(frozen=True, slots=True)
+class FredKeyVal(ComponentInterface):
+    """A simple key-value store implementation using a backend service.
+    This class provides methods to interact with a key-value store, such as setting,
+    getting, and deleting key-value pairs. The actual implementation of these methods
+    depends on the underlying service being used (e.g., Redis).
+    """
+    
+    def set(self, key: str, value: str, **kwargs) -> None:
+        """Sets a key-value pair in the store.
+        The implementation of this method depends on the underlying service.
+        For example, if the service is Redis, it uses the SET command to store the
+        key-value pair.
+        Args:
+            key (str): The key to set.
+            value (str): The value to associate with the key.
+            **kwargs: Additional keyword arguments for setting the key-value pair,
+                      such as expiration time.
+        Raises:
+            NotImplementedError: If the method is not implemented for the current service.
+        """
+        match self._cat:
+            case ServiceCatalog.REDIS:
+                self._srv.client.set(key, value)
+                expire = kwargs.get("expire")
+                if expire and isinstance(expire, int):
+                    self._srv.client.expire(key, expire)
+            case _:
+                raise NotImplementedError(f"Set method not implemented for service {self._nme}")
+
+    def get(self, key: str, fail: bool = False) -> Optional[str]:
+        """Gets the value associated with a key from the store.
+        The implementation of this method depends on the underlying service.
+        For example, if the service is Redis, it uses the GET command to retrieve the
+        value associated with the key.
+        Args:
+            key (str): The key to retrieve.
+            fail (bool): If True, raises a KeyError if the key is not found. Defaults to False.
+        Returns:
+            Optional[str]: The value associated with the key, or None if the key is not found
+                           and fail is False.
+        Raises:
+            KeyError: If the key is not found and fail is True.
+            NotImplementedError: If the method is not implemented for the current service.
+        """
+        match self._cat:
+            case ServiceCatalog.REDIS:
+                result = self._srv.client.get(key)
+                if result is None and fail:
+                    raise KeyError(f"Key {key} not found.")
+                return result
+            case _:
+                raise NotImplementedError(f"Get method not implemented for service {self._nme}")
+
+    def delete(self, key: str) -> None:
+        """Deletes a key-value pair from the store.
+        The implementation of this method depends on the underlying service.
+        For example, if the service is Redis, it uses the DEL command to remove the
+        key-value pair.
+        Args:
+            key (str): The key to delete.
+        Raises:
+            NotImplementedError: If the method is not implemented for the current service.
+        """
+        match self._cat:
+            case ServiceCatalog.REDIS:
+                self._srv.client.delete(key)
+            case _:
+                raise NotImplementedError(f"Delete method not implemented for service {self._nme}")

fred_oss-0.16.0/src/main/fred/dao/comp/_queue.py

@@ -0,0 +1,79 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from fred.dao.service.catalog import ServiceCatalog
+from fred.dao.comp.interface import ComponentInterface
+
+
+@dataclass(frozen=True, slots=True)
+class FredQueue(ComponentInterface):
+    """A simple queue implementation using a backend service.
+    This class provides methods to interact with a queue, such as adding,
+    removing, and checking the size of the queue. The actual implementation
+    of these methods depends on the underlying service being used (e.g., Redis).
+    Attributes:
+        name: str: The name of the queue.
+    """
+    name: str
+
+    def size(self) -> int:
+        """Returns the number of items in the queue.
+        The implementation of this method depends on the underlying service.
+        For example, if the service is Redis, it uses the LLEN command to get the
+        length of the list representing the queue.
+        Returns:
+            int: The number of items in the queue.
+        Raises:
+            NotImplementedError: If the method is not implemented for the current service.
+        """
+        match self._cat:
+            case ServiceCatalog.REDIS:
+                return self._srv.client.llen(self.name)
+            case _:
+                raise NotImplementedError(f"Size method not implemented for service {self._nme}")
+
+    def clear(self) -> None:
+        """Clears all items from the queue.
+        The implementation of this method depends on the underlying service.
+        For example, if the service is Redis, it uses the DEL command to remove the
+        key representing the queue.
+        Raises:
+            NotImplementedError: If the method is not implemented for the current service.
+        """
+        match self._cat:
+            case ServiceCatalog.REDIS:
+                self._srv.client.delete(self.name)
+            case _:
+                raise NotImplementedError(f"Clear method not implemented for service {self._nme}")
+
+    def add(self, item: str) -> None:
+        """Adds an item to the queue.
+        The implementation of this method depends on the underlying service.
+        For example, if the service is Redis, it uses the LPUSH command to add the
+        item to the front of the list representing the queue.
+        Args:
+            item (str): The item to add to the queue.
+        Raises:
+            NotImplementedError: If the method is not implemented for the current service.
+        """
+        match self._cat:
+            case ServiceCatalog.REDIS:
+                self._srv.client.lpush(self.name, item)
+            case _:
+                raise NotImplementedError(f"Add method not implemented for service {self._srv._nme}")
+
+    def pop(self) -> Optional[str]:
+        """Removes and returns an item from the queue.
+        The implementation of this method depends on the underlying service.
+        For example, if the service is Redis, it uses the RPOP command to remove and
+        return the last item from the list representing the queue.
+        Returns:
+            Optional[str]: The item removed from the queue, or None if the queue is empty.
+        Raises:
+            NotImplementedError: If the method is not implemented for the current service.
+        """
+        match self._cat:
+            case ServiceCatalog.REDIS:
+                return self._srv.client.rpop(self.name)
+            case _:
+                raise NotImplementedError(f"Pop method not implemented for service {self._srv._nme}")

fred_oss-0.16.0/src/main/fred/dao/comp/catalog.py

@@ -0,0 +1,89 @@
+import enum
+from functools import lru_cache
+from typing import Optional
+
+from fred.dao.comp.interface import ComponentInterface
+from fred.dao.comp._queue import FredQueue
+from fred.dao.comp._keyval import FredKeyVal
+
+
+class _PreconfCatalogMixin:
+    """A mixin class to allow enum members to be called directly to create instances
+    of preconfigured components.
+    This mixin is used in conjunction with the `preconf` class method of the `CompCatalog`
+    enum to create a new enum with preconfigured components for a specific service."""
+
+    def __call__(self, *args, **kwargs) -> ComponentInterface:
+        """Create an instance of the preconfigured component. This method
+        allows the enum member to be called directly to instantiate the component
+        with any additional arguments.
+        Args:
+            *args: Positional arguments to pass to the component constructor.
+            **kwargs: Keyword arguments to pass to the component constructor.
+        Returns:
+            ComponentInterface: An instance of the preconfigured component.
+        """
+        return self.value(*args, **kwargs)
+
+
+class CompCatalog(enum.Enum):
+    """An enumeration of available component types.
+    Each enum member corresponds to a specific component class that implements
+    the `ComponentInterface`. This enum provides a way to reference and create
+    instances of different component types in a standardized manner.
+    """
+    QUEUE = FredQueue
+    KEYVAL = FredKeyVal
+
+    @classmethod
+    def from_classname(cls, classname: str) -> "CompCatalog":
+        """Get enum member by component class name.
+        Args:
+            classname (str): The class name of the component.
+        Returns:
+            CompCatalog: The corresponding enum member.
+        Raises:
+            ValueError: If no matching component is found.
+        """
+        for item in cls:
+            if item.value.__name__ == classname:
+                return item
+        raise ValueError(f"No component found for classname: {classname}")
+
+    @classmethod
+    @lru_cache(maxsize=None)  # TODO: Consider cache invalidation strategy if needed
+    def preconf(cls, srv_name: str, **kwargs) -> enum.Enum:
+        """Create a new Enum with preconfigured components for a specific service name.
+        Args:
+            srv_name (str): The service name to preconfigure the components with.
+            **kwargs: Additional keyword arguments to pass to the component constructors.
+        Returns:
+            enum.Enum: A new Enum class with preconfigured components.
+        """
+        return enum.Enum(
+            f"{srv_name.title()}{cls.__name__}",
+            {item.name: item.value.mount(srv_name=srv_name, **kwargs) for item in cls},
+            type=_PreconfCatalogMixin,
+        )
+
+    def component_cls(self) -> type[ComponentInterface]:
+        """Returns the class of the component associated with the enum member.
+        Returns:
+            type[ComponentInterface]: The class of the component.
+        """
+        return self.value
+
+    def auto(self, srv_name: Optional[str] = None, **kwargs) -> ComponentInterface:
+        """Automatically creates an instance of the component, mounting it to a service.
+        This method is a convenience wrapper that first mounts the component to a service
+        and then creates an instance of the component.
+        Args:
+            srv_name (Optional[str]): The name of the service to mount. Defaults to None.
+            **kwargs: Additional keyword arguments for both mounting the service and
+                      creating the component instance. If there are specific arguments
+                      for the service, they should be passed under the key `srv_kwargs`
+                      as a dictionary.
+        Returns:
+            ComponentInterface: An instance of the component.
+        """
+        return self.value.auto(srv_name=srv_name, **kwargs)

fred_oss-0.16.0/src/main/fred/dao/comp/interface.py

@@ -0,0 +1,59 @@
+from typing import Optional
+from fred.dao.service.interface import ServiceInterface
+from fred.dao.service.catalog import ServiceCatalog
+
+
+class SrvCompanionMixin:
+    _srv: ServiceInterface
+
+    @classmethod
+    def _set_srv(cls, name: Optional[str] = None, **kwargs):
+        """Sets the service instance for the component class.
+        This method initializes the `_srv` class variable with an instance
+        of the service specified by `name` and any additional parameters passed via `kwargs`.
+        Args:
+            name (Optional[str]): The name of the service to set. Defaults to "REDIS".
+            **kwargs: Additional keyword arguments to configure the service instance.
+        """
+        cls._srv = ServiceCatalog[(name or "REDIS").upper()].auto(**kwargs)
+    
+    @property
+    def _nme(self) -> str:
+        """Returns the class name of the current service instance."""
+        return self._srv.__class__.__name__
+
+    @property
+    def _cat(self) -> ServiceCatalog:
+        """Returns the ServiceCatalog enum member corresponding to the current service instance."""
+        return ServiceCatalog.from_classname(self._nme)
+
+
+class ComponentInterface(SrvCompanionMixin):
+
+    @classmethod
+    def mount(cls, srv_name: Optional[str] = None, **kwargs) -> type["ComponentInterface"]:
+        """Mounts the component to a specific service instance.
+        This method configures the component to use a service instance
+        identified by `srv_name` and any additional parameters passed via `kwargs`.
+        
+        Args:
+            srv_name (Optional[str]): The name of the service to mount. Defaults to "REDIS".
+            **kwargs: Additional keyword arguments to configure the service instance.
+        """
+        cls._set_srv(name=srv_name, **kwargs)
+        return cls
+
+    @classmethod
+    def auto(cls, srv_name: Optional[str] = None, **kwargs) -> "ComponentInterface":
+        """Automatically creates an instance of the component, mounting it to a service.
+        This method is a convenience wrapper that first mounts the component to a service
+        and then creates an instance of the component.
+        Args:
+            srv_name (Optional[str]): The name of the service to mount. Defaults to "REDIS".
+            **kwargs: Additional keyword arguments for both mounting the service and
+                      creating the component instance. If there are specific arguments
+                      for the service, they should be passed under the key `srv_kwargs`
+                      as a dictionary.
+        """
+        srv_kwargs = kwargs.pop("srv_kwargs", {})
+        return cls.mount(srv_name=srv_name, **srv_kwargs)(**kwargs)

fred_oss-0.16.0/src/main/fred/dao/service/_redis.py

@@ -0,0 +1,25 @@
+from redis import Redis, ConnectionPool
+
+from fred.dao.service.utils import get_redis_configs_from_payload
+from fred.dao.service.interface import ServiceConnectionPoolInterface, ServiceInterface
+
+
+class RedisConnectionPool(ServiceConnectionPoolInterface[ConnectionPool]):
+
+    @classmethod
+    def _create_pool(cls, **kwargs) -> ConnectionPool:
+        configs = get_redis_configs_from_payload(payload=kwargs, keep=False)
+        return ConnectionPool(**configs)
+
+
+class RedisService(ServiceInterface[Redis]):
+    instance: Redis
+
+    @classmethod
+    def _create_instance(cls, **kwargs) -> Redis:
+        return Redis(connection_pool=RedisConnectionPool.get_or_create_pool(**kwargs))
+
+    @classmethod
+    def auto(cls, **kwargs) -> "RedisService":
+        cls.instance = Redis(connection_pool=RedisConnectionPool.get_or_create_pool(**kwargs))
+        return cls(**kwargs)

fred_oss-0.16.0/src/main/fred/dao/service/catalog.py

@@ -0,0 +1,36 @@
+import enum
+from functools import lru_cache
+
+from fred.dao.service.interface import ServiceInterface
+from fred.dao.service._redis import RedisService
+
+
+class ServiceCatalog(enum.Enum):
+    REDIS = RedisService
+
+    @classmethod
+    def from_classname(cls, classname: str) -> "ServiceCatalog":
+        for item in cls:
+            if item.value.__name__ == classname:
+                return item
+        raise ValueError(f"No service found for classname: {classname}")
+
+    @lru_cache(maxsize=None)  # TODO: Consider cache invalidation strategy if needed
+    def component_catalog(self, **kwargs) -> enum.Enum:
+        """Get a preconfigured component catalog for this (self) service.
+        This method returns a new Enum with preconfigured components for the
+        service represented by this enum member.
+        Args:
+            **kwargs: Additional keyword arguments to pass to the component constructors.
+        Returns:
+             enum.Enum: A new Enum with preconfigured components for this service.
+        """
+        from fred.dao.comp.catalog import CompCatalog  # Avoid circular import
+
+        return CompCatalog.preconf(srv_name=self.name, **kwargs)
+
+    def service_cls(self) -> type[ServiceInterface]:
+        return self.value
+
+    def auto(self, **kwargs) -> ServiceInterface:
+        return self.value.auto(**kwargs)

fred_oss-0.16.0/src/main/fred/dao/service/interface.py

@@ -0,0 +1,54 @@
+import uuid
+import json
+from functools import lru_cache
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class ServiceConnectionPoolInterface(Generic[T]):
+    pool_registry: dict[str, T] = {}
+
+    @classmethod
+    def get_pool_id(cls, **kwargs) -> str:
+        return str(uuid.uuid5(uuid.NAMESPACE_OID, json.dumps(kwargs, sort_keys=True)))
+
+    @classmethod
+    def _create_pool(cls, **kwargs) -> T:
+        raise NotImplementedError("This method should be implemented by subclasses.")
+
+    @classmethod
+    @lru_cache
+    def get_or_create_pool(cls, **kwargs) -> T:
+        pool_id = cls.get_pool_id(**kwargs)
+        pool = cls.pool_registry.get(pool_id)
+        if not pool:
+            pool = cls.pool_registry[pool_id] = cls._create_pool(**kwargs)
+        return pool
+
+
+class ServiceInterface(Generic[T]):
+    instance: T
+
+    def __init__(self, **kwargs):
+        self.config = kwargs
+
+    @classmethod
+    def _create_instance(cls, **kwargs) -> T:
+        raise NotImplementedError("This method should be implemented by subclasses.")
+    
+    @classmethod
+    def auto(cls, **kwargs) -> "ServiceInterface":
+        raise NotImplementedError("This method should be implemented by subclasses.")
+
+    @property
+    def client(self) -> T:  
+        if not getattr(self, "instance", None):
+            self.instance = self._create_instance(**getattr(self, "config", {}))
+        return self.instance
+    
+    def close(self):
+        # Close the instance if it has a close method.
+        # This method can be overridden by subclasses if needed.
+        if self.instance and hasattr(self.instance, "close") and callable(self.instance.close):
+            self.instance.close()

fred_oss-0.16.0/src/main/fred/dao/service/utils.py

@@ -0,0 +1,37 @@
+from fred.settings import get_environ_variable
+
+
+def get_redis_configs_from_payload(
+        payload: dict,
+        keep: bool = False,
+    ) -> dict:
+    """Extract Redis configuration from the given payload dictionary.
+    This function looks for common Redis configuration keys in the payload
+    dictionary. If a key is not found, it falls back to environment variables.
+    Args:
+        payload (dict): The dictionary from which to extract Redis configuration.
+        keep (bool): If True, the original keys are retained in the payload. If False, they are removed.
+    Returns:
+        dict: A dictionary containing Redis configuration parameters.
+    """
+    host = port = password = db = None
+    for host_key in ["host", "redis_host"]:
+        if (host := payload.get(host_key) if keep else payload.pop(host_key, None)):
+            break
+    for port_key in ["port", "redis_port"]:
+        if (port := payload.get(port_key) if keep else payload.pop(port_key, None)):
+            break
+    for password_key in ["password", "redis_password"]:
+        if (password := payload.get(password_key) if keep else payload.pop(password_key, None)):
+            break
+    for db_key in ["db", "redis_db"]:
+        if (db := payload.get(db_key) if keep else payload.pop(db_key, None)):
+            break
+    return {
+        "host": host or get_environ_variable(name="REDIS_HOST", default="localhost"),
+        "port": int(port or get_environ_variable(name="REDIS_PORT", default=6379)),
+        "password": password or get_environ_variable(name="REDIS_PASSWORD", default=None),
+        "db": int(db or get_environ_variable(name="REDIS_DB", default=0)),
+        "decode_responses": True,
+        **(payload.get("redis_configs", {}) if keep else payload.pop("redis_configs", {})),
+    }

fred_oss-0.16.0/src/main/fred/version

@@ -0,0 +1 @@
+0.16.0

{fred_oss-0.14.0 → fred_oss-0.16.0/src/main/fred_oss.egg-info}/PKG-INFO

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

{fred_oss-0.14.0 → fred_oss-0.16.0}/src/main/fred_oss.egg-info/SOURCES.txt

@@ -11,6 +11,17 @@ src/main/fred/cli/__init__.py
 src/main/fred/cli/__main__.py
 src/main/fred/cli/interface.py
 src/main/fred/cli/main.py
+src/main/fred/dao/__init__.py
+src/main/fred/dao/comp/__init__.py
+src/main/fred/dao/comp/_keyval.py
+src/main/fred/dao/comp/_queue.py
+src/main/fred/dao/comp/catalog.py
+src/main/fred/dao/comp/interface.py
+src/main/fred/dao/service/__init__.py
+src/main/fred/dao/service/_redis.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/integrations/databricks/__init__.py
 src/main/fred/integrations/databricks/cli_ext.py
 src/main/fred/integrations/databricks/runtime.py

fred_oss-0.14.0/src/main/fred/version

@@ -1 +0,0 @@
-0.14.0