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

flwr/common/record/metricrecord.py

@@ -15,12 +15,21 @@
 """MetricRecord."""
 
 
+from __future__ import annotations
+
 from logging import WARN
-from typing import Optional, get_args
+from typing import cast, get_args
 
 from flwr.common.typing import MetricRecordValues, MetricScalar
 
+# pylint: disable=E0611
+from flwr.proto.recorddict_pb2 import MetricRecord as ProtoMetricRecord
+from flwr.proto.recorddict_pb2 import MetricRecordValue as ProtoMetricRecordValue
+
+# pylint: enable=E0611
+from ..inflatable import InflatableObject, add_header_to_object_body, get_object_body
 from ..logger import log
+from ..serde_utils import record_value_dict_from_proto, record_value_dict_to_proto
 from .typeddict import TypedDict
 
 
@@ -59,8 +68,8 @@ def _check_value(value: MetricRecordValues) -> None:
         is_valid(value)
 
 
-class MetricRecord(TypedDict[str, MetricRecordValues]):
-    """Metrics recod.
+class MetricRecord(TypedDict[str, MetricRecordValues], InflatableObject):
+    """Metric record.
 
     A :code:`MetricRecord` is a Python dictionary designed to ensure that
     each key-value pair adheres to specified data types. A :code:`MetricRecord`
@@ -89,27 +98,27 @@ class MetricRecord(TypedDict[str, MetricRecordValues]):
     Common to these examples is that the output can be typically represented by
     a single scalar (:code:`int`, :code:`float`) or list of scalars.
 
-    Let's see some examples of how to construct a :code:`MetricRecord` from scratch:
+    Let's see some examples of how to construct a :code:`MetricRecord` from scratch::
+
+        from flwr.common import MetricRecord
 
-    >>> from flwr.common import MetricRecord
-    >>>
-    >>> # A `MetricRecord` is a specialized Python dictionary
-    >>> record = MetricRecord({"accuracy": 0.94})
-    >>> # You can add more content to an existing record
-    >>> record["loss"] = 0.01
-    >>> # It also supports lists
-    >>> record["loss-historic"] = [0.9, 0.5, 0.01]
+        # A `MetricRecord` is a specialized Python dictionary
+        record = MetricRecord({"accuracy": 0.94})
+        # You can add more content to an existing record
+        record["loss"] = 0.01
+        # It also supports lists
+        record["loss-historic"] = [0.9, 0.5, 0.01]
 
     Since types are enforced, the types of the objects inserted are checked. For a
     :code:`MetricRecord`, value types allowed are those in defined in
     :code:`flwr.common.MetricRecordValues`. Similarly, only :code:`str` keys are
-    allowed.
+    allowed::
 
-    >>> from flwr.common import MetricRecord
-    >>>
-    >>> record = MetricRecord() # an empty record
-    >>> # Add unsupported value
-    >>> record["something-unsupported"] = {'a': 123} # Will throw a `TypeError`
+        from flwr.common import MetricRecord
+
+        record = MetricRecord() # an empty record
+        # Add unsupported value
+        record["something-unsupported"] = {'a': 123} # Will throw a `TypeError`
 
     If you need a more versatily type of record try :code:`ConfigRecord` or
     :code:`ArrayRecord`.
@@ -117,7 +126,7 @@ class MetricRecord(TypedDict[str, MetricRecordValues]):
 
     def __init__(
         self,
-        metric_dict: Optional[dict[str, MetricRecordValues]] = None,
+        metric_dict: dict[str, MetricRecordValues] | None = None,
         keep_input: bool = True,
     ) -> None:
         super().__init__(_check_key, _check_value)
@@ -143,6 +152,48 @@ class MetricRecord(TypedDict[str, MetricRecordValues]):
             num_bytes += len(k)
         return num_bytes
 
+    def deflate(self) -> bytes:
+        """Deflate object."""
+        protos = record_value_dict_to_proto(self, [float, int], ProtoMetricRecordValue)
+        obj_body = ProtoMetricRecord(
+            items=[ProtoMetricRecord.Item(key=k, value=v) for k, v in protos.items()]
+        ).SerializeToString()
+        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
+    ) -> MetricRecord:
+        """Inflate a MetricRecord from bytes.
+
+        Parameters
+        ----------
+        object_content : bytes
+            The deflated object content of the MetricRecord.
+
+        children : Optional[dict[str, InflatableObject]] (default: None)
+            Must be ``None``. ``MetricRecord`` does not support child objects.
+            Providing any children will raise a ``ValueError``.
+
+        Returns
+        -------
+        MetricRecord
+            The inflated MetricRecord.
+        """
+        if children:
+            raise ValueError("`MetricRecord` objects do not have children.")
+
+        obj_body = get_object_body(object_content, cls)
+        metric_record_proto = ProtoMetricRecord.FromString(obj_body)
+        protos = {item.key: item.value for item in metric_record_proto.items}
+        return cls(
+            metric_dict=cast(
+                dict[str, MetricRecordValues],
+                record_value_dict_from_proto(protos),
+            ),
+            keep_input=False,
+        )
+
 
 class MetricsRecord(MetricRecord):
     """Deprecated class ``MetricsRecord``, use ``MetricRecord`` instead.
@@ -174,7 +225,7 @@ class MetricsRecord(MetricRecord):
 
     def __init__(
         self,
-        metric_dict: Optional[dict[str, MetricRecordValues]] = None,
+        metric_dict: dict[str, MetricRecordValues] | None = None,
         keep_input: bool = True,
     ):
         if not MetricsRecord._warning_logged:

flwr/common/record/recorddict.py

@@ -17,10 +17,12 @@
 
 from __future__ import annotations
 
+import json
 from logging import WARN
 from textwrap import indent
 from typing import TypeVar, Union, cast
 
+from ..inflatable import InflatableObject, add_header_to_object_body, get_object_body
 from ..logger import log
 from .arrayrecord import ArrayRecord
 from .configrecord import ConfigRecord
@@ -29,6 +31,22 @@ from .typeddict import TypedDict
 
 RecordType = Union[ArrayRecord, MetricRecord, ConfigRecord]
 
+
+class _WarningTracker:
+    """A class to track warnings for deprecated properties."""
+
+    def __init__(self) -> None:
+        # These variables are used to ensure that the deprecation warnings
+        # for the deprecated properties/class are logged only once.
+        self.recordset_init_logged = False
+        self.recorddict_init_logged = False
+        self.parameters_records_logged = False
+        self.metrics_records_logged = False
+        self.configs_records_logged = False
+
+
+_warning_tracker = _WarningTracker()
+
 T = TypeVar("T")
 
 
@@ -81,7 +99,7 @@ class _SyncedDict(TypedDict[str, T]):
             )
 
 
-class RecordDict(TypedDict[str, RecordType]):
+class RecordDict(TypedDict[str, RecordType], InflatableObject):
     """RecordDict stores groups of arrays, metrics and configs.
 
     A :class:`RecordDict` is the unified mechanism by which arrays,
@@ -103,48 +121,74 @@ class RecordDict(TypedDict[str, RecordType]):
     are Python dictionaries designed to ensure that each key-value pair
     adheres to specified data types.
 
-    Let's see an example.
-
-    >>>  from flwr.common import RecordDict
-    >>>  from flwr.common import ArrayRecord, ConfigRecord, MetricRecord
-    >>>
-    >>>  # Let's begin with an empty record
-    >>>  my_records = RecordDict()
-    >>>
-    >>>  # We can create a ConfigRecord
-    >>>  c_record = ConfigRecord({"lr": 0.1, "batch-size": 128})
-    >>>  # Adding it to the RecordDict would look like this
-    >>>  my_records["my_config"] = c_record
-    >>>
-    >>>  # We can create a MetricRecord following a similar process
-    >>>  m_record = MetricRecord({"accuracy": 0.93, "losses": [0.23, 0.1]})
-    >>>  # Adding it to the RecordDict would look like this
-    >>>  my_records["my_metrics"] = m_record
+    Let's see an example::
+
+        from flwr.common import RecordDict
+        from flwr.common import ArrayRecord, ConfigRecord, MetricRecord
+
+        # Let's begin with an empty record
+        my_records = RecordDict()
+
+        # We can create a ConfigRecord
+        c_record = ConfigRecord({"lr": 0.1, "batch-size": 128})
+        # Adding it to the RecordDict would look like this
+        my_records["my_config"] = c_record
+
+        # We can create a MetricRecord following a similar process
+        m_record = MetricRecord({"accuracy": 0.93, "losses": [0.23, 0.1]})
+        # Adding it to the RecordDict would look like this
+        my_records["my_metrics"] = m_record
 
     Adding an :code:`ArrayRecord` follows the same steps as above but first,
     the array needs to be serialized and represented as a :code:`flwr.common.Array`.
-    For example:
-
-    >>>  from flwr.common import Array
-    >>>  # Creating an ArrayRecord would look like this
-    >>>  arr_np = np.random.randn(3, 3)
-    >>>
-    >>>  # You can use the built-in tool to serialize the array
-    >>>  arr = Array(arr_np)
-    >>>
-    >>>  # Finally, create the record
-    >>>  arr_record = ArrayRecord({"my_array": arr})
-    >>>
-    >>>  # Adding it to the RecordDict would look like this
-    >>>  my_records["my_parameters"] = arr_record
+    For example::
+
+        from flwr.common import Array
+        # Creating an ArrayRecord would look like this
+        arr_np = np.random.randn(3, 3)
+
+        # You can use the built-in tool to serialize the array
+        arr = Array(arr_np)
+
+        # Finally, create the record
+        arr_record = ArrayRecord({"my_array": arr})
+
+        # Adding it to the RecordDict would look like this
+        my_records["my_parameters"] = arr_record
 
     For additional examples on how to construct each of the records types shown
     above, please refer to the documentation for :code:`ConfigRecord`,
     :code:`MetricRecord` and :code:`ArrayRecord`.
     """
 
-    def __init__(self, records: dict[str, RecordType] | None = None) -> None:
+    def __init__(
+        self,
+        records: dict[str, RecordType] | None = None,
+        *,
+        parameters_records: dict[str, ArrayRecord] | None = None,
+        metrics_records: dict[str, MetricRecord] | None = None,
+        configs_records: dict[str, ConfigRecord] | None = None,
+    ) -> None:
         super().__init__(_check_key, _check_value)
+
+        # Warning for deprecated usage
+        if (
+            parameters_records is not None
+            or metrics_records is not None
+            or configs_records is not None
+        ):
+            log(
+                WARN,
+                "The arguments `parameters_records`, `metrics_records`, and "
+                "`configs_records` of `RecordDict` are deprecated and will "
+                "be removed in a future release. "
+                "Please pass all records using the `records` argument instead.",
+            )
+            records = records or {}
+            records.update(parameters_records or {})
+            records.update(metrics_records or {})
+            records.update(configs_records or {})
+
         if records is not None:
             for key, record in records.items():
                 self[key] = record
@@ -196,6 +240,120 @@ class RecordDict(TypedDict[str, RecordType]):
                 type(value).__name__,
             )
 
+    @property
+    def parameters_records(self) -> TypedDict[str, ArrayRecord]:
+        """Deprecated property.
+
+        Use ``array_records`` instead.
+        """
+        if _warning_tracker.parameters_records_logged:
+            _warning_tracker.parameters_records_logged = True
+            log(
+                WARN,
+                "The `parameters_records` property of `RecordDict` "
+                "(formerly `RecordSet`) is deprecated and will be removed in a "
+                "future release. Please use the `array_records` property instead.",
+            )
+        return self.array_records
+
+    @property
+    def metrics_records(self) -> TypedDict[str, MetricRecord]:
+        """Deprecated property.
+
+        Use ``metric_records`` instead.
+        """
+        if not _warning_tracker.metrics_records_logged:
+            _warning_tracker.metrics_records_logged = True
+            log(
+                WARN,
+                "The `metrics_records` property of `RecordDict` "
+                "(formerly `RecordSet`) is deprecated and will be removed in a "
+                "future release. Please use the `metric_records` property instead.",
+            )
+        return self.metric_records
+
+    @property
+    def configs_records(self) -> TypedDict[str, ConfigRecord]:
+        """Deprecated property.
+
+        Use ``config_records`` instead.
+        """
+        if not _warning_tracker.configs_records_logged:
+            _warning_tracker.configs_records_logged = True
+            log(
+                WARN,
+                "The `configs_records` property of `RecordDict` "
+                "(formerly `RecordSet`) is deprecated and will be removed in a "
+                "future release. Please use the `config_records` property instead.",
+            )
+        return self.config_records
+
+    @property
+    def children(self) -> dict[str, InflatableObject]:
+        """Return a dictionary of records with their Object IDs as keys."""
+        return {record.object_id: record for record in self.values()}
+
+    def deflate(self) -> bytes:
+        """Deflate the RecordDict."""
+        # record_name: record_object_id mapping
+        record_refs: dict[str, str] = {}
+
+        for record_name, record in self.items():
+            record_refs[record_name] = record.object_id
+
+        # Serialize references dict
+        object_body = json.dumps(record_refs).encode("utf-8")
+        return add_header_to_object_body(object_body=object_body, obj=self)
+
+    @classmethod
+    def inflate(
+        cls, object_content: bytes, children: dict[str, InflatableObject] | None = None
+    ) -> RecordDict:
+        """Inflate an RecordDict from bytes.
+
+        Parameters
+        ----------
+        object_content : bytes
+            The deflated object content of the RecordDict.
+        children : Optional[dict[str, InflatableObject]]  (default: None)
+            Dictionary of children InflatableObjects mapped to their Object IDs.
+            These children enable the full inflation of the RecordDict. Default is None.
+
+        Returns
+        -------
+        RecordDict
+            The inflated RecordDict.
+        """
+        if children is None:
+            children = {}
+
+        # Inflate mapping of record_names (keys in the RecordDict) to Record' object IDs
+        obj_body = get_object_body(object_content, cls)
+        record_refs: dict[str, str] = json.loads(obj_body.decode(encoding="utf-8"))
+
+        unique_records = set(record_refs.values())
+        children_obj_ids = set(children.keys())
+        if unique_records != children_obj_ids:
+            raise ValueError(
+                "Unexpected set of `children`. "
+                f"Expected {unique_records} but got {children_obj_ids}."
+            )
+
+        # Ensure children are one of the *Record objects exepecte in a RecordDict
+        if not all(
+            isinstance(ch, (ArrayRecord, ConfigRecord, MetricRecord))
+            for ch in children.values()
+        ):
+            raise ValueError(
+                "`Children` are expected to be of type `ArrayRecord`, "
+                "`ConfigRecord` or `MetricRecord`."
+            )
+
+        # Instantiate new RecordDict
+        return RecordDict(
+            {name: children[object_id] for name, object_id in record_refs.items()}  # type: ignore
+        )
+
 
 class RecordSet(RecordDict):
     """Deprecated class ``RecordSet``, use ``RecordDict`` instead.
@@ -223,66 +381,25 @@ class RecordSet(RecordDict):
         my_content = RecordDict()
     """
 
-    _warning_logged = False
-    _warning_logged_params = False
-    _warning_logged_metrics = False
-    _warning_logged_configs = False
-
-    def __init__(self, records: dict[str, RecordType] | None = None) -> None:
-        if not RecordSet._warning_logged:
-            RecordSet._warning_logged = True
+    def __init__(
+        self,
+        records: dict[str, RecordType] | None = None,
+        *,
+        parameters_records: dict[str, ArrayRecord] | None = None,
+        metrics_records: dict[str, MetricRecord] | None = None,
+        configs_records: dict[str, ConfigRecord] | None = None,
+    ) -> None:
+        if not _warning_tracker.recordset_init_logged:
+            _warning_tracker.recordset_init_logged = True
             log(
                 WARN,
                 "The `RecordSet` class has been renamed to `RecordDict`. "
                 "Support for `RecordSet` will be removed in a future release. "
                 "Please update your code accordingly.",
             )
-        super().__init__(records)
-
-    @property
-    def parameters_records(self) -> TypedDict[str, ArrayRecord]:
-        """Deprecated property.
-
-        Use ``array_records`` instead.
-        """
-        if not RecordSet._warning_logged_params:
-            RecordSet._warning_logged_params = True
-            log(
-                WARN,
-                "`RecordSet.parameters_records` has been deprecated "
-                "and will be removed in a future release. Please use "
-                "`RecordDict.array_records` instead.",
-            )
-        return self.array_records
-
-    @property
-    def metrics_records(self) -> TypedDict[str, MetricRecord]:
-        """Deprecated property.
-
-        Use ``metric_records`` instead.
-        """
-        if not RecordSet._warning_logged_metrics:
-            RecordSet._warning_logged_metrics = True
-            log(
-                WARN,
-                "`RecordSet.metrics_records` has been deprecated "
-                "and will be removed in a future release. Please use "
-                "`RecordDict.metric_records` instead.",
-            )
-        return self.metric_records
-
-    @property
-    def configs_records(self) -> TypedDict[str, ConfigRecord]:
-        """Deprecated property.
-
-        Use ``config_records`` instead.
-        """
-        if not RecordSet._warning_logged_configs:
-            RecordSet._warning_logged_configs = True
-            log(
-                WARN,
-                "`RecordSet.configs_records` has been deprecated "
-                "and will be removed in a future release. Please use "
-                "`RecordDict.config_records` instead.",
-            )
-        return self.config_records
+        super().__init__(
+            records,
+            parameters_records=parameters_records,
+            metrics_records=metrics_records,
+            configs_records=configs_records,
+        )

flwr/common/record/typeddict.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/common/recorddict_compat.py

@@ -111,12 +111,12 @@ def parameters_to_arrayrecord(parameters: Parameters, keep_input: bool) -> Array
         else:
             tensor = parameters.tensors.pop(0)
         ordered_dict[str(idx)] = Array(
-            data=tensor, dtype="", stype=tensor_type, shape=[]
+            data=tensor, dtype="", stype=tensor_type, shape=()
         )
 
     if num_arrays == 0:
         ordered_dict[EMPTY_TENSOR_KEY] = Array(
-            data=b"", dtype="", stype=tensor_type, shape=[]
+            data=b"", dtype="", stype=tensor_type, shape=()
         )
     return ArrayRecord(ordered_dict, keep_input=keep_input)
 

flwr/common/retry_invoker.py

@@ -1,4 +1,4 @@
-# Copyright 2023 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.
@@ -25,10 +25,12 @@ from typing import Any, Callable, Optional, Union, cast
 
 import grpc
 
+from flwr.client.grpc_rere_client.grpc_adapter import GrpcAdapter
 from flwr.common.constant import MAX_RETRY_DELAY
 from flwr.common.logger import log
 from flwr.common.typing import RunNotRunningException
 from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
+from flwr.proto.fleet_pb2_grpc import FleetStub
 from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub
 from flwr.proto.simulationio_pb2_grpc import SimulationIoStub
 
@@ -166,15 +168,15 @@ class RetryInvoker:
 
     Examples
     --------
-    Initialize a `RetryInvoker` with exponential backoff and invoke a function:
-
-    >>> invoker = RetryInvoker(
-    ...     exponential,  # Or use `lambda: exponential(3, 2)` to pass arguments
-    ...     grpc.RpcError,
-    ...     max_tries=3,
-    ...     max_time=None,
-    ... )
-    >>> invoker.invoke(my_func, arg1, arg2, kw1=kwarg1)
+    Initialize a `RetryInvoker` with exponential backoff and invoke a function::
+
+        invoker = RetryInvoker(
+            exponential,  # Or use `lambda: exponential(3, 2)` to pass arguments
+            grpc.RpcError,
+            max_tries=3,
+            max_time=None,
+        )
+        invoker.invoke(my_func, arg1, arg2, kw1=kwarg1)
     """
 
     # pylint: disable-next=too-many-arguments
@@ -366,7 +368,9 @@ def _make_simple_grpc_retry_invoker() -> RetryInvoker:
 
 
 def _wrap_stub(
-    stub: Union[ServerAppIoStub, ClientAppIoStub, SimulationIoStub],
+    stub: Union[
+        ServerAppIoStub, ClientAppIoStub, SimulationIoStub, FleetStub, GrpcAdapter
+    ],
     retry_invoker: RetryInvoker,
 ) -> None:
     """Wrap a gRPC stub with a retry invoker."""

flwr/common/secure_aggregation/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023 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/common/secure_aggregation/crypto/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023 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.