flwr-nightly 1.10.0.dev20240612__py3-none-any.whl → 1.10.0.dev20240614__py3-none-any.whl

flwr/cli/build.py

@@ -33,7 +33,7 @@ def build(
         Optional[Path],
         typer.Option(help="The Flower project directory to bundle into a FAB"),
     ] = None,
-) -> None:
+) -> str:
     """Build a Flower project into a Flower App Bundle (FAB).
 
     You can run `flwr build` without any argument to bundle the current directory:
@@ -125,6 +125,8 @@ def build(
         f"🎊 Successfully built {fab_filename}.", fg=typer.colors.GREEN, bold=True
     )
 
+    return fab_filename
+
 
 def _load_gitignore(directory: Path) -> pathspec.PathSpec:
     """Load and parse .gitignore file, returning a pathspec."""

flwr/cli/config_utils.py

@@ -14,14 +14,56 @@
 # ==============================================================================
 """Utility to validate the `pyproject.toml` file."""
 
+import zipfile
+from io import BytesIO
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import IO, Any, Dict, List, Optional, Tuple, Union
 
 import tomli
 
 from flwr.common import object_ref
 
 
+def get_fab_metadata(fab_file: Union[Path, bytes]) -> Tuple[str, str]:
+    """Extract the fab_id and the fab_version 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
+    -------
+    Tuple[str, str]
+        The `fab_version` and `fab_id` 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")
+
+        conf = load_from_string(toml_content)
+        if conf is None:
+            raise ValueError("Invalid TOML content in pyproject.toml")
+
+        is_valid, errors, _ = validate(conf, check_module=False)
+        if not is_valid:
+            raise ValueError(errors)
+
+        return (
+            conf["project"]["version"],
+            f"{conf['flower']['publisher']}/{conf['project']['name']}",
+        )
+
+
 def load_and_validate(
     path: Optional[Path] = None,
     check_module: bool = True,
@@ -63,8 +105,7 @@ def load(path: Optional[Path] = None) -> Optional[Dict[str, Any]]:
         return None
 
     with toml_path.open(encoding="utf-8") as toml_file:
-        data = tomli.loads(toml_file.read())
-        return data
+        return load_from_string(toml_file.read())
 
 
 # pylint: disable=too-many-branches
@@ -128,3 +169,12 @@ def validate(
         return False, [reason], []
 
     return True, [], []
+
+
+def load_from_string(toml_content: str) -> Optional[Dict[str, Any]]:
+    """Load TOML content from a string and return as dict."""
+    try:
+        data = tomli.loads(toml_content)
+        return data
+    except tomli.TOMLDecodeError:
+        return None

flwr/cli/install.py

@@ -15,16 +15,18 @@
 """Flower command line interface `install` command."""
 
 
-import os
 import shutil
 import tempfile
 import zipfile
+from io import BytesIO
 from pathlib import Path
-from typing import Optional
+from typing import IO, Optional, Union
 
 import typer
 from typing_extensions import Annotated
 
+from flwr.common.config import get_flwr_dir
+
 from .config_utils import load_and_validate
 from .utils import get_sha256_hash
 
@@ -80,11 +82,24 @@ def install(
 
 
 def install_from_fab(
-    fab_file: Path, flwr_dir: Optional[Path], skip_prompt: bool = False
-) -> None:
+    fab_file: Union[Path, bytes],
+    flwr_dir: Optional[Path],
+    skip_prompt: bool = False,
+) -> Path:
     """Install from a FAB file after extracting and validating."""
+    fab_file_archive: Union[Path, IO[bytes]]
+    fab_name: Optional[str]
+    if isinstance(fab_file, bytes):
+        fab_file_archive = BytesIO(fab_file)
+        fab_name = None
+    elif isinstance(fab_file, Path):
+        fab_file_archive = fab_file
+        fab_name = fab_file.stem
+    else:
+        raise ValueError("fab_file must be either a Path or bytes")
+
     with tempfile.TemporaryDirectory() as tmpdir:
-        with zipfile.ZipFile(fab_file, "r") as zipf:
+        with zipfile.ZipFile(fab_file_archive, "r") as zipf:
             zipf.extractall(tmpdir)
             tmpdir_path = Path(tmpdir)
             info_dir = tmpdir_path / ".info"
@@ -110,15 +125,19 @@ def install_from_fab(
 
             shutil.rmtree(info_dir)
 
-            validate_and_install(tmpdir_path, fab_file.stem, flwr_dir, skip_prompt)
+            installed_path = validate_and_install(
+                tmpdir_path, fab_name, flwr_dir, skip_prompt
+            )
+
+    return installed_path
 
 
 def validate_and_install(
     project_dir: Path,
-    fab_name: str,
+    fab_name: Optional[str],
     flwr_dir: Optional[Path],
     skip_prompt: bool = False,
-) -> None:
+) -> Path:
     """Validate TOML files and install the project to the desired directory."""
     config, _, _ = load_and_validate(project_dir / "pyproject.toml", check_module=False)
 
@@ -134,7 +153,10 @@ def validate_and_install(
     project_name = config["project"]["name"]
     version = config["project"]["version"]
 
-    if fab_name != f"{publisher}.{project_name}.{version.replace('.', '-')}":
+    if (
+        fab_name
+        and fab_name != f"{publisher}.{project_name}.{version.replace('.', '-')}"
+    ):
         typer.secho(
             "❌ FAB file has incorrect name. The file name must follow the format "
             "`<publisher>.<project_name>.<version>.fab`.",
@@ -144,16 +166,7 @@ def validate_and_install(
         raise typer.Exit(code=1)
 
     install_dir: Path = (
-        (
-            Path(
-                os.getenv(
-                    "FLWR_HOME",
-                    f"{os.getenv('XDG_DATA_HOME', os.getenv('HOME'))}/.flwr",
-                )
-            )
-            if not flwr_dir
-            else flwr_dir
-        )
+        (get_flwr_dir() if not flwr_dir else flwr_dir)
         / "apps"
         / publisher
         / project_name
@@ -168,7 +181,7 @@ def validate_and_install(
                 bold=True,
             )
         ):
-            return
+            return install_dir
 
     install_dir.mkdir(parents=True, exist_ok=True)
 
@@ -185,6 +198,8 @@ def validate_and_install(
         bold=True,
     )
 
+    return install_dir
+
 
 def _verify_hashes(list_content: str, tmpdir: Path) -> bool:
     """Verify file hashes based on the LIST content."""

flwr/cli/run/run.py

@@ -16,12 +16,18 @@
 
 import sys
 from enum import Enum
+from logging import DEBUG
 from typing import Optional
 
 import typer
 from typing_extensions import Annotated
 
 from flwr.cli import config_utils
+from flwr.common.constant import SUPEREXEC_DEFAULT_ADDRESS
+from flwr.common.grpc import GRPC_MAX_MESSAGE_LENGTH, create_channel
+from flwr.common.logger import log
+from flwr.proto.exec_pb2 import StartRunRequest  # pylint: disable=E0611
+from flwr.proto.exec_pb2_grpc import ExecStub
 from flwr.simulation.run_simulation import _run_simulation
 
 
@@ -31,20 +37,32 @@ class Engine(str, Enum):
     SIMULATION = "simulation"
 
 
+# pylint: disable-next=too-many-locals
 def run(
     engine: Annotated[
         Optional[Engine],
         typer.Option(case_sensitive=False, help="The ML framework to use"),
     ] = None,
+    use_superexec: Annotated[
+        bool,
+        typer.Option(
+            case_sensitive=False, help="Use this flag to use the new SuperExec API"
+        ),
+    ] = False,
 ) -> None:
     """Run Flower project."""
+    if use_superexec:
+        _start_superexec_run()
+        return
+
     typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
 
     config, errors, warnings = config_utils.load_and_validate()
 
     if config is None:
         typer.secho(
-            "Project configuration could not be loaded.\npyproject.toml is invalid:\n"
+            "Project configuration could not be loaded.\n"
+            "pyproject.toml is invalid:\n"
             + "\n".join([f"- {line}" for line in errors]),
             fg=typer.colors.RED,
             bold=True,
@@ -82,3 +100,22 @@ def run(
             fg=typer.colors.RED,
             bold=True,
         )
+
+
+def _start_superexec_run() -> None:
+    def on_channel_state_change(channel_connectivity: str) -> None:
+        """Log channel connectivity."""
+        log(DEBUG, channel_connectivity)
+
+    channel = create_channel(
+        server_address=SUPEREXEC_DEFAULT_ADDRESS,
+        insecure=True,
+        root_certificates=None,
+        max_message_length=GRPC_MAX_MESSAGE_LENGTH,
+        interceptors=None,
+    )
+    channel.subscribe(on_channel_state_change)
+    stub = ExecStub(channel)
+
+    req = StartRunRequest()
+    stub.StartRun(req)

flwr/client/app.py

@@ -19,7 +19,7 @@ import sys
 import time
 from dataclasses import dataclass
 from logging import DEBUG, ERROR, INFO, WARN
-from typing import Callable, ContextManager, Optional, Tuple, Type, Union
+from typing import Callable, ContextManager, Dict, Optional, Tuple, Type, Union
 
 from cryptography.hazmat.primitives.asymmetric import ec
 from grpc import RpcError
@@ -177,7 +177,7 @@ def start_client(
 def _start_client_internal(
     *,
     server_address: str,
-    load_client_app_fn: Optional[Callable[[], ClientApp]] = None,
+    load_client_app_fn: Optional[Callable[[str, str], ClientApp]] = None,
     client_fn: Optional[ClientFn] = None,
     client: Optional[Client] = None,
     grpc_max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,
@@ -252,7 +252,7 @@ def _start_client_internal(
 
             client_fn = single_client_factory
 
-        def _load_client_app() -> ClientApp:
+        def _load_client_app(_1: str, _2: str) -> ClientApp:
             return ClientApp(client_fn=client_fn)
 
         load_client_app_fn = _load_client_app
@@ -308,6 +308,8 @@ def _start_client_internal(
     )
 
     node_state = NodeState()
+    # run_id -> (fab_id, fab_version)
+    run_info: Dict[int, Tuple[str, str]] = {}
 
     while not app_state_tracker.interrupt:
         sleep_duration: int = 0
@@ -319,7 +321,6 @@ def _start_client_internal(
             root_certificates,
             authentication_keys,
         ) as conn:
-            # pylint: disable-next=W0612
             receive, send, create_node, delete_node, get_run = conn
 
             # Register node
@@ -356,13 +357,20 @@ def _start_client_internal(
                         send(out_message)
                         break
 
+                    # Get run info
+                    run_id = message.metadata.run_id
+                    if run_id not in run_info:
+                        if get_run is not None:
+                            run_info[run_id] = get_run(run_id)
+                        # If get_run is None, i.e., in grpc-bidi mode
+                        else:
+                            run_info[run_id] = ("", "")
+
                     # Register context for this run
-                    node_state.register_context(run_id=message.metadata.run_id)
+                    node_state.register_context(run_id=run_id)
 
                     # Retrieve context for this run
-                    context = node_state.retrieve_context(
-                        run_id=message.metadata.run_id
-                    )
+                    context = node_state.retrieve_context(run_id=run_id)
 
                     # Create an error reply message that will never be used to prevent
                     # the used-before-assignment linting error
@@ -373,7 +381,7 @@ def _start_client_internal(
                     # Handle app loading and task message
                     try:
                         # Load ClientApp instance
-                        client_app: ClientApp = load_client_app_fn()
+                        client_app: ClientApp = load_client_app_fn(*run_info[run_id])
 
                         # Execute ClientApp
                         reply_message = client_app(message=message, context=context)
@@ -411,7 +419,7 @@ def _start_client_internal(
                     else:
                         # No exception, update node state
                         node_state.update_context(
-                            run_id=message.metadata.run_id,
+                            run_id=run_id,
                             context=context,
                         )
 

flwr/client/supernode/app.py

@@ -20,6 +20,7 @@ from logging import DEBUG, INFO, WARN
 from pathlib import Path
 from typing import Callable, Optional, Tuple
 
+import tomli
 from cryptography.exceptions import UnsupportedAlgorithm
 from cryptography.hazmat.primitives.asymmetric import ec
 from cryptography.hazmat.primitives.serialization import (
@@ -27,8 +28,10 @@ from cryptography.hazmat.primitives.serialization import (
     load_ssh_public_key,
 )
 
+from flwr.cli.config_utils import validate_fields
 from flwr.client.client_app import ClientApp, LoadClientAppError
 from flwr.common import EventType, event
+from flwr.common.config import get_flwr_dir
 from flwr.common.exit_handlers import register_exit_handlers
 from flwr.common.logger import log, warn_deprecated_feature
 from flwr.common.object_ref import load_app, validate
@@ -44,11 +47,23 @@ def run_supernode() -> None:
 
     event(EventType.RUN_SUPERNODE_ENTER)
 
-    _ = _parse_args_run_supernode().parse_args()
+    args = _parse_args_run_supernode().parse_args()
 
-    log(
-        DEBUG,
-        "Flower SuperNode starting...",
+    _warn_deprecated_server_arg(args)
+
+    root_certificates = _get_certificates(args)
+    load_fn = _get_load_client_app_fn(args, multi_app=True)
+    authentication_keys = _try_setup_client_authentication(args)
+
+    _start_client_internal(
+        server_address=args.server,
+        load_client_app_fn=load_fn,
+        transport="rest" if args.rest else "grpc-rere",
+        root_certificates=root_certificates,
+        insecure=args.insecure,
+        authentication_keys=authentication_keys,
+        max_retries=args.max_retries,
+        max_wait_time=args.max_wait_time,
     )
 
     # Graceful shutdown
@@ -65,6 +80,27 @@ def run_client_app() -> None:
 
     args = _parse_args_run_client_app().parse_args()
 
+    _warn_deprecated_server_arg(args)
+
+    root_certificates = _get_certificates(args)
+    load_fn = _get_load_client_app_fn(args, multi_app=False)
+    authentication_keys = _try_setup_client_authentication(args)
+
+    _start_client_internal(
+        server_address=args.superlink,
+        load_client_app_fn=load_fn,
+        transport="rest" if args.rest else "grpc-rere",
+        root_certificates=root_certificates,
+        insecure=args.insecure,
+        authentication_keys=authentication_keys,
+        max_retries=args.max_retries,
+        max_wait_time=args.max_wait_time,
+    )
+    register_exit_handlers(event_type=EventType.RUN_CLIENT_APP_LEAVE)
+
+
+def _warn_deprecated_server_arg(args: argparse.Namespace) -> None:
+    """Warn about the deprecated argument `--server`."""
     if args.server != ADDRESS_FLEET_API_GRPC_RERE:
         warn = "Passing flag --server is deprecated. Use --superlink instead."
         warn_deprecated_feature(warn)
@@ -82,27 +118,6 @@ def run_client_app() -> None:
         else:
             args.superlink = args.server
 
-    root_certificates = _get_certificates(args)
-    log(
-        DEBUG,
-        "Flower will load ClientApp `%s`",
-        getattr(args, "client-app"),
-    )
-    load_fn = _get_load_client_app_fn(args)
-    authentication_keys = _try_setup_client_authentication(args)
-
-    _start_client_internal(
-        server_address=args.superlink,
-        load_client_app_fn=load_fn,
-        transport="rest" if args.rest else "grpc-rere",
-        root_certificates=root_certificates,
-        insecure=args.insecure,
-        authentication_keys=authentication_keys,
-        max_retries=args.max_retries,
-        max_wait_time=args.max_wait_time,
-    )
-    register_exit_handlers(event_type=EventType.RUN_CLIENT_APP_LEAVE)
-
 
 def _get_certificates(args: argparse.Namespace) -> Optional[bytes]:
     """Load certificates if specified in args."""
@@ -140,24 +155,112 @@ def _get_certificates(args: argparse.Namespace) -> Optional[bytes]:
 
 
 def _get_load_client_app_fn(
-    args: argparse.Namespace,
-) -> Callable[[], ClientApp]:
-    """Get the load_client_app_fn function."""
-    client_app_dir = args.dir
-    if client_app_dir is not None:
-        sys.path.insert(0, client_app_dir)
+    args: argparse.Namespace, multi_app: bool
+) -> Callable[[str, str], ClientApp]:
+    """Get the load_client_app_fn function.
+
+    If `multi_app` is True, this function loads the specified ClientApp
+    based on `fab_id` and `fab_version`. If `fab_id` is empty, a default
+    ClientApp will be loaded.
+
+    If `multi_app` is False, it ignores `fab_id` and `fab_version` and
+    loads a default ClientApp.
+    """
+    # Find the Flower directory containing Flower Apps (only for multi-app)
+    flwr_dir = Path("")
+    if "flwr_dir" in args:
+        if args.flwr_dir is None:
+            flwr_dir = get_flwr_dir()
+        else:
+            flwr_dir = Path(args.flwr_dir)
+
+    sys.path.insert(0, str(flwr_dir))
 
-    app_ref: str = getattr(args, "client-app")
-    valid, error_msg = validate(app_ref)
-    if not valid and error_msg:
-        raise LoadClientAppError(error_msg) from None
+    default_app_ref: str = getattr(args, "client-app")
 
-    def _load() -> ClientApp:
-        client_app = load_app(app_ref, LoadClientAppError)
+    if not multi_app:
+        log(
+            DEBUG,
+            "Flower SuperNode will load and validate ClientApp `%s`",
+            getattr(args, "client-app"),
+        )
+        valid, error_msg = validate(default_app_ref)
+        if not valid and error_msg:
+            raise LoadClientAppError(error_msg) from None
+
+    def _load(fab_id: str, fab_version: str) -> ClientApp:
+        # If multi-app feature is disabled
+        if not multi_app:
+            # Set sys.path
+            sys.path[0] = args.dir
+
+            # Set app reference
+            client_app_ref = default_app_ref
+        # If multi-app feature is enabled but the fab id is not specified
+        elif fab_id == "":
+            if default_app_ref == "":
+                raise LoadClientAppError(
+                    "Invalid FAB ID: The FAB ID is empty.",
+                ) from None
+
+            log(WARN, "FAB ID is not provided; the default ClientApp will be loaded.")
+            # Set sys.path
+            sys.path[0] = args.dir
+
+            # Set app reference
+            client_app_ref = default_app_ref
+        # If multi-app feature is enabled
+        else:
+            # Check the fab_id
+            if fab_id.count("/") != 1:
+                raise LoadClientAppError(
+                    f"Invalid FAB ID: {fab_id}",
+                ) from None
+            username, project_name = fab_id.split("/")
+
+            # Locate the directory
+            project_dir = flwr_dir / "apps" / username / project_name / fab_version
+
+            # Check if the directory exists
+            if not project_dir.exists():
+                raise LoadClientAppError(
+                    f"Invalid Flower App directory: {project_dir}",
+                ) from None
+
+            # Load pyproject.toml file
+            toml_path = project_dir / "pyproject.toml"
+            if not toml_path.is_file():
+                raise LoadClientAppError(
+                    f"Cannot find pyproject.toml in {project_dir}",
+                ) from None
+            with open(toml_path, 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 LoadClientAppError(
+                    f"Invalid pyproject.toml:\n{error_msg}",
+                ) from None
+
+            # Set sys.path
+            sys.path[0] = str(project_dir)
+
+            # Set app reference
+            client_app_ref = config["flower"]["components"]["clientapp"]
+
+        # Load ClientApp
+        log(
+            DEBUG,
+            "Loading ClientApp `%s`",
+            client_app_ref,
+        )
+        client_app = load_app(client_app_ref, LoadClientAppError)
 
         if not isinstance(client_app, ClientApp):
             raise LoadClientAppError(
-                f"Attribute {app_ref} is not of type {ClientApp}",
+                f"Attribute {client_app_ref} is not of type {ClientApp}",
             ) from None
 
         return client_app

flwr/common/config.py

@@ -0,0 +1,28 @@
+# 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
+
+
+def get_flwr_dir() -> Path:
+    """Return the Flower home directory based on env variables."""
+    return Path(
+        os.getenv(
+            "FLWR_HOME",
+            f"{os.getenv('XDG_DATA_HOME', os.getenv('HOME'))}/.flwr",
+        )
+    )

flwr/common/constant.py

@@ -36,6 +36,8 @@ TRANSPORT_TYPES = [
     TRANSPORT_TYPE_VCE,
 ]
 
+SUPEREXEC_DEFAULT_ADDRESS = "0.0.0.0:9093"
+
 # Constants for ping
 PING_DEFAULT_INTERVAL = 30
 PING_CALL_TIMEOUT = 5

flwr/common/telemetry.py

@@ -164,6 +164,10 @@ class EventType(str, Enum):
     RUN_SUPERNODE_ENTER = auto()
     RUN_SUPERNODE_LEAVE = auto()
 
+    # SuperExec
+    RUN_SUPEREXEC_ENTER = auto()
+    RUN_SUPEREXEC_LEAVE = auto()
+
 
 # Use the ThreadPoolExecutor with max_workers=1 to have a queue
 # and also ensure that telemetry calls are not blocking.

flwr/proto/exec_pb2.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: flwr/proto/exec.proto
+# Protobuf Python Version: 4.25.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x15\x66lwr/proto/exec.proto\x12\nflwr.proto\"#\n\x0fStartRunRequest\x12\x10\n\x08\x66\x61\x62_file\x18\x01 \x01(\x0c\"\"\n\x10StartRunResponse\x12\x0e\n\x06run_id\x18\x01 \x01(\x12\x32O\n\x04\x45xec\x12G\n\x08StartRun\x12\x1b.flwr.proto.StartRunRequest\x1a\x1c.flwr.proto.StartRunResponse\"\x00\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'flwr.proto.exec_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_STARTRUNREQUEST']._serialized_start=37
+  _globals['_STARTRUNREQUEST']._serialized_end=72
+  _globals['_STARTRUNRESPONSE']._serialized_start=74
+  _globals['_STARTRUNRESPONSE']._serialized_end=108
+  _globals['_EXEC']._serialized_start=110
+  _globals['_EXEC']._serialized_end=189
+# @@protoc_insertion_point(module_scope)