flwr-nightly 1.8.0.dev20240314__py3-none-any.whl → 1.11.0.dev20240813__py3-none-any.whl

flwr/common/message.py

@@ -16,12 +16,15 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+import time
+import warnings
+from typing import Optional, cast
 
 from .record import RecordSet
 
+DEFAULT_TTL = 3600
+
 
-@dataclass
 class Metadata:  # pylint: disable=too-many-instance-attributes
     """A dataclass holding metadata associated with the current message.
 
@@ -40,27 +43,13 @@ class Metadata:  # pylint: disable=too-many-instance-attributes
     group_id : str
         An identifier for grouping messages. In some settings,
         this is used as the FL round.
-    ttl : str
-        Time-to-live for this message.
+    ttl : float
+        Time-to-live for this message in seconds.
     message_type : str
         A string that encodes the action to be executed on
         the receiving end.
-    partition_id : Optional[int]
-        An identifier that can be used when loading a particular
-        data partition for a ClientApp. Making use of this identifier
-        is more relevant when conducting simulations.
     """
 
-    _run_id: int
-    _message_id: str
-    _src_node_id: int
-    _dst_node_id: int
-    _reply_to_message: str
-    _group_id: str
-    _ttl: str
-    _message_type: str
-    _partition_id: int | None
-
     def __init__(  # pylint: disable=too-many-arguments
         self,
         run_id: int,
@@ -69,92 +58,103 @@ class Metadata:  # pylint: disable=too-many-instance-attributes
         dst_node_id: int,
         reply_to_message: str,
         group_id: str,
-        ttl: str,
+        ttl: float,
         message_type: str,
-        partition_id: int | None = None,
     ) -> None:
-        self._run_id = run_id
-        self._message_id = message_id
-        self._src_node_id = src_node_id
-        self._dst_node_id = dst_node_id
-        self._reply_to_message = reply_to_message
-        self._group_id = group_id
-        self._ttl = ttl
-        self._message_type = message_type
-        self._partition_id = partition_id
+        var_dict = {
+            "_run_id": run_id,
+            "_message_id": message_id,
+            "_src_node_id": src_node_id,
+            "_dst_node_id": dst_node_id,
+            "_reply_to_message": reply_to_message,
+            "_group_id": group_id,
+            "_ttl": ttl,
+            "_message_type": message_type,
+        }
+        self.__dict__.update(var_dict)
 
     @property
     def run_id(self) -> int:
         """An identifier for the current run."""
-        return self._run_id
+        return cast(int, self.__dict__["_run_id"])
 
     @property
     def message_id(self) -> str:
         """An identifier for the current message."""
-        return self._message_id
+        return cast(str, self.__dict__["_message_id"])
 
     @property
     def src_node_id(self) -> int:
         """An identifier for the node sending this message."""
-        return self._src_node_id
+        return cast(int, self.__dict__["_src_node_id"])
 
     @property
     def reply_to_message(self) -> str:
         """An identifier for the message this message replies to."""
-        return self._reply_to_message
+        return cast(str, self.__dict__["_reply_to_message"])
 
     @property
     def dst_node_id(self) -> int:
         """An identifier for the node receiving this message."""
-        return self._dst_node_id
+        return cast(int, self.__dict__["_dst_node_id"])
 
     @dst_node_id.setter
     def dst_node_id(self, value: int) -> None:
         """Set dst_node_id."""
-        self._dst_node_id = value
+        self.__dict__["_dst_node_id"] = value
 
     @property
     def group_id(self) -> str:
         """An identifier for grouping messages."""
-        return self._group_id
+        return cast(str, self.__dict__["_group_id"])
 
     @group_id.setter
     def group_id(self, value: str) -> None:
         """Set group_id."""
-        self._group_id = value
+        self.__dict__["_group_id"] = value
 
     @property
-    def ttl(self) -> str:
+    def created_at(self) -> float:
+        """Unix timestamp when the message was created."""
+        return cast(float, self.__dict__["_created_at"])
+
+    @created_at.setter
+    def created_at(self, value: float) -> None:
+        """Set creation timestamp for this message."""
+        self.__dict__["_created_at"] = value
+
+    @property
+    def ttl(self) -> float:
         """Time-to-live for this message."""
-        return self._ttl
+        return cast(float, self.__dict__["_ttl"])
 
     @ttl.setter
-    def ttl(self, value: str) -> None:
+    def ttl(self, value: float) -> None:
         """Set ttl."""
-        self._ttl = value
+        self.__dict__["_ttl"] = value
 
     @property
     def message_type(self) -> str:
         """A string that encodes the action to be executed on the receiving end."""
-        return self._message_type
+        return cast(str, self.__dict__["_message_type"])
 
     @message_type.setter
     def message_type(self, value: str) -> None:
         """Set message_type."""
-        self._message_type = value
+        self.__dict__["_message_type"] = value
 
-    @property
-    def partition_id(self) -> int | None:
-        """An identifier telling which data partition a ClientApp should use."""
-        return self._partition_id
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        view = ", ".join([f"{k.lstrip('_')}={v!r}" for k, v in self.__dict__.items()])
+        return f"{self.__class__.__qualname__}({view})"
 
-    @partition_id.setter
-    def partition_id(self, value: int) -> None:
-        """Set patition_id."""
-        self._partition_id = value
+    def __eq__(self, other: object) -> bool:
+        """Compare two instances of the class."""
+        if not isinstance(other, self.__class__):
+            raise NotImplementedError
+        return self.__dict__ == other.__dict__
 
 
-@dataclass
 class Error:
     """A dataclass that stores information about an error that occurred.
 
@@ -166,25 +166,35 @@ class Error:
         A reason for why the error arose (e.g. an exception stack-trace)
     """
 
-    _code: int
-    _reason: str | None = None
-
     def __init__(self, code: int, reason: str | None = None) -> None:
-        self._code = code
-        self._reason = reason
+        var_dict = {
+            "_code": code,
+            "_reason": reason,
+        }
+        self.__dict__.update(var_dict)
 
     @property
     def code(self) -> int:
         """Error code."""
-        return self._code
+        return cast(int, self.__dict__["_code"])
 
     @property
     def reason(self) -> str | None:
         """Reason reported about the error."""
-        return self._reason
+        return cast(Optional[str], self.__dict__["_reason"])
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        view = ", ".join([f"{k.lstrip('_')}={v!r}" for k, v in self.__dict__.items()])
+        return f"{self.__class__.__qualname__}({view})"
+
+    def __eq__(self, other: object) -> bool:
+        """Compare two instances of the class."""
+        if not isinstance(other, self.__class__):
+            raise NotImplementedError
+        return self.__dict__ == other.__dict__
 
 
-@dataclass
 class Message:
     """State of your application from the viewpoint of the entity using it.
 
@@ -200,105 +210,108 @@ class Message:
         when processing another message.
     """
 
-    _metadata: Metadata
-    _content: RecordSet | None = None
-    _error: Error | None = None
-
     def __init__(
         self,
         metadata: Metadata,
         content: RecordSet | None = None,
         error: Error | None = None,
     ) -> None:
-        self._metadata = metadata
-
         if not (content is None) ^ (error is None):
             raise ValueError("Either `content` or `error` must be set, but not both.")
 
-        self._content = content
-        self._error = error
+        metadata.created_at = time.time()  # Set the message creation timestamp
+        var_dict = {
+            "_metadata": metadata,
+            "_content": content,
+            "_error": error,
+        }
+        self.__dict__.update(var_dict)
 
     @property
     def metadata(self) -> Metadata:
         """A dataclass including information about the message to be executed."""
-        return self._metadata
+        return cast(Metadata, self.__dict__["_metadata"])
 
     @property
     def content(self) -> RecordSet:
         """The content of this message."""
-        if self._content is None:
+        if self.__dict__["_content"] is None:
             raise ValueError(
                 "Message content is None. Use <message>.has_content() "
                 "to check if a message has content."
             )
-        return self._content
+        return cast(RecordSet, self.__dict__["_content"])
 
     @content.setter
     def content(self, value: RecordSet) -> None:
         """Set content."""
-        if self._error is None:
-            self._content = value
+        if self.__dict__["_error"] is None:
+            self.__dict__["_content"] = value
         else:
             raise ValueError("A message with an error set cannot have content.")
 
     @property
     def error(self) -> Error:
         """Error captured by this message."""
-        if self._error is None:
+        if self.__dict__["_error"] is None:
             raise ValueError(
                 "Message error is None. Use <message>.has_error() "
                 "to check first if a message carries an error."
             )
-        return self._error
+        return cast(Error, self.__dict__["_error"])
 
     @error.setter
     def error(self, value: Error) -> None:
         """Set error."""
         if self.has_content():
             raise ValueError("A message with content set cannot carry an error.")
-        self._error = value
+        self.__dict__["_error"] = value
 
     def has_content(self) -> bool:
         """Return True if message has content, else False."""
-        return self._content is not None
+        return self.__dict__["_content"] is not None
 
     def has_error(self) -> bool:
         """Return True if message has an error, else False."""
-        return self._error is not None
-
-    def _create_reply_metadata(self, ttl: str) -> Metadata:
-        """Construct metadata for a reply message."""
-        return Metadata(
-            run_id=self.metadata.run_id,
-            message_id="",
-            src_node_id=self.metadata.dst_node_id,
-            dst_node_id=self.metadata.src_node_id,
-            reply_to_message=self.metadata.message_id,
-            group_id=self.metadata.group_id,
-            ttl=ttl,
-            message_type=self.metadata.message_type,
-            partition_id=self.metadata.partition_id,
-        )
+        return self.__dict__["_error"] is not None
 
-    def create_error_reply(
-        self,
-        error: Error,
-        ttl: str,
-    ) -> Message:
+    def create_error_reply(self, error: Error, ttl: float | None = None) -> Message:
         """Construct a reply message indicating an error happened.
 
         Parameters
         ----------
         error : Error
             The error that was encountered.
-        ttl : str
-            Time-to-live for this message.
+        ttl : Optional[float] (default: None)
+            Time-to-live for this message in seconds. If unset, it will be set based
+            on the remaining time for the received message before it expires. This
+            follows the equation:
+
+            ttl = msg.meta.ttl - (reply.meta.created_at - msg.meta.created_at)
         """
+        if ttl:
+            warnings.warn(
+                "A custom TTL was set, but note that the SuperLink does not enforce "
+                "the TTL yet. The SuperLink will start enforcing the TTL in a future "
+                "version of Flower.",
+                stacklevel=2,
+            )
+        # If no TTL passed, use default for message creation (will update after
+        # message creation)
+        ttl_ = DEFAULT_TTL if ttl is None else ttl
         # Create reply with error
-        message = Message(metadata=self._create_reply_metadata(ttl), error=error)
+        message = Message(metadata=_create_reply_metadata(self, ttl_), error=error)
+
+        if ttl is None:
+            # Set TTL equal to the remaining time for the received message to expire
+            ttl = self.metadata.ttl - (
+                message.metadata.created_at - self.metadata.created_at
+            )
+            message.metadata.ttl = ttl
+
         return message
 
-    def create_reply(self, content: RecordSet, ttl: str) -> Message:
+    def create_reply(self, content: RecordSet, ttl: float | None = None) -> Message:
         """Create a reply to this message with specified content and TTL.
 
         The method generates a new `Message` as a reply to this message.
@@ -309,15 +322,64 @@ class Message:
         ----------
         content : RecordSet
             The content for the reply message.
-        ttl : str
-            Time-to-live for this message.
+        ttl : Optional[float] (default: None)
+            Time-to-live for this message in seconds. If unset, it will be set based
+            on the remaining time for the received message before it expires. This
+            follows the equation:
+
+            ttl = msg.meta.ttl - (reply.meta.created_at - msg.meta.created_at)
 
         Returns
         -------
         Message
             A new `Message` instance representing the reply.
         """
-        return Message(
-            metadata=self._create_reply_metadata(ttl),
+        if ttl:
+            warnings.warn(
+                "A custom TTL was set, but note that the SuperLink does not enforce "
+                "the TTL yet. The SuperLink will start enforcing the TTL in a future "
+                "version of Flower.",
+                stacklevel=2,
+            )
+        # If no TTL passed, use default for message creation (will update after
+        # message creation)
+        ttl_ = DEFAULT_TTL if ttl is None else ttl
+
+        message = Message(
+            metadata=_create_reply_metadata(self, ttl_),
             content=content,
         )
+
+        if ttl is None:
+            # Set TTL equal to the remaining time for the received message to expire
+            ttl = self.metadata.ttl - (
+                message.metadata.created_at - self.metadata.created_at
+            )
+            message.metadata.ttl = ttl
+
+        return message
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        view = ", ".join(
+            [
+                f"{k.lstrip('_')}={v!r}"
+                for k, v in self.__dict__.items()
+                if v is not None
+            ]
+        )
+        return f"{self.__class__.__qualname__}({view})"
+
+
+def _create_reply_metadata(msg: Message, ttl: float) -> Metadata:
+    """Construct metadata for a reply message."""
+    return Metadata(
+        run_id=msg.metadata.run_id,
+        message_id="",
+        src_node_id=msg.metadata.dst_node_id,
+        dst_node_id=msg.metadata.src_node_id,
+        reply_to_message=msg.metadata.message_id,
+        group_id=msg.metadata.group_id,
+        ttl=ttl,
+        message_type=msg.metadata.message_type,
+    )

flwr/common/object_ref.py

@@ -17,8 +17,13 @@
 
 import ast
 import importlib
+import sys
 from importlib.util import find_spec
-from typing import Any, Optional, Tuple, Type
+from logging import WARN
+from pathlib import Path
+from typing import Any, Optional, Tuple, Type, Union
+
+from .logger import log
 
 OBJECT_REF_HELP_STR = """
 \n\nThe object reference string should have the form <module>:<attribute>. Valid
@@ -28,21 +33,41 @@ attribute.
 """
 
 
+_current_sys_path: Optional[str] = None
+
+
 def validate(
     module_attribute_str: str,
+    check_module: bool = True,
+    project_dir: Optional[Union[str, Path]] = None,
 ) -> Tuple[bool, Optional[str]]:
     """Validate object reference.
 
-    The object reference string should have the form <module>:<attribute>. Valid
-    examples include `client:app` and `project.package.module:wrapper.app`. It must
-    refer to a module on the PYTHONPATH and the module needs to have the specified
-    attribute.
+    Parameters
+    ----------
+    module_attribute_str : str
+        The reference to the object. It should have the form `<module>:<attribute>`.
+        Valid examples include `client:app` and `project.package.module:wrapper.app`.
+        It must refer to a module on the PYTHONPATH or in the provided `project_dir`
+        and the module needs to have the specified attribute.
+    check_module : bool (default: True)
+        Flag indicating whether to verify the existence of the module and the
+        specified attribute within it.
+    project_dir : Optional[Union[str, Path]] (default: None)
+        The directory containing the module. If None, the current working directory
+        is used. If `check_module` is True, the `project_dir` will be inserted into
+        the system path, and the previously inserted `project_dir` will be removed.
 
     Returns
     -------
     Tuple[bool, Optional[str]]
         A boolean indicating whether an object reference is valid and
         the reason why it might not be.
+
+    Note
+    ----
+    This function will modify `sys.path` by inserting the provided `project_dir`
+    and removing the previously inserted `project_dir`.
     """
     module_str, _, attributes_str = module_attribute_str.partition(":")
     if not module_str:
@@ -56,15 +81,21 @@ def validate(
             f"Missing attribute in {module_attribute_str}{OBJECT_REF_HELP_STR}",
         )
 
-    # Load module
-    module = find_spec(module_str)
-    if module and module.origin:
-        if not _find_attribute_in_module(module.origin, attributes_str):
-            return (
-                False,
-                f"Unable to find attribute {attributes_str} in module {module_str}"
-                f"{OBJECT_REF_HELP_STR}",
-            )
+    if check_module:
+        # Set the system path
+        _set_sys_path(project_dir)
+
+        # Load module
+        module = find_spec(module_str)
+        if module and module.origin:
+            if not _find_attribute_in_module(module.origin, attributes_str):
+                return (
+                    False,
+                    f"Unable to find attribute {attributes_str} in module {module_str}"
+                    f"{OBJECT_REF_HELP_STR}",
+                )
+            return (True, None)
+    else:
         return (True, None)
 
     return (
@@ -73,44 +104,114 @@ def validate(
     )
 
 
-def load_app(
+def load_app(  # pylint: disable= too-many-branches
     module_attribute_str: str,
     error_type: Type[Exception],
+    project_dir: Optional[Union[str, Path]] = None,
 ) -> Any:
     """Return the object specified in a module attribute string.
 
-    The module/attribute string should have the form <module>:<attribute>. Valid
-    examples include `client:app` and `project.package.module:wrapper.app`. It must
-    refer to a module on the PYTHONPATH, the module needs to have the specified
-    attribute.
+    Parameters
+    ----------
+    module_attribute_str : str
+        The reference to the object. It should have the form `<module>:<attribute>`.
+        Valid examples include `client:app` and `project.package.module:wrapper.app`.
+        It must refer to a module on the PYTHONPATH or in the provided `project_dir`
+        and the module needs to have the specified attribute.
+    error_type : Type[Exception]
+        The type of exception to be raised if the provided `module_attribute_str` is
+        in an invalid format.
+    project_dir : Optional[Union[str, Path]], optional (default=None)
+        The directory containing the module. If None, the current working directory
+        is used. The `project_dir` will be inserted into the system path, and the
+        previously inserted `project_dir` will be removed.
+
+    Returns
+    -------
+    Any
+        The object specified by the module attribute string.
+
+    Note
+    ----
+    This function will modify `sys.path` by inserting the provided `project_dir`
+    and removing the previously inserted `project_dir`.
     """
-    valid, error_msg = validate(module_attribute_str)
+    valid, error_msg = validate(module_attribute_str, check_module=False)
     if not valid and error_msg:
         raise error_type(error_msg) from None
 
     module_str, _, attributes_str = module_attribute_str.partition(":")
 
     try:
-        module = importlib.import_module(module_str)
-    except ModuleNotFoundError:
+        _set_sys_path(project_dir)
+
+        if module_str not in sys.modules:
+            module = importlib.import_module(module_str)
+        # Hack: `tabnet` does not work with `importlib.reload`
+        elif "tabnet" in sys.modules:
+            log(
+                WARN,
+                "Cannot reload module `%s` from disk due to compatibility issues "
+                "with the `tabnet` library. The module will be loaded from the "
+                "cache instead. If you experience issues, consider restarting "
+                "the application.",
+                module_str,
+            )
+            module = sys.modules[module_str]
+        else:
+            module = sys.modules[module_str]
+
+            if project_dir is None:
+                project_dir = Path.cwd()
+
+            # Reload cached modules in the project directory
+            for m in list(sys.modules.values()):
+                path: Optional[str] = getattr(m, "__file__", None)
+                if path is not None and path.startswith(str(project_dir)):
+                    importlib.reload(m)
+
+    except ModuleNotFoundError as err:
         raise error_type(
             f"Unable to load module {module_str}{OBJECT_REF_HELP_STR}",
-        ) from None
+        ) from err
 
     # Recursively load attribute
     attribute = module
     try:
         for attribute_str in attributes_str.split("."):
             attribute = getattr(attribute, attribute_str)
-    except AttributeError:
+    except AttributeError as err:
         raise error_type(
             f"Unable to load attribute {attributes_str} from module {module_str}"
             f"{OBJECT_REF_HELP_STR}",
-        ) from None
+        ) from err
 
     return attribute
 
 
+def _set_sys_path(directory: Optional[Union[str, Path]]) -> None:
+    """Set the system path."""
+    if directory is None:
+        directory = Path.cwd()
+    else:
+        directory = Path(directory).absolute()
+
+    # If the directory has already been added to `sys.path`, return
+    if str(directory) in sys.path:
+        return
+
+    # Remove the old path if it exists and is not `""`.
+    global _current_sys_path  # pylint: disable=global-statement
+    if _current_sys_path is not None:
+        sys.path.remove(_current_sys_path)
+
+    # Add the new path to sys.path
+    sys.path.insert(0, str(directory))
+
+    # Update the current_sys_path
+    _current_sys_path = str(directory)
+
+
 def _find_attribute_in_module(file_path: str, attribute_name: str) -> bool:
     """Check if attribute_name exists in module's abstract symbolic tree."""
     with open(file_path, encoding="utf-8") as file:

flwr/common/record/__init__.py

@@ -22,9 +22,9 @@ from .recordset import RecordSet
 
 __all__ = [
     "Array",
-    "array_from_numpy",
     "ConfigsRecord",
     "MetricsRecord",
     "ParametersRecord",
     "RecordSet",
+    "array_from_numpy",
 ]

flwr/common/record/parametersrecord.py

@@ -82,7 +82,6 @@ def _check_value(value: Array) -> None:
         )
 
 
-@dataclass
 class ParametersRecord(TypedDict[str, Array]):
     """Parameters record.