flwr 1.13.1__py3-none-any.whl → 1.15.0__py3-none-any.whl

flwr/common/config.py

@@ -14,23 +14,30 @@
 # ==============================================================================
 """Provide functions for managing global Flower config."""
 
+
 import os
 import re
+import zipfile
+from io import BytesIO
 from pathlib import Path
-from typing import Any, Optional, Union, cast, get_args
+from typing import IO, Any, Optional, TypeVar, Union, cast, get_args
 
 import tomli
+import typer
 
-from flwr.cli.config_utils import get_fab_config, validate_fields
-from flwr.common import ConfigsRecord
 from flwr.common.constant import (
     APP_DIR,
     FAB_CONFIG_FILE,
     FAB_HASH_TRUNCATION,
+    FLWR_DIR,
     FLWR_HOME,
 )
 from flwr.common.typing import Run, UserConfig, UserConfigValue
 
+from . import ConfigsRecord, object_ref
+
+T_dict = TypeVar("T_dict", bound=dict[str, Any])  # pylint: disable=invalid-name
+
 
 def get_flwr_dir(provided_path: Optional[str] = None) -> Path:
     """Return the Flower home directory based on env variables."""
@@ -38,7 +45,7 @@ def get_flwr_dir(provided_path: Optional[str] = None) -> Path:
         return Path(
             os.getenv(
                 FLWR_HOME,
-                Path(f"{os.getenv('XDG_DATA_HOME', os.getenv('HOME'))}") / ".flwr",
+                Path(f"{os.getenv('XDG_DATA_HOME', os.getenv('HOME'))}") / FLWR_DIR,
             )
         )
     return Path(provided_path).absolute()
@@ -78,7 +85,7 @@ def get_project_config(project_dir: Union[str, Path]) -> dict[str, Any]:
         config = tomli.loads(toml_file.read())
 
     # Validate pyproject.toml fields
-    is_valid, errors, _ = validate_fields(config)
+    is_valid, errors, _ = validate_fields_in_config(config)
     if not is_valid:
         error_msg = "\n".join([f"  - {error}" for error in errors])
         raise ValueError(
@@ -89,19 +96,28 @@ def get_project_config(project_dir: Union[str, Path]) -> dict[str, Any]:
 
 
 def fuse_dicts(
-    main_dict: UserConfig,
-    override_dict: UserConfig,
-) -> UserConfig:
+    main_dict: T_dict,
+    override_dict: T_dict,
+    check_keys: bool = True,
+) -> T_dict:
     """Merge a config with the overrides.
 
-    Remove the nesting by adding the nested keys as prefixes separated by dots, and fuse
-    it with the override dict.
+    If `check_keys` is set to True, an error will be raised if the override
+    dictionary contains keys that are not present in the main dictionary.
+    Otherwise, only the keys present in the main dictionary will be updated.
     """
-    fused_dict = main_dict.copy()
+    if not isinstance(main_dict, dict) or not isinstance(override_dict, dict):
+        raise ValueError("Both dictionaries must be of type dict")
+
+    fused_dict = cast(T_dict, main_dict.copy())
 
     for key, value in override_dict.items():
         if key in main_dict:
+            if isinstance(value, dict):
+                fused_dict[key] = fuse_dicts(main_dict[key], value)
             fused_dict[key] = value
+        elif check_keys:
+            raise ValueError(f"Key '{key}' is not present in the main dictionary")
 
     return fused_dict
 
@@ -190,8 +206,8 @@ def unflatten_dict(flat_dict: dict[str, Any]) -> dict[str, Any]:
 
 
 def parse_config_args(
-    config: Optional[list[str]],
-) -> UserConfig:
+    config: Optional[list[str]], flatten: bool = True
+) -> dict[str, Any]:
     """Parse separator separated list of key-value pairs separated by '='."""
     overrides: UserConfig = {}
 
@@ -218,17 +234,29 @@ def parse_config_args(
 
             matches = pattern.findall(config_line)
             toml_str = "\n".join(f"{k} = {v}" for k, v in matches)
-            overrides.update(tomli.loads(toml_str))
-            flat_overrides = flatten_dict(overrides)
+            try:
+                overrides.update(tomli.loads(toml_str))
+                flat_overrides = flatten_dict(overrides) if flatten else overrides
+            except tomli.TOMLDecodeError as err:
+                typer.secho(
+                    "❌ The provided configuration string is in an invalid format. "
+                    "The correct format should be, e.g., 'key1=123 key2=false "
+                    'key3="string"\', where values must be of type bool, int, '
+                    "string, or float. Ensure proper formatting with "
+                    "space-separated key-value pairs.",
+                    fg=typer.colors.RED,
+                    bold=True,
+                )
+                raise typer.Exit(code=1) from err
 
     return flat_overrides
 
 
 def get_metadata_from_config(config: dict[str, Any]) -> tuple[str, str]:
-    """Extract `fab_version` and `fab_id` from a project config."""
+    """Extract `fab_id` and `fab_version` from a project config."""
     return (
-        config["project"]["version"],
         f"{config['tool']['flwr']['app']['publisher']}/{config['project']['name']}",
+        config["project"]["version"],
     )
 
 
@@ -239,3 +267,127 @@ def user_config_to_configsrecord(config: UserConfig) -> ConfigsRecord:
         c_record[k] = v
 
     return c_record
+
+
+def get_fab_config(fab_file: Union[Path, bytes]) -> dict[str, Any]:
+    """Extract the config from a FAB file or path.
+
+    Parameters
+    ----------
+    fab_file : Union[Path, bytes]
+        The Flower App Bundle file to validate and extract the metadata from.
+        It can either be a path to the file or the file itself as bytes.
+
+    Returns
+    -------
+    Dict[str, Any]
+        The `config` of the given Flower App Bundle.
+    """
+    fab_file_archive: Union[Path, IO[bytes]]
+    if isinstance(fab_file, bytes):
+        fab_file_archive = BytesIO(fab_file)
+    elif isinstance(fab_file, Path):
+        fab_file_archive = fab_file
+    else:
+        raise ValueError("fab_file must be either a Path or bytes")
+
+    with zipfile.ZipFile(fab_file_archive, "r") as zipf:
+        with zipf.open("pyproject.toml") as file:
+            toml_content = file.read().decode("utf-8")
+        try:
+            conf = tomli.loads(toml_content)
+        except tomli.TOMLDecodeError:
+            raise ValueError("Invalid TOML content in pyproject.toml") from None
+
+        is_valid, errors, _ = validate_config(conf, check_module=False)
+        if not is_valid:
+            raise ValueError(errors)
+
+        return conf
+
+
+def _validate_run_config(config_dict: dict[str, Any], errors: list[str]) -> None:
+    for key, value in config_dict.items():
+        if isinstance(value, dict):
+            _validate_run_config(config_dict[key], errors)
+        elif not isinstance(value, get_args(UserConfigValue)):
+            raise ValueError(
+                f"The value for key {key} needs to be of type `int`, `float`, "
+                "`bool, `str`, or  a `dict` of those.",
+            )
+
+
+# pylint: disable=too-many-branches
+def validate_fields_in_config(
+    config: dict[str, Any]
+) -> tuple[bool, list[str], list[str]]:
+    """Validate pyproject.toml fields."""
+    errors = []
+    warnings = []
+
+    if "project" not in config:
+        errors.append("Missing [project] section")
+    else:
+        if "name" not in config["project"]:
+            errors.append('Property "name" missing in [project]')
+        if "version" not in config["project"]:
+            errors.append('Property "version" missing in [project]')
+        if "description" not in config["project"]:
+            warnings.append('Recommended property "description" missing in [project]')
+        if "license" not in config["project"]:
+            warnings.append('Recommended property "license" missing in [project]')
+        if "authors" not in config["project"]:
+            warnings.append('Recommended property "authors" missing in [project]')
+
+    if (
+        "tool" not in config
+        or "flwr" not in config["tool"]
+        or "app" not in config["tool"]["flwr"]
+    ):
+        errors.append("Missing [tool.flwr.app] section")
+    else:
+        if "publisher" not in config["tool"]["flwr"]["app"]:
+            errors.append('Property "publisher" missing in [tool.flwr.app]')
+        if "config" in config["tool"]["flwr"]["app"]:
+            _validate_run_config(config["tool"]["flwr"]["app"]["config"], errors)
+        if "components" not in config["tool"]["flwr"]["app"]:
+            errors.append("Missing [tool.flwr.app.components] section")
+        else:
+            if "serverapp" not in config["tool"]["flwr"]["app"]["components"]:
+                errors.append(
+                    'Property "serverapp" missing in [tool.flwr.app.components]'
+                )
+            if "clientapp" not in config["tool"]["flwr"]["app"]["components"]:
+                errors.append(
+                    'Property "clientapp" missing in [tool.flwr.app.components]'
+                )
+
+    return len(errors) == 0, errors, warnings
+
+
+def validate_config(
+    config: dict[str, Any],
+    check_module: bool = True,
+    project_dir: Optional[Union[str, Path]] = None,
+) -> tuple[bool, list[str], list[str]]:
+    """Validate pyproject.toml."""
+    is_valid, errors, warnings = validate_fields_in_config(config)
+
+    if not is_valid:
+        return False, errors, warnings
+
+    # Validate serverapp
+    serverapp_ref = config["tool"]["flwr"]["app"]["components"]["serverapp"]
+    is_valid, reason = object_ref.validate(serverapp_ref, check_module, project_dir)
+
+    if not is_valid and isinstance(reason, str):
+        return False, [reason], []
+
+    # Validate clientapp
+    clientapp_ref = config["tool"]["flwr"]["app"]["components"]["clientapp"]
+    is_valid, reason = object_ref.validate(clientapp_ref, check_module, project_dir)
+
+    if not is_valid and isinstance(reason, str):
+        return False, [reason], []
+
+    return True, [], []

flwr/common/constant.py

@@ -17,14 +17,6 @@
 
 from __future__ import annotations
 
-MISSING_EXTRA_REST = """
-Extra dependencies required for using the REST-based Fleet API are missing.
-
-To use the REST API, install `flwr` with the `rest` extra:
-
-    `pip install flwr[rest]`.
-"""
-
 TRANSPORT_TYPE_GRPC_BIDI = "grpc-bidi"
 TRANSPORT_TYPE_GRPC_RERE = "grpc-rere"
 TRANSPORT_TYPE_GRPC_ADAPTER = "grpc-adapter"
@@ -80,7 +72,11 @@ FAB_ALLOWED_EXTENSIONS = {".py", ".toml", ".md"}
 FAB_CONFIG_FILE = "pyproject.toml"
 FAB_DATE = (2024, 10, 1, 0, 0, 0)
 FAB_HASH_TRUNCATION = 8
-FLWR_HOME = "FLWR_HOME"
+FLWR_DIR = ".flwr"  # The default Flower directory: ~/.flwr/
+FLWR_HOME = "FLWR_HOME"  # If set, override the default Flower directory
+
+# Constant for SuperLink
+SUPERLINK_NODE_ID = 1
 
 # Constants entries in Node config for Simulation
 PARTITION_ID_KEY = "partition-id"
@@ -110,6 +106,18 @@ LOG_UPLOAD_INTERVAL = 0.2  # Minimum interval between two log uploads
 # Retry configurations
 MAX_RETRY_DELAY = 20  # Maximum delay duration between two consecutive retries.
 
+# Constants for user authentication
+CREDENTIALS_DIR = ".credentials"
+AUTH_TYPE_KEY = "auth_type"
+ACCESS_TOKEN_KEY = "access_token"
+REFRESH_TOKEN_KEY = "refresh_token"
+
+# Constants for node authentication
+PUBLIC_KEY_HEADER = "public-key-bin"  # Must end with "-bin" for binary data
+SIGNATURE_HEADER = "signature-bin"  # Must end with "-bin" for binary data
+TIMESTAMP_HEADER = "timestamp"
+TIMESTAMP_TOLERANCE = 10  # Tolerance for timestamp verification
+
 
 class MessageType:
     """Message type."""
@@ -181,3 +189,24 @@ class SubStatus:
     def __new__(cls) -> SubStatus:
         """Prevent instantiation."""
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class CliOutputFormat:
+    """Define output format for `flwr` CLI commands."""
+
+    DEFAULT = "default"
+    JSON = "json"
+
+    def __new__(cls) -> CliOutputFormat:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class AuthType:
+    """User authentication types."""
+
+    OIDC = "oidc"
+
+    def __new__(cls) -> AuthType:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")

flwr/common/differential_privacy.py

@@ -39,7 +39,8 @@ def get_norm(input_arrays: NDArrays) -> float:
 def add_gaussian_noise_inplace(input_arrays: NDArrays, std_dev: float) -> None:
     """Add Gaussian noise to each element of the input arrays."""
     for array in input_arrays:
-        array += np.random.normal(0, std_dev, array.shape)
+        noise = np.random.normal(0, std_dev, array.shape).astype(array.dtype)
+        array += noise
 
 
 def clip_inputs_inplace(input_arrays: NDArrays, clipping_norm: float) -> None:

flwr/common/exit/__init__.py

@@ -0,0 +1,24 @@
+# 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 exit functionality."""
+
+
+from .exit import flwr_exit
+from .exit_code import ExitCode
+
+__all__ = [
+    "ExitCode",
+    "flwr_exit",
+]

flwr/common/exit/exit.py

@@ -0,0 +1,99 @@
+# 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.
+# ==============================================================================
+"""Unified exit function."""
+
+
+from __future__ import annotations
+
+import sys
+from logging import ERROR, INFO
+from typing import Any, NoReturn
+
+from flwr.common import EventType, event
+
+from ..logger import log
+from .exit_code import EXIT_CODE_HELP
+
+HELP_PAGE_URL = "https://flower.ai/docs/framework/ref-exit-codes/"
+
+
+def flwr_exit(
+    code: int,
+    message: str | None = None,
+    event_type: EventType | None = None,
+    event_details: dict[str, Any] | None = None,
+) -> NoReturn:
+    """Handle application exit with an optional message.
+
+    The exit message logged and displayed will follow this structure:
+
+    >>> Exit Code: <code>
+    >>> <message>
+    >>> <short-help-message>
+    >>>
+    >>> For more information, visit: <help-page-url>
+
+    - `<code>`: The unique exit code representing the termination reason.
+    - `<message>`: Optional context or additional information about the exit.
+    - `<short-help-message>`: A brief explanation for the given exit code.
+    - `<help-page-url>`: A URL providing detailed documentation and resolution steps.
+    """
+    is_error = not 0 <= code < 100  # 0-99 are success exit codes
+
+    # Construct exit message
+    exit_message = f"Exit Code: {code}\n" if is_error else ""
+    exit_message += message or ""
+    if short_help_message := EXIT_CODE_HELP.get(code, ""):
+        exit_message += f"\n{short_help_message}"
+
+    # Set log level and system exit code
+    log_level = ERROR if is_error else INFO
+    sys_exit_code = 1 if is_error else 0
+
+    # Add help URL for non-successful/graceful exits
+    if is_error:
+        help_url = f"{HELP_PAGE_URL}{code}.html"
+        exit_message += f"\n\nFor more information, visit: <{help_url}>"
+
+    # Telemetry event
+    event_type = event_type or _try_obtain_telemetry_event()
+    if event_type:
+        event_details = event_details or {}
+        event_details["exit_code"] = code
+        event(event_type, event_details).result()
+
+    # Log the exit message
+    log(log_level, exit_message)
+
+    # Exit
+    sys.exit(sys_exit_code)
+
+
+# pylint: disable-next=too-many-return-statements
+def _try_obtain_telemetry_event() -> EventType | None:
+    """Try to obtain a telemetry event."""
+    if sys.argv[0].endswith("flower-superlink"):
+        return EventType.RUN_SUPERLINK_LEAVE
+    if sys.argv[0].endswith("flower-supernode"):
+        return EventType.RUN_SUPERNODE_LEAVE
+    if sys.argv[0].endswith("flwr-serverapp"):
+        return EventType.FLWR_SERVERAPP_RUN_LEAVE
+    if sys.argv[0].endswith("flwr-clientapp"):
+        return None  # Not yet implemented
+    if sys.argv[0].endswith("flwr-simulation"):
+        return EventType.FLWR_SIMULATION_RUN_LEAVE
+    if sys.argv[0].endswith("flower-simulation"):
+        return EventType.CLI_FLOWER_SIMULATION_LEAVE
+    return None

flwr/common/exit/exit_code.py

@@ -0,0 +1,93 @@
+# 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.
+# ==============================================================================
+"""Exit codes."""
+
+
+from __future__ import annotations
+
+
+class ExitCode:
+    """Exit codes for Flower components."""
+
+    # Success exit codes (0-99)
+    SUCCESS = 0  # Successful exit without any errors or signals
+    GRACEFUL_EXIT_SIGINT = 1  # Graceful exit triggered by SIGINT
+    GRACEFUL_EXIT_SIGQUIT = 2  # Graceful exit triggered by SIGQUIT
+    GRACEFUL_EXIT_SIGTERM = 3  # Graceful exit triggered by SIGTERM
+
+    # SuperLink-specific exit codes (100-199)
+    SUPERLINK_THREAD_CRASH = 100
+
+    # ServerApp-specific exit codes (200-299)
+
+    # SuperNode-specific exit codes (300-399)
+    SUPERNODE_REST_ADDRESS_INVALID = 300
+    SUPERNODE_NODE_AUTH_KEYS_REQUIRED = 301
+    SUPERNODE_NODE_AUTH_KEYS_INVALID = 302
+
+    # ClientApp-specific exit codes (400-499)
+
+    # Simulation-specific exit codes (500-599)
+
+    # Common exit codes (600-)
+    COMMON_ADDRESS_INVALID = 600
+    COMMON_MISSING_EXTRA_REST = 601
+    COMMON_TLS_NOT_SUPPORTED = 602
+
+    def __new__(cls) -> ExitCode:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+# All short help messages for exit codes
+EXIT_CODE_HELP = {
+    # Success exit codes (0-99)
+    ExitCode.SUCCESS: "",
+    ExitCode.GRACEFUL_EXIT_SIGINT: "",
+    ExitCode.GRACEFUL_EXIT_SIGQUIT: "",
+    ExitCode.GRACEFUL_EXIT_SIGTERM: "",
+    # SuperLink-specific exit codes (100-199)
+    ExitCode.SUPERLINK_THREAD_CRASH: "An important background thread has crashed.",
+    # ServerApp-specific exit codes (200-299)
+    # SuperNode-specific exit codes (300-399)
+    ExitCode.SUPERNODE_REST_ADDRESS_INVALID: (
+        "When using the REST API, please provide `https://` or "
+        "`http://` before the server address (e.g. `http://127.0.0.1:8080`)"
+    ),
+    ExitCode.SUPERNODE_NODE_AUTH_KEYS_REQUIRED: (
+        "Node authentication requires file paths to both "
+        "'--auth-supernode-private-key' and '--auth-supernode-public-key' "
+        "to be provided (providing only one of them is not sufficient)."
+    ),
+    ExitCode.SUPERNODE_NODE_AUTH_KEYS_INVALID: (
+        "Node uthentication requires elliptic curve private and public key pair. "
+        "Please ensure that the file path points to a valid private/public key "
+        "file and try again."
+    ),
+    # ClientApp-specific exit codes (400-499)
+    # Simulation-specific exit codes (500-599)
+    # Common exit codes (600-)
+    ExitCode.COMMON_ADDRESS_INVALID: (
+        "Please provide a valid URL, IPv4 or IPv6 address."
+    ),
+    ExitCode.COMMON_MISSING_EXTRA_REST: """
+Extra dependencies required for using the REST-based Fleet API are missing.
+
+To use the REST API, install `flwr` with the `rest` extra:
+
+    `pip install "flwr[rest]"`.
+""",
+    ExitCode.COMMON_TLS_NOT_SUPPORTED: "Please use the '--insecure' flag.",
+}

flwr/common/exit_handlers.py

@@ -15,28 +15,38 @@
 """Common function to register exit handlers for server and client."""
 
 
-import sys
-from signal import SIGINT, SIGTERM, signal
+from signal import SIGINT, SIGQUIT, SIGTERM, signal
 from threading import Thread
 from types import FrameType
 from typing import Optional
 
 from grpc import Server
 
-from flwr.common.telemetry import EventType, event
+from flwr.common.telemetry import EventType
+
+from .exit import ExitCode, flwr_exit
+
+SIGNAL_TO_EXIT_CODE = {
+    SIGINT: ExitCode.GRACEFUL_EXIT_SIGINT,
+    SIGQUIT: ExitCode.GRACEFUL_EXIT_SIGQUIT,
+    SIGTERM: ExitCode.GRACEFUL_EXIT_SIGTERM,
+}
 
 
 def register_exit_handlers(
     event_type: EventType,
+    exit_message: Optional[str] = None,
     grpc_servers: Optional[list[Server]] = None,
     bckg_threads: Optional[list[Thread]] = None,
 ) -> None:
-    """Register exit handlers for `SIGINT` and `SIGTERM` signals.
+    """Register exit handlers for `SIGINT`, `SIGTERM` and `SIGQUIT` signals.
 
     Parameters
     ----------
     event_type : EventType
         The telemetry event that should be logged before exit.
+    exit_message : Optional[str] (default: None)
+        The message to be logged before exiting.
     grpc_servers: Optional[List[Server]] (default: None)
         An otpional list of gRPC servers that need to be gracefully
         terminated before exiting.
@@ -46,6 +56,7 @@ def register_exit_handlers(
     """
     default_handlers = {
         SIGINT: None,
+        SIGQUIT: None,
         SIGTERM: None,
     }
 
@@ -61,8 +72,6 @@ def register_exit_handlers(
         # Reset to default handler
         signal(signalnum, default_handlers[signalnum])
 
-        event_res = event(event_type=event_type)
-
         if grpc_servers is not None:
             for grpc_server in grpc_servers:
                 grpc_server.stop(grace=1)
@@ -71,16 +80,21 @@ def register_exit_handlers(
             for bckg_thread in bckg_threads:
                 bckg_thread.join()
 
-        # Ensure event has happend
-        event_res.result()
-
         # Setup things for graceful exit
-        sys.exit(0)
+        flwr_exit(
+            code=SIGNAL_TO_EXIT_CODE[signalnum],
+            message=exit_message,
+            event_type=event_type,
+        )
 
     default_handlers[SIGINT] = signal(  # type: ignore
         SIGINT,
         graceful_exit_handler,  # type: ignore
     )
+    default_handlers[SIGQUIT] = signal(  # type: ignore
+        SIGQUIT,
+        graceful_exit_handler,  # type: ignore
+    )
     default_handlers[SIGTERM] = signal(  # type: ignore
         SIGTERM,
         graceful_exit_handler,  # type: ignore