flwr-nightly 1.8.0.dev20240315__py3-none-any.whl → 1.15.0.dev20250115__py3-none-any.whl

flwr/server/run_serverapp.py

@@ -15,40 +15,38 @@
 """Run ServerApp."""
 
 
-import argparse
-import sys
-from logging import DEBUG, INFO, WARN
-from pathlib import Path
+from logging import DEBUG, ERROR
 from typing import Optional
 
-from flwr.common import Context, EventType, RecordSet, event
-from flwr.common.logger import log, update_console_handler
+from flwr.common import Context, EventType, event
+from flwr.common.exit_handlers import register_exit_handlers
+from flwr.common.logger import log
 from flwr.common.object_ref import load_app
 
-from .driver.driver import Driver
+from .driver import Driver
 from .server_app import LoadServerAppError, ServerApp
 
 
 def run(
     driver: Driver,
+    context: Context,
     server_app_dir: str,
     server_app_attr: Optional[str] = None,
     loaded_server_app: Optional[ServerApp] = None,
-) -> None:
+) -> Context:
     """Run ServerApp with a given Driver."""
     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 "
-            "but not both. "
+            "but not both."
         )
 
-    if server_app_dir is not None:
-        sys.path.insert(0, server_app_dir)
-
     # Load ServerApp if needed
     def _load() -> ServerApp:
         if server_app_attr:
-            server_app: ServerApp = load_app(server_app_attr, LoadServerAppError)
+            server_app: ServerApp = load_app(
+                server_app_attr, LoadServerAppError, server_app_dir
+            )
 
             if not isinstance(server_app, ServerApp):
                 raise LoadServerAppError(
@@ -61,127 +59,18 @@ def run(
 
     server_app = _load()
 
-    # Initialize Context
-    context = Context(state=RecordSet())
-
     # Call ServerApp
     server_app(driver=driver, context=context)
 
     log(DEBUG, "ServerApp finished running.")
+    return context
 
 
 def run_server_app() -> None:
     """Run Flower server app."""
     event(EventType.RUN_SERVER_APP_ENTER)
-
-    args = _parse_args_run_server_app().parse_args()
-
-    update_console_handler(
-        level=DEBUG if args.verbose else INFO,
-        timestamps=args.verbose,
-        colored=True,
-    )
-
-    # Obtain certificates
-    if args.insecure:
-        if args.root_certificates is not None:
-            sys.exit(
-                "Conflicting options: The '--insecure' flag disables HTTPS, "
-                "but '--root-certificates' was also specified. Please remove "
-                "the '--root-certificates' option when running in insecure mode, "
-                "or omit '--insecure' to use HTTPS."
-            )
-        log(
-            WARN,
-            "Option `--insecure` was set. "
-            "Starting insecure HTTP client connected to %s.",
-            args.server,
-        )
-        root_certificates = None
-    else:
-        # Load the certificates if provided, or load the system certificates
-        cert_path = args.root_certificates
-        if cert_path is None:
-            root_certificates = None
-        else:
-            root_certificates = Path(cert_path).read_bytes()
-        log(
-            DEBUG,
-            "Starting secure HTTPS client connected to %s "
-            "with the following certificates: %s.",
-            args.server,
-            cert_path,
-        )
-
-    log(
-        DEBUG,
-        "Flower will load ServerApp `%s`",
-        getattr(args, "server-app"),
-    )
-
     log(
-        DEBUG,
-        "root_certificates: `%s`",
-        root_certificates,
+        ERROR,
+        "The command `flower-server-app` has been replaced by `flwr run`.",
     )
-
-    server_app_dir = args.dir
-    server_app_attr = getattr(args, "server-app")
-
-    # Initialize Driver
-    driver = Driver(
-        driver_service_address=args.server,
-        root_certificates=root_certificates,
-    )
-
-    # Run the Server App with the Driver
-    run(driver=driver, server_app_dir=server_app_dir, server_app_attr=server_app_attr)
-
-    # Clean up
-    driver.close()
-
-    event(EventType.RUN_SERVER_APP_LEAVE)
-
-
-def _parse_args_run_server_app() -> argparse.ArgumentParser:
-    """Parse flower-server-app command line arguments."""
-    parser = argparse.ArgumentParser(
-        description="Start a Flower server app",
-    )
-
-    parser.add_argument(
-        "server-app",
-        help="For example: `server:app` or `project.package.module:wrapper.app`",
-    )
-    parser.add_argument(
-        "--insecure",
-        action="store_true",
-        help="Run the server app without HTTPS. By default, the app runs with "
-        "HTTPS enabled. Use this flag only if you understand the risks.",
-    )
-    parser.add_argument(
-        "--verbose",
-        action="store_true",
-        help="Set the logging to `DEBUG`.",
-    )
-    parser.add_argument(
-        "--root-certificates",
-        metavar="ROOT_CERT",
-        type=str,
-        help="Specifies the path to the PEM-encoded root certificate file for "
-        "establishing secure HTTPS connections.",
-    )
-    parser.add_argument(
-        "--server",
-        default="0.0.0.0:9091",
-        help="Server address",
-    )
-    parser.add_argument(
-        "--dir",
-        default="",
-        help="Add specified directory to the PYTHONPATH and load Flower "
-        "app from there."
-        " Default: current working directory.",
-    )
-
-    return parser
+    register_exit_handlers(event_type=EventType.RUN_SERVER_APP_LEAVE)

flwr/server/server.py

@@ -19,7 +19,7 @@ import concurrent.futures
 import io
 import timeit
 from logging import INFO, WARN
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Optional, Union
 
 from flwr.common import (
     Code,
@@ -41,17 +41,17 @@ from flwr.server.strategy import FedAvg, Strategy
 
 from .server_config import ServerConfig
 
-FitResultsAndFailures = Tuple[
-    List[Tuple[ClientProxy, FitRes]],
-    List[Union[Tuple[ClientProxy, FitRes], BaseException]],
+FitResultsAndFailures = tuple[
+    list[tuple[ClientProxy, FitRes]],
+    list[Union[tuple[ClientProxy, FitRes], BaseException]],
 ]
-EvaluateResultsAndFailures = Tuple[
-    List[Tuple[ClientProxy, EvaluateRes]],
-    List[Union[Tuple[ClientProxy, EvaluateRes], BaseException]],
+EvaluateResultsAndFailures = tuple[
+    list[tuple[ClientProxy, EvaluateRes]],
+    list[Union[tuple[ClientProxy, EvaluateRes], BaseException]],
 ]
-ReconnectResultsAndFailures = Tuple[
-    List[Tuple[ClientProxy, DisconnectRes]],
-    List[Union[Tuple[ClientProxy, DisconnectRes], BaseException]],
+ReconnectResultsAndFailures = tuple[
+    list[tuple[ClientProxy, DisconnectRes]],
+    list[Union[tuple[ClientProxy, DisconnectRes], BaseException]],
 ]
 
 
@@ -84,14 +84,14 @@ class Server:
         return self._client_manager
 
     # pylint: disable=too-many-locals
-    def fit(self, num_rounds: int, timeout: Optional[float]) -> Tuple[History, float]:
+    def fit(self, num_rounds: int, timeout: Optional[float]) -> tuple[History, float]:
         """Run federated averaging for a number of rounds."""
         history = History()
 
         # Initialize parameters
         log(INFO, "[INIT]")
         self.parameters = self._get_initial_parameters(server_round=0, timeout=timeout)
-        log(INFO, "Evaluating initial global parameters")
+        log(INFO, "Starting evaluation of initial global parameters")
         res = self.strategy.evaluate(0, parameters=self.parameters)
         if res is not None:
             log(
@@ -102,6 +102,8 @@ class Server:
             )
             history.add_loss_centralized(server_round=0, loss=res[0])
             history.add_metrics_centralized(server_round=0, metrics=res[1])
+        else:
+            log(INFO, "Evaluation returned no results (`None`)")
 
         # Run federated learning for num_rounds
         start_time = timeit.default_timer()
@@ -161,7 +163,7 @@ class Server:
         server_round: int,
         timeout: Optional[float],
     ) -> Optional[
-        Tuple[Optional[float], Dict[str, Scalar], EvaluateResultsAndFailures]
+        tuple[Optional[float], dict[str, Scalar], EvaluateResultsAndFailures]
     ]:
         """Validate current global model on a number of clients."""
         # Get clients and their respective instructions from strategy
@@ -195,9 +197,9 @@ class Server:
         )
 
         # Aggregate the evaluation results
-        aggregated_result: Tuple[
+        aggregated_result: tuple[
             Optional[float],
-            Dict[str, Scalar],
+            dict[str, Scalar],
         ] = self.strategy.aggregate_evaluate(server_round, results, failures)
 
         loss_aggregated, metrics_aggregated = aggregated_result
@@ -208,7 +210,7 @@ class Server:
         server_round: int,
         timeout: Optional[float],
     ) -> Optional[
-        Tuple[Optional[Parameters], Dict[str, Scalar], FitResultsAndFailures]
+        tuple[Optional[Parameters], dict[str, Scalar], FitResultsAndFailures]
     ]:
         """Perform a single round of federated averaging."""
         # Get clients and their respective instructions from strategy
@@ -243,9 +245,9 @@ class Server:
         )
 
         # Aggregate training results
-        aggregated_result: Tuple[
+        aggregated_result: tuple[
             Optional[Parameters],
-            Dict[str, Scalar],
+            dict[str, Scalar],
         ] = self.strategy.aggregate_fit(server_round, results, failures)
 
         parameters_aggregated, metrics_aggregated = aggregated_result
@@ -282,12 +284,19 @@ class Server:
         get_parameters_res = random_client.get_parameters(
             ins=ins, timeout=timeout, group_id=server_round
         )
-        log(INFO, "Received initial parameters from one random client")
+        if get_parameters_res.status.code == Code.OK:
+            log(INFO, "Received initial parameters from one random client")
+        else:
+            log(
+                WARN,
+                "Failed to receive initial parameters from the client."
+                " Empty initial parameters will be used.",
+            )
         return get_parameters_res.parameters
 
 
 def reconnect_clients(
-    client_instructions: List[Tuple[ClientProxy, ReconnectIns]],
+    client_instructions: list[tuple[ClientProxy, ReconnectIns]],
     max_workers: Optional[int],
     timeout: Optional[float],
 ) -> ReconnectResultsAndFailures:
@@ -303,8 +312,8 @@ def reconnect_clients(
         )
 
     # Gather results
-    results: List[Tuple[ClientProxy, DisconnectRes]] = []
-    failures: List[Union[Tuple[ClientProxy, DisconnectRes], BaseException]] = []
+    results: list[tuple[ClientProxy, DisconnectRes]] = []
+    failures: list[Union[tuple[ClientProxy, DisconnectRes], BaseException]] = []
     for future in finished_fs:
         failure = future.exception()
         if failure is not None:
@@ -319,7 +328,7 @@ def reconnect_client(
     client: ClientProxy,
     reconnect: ReconnectIns,
     timeout: Optional[float],
-) -> Tuple[ClientProxy, DisconnectRes]:
+) -> tuple[ClientProxy, DisconnectRes]:
     """Instruct client to disconnect and (optionally) reconnect later."""
     disconnect = client.reconnect(
         reconnect,
@@ -330,7 +339,7 @@ def reconnect_client(
 
 
 def fit_clients(
-    client_instructions: List[Tuple[ClientProxy, FitIns]],
+    client_instructions: list[tuple[ClientProxy, FitIns]],
     max_workers: Optional[int],
     timeout: Optional[float],
     group_id: int,
@@ -347,8 +356,8 @@ def fit_clients(
         )
 
     # Gather results
-    results: List[Tuple[ClientProxy, FitRes]] = []
-    failures: List[Union[Tuple[ClientProxy, FitRes], BaseException]] = []
+    results: list[tuple[ClientProxy, FitRes]] = []
+    failures: list[Union[tuple[ClientProxy, FitRes], BaseException]] = []
     for future in finished_fs:
         _handle_finished_future_after_fit(
             future=future, results=results, failures=failures
@@ -358,7 +367,7 @@ def fit_clients(
 
 def fit_client(
     client: ClientProxy, ins: FitIns, timeout: Optional[float], group_id: int
-) -> Tuple[ClientProxy, FitRes]:
+) -> tuple[ClientProxy, FitRes]:
     """Refine parameters on a single client."""
     fit_res = client.fit(ins, timeout=timeout, group_id=group_id)
     return client, fit_res
@@ -366,8 +375,8 @@ def fit_client(
 
 def _handle_finished_future_after_fit(
     future: concurrent.futures.Future,  # type: ignore
-    results: List[Tuple[ClientProxy, FitRes]],
-    failures: List[Union[Tuple[ClientProxy, FitRes], BaseException]],
+    results: list[tuple[ClientProxy, FitRes]],
+    failures: list[Union[tuple[ClientProxy, FitRes], BaseException]],
 ) -> None:
     """Convert finished future into either a result or a failure."""
     # Check if there was an exception
@@ -377,7 +386,7 @@ def _handle_finished_future_after_fit(
         return
 
     # Successfully received a result from a client
-    result: Tuple[ClientProxy, FitRes] = future.result()
+    result: tuple[ClientProxy, FitRes] = future.result()
     _, res = result
 
     # Check result status code
@@ -390,7 +399,7 @@ def _handle_finished_future_after_fit(
 
 
 def evaluate_clients(
-    client_instructions: List[Tuple[ClientProxy, EvaluateIns]],
+    client_instructions: list[tuple[ClientProxy, EvaluateIns]],
     max_workers: Optional[int],
     timeout: Optional[float],
     group_id: int,
@@ -407,8 +416,8 @@ def evaluate_clients(
         )
 
     # Gather results
-    results: List[Tuple[ClientProxy, EvaluateRes]] = []
-    failures: List[Union[Tuple[ClientProxy, EvaluateRes], BaseException]] = []
+    results: list[tuple[ClientProxy, EvaluateRes]] = []
+    failures: list[Union[tuple[ClientProxy, EvaluateRes], BaseException]] = []
     for future in finished_fs:
         _handle_finished_future_after_evaluate(
             future=future, results=results, failures=failures
@@ -421,7 +430,7 @@ def evaluate_client(
     ins: EvaluateIns,
     timeout: Optional[float],
     group_id: int,
-) -> Tuple[ClientProxy, EvaluateRes]:
+) -> tuple[ClientProxy, EvaluateRes]:
     """Evaluate parameters on a single client."""
     evaluate_res = client.evaluate(ins, timeout=timeout, group_id=group_id)
     return client, evaluate_res
@@ -429,8 +438,8 @@ def evaluate_client(
 
 def _handle_finished_future_after_evaluate(
     future: concurrent.futures.Future,  # type: ignore
-    results: List[Tuple[ClientProxy, EvaluateRes]],
-    failures: List[Union[Tuple[ClientProxy, EvaluateRes], BaseException]],
+    results: list[tuple[ClientProxy, EvaluateRes]],
+    failures: list[Union[tuple[ClientProxy, EvaluateRes], BaseException]],
 ) -> None:
     """Convert finished future into either a result or a failure."""
     # Check if there was an exception
@@ -440,7 +449,7 @@ def _handle_finished_future_after_evaluate(
         return
 
     # Successfully received a result from a client
-    result: Tuple[ClientProxy, EvaluateRes] = future.result()
+    result: tuple[ClientProxy, EvaluateRes] = future.result()
     _, res = result
 
     # Check result status code
@@ -457,7 +466,7 @@ def init_defaults(
     config: Optional[ServerConfig],
     strategy: Optional[Strategy],
     client_manager: Optional[ClientManager],
-) -> Tuple[Server, ServerConfig]:
+) -> tuple[Server, ServerConfig]:
     """Create server instance if none was given."""
     if server is None:
         if client_manager is None:
@@ -486,12 +495,9 @@ def run_fl(
 
     log(INFO, "")
     log(INFO, "[SUMMARY]")
-    log(INFO, "Run finished %s rounds in %.2fs", config.num_rounds, elapsed_time)
-    for idx, line in enumerate(io.StringIO(str(hist))):
-        if idx == 0:
-            log(INFO, "%s", line.strip("\n"))
-        else:
-            log(INFO, "\t%s", line.strip("\n"))
+    log(INFO, "Run finished %s round(s) in %.2fs", config.num_rounds, elapsed_time)
+    for line in io.StringIO(str(hist)):
+        log(INFO, "\t%s", line.strip("\n"))
     log(INFO, "")
 
     # Graceful shutdown

flwr/server/server_app.py

@@ -17,7 +17,11 @@
 
 from typing import Callable, Optional
 
-from flwr.common import Context, RecordSet
+from flwr.common import Context
+from flwr.common.logger import (
+    warn_deprecated_feature_with_example,
+    warn_preview_feature,
+)
 from flwr.server.strategy import Strategy
 
 from .client_manager import ClientManager
@@ -25,7 +29,20 @@ from .compat import start_driver
 from .driver import Driver
 from .server import Server
 from .server_config import ServerConfig
-from .typing import ServerAppCallable
+from .typing import ServerAppCallable, ServerFn
+
+SERVER_FN_USAGE_EXAMPLE = """
+
+        def server_fn(context: Context):
+            server_config = ServerConfig(num_rounds=3)
+            strategy = FedAvg()
+            return ServerAppComponents(
+                strategy=strategy,
+                server_config=server_config,
+        )
+
+        app = ServerApp(server_fn=server_fn)
+"""
 
 
 class ServerApp:
@@ -35,13 +52,15 @@ class ServerApp:
     --------
     Use the `ServerApp` with an existing `Strategy`:
 
-    >>> server_config = ServerConfig(num_rounds=3)
-    >>> strategy = FedAvg()
+    >>> def server_fn(context: Context):
+    >>>     server_config = ServerConfig(num_rounds=3)
+    >>>     strategy = FedAvg()
+    >>>     return ServerAppComponents(
+    >>>         strategy=strategy,
+    >>>         server_config=server_config,
+    >>>     )
     >>>
-    >>> app = ServerApp()
-    >>>     server_config=server_config,
-    >>>     strategy=strategy,
-    >>> )
+    >>> app = ServerApp(server_fn=server_fn)
 
     Use the `ServerApp` with a custom main function:
 
@@ -52,23 +71,52 @@ class ServerApp:
     >>>    print("ServerApp running")
     """
 
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
     def __init__(
         self,
         server: Optional[Server] = None,
         config: Optional[ServerConfig] = None,
         strategy: Optional[Strategy] = None,
         client_manager: Optional[ClientManager] = None,
+        server_fn: Optional[ServerFn] = None,
     ) -> None:
+        if any([server, config, strategy, client_manager]):
+            warn_deprecated_feature_with_example(
+                deprecation_message="Passing either `server`, `config`, `strategy` or "
+                "`client_manager` directly to the ServerApp "
+                "constructor is deprecated.",
+                example_message="Pass `ServerApp` arguments wrapped "
+                "in a `flwr.server.ServerAppComponents` object that gets "
+                "returned by a function passed as the `server_fn` argument "
+                "to the `ServerApp` constructor. For example: ",
+                code_example=SERVER_FN_USAGE_EXAMPLE,
+            )
+
+            if server_fn:
+                raise ValueError(
+                    "Passing `server_fn` is incompatible with passing the "
+                    "other arguments (now deprecated) to ServerApp. "
+                    "Use `server_fn` exclusively."
+                )
+
         self._server = server
         self._config = config
         self._strategy = strategy
         self._client_manager = client_manager
+        self._server_fn = server_fn
         self._main: Optional[ServerAppCallable] = None
 
     def __call__(self, driver: Driver, context: Context) -> None:
         """Execute `ServerApp`."""
         # Compatibility mode
         if not self._main:
+            if self._server_fn:
+                # Execute server_fn()
+                components = self._server_fn(context)
+                self._server = components.server
+                self._config = components.config
+                self._strategy = components.strategy
+                self._client_manager = components.client_manager
             start_driver(
                 server=self._server,
                 config=self._config,
@@ -79,7 +127,6 @@ class ServerApp:
             return
 
         # New execution mode
-        context = Context(state=RecordSet())
         self._main(driver, context)
 
     def main(self) -> Callable[[ServerAppCallable], ServerAppCallable]:
@@ -105,7 +152,7 @@ class ServerApp:
                     >>> server_config = ServerConfig(num_rounds=3)
                     >>> strategy = FedAvg()
                     >>>
-                    >>> app = ServerApp()
+                    >>> app = ServerApp(
                     >>>     server_config=server_config,
                     >>>     strategy=strategy,
                     >>> )
@@ -120,6 +167,8 @@ class ServerApp:
                     """,
                 )
 
+            warn_preview_feature("ServerApp-register-main-function")
+
             # Register provided function with the ServerApp object
             self._main = main_fn
 

flwr/server/serverapp/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2024 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 AppIO service."""
+
+
+from .app import flwr_serverapp as flwr_serverapp
+
+__all__ = [
+    "flwr_serverapp",
+]