flwr-nightly 1.17.0.dev20250318__py3-none-any.whl → 1.17.0.dev20250320__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 ..grid 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,
@@ -80,7 +80,7 @@ def start_driver(  # pylint: disable=too-many-arguments, too-many-locals
 
     # Start the thread updating nodes
     thread, f_stop, c_done = start_update_client_manager_thread(
-        driver, initialized_server.client_manager()
+        grid, initialized_server.client_manager()
     )
 
     # Wait until the node registration done

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 ..grid import Driver
-from .grid_client_proxy import DriverClientProxy
+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, 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.
 
@@ -59,7 +59,7 @@ def start_update_client_manager_thread(
     thread = threading.Thread(
         target=_update_client_manager,
         args=(
-            driver,
+            grid,
             client_manager,
             f_stop,
             c_done,
@@ -72,17 +72,17 @@ def start_update_client_manager_thread(
 
 
 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
@@ -97,10 +97,10 @@ 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

flwr/server/compat/grid_client_proxy.py

@@ -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 ..grid.grid 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,17 +101,17 @@ 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,
+        recorddict: RecordDict,
         message_type: str,
         timeout: Optional[float],
         group_id: Optional[int],
-    ) -> RecordSet:
+    ) -> RecordDict:
 
         # Create message
-        message = self.driver.create_message(
-            content=recordset,
+        message = self.grid.create_message(
+            content=recorddict,
             message_type=message_type,
             dst_node_id=self.node_id,
             group_id=str(group_id) if group_id else "",
@@ -119,7 +119,7 @@ class DriverClientProxy(ClientProxy):
         )
 
         # 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/grid/__init__.py

@@ -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 .grid import Driver
-from .grpc_grid import GrpcDriver
-from .inmemory_grid 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/grid/grid.py

@@ -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
         -------
@@ -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:
+            ...
+    """

flwr/server/grid/grpc_grid.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower gRPC Driver."""
+"""Flower gRPC Grid."""
 
 
 import time
@@ -22,13 +22,13 @@ from typing import Optional, cast
 
 import grpc
 
-from flwr.common import DEFAULT_TTL, Message, Metadata, RecordSet
+from flwr.common import Message, RecordDict
 from flwr.common.constant import (
     SERVERAPPIO_API_DEFAULT_CLIENT_ADDRESS,
     SUPERLINK_NODE_ID,
 )
 from flwr.common.grpc import create_channel, on_channel_state_change
-from flwr.common.logger import log
+from flwr.common.logger import log, warn_deprecated_feature
 from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
 from flwr.common.serde import message_from_proto, message_to_proto, run_from_proto
 from flwr.common.typing import Run
@@ -45,11 +45,11 @@ from flwr.proto.serverappio_pb2 import (  # pylint: disable=E0611
 )
 from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub  # pylint: disable=E0611
 
-from .grid import Driver
+from .grid import Grid
 
 ERROR_MESSAGE_PUSH_MESSAGES_RESOURCE_EXHAUSTED = """
 
-[Driver.push_messages] gRPC error occurred:
+[Grid.push_messages] gRPC error occurred:
 
 The 2GB gRPC limit has been reached. Consider reducing the number of messages pushed
 at once, or push messages individually, for example:
@@ -57,13 +57,13 @@ at once, or push messages individually, for example:
 > msgs = [msg1, msg2, msg3]
 > msg_ids = []
 > for msg in msgs:
->     msg_id = driver.push_messages([msg])
+>     msg_id = grid.push_messages([msg])
 >     msg_ids.extend(msg_id)
 """
 
 ERROR_MESSAGE_PULL_MESSAGES_RESOURCE_EXHAUSTED = """
 
-[Driver.pull_messages] gRPC error occurred:
+[Grid.pull_messages] gRPC error occurred:
 
 The 2GB gRPC limit has been reached. Consider reducing the number of messages pulled
 at once, or pull messages individually, for example:
@@ -71,13 +71,13 @@ at once, or pull messages individually, for example:
 > msgs_ids = [msg_id1, msg_id2, msg_id3]
 > msgs = []
 > for msg_id in msg_ids:
->     msg = driver.pull_messages([msg_id])
+>     msg = grid.pull_messages([msg_id])
 >     msgs.extend(msg)
 """
 
 
-class GrpcDriver(Driver):
-    """`GrpcDriver` provides an interface to the ServerAppIo API.
+class GrpcGrid(Grid):
+    """`GrpcGrid` provides an interface to the ServerAppIo API.
 
     Parameters
     ----------
@@ -101,6 +101,7 @@ class GrpcDriver(Driver):
         self._channel: Optional[grpc.Channel] = None
         self.node = Node(node_id=SUPERLINK_NODE_ID)
         self._retry_invoker = _make_simple_grpc_retry_invoker()
+        super().__init__()
 
     @property
     def _is_connected(self) -> bool:
@@ -160,18 +161,15 @@ class GrpcDriver(Driver):
     def _check_message(self, message: Message) -> None:
         # Check if the message is valid
         if not (
-            # Assume self._run being initialized
-            message.metadata.run_id == cast(Run, self._run).run_id
-            and message.metadata.src_node_id == self.node.node_id
-            and message.metadata.message_id == ""
-            and message.metadata.reply_to_message == ""
+            message.metadata.message_id == ""
+            and message.metadata.reply_to_message_id == ""
             and message.metadata.ttl > 0
         ):
             raise ValueError(f"Invalid message: {message}")
 
     def create_message(  # pylint: disable=too-many-arguments,R0917
         self,
-        content: RecordSet,
+        content: RecordDict,
         message_type: str,
         dst_node_id: int,
         group_id: str,
@@ -182,22 +180,15 @@ class GrpcDriver(Driver):
         This method constructs a new `Message` with given content and metadata.
         The `run_id` and `src_node_id` will be set automatically.
         """
-        ttl_ = DEFAULT_TTL if ttl is None else ttl
-        metadata = Metadata(
-            run_id=cast(Run, self._run).run_id,
-            message_id="",  # Will be set by the server
-            src_node_id=self.node.node_id,
-            dst_node_id=dst_node_id,
-            reply_to_message="",
-            group_id=group_id,
-            ttl=ttl_,
-            message_type=message_type,
+        warn_deprecated_feature(
+            "`Driver.create_message` / `Grid.create_message` is deprecated."
+            "Use `Message` constructor instead."
         )
-        return Message(metadata=metadata, content=content)
+        return Message(content, dst_node_id, message_type, ttl=ttl, group_id=group_id)
 
     def get_node_ids(self) -> Iterable[int]:
         """Get node IDs."""
-        # Call GrpcDriverStub method
+        # Call GrpcServerAppIoStub method
         res: GetNodesResponse = self._stub.GetNodes(
             GetNodesRequest(run_id=cast(Run, self._run).run_id)
         )
@@ -210,8 +201,12 @@ class GrpcDriver(Driver):
         to the node specified in `dst_node_id`.
         """
         # Construct Messages
+        run_id = cast(Run, self._run).run_id
         message_proto_list: list[ProtoMessage] = []
         for msg in messages:
+            # Populate metadata
+            msg.metadata.__dict__["_run_id"] = run_id
+            msg.metadata.__dict__["_src_node_id"] = self.node.node_id
             # Check message
             self._check_message(msg)
             # Convert to proto
@@ -220,11 +215,9 @@ class GrpcDriver(Driver):
             message_proto_list.append(msg_proto)
 
         try:
-            # Call GrpcDriverStub method
+            # Call GrpcServerAppIoStub method
             res: PushInsMessagesResponse = self._stub.PushMessages(
-                PushInsMessagesRequest(
-                    messages_list=message_proto_list, run_id=cast(Run, self._run).run_id
-                )
+                PushInsMessagesRequest(messages_list=message_proto_list, run_id=run_id)
             )
             if len([msg_id for msg_id in res.message_ids if msg_id]) != len(
                 message_proto_list
@@ -288,7 +281,7 @@ class GrpcDriver(Driver):
             res_msgs = self.pull_messages(msg_ids)
             ret.extend(res_msgs)
             msg_ids.difference_update(
-                {msg.metadata.reply_to_message for msg in res_msgs}
+                {msg.metadata.reply_to_message_id for msg in res_msgs}
             )
             if len(msg_ids) == 0:
                 break