flwr-nightly 1.19.0.dev20250516__py3-none-any.whl → 1.19.0.dev20250521__py3-none-any.whl

flwr/common/inflatable_grpc_utils.py

@@ -0,0 +1,97 @@
+# 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.
+# ==============================================================================
+"""InflatableObject utils."""
+
+
+from typing import Union
+
+from flwr.proto.fleet_pb2_grpc import FleetStub  # pylint: disable=E0611
+from flwr.proto.message_pb2 import (  # pylint: disable=E0611
+    PullObjectRequest,
+    PullObjectResponse,
+    PushObjectRequest,
+    PushObjectResponse,
+)
+from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub  # pylint: disable=E0611
+
+from .inflatable import (
+    InflatableObject,
+    get_object_head_values_from_object_content,
+    get_object_id,
+)
+from .record import Array, ArrayRecord, ConfigRecord, MetricRecord, RecordDict
+
+# Helper registry that maps names of classes to their type
+inflatable_class_registry: dict[str, type[InflatableObject]] = {
+    Array.__qualname__: Array,
+    ArrayRecord.__qualname__: ArrayRecord,
+    ConfigRecord.__qualname__: ConfigRecord,
+    MetricRecord.__qualname__: MetricRecord,
+    RecordDict.__qualname__: RecordDict,
+}
+
+
+def push_object_to_servicer(
+    obj: InflatableObject, stub: Union[FleetStub, ServerAppIoStub]
+) -> set[str]:
+    """Recursively deflate an object and push it to the servicer.
+
+    Objects with the same ID are not pushed twice. It returns the set of pushed object
+    IDs.
+    """
+    pushed_object_ids: set[str] = set()
+    # Push children if it has any
+    if children := obj.children:
+        for child in children.values():
+            pushed_object_ids |= push_object_to_servicer(child, stub)
+
+    # Deflate object and push
+    object_content = obj.deflate()
+    object_id = get_object_id(object_content)
+    _: PushObjectResponse = stub.PushObject(
+        PushObjectRequest(
+            object_id=object_id,
+            object_content=object_content,
+        )
+    )
+    pushed_object_ids.add(object_id)
+
+    return pushed_object_ids
+
+
+def pull_object_from_servicer(
+    object_id: str, stub: Union[FleetStub, ServerAppIoStub]
+) -> InflatableObject:
+    """Recursively inflate an object by pulling it from the servicer."""
+    # Pull object
+    object_proto: PullObjectResponse = stub.PullObject(
+        PullObjectRequest(object_id=object_id)
+    )
+    object_content = object_proto.object_content
+
+    # Extract object class and object_ids of children
+    obj_type, children_obj_ids, _ = get_object_head_values_from_object_content(
+        object_content=object_content
+    )
+    # Resolve object class
+    cls_type = inflatable_class_registry[obj_type]
+
+    # Pull all children objects
+    children: dict[str, InflatableObject] = {}
+    for child_object_id in children_obj_ids:
+        children[child_object_id] = pull_object_from_servicer(child_object_id, stub)
+
+    # Inflate object passing its children
+    return cls_type.inflate(object_content, children=children)

flwr/common/message.py

@@ -18,14 +18,29 @@
 from __future__ import annotations
 
 from logging import WARNING
-from typing import Any, Optional, cast, overload
+from typing import Any, cast, overload
 
 from flwr.common.date import now
 from flwr.common.logger import warn_deprecated_feature
-
-from .constant import MESSAGE_TTL_TOLERANCE, MessageType, MessageTypeLegacy
+from flwr.proto.message_pb2 import Message as ProtoMessage  # pylint: disable=E0611
+
+from ..app.error import Error
+from ..app.metadata import Metadata
+from .constant import MESSAGE_TTL_TOLERANCE
+from .inflatable import (
+    InflatableObject,
+    add_header_to_object_body,
+    get_object_body,
+    get_object_children_ids_from_object_content,
+)
 from .logger import log
 from .record import RecordDict
+from .serde_utils import (
+    error_from_proto,
+    error_to_proto,
+    metadata_from_proto,
+    metadata_to_proto,
+)
 
 DEFAULT_TTL = 43200  # This is 12 hours
 MESSAGE_INIT_ERROR_MESSAGE = (
@@ -56,203 +71,7 @@ class MessageInitializationError(TypeError):
         super().__init__(message or MESSAGE_INIT_ERROR_MESSAGE)
 
 
-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__
-
-
-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__
-
-
-class Message:
+class Message(InflatableObject):
     """Represents a message exchanged between ClientApp and ServerApp.
 
     This class encapsulates the payload and metadata necessary for communication
@@ -525,6 +344,74 @@ class Message:
         )
         return f"{self.__class__.__qualname__}({view})"
 
+    @property
+    def children(self) -> dict[str, InflatableObject] | None:
+        """Return a dictionary of a single RecordDict with its Object IDs as key."""
+        return {self.content.object_id: self.content} if self.has_content() else None
+
+    def deflate(self) -> bytes:
+        """Deflate message."""
+        # Store message metadata and error in object body
+        obj_body = ProtoMessage(
+            metadata=metadata_to_proto(self.metadata),
+            content=None,
+            error=error_to_proto(self.error) if self.has_error() else None,
+        ).SerializeToString(deterministic=True)
+
+        return add_header_to_object_body(object_body=obj_body, obj=self)
+
+    @classmethod
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> Message:
+        """Inflate an Message from bytes.
+
+        Parameters
+        ----------
+        object_content : bytes
+            The deflated object content of the Message.
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Dictionary of children InflatableObjects mapped to their Object IDs.
+            These children enable the full inflation of the Message.
+
+        Returns
+        -------
+        Message
+            The inflated Message.
+        """
+        if children is None:
+            children = {}
+
+        # Get the children id from the deflated message
+        children_ids = get_object_children_ids_from_object_content(object_content)
+
+        # If the message had content, only one children is possible
+        # If the message carried an error, the returned listed should be empty
+        if children_ids != list(children.keys()):
+            raise ValueError(
+                f"Mismatch in children object IDs: expected {children_ids}, but "
+                f"received {list(children.keys())}. The provided children must exactly "
+                "match the IDs specified in the object head."
+            )
+
+        # Inflate content
+        obj_body = get_object_body(object_content, cls)
+        proto_message = ProtoMessage.FromString(obj_body)
+
+        # Prepare content if error wasn't set in protobuf message
+        if proto_message.HasField("error"):
+            content = None
+            error = error_from_proto(proto_message.error)
+        else:
+            content = cast(RecordDict, children[children_ids[0]])
+            error = None
+        # Return message
+        return make_message(
+            metadata=metadata_from_proto(proto_message.metadata),
+            content=content,
+            error=error,
+        )
+
 
 def make_message(
     metadata: Metadata, content: RecordDict | None = None, error: Error | None = None
@@ -614,48 +501,3 @@ def _check_arg_types(  # pylint: disable=too-many-arguments, R0917
     ):
         return
     raise MessageInitializationError()
-
-
-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/common/record/array.py

@@ -284,7 +284,7 @@ class Array(InflatableObject):
         Array
             The inflated Array.
         """
-        if children is not None:
+        if children:
             raise ValueError("`Array` objects do not have children.")
 
         obj_body = get_object_body(object_content, cls)

flwr/common/record/configrecord.py

@@ -204,7 +204,7 @@ class ConfigRecord(TypedDict[str, ConfigRecordValues], InflatableObject):
         ConfigRecord
             The inflated ConfigRecord.
         """
-        if children is not None:
+        if children:
             raise ValueError("`ConfigRecord` objects do not have children.")
 
         obj_body = get_object_body(object_content, cls)

flwr/common/serde.py

@@ -20,11 +20,9 @@ from typing import Any, cast
 
 # pylint: disable=E0611
 from flwr.proto.clientappio_pb2 import ClientAppOutputCode, ClientAppOutputStatus
-from flwr.proto.error_pb2 import Error as ProtoError
 from flwr.proto.fab_pb2 import Fab as ProtoFab
 from flwr.proto.message_pb2 import Context as ProtoContext
 from flwr.proto.message_pb2 import Message as ProtoMessage
-from flwr.proto.message_pb2 import Metadata as ProtoMetadata
 from flwr.proto.recorddict_pb2 import Array as ProtoArray
 from flwr.proto.recorddict_pb2 import ArrayRecord as ProtoArrayRecord
 from flwr.proto.recorddict_pb2 import ConfigRecord as ProtoConfigRecord
@@ -55,8 +53,15 @@ from . import (
     typing,
 )
 from .constant import INT64_MAX_VALUE
-from .message import Error, Message, Metadata, make_message
-from .serde_utils import record_value_dict_from_proto, record_value_dict_to_proto
+from .message import Message, make_message
+from .serde_utils import (
+    error_from_proto,
+    error_to_proto,
+    metadata_from_proto,
+    metadata_to_proto,
+    record_value_dict_from_proto,
+    record_value_dict_to_proto,
+)
 
 #  === Parameters message ===
 
@@ -446,21 +451,6 @@ def config_record_from_proto(record_proto: ProtoConfigRecord) -> ConfigRecord:
     )
 
 
-# === Error message ===
-
-
-def error_to_proto(error: Error) -> ProtoError:
-    """Serialize Error to ProtoBuf."""
-    reason = error.reason if error.reason else ""
-    return ProtoError(code=error.code, reason=reason)
-
-
-def error_from_proto(error_proto: ProtoError) -> Error:
-    """Deserialize Error from ProtoBuf."""
-    reason = error_proto.reason if len(error_proto.reason) > 0 else None
-    return Error(code=error_proto.code, reason=reason)
-
-
 # === RecordDict message ===
 
 
@@ -549,41 +539,6 @@ def user_config_value_from_proto(scalar_msg: Scalar) -> typing.UserConfigValue:
     return cast(typing.UserConfigValue, scalar)
 
 
-# === Metadata messages ===
-
-
-def metadata_to_proto(metadata: Metadata) -> ProtoMetadata:
-    """Serialize `Metadata` to ProtoBuf."""
-    proto = ProtoMetadata(  # pylint: disable=E1101
-        run_id=metadata.run_id,
-        message_id=metadata.message_id,
-        src_node_id=metadata.src_node_id,
-        dst_node_id=metadata.dst_node_id,
-        reply_to_message_id=metadata.reply_to_message_id,
-        group_id=metadata.group_id,
-        ttl=metadata.ttl,
-        message_type=metadata.message_type,
-        created_at=metadata.created_at,
-    )
-    return proto
-
-
-def metadata_from_proto(metadata_proto: ProtoMetadata) -> Metadata:
-    """Deserialize `Metadata` from ProtoBuf."""
-    metadata = Metadata(
-        run_id=metadata_proto.run_id,
-        message_id=metadata_proto.message_id,
-        src_node_id=metadata_proto.src_node_id,
-        dst_node_id=metadata_proto.dst_node_id,
-        reply_to_message_id=metadata_proto.reply_to_message_id,
-        group_id=metadata_proto.group_id,
-        created_at=metadata_proto.created_at,
-        ttl=metadata_proto.ttl,
-        message_type=metadata_proto.message_type,
-    )
-    return metadata
-
-
 # === Message messages ===
 
 

flwr/common/serde_utils.py

@@ -20,6 +20,8 @@ from typing import Any, TypeVar, cast
 from google.protobuf.message import Message as GrpcMessage
 
 # pylint: disable=E0611
+from flwr.proto.error_pb2 import Error as ProtoError
+from flwr.proto.message_pb2 import Metadata as ProtoMetadata
 from flwr.proto.recorddict_pb2 import (
     BoolList,
     BytesList,
@@ -29,9 +31,13 @@ from flwr.proto.recorddict_pb2 import (
     UintList,
 )
 
+from ..app.error import Error
+from ..app.metadata import Metadata
 from .constant import INT64_MAX_VALUE
 from .record.typeddict import TypedDict
 
+# pylint: enable=E0611
+
 _type_to_field: dict[type, str] = {
     float: "double",
     int: "sint64",
@@ -121,3 +127,47 @@ def record_value_dict_from_proto(
 ) -> dict[str, Any]:
     """Deserialize the record value dict from ProtoBuf."""
     return {k: _record_value_from_proto(v) for k, v in value_dict_proto.items()}
+
+
+def error_to_proto(error: Error) -> ProtoError:
+    """Serialize Error to ProtoBuf."""
+    reason = error.reason if error.reason else ""
+    return ProtoError(code=error.code, reason=reason)
+
+
+def error_from_proto(error_proto: ProtoError) -> Error:
+    """Deserialize Error from ProtoBuf."""
+    reason = error_proto.reason if len(error_proto.reason) > 0 else None
+    return Error(code=error_proto.code, reason=reason)
+
+
+def metadata_to_proto(metadata: Metadata) -> ProtoMetadata:
+    """Serialize `Metadata` to ProtoBuf."""
+    proto = ProtoMetadata(  # pylint: disable=E1101
+        run_id=metadata.run_id,
+        message_id=metadata.message_id,
+        src_node_id=metadata.src_node_id,
+        dst_node_id=metadata.dst_node_id,
+        reply_to_message_id=metadata.reply_to_message_id,
+        group_id=metadata.group_id,
+        ttl=metadata.ttl,
+        message_type=metadata.message_type,
+        created_at=metadata.created_at,
+    )
+    return proto
+
+
+def metadata_from_proto(metadata_proto: ProtoMetadata) -> Metadata:
+    """Deserialize `Metadata` from ProtoBuf."""
+    metadata = Metadata(
+        run_id=metadata_proto.run_id,
+        message_id=metadata_proto.message_id,
+        src_node_id=metadata_proto.src_node_id,
+        dst_node_id=metadata_proto.dst_node_id,
+        reply_to_message_id=metadata_proto.reply_to_message_id,
+        group_id=metadata_proto.group_id,
+        created_at=metadata_proto.created_at,
+        ttl=metadata_proto.ttl,
+        message_type=metadata_proto.message_type,
+    )
+    return metadata

flwr/compat/__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.
+# ==============================================================================
+"""Compatibility package containing deprecated legacy components."""

flwr/compat/client/__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.
+# ==============================================================================
+"""Legacy components previously located in ``flwr.client``."""