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

flwr/server/compat/app.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower driver app."""
+"""Flower grid app."""
 
 
 from logging import INFO
@@ -25,27 +25,27 @@ from flwr.server.server import Server, init_defaults, run_fl
 from flwr.server.server_config import ServerConfig
 from flwr.server.strategy import Strategy
 
-from ..driver import Driver
+from ..grid import Grid
 from .app_utils import start_update_client_manager_thread
 
 
-def start_driver(  # pylint: disable=too-many-arguments, too-many-locals
+def start_grid(  # pylint: disable=too-many-arguments, too-many-locals
     *,
-    driver: Driver,
+    grid: Grid,
     server: Optional[Server] = None,
     config: Optional[ServerConfig] = None,
     strategy: Optional[Strategy] = None,
     client_manager: Optional[ClientManager] = None,
 ) -> History:
-    """Start a Flower Driver API server.
+    """Start a Flower server.
 
     Parameters
     ----------
-    driver : Driver
-        The Driver object to use.
+    grid : Grid
+        The Grid object to use.
     server : Optional[flwr.server.Server] (default: None)
         A server implementation, either `flwr.server.Server` or a subclass
-        thereof. If no instance is provided, then `start_driver` will create
+        thereof. If no instance is provided, then `start_grid` will create
         one.
     config : Optional[ServerConfig] (default: None)
         Currently supported values are `num_rounds` (int, default: 1) and
@@ -56,7 +56,7 @@ def start_driver(  # pylint: disable=too-many-arguments, too-many-locals
         `start_server` will use `flwr.server.strategy.FedAvg`.
     client_manager : Optional[flwr.server.ClientManager] (default: None)
         An implementation of the class `flwr.server.ClientManager`. If no
-        implementation is provided, then `start_driver` will use
+        implementation is provided, then `start_grid` will use
         `flwr.server.SimpleClientManager`.
 
     Returns
@@ -64,7 +64,7 @@ def start_driver(  # pylint: disable=too-many-arguments, too-many-locals
     hist : flwr.server.history.History
         Object containing training and evaluation metrics.
     """
-    # Initialize the Driver API server and config
+    # Initialize the server and config
     initialized_server, initialized_config = init_defaults(
         server=server,
         config=config,
@@ -79,10 +79,13 @@ def start_driver(  # pylint: disable=too-many-arguments, too-many-locals
     log(INFO, "")
 
     # Start the thread updating nodes
-    thread, f_stop = start_update_client_manager_thread(
-        driver, initialized_server.client_manager()
+    thread, f_stop, c_done = start_update_client_manager_thread(
+        grid, initialized_server.client_manager()
     )
 
+    # Wait until the node registration done
+    c_done.wait()
+
     # Start training
     hist = run_fl(
         server=initialized_server,

flwr/server/compat/app_utils.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Utility functions for the `start_driver`."""
+"""Utility functions for the `start_grid`."""
 
 
 import threading
@@ -20,18 +20,18 @@ import threading
 from flwr.common.typing import RunNotRunningException
 
 from ..client_manager import ClientManager
-from ..compat.driver_client_proxy import DriverClientProxy
-from ..driver import Driver
+from ..grid import Grid
+from .grid_client_proxy import GridClientProxy
 
 
 def start_update_client_manager_thread(
-    driver: Driver,
+    grid: Grid,
     client_manager: ClientManager,
-) -> tuple[threading.Thread, threading.Event]:
+) -> tuple[threading.Thread, threading.Event, threading.Event]:
     """Periodically update the nodes list in the client manager in a thread.
 
-    This function starts a thread that periodically uses the associated driver to
-    get all node_ids. Each node_id is then converted into a `DriverClientProxy`
+    This function starts a thread that periodically uses the associated grid to
+    get all node_ids. Each node_id is then converted into a `GridClientProxy`
     instance and stored in the `registered_nodes` dictionary with node_id as key.
 
     New nodes will be added to the ClientManager via `client_manager.register()`,
@@ -40,8 +40,8 @@ def start_update_client_manager_thread(
 
     Parameters
     ----------
-    driver : Driver
-        The Driver object to use.
+    grid : Grid
+        The Grid object to use.
     client_manager : ClientManager
         The ClientManager object to be updated.
 
@@ -51,33 +51,38 @@ def start_update_client_manager_thread(
         A thread that updates the ClientManager and handles the stop event.
     threading.Event
         An event that, when set, signals the thread to stop.
+    threading.Event
+        An event that, when set, signals the node registration done.
     """
     f_stop = threading.Event()
+    c_done = threading.Event()
     thread = threading.Thread(
         target=_update_client_manager,
         args=(
-            driver,
+            grid,
             client_manager,
             f_stop,
+            c_done,
         ),
         daemon=True,
     )
     thread.start()
 
-    return thread, f_stop
+    return thread, f_stop, c_done
 
 
 def _update_client_manager(
-    driver: Driver,
+    grid: Grid,
     client_manager: ClientManager,
     f_stop: threading.Event,
+    c_done: threading.Event,
 ) -> None:
     """Update the nodes list in the client manager."""
-    # Loop until the driver is disconnected
-    registered_nodes: dict[int, DriverClientProxy] = {}
+    # Loop until the grid is disconnected
+    registered_nodes: dict[int, GridClientProxy] = {}
     while not f_stop.is_set():
         try:
-            all_node_ids = set(driver.get_node_ids())
+            all_node_ids = set(grid.get_node_ids())
         except RunNotRunningException:
             f_stop.set()
             break
@@ -92,16 +97,19 @@ def _update_client_manager(
 
         # Register new nodes
         for node_id in new_nodes:
-            client_proxy = DriverClientProxy(
+            client_proxy = GridClientProxy(
                 node_id=node_id,
-                driver=driver,
-                run_id=driver.run.run_id,
+                grid=grid,
+                run_id=grid.run.run_id,
             )
             if client_manager.register(client_proxy):
                 registered_nodes[node_id] = client_proxy
             else:
                 raise RuntimeError("Could not register node.")
 
+        # Flag first pass for nodes registration is completed
+        c_done.set()
+
         # Sleep for 3 seconds
         if not f_stop.is_set():
             f_stop.wait(3)

flwr/server/compat/{driver_client_proxy.py → grid_client_proxy.py}

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.
@@ -12,26 +12,26 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower ClientProxy implementation for Driver API."""
+"""Flower ClientProxy implementation using Grid."""
 
 
 from typing import Optional
 
 from flwr import common
-from flwr.common import Message, MessageType, MessageTypeLegacy, RecordSet
-from flwr.common import recordset_compat as compat
+from flwr.common import Message, MessageType, MessageTypeLegacy, RecordDict
+from flwr.common import recorddict_compat as compat
 from flwr.server.client_proxy import ClientProxy
 
-from ..driver.driver import Driver
+from ..grid.grid import Grid
 
 
-class DriverClientProxy(ClientProxy):
-    """Flower client proxy which delegates work using the Driver API."""
+class GridClientProxy(ClientProxy):
+    """Flower client proxy which delegates work using Grid."""
 
-    def __init__(self, node_id: int, driver: Driver, run_id: int):
+    def __init__(self, node_id: int, grid: Grid, run_id: int):
         super().__init__(str(node_id))
         self.node_id = node_id
-        self.driver = driver
+        self.grid = grid
         self.run_id = run_id
 
     def get_properties(
@@ -41,14 +41,14 @@ class DriverClientProxy(ClientProxy):
         group_id: Optional[int],
     ) -> common.GetPropertiesRes:
         """Return client's properties."""
-        # Ins to RecordSet
-        out_recordset = compat.getpropertiesins_to_recordset(ins)
+        # Ins to RecordDict
+        out_recorddict = compat.getpropertiesins_to_recorddict(ins)
         # Fetch response
-        in_recordset = self._send_receive_recordset(
-            out_recordset, MessageTypeLegacy.GET_PROPERTIES, timeout, group_id
+        in_recorddict = self._send_receive_recorddict(
+            out_recorddict, MessageTypeLegacy.GET_PROPERTIES, timeout, group_id
         )
-        # RecordSet to Res
-        return compat.recordset_to_getpropertiesres(in_recordset)
+        # RecordDict to Res
+        return compat.recorddict_to_getpropertiesres(in_recorddict)
 
     def get_parameters(
         self,
@@ -57,40 +57,40 @@ class DriverClientProxy(ClientProxy):
         group_id: Optional[int],
     ) -> common.GetParametersRes:
         """Return the current local model parameters."""
-        # Ins to RecordSet
-        out_recordset = compat.getparametersins_to_recordset(ins)
+        # Ins to RecordDict
+        out_recorddict = compat.getparametersins_to_recorddict(ins)
         # Fetch response
-        in_recordset = self._send_receive_recordset(
-            out_recordset, MessageTypeLegacy.GET_PARAMETERS, timeout, group_id
+        in_recorddict = self._send_receive_recorddict(
+            out_recorddict, MessageTypeLegacy.GET_PARAMETERS, timeout, group_id
         )
-        # RecordSet to Res
-        return compat.recordset_to_getparametersres(in_recordset, False)
+        # RecordDict to Res
+        return compat.recorddict_to_getparametersres(in_recorddict, False)
 
     def fit(
         self, ins: common.FitIns, timeout: Optional[float], group_id: Optional[int]
     ) -> common.FitRes:
         """Train model parameters on the locally held dataset."""
-        # Ins to RecordSet
-        out_recordset = compat.fitins_to_recordset(ins, keep_input=True)
+        # Ins to RecordDict
+        out_recorddict = compat.fitins_to_recorddict(ins, keep_input=True)
         # Fetch response
-        in_recordset = self._send_receive_recordset(
-            out_recordset, MessageType.TRAIN, timeout, group_id
+        in_recorddict = self._send_receive_recorddict(
+            out_recorddict, MessageType.TRAIN, timeout, group_id
         )
-        # RecordSet to Res
-        return compat.recordset_to_fitres(in_recordset, keep_input=False)
+        # RecordDict to Res
+        return compat.recorddict_to_fitres(in_recorddict, keep_input=False)
 
     def evaluate(
         self, ins: common.EvaluateIns, timeout: Optional[float], group_id: Optional[int]
     ) -> common.EvaluateRes:
         """Evaluate model parameters on the locally held dataset."""
-        # Ins to RecordSet
-        out_recordset = compat.evaluateins_to_recordset(ins, keep_input=True)
+        # Ins to RecordDict
+        out_recorddict = compat.evaluateins_to_recorddict(ins, keep_input=True)
         # Fetch response
-        in_recordset = self._send_receive_recordset(
-            out_recordset, MessageType.EVALUATE, timeout, group_id
+        in_recorddict = self._send_receive_recorddict(
+            out_recorddict, MessageType.EVALUATE, timeout, group_id
         )
-        # RecordSet to Res
-        return compat.recordset_to_evaluateres(in_recordset)
+        # RecordDict to Res
+        return compat.recorddict_to_evaluateres(in_recorddict)
 
     def reconnect(
         self,
@@ -101,25 +101,25 @@ class DriverClientProxy(ClientProxy):
         """Disconnect and (optionally) reconnect later."""
         return common.DisconnectRes(reason="")  # Nothing to do here (yet)
 
-    def _send_receive_recordset(
+    def _send_receive_recorddict(
         self,
-        recordset: RecordSet,
-        task_type: str,
+        recorddict: RecordDict,
+        message_type: str,
         timeout: Optional[float],
         group_id: Optional[int],
-    ) -> RecordSet:
+    ) -> RecordDict:
 
         # Create message
-        message = self.driver.create_message(
-            content=recordset,
-            message_type=task_type,
+        message = Message(
+            content=recorddict,
+            message_type=message_type,
             dst_node_id=self.node_id,
             group_id=str(group_id) if group_id else "",
             ttl=timeout,
         )
 
         # Send message and wait for reply
-        messages = list(self.driver.send_and_receive(messages=[message]))
+        messages = list(self.grid.send_and_receive(messages=[message]))
 
         # A single reply is expected
         if len(messages) != 1:

flwr/server/fleet_event_log_interceptor.py

@@ -0,0 +1,94 @@
+# 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.
+# ==============================================================================
+"""Flower Fleet API event log interceptor."""
+
+
+from typing import Any, Callable, cast
+
+import grpc
+from google.protobuf.message import Message as GrpcMessage
+
+from flwr.common.event_log_plugin.event_log_plugin import EventLogWriterPlugin
+from flwr.common.typing import LogEntry
+
+
+class FleetEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
+    """Fleet API interceptor for logging events."""
+
+    def __init__(self, log_plugin: EventLogWriterPlugin) -> None:
+        self.log_plugin = log_plugin
+
+    def intercept_service(
+        self,
+        continuation: Callable[[Any], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> grpc.RpcMethodHandler:
+        """Flower Fleet API server interceptor logging logic.
+
+        Intercept all unary-unary calls from users and log the event. Continue RPC call
+        if event logger is enabled on the SuperLink, else, terminate RPC call by setting
+        context to abort.
+        """
+        # One of the method handlers in
+        # `flwr.server.superlink.fleet.grpc_rere.fleet_servicer.FleetServicer`
+        method_handler: grpc.RpcMethodHandler = continuation(handler_call_details)
+        method_name: str = handler_call_details.method
+        return self._generic_event_log_unary_method_handler(method_handler, method_name)
+
+    def _generic_event_log_unary_method_handler(
+        self, method_handler: grpc.RpcMethodHandler, method_name: str
+    ) -> grpc.RpcMethodHandler:
+        def _generic_method_handler(
+            request: GrpcMessage,
+            context: grpc.ServicerContext,
+        ) -> GrpcMessage:
+            log_entry: LogEntry
+            # Log before call
+            log_entry = self.log_plugin.compose_log_before_event(
+                request=request,
+                context=context,
+                user_info=None,
+                method_name=method_name,
+            )
+            self.log_plugin.write_log(log_entry)
+
+            call = method_handler.unary_unary
+            unary_response, error = None, None
+            try:
+                unary_response = cast(GrpcMessage, call(request, context))
+            except BaseException as e:
+                error = e
+                raise
+            finally:
+                log_entry = self.log_plugin.compose_log_after_event(
+                    request=request,
+                    context=context,
+                    user_info=None,
+                    method_name=method_name,
+                    response=unary_response or error,
+                )
+                self.log_plugin.write_log(log_entry)
+            return unary_response
+
+        if method_handler.unary_unary:
+            message_handler = grpc.unary_unary_rpc_method_handler
+        else:
+            # If the method type is not `unary_unary` raise an error
+            raise NotImplementedError("This RPC method type is not supported.")
+        return message_handler(
+            _generic_method_handler,
+            request_deserializer=method_handler.request_deserializer,
+            response_serializer=method_handler.response_serializer,
+        )

flwr/server/{driver → grid}/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2022 Flower Labs GmbH. All Rights Reserved.
+# 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.
@@ -12,15 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower driver SDK."""
+"""Flower grid SDK."""
 
 
-from .driver import Driver
-from .grpc_driver import GrpcDriver
-from .inmemory_driver import InMemoryDriver
+from .grid import Driver, Grid
+from .grpc_grid import GrpcGrid
+from .inmemory_grid import InMemoryGrid
 
 __all__ = [
     "Driver",
-    "GrpcDriver",
-    "InMemoryDriver",
+    "Grid",
+    "GrpcGrid",
+    "InMemoryGrid",
 ]

flwr/server/{driver/driver.py → grid/grid.py}

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.
@@ -12,32 +12,32 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Driver (abstract base class)."""
+"""Grid (abstract base class)."""
 
 
 from abc import ABC, abstractmethod
 from collections.abc import Iterable
 from typing import Optional
 
-from flwr.common import Message, RecordSet
+from flwr.common import Message, RecordDict
 from flwr.common.typing import Run
 
 
-class Driver(ABC):
-    """Abstract base Driver class for the ServerAppIo API."""
+class Grid(ABC):
+    """Abstract base class Grid to send/receive messages."""
 
     @abstractmethod
     def set_run(self, run_id: int) -> None:
         """Request a run to the SuperLink with a given `run_id`.
 
-        If a Run with the specified `run_id` exists, a local Run
+        If a ``Run`` with the specified ``run_id`` exists, a local ``Run``
         object will be created. It enables further functionality
-        in the driver, such as sending `Messages`.
+        in the grid, such as sending ``Message``s.
 
         Parameters
         ----------
         run_id : int
-            The `run_id` of the Run this Driver object operates in.
+            The ``run_id`` of the ``Run`` this ``Grid`` object operates in.
         """
 
     @property
@@ -48,7 +48,7 @@ class Driver(ABC):
     @abstractmethod
     def create_message(  # pylint: disable=too-many-arguments,R0917
         self,
-        content: RecordSet,
+        content: RecordDict,
         message_type: str,
         dst_node_id: int,
         group_id: str,
@@ -56,12 +56,12 @@ class Driver(ABC):
     ) -> Message:
         """Create a new message with specified parameters.
 
-        This method constructs a new `Message` with given content and metadata.
-        The `run_id` and `src_node_id` will be set automatically.
+        This method constructs a new ``Message`` with given content and metadata.
+        The ``run_id`` and ``src_node_id`` will be set automatically.
 
         Parameters
         ----------
-        content : RecordSet
+        content : RecordDict
             The content for the new message. This holds records that are to be sent
             to the destination node.
         message_type : str
@@ -71,12 +71,12 @@ class Driver(ABC):
             The ID of the destination node to which the message is being sent.
         group_id : str
             The ID of the group to which this message is associated. In some settings,
-            this is used as the FL round.
+            this is used as the federated learning round.
         ttl : Optional[float] (default: None)
             Time-to-live for the round trip of this message, i.e., the time from sending
             this message to receiving a reply. It specifies in seconds the duration for
             which the message and its potential reply are considered valid. If unset,
-            the default TTL (i.e., `common.DEFAULT_TTL`) will be used.
+            the default TTL (i.e., ``common.DEFAULT_TTL``) will be used.
 
         Returns
         -------
@@ -85,7 +85,7 @@ class Driver(ABC):
         """
 
     @abstractmethod
-    def get_node_ids(self) -> list[int]:
+    def get_node_ids(self) -> Iterable[int]:
         """Get node IDs."""
 
     @abstractmethod
@@ -93,7 +93,7 @@ class Driver(ABC):
         """Push messages to specified node IDs.
 
         This method takes an iterable of messages and sends each message
-        to the node specified in `dst_node_id`.
+        to the node specified in ``dst_node_id``.
 
         Parameters
         ----------
@@ -154,8 +154,37 @@ class Driver(ABC):
 
         Notes
         -----
-        This method uses `push_messages` to send the messages and `pull_messages`
-        to collect the replies. If `timeout` is set, the method may not return
+        This method uses ``push_messages`` to send the messages and ``pull_messages``
+        to collect the replies. If ``timeout`` is set, the method may not return
         replies for all sent messages. A message remains valid until its TTL,
-        which is not affected by `timeout`.
+        which is not affected by ``timeout``.
         """
+
+
+class Driver(Grid):
+    """Deprecated abstract base class ``Driver``, use ``Grid`` instead.
+
+    This class is provided solely for backward compatibility with legacy
+    code that previously relied on the ``Driver`` class. It has been deprecated
+    in favor of the updated abstract base class ``Grid``, which now encompasses
+    all communication-related functionality and improvements between the
+    ServerApp and the SuperLink.
+
+    .. warning::
+        ``Driver`` is deprecated and will be removed in a future release.
+        Use `Grid` in the signature of your ServerApp.
+
+    Examples
+    --------
+    Legacy (deprecated) usage::
+
+        @app.main()
+        def main(driver: Driver, context: Context) -> None:
+            ...
+
+    Updated usage::
+
+        @app.main()
+        def main(grid: Grid, context: Context) -> None:
+            ...
+    """