flwr 1.15.2__py3-none-any.whl → 1.16.0__py3-none-any.whl

flwr/common/constant.py

@@ -212,3 +212,19 @@ class AuthType:
     def __new__(cls) -> AuthType:
         """Prevent instantiation."""
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class EventLogWriterType:
+    """Event log writer types."""
+
+    FALSE = "false"
+    STDOUT = "stdout"
+
+    def __new__(cls) -> EventLogWriterType:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+    @classmethod
+    def choices(cls) -> list[str]:
+        """Return a list of available log writer choices."""
+        return [cls.FALSE, cls.STDOUT]

flwr/common/event_log_plugin/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Event log plugin components."""
+
+
+from .event_log_plugin import EventLogWriterPlugin as EventLogWriterPlugin
+
+__all__ = [
+    "EventLogWriterPlugin",
+]

flwr/common/event_log_plugin/event_log_plugin.py

@@ -0,0 +1,60 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Abstract class for Flower Event Log Writer Plugin."""
+
+
+from abc import ABC, abstractmethod
+from typing import Optional, Union
+
+import grpc
+from google.protobuf.message import Message as GrpcMessage
+
+from flwr.common.typing import LogEntry, UserInfo
+
+
+class EventLogWriterPlugin(ABC):
+    """Abstract Flower Event Log Writer Plugin class for ExecServicer."""
+
+    @abstractmethod
+    def __init__(self) -> None:
+        """Abstract constructor."""
+
+    @abstractmethod
+    def compose_log_before_event(  # pylint: disable=too-many-arguments
+        self,
+        request: GrpcMessage,
+        context: grpc.ServicerContext,
+        user_info: UserInfo,
+        method_name: str,
+    ) -> LogEntry:
+        """Compose pre-event log entry from the provided request and context."""
+
+    @abstractmethod
+    def compose_log_after_event(  # pylint: disable=too-many-arguments,R0917
+        self,
+        request: GrpcMessage,
+        context: grpc.ServicerContext,
+        user_info: UserInfo,
+        method_name: str,
+        response: Optional[Union[GrpcMessage, Exception]],
+    ) -> LogEntry:
+        """Compose post-event log entry from the provided response and context."""
+
+    @abstractmethod
+    def write_log(
+        self,
+        log_entry: LogEntry,
+    ) -> None:
+        """Write the event log to the specified data sink."""

flwr/common/grpc.py

@@ -27,7 +27,7 @@ import grpc
 from .address import is_port_in_use
 from .logger import log
 
-GRPC_MAX_MESSAGE_LENGTH: int = 536_870_912  # == 512 * 1024 * 1024
+GRPC_MAX_MESSAGE_LENGTH: int = 2_147_483_647  # == 2048 * 1024 * 1024 -1 (2GB)
 
 INVALID_CERTIFICATES_ERR_MSG = """
     When setting any of root_certificate, certificate, or private_key,

flwr/common/message.py

@@ -25,7 +25,7 @@ from .constant import MESSAGE_TTL_TOLERANCE
 from .logger import log
 from .record import RecordSet
 
-DEFAULT_TTL = 3600
+DEFAULT_TTL = 43200  # This is 12 hours
 
 
 class Metadata:  # pylint: disable=too-many-instance-attributes
@@ -126,6 +126,16 @@ class Metadata:  # pylint: disable=too-many-instance-attributes
         """Set creation timestamp for this message."""
         self.__dict__["_created_at"] = value
 
+    @property
+    def delivered_at(self) -> str:
+        """Unix timestamp when the message was delivered."""
+        return cast(str, self.__dict__["_delivered_at"])
+
+    @delivered_at.setter
+    def delivered_at(self, value: str) -> None:
+        """Set delivery timestamp of this message."""
+        self.__dict__["_delivered_at"] = value
+
     @property
     def ttl(self) -> float:
         """Time-to-live for this message."""
@@ -223,6 +233,7 @@ class Message:
             raise ValueError("Either `content` or `error` must be set, but not both.")
 
         metadata.created_at = time.time()  # Set the message creation timestamp
+        metadata.delivered_at = ""
         var_dict = {
             "_metadata": metadata,
             "_content": content,
@@ -310,7 +321,7 @@ class Message:
             )
             message.metadata.ttl = ttl
 
-        self._limit_task_res_ttl(message)
+        self._limit_message_res_ttl(message)
 
         return message
 
@@ -353,7 +364,7 @@ class Message:
             )
             message.metadata.ttl = ttl
 
-        self._limit_task_res_ttl(message)
+        self._limit_message_res_ttl(message)
 
         return message
 
@@ -368,14 +379,14 @@ class Message:
         )
         return f"{self.__class__.__qualname__}({view})"
 
-    def _limit_task_res_ttl(self, message: Message) -> None:
-        """Limit the TaskRes TTL to not exceed the expiration time of the TaskIns it
-        replies to.
+    def _limit_message_res_ttl(self, message: Message) -> None:
+        """Limit the TTL of the provided Message to not exceed the expiration time of
+        this Message it replies to.
 
         Parameters
         ----------
         message : Message
-            The message to which the TaskRes is replying.
+            The reply Message to limit the TTL for.
         """
         # Calculate the maximum allowed TTL
         max_allowed_ttl = (

flwr/common/object_ref.py

@@ -170,7 +170,6 @@ def load_app(  # pylint: disable= too-many-branches
                 module = importlib.import_module(module_str)
             else:
                 module = sys.modules[module_str]
-                _reload_modules(project_dir)
 
         except ModuleNotFoundError as err:
             raise error_type(
@@ -200,15 +199,6 @@ def _unload_modules(project_dir: Path) -> None:
             del sys.modules[name]
 
 
-def _reload_modules(project_dir: Path) -> None:
-    """Reload modules from the project directory."""
-    dir_str = str(project_dir.absolute())
-    for m in list(sys.modules.values()):
-        path: Optional[str] = getattr(m, "__file__", None)
-        if path is not None and path.startswith(dir_str):
-            importlib.reload(m)
-
-
 def _set_sys_path(directory: Optional[Union[str, Path]]) -> None:
     """Set the system path."""
     if directory is None:

flwr/common/record/conversion_utils.py

@@ -15,26 +15,17 @@
 """Conversion utility functions for Records."""
 
 
-from io import BytesIO
-
-import numpy as np
-
-from ..constant import SType
+from ..logger import warn_deprecated_feature
 from ..typing import NDArray
 from .parametersrecord import Array
 
+WARN_DEPRECATED_MESSAGE = (
+    "`array_from_numpy` is deprecated. Instead, use the `Array(ndarray)` class "
+    "directly or `Array.from_numpy_ndarray(ndarray)`."
+)
+
 
 def array_from_numpy(ndarray: NDArray) -> Array:
     """Create Array from NumPy ndarray."""
-    buffer = BytesIO()
-    # WARNING: NEVER set allow_pickle to true.
-    # Reason: loading pickled data can execute arbitrary code
-    # Source: https://numpy.org/doc/stable/reference/generated/numpy.save.html
-    np.save(buffer, ndarray, allow_pickle=False)
-    data = buffer.getvalue()
-    return Array(
-        dtype=str(ndarray.dtype),
-        shape=list(ndarray.shape),
-        stype=SType.NUMPY,
-        data=data,
-    )
+    warn_deprecated_feature(WARN_DEPRECATED_MESSAGE)
+    return Array.from_numpy_ndarray(ndarray)

flwr/common/record/parametersrecord.py

@@ -15,10 +15,12 @@
 """ParametersRecord and Array."""
 
 
+from __future__ import annotations
+
 from collections import OrderedDict
 from dataclasses import dataclass
 from io import BytesIO
-from typing import Optional, cast
+from typing import Any, cast, overload
 
 import numpy as np
 
@@ -27,29 +29,64 @@ from ..typing import NDArray
 from .typeddict import TypedDict
 
 
+def _raise_array_init_error() -> None:
+    raise TypeError(
+        f"Invalid arguments for {Array.__qualname__}. Expected either a "
+        "NumPy ndarray, or explicit dtype/shape/stype/data values."
+    )
+
+
 @dataclass
 class Array:
     """Array type.
 
     A dataclass containing serialized data from an array-like or tensor-like object
-    along with some metadata about it.
+    along with metadata about it. The class can be initialized in one of two ways:
+
+    1. By specifying explicit values for `dtype`, `shape`, `stype`, and `data`.
+    2. By providing a NumPy ndarray (via the `ndarray` argument).
+
+    In scenario (2), the `dtype`, `shape`, `stype`, and `data` are automatically
+    derived from the input. In scenario (1), these fields must be specified manually.
 
     Parameters
     ----------
-    dtype : str
-        A string representing the data type of the serialised object (e.g. `np.float32`)
+    dtype : Optional[str] (default: None)
+        A string representing the data type of the serialized object (e.g. `"float32"`).
+        Only required if you are not passing in a ndarray.
 
-    shape : List[int]
-        A list representing the shape of the unserialized array-like object. This is
-        used to deserialize the data (depending on the serialization method) or simply
-        as a metadata field.
+    shape : Optional[list[int]] (default: None)
+        A list representing the shape of the unserialized array-like object. Only
+        required if you are not passing in a ndarray.
 
-    stype : str
-        A string indicating the type of serialisation mechanism used to generate the
-        bytes in `data` from an array-like or tensor-like object.
+    stype : Optional[str] (default: None)
+        A string indicating the serialization mechanism used to generate the bytes in
+        `data` from an array-like or tensor-like object. Only required if you are not
+        passing in a ndarray.
 
-    data: bytes
-        A buffer of bytes containing the data.
+    data : Optional[bytes] (default: None)
+        A buffer of bytes containing the data. Only required if you are not passing in
+        a ndarray.
+
+    ndarray : Optional[NDArray] (default: None)
+        A NumPy ndarray. If provided, the `dtype`, `shape`, `stype`, and `data`
+        fields are derived automatically from it.
+
+    Examples
+    --------
+    Initializing by specifying all fields directly:
+
+    >>> arr1 = Array(
+    >>>     dtype="float32",
+    >>>     shape=[3, 3],
+    >>>     stype="numpy.ndarray",
+    >>>     data=b"serialized_data...",
+    >>> )
+
+    Initializing with a NumPy ndarray:
+
+    >>> import numpy as np
+    >>> arr2 = Array(np.random.randn(3, 3))
     """
 
     dtype: str
@@ -57,6 +94,105 @@ class Array:
     stype: str
     data: bytes
 
+    @overload
+    def __init__(  # noqa: E704
+        self, dtype: str, shape: list[int], stype: str, data: bytes
+    ) -> None: ...
+
+    @overload
+    def __init__(self, ndarray: NDArray) -> None: ...  # noqa: E704
+
+    def __init__(  # pylint: disable=too-many-arguments, too-many-locals
+        self,
+        *args: Any,
+        dtype: str | None = None,
+        shape: list[int] | None = None,
+        stype: str | None = None,
+        data: bytes | None = None,
+        ndarray: NDArray | None = None,
+    ) -> None:
+        # Determine the initialization method and validate input arguments.
+        # Support two initialization formats:
+        # 1. Array(dtype: str, shape: list[int], stype: str, data: bytes)
+        # 2. Array(ndarray: NDArray)
+
+        # Initialize all arguments
+        # If more than 4 positional arguments are provided, raise an error.
+        if len(args) > 4:
+            _raise_array_init_error()
+        all_args = [None] * 4
+        for i, arg in enumerate(args):
+            all_args[i] = arg
+        init_method: str | None = None  # Track which init method is being used
+
+        # Try to assign a value to all_args[index] if it's not already set.
+        # If an initialization method is provided, update init_method.
+        def _try_set_arg(index: int, arg: Any, method: str) -> None:
+            # Skip if arg is None
+            if arg is None:
+                return
+            # Raise an error if all_args[index] is already set
+            if all_args[index] is not None:
+                _raise_array_init_error()
+            # Raise an error if a different initialization method is already set
+            nonlocal init_method
+            if init_method is not None and init_method != method:
+                _raise_array_init_error()
+            # Set init_method and all_args[index]
+            if init_method is None:
+                init_method = method
+            all_args[index] = arg
+
+        # Try to set keyword arguments in all_args
+        _try_set_arg(0, dtype, "direct")
+        _try_set_arg(1, shape, "direct")
+        _try_set_arg(2, stype, "direct")
+        _try_set_arg(3, data, "direct")
+        _try_set_arg(0, ndarray, "ndarray")
+
+        # Check if all arguments are correctly set
+        all_args = [arg for arg in all_args if arg is not None]
+
+        # Handle direct field initialization
+        if not init_method or init_method == "direct":
+            if (
+                len(all_args) == 4  # pylint: disable=too-many-boolean-expressions
+                and isinstance(all_args[0], str)
+                and isinstance(all_args[1], list)
+                and all(isinstance(i, int) for i in all_args[1])
+                and isinstance(all_args[2], str)
+                and isinstance(all_args[3], bytes)
+            ):
+                self.dtype, self.shape, self.stype, self.data = all_args
+                return
+
+        # Handle NumPy array
+        if not init_method or init_method == "ndarray":
+            if len(all_args) == 1 and isinstance(all_args[0], np.ndarray):
+                self.__dict__.update(self.from_numpy_ndarray(all_args[0]).__dict__)
+                return
+
+        _raise_array_init_error()
+
+    @classmethod
+    def from_numpy_ndarray(cls, ndarray: NDArray) -> Array:
+        """Create Array from NumPy ndarray."""
+        assert isinstance(
+            ndarray, np.ndarray
+        ), f"Expected NumPy ndarray, got {type(ndarray)}"
+        buffer = BytesIO()
+        # WARNING: NEVER set allow_pickle to true.
+        # Reason: loading pickled data can execute arbitrary code
+        # Source: https://numpy.org/doc/stable/reference/generated/numpy.save.html
+        np.save(buffer, ndarray, allow_pickle=False)
+        data = buffer.getvalue()
+        return Array(
+            dtype=str(ndarray.dtype),
+            shape=list(ndarray.shape),
+            stype=SType.NUMPY,
+            data=data,
+        )
+
     def numpy(self) -> NDArray:
         """Return the array as a NumPy array."""
         if self.stype != SType.NUMPY:
@@ -117,7 +253,6 @@ class ParametersRecord(TypedDict[str, Array]):
 
     >>> import numpy as np
     >>> from flwr.common import ParametersRecord
-    >>> from flwr.common import array_from_numpy
     >>>
     >>> # Let's create a simple NumPy array
     >>> arr_np = np.random.randn(3, 3)
@@ -128,7 +263,7 @@ class ParametersRecord(TypedDict[str, Array]):
     >>>      [-0.10758364,  1.97619858, -0.37120501]])
     >>>
     >>> # Let's create an Array out of it
-    >>> arr = array_from_numpy(arr_np)
+    >>> arr = Array(arr_np)
     >>>
     >>> # If we print it you'll see (note the binary data)
     >>> Array(dtype='float64', shape=[3,3], stype='numpy.ndarray', data=b'@\x99\x18...')
@@ -176,7 +311,7 @@ class ParametersRecord(TypedDict[str, Array]):
 
     def __init__(
         self,
-        array_dict: Optional[OrderedDict[str, Array]] = None,
+        array_dict: OrderedDict[str, Array] | None = None,
         keep_input: bool = False,
     ) -> None:
         super().__init__(_check_key, _check_value)