flwr-nightly 1.8.0.dev20240314__py3-none-any.whl → 1.15.0.dev20250114__py3-none-any.whl

flwr/cli/app.py

@@ -14,11 +14,18 @@
 # ==============================================================================
 """Flower command line interface."""
 
+
 import typer
+from typer.main import get_command
 
-from .example import example
+from .build import build
+from .install import install
+from .log import log
+from .login import login
+from .ls import ls
 from .new import new
 from .run import run
+from .stop import stop
 
 app = typer.Typer(
     help=typer.style(
@@ -30,8 +37,15 @@ app = typer.Typer(
 )
 
 app.command()(new)
-app.command()(example)
 app.command()(run)
+app.command()(build)
+app.command()(install)
+app.command()(log)
+app.command()(ls)
+app.command()(stop)
+app.command()(login)
+
+typer_click_object = get_command(app)
 
 if __name__ == "__main__":
     app()

flwr/cli/build.py

@@ -0,0 +1,181 @@
+# 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 command line interface `build` command."""
+
+
+import hashlib
+import os
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Annotated, Any, Optional, Union
+
+import pathspec
+import tomli_w
+import typer
+
+from flwr.common.constant import FAB_ALLOWED_EXTENSIONS, FAB_DATE, FAB_HASH_TRUNCATION
+
+from .config_utils import load_and_validate
+from .utils import is_valid_project_name
+
+
+def write_to_zip(
+    zipfile_obj: zipfile.ZipFile, filename: str, contents: Union[bytes, str]
+) -> zipfile.ZipFile:
+    """Set a fixed date and write contents to a zip file."""
+    zip_info = zipfile.ZipInfo(filename)
+    zip_info.date_time = FAB_DATE
+    zipfile_obj.writestr(zip_info, contents)
+    return zipfile_obj
+
+
+def get_fab_filename(conf: dict[str, Any], fab_hash: str) -> str:
+    """Get the FAB filename based on the given config and FAB hash."""
+    publisher = conf["tool"]["flwr"]["app"]["publisher"]
+    name = conf["project"]["name"]
+    version = conf["project"]["version"].replace(".", "-")
+    fab_hash_truncated = fab_hash[:FAB_HASH_TRUNCATION]
+    return f"{publisher}.{name}.{version}.{fab_hash_truncated}.fab"
+
+
+# pylint: disable=too-many-locals, too-many-statements
+def build(
+    app: Annotated[
+        Optional[Path],
+        typer.Option(help="Path of the Flower App to bundle into a FAB"),
+    ] = None,
+) -> tuple[str, str]:
+    """Build a Flower App into a Flower App Bundle (FAB).
+
+    You can run ``flwr build`` without any arguments to bundle the app located in the
+    current directory. Alternatively, you can you can specify a path using the ``--app``
+    option to bundle an app located at the provided path. For example:
+
+    ``flwr build --app ./apps/flower-hello-world``.
+    """
+    if app is None:
+        app = Path.cwd()
+
+    app = app.resolve()
+    if not app.is_dir():
+        typer.secho(
+            f"❌ The path {app} is not a valid path to a Flower app.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    if not is_valid_project_name(app.name):
+        typer.secho(
+            f"❌ The project name {app.name} is invalid, "
+            "a valid project name must start with a letter, "
+            "and can only contain letters, digits, and hyphens.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    conf, errors, warnings = load_and_validate(app / "pyproject.toml")
+    if conf is None:
+        typer.secho(
+            "Project configuration could not be loaded.\npyproject.toml is invalid:\n"
+            + "\n".join([f"- {line}" for line in errors]),
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    if warnings:
+        typer.secho(
+            "Project configuration is missing the following "
+            "recommended properties:\n" + "\n".join([f"- {line}" for line in warnings]),
+            fg=typer.colors.RED,
+            bold=True,
+        )
+
+    # Load .gitignore rules if present
+    ignore_spec = _load_gitignore(app)
+
+    list_file_content = ""
+
+    # Remove the 'federations' field from 'tool.flwr' if it exists
+    if (
+        "tool" in conf
+        and "flwr" in conf["tool"]
+        and "federations" in conf["tool"]["flwr"]
+    ):
+        del conf["tool"]["flwr"]["federations"]
+
+    toml_contents = tomli_w.dumps(conf)
+
+    with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as temp_file:
+        temp_filename = temp_file.name
+
+        with zipfile.ZipFile(temp_filename, "w", zipfile.ZIP_DEFLATED) as fab_file:
+            write_to_zip(fab_file, "pyproject.toml", toml_contents)
+
+            # Continue with adding other files
+            all_files = [
+                f
+                for f in app.rglob("*")
+                if not ignore_spec.match_file(f)
+                and f.name != temp_filename
+                and f.suffix in FAB_ALLOWED_EXTENSIONS
+                and f.name != "pyproject.toml"  # Exclude the original pyproject.toml
+            ]
+
+            for file_path in all_files:
+                # Read the file content manually
+                with open(file_path, "rb") as f:
+                    file_contents = f.read()
+
+                archive_path = file_path.relative_to(app)
+                write_to_zip(fab_file, str(archive_path), file_contents)
+
+                # Calculate file info
+                sha256_hash = hashlib.sha256(file_contents).hexdigest()
+                file_size_bits = os.path.getsize(file_path) * 8  # size in bits
+                list_file_content += f"{archive_path},{sha256_hash},{file_size_bits}\n"
+
+            # Add CONTENT and CONTENT.jwt to the zip file
+            write_to_zip(fab_file, ".info/CONTENT", list_file_content)
+
+    # Get hash of FAB file
+    content = Path(temp_filename).read_bytes()
+    fab_hash = hashlib.sha256(content).hexdigest()
+
+    # Set the name of the zip file
+    fab_filename = get_fab_filename(conf, fab_hash)
+
+    # Once the temporary zip file is created, rename it to the final filename
+    shutil.move(temp_filename, fab_filename)
+
+    typer.secho(
+        f"🎊 Successfully built {fab_filename}", fg=typer.colors.GREEN, bold=True
+    )
+
+    return fab_filename, fab_hash
+
+
+def _load_gitignore(app: Path) -> pathspec.PathSpec:
+    """Load and parse .gitignore file, returning a pathspec."""
+    gitignore_path = app / ".gitignore"
+    patterns = ["__pycache__/"]  # Default pattern
+    if gitignore_path.exists():
+        with open(gitignore_path, encoding="UTF-8") as file:
+            patterns.extend(file.readlines())
+    return pathspec.PathSpec.from_lines("gitwildmatch", patterns)

flwr/cli/cli_user_auth_interceptor.py

@@ -0,0 +1,90 @@
+# 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 run interceptor."""
+
+
+from typing import Any, Callable, Union
+
+import grpc
+
+from flwr.common.auth_plugin import CliAuthPlugin
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    StartRunRequest,
+    StreamLogsRequest,
+)
+
+Request = Union[
+    StartRunRequest,
+    StreamLogsRequest,
+]
+
+
+class CliUserAuthInterceptor(
+    grpc.UnaryUnaryClientInterceptor, grpc.UnaryStreamClientInterceptor  # type: ignore
+):
+    """CLI interceptor for user authentication."""
+
+    def __init__(self, auth_plugin: CliAuthPlugin):
+        self.auth_plugin = auth_plugin
+
+    def _authenticated_call(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Send and receive tokens via metadata."""
+        new_metadata = self.auth_plugin.write_tokens_to_metadata(
+            client_call_details.metadata or []
+        )
+
+        details = client_call_details._replace(metadata=new_metadata)
+
+        response = continuation(details, request)
+        if response.initial_metadata():
+            credentials = self.auth_plugin.read_tokens_from_metadata(
+                response.initial_metadata()
+            )
+            # The metadata contains tokens only if they have been refreshed
+            if credentials is not None:
+                self.auth_plugin.store_tokens(credentials)
+
+        return response
+
+    def intercept_unary_unary(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Intercept a unary-unary call for user authentication.
+
+        This method intercepts a unary-unary RPC call initiated from the CLI and adds
+        the required authentication tokens to the RPC metadata.
+        """
+        return self._authenticated_call(continuation, client_call_details, request)
+
+    def intercept_unary_stream(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Intercept a unary-stream call for user authentication.
+
+        This method intercepts a unary-stream RPC call initiated from the CLI and adds
+        the required authentication tokens to the RPC metadata.
+        """
+        return self._authenticated_call(continuation, client_call_details, request)

flwr/cli/config_utils.py

@@ -0,0 +1,343 @@
+# 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.
+# ==============================================================================
+"""Utility to validate the `pyproject.toml` file."""
+
+
+import zipfile
+from io import BytesIO
+from pathlib import Path
+from typing import IO, Any, Optional, Union, get_args
+
+import tomli
+import typer
+
+from flwr.common import object_ref
+from flwr.common.typing import UserConfigValue
+
+
+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")
+
+        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
+
+
+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_id` and `fab_version` of the given Flower App Bundle.
+    """
+    conf = get_fab_config(fab_file)
+
+    return (
+        f"{conf['tool']['flwr']['app']['publisher']}/{conf['project']['name']}",
+        conf["project"]["version"],
+    )
+
+
+def load_and_validate(
+    path: Optional[Path] = None,
+    check_module: bool = True,
+) -> tuple[Optional[dict[str, Any]], list[str], list[str]]:
+    """Load and validate pyproject.toml as dict.
+
+    Parameters
+    ----------
+    path : Optional[Path] (default: None)
+        The path of the Flower App config file to load. By default it
+        will try to use `pyproject.toml` inside the current directory.
+    check_module: bool (default: True)
+        Whether the validity of the Python module should be checked.
+        This requires the project to be installed in the currently
+        running environment. True by default.
+
+    Returns
+    -------
+    Tuple[Optional[config], List[str], List[str]]
+        A tuple with the optional config in case it exists and is valid
+        and associated errors and warnings.
+    """
+    if path is None:
+        path = Path.cwd() / "pyproject.toml"
+
+    config = load(path)
+
+    if config is None:
+        errors = [
+            "Project configuration could not be loaded. "
+            "`pyproject.toml` does not exist."
+        ]
+        return (None, errors, [])
+
+    is_valid, errors, warnings = validate(config, check_module, path.parent)
+
+    if not is_valid:
+        return (None, errors, warnings)
+
+    return (config, errors, warnings)
+
+
+def load(toml_path: Path) -> Optional[dict[str, Any]]:
+    """Load pyproject.toml and return as dict."""
+    if not toml_path.is_file():
+        return None
+
+    with toml_path.open(encoding="utf-8") as toml_file:
+        return load_from_string(toml_file.read())
+
+
+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(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: 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(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, [], []
+
+
+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
+
+
+def process_loaded_project_config(
+    config: Union[dict[str, Any], None], errors: list[str], warnings: list[str]
+) -> dict[str, Any]:
+    """Process and return the loaded project configuration.
+
+    This function handles errors and warnings from the `load_and_validate` function,
+    exits on critical issues, and returns the validated configuration.
+    """
+    if config is None:
+        typer.secho(
+            "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,
+        )
+        raise typer.Exit(code=1)
+
+    if warnings:
+        typer.secho(
+            "Project configuration is missing the following "
+            "recommended properties:\n" + "\n".join([f"- {line}" for line in warnings]),
+            fg=typer.colors.RED,
+            bold=True,
+        )
+
+    typer.secho("Success", fg=typer.colors.GREEN)
+
+    return config
+
+
+def validate_federation_in_project_config(
+    federation: Optional[str], config: dict[str, Any]
+) -> tuple[str, dict[str, Any]]:
+    """Validate the federation name in the Flower project configuration."""
+    federation = federation or config["tool"]["flwr"]["federations"].get("default")
+
+    if federation is None:
+        typer.secho(
+            "❌ No federation name was provided and the project's `pyproject.toml` "
+            "doesn't declare a default federation (with an Exec API address or an "
+            "`options.num-supernodes` value).",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Validate the federation exists in the configuration
+    federation_config = config["tool"]["flwr"]["federations"].get(federation)
+    if federation_config is None:
+        available_feds = {
+            fed for fed in config["tool"]["flwr"]["federations"] if fed != "default"
+        }
+        typer.secho(
+            f"❌ There is no `{federation}` federation declared in the "
+            "`pyproject.toml`.\n The following federations were found:\n\n"
+            + "\n".join(available_feds),
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    return federation, federation_config
+
+
+def validate_certificate_in_federation_config(
+    app: Path, federation_config: dict[str, Any]
+) -> tuple[bool, Optional[bytes]]:
+    """Validate the certificates in the Flower project configuration."""
+    insecure_str = federation_config.get("insecure")
+    if root_certificates := federation_config.get("root-certificates"):
+        root_certificates_bytes = (app / root_certificates).read_bytes()
+        if insecure := bool(insecure_str):
+            typer.secho(
+                "❌ `root_certificates` were provided but the `insecure` parameter "
+                "is set to `True`.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1)
+    else:
+        root_certificates_bytes = None
+        if insecure_str is None:
+            typer.secho(
+                "❌ To disable TLS, set `insecure = true` in `pyproject.toml`.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1)
+        if not (insecure := bool(insecure_str)):
+            typer.secho(
+                "❌ No certificate were given yet `insecure` is set to `False`.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1)
+
+    return insecure, root_certificates_bytes
+
+
+def exit_if_no_address(federation_config: dict[str, Any], cmd: str) -> None:
+    """Exit if the provided federation_config has no "address" key."""
+    if "address" not in federation_config:
+        typer.secho(
+            f"❌ `flwr {cmd}` currently works with a SuperLink. Ensure that the correct"
+            "SuperLink (Exec API) address is provided in `pyproject.toml`.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)

flwr/cli/example.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `example` command."""
 
+
 import json
 import os
 import subprocess
@@ -39,7 +40,9 @@ def example() -> None:
     with urllib.request.urlopen(examples_directory_url) as res:
         data = json.load(res)
         example_names = [
-            item["path"] for item in data["tree"] if item["path"] not in [".gitignore"]
+            item["path"]
+            for item in data["tree"]
+            if item["path"] not in [".gitignore", "doc"]
         ]
 
     example_name = prompt_options(