flwr 1.17.0__py3-none-any.whl → 1.19.0__py3-none-any.whl

flwr/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# 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.

flwr/app/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+# ==============================================================================
+"""Public Flower App APIs."""

flwr/app/error.py

@@ -0,0 +1,68 @@
+# 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.
+# ==============================================================================
+"""Error."""
+
+
+from __future__ import annotations
+
+from typing import Optional, cast
+
+DEFAULT_TTL = 43200  # This is 12 hours
+MESSAGE_INIT_ERROR_MESSAGE = (
+    "Invalid arguments for Message. Expected one of the documented "
+    "signatures: Message(content: RecordDict, dst_node_id: int, message_type: str,"
+    " *, [ttl: float, group_id: str]) or Message(content: RecordDict | error: Error,"
+    " *, reply_to: Message, [ttl: float])."
+)
+
+
+class Error:
+    """The class storing information about an error that occurred.
+
+    Parameters
+    ----------
+    code : int
+        An identifier for the error.
+    reason : Optional[str]
+        A reason for why the error arose (e.g. an exception stack-trace)
+    """
+
+    def __init__(self, code: int, reason: str | None = None) -> None:
+        var_dict = {
+            "_code": code,
+            "_reason": reason,
+        }
+        self.__dict__.update(var_dict)
+
+    @property
+    def code(self) -> int:
+        """Error code."""
+        return cast(int, self.__dict__["_code"])
+
+    @property
+    def reason(self) -> str | None:
+        """Reason reported about the error."""
+        return cast(Optional[str], self.__dict__["_reason"])
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        view = ", ".join([f"{k.lstrip('_')}={v!r}" for k, v in self.__dict__.items()])
+        return f"{self.__class__.__qualname__}({view})"
+
+    def __eq__(self, other: object) -> bool:
+        """Compare two instances of the class."""
+        if not isinstance(other, self.__class__):
+            raise NotImplementedError
+        return self.__dict__ == other.__dict__

flwr/app/metadata.py

@@ -0,0 +1,223 @@
+# 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.
+# ==============================================================================
+"""Metadata."""
+
+
+from __future__ import annotations
+
+from typing import cast
+
+from ..common.constant import MessageType, MessageTypeLegacy
+
+
+class Metadata:  # pylint: disable=too-many-instance-attributes
+    """The class representing metadata associated with the current message.
+
+    Parameters
+    ----------
+    run_id : int
+        An identifier for the current run.
+    message_id : str
+        An identifier for the current message.
+    src_node_id : int
+        An identifier for the node sending this message.
+    dst_node_id : int
+        An identifier for the node receiving this message.
+    reply_to_message_id : str
+        An identifier for the message to which this message is a reply.
+    group_id : str
+        An identifier for grouping messages. In some settings,
+        this is used as the FL round.
+    created_at : float
+        Unix timestamp when the message was created.
+    ttl : float
+        Time-to-live for this message in seconds.
+    message_type : str
+        A string that encodes the action to be executed on
+        the receiving end.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        run_id: int,
+        message_id: str,
+        src_node_id: int,
+        dst_node_id: int,
+        reply_to_message_id: str,
+        group_id: str,
+        created_at: float,
+        ttl: float,
+        message_type: str,
+    ) -> None:
+        var_dict = {
+            "_run_id": run_id,
+            "_message_id": message_id,
+            "_src_node_id": src_node_id,
+            "_dst_node_id": dst_node_id,
+            "_reply_to_message_id": reply_to_message_id,
+            "_group_id": group_id,
+            "_created_at": created_at,
+            "_ttl": ttl,
+            "_message_type": message_type,
+        }
+        self.__dict__.update(var_dict)
+        self.message_type = message_type  # Trigger validation
+
+    @property
+    def run_id(self) -> int:
+        """An identifier for the current run."""
+        return cast(int, self.__dict__["_run_id"])
+
+    @property
+    def message_id(self) -> str:
+        """An identifier for the current message."""
+        return cast(str, self.__dict__["_message_id"])
+
+    @property
+    def src_node_id(self) -> int:
+        """An identifier for the node sending this message."""
+        return cast(int, self.__dict__["_src_node_id"])
+
+    @property
+    def reply_to_message_id(self) -> str:
+        """An identifier for the message to which this message is a reply."""
+        return cast(str, self.__dict__["_reply_to_message_id"])
+
+    @property
+    def dst_node_id(self) -> int:
+        """An identifier for the node receiving this message."""
+        return cast(int, self.__dict__["_dst_node_id"])
+
+    @dst_node_id.setter
+    def dst_node_id(self, value: int) -> None:
+        """Set dst_node_id."""
+        self.__dict__["_dst_node_id"] = value
+
+    @property
+    def group_id(self) -> str:
+        """An identifier for grouping messages."""
+        return cast(str, self.__dict__["_group_id"])
+
+    @group_id.setter
+    def group_id(self, value: str) -> None:
+        """Set group_id."""
+        self.__dict__["_group_id"] = value
+
+    @property
+    def created_at(self) -> float:
+        """Unix timestamp when the message was created."""
+        return cast(float, self.__dict__["_created_at"])
+
+    @created_at.setter
+    def created_at(self, value: float) -> None:
+        """Set creation timestamp of this message."""
+        self.__dict__["_created_at"] = value
+
+    @property
+    def delivered_at(self) -> str:
+        """Unix timestamp when the message was delivered."""
+        return cast(str, self.__dict__["_delivered_at"])
+
+    @delivered_at.setter
+    def delivered_at(self, value: str) -> None:
+        """Set delivery timestamp of this message."""
+        self.__dict__["_delivered_at"] = value
+
+    @property
+    def ttl(self) -> float:
+        """Time-to-live for this message."""
+        return cast(float, self.__dict__["_ttl"])
+
+    @ttl.setter
+    def ttl(self, value: float) -> None:
+        """Set ttl."""
+        self.__dict__["_ttl"] = value
+
+    @property
+    def message_type(self) -> str:
+        """A string that encodes the action to be executed on the receiving end."""
+        return cast(str, self.__dict__["_message_type"])
+
+    @message_type.setter
+    def message_type(self, value: str) -> None:
+        """Set message_type."""
+        # Validate message type
+        if validate_legacy_message_type(value):
+            pass  # Backward compatibility for legacy message types
+        elif not validate_message_type(value):
+            raise ValueError(
+                f"Invalid message type: '{value}'. "
+                "Expected format: '<category>' or '<category>.<action>', "
+                "where <category> must be 'train', 'evaluate', or 'query', "
+                "and <action> must be a valid Python identifier."
+            )
+
+        self.__dict__["_message_type"] = value
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        view = ", ".join([f"{k.lstrip('_')}={v!r}" for k, v in self.__dict__.items()])
+        return f"{self.__class__.__qualname__}({view})"
+
+    def __eq__(self, other: object) -> bool:
+        """Compare two instances of the class."""
+        if not isinstance(other, self.__class__):
+            raise NotImplementedError
+        return self.__dict__ == other.__dict__
+
+
+def validate_message_type(message_type: str) -> bool:
+    """Validate if the message type is valid.
+
+    A valid message type format must be one of the following:
+
+    - "<category>"
+    - "<category>.<action>"
+
+    where `category` must be one of "train", "evaluate", or "query",
+    and `action` must be a valid Python identifier.
+    """
+    # Check if conforming to the format "<category>"
+    valid_types = {
+        MessageType.TRAIN,
+        MessageType.EVALUATE,
+        MessageType.QUERY,
+        MessageType.SYSTEM,
+    }
+    if message_type in valid_types:
+        return True
+
+    # Check if conforming to the format "<category>.<action>"
+    if message_type.count(".") != 1:
+        return False
+
+    category, action = message_type.split(".")
+    if category in valid_types and action.isidentifier():
+        return True
+
+    return False
+
+
+def validate_legacy_message_type(message_type: str) -> bool:
+    """Validate if the legacy message type is valid."""
+    # Backward compatibility for legacy message types
+    if message_type in (
+        MessageTypeLegacy.GET_PARAMETERS,
+        MessageTypeLegacy.GET_PROPERTIES,
+        "reconnect",
+    ):
+        return True
+
+    return False

flwr/cli/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.

flwr/cli/app.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.
@@ -14,10 +14,11 @@
 # ==============================================================================
 """Flower command line interface."""
 
-
 import typer
 from typer.main import get_command
 
+from flwr.common.version import package_version
+
 from .build import build
 from .install import install
 from .log import log
@@ -34,6 +35,7 @@ app = typer.Typer(
         bold=True,
     ),
     no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
 )
 
 app.command()(new)
@@ -47,5 +49,22 @@ app.command()(login)
 
 typer_click_object = get_command(app)
 
+
+@app.callback(invoke_without_command=True)
+def version_callback(
+    ver: bool = typer.Option(
+        None,
+        "-V",
+        "--version",
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """Print version."""
+    if ver:
+        typer.secho(f"Flower version: {package_version}", fg="blue")
+        raise typer.Exit()
+
+
 if __name__ == "__main__":
     app()

flwr/cli/build.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.
@@ -16,10 +16,8 @@
 
 
 import hashlib
-import os
-import shutil
-import tempfile
 import zipfile
+from io import BytesIO
 from pathlib import Path
 from typing import Annotated, Any, Optional, Union
 
@@ -29,6 +27,7 @@ import typer
 
 from flwr.common.constant import FAB_ALLOWED_EXTENSIONS, FAB_DATE, FAB_HASH_TRUNCATION
 
+from .config_utils import load as load_toml
 from .config_utils import load_and_validate
 from .utils import is_valid_project_name
 
@@ -43,11 +42,11 @@ def write_to_zip(
     return zipfile_obj
 
 
-def get_fab_filename(conf: dict[str, Any], fab_hash: str) -> str:
+def get_fab_filename(config: 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(".", "-")
+    publisher = config["tool"]["flwr"]["app"]["publisher"]
+    name = config["project"]["name"]
+    version = config["project"]["version"].replace(".", "-")
     fab_hash_truncated = fab_hash[:FAB_HASH_TRUNCATION]
     return f"{publisher}.{name}.{version}.{fab_hash_truncated}.fab"
 
@@ -89,8 +88,8 @@ def build(
         )
         raise typer.Exit(code=1)
 
-    conf, errors, warnings = load_and_validate(app / "pyproject.toml")
-    if conf is None:
+    config, errors, warnings = load_and_validate(app / "pyproject.toml")
+    if config is None:
         typer.secho(
             "Project configuration could not be loaded.\npyproject.toml is invalid:\n"
             + "\n".join([f"- {line}" for line in errors]),
@@ -107,70 +106,96 @@ def build(
             bold=True,
         )
 
-    # Load .gitignore rules if present
-    ignore_spec = _load_gitignore(app)
+    # Build FAB
+    fab_bytes, fab_hash, _ = build_fab(app)
 
-    list_file_content = ""
+    # Get the name of the zip file
+    fab_filename = get_fab_filename(config, fab_hash)
+
+    # Write the FAB
+    Path(fab_filename).write_bytes(fab_bytes)
+
+    typer.secho(
+        f"🎊 Successfully built {fab_filename}", fg=typer.colors.GREEN, bold=True
+    )
+
+    return fab_filename, fab_hash
 
-    # 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)
+def build_fab(app: Path) -> tuple[bytes, str, dict[str, Any]]:
+    """Build a FAB in memory and return the bytes, hash, and config.
 
-    with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as temp_file:
-        temp_filename = temp_file.name
+    This function assumes that the provided path points to a valid Flower app and
+    bundles it into a FAB without performing additional validation.
 
-        with zipfile.ZipFile(temp_filename, "w", zipfile.ZIP_DEFLATED) as fab_file:
-            write_to_zip(fab_file, "pyproject.toml", toml_contents)
+    Parameters
+    ----------
+    app : Path
+        Path to the Flower app to bundle into a FAB.
 
-            # 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
-            ]
+    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)
+    """
+    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.")
 
-            all_files.sort()
+    # Remove the 'federations' field if it exists
+    if (
+        "tool" in config
+        and "flwr" in config["tool"]
+        and "federations" in config["tool"]["flwr"]
+    ):
+        del config["tool"]["flwr"]["federations"]
 
-            for file_path in all_files:
-                # Read the file content manually
-                with open(file_path, "rb") as f:
-                    file_contents = f.read()
+    # Load .gitignore rules if present
+    ignore_spec = _load_gitignore(app)
 
-                archive_path = file_path.relative_to(app)
-                write_to_zip(fab_file, str(archive_path), file_contents)
+    # 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
+    ]
+    all_files.sort()
+
+    # Create a zip file in memory
+    list_file_content = ""
 
-                # 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"
+    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))
 
-            # Add CONTENT and CONTENT.jwt to the zip file
-            write_to_zip(fab_file, ".info/CONTENT", list_file_content)
+        for file_path in all_files:
+            # Read the file content manually
+            file_contents = file_path.read_bytes()
 
-    # Get hash of FAB file
-    content = Path(temp_filename).read_bytes()
-    fab_hash = hashlib.sha256(content).hexdigest()
+            archive_path = str(file_path.relative_to(app))
+            write_to_zip(fab_file, archive_path, file_contents)
 
-    # Set the name of the zip file
-    fab_filename = get_fab_filename(conf, fab_hash)
+            # 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"
 
-    # Once the temporary zip file is created, rename it to the final filename
-    shutil.move(temp_filename, fab_filename)
+        # Add CONTENT and CONTENT.jwt to the zip file
+        write_to_zip(fab_file, ".info/CONTENT", list_file_content)
 
-    typer.secho(
-        f"🎊 Successfully built {fab_filename}", fg=typer.colors.GREEN, bold=True
-    )
+    fab_bytes = fab_buffer.getvalue()
+    fab_hash = hashlib.sha256(fab_bytes).hexdigest()
 
-    return fab_filename, fab_hash
+    return fab_bytes, fab_hash, config
 
 
 def _load_gitignore(app: Path) -> pathspec.PathSpec:

flwr/cli/cli_user_auth_interceptor.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.

flwr/cli/config_utils.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.
@@ -176,11 +176,32 @@ def validate_federation_in_project_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")
+    """Validate the certificates in the Flower project configuration.
+
+    Accepted configurations:
+      1. TLS enabled and gRPC will load(*) the trusted certificate bundle:
+         - Only `address` is provided. `root-certificates` and `insecure` not set.
+         - `address` is provided and `insecure` set to `false`. `root-certificates` not
+           set.
+         (*)gRPC uses a multi-step fallback mechanism to load the trusted certificate
+            bundle in the following sequence:
+            a. A configured file path (if set via configuration or environment),
+            b. An override callback (if registered via
+               `grpc_set_ssl_roots_override_callback`),
+            c. The OS trust store (if available),
+            d. A bundled default certificate file.
+      2. TLS enabled with self-signed certificates:
+         - `address` and `root-certificates` are provided. `insecure` not set.
+         - `address` and `root-certificates` are provided. `insecure` set to `false`.
+      3. TLS disabled. This is not recommended and should only be used for prototyping:
+         - `address` is provided and `insecure = true`. If `root-certificates` is
+           set, exit with an error.
+    """
+    insecure = get_insecure_flag(federation_config)
+
+    # Process root certificates
     if root_certificates := federation_config.get("root-certificates"):
-        root_certificates_bytes = (app / root_certificates).read_bytes()
-        if insecure := bool(insecure_str):
+        if insecure:
             typer.secho(
                 "❌ `root-certificates` were provided but the `insecure` parameter "
                 "is set to `True`.",
@@ -188,22 +209,19 @@ def validate_certificate_in_federation_config(
                 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)):
+
+        # TLS is enabled with self-signed certificates: attempt to read the file
+        try:
+            root_certificates_bytes = (app / root_certificates).read_bytes()
+        except Exception as e:
             typer.secho(
-                "❌ No certificate were given yet `insecure` is set to `False`.",
+                f"❌ Failed to read certificate file `{root_certificates}`: {e}",
                 fg=typer.colors.RED,
                 bold=True,
             )
-            raise typer.Exit(code=1)
+            raise typer.Exit(code=1) from e
+    else:
+        root_certificates_bytes = None
 
     return insecure, root_certificates_bytes
 
@@ -218,3 +236,21 @@ def exit_if_no_address(federation_config: dict[str, Any], cmd: str) -> None:
             bold=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."""
+    insecure_value = federation_config.get("insecure")
+
+    if insecure_value is None:
+        # Not provided, default to False (TLS enabled)
+        return False
+    if isinstance(insecure_value, bool):
+        return insecure_value
+    typer.secho(
+        "❌ Invalid type for `insecure`: expected a boolean if provided. "
+        "(`insecure = true` or `insecure = false`)",
+        fg=typer.colors.RED,
+        bold=True,
+    )
+    raise typer.Exit(code=1)

flwr/cli/example.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.