flwr 1.18.0__py3-none-any.whl → 1.20.0__py3-none-any.whl

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/build.py

@@ -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
 
@@ -27,8 +25,14 @@ import pathspec
 import tomli_w
 import typer
 
-from flwr.common.constant import FAB_ALLOWED_EXTENSIONS, FAB_DATE, FAB_HASH_TRUNCATION
+from flwr.common.constant import (
+    FAB_ALLOWED_EXTENSIONS,
+    FAB_DATE,
+    FAB_HASH_TRUNCATION,
+    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
 
@@ -43,11 +47,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"
 
@@ -58,7 +62,7 @@ def build(
         Optional[Path],
         typer.Option(help="Path of the Flower App to bundle into a FAB"),
     ] = None,
-) -> tuple[str, str]:
+) -> None:
     """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
@@ -89,8 +93,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 +111,101 @@ 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)
 
-    # 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"]
+    # Write the FAB
+    Path(fab_filename).write_bytes(fab_bytes)
 
-    toml_contents = tomli_w.dumps(conf)
+    typer.secho(
+        f"🎊 Successfully built {fab_filename}", fg=typer.colors.GREEN, bold=True
+    )
 
-    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)
+def build_fab(app: Path) -> tuple[bytes, str, dict[str, Any]]:
+    """Build a FAB in memory and return the bytes, hash, and config.
 
-            # 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
-            ]
+    This function assumes that the provided path points to a valid Flower app and
+    bundles it into a FAB without performing additional validation.
 
-            all_files.sort()
+    Parameters
+    ----------
+    app : Path
+        Path to the Flower app to bundle into a FAB.
 
-            for file_path in all_files:
-                # Read the file content manually
-                with open(file_path, "rb") as f:
-                    file_contents = f.read()
+    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()
 
-                archive_path = file_path.relative_to(app)
-                write_to_zip(fab_file, str(archive_path), file_contents)
+    # Load the pyproject.toml file
+    config = load_toml(app / "pyproject.toml")
+    if config is None:
+        raise ValueError("Project configuration could not be loaded.")
 
-                # 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"
+    # 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"]
 
-            # Add CONTENT and CONTENT.jwt to the zip file
-            write_to_zip(fab_file, ".info/CONTENT", list_file_content)
+    # Load .gitignore rules if present
+    ignore_spec = _load_gitignore(app)
 
-    # Get hash of FAB file
-    content = Path(temp_filename).read_bytes()
-    fab_hash = hashlib.sha256(content).hexdigest()
+    # 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 = ""
 
-    # Set the name of the zip file
-    fab_filename = get_fab_filename(conf, fab_hash)
+    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))
 
-    # Once the temporary zip file is created, rename it to the final filename
-    shutil.move(temp_filename, fab_filename)
+        for file_path in all_files:
+            # Read the file content manually
+            file_contents = file_path.read_bytes()
 
-    typer.secho(
-        f"🎊 Successfully built {fab_filename}", fg=typer.colors.GREEN, bold=True
-    )
+            archive_path = str(file_path.relative_to(app)).replace("\\", "/")
+            write_to_zip(fab_file, archive_path, file_contents)
+
+            # 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"
+
+        # Add CONTENT and CONTENT.jwt to the zip file
+        write_to_zip(fab_file, ".info/CONTENT", list_file_content)
+
+    fab_bytes = fab_buffer.getvalue()
+    if len(fab_bytes) > FAB_MAX_SIZE:
+        raise ValueError(
+            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_filename, fab_hash
+    return fab_bytes, fab_hash, config
 
 
 def _load_gitignore(app: Path) -> pathspec.PathSpec:

flwr/cli/log.py

@@ -35,7 +35,7 @@ from flwr.common.logger import log as logger
 from flwr.proto.exec_pb2 import StreamLogsRequest  # pylint: disable=E0611
 from flwr.proto.exec_pb2_grpc import ExecStub
 
-from .utils import init_channel, try_obtain_cli_auth_plugin, unauthenticated_exc_handler
+from .utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
 
 
 class AllLogsRetrieved(BaseException):
@@ -95,7 +95,7 @@ def stream_logs(
     latest_timestamp = 0.0
     res = None
     try:
-        with unauthenticated_exc_handler():
+        with flwr_cli_grpc_exc_handler():
             for res in stub.StreamLogs(req, timeout=duration):
                 print(res.log_output, end="")
         raise AllLogsRetrieved()
@@ -116,7 +116,7 @@ def print_logs(run_id: int, channel: grpc.Channel, timeout: int) -> None:
     req = StreamLogsRequest(run_id=run_id, after_timestamp=0.0)
 
     try:
-        with unauthenticated_exc_handler():
+        with flwr_cli_grpc_exc_handler():
             # Enforce timeout for graceful exit
             for res in stub.StreamLogs(req, timeout=timeout):
                 print(res.log_output)

flwr/cli/login/login.py

@@ -35,11 +35,7 @@ from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
 )
 from flwr.proto.exec_pb2_grpc import ExecStub
 
-from ..utils import (
-    init_channel,
-    try_obtain_cli_auth_plugin,
-    unauthenticated_exc_handler,
-)
+from ..utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
 
 
 def login(  # pylint: disable=R0914
@@ -96,7 +92,7 @@ def login(  # pylint: disable=R0914
     stub = ExecStub(channel)
 
     login_request = GetLoginDetailsRequest()
-    with unauthenticated_exc_handler():
+    with flwr_cli_grpc_exc_handler():
         login_response: GetLoginDetailsResponse = stub.GetLoginDetails(login_request)
 
     # Get the auth plugin
@@ -120,7 +116,7 @@ def login(  # pylint: disable=R0914
         expires_in=login_response.expires_in,
         interval=login_response.interval,
     )
-    with unauthenticated_exc_handler():
+    with flwr_cli_grpc_exc_handler():
         credentials = auth_plugin.login(details, stub)
 
     # Store the tokens

flwr/cli/ls.py

@@ -44,7 +44,7 @@ from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
 )
 from flwr.proto.exec_pb2_grpc import ExecStub
 
-from .utils import init_channel, try_obtain_cli_auth_plugin, unauthenticated_exc_handler
+from .utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
 
 _RunListType = tuple[int, str, str, str, str, str, str, str, str]
 
@@ -130,23 +130,16 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
             # Display information about a specific run ID
             if run_id is not None:
                 typer.echo(f"🔍 Displaying information for run ID {run_id}...")
-                restore_output()
-                _display_one_run(stub, run_id, output_format)
+                formatted_runs = _display_one_run(stub, run_id)
             # By default, list all runs
             else:
                 typer.echo("📄 Listing all runs...")
-                restore_output()
-                _list_runs(stub, output_format)
-
-        except ValueError as err:
-            if suppress_output:
-                redirect_output(captured_output)
-            typer.secho(
-                f"❌ {err}",
-                fg=typer.colors.RED,
-                bold=True,
-            )
-            raise typer.Exit(code=1) from err
+                formatted_runs = _list_runs(stub)
+            restore_output()
+            if output_format == CliOutputFormat.JSON:
+                Console().print_json(_to_json(formatted_runs))
+            else:
+                Console().print(_to_table(formatted_runs))
         finally:
             if channel:
                 channel.close()
@@ -300,37 +293,23 @@ def _to_json(run_list: list[_RunListType]) -> str:
     return json.dumps({"success": True, "runs": runs_list})
 
 
-def _list_runs(
-    stub: ExecStub,
-    output_format: str = CliOutputFormat.DEFAULT,
-) -> None:
+def _list_runs(stub: ExecStub) -> list[_RunListType]:
     """List all runs."""
-    with unauthenticated_exc_handler():
+    with flwr_cli_grpc_exc_handler():
         res: ListRunsResponse = stub.ListRuns(ListRunsRequest())
     run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
 
-    formatted_runs = _format_runs(run_dict, res.now)
-    if output_format == CliOutputFormat.JSON:
-        Console().print_json(_to_json(formatted_runs))
-    else:
-        Console().print(_to_table(formatted_runs))
+    return _format_runs(run_dict, res.now)
 
 
-def _display_one_run(
-    stub: ExecStub,
-    run_id: int,
-    output_format: str = CliOutputFormat.DEFAULT,
-) -> None:
+def _display_one_run(stub: ExecStub, run_id: int) -> list[_RunListType]:
     """Display information about a specific run."""
-    with unauthenticated_exc_handler():
+    with flwr_cli_grpc_exc_handler():
         res: ListRunsResponse = stub.ListRuns(ListRunsRequest(run_id=run_id))
     if not res.run_dict:
+        # This won't be reached as an gRPC error is raised if run_id is invalid
         raise ValueError(f"Run ID {run_id} not found")
 
     run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
 
-    formatted_runs = _format_runs(run_dict, res.now)
-    if output_format == CliOutputFormat.JSON:
-        Console().print_json(_to_json(formatted_runs))
-    else:
-        Console().print(_to_table(formatted_runs))
+    return _format_runs(run_dict, res.now)