flwr-nightly 1.19.0.dev20250516__py3-none-any.whl → 1.19.0.dev20250521__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/client/__init__.py

@@ -15,8 +15,8 @@
 """Flower client."""
 
 
-from .app import start_client as start_client
-from .app import start_numpy_client as start_numpy_client
+from ..compat.client.app import start_client as start_client  # Deprecated
+from ..compat.client.app import start_numpy_client as start_numpy_client  # Deprecated
 from .client import Client as Client
 from .client_app import ClientApp as ClientApp
 from .numpy_client import NumPyClient as NumPyClient

flwr/client/client_app.py

@@ -20,6 +20,7 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from typing import Callable, Optional
 
+from flwr.app.metadata import validate_message_type
 from flwr.client.client import Client
 from flwr.client.message_handler.message_handler import (
     handle_legacy_message_from_msgtype,
@@ -28,7 +29,6 @@ from flwr.client.mod.utils import make_ffn
 from flwr.client.typing import ClientFnExt, Mod
 from flwr.common import Context, Message, MessageType
 from flwr.common.logger import warn_deprecated_feature
-from flwr.common.message import validate_message_type
 
 from .typing import ClientAppCallable
 

flwr/client/clientapp/app.py

@@ -23,6 +23,7 @@ from typing import Optional
 
 import grpc
 
+from flwr.app.error import Error
 from flwr.cli.install import install_from_fab
 from flwr.client.client_app import ClientApp, LoadClientAppError
 from flwr.common import Context, Message
@@ -32,7 +33,6 @@ from flwr.common.constant import CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS, ErrorCo
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.grpc import create_channel, on_channel_state_change
 from flwr.common.logger import log
-from flwr.common.message import Error
 from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
 from flwr.common.serde import (
     context_from_proto,

flwr/client/grpc_rere_client/connection.py

@@ -25,13 +25,14 @@ from typing import Callable, Optional, Union, cast
 import grpc
 from cryptography.hazmat.primitives.asymmetric import ec
 
+from flwr.app.metadata import Metadata
 from flwr.client.message_handler.message_handler import validate_out_message
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
 from flwr.common.constant import HEARTBEAT_CALL_TIMEOUT, HEARTBEAT_DEFAULT_INTERVAL
 from flwr.common.grpc import create_channel, on_channel_state_change
 from flwr.common.heartbeat import HeartbeatSender
 from flwr.common.logger import log
-from flwr.common.message import Message, Metadata
+from flwr.common.message import Message
 from flwr.common.retry_invoker import RetryInvoker
 from flwr.common.secure_aggregation.crypto.symmetric_encryption import (
     generate_key_pairs,

flwr/client/rest_client/connection.py

@@ -25,13 +25,14 @@ from cryptography.hazmat.primitives.asymmetric import ec
 from google.protobuf.message import Message as GrpcMessage
 from requests.exceptions import ConnectionError as RequestsConnectionError
 
+from flwr.app.metadata import Metadata
 from flwr.client.message_handler.message_handler import validate_out_message
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
 from flwr.common.constant import HEARTBEAT_DEFAULT_INTERVAL
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.heartbeat import HeartbeatSender
 from flwr.common.logger import log
-from flwr.common.message import Message, Metadata
+from flwr.common.message import Message
 from flwr.common.retry_invoker import RetryInvoker
 from flwr.common.serde import message_from_proto, message_to_proto, run_from_proto
 from flwr.common.typing import Fab, Run