flwr-nightly 1.17.0.dev20250318__py3-none-any.whl → 1.17.0.dev20250319__py3-none-any.whl

flwr/common/constant.py

@@ -61,6 +61,7 @@ PING_CALL_TIMEOUT = 5
 PING_BASE_MULTIPLIER = 0.8
 PING_RANDOM_RANGE = (-0.1, 0.1)
 PING_MAX_INTERVAL = 1e300
+PING_PATIENCE = 2
 
 # IDs
 RUN_ID_NUM_BYTES = 8
@@ -166,6 +167,7 @@ class ErrorCode:
     CLIENT_APP_RAISED_EXCEPTION = 2
     MESSAGE_UNAVAILABLE = 3
     REPLY_MESSAGE_UNAVAILABLE = 4
+    NODE_UNAVAILABLE = 5
 
     def __new__(cls) -> ErrorCode:
         """Prevent instantiation."""

flwr/common/logger.py

@@ -250,9 +250,9 @@ def warn_deprecated_feature_with_example(
     log(
         WARN,
         """FEATURE UPDATE: %s
-        ------------------------------------------------------------
+            ------------------------------------------------------------
         %s
-        ------------------------------------------------------------
+            ------------------------------------------------------------
         """,
         example_message,
         code_example,

flwr/server/__init__.py

@@ -22,6 +22,7 @@ from .client_manager import ClientManager as ClientManager
 from .client_manager import SimpleClientManager as SimpleClientManager
 from .compat import LegacyContext as LegacyContext
 from .grid import Driver as Driver
+from .grid import Grid as Grid
 from .history import History as History
 from .server import Server as Server
 from .server_app import ServerApp as ServerApp
@@ -31,6 +32,7 @@ from .serverapp_components import ServerAppComponents as ServerAppComponents
 __all__ = [
     "ClientManager",
     "Driver",
+    "Grid",
     "History",
     "LegacyContext",
     "Server",

flwr/server/compat/__init__.py

@@ -15,10 +15,10 @@
 """Flower ServerApp compatibility package."""
 
 
-from .app import start_driver as start_driver
+from .app import start_grid as start_grid
 from .legacy_context import LegacyContext as LegacyContext
 
 __all__ = [
     "LegacyContext",
-    "start_driver",
+    "start_grid",
 ]

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,7 +12,7 @@
 # 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
@@ -22,16 +22,16 @@ from flwr.common import Message, MessageType, MessageTypeLegacy, RecordSet
 from flwr.common import recordset_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(
@@ -110,7 +110,7 @@ class DriverClientProxy(ClientProxy):
     ) -> RecordSet:
 
         # Create message
-        message = self.driver.create_message(
+        message = self.grid.create_message(
             content=recordset,
             message_type=message_type,
             dst_node_id=self.node_id,
@@ -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,7 +12,7 @@
 # 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
@@ -23,21 +23,21 @@ from flwr.common import Message, RecordSet
 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
@@ -56,8 +56,8 @@ 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
         ----------
@@ -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
@@ -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:
@@ -197,7 +198,7 @@ class GrpcDriver(Driver):
 
     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)
         )
@@ -220,7 +221,7 @@ 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

flwr/server/grid/inmemory_grid.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower in-memory Driver."""
+"""Flower in-memory Grid."""
 
 
 import time
@@ -26,16 +26,16 @@ from flwr.common.typing import Run
 from flwr.proto.node_pb2 import Node  # pylint: disable=E0611
 from flwr.server.superlink.linkstate import LinkStateFactory
 
-from .grid import Driver
+from .grid import Grid
 
 
-class InMemoryDriver(Driver):
-    """`InMemoryDriver` class provides an interface to the ServerAppIo API.
+class InMemoryGrid(Grid):
+    """`InMemoryGrid` class provides an interface to the ServerAppIo API.
 
     Parameters
     ----------
     state_factory : StateFactory
-        A StateFactory embedding a state that this driver can interface with.
+        A StateFactory embedding a state that this grid can interface with.
     pull_interval : float (default=0.1)
         Sleep duration between calls to `pull_messages`.
     """

flwr/server/run_serverapp.py

@@ -22,18 +22,18 @@ from flwr.common import Context
 from flwr.common.logger import log
 from flwr.common.object_ref import load_app
 
-from .grid import Driver
+from .grid import Grid
 from .server_app import LoadServerAppError, ServerApp
 
 
 def run(
-    driver: Driver,
+    grid: Grid,
     context: Context,
     server_app_dir: str,
     server_app_attr: Optional[str] = None,
     loaded_server_app: Optional[ServerApp] = None,
 ) -> Context:
-    """Run ServerApp with a given Driver."""
+    """Run ServerApp with a given Grid."""
     if not (server_app_attr is None) ^ (loaded_server_app is None):
         raise ValueError(
             "Either `server_app_attr` or `loaded_server_app` should be set "
@@ -59,7 +59,7 @@ def run(
     server_app = _load()
 
     # Call ServerApp
-    server_app(driver=driver, context=context)
+    server_app(grid=grid, context=context)
 
     log(DEBUG, "ServerApp finished running.")
     return context

flwr/server/server_app.py

@@ -15,6 +15,7 @@
 """Flower ServerApp."""
 
 
+import inspect
 from collections.abc import Iterator
 from contextlib import contextmanager
 from typing import Callable, Optional
@@ -24,8 +25,8 @@ from flwr.common.logger import warn_deprecated_feature_with_example
 from flwr.server.strategy import Strategy
 
 from .client_manager import ClientManager
-from .compat import start_driver
-from .grid import Driver
+from .compat import start_grid
+from .grid import Driver, Grid
 from .server import Server
 from .server_config import ServerConfig
 from .typing import ServerAppCallable, ServerFn
@@ -43,6 +44,21 @@ SERVER_FN_USAGE_EXAMPLE = """
         app = ServerApp(server_fn=server_fn)
 """
 
+GRID_USAGE_EXAMPLE = """
+                app = ServerApp()
+
+                @app.main()
+                def main(grid: Grid, context: Context) -> None:
+                    # Your existing ServerApp code ...
+"""
+
+DRIVER_DEPRECATION_MSG = """
+            The `Driver` class is deprecated, it will be removed in a future release.
+"""
+DRIVER_EXAMPLE_MSG = """
+            Instead, use `Grid` in the signature of your `ServerApp`. For example:
+"""
+
 
 @contextmanager
 def _empty_lifespan(_: Context) -> Iterator[None]:
@@ -54,7 +70,7 @@ class ServerApp:  # pylint: disable=too-many-instance-attributes
 
     Examples
     --------
-    Use the `ServerApp` with an existing `Strategy`:
+    Use the ``ServerApp`` with an existing ``Strategy``:
 
     >>> def server_fn(context: Context):
     >>>     server_config = ServerConfig(num_rounds=3)
@@ -66,12 +82,12 @@ class ServerApp:  # pylint: disable=too-many-instance-attributes
     >>>
     >>> app = ServerApp(server_fn=server_fn)
 
-    Use the `ServerApp` with a custom main function:
+    Use the ``ServerApp`` with a custom main function:
 
     >>> app = ServerApp()
     >>>
     >>> @app.main()
-    >>> def main(driver: Driver, context: Context) -> None:
+    >>> def main(grid: Grid, context: Context) -> None:
     >>>    print("ServerApp running")
     """
 
@@ -111,7 +127,7 @@ class ServerApp:  # pylint: disable=too-many-instance-attributes
         self._main: Optional[ServerAppCallable] = None
         self._lifespan = _empty_lifespan
 
-    def __call__(self, driver: Driver, context: Context) -> None:
+    def __call__(self, grid: Grid, context: Context) -> None:
         """Execute `ServerApp`."""
         with self._lifespan(context):
             # Compatibility mode
@@ -123,17 +139,17 @@ class ServerApp:  # pylint: disable=too-many-instance-attributes
                     self._config = components.config
                     self._strategy = components.strategy
                     self._client_manager = components.client_manager
-                start_driver(
+                start_grid(
                     server=self._server,
                     config=self._config,
                     strategy=self._strategy,
                     client_manager=self._client_manager,
-                    driver=driver,
+                    grid=grid,
                 )
                 return
 
             # New execution mode
-            self._main(driver, context)
+            self._main(grid, context)
 
     def main(self) -> Callable[[ServerAppCallable], ServerAppCallable]:
         """Return a decorator that registers the main fn with the server app.
@@ -143,7 +159,7 @@ class ServerApp:  # pylint: disable=too-many-instance-attributes
         >>> app = ServerApp()
         >>>
         >>> @app.main()
-        >>> def main(driver: Driver, context: Context) -> None:
+        >>> def main(grid: Grid, context: Context) -> None:
         >>>    print("ServerApp running")
         """
 
@@ -168,11 +184,21 @@ class ServerApp:  # pylint: disable=too-many-instance-attributes
                     >>> app = ServerApp()
                     >>>
                     >>> @app.main()
-                    >>> def main(driver: Driver, context: Context) -> None:
+                    >>> def main(grid: Grid, context: Context) -> None:
                     >>>    print("ServerApp running")
                     """,
                 )
 
+            sig = inspect.signature(main_fn)
+            param = list(sig.parameters.values())[0]
+            # Check if parameter name or the annotation should be updated
+            if param.name == "driver" or param.annotation is Driver:
+                warn_deprecated_feature_with_example(
+                    deprecation_message=DRIVER_DEPRECATION_MSG,
+                    example_message=DRIVER_EXAMPLE_MSG,
+                    code_example=GRID_USAGE_EXAMPLE,
+                )
+
             # Register provided function with the ServerApp object
             self._main = main_fn