flwr-nightly 1.8.0.dev20240314__py3-none-any.whl → 1.11.0.dev20240813__py3-none-any.whl

flwr/common/config.py

@@ -0,0 +1,193 @@
+# 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.
+# ==============================================================================
+"""Provide functions for managing global Flower config."""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union, cast, get_args
+
+import tomli
+
+from flwr.cli.config_utils import validate_fields
+from flwr.common.constant import APP_DIR, FAB_CONFIG_FILE, FLWR_HOME
+from flwr.common.typing import Run, UserConfig, UserConfigValue
+
+
+def get_flwr_dir(provided_path: Optional[str] = None) -> Path:
+    """Return the Flower home directory based on env variables."""
+    if provided_path is None or not Path(provided_path).is_dir():
+        return Path(
+            os.getenv(
+                FLWR_HOME,
+                Path(f"{os.getenv('XDG_DATA_HOME', os.getenv('HOME'))}") / ".flwr",
+            )
+        )
+    return Path(provided_path).absolute()
+
+
+def get_project_dir(
+    fab_id: str, fab_version: str, flwr_dir: Optional[Union[str, Path]] = None
+) -> Path:
+    """Return the project directory based on the given fab_id and fab_version."""
+    # Check the fab_id
+    if fab_id.count("/") != 1:
+        raise ValueError(
+            f"Invalid FAB ID: {fab_id}",
+        )
+    publisher, project_name = fab_id.split("/")
+    if flwr_dir is None:
+        flwr_dir = get_flwr_dir()
+    return Path(flwr_dir) / APP_DIR / publisher / project_name / fab_version
+
+
+def get_project_config(project_dir: Union[str, Path]) -> Dict[str, Any]:
+    """Return pyproject.toml in the given project directory."""
+    # Load pyproject.toml file
+    toml_path = Path(project_dir) / FAB_CONFIG_FILE
+    if not toml_path.is_file():
+        raise FileNotFoundError(
+            f"Cannot find {FAB_CONFIG_FILE} in {project_dir}",
+        )
+    with toml_path.open(encoding="utf-8") as toml_file:
+        config = tomli.loads(toml_file.read())
+
+    # Validate pyproject.toml fields
+    is_valid, errors, _ = validate_fields(config)
+    if not is_valid:
+        error_msg = "\n".join([f"  - {error}" for error in errors])
+        raise ValueError(
+            f"Invalid {FAB_CONFIG_FILE}:\n{error_msg}",
+        )
+
+    return config
+
+
+def _fuse_dicts(
+    main_dict: UserConfig,
+    override_dict: UserConfig,
+) -> UserConfig:
+    fused_dict = main_dict.copy()
+
+    for key, value in override_dict.items():
+        if key in main_dict:
+            fused_dict[key] = value
+
+    return fused_dict
+
+
+def get_fused_config_from_dir(
+    project_dir: Path, override_config: UserConfig
+) -> UserConfig:
+    """Merge the overrides from a given dict with the config from a Flower App."""
+    default_config = get_project_config(project_dir)["tool"]["flwr"]["app"].get(
+        "config", {}
+    )
+    flat_default_config = flatten_dict(default_config)
+
+    return _fuse_dicts(flat_default_config, override_config)
+
+
+def get_fused_config(run: Run, flwr_dir: Optional[Path]) -> UserConfig:
+    """Merge the overrides from a `Run` with the config from a FAB.
+
+    Get the config using the fab_id and the fab_version, remove the nesting by adding
+    the nested keys as prefixes separated by dots, and fuse it with the override dict.
+    """
+    # Return empty dict if fab_id or fab_version is empty
+    if not run.fab_id or not run.fab_version:
+        return {}
+
+    project_dir = get_project_dir(run.fab_id, run.fab_version, flwr_dir)
+
+    # Return empty dict if project directory does not exist
+    if not project_dir.is_dir():
+        return {}
+
+    return get_fused_config_from_dir(project_dir, run.override_config)
+
+
+def flatten_dict(
+    raw_dict: Optional[Dict[str, Any]], parent_key: str = ""
+) -> UserConfig:
+    """Flatten dict by joining nested keys with a given separator."""
+    if raw_dict is None:
+        return {}
+
+    items: List[Tuple[str, UserConfigValue]] = []
+    separator: str = "."
+    for k, v in raw_dict.items():
+        new_key = f"{parent_key}{separator}{k}" if parent_key else k
+        if isinstance(v, dict):
+            items.extend(flatten_dict(v, parent_key=new_key).items())
+        elif isinstance(v, get_args(UserConfigValue)):
+            items.append((new_key, cast(UserConfigValue, v)))
+        else:
+            raise ValueError(
+                f"The value for key {k} needs to be of type `int`, `float`, "
+                "`bool, `str`, or  a `dict` of those.",
+            )
+    return dict(items)
+
+
+def unflatten_dict(flat_dict: Dict[str, Any]) -> Dict[str, Any]:
+    """Unflatten a dict with keys containing separators into a nested dict."""
+    unflattened_dict: Dict[str, Any] = {}
+    separator: str = "."
+
+    for key, value in flat_dict.items():
+        parts = key.split(separator)
+        d = unflattened_dict
+        for part in parts[:-1]:
+            if part not in d:
+                d[part] = {}
+            d = d[part]
+        d[parts[-1]] = value
+
+    return unflattened_dict
+
+
+def parse_config_args(
+    config: Optional[List[str]],
+    separator: str = ",",
+) -> UserConfig:
+    """Parse separator separated list of key-value pairs separated by '='."""
+    overrides: UserConfig = {}
+
+    if config is None:
+        return overrides
+
+    for config_line in config:
+        if config_line:
+            overrides_list = config_line.split(separator)
+            if (
+                len(overrides_list) == 1
+                and "=" not in overrides_list
+                and overrides_list[0].endswith(".toml")
+            ):
+                with Path(overrides_list[0]).open("rb") as config_file:
+                    overrides = flatten_dict(tomli.load(config_file))
+            else:
+                toml_str = "\n".join(overrides_list)
+                overrides.update(tomli.loads(toml_str))
+
+    return overrides
+
+
+def get_metadata_from_config(config: Dict[str, Any]) -> Tuple[str, str]:
+    """Extract `fab_version` and `fab_id` from a project config."""
+    return (
+        config["project"]["version"],
+        f"{config['tool']['flwr']['app']['publisher']}/{config['project']['name']}",
+    )

flwr/common/constant.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2023 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.
@@ -27,6 +27,7 @@ To use the REST API, install `flwr` with the `rest` extra:
 
 TRANSPORT_TYPE_GRPC_BIDI = "grpc-bidi"
 TRANSPORT_TYPE_GRPC_RERE = "grpc-rere"
+TRANSPORT_TYPE_GRPC_ADAPTER = "grpc-adapter"
 TRANSPORT_TYPE_REST = "rest"
 TRANSPORT_TYPE_VCE = "vce"
 TRANSPORT_TYPES = [
@@ -36,6 +37,33 @@ TRANSPORT_TYPES = [
     TRANSPORT_TYPE_VCE,
 ]
 
+SUPEREXEC_DEFAULT_ADDRESS = "0.0.0.0:9093"
+
+# Constants for ping
+PING_DEFAULT_INTERVAL = 30
+PING_CALL_TIMEOUT = 5
+PING_BASE_MULTIPLIER = 0.8
+PING_RANDOM_RANGE = (-0.1, 0.1)
+PING_MAX_INTERVAL = 1e300
+
+# IDs
+RUN_ID_NUM_BYTES = 8
+NODE_ID_NUM_BYTES = 8
+GRPC_ADAPTER_METADATA_FLOWER_VERSION_KEY = "flower-version"
+GRPC_ADAPTER_METADATA_SHOULD_EXIT_KEY = "should-exit"
+
+# Constants for FAB
+APP_DIR = "apps"
+FAB_CONFIG_FILE = "pyproject.toml"
+FLWR_HOME = "FLWR_HOME"
+
+# Constants entries in Node config for Simulation
+PARTITION_ID_KEY = "partition-id"
+NUM_PARTITIONS_KEY = "num-partitions"
+
+GRPC_ADAPTER_METADATA_FLOWER_VERSION_KEY = "flower-version"
+GRPC_ADAPTER_METADATA_SHOULD_EXIT_KEY = "should-exit"
+
 
 class MessageType:
     """Message type."""
@@ -68,3 +96,16 @@ class SType:
     def __new__(cls) -> SType:
         """Prevent instantiation."""
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class ErrorCode:
+    """Error codes for Message's Error."""
+
+    UNKNOWN = 0
+    LOAD_CLIENT_APP_EXCEPTION = 1
+    CLIENT_APP_RAISED_EXCEPTION = 2
+    NODE_UNAVAILABLE = 3
+
+    def __new__(cls) -> ErrorCode:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")

flwr/common/context.py

@@ -18,14 +18,20 @@
 from dataclasses import dataclass
 
 from .record import RecordSet
+from .typing import UserConfig
 
 
 @dataclass
 class Context:
-    """State of your run.
+    """Context of your run.
 
     Parameters
     ----------
+    node_id : int
+        The ID that identifies the node.
+    node_config : UserConfig
+        A config (key/value mapping) unique to the node and independent of the
+        `run_config`. This config persists across all runs this node participates in.
     state : RecordSet
         Holds records added by the entity in a given run and that will stay local.
         This means that the data it holds will never leave the system it's running from.
@@ -33,6 +39,25 @@ class Context:
         executing mods. It can also be used as a memory to access
         at different points during the lifecycle of this entity (e.g. across
         multiple rounds)
+    run_config : UserConfig
+        A config (key/value mapping) held by the entity in a given run and that will
+        stay local. It can be used at any point during the lifecycle of this entity
+        (e.g. across multiple rounds)
     """
 
+    node_id: int
+    node_config: UserConfig
     state: RecordSet
+    run_config: UserConfig
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        node_id: int,
+        node_config: UserConfig,
+        state: RecordSet,
+        run_config: UserConfig,
+    ) -> None:
+        self.node_id = node_id
+        self.node_config = node_config
+        self.state = state
+        self.run_config = run_config

flwr/common/date.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2023 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.

flwr/common/dp.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2022 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.

flwr/common/grpc.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2022 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.
@@ -16,7 +16,7 @@
 
 
 from logging import DEBUG
-from typing import Optional
+from typing import Optional, Sequence
 
 import grpc
 
@@ -30,6 +30,7 @@ def create_channel(
     insecure: bool,
     root_certificates: Optional[bytes] = None,
     max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,
+    interceptors: Optional[Sequence[grpc.UnaryUnaryClientInterceptor]] = None,
 ) -> grpc.Channel:
     """Create a gRPC channel, either secure or insecure."""
     # Check for conflicting parameters
@@ -57,4 +58,7 @@ def create_channel(
         )
         log(DEBUG, "Opened secure gRPC connection using certificates")
 
+    if interceptors is not None:
+        channel = grpc.intercept_channel(channel, interceptors)
+
     return channel

flwr/common/logger.py

@@ -82,13 +82,20 @@ class ConsoleHandler(StreamHandler):
         return formatter.format(record)
 
 
-def update_console_handler(level: int, timestamps: bool, colored: bool) -> None:
+def update_console_handler(
+    level: Optional[int] = None,
+    timestamps: Optional[bool] = None,
+    colored: Optional[bool] = None,
+) -> None:
     """Update the logging handler."""
     for handler in logging.getLogger(LOGGER_NAME).handlers:
         if isinstance(handler, ConsoleHandler):
-            handler.setLevel(level)
-            handler.timestamps = timestamps
-            handler.colored = colored
+            if level is not None:
+                handler.setLevel(level)
+            if timestamps is not None:
+                handler.timestamps = timestamps
+            if colored is not None:
+                handler.colored = colored
 
 
 # Configure console logger
@@ -164,13 +171,13 @@ logger = logging.getLogger(LOGGER_NAME)  # pylint: disable=invalid-name
 log = logger.log  # pylint: disable=invalid-name
 
 
-def warn_experimental_feature(name: str) -> None:
-    """Warn the user when they use an experimental feature."""
+def warn_preview_feature(name: str) -> None:
+    """Warn the user when they use a preview feature."""
     log(
         WARN,
-        """EXPERIMENTAL FEATURE: %s
+        """PREVIEW FEATURE: %s
 
-            This is an experimental feature. It could change significantly or be removed
+            This is a preview feature. It could change significantly or be removed
             entirely in future versions of Flower.
         """,
         name,
@@ -188,3 +195,67 @@ def warn_deprecated_feature(name: str) -> None:
         """,
         name,
     )
+
+
+def warn_deprecated_feature_with_example(
+    deprecation_message: str, example_message: str, code_example: str
+) -> None:
+    """Warn if a feature is deprecated and show code example."""
+    log(
+        WARN,
+        """DEPRECATED FEATURE: %s
+
+            Check the following `FEATURE UPDATE` warning message for the preferred
+            new mechanism to use this feature in Flower.
+        """,
+        deprecation_message,
+    )
+    log(
+        WARN,
+        """FEATURE UPDATE: %s
+        ------------------------------------------------------------
+        %s
+        ------------------------------------------------------------
+        """,
+        example_message,
+        code_example,
+    )
+
+
+def warn_unsupported_feature(name: str) -> None:
+    """Warn the user when they use an unsupported feature."""
+    log(
+        WARN,
+        """UNSUPPORTED FEATURE: %s
+
+            This is an unsupported feature. It will be removed
+            entirely in future versions of Flower.
+        """,
+        name,
+    )
+
+
+def set_logger_propagation(
+    child_logger: logging.Logger, value: bool = True
+) -> logging.Logger:
+    """Set the logger propagation attribute.
+
+    Parameters
+    ----------
+    child_logger : logging.Logger
+        Child logger object
+    value : bool
+        Boolean setting for propagation. If True, both parent and child logger
+        display messages. Otherwise, only the child logger displays a message.
+        This False setting prevents duplicate logs in Colab notebooks.
+        Reference: https://stackoverflow.com/a/19561320
+
+    Returns
+    -------
+    logging.Logger
+        Child logger object with updated propagation setting
+    """
+    child_logger.propagate = value
+    if not child_logger.propagate:
+        child_logger.log(logging.DEBUG, "Logger propagate set to False")
+    return child_logger