flwr 1.22.0__tar.gz → 1.23.0__tar.gz

{flwr-1.22.0 → flwr-1.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr
-Version: 1.22.0
+Version: 1.23.0
 Summary: Flower: A Friendly Federated AI Framework
 License: Apache-2.0
 Keywords: Artificial Intelligence,Federated AI,Federated Analytics,Federated Evaluation,Federated Learning,Flower,Machine Learning

{flwr-1.22.0 → flwr-1.23.0}/py/flwr/cli/app.py

@@ -28,6 +28,9 @@ from .new import new
 from .pull import pull
 from .run import run
 from .stop import stop
+from .supernode import ls as supernode_list
+from .supernode import register as supernode_register
+from .supernode import unregister as supernode_unregister
 
 app = typer.Typer(
     help=typer.style(
@@ -44,11 +47,22 @@ app.command()(run)
 app.command()(build)
 app.command()(install)
 app.command()(log)
-app.command()(ls)
+app.command("list")(ls)
+app.command(hidden=True)(ls)
 app.command()(stop)
 app.command()(login)
 app.command()(pull)
 
+# Create supernode command group
+supernode_app = typer.Typer(help="Manage SuperNodes")
+supernode_app.command()(supernode_register)
+supernode_app.command()(supernode_unregister)
+# Make it appear as "list"
+supernode_app.command("list")(supernode_list)
+# Hide "ls" command (left as alias)
+supernode_app.command(hidden=True)(supernode_list)
+app.add_typer(supernode_app, name="supernode")
+
 typer_click_object = get_command(app)
 
 

{flwr-1.22.0 → flwr-1.23.0}/py/flwr/cli/auth_plugin/__init__.py

@@ -12,20 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower user auth plugins."""
+"""Flower account auth plugins."""
 
 
-from flwr.common.auth_plugin import CliAuthPlugin
-from flwr.common.constant import AuthType
+from flwr.common.constant import AuthnType
 
+from .auth_plugin import CliAuthPlugin, LoginError
+from .noop_auth_plugin import NoOpCliAuthPlugin
 from .oidc_cli_plugin import OidcCliPlugin
 
 
-def get_cli_auth_plugins() -> dict[str, type[CliAuthPlugin]]:
+def get_cli_plugin_class(authn_type: str) -> type[CliAuthPlugin]:
     """Return all CLI authentication plugins."""
-    return {AuthType.OIDC: OidcCliPlugin}
+    if authn_type == AuthnType.NOOP:
+        return NoOpCliAuthPlugin
+    if authn_type == AuthnType.OIDC:
+        return OidcCliPlugin
+    raise ValueError(f"Unsupported authentication type: {authn_type}")
 
 
 __all__ = [
-    "get_cli_auth_plugins",
+    "CliAuthPlugin",
+    "LoginError",
+    "NoOpCliAuthPlugin",
+    "OidcCliPlugin",
+    "get_cli_plugin_class",
 ]

flwr-1.23.0/py/flwr/cli/auth_plugin/auth_plugin.py

@@ -0,0 +1,95 @@
+# 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.
+# ==============================================================================
+"""Abstract classes for Flower account auth plugin."""
+
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Optional, Union
+
+from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
+from flwr.proto.control_pb2_grpc import ControlStub
+
+
+class LoginError(Exception):
+    """Login error exception."""
+
+    def __init__(self, message: str):
+        self.message = message
+
+
+class CliAuthPlugin(ABC):
+    """Abstract Flower Auth Plugin class for CLI.
+
+    Parameters
+    ----------
+    credentials_path : Path
+        Path to the Flower account's authentication credentials file.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def login(
+        login_details: AccountAuthLoginDetails,
+        control_stub: ControlStub,
+    ) -> AccountAuthCredentials:
+        """Authenticate the account and retrieve authentication credentials.
+
+        Parameters
+        ----------
+        login_details : AccountAuthLoginDetails
+            An object containing the account's login details.
+        control_stub : ControlStub
+            A stub for executing RPC calls to the server.
+
+        Returns
+        -------
+        AccountAuthCredentials
+            The authentication credentials obtained after login.
+
+        Raises
+        ------
+        LoginError
+            If the login process fails.
+        """
+
+    @abstractmethod
+    def __init__(self, credentials_path: Path):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def store_tokens(self, credentials: AccountAuthCredentials) -> None:
+        """Store authentication tokens to the `credentials_path`.
+
+        The credentials, including tokens, will be saved as a JSON file
+        at `credentials_path`.
+        """
+
+    @abstractmethod
+    def load_tokens(self) -> None:
+        """Load authentication tokens from the `credentials_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."""
+
+    @abstractmethod
+    def read_tokens_from_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Optional[AccountAuthCredentials]:
+        """Read authentication tokens from the provided metadata."""

flwr-1.23.0/py/flwr/cli/auth_plugin/noop_auth_plugin.py

@@ -0,0 +1,58 @@
+# 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.
+# ==============================================================================
+"""Concrete NoOp implementation for CLI-side account authentication plugin."""
+
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Optional, Union
+
+from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
+from flwr.proto.control_pb2_grpc import ControlStub
+
+from .auth_plugin import CliAuthPlugin, LoginError
+
+
+class NoOpCliAuthPlugin(CliAuthPlugin):
+    """No-operation implementation of the CliAuthPlugin."""
+
+    @staticmethod
+    def login(
+        login_details: AccountAuthLoginDetails,
+        control_stub: ControlStub,
+    ) -> AccountAuthCredentials:
+        """Raise LoginError as no-op plugin does not support login."""
+        raise LoginError("Account authentication is not enabled on this SuperLink.")
+
+    def __init__(self, credentials_path: Path) -> None:
+        pass
+
+    def store_tokens(self, credentials: AccountAuthCredentials) -> None:
+        """Do nothing."""
+
+    def load_tokens(self) -> None:
+        """Do nothing."""
+
+    def write_tokens_to_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Sequence[tuple[str, Union[str, bytes]]]:
+        """Return the metadata unchanged."""
+        return metadata
+
+    def read_tokens_from_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Optional[AccountAuthCredentials]:
+        """Return None."""
+        return None

{flwr-1.22.0 → flwr-1.23.0}/py/flwr/cli/auth_plugin/oidc_cli_plugin.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower CLI user auth plugin for OIDC."""
+"""Flower CLI account auth plugin for OIDC."""
 
 
 import json
@@ -23,20 +23,21 @@ from typing import Any, Optional, Union
 
 import typer
 
-from flwr.common.auth_plugin import CliAuthPlugin
 from flwr.common.constant import (
     ACCESS_TOKEN_KEY,
-    AUTH_TYPE_JSON_KEY,
+    AUTHN_TYPE_JSON_KEY,
     REFRESH_TOKEN_KEY,
-    AuthType,
+    AuthnType,
 )
-from flwr.common.typing import UserAuthCredentials, UserAuthLoginDetails
+from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     GetAuthTokensRequest,
     GetAuthTokensResponse,
 )
 from flwr.proto.control_pb2_grpc import ControlStub
 
+from .auth_plugin import CliAuthPlugin, LoginError
+
 
 class OidcCliPlugin(CliAuthPlugin):
     """Flower OIDC auth plugin for CLI."""
@@ -48,12 +49,12 @@ class OidcCliPlugin(CliAuthPlugin):
 
     @staticmethod
     def login(
-        login_details: UserAuthLoginDetails,
+        login_details: AccountAuthLoginDetails,
         control_stub: ControlStub,
-    ) -> UserAuthCredentials:
-        """Authenticate the user and retrieve authentication credentials."""
+    ) -> AccountAuthCredentials:
+        """Authenticate the account and retrieve authentication credentials."""
         typer.secho(
-            "Please login with your user credentials here: "
+            "Please log into your Flower account here: "
             f"{login_details.verification_uri_complete}",
             fg=typer.colors.BLUE,
         )
@@ -69,26 +70,16 @@ class OidcCliPlugin(CliAuthPlugin):
             refresh_token = res.refresh_token
 
             if access_token and refresh_token:
-                typer.secho(
-                    "✅ Login successful.",
-                    fg=typer.colors.GREEN,
-                    bold=False,
-                )
-                return UserAuthCredentials(
+                return AccountAuthCredentials(
                     access_token=access_token,
                     refresh_token=refresh_token,
                 )
 
             time.sleep(login_details.interval)
 
-        typer.secho(
-            "❌ Timeout, failed to sign in.",
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1)
+        raise LoginError("Process timed out.")
 
-    def store_tokens(self, credentials: UserAuthCredentials) -> None:
+    def store_tokens(self, credentials: AccountAuthCredentials) -> None:
         """Store authentication tokens to the `credentials_path`.
 
         The credentials, including tokens, will be saved as a JSON file
@@ -97,7 +88,7 @@ class OidcCliPlugin(CliAuthPlugin):
         self.access_token = credentials.access_token
         self.refresh_token = credentials.refresh_token
         json_dict = {
-            AUTH_TYPE_JSON_KEY: AuthType.OIDC,
+            AUTHN_TYPE_JSON_KEY: AuthnType.OIDC,
             ACCESS_TOKEN_KEY: credentials.access_token,
             REFRESH_TOKEN_KEY: credentials.refresh_token,
         }
@@ -135,14 +126,14 @@ class OidcCliPlugin(CliAuthPlugin):
 
     def read_tokens_from_metadata(
         self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Optional[UserAuthCredentials]:
+    ) -> Optional[AccountAuthCredentials]:
         """Read authentication tokens from the provided metadata."""
         metadata_dict = dict(metadata)
         access_token = metadata_dict.get(ACCESS_TOKEN_KEY)
         refresh_token = metadata_dict.get(REFRESH_TOKEN_KEY)
 
         if isinstance(access_token, str) and isinstance(refresh_token, str):
-            return UserAuthCredentials(
+            return AccountAuthCredentials(
                 access_token=access_token,
                 refresh_token=refresh_token,
             )

{flwr-1.22.0 → flwr-1.23.0}/py/flwr/cli/build.py

@@ -17,22 +17,25 @@
 
 import hashlib
 import zipfile
+from collections.abc import Iterable
 from io import BytesIO
 from pathlib import Path
 from typing import Annotated, Any, Optional, Union
 
 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
 
@@ -112,7 +115,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 +131,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 +143,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, Union[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, Union[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: Union[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 +213,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 +236,54 @@ 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 all_files:
-            # Read the file content manually
-            file_contents = file_path.read_bytes()
+        for file_path in filtered_paths:
 
-            archive_path = str(file_path.relative_to(app)).replace("\\", "/")
-            write_to_zip(fab_file, archive_path, file_contents)
+            # Get file contents as bytes
+            file_content = to_bytes(files[file_path])
 
-            # 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"
+            # Write file to FAB
+            write_to_zip(fab_file, file_path, file_content)
 
-        # Add CONTENT and CONTENT.jwt to the zip file
+            # 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 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 build_pathspec(patterns: Iterable[str]) -> pathspec.PathSpec:
+    """Build a PathSpec from a list of patterns."""
+    return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
+
+
+def get_fab_include_pathspec() -> pathspec.PathSpec:
+    """Get the PathSpec for files to include in a FAB."""
+    return build_pathspec(FAB_INCLUDE_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())
+
+def get_fab_exclude_pathspec(gitignore_content: Optional[bytes]) -> 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.
+    """
+    patterns = list(FAB_EXCLUDE_PATTERNS)
+    if gitignore_content:
+        patterns += gitignore_content.decode("UTF-8").splitlines()
     return pathspec.PathSpec.from_lines("gitwildmatch", patterns)

flwr-1.22.0/py/flwr/cli/cli_user_auth_interceptor.py → flwr-1.23.0/py/flwr/cli/cli_account_auth_interceptor.py

@@ -19,22 +19,23 @@ from typing import Any, Callable, Union
 
 import grpc
 
-from flwr.common.auth_plugin import CliAuthPlugin
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     StartRunRequest,
     StreamLogsRequest,
 )
 
+from .auth_plugin import CliAuthPlugin
+
 Request = Union[
     StartRunRequest,
     StreamLogsRequest,
 ]
 
 
-class CliUserAuthInterceptor(
+class CliAccountAuthInterceptor(
     grpc.UnaryUnaryClientInterceptor, grpc.UnaryStreamClientInterceptor  # type: ignore
 ):
-    """CLI interceptor for user authentication."""
+    """CLI interceptor for account authentication."""
 
     def __init__(self, auth_plugin: CliAuthPlugin):
         self.auth_plugin = auth_plugin
@@ -69,7 +70,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 +83,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-1.22.0 → flwr-1.23.0}/py/flwr/cli/log.py

@@ -35,7 +35,7 @@ from flwr.common.logger import log as logger
 from flwr.proto.control_pb2 import StreamLogsRequest  # pylint: disable=E0611
 from flwr.proto.control_pb2_grpc import ControlStub
 
-from .utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
+from .utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
 
 
 class AllLogsRetrieved(BaseException):
@@ -186,7 +186,7 @@ def _log_with_control_api(
     run_id: int,
     stream: bool,
 ) -> None:
-    auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
+    auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
     channel = init_channel(app, federation_config, auth_plugin)
 
     if stream: