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

flwr/client/grpc_client/connection.py

@@ -76,7 +76,7 @@ def grpc_connection(  # pylint: disable=R0913,R0915,too-many-positional-argument
         Optional[Callable[[], Optional[int]]],
         Optional[Callable[[], None]],
         Optional[Callable[[int], Run]],
-        Optional[Callable[[str], Fab]],
+        Optional[Callable[[str, int], Fab]],
     ]
 ]:
     """Establish a gRPC connection to a gRPC server.

flwr/client/grpc_rere_client/connection.py

@@ -42,7 +42,7 @@ from flwr.common.logger import log
 from flwr.common.message import Message, Metadata
 from flwr.common.retry_invoker import RetryInvoker
 from flwr.common.serde import message_from_taskins, message_to_taskres, run_from_proto
-from flwr.common.typing import Fab, Run
+from flwr.common.typing import Fab, Run, RunNotRunningException
 from flwr.proto.fab_pb2 import GetFabRequest, GetFabResponse  # pylint: disable=E0611
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
     CreateNodeRequest,
@@ -84,7 +84,7 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         Optional[Callable[[], Optional[int]]],
         Optional[Callable[[], None]],
         Optional[Callable[[int], Run]],
-        Optional[Callable[[str], Fab]],
+        Optional[Callable[[str, int], Fab]],
     ]
 ]:
     """Primitives for request/response-based interaction with a server.
@@ -155,10 +155,16 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     ping_thread: Optional[threading.Thread] = None
     ping_stop_event = threading.Event()
 
+    def _should_giveup_fn(e: Exception) -> bool:
+        if e.code() == grpc.StatusCode.PERMISSION_DENIED:  # type: ignore
+            raise RunNotRunningException
+        if e.code() == grpc.StatusCode.UNAVAILABLE:  # type: ignore
+            return False
+        return True
+
     # Restrict retries to cases where the status code is UNAVAILABLE
-    retry_invoker.should_giveup = (
-        lambda e: e.code() != grpc.StatusCode.UNAVAILABLE  # type: ignore
-    )
+    # If the status code is PERMISSION_DENIED, additionally raise RunNotRunningException
+    retry_invoker.should_giveup = _should_giveup_fn
 
     ###########################################################################
     # ping/create_node/delete_node/receive/send/get_run functions
@@ -290,9 +296,9 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         # Return fab_id and fab_version
         return run_from_proto(get_run_response.run)
 
-    def get_fab(fab_hash: str) -> Fab:
+    def get_fab(fab_hash: str, run_id: int) -> Fab:
         # Call FleetAPI
-        get_fab_request = GetFabRequest(node=node, hash_str=fab_hash)
+        get_fab_request = GetFabRequest(node=node, hash_str=fab_hash, run_id=run_id)
         get_fab_response: GetFabResponse = retry_invoker.invoke(
             stub.GetFab,
             request=get_fab_request,

flwr/client/message_handler/message_handler.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Client-side message handler."""
 
+
 from logging import WARN
 from typing import Optional, cast
 
@@ -104,8 +105,6 @@ def handle_legacy_message_from_msgtype(
             "Please use `NumPyClient.to_client()` method to convert it to `Client`.",
         )
 
-    client.set_context(context)
-
     message_type = message.metadata.message_type
 
     # Handle GetPropertiesIns

flwr/client/mod/comms_mods.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Mods that report statistics about message communication."""
 
+
 from logging import INFO
 
 import numpy as np

flwr/client/mod/localdp_mod.py

@@ -136,7 +136,7 @@ class LocalDpMod:
         fit_res.parameters = ndarrays_to_parameters(client_to_server_params)
 
         # Add noise to model params
-        add_localdp_gaussian_noise_to_params(
+        fit_res.parameters = add_localdp_gaussian_noise_to_params(
             fit_res.parameters, self.sensitivity, self.epsilon, self.delta
         )
 

flwr/client/nodestate/__init__.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower NodeState."""
 
+
 from .in_memory_nodestate import InMemoryNodeState as InMemoryNodeState
 from .nodestate import NodeState as NodeState
 from .nodestate_factory import NodeStateFactory as NodeStateFactory

flwr/client/nodestate/nodestate.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Abstract base class NodeState."""
 
+
 import abc
 from typing import Optional
 

flwr/client/nodestate/nodestate_factory.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Factory class that creates NodeState instances."""
 
+
 import threading
 from typing import Optional
 

flwr/client/numpy_client.py

@@ -21,13 +21,11 @@ from typing import Callable
 from flwr.client.client import Client
 from flwr.common import (
     Config,
-    Context,
     NDArrays,
     Scalar,
     ndarrays_to_parameters,
     parameters_to_ndarrays,
 )
-from flwr.common.logger import warn_deprecated_feature_with_example
 from flwr.common.typing import (
     Code,
     EvaluateIns,
@@ -71,8 +69,6 @@ Example
 class NumPyClient(ABC):
     """Abstract base class for Flower clients using NumPy."""
 
-    _context: Context
-
     def get_properties(self, config: Config) -> dict[str, Scalar]:
         """Return a client's set of properties.
 
@@ -175,34 +171,6 @@ class NumPyClient(ABC):
         _ = (self, parameters, config)
         return 0.0, 0, {}
 
-    @property
-    def context(self) -> Context:
-        """Getter for `Context` client attribute."""
-        warn_deprecated_feature_with_example(
-            "Accessing the context via the client's attribute is deprecated.",
-            example_message="Instead, pass it to the client's "
-            "constructor in your `client_fn()` which already "
-            "receives a context object.",
-            code_example="def client_fn(context: Context) -> Client:\n\n"
-            "\t\t# Your existing client_fn\n\n"
-            "\t\t# Pass `context` to the constructor\n"
-            "\t\treturn FlowerClient(context).to_client()",
-        )
-        return self._context
-
-    @context.setter
-    def context(self, context: Context) -> None:
-        """Setter for `Context` client attribute."""
-        self._context = context
-
-    def get_context(self) -> Context:
-        """Get the run context from this client."""
-        return self.context
-
-    def set_context(self, context: Context) -> None:
-        """Apply a run context to this client."""
-        self.context = context
-
     def to_client(self) -> Client:
         """Convert to object to Client type and return it."""
         return _wrap_numpy_client(client=self)
@@ -299,21 +267,9 @@ def _evaluate(self: Client, ins: EvaluateIns) -> EvaluateRes:
     )
 
 
-def _get_context(self: Client) -> Context:
-    """Return context of underlying NumPyClient."""
-    return self.numpy_client.get_context()  # type: ignore
-
-
-def _set_context(self: Client, context: Context) -> None:
-    """Apply context to underlying NumPyClient."""
-    self.numpy_client.set_context(context)  # type: ignore
-
-
 def _wrap_numpy_client(client: NumPyClient) -> Client:
     member_dict: dict[str, Callable] = {  # type: ignore
         "__init__": _constructor,
-        "get_context": _get_context,
-        "set_context": _set_context,
     }
 
     # Add wrapper type methods (if overridden)

flwr/client/rest_client/connection.py

@@ -96,7 +96,7 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         Optional[Callable[[], Optional[int]]],
         Optional[Callable[[], None]],
         Optional[Callable[[int], Run]],
-        Optional[Callable[[str], Fab]],
+        Optional[Callable[[str, int], Fab]],
     ]
 ]:
     """Primitives for request/response-based interaction with a server.
@@ -361,9 +361,9 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
 
         return run_from_proto(res.run)
 
-    def get_fab(fab_hash: str) -> Fab:
+    def get_fab(fab_hash: str, run_id: int) -> Fab:
         # Construct the request
-        req = GetFabRequest(node=node, hash_str=fab_hash)
+        req = GetFabRequest(node=node, hash_str=fab_hash, run_id=run_id)
 
         # Send the request
         res = _request(req, GetFabResponse, PATH_GET_FAB)

flwr/client/supernode/app.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower SuperNode."""
 
+
 import argparse
 import sys
 from logging import DEBUG, ERROR, INFO, WARN
@@ -113,9 +114,8 @@ def run_client_app() -> None:
     event(EventType.RUN_CLIENT_APP_ENTER)
     log(
         ERROR,
-        "The command `flower-client-app` has been replaced by `flower-supernode`.",
+        "The command `flower-client-app` has been replaced by `flwr run`.",
     )
-    log(INFO, "Execute `flower-supernode --help` to learn how to use it.")
     register_exit_handlers(event_type=EventType.RUN_CLIENT_APP_LEAVE)
 
 

flwr/common/address.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower IP address utils."""
 
+
 import socket
 from ipaddress import ip_address
 from typing import Optional

flwr/common/args.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Common Flower arguments."""
 
+
 import argparse
 import sys
 from logging import DEBUG, ERROR, WARN

flwr/common/auth_plugin/__init__.py

@@ -0,0 +1,24 @@
+# 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.
+# ==============================================================================
+"""Auth plugin components."""
+
+
+from .auth_plugin import CliAuthPlugin as CliAuthPlugin
+from .auth_plugin import ExecAuthPlugin as ExecAuthPlugin
+
+__all__ = [
+    "CliAuthPlugin",
+    "ExecAuthPlugin",
+]

flwr/common/auth_plugin/auth_plugin.py

@@ -0,0 +1,111 @@
+# 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.
+# ==============================================================================
+"""Abstract classes for Flower User Auth Plugin."""
+
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Optional, Union
+
+from flwr.proto.exec_pb2_grpc import ExecStub
+
+
+class ExecAuthPlugin(ABC):
+    """Abstract Flower Auth Plugin class for ExecServicer.
+
+    Parameters
+    ----------
+    config : dict[str, Any]
+        The authentication configuration loaded from a YAML file.
+    """
+
+    @abstractmethod
+    def __init__(self, config: dict[str, Any]):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def get_login_details(self) -> dict[str, str]:
+        """Get the login details."""
+
+    @abstractmethod
+    def validate_tokens_in_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> bool:
+        """Validate authentication tokens in the provided metadata."""
+
+    @abstractmethod
+    def get_auth_tokens(self, auth_details: dict[str, str]) -> dict[str, str]:
+        """Get authentication tokens."""
+
+    @abstractmethod
+    def refresh_tokens(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Optional[Sequence[tuple[str, Union[str, bytes]]]]:
+        """Refresh authentication tokens in the provided metadata."""
+
+
+class CliAuthPlugin(ABC):
+    """Abstract Flower Auth Plugin class for CLI.
+
+    Parameters
+    ----------
+    user_auth_config_path : Path
+        The path to the user's authentication configuration file.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def login(
+        login_details: dict[str, str],
+        exec_stub: ExecStub,
+    ) -> dict[str, Any]:
+        """Authenticate the user with the SuperLink.
+
+        Parameters
+        ----------
+        login_details : dict[str, str]
+            A dictionary containing the user's login details.
+        exec_stub : ExecStub
+            An instance of `ExecStub` used for communication with the SuperLink.
+
+        Returns
+        -------
+        user_auth_config : dict[str, Any]
+            A dictionary containing the user's authentication configuration
+            in JSON format.
+        """
+
+    @abstractmethod
+    def __init__(self, user_auth_config_path: Path):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def store_tokens(self, user_auth_config: dict[str, Any]) -> None:
+        """Store authentication tokens from the provided user_auth_config.
+
+        The configuration, including tokens, will be saved as a JSON file
+        at `user_auth_config_path`.
+        """
+
+    @abstractmethod
+    def load_tokens(self) -> None:
+        """Load authentication tokens from the user_auth_config_path."""
+
+    @abstractmethod
+    def write_tokens_to_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Sequence[tuple[str, Union[str, bytes]]]:
+        """Write authentication tokens to the provided metadata."""

flwr/common/config.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Provide functions for managing global Flower config."""
 
+
 import os
 import re
 from pathlib import Path
@@ -27,6 +28,7 @@ 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
@@ -38,7 +40,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()

flwr/common/constant.py

@@ -80,7 +80,8 @@ 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
 
 # Constants entries in Node config for Simulation
 PARTITION_ID_KEY = "partition-id"
@@ -110,6 +111,10 @@ 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 = "auth_type"
+
 
 class MessageType:
     """Message type."""
@@ -181,3 +186,14 @@ 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.")

flwr/common/logger.py

@@ -15,16 +15,21 @@
 """Flower Logger."""
 
 
+import json as _json
 import logging
+import re
 import sys
 import threading
 import time
+from io import StringIO
 from logging import WARN, LogRecord
 from logging.handlers import HTTPHandler
 from queue import Empty, Queue
 from typing import TYPE_CHECKING, Any, Optional, TextIO, Union
 
 import grpc
+import typer
+from rich.console import Console
 
 from flwr.proto.log_pb2 import PushLogsRequest  # pylint: disable=E0611
 from flwr.proto.node_pb2 import Node  # pylint: disable=E0611
@@ -303,6 +308,13 @@ def restore_output() -> None:
     console_handler.stream = sys.stdout
 
 
+def redirect_output(output_buffer: StringIO) -> None:
+    """Redirect stdout and stderr to text I/O buffer."""
+    sys.stdout = output_buffer
+    sys.stderr = output_buffer
+    console_handler.stream = sys.stdout
+
+
 def _log_uploader(
     log_queue: Queue[Optional[str]], node_id: int, run_id: int, stub: ServerAppIoStub
 ) -> None:
@@ -366,3 +378,31 @@ def stop_log_uploader(
     """Stop the log uploader thread."""
     log_queue.put(None)
     log_uploader.join()
+
+
+def _remove_emojis(text: str) -> str:
+    """Remove emojis from the provided text."""
+    emoji_pattern = re.compile(
+        "["
+        "\U0001F600-\U0001F64F"  # Emoticons
+        "\U0001F300-\U0001F5FF"  # Symbols & Pictographs
+        "\U0001F680-\U0001F6FF"  # Transport & Map Symbols
+        "\U0001F1E0-\U0001F1FF"  # Flags
+        "\U00002702-\U000027B0"  # Dingbats
+        "\U000024C2-\U0001F251"
+        "]+",
+        flags=re.UNICODE,
+    )
+    return emoji_pattern.sub(r"", text)
+
+
+def print_json_error(msg: str, e: Union[typer.Exit, Exception]) -> None:
+    """Print error message as JSON."""
+    Console().print_json(
+        _json.dumps(
+            {
+                "success": False,
+                "error-message": _remove_emojis(str(msg) + "\n" + str(e)),
+            }
+        )
+    )

flwr/common/message.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Message."""
 
+
 from __future__ import annotations
 
 import time

flwr/common/object_ref.py

@@ -21,6 +21,7 @@ import sys
 from importlib.util import find_spec
 from logging import WARN
 from pathlib import Path
+from threading import Lock
 from typing import Any, Optional, Union
 
 from .logger import log
@@ -34,6 +35,7 @@ attribute.
 
 
 _current_sys_path: Optional[str] = None
+_import_lock = Lock()
 
 
 def validate(
@@ -146,60 +148,61 @@ def load_app(  # pylint: disable= too-many-branches
     - This function will modify `sys.path` by inserting the provided `project_dir`
       and removing the previously inserted `project_dir`.
     """
-    valid, error_msg = validate(module_attribute_str, check_module=False)
-    if not valid and error_msg:
-        raise error_type(error_msg) from None
-
-    module_str, _, attributes_str = module_attribute_str.partition(":")
-
-    try:
-        # Initialize project path
-        if project_dir is None:
-            project_dir = Path.cwd()
-        project_dir = Path(project_dir).absolute()
-
-        # Unload modules if the project directory has changed
-        if _current_sys_path and _current_sys_path != str(project_dir):
-            _unload_modules(Path(_current_sys_path))
-
-        # Set the system path
-        _set_sys_path(project_dir)
-
-        # Import the module
-        if module_str not in sys.modules:
-            module = importlib.import_module(module_str)
-        # Hack: `tabnet` does not work with `importlib.reload`
-        elif "tabnet" in sys.modules:
-            log(
-                WARN,
-                "Cannot reload module `%s` from disk due to compatibility issues "
-                "with the `tabnet` library. The module will be loaded from the "
-                "cache instead. If you experience issues, consider restarting "
-                "the application.",
-                module_str,
-            )
-            module = sys.modules[module_str]
-        else:
-            module = sys.modules[module_str]
-            _reload_modules(project_dir)
-
-    except ModuleNotFoundError as err:
-        raise error_type(
-            f"Unable to load module {module_str}{OBJECT_REF_HELP_STR}",
-        ) from err
-
-    # Recursively load attribute
-    attribute = module
-    try:
-        for attribute_str in attributes_str.split("."):
-            attribute = getattr(attribute, attribute_str)
-    except AttributeError as err:
-        raise error_type(
-            f"Unable to load attribute {attributes_str} from module {module_str}"
-            f"{OBJECT_REF_HELP_STR}",
-        ) from err
-
-    return attribute
+    with _import_lock:
+        valid, error_msg = validate(module_attribute_str, check_module=False)
+        if not valid and error_msg:
+            raise error_type(error_msg) from None
+
+        module_str, _, attributes_str = module_attribute_str.partition(":")
+
+        try:
+            # Initialize project path
+            if project_dir is None:
+                project_dir = Path.cwd()
+            project_dir = Path(project_dir).absolute()
+
+            # Unload modules if the project directory has changed
+            if _current_sys_path and _current_sys_path != str(project_dir):
+                _unload_modules(Path(_current_sys_path))
+
+            # Set the system path
+            _set_sys_path(project_dir)
+
+            # Import the module
+            if module_str not in sys.modules:
+                module = importlib.import_module(module_str)
+            # Hack: `tabnet` does not work with `importlib.reload`
+            elif "tabnet" in sys.modules:
+                log(
+                    WARN,
+                    "Cannot reload module `%s` from disk due to compatibility issues "
+                    "with the `tabnet` library. The module will be loaded from the "
+                    "cache instead. If you experience issues, consider restarting "
+                    "the application.",
+                    module_str,
+                )
+                module = sys.modules[module_str]
+            else:
+                module = sys.modules[module_str]
+                _reload_modules(project_dir)
+
+        except ModuleNotFoundError as err:
+            raise error_type(
+                f"Unable to load module {module_str}{OBJECT_REF_HELP_STR}",
+            ) from err
+
+        # Recursively load attribute
+        attribute = module
+        try:
+            for attribute_str in attributes_str.split("."):
+                attribute = getattr(attribute, attribute_str)
+        except AttributeError as err:
+            raise error_type(
+                f"Unable to load attribute {attributes_str} from module {module_str}"
+                f"{OBJECT_REF_HELP_STR}",
+            ) from err
+
+        return attribute
 
 
 def _unload_modules(project_dir: Path) -> None: