flwr 1.22.0__py3-none-any.whl → 1.24.0__py3-none-any.whl

flwr/cli/build.py

@@ -19,28 +19,45 @@ import hashlib
 import zipfile
 from io import BytesIO
 from pathlib import Path
-from typing import Annotated, Any, Optional, Union
+from typing import Annotated, Any
 
 import pathspec
+import tomli
 import tomli_w
 import typer
 
 from flwr.common.constant import (
-    FAB_ALLOWED_EXTENSIONS,
+    FAB_CONFIG_FILE,
     FAB_DATE,
+    FAB_EXCLUDE_PATTERNS,
     FAB_HASH_TRUNCATION,
+    FAB_INCLUDE_PATTERNS,
     FAB_MAX_SIZE,
 )
 
-from .config_utils import load as load_toml
 from .config_utils import load_and_validate
-from .utils import is_valid_project_name
+from .utils import build_pathspec, is_valid_project_name, load_gitignore_patterns
 
 
 def write_to_zip(
-    zipfile_obj: zipfile.ZipFile, filename: str, contents: Union[bytes, str]
+    zipfile_obj: zipfile.ZipFile, filename: str, contents: bytes | str
 ) -> zipfile.ZipFile:
-    """Set a fixed date and write contents to a zip file."""
+    """Set a fixed date and write contents to a zip file.
+
+    Parameters
+    ----------
+    zipfile_obj : zipfile.ZipFile
+        The ZipFile object to write to.
+    filename : str
+        Name of the file within the zip archive.
+    contents : bytes | str
+        The file contents to write.
+
+    Returns
+    -------
+    ZipFile
+        The modified ZipFile object.
+    """
     zip_info = zipfile.ZipInfo(filename)
     zip_info.date_time = FAB_DATE
     zipfile_obj.writestr(zip_info, contents)
@@ -48,7 +65,21 @@ def write_to_zip(
 
 
 def get_fab_filename(config: dict[str, Any], fab_hash: str) -> str:
-    """Get the FAB filename based on the given config and FAB hash."""
+    """Get the FAB filename based on the given config and FAB hash.
+
+    Parameters
+    ----------
+    config : dict[str, Any]
+        The project configuration dictionary.
+    fab_hash : str
+        The SHA-256 hash of the FAB file.
+
+    Returns
+    -------
+    str
+        The formatted FAB filename in the pattern:
+        <publisher>.<name>.<version>.<hash_prefix>.fab
+    """
     publisher = config["tool"]["flwr"]["app"]["publisher"]
     name = config["project"]["name"]
     version = config["project"]["version"].replace(".", "-")
@@ -59,7 +90,7 @@ def get_fab_filename(config: dict[str, Any], fab_hash: str) -> str:
 # pylint: disable=too-many-locals, too-many-statements
 def build(
     app: Annotated[
-        Optional[Path],
+        Path | None,
         typer.Option(help="Path of the Flower App to bundle into a FAB"),
     ] = None,
 ) -> None:
@@ -80,6 +111,7 @@ def build(
             f"❌ The path {app} is not a valid path to a Flower app.",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -90,6 +122,7 @@ def build(
             "and can only contain letters, digits, and hyphens.",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -100,6 +133,7 @@ def build(
             + "\n".join([f"- {line}" for line in errors]),
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -112,7 +146,10 @@ def build(
         )
 
     # Build FAB
-    fab_bytes, fab_hash, _ = build_fab(app)
+    fab_bytes = build_fab_from_disk(app)
+
+    # Calculate hash for filename
+    fab_hash = hashlib.sha256(fab_bytes).hexdigest()
 
     # Get the name of the zip file
     fab_filename = get_fab_filename(config, fab_hash)
@@ -125,11 +162,10 @@ def build(
     )
 
 
-def build_fab(app: Path) -> tuple[bytes, str, dict[str, Any]]:
-    """Build a FAB in memory and return the bytes, hash, and config.
+def build_fab_from_disk(app: Path) -> bytes:
+    """Build a FAB from files on disk and return the FAB as bytes.
 
-    This function assumes that the provided path points to a valid Flower app and
-    bundles it into a FAB without performing additional validation.
+    This function reads files from disk and bundles them into a FAB.
 
     Parameters
     ----------
@@ -138,18 +174,67 @@ def build_fab(app: Path) -> tuple[bytes, str, dict[str, Any]]:
 
     Returns
     -------
-    tuple[bytes, str, dict[str, Any]]
-        A tuple containing:
-        - the FAB as bytes
-        - the SHA256 hash of the FAB
-        - the project configuration (with the 'federations' field removed)
+    bytes
+        The FAB as bytes.
     """
     app = app.resolve()
 
-    # Load the pyproject.toml file
-    config = load_toml(app / "pyproject.toml")
-    if config is None:
-        raise ValueError("Project configuration could not be loaded.")
+    # Collect all files recursively (including pyproject.toml and .gitignore)
+    all_files = [f for f in app.rglob("*") if f.is_file()]
+
+    # Create dict mapping relative paths to Path objects
+    files_dict: dict[str, bytes | Path] = {
+        # Ensure consistent path separators across platforms
+        str(file_path.relative_to(app)).replace("\\", "/"): file_path
+        for file_path in all_files
+    }
+
+    # Build FAB from the files dict
+    return build_fab_from_files(files_dict)
+
+
+def build_fab_from_files(files: dict[str, bytes | Path]) -> bytes:
+    r"""Build a FAB from in-memory files and return the FAB as bytes.
+
+    This is the core FAB building function that works with in-memory data.
+    It accepts either bytes or Path objects as file contents, applies filtering
+    rules (include/exclude patterns), and builds the FAB.
+
+    Parameters
+    ----------
+    files : dict[str, Union[bytes, Path]]
+        Dictionary mapping relative file paths to their contents.
+        - Keys: Relative paths (strings)
+        - Values: Either bytes (file contents) or Path (will be read)
+        Must include "pyproject.toml" and optionally ".gitignore".
+
+    Returns
+    -------
+    bytes
+        The FAB as bytes.
+
+    Examples
+    --------
+    Build a FAB from in-memory files::
+
+        files = {
+            "pyproject.toml": b"[project]\nname = 'myapp'\n...",
+            ".gitignore": b"*.pyc\n__pycache__/\n",
+            "src/client.py": Path("/path/to/client.py"),
+            "src/server.py": b"print('hello')",
+            "README.md": b"# My App\n",
+        }
+        fab_bytes = build_fab_from_files(files)
+    """
+
+    def to_bytes(content: bytes | Path) -> bytes:
+        return content.read_bytes() if isinstance(content, Path) else content
+
+    # Extract, load, and parse pyproject.toml
+    if FAB_CONFIG_FILE not in files:
+        raise ValueError(f"{FAB_CONFIG_FILE} not found in files")
+    pyproject_content = to_bytes(files[FAB_CONFIG_FILE])
+    config = tomli.loads(pyproject_content.decode("utf-8"))
 
     # Remove the 'federations' field if it exists
     if (
@@ -159,18 +244,22 @@ def build_fab(app: Path) -> tuple[bytes, str, dict[str, Any]]:
     ):
         del config["tool"]["flwr"]["federations"]
 
-    # Load .gitignore rules if present
-    ignore_spec = _load_gitignore(app)
+    # Extract and load .gitignore if present
+    gitignore_content = None
+    if ".gitignore" in files:
+        gitignore_content = to_bytes(files[".gitignore"])
+
+    # Get exclude and include specs
+    exclude_spec = get_fab_exclude_pathspec(gitignore_content)
+    include_spec = get_fab_include_pathspec()
 
-    # Search for all files in the app directory
-    all_files = [
-        f
-        for f in app.rglob("*")
-        if not ignore_spec.match_file(f)
-        and f.suffix in FAB_ALLOWED_EXTENSIONS
-        and f.name != "pyproject.toml"  # Exclude the original pyproject.toml
+    # Filter files based on include/exclude specs
+    filtered_paths = [
+        path.replace("\\", "/")  # Ensure consistent path separators across platforms
+        for path in files.keys()
+        if include_spec.match_file(path) and not exclude_spec.match_file(path)
     ]
-    all_files.sort()
+    filtered_paths.sort()  # Sort for deterministic output
 
     # Create a zip file in memory
     list_file_content = ""
@@ -178,41 +267,65 @@ def build_fab(app: Path) -> tuple[bytes, str, dict[str, Any]]:
     fab_buffer = BytesIO()
     with zipfile.ZipFile(fab_buffer, "w", zipfile.ZIP_DEFLATED) as fab_file:
         # Add pyproject.toml
-        write_to_zip(fab_file, "pyproject.toml", tomli_w.dumps(config))
+        write_to_zip(fab_file, FAB_CONFIG_FILE, tomli_w.dumps(config))
+
+        for file_path in filtered_paths:
 
-        for file_path in all_files:
-            # Read the file content manually
-            file_contents = file_path.read_bytes()
+            # Get file contents as bytes
+            file_content = to_bytes(files[file_path])
 
-            archive_path = str(file_path.relative_to(app)).replace("\\", "/")
-            write_to_zip(fab_file, archive_path, file_contents)
+            # Write file to FAB
+            write_to_zip(fab_file, file_path, file_content)
 
-            # Calculate file info
-            sha256_hash = hashlib.sha256(file_contents).hexdigest()
-            file_size_bits = len(file_contents) * 8  # size in bits
-            list_file_content += f"{archive_path},{sha256_hash},{file_size_bits}\n"
+            # Calculate file info for CONTENT manifest
+            sha256_hash = hashlib.sha256(file_content).hexdigest()
+            file_size_bits = len(file_content) * 8  # size in bits
+            list_file_content += f"{file_path},{sha256_hash},{file_size_bits}\n"
 
-        # Add CONTENT and CONTENT.jwt to the zip file
+        # Add CONTENT manifest to the zip file
         write_to_zip(fab_file, ".info/CONTENT", list_file_content)
 
     fab_bytes = fab_buffer.getvalue()
+
+    # Validate FAB size
     if len(fab_bytes) > FAB_MAX_SIZE:
         raise ValueError(
-            f"FAB size exceeds maximum allowed size of {FAB_MAX_SIZE:,} bytes."
+            f"FAB size exceeds maximum allowed size of {FAB_MAX_SIZE:,} bytes. "
             "To reduce the package size, consider ignoring unnecessary files "
             "via your `.gitignore` file or excluding them from the build."
         )
 
-    fab_hash = hashlib.sha256(fab_bytes).hexdigest()
+    return fab_bytes
+
 
-    return fab_bytes, fab_hash, config
+def get_fab_include_pathspec() -> pathspec.PathSpec:
+    """Get the PathSpec for files to include in a FAB.
 
+    Returns
+    -------
+    PathSpec
+        PathSpec object with default include patterns for FAB files.
+    """
+    return build_pathspec(FAB_INCLUDE_PATTERNS)
+
+
+def get_fab_exclude_pathspec(gitignore_content: bytes | None) -> pathspec.PathSpec:
+    """Get the PathSpec for files to exclude from a FAB.
+
+    If gitignore_content is provided, its patterns will be combined with the default
+    exclude patterns.
 
-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())
+    Parameters
+    ----------
+    gitignore_content : bytes | None
+        Optional gitignore file content as bytes.
+
+    Returns
+    -------
+    PathSpec
+        PathSpec object with combined exclude patterns.
+    """
+    patterns = list(FAB_EXCLUDE_PATTERNS)
+    if gitignore_content:
+        patterns += load_gitignore_patterns(gitignore_content)
     return pathspec.PathSpec.from_lines("gitwildmatch", patterns)

flwr/cli/{cli_user_auth_interceptor.py → cli_account_auth_interceptor.py}

@@ -15,26 +15,29 @@
 """Flower run interceptor."""
 
 
-from typing import Any, Callable, Union
+from collections.abc import Callable
+from typing import Any
 
 import grpc
 
-from flwr.common.auth_plugin import CliAuthPlugin
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     StartRunRequest,
     StreamLogsRequest,
 )
 
-Request = Union[
-    StartRunRequest,
-    StreamLogsRequest,
-]
+from .auth_plugin import CliAuthPlugin
+
+Request = StartRunRequest | StreamLogsRequest
 
 
-class CliUserAuthInterceptor(
+class CliAccountAuthInterceptor(
     grpc.UnaryUnaryClientInterceptor, grpc.UnaryStreamClientInterceptor  # type: ignore
 ):
-    """CLI interceptor for user authentication."""
+    """CLI interceptor for account authentication.
+
+    This interceptor adds authentication tokens to gRPC metadata for CLI requests and
+    handles token refresh from response metadata.
+    """
 
     def __init__(self, auth_plugin: CliAuthPlugin):
         self.auth_plugin = auth_plugin
@@ -45,7 +48,22 @@ class CliUserAuthInterceptor(
         client_call_details: grpc.ClientCallDetails,
         request: Request,
     ) -> grpc.Call:
-        """Send and receive tokens via metadata."""
+        """Send and receive tokens via metadata.
+
+        Parameters
+        ----------
+        continuation : Callable[[Any, Any], Any]
+            The next interceptor or handler in the chain.
+        client_call_details : grpc.ClientCallDetails
+            Details of the RPC call as a NamedTuple.
+        request : Request
+            The RPC request object.
+
+        Returns
+        -------
+        grpc.Call
+            The RPC response.
+        """
         new_metadata = self.auth_plugin.write_tokens_to_metadata(
             client_call_details.metadata or []
         )
@@ -69,7 +87,7 @@ class CliUserAuthInterceptor(
         client_call_details: grpc.ClientCallDetails,
         request: Request,
     ) -> grpc.Call:
-        """Intercept a unary-unary call for user authentication.
+        """Intercept a unary-unary call for account authentication.
 
         This method intercepts a unary-unary RPC call initiated from the CLI and adds
         the required authentication tokens to the RPC metadata.
@@ -82,7 +100,7 @@ class CliUserAuthInterceptor(
         client_call_details: grpc.ClientCallDetails,
         request: Request,
     ) -> grpc.Call:
-        """Intercept a unary-stream call for user authentication.
+        """Intercept a unary-stream call for account authentication.
 
         This method intercepts a unary-stream RPC call initiated from the CLI and adds
         the required authentication tokens to the RPC metadata.

flwr/cli/config_utils.py

@@ -16,7 +16,7 @@
 
 
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 import tomli
 import typer
@@ -30,7 +30,7 @@ from flwr.common.config import (
 )
 
 
-def get_fab_metadata(fab_file: Union[Path, bytes]) -> tuple[str, str]:
+def get_fab_metadata(fab_file: Path | bytes) -> tuple[str, str]:
     """Extract the fab_id and the fab_version from a FAB file or path.
 
     Parameters
@@ -48,9 +48,9 @@ def get_fab_metadata(fab_file: Union[Path, bytes]) -> tuple[str, str]:
 
 
 def load_and_validate(
-    path: Optional[Path] = None,
+    path: Path | None = None,
     check_module: bool = True,
-) -> tuple[Optional[dict[str, Any]], list[str], list[str]]:
+) -> tuple[dict[str, Any] | None, list[str], list[str]]:
     """Load and validate pyproject.toml as dict.
 
     Parameters
@@ -89,8 +89,20 @@ def load_and_validate(
     return (config, errors, warnings)
 
 
-def load(toml_path: Path) -> Optional[dict[str, Any]]:
-    """Load pyproject.toml and return as dict."""
+def load(toml_path: Path) -> dict[str, Any] | None:
+    """Load pyproject.toml and return as dict.
+
+    Parameters
+    ----------
+    toml_path : Path
+        Path to the pyproject.toml file.
+
+    Returns
+    -------
+    dict[str, Any] | None
+        Parsed TOML configuration as dictionary, or None if file doesn't exist
+        or has invalid TOML syntax.
+    """
     if not toml_path.is_file():
         return None
 
@@ -102,12 +114,31 @@ def load(toml_path: Path) -> Optional[dict[str, Any]]:
 
 
 def process_loaded_project_config(
-    config: Union[dict[str, Any], None], errors: list[str], warnings: list[str]
+    config: 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.
+
+    Parameters
+    ----------
+    config : dict[str, Any] | None
+        The loaded configuration dictionary, or None if loading failed.
+    errors : list[str]
+        List of error messages from validation.
+    warnings : list[str]
+        List of warning messages from validation.
+
+    Returns
+    -------
+    dict[str, Any]
+        The validated configuration dictionary.
+
+    Raises
+    ------
+    typer.Exit
+        If config is None or contains critical errors.
     """
     if config is None:
         typer.secho(
@@ -116,6 +147,7 @@ def process_loaded_project_config(
             + "\n".join([f"- {line}" for line in errors]),
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -133,11 +165,32 @@ def process_loaded_project_config(
 
 
 def validate_federation_in_project_config(
-    federation: Optional[str],
+    federation: str | None,
     config: dict[str, Any],
-    overrides: Optional[list[str]] = None,
+    overrides: list[str] | None = None,
 ) -> tuple[str, dict[str, Any]]:
-    """Validate the federation name in the Flower project configuration."""
+    """Validate the federation name in the Flower project configuration.
+
+    Parameters
+    ----------
+    federation : str | None
+        Name of the federation, or None to use default from config.
+    config : dict[str, Any]
+        The project configuration dictionary.
+    overrides : list[str] | None
+        List of configuration override strings. Default is None.
+
+    Returns
+    -------
+    tuple[str, dict[str, Any]]
+        A tuple of (federation_name, federation_config).
+
+    Raises
+    ------
+    typer.Exit
+        If no federation name provided and no default found, or if federation
+        doesn't exist in config.
+    """
     federation = federation or config["tool"]["flwr"]["federations"].get("default")
 
     if federation is None:
@@ -147,6 +200,7 @@ def validate_federation_in_project_config(
             "`options.num-supernodes` value).",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -162,6 +216,7 @@ def validate_federation_in_project_config(
             + "\n".join(available_feds),
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -175,7 +230,7 @@ def validate_federation_in_project_config(
 
 def validate_certificate_in_federation_config(
     app: Path, federation_config: dict[str, Any]
-) -> tuple[bool, Optional[bytes]]:
+) -> tuple[bool, bytes | None]:
     """Validate the certificates in the Flower project configuration.
 
     Accepted configurations:
@@ -207,6 +262,7 @@ def validate_certificate_in_federation_config(
                 "is set to `True`.",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1)
 
@@ -218,6 +274,7 @@ def validate_certificate_in_federation_config(
                 f"❌ Failed to read certificate file `{root_certificates}`: {e}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1) from e
     else:
@@ -227,19 +284,49 @@ def validate_certificate_in_federation_config(
 
 
 def exit_if_no_address(federation_config: dict[str, Any], cmd: str) -> None:
-    """Exit if the provided federation_config has no "address" key."""
+    """Exit if the provided federation_config has no "address" key.
+
+    Parameters
+    ----------
+    federation_config : dict[str, Any]
+        The federation configuration dictionary to check.
+    cmd : str
+        The command name to display in the error message.
+
+    Raises
+    ------
+    typer.Exit
+        If 'address' key is not present in federation_config.
+    """
     if "address" not in federation_config:
         typer.secho(
             f"❌ `flwr {cmd}` currently works with a SuperLink. Ensure that the "
             "correct SuperLink (Control API) address is provided in `pyproject.toml`.",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
 
 def get_insecure_flag(federation_config: dict[str, Any]) -> bool:
-    """Extract and validate the `insecure` flag from the federation configuration."""
+    """Extract and validate the `insecure` flag from the federation configuration.
+
+    Parameters
+    ----------
+    federation_config : dict[str, Any]
+        The federation configuration dictionary.
+
+    Returns
+    -------
+    bool
+        The insecure flag value. Returns False if not specified.
+
+    Raises
+    ------
+    typer.Exit
+        If insecure value is not a boolean type.
+    """
     insecure_value = federation_config.get("insecure")
 
     if insecure_value is None:
@@ -252,5 +339,6 @@ def get_insecure_flag(federation_config: dict[str, Any]) -> bool:
         "(`insecure = true` or `insecure = false`)",
         fg=typer.colors.RED,
         bold=True,
+        err=True,
     )
     raise typer.Exit(code=1)

flwr/cli/federation/__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 command line interface `federation` command."""
+
+
+from .ls import ls as ls
+from .show import show as show
+
+__all__ = [
+    "ls",
+    "show",
+]