flwr-nightly 1.8.0.dev20240315__py3-none-any.whl → 1.15.0.dev20250115__py3-none-any.whl

flwr/common/record/recordset.py

@@ -15,65 +15,188 @@
 """RecordSet."""
 
 
+from __future__ import annotations
+
 from dataclasses import dataclass
-from typing import Callable, Dict, Optional, Type, TypeVar
+from typing import cast
 
 from .configsrecord import ConfigsRecord
 from .metricsrecord import MetricsRecord
 from .parametersrecord import ParametersRecord
 from .typeddict import TypedDict
 
-T = TypeVar("T")
-
 
 @dataclass
-class RecordSet:
-    """RecordSet stores groups of parameters, metrics and configs."""
+class RecordSetData:
+    """Inner data container for the RecordSet class."""
 
-    _parameters_records: TypedDict[str, ParametersRecord]
-    _metrics_records: TypedDict[str, MetricsRecord]
-    _configs_records: TypedDict[str, ConfigsRecord]
+    parameters_records: TypedDict[str, ParametersRecord]
+    metrics_records: TypedDict[str, MetricsRecord]
+    configs_records: TypedDict[str, ConfigsRecord]
 
     def __init__(
         self,
-        parameters_records: Optional[Dict[str, ParametersRecord]] = None,
-        metrics_records: Optional[Dict[str, MetricsRecord]] = None,
-        configs_records: Optional[Dict[str, ConfigsRecord]] = None,
+        parameters_records: dict[str, ParametersRecord] | None = None,
+        metrics_records: dict[str, MetricsRecord] | None = None,
+        configs_records: dict[str, ConfigsRecord] | None = None,
     ) -> None:
-        def _get_check_fn(__t: Type[T]) -> Callable[[T], None]:
-            def _check_fn(__v: T) -> None:
-                if not isinstance(__v, __t):
-                    raise TypeError(f"Expected `{__t}`, but `{type(__v)}` was passed.")
-
-            return _check_fn
-
-        self._parameters_records = TypedDict[str, ParametersRecord](
-            _get_check_fn(str), _get_check_fn(ParametersRecord)
+        self.parameters_records = TypedDict[str, ParametersRecord](
+            self._check_fn_str, self._check_fn_params
         )
-        self._metrics_records = TypedDict[str, MetricsRecord](
-            _get_check_fn(str), _get_check_fn(MetricsRecord)
+        self.metrics_records = TypedDict[str, MetricsRecord](
+            self._check_fn_str, self._check_fn_metrics
         )
-        self._configs_records = TypedDict[str, ConfigsRecord](
-            _get_check_fn(str), _get_check_fn(ConfigsRecord)
+        self.configs_records = TypedDict[str, ConfigsRecord](
+            self._check_fn_str, self._check_fn_configs
         )
         if parameters_records is not None:
-            self._parameters_records.update(parameters_records)
+            self.parameters_records.update(parameters_records)
         if metrics_records is not None:
-            self._metrics_records.update(metrics_records)
+            self.metrics_records.update(metrics_records)
         if configs_records is not None:
-            self._configs_records.update(configs_records)
+            self.configs_records.update(configs_records)
+
+    def _check_fn_str(self, key: str) -> None:
+        if not isinstance(key, str):
+            raise TypeError(
+                f"Expected `{str.__name__}`, but "
+                f"received `{type(key).__name__}` for the key."
+            )
+
+    def _check_fn_params(self, record: ParametersRecord) -> None:
+        if not isinstance(record, ParametersRecord):
+            raise TypeError(
+                f"Expected `{ParametersRecord.__name__}`, but "
+                f"received `{type(record).__name__}` for the value."
+            )
+
+    def _check_fn_metrics(self, record: MetricsRecord) -> None:
+        if not isinstance(record, MetricsRecord):
+            raise TypeError(
+                f"Expected `{MetricsRecord.__name__}`, but "
+                f"received `{type(record).__name__}` for the value."
+            )
+
+    def _check_fn_configs(self, record: ConfigsRecord) -> None:
+        if not isinstance(record, ConfigsRecord):
+            raise TypeError(
+                f"Expected `{ConfigsRecord.__name__}`, but "
+                f"received `{type(record).__name__}` for the value."
+            )
+
+
+class RecordSet:
+    """RecordSet stores groups of parameters, metrics and configs.
+
+    A :code:`RecordSet` is the unified mechanism by which parameters,
+    metrics and configs can be either stored as part of a
+    `flwr.common.Context <flwr.common.Context.html>`_ in your apps
+    or communicated as part of a
+    `flwr.common.Message <flwr.common.Message.html>`_ between your apps.
+
+    Parameters
+    ----------
+    parameters_records : Optional[Dict[str, ParametersRecord]]
+        A dictionary of :code:`ParametersRecords` that can be used to record
+        and communicate model parameters and high-dimensional arrays.
+    metrics_records : Optional[Dict[str, MetricsRecord]]
+        A dictionary of :code:`MetricsRecord` that can be used to record
+        and communicate scalar-valued metrics that are the result of performing
+        and action, for example, by a :code:`ClientApp`.
+    configs_records : Optional[Dict[str, ConfigsRecord]]
+        A dictionary of :code:`ConfigsRecord` that can be used to record
+        and communicate configuration values to an entity (e.g. to a
+        :code:`ClientApp`)
+        for it to adjust how an action is performed.
+
+    Examples
+    --------
+    A :code:`RecordSet` can hold three types of records, each designed
+    with an specific purpose. What is common to all of them is that they
+    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 RecordSet
+    >>>  from flwr.common import ConfigsRecord, MetricsRecord, ParametersRecord
+    >>>
+    >>>  # Let's begin with an empty record
+    >>>  my_recordset = RecordSet()
+    >>>
+    >>>  # We can create a ConfigsRecord
+    >>>  c_record = ConfigsRecord({"lr": 0.1, "batch-size": 128})
+    >>>  # Adding it to the record_set would look like this
+    >>>  my_recordset.configs_records["my_config"] = c_record
+    >>>
+    >>>  # We can create a MetricsRecord following a similar process
+    >>>  m_record = MetricsRecord({"accuracy": 0.93, "losses": [0.23, 0.1]})
+    >>>  # Adding it to the record_set would look like this
+    >>>  my_recordset.metrics_records["my_metrics"] = m_record
+
+    Adding a :code:`ParametersRecord` follows the same steps as above but first,
+    the array needs to be serialized and represented as a :code:`flwr.common.Array`.
+    If the array is a :code:`NumPy` array, you can use the built-in utility function
+    `array_from_numpy <flwr.common.array_from_numpy.html>`_. It is often possible to
+    convert an array first to :code:`NumPy` and then use the aforementioned function.
+
+    >>>  from flwr.common import array_from_numpy
+    >>>  # Creating a ParametersRecord would look like this
+    >>>  arr_np = np.random.randn(3, 3)
+    >>>
+    >>>  # You can use the built-in tool to serialize the array
+    >>>  arr = array_from_numpy(arr_np)
+    >>>
+    >>>  # Finally, create the record
+    >>>  p_record = ParametersRecord({"my_array": arr})
+    >>>
+    >>>  # Adding it to the record_set would look like this
+    >>>  my_recordset.parameters_records["my_parameters"] = p_record
+
+    For additional examples on how to construct each of the records types shown
+    above, please refer to the documentation for :code:`ConfigsRecord`,
+    :code:`MetricsRecord` and :code:`ParametersRecord`.
+    """
+
+    def __init__(
+        self,
+        parameters_records: dict[str, ParametersRecord] | None = None,
+        metrics_records: dict[str, MetricsRecord] | None = None,
+        configs_records: dict[str, ConfigsRecord] | None = None,
+    ) -> None:
+        data = RecordSetData(
+            parameters_records=parameters_records,
+            metrics_records=metrics_records,
+            configs_records=configs_records,
+        )
+        self.__dict__["_data"] = data
 
     @property
     def parameters_records(self) -> TypedDict[str, ParametersRecord]:
         """Dictionary holding ParametersRecord instances."""
-        return self._parameters_records
+        data = cast(RecordSetData, self.__dict__["_data"])
+        return data.parameters_records
 
     @property
     def metrics_records(self) -> TypedDict[str, MetricsRecord]:
         """Dictionary holding MetricsRecord instances."""
-        return self._metrics_records
+        data = cast(RecordSetData, self.__dict__["_data"])
+        return data.metrics_records
 
     @property
     def configs_records(self) -> TypedDict[str, ConfigsRecord]:
         """Dictionary holding ConfigsRecord instances."""
-        return self._configs_records
+        data = cast(RecordSetData, self.__dict__["_data"])
+        return data.configs_records
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        flds = ("parameters_records", "metrics_records", "configs_records")
+        view = ", ".join([f"{fld}={getattr(self, fld)!r}" for fld in flds])
+        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/common/record/typeddict.py

@@ -15,99 +15,74 @@
 """Typed dict base class for *Records."""
 
 
-from typing import Any, Callable, Dict, Generic, Iterator, Tuple, TypeVar, cast
+from collections.abc import ItemsView, Iterator, KeysView, MutableMapping, ValuesView
+from typing import Callable, Generic, TypeVar, cast
 
 K = TypeVar("K")  # Key type
 V = TypeVar("V")  # Value type
 
 
-class TypedDict(Generic[K, V]):
+class TypedDict(MutableMapping[K, V], Generic[K, V]):
     """Typed dictionary."""
 
     def __init__(
         self, check_key_fn: Callable[[K], None], check_value_fn: Callable[[V], None]
     ):
-        self._data: Dict[K, V] = {}
-        self._check_key_fn = check_key_fn
-        self._check_value_fn = check_value_fn
+        self.__dict__["_check_key_fn"] = check_key_fn
+        self.__dict__["_check_value_fn"] = check_value_fn
+        self.__dict__["_data"] = {}
 
     def __setitem__(self, key: K, value: V) -> None:
         """Set the given key to the given value after type checking."""
         # Check the types of key and value
-        self._check_key_fn(key)
-        self._check_value_fn(value)
+        cast(Callable[[K], None], self.__dict__["_check_key_fn"])(key)
+        cast(Callable[[V], None], self.__dict__["_check_value_fn"])(value)
+
         # Set key-value pair
-        self._data[key] = value
+        cast(dict[K, V], self.__dict__["_data"])[key] = value
 
     def __delitem__(self, key: K) -> None:
         """Remove the item with the specified key."""
-        del self._data[key]
+        del cast(dict[K, V], self.__dict__["_data"])[key]
 
     def __getitem__(self, item: K) -> V:
         """Return the value for the specified key."""
-        return self._data[item]
+        return cast(dict[K, V], self.__dict__["_data"])[item]
 
     def __iter__(self) -> Iterator[K]:
         """Yield an iterator over the keys of the dictionary."""
-        return iter(self._data)
+        return iter(cast(dict[K, V], self.__dict__["_data"]))
 
     def __repr__(self) -> str:
         """Return a string representation of the dictionary."""
-        return self._data.__repr__()
+        return cast(dict[K, V], self.__dict__["_data"]).__repr__()
 
     def __len__(self) -> int:
         """Return the number of items in the dictionary."""
-        return len(self._data)
+        return len(cast(dict[K, V], self.__dict__["_data"]))
 
-    def __contains__(self, key: K) -> bool:
+    def __contains__(self, key: object) -> bool:
         """Check if the dictionary contains the specified key."""
-        return key in self._data
+        return key in cast(dict[K, V], self.__dict__["_data"])
 
     def __eq__(self, other: object) -> bool:
         """Compare this instance to another dictionary or TypedDict."""
+        data = cast(dict[K, V], self.__dict__["_data"])
         if isinstance(other, TypedDict):
-            return self._data == other._data
+            other_data = cast(dict[K, V], other.__dict__["_data"])
+            return data == other_data
         if isinstance(other, dict):
-            return self._data == other
+            return data == other
         return NotImplemented
 
-    def items(self) -> Iterator[Tuple[K, V]]:
-        """R.items() -> a set-like object providing a view on R's items."""
-        return cast(Iterator[Tuple[K, V]], self._data.items())
-
-    def keys(self) -> Iterator[K]:
-        """R.keys() -> a set-like object providing a view on R's keys."""
-        return cast(Iterator[K], self._data.keys())
-
-    def values(self) -> Iterator[V]:
-        """R.values() -> an object providing a view on R's values."""
-        return cast(Iterator[V], self._data.values())
-
-    def update(self, *args: Any, **kwargs: Any) -> None:
-        """R.update([E, ]**F) -> None.
-
-        Update R from dict/iterable E and F.
-        """
-        for key, value in dict(*args, **kwargs).items():
-            self[key] = value
-
-    def pop(self, key: K) -> V:
-        """R.pop(k[,d]) -> v, remove specified key and return the corresponding value.
-
-        If key is not found, d is returned if given, otherwise KeyError is raised.
-        """
-        return self._data.pop(key)
-
-    def get(self, key: K, default: V) -> V:
-        """R.get(k[,d]) -> R[k] if k in R, else d.
-
-        d defaults to None.
-        """
-        return self._data.get(key, default)
+    def keys(self) -> KeysView[K]:
+        """D.keys() -> a set-like object providing a view on D's keys."""
+        return cast(dict[K, V], self.__dict__["_data"]).keys()
 
-    def clear(self) -> None:
-        """R.clear() -> None.
+    def values(self) -> ValuesView[V]:
+        """D.values() -> an object providing a view on D's values."""
+        return cast(dict[K, V], self.__dict__["_data"]).values()
 
-        Remove all items from R.
-        """
-        self._data.clear()
+    def items(self) -> ItemsView[K, V]:
+        """D.items() -> a set-like object providing a view on D's items."""
+        return cast(dict[K, V], self.__dict__["_data"]).items()

flwr/common/recordset_compat.py

@@ -15,7 +15,9 @@
 """RecordSet utilities."""
 
 
-from typing import Dict, Mapping, OrderedDict, Tuple, Union, cast, get_args
+from collections import OrderedDict
+from collections.abc import Mapping
+from typing import Union, cast, get_args
 
 from . import Array, ConfigsRecord, MetricsRecord, ParametersRecord, RecordSet
 from .typing import (
@@ -35,6 +37,8 @@ from .typing import (
     Status,
 )
 
+EMPTY_TENSOR_KEY = "_empty"
+
 
 def parametersrecord_to_parameters(
     record: ParametersRecord, keep_input: bool
@@ -55,11 +59,17 @@ def parametersrecord_to_parameters(
     keep_input : bool
         A boolean indicating whether entries in the record should be deleted from the
         input dictionary immediately after adding them to the record.
+
+    Returns
+    -------
+    parameters : Parameters
+        The parameters in the legacy format Parameters.
     """
     parameters = Parameters(tensors=[], tensor_type="")
 
     for key in list(record.keys()):
-        parameters.tensors.append(record[key].data)
+        if key != EMPTY_TENSOR_KEY:
+            parameters.tensors.append(record[key].data)
 
         if not parameters.tensor_type:
             # Setting from first array in record. Recall the warning in the docstrings
@@ -89,6 +99,11 @@ def parameters_to_parametersrecord(
         A boolean indicating whether parameters should be deleted from the input
         Parameters object (i.e. a list of serialized NumPy arrays) immediately after
         adding them to the record.
+
+    Returns
+    -------
+    ParametersRecord
+        The ParametersRecord containing the provided parameters.
     """
     tensor_type = parameters.tensor_type
 
@@ -103,12 +118,16 @@ def parameters_to_parametersrecord(
             data=tensor, dtype="", stype=tensor_type, shape=[]
         )
 
+    if num_arrays == 0:
+        ordered_dict[EMPTY_TENSOR_KEY] = Array(
+            data=b"", dtype="", stype=tensor_type, shape=[]
+        )
     return ParametersRecord(ordered_dict, keep_input=keep_input)
 
 
 def _check_mapping_from_recordscalartype_to_scalar(
     record_data: Mapping[str, Union[ConfigsRecordValues, MetricsRecordValues]]
-) -> Dict[str, Scalar]:
+) -> dict[str, Scalar]:
     """Check mapping `common.*RecordValues` into `common.Scalar` is possible."""
     for value in record_data.values():
         if not isinstance(value, get_args(Scalar)):
@@ -119,14 +138,14 @@ def _check_mapping_from_recordscalartype_to_scalar(
                 "supported by the `common.RecordSet` infrastructure. "
                 f"You used type: {type(value)}"
             )
-    return cast(Dict[str, Scalar], record_data)
+    return cast(dict[str, Scalar], record_data)
 
 
 def _recordset_to_fit_or_evaluate_ins_components(
     recordset: RecordSet,
     ins_str: str,
     keep_input: bool,
-) -> Tuple[Parameters, Dict[str, Scalar]]:
+) -> tuple[Parameters, dict[str, Scalar]]:
     """Derive Fit/Evaluate Ins from a RecordSet."""
     # get Array and construct Parameters
     parameters_record = recordset.parameters_records[f"{ins_str}.parameters"]
@@ -138,7 +157,7 @@ def _recordset_to_fit_or_evaluate_ins_components(
     # get config dict
     config_record = recordset.configs_records[f"{ins_str}.config"]
     # pylint: disable-next=protected-access
-    config_dict = _check_mapping_from_recordscalartype_to_scalar(config_record._data)
+    config_dict = _check_mapping_from_recordscalartype_to_scalar(config_record)
 
     return parameters, config_dict
 
@@ -162,7 +181,7 @@ def _fit_or_evaluate_ins_to_recordset(
 def _embed_status_into_recordset(
     res_str: str, status: Status, recordset: RecordSet
 ) -> RecordSet:
-    status_dict: Dict[str, ConfigsRecordValues] = {
+    status_dict: dict[str, ConfigsRecordValues] = {
         "code": int(status.code.value),
         "message": status.message,
     }
@@ -206,7 +225,7 @@ def recordset_to_fitres(recordset: RecordSet, keep_input: bool) -> FitRes:
     )
     configs_record = recordset.configs_records[f"{ins_str}.metrics"]
     # pylint: disable-next=protected-access
-    metrics = _check_mapping_from_recordscalartype_to_scalar(configs_record._data)
+    metrics = _check_mapping_from_recordscalartype_to_scalar(configs_record)
     status = _extract_status_from_recordset(ins_str, recordset)
 
     return FitRes(
@@ -267,7 +286,7 @@ def recordset_to_evaluateres(recordset: RecordSet) -> EvaluateRes:
     configs_record = recordset.configs_records[f"{ins_str}.metrics"]
 
     # pylint: disable-next=protected-access
-    metrics = _check_mapping_from_recordscalartype_to_scalar(configs_record._data)
+    metrics = _check_mapping_from_recordscalartype_to_scalar(configs_record)
     status = _extract_status_from_recordset(ins_str, recordset)
 
     return EvaluateRes(
@@ -307,7 +326,7 @@ def recordset_to_getparametersins(recordset: RecordSet) -> GetParametersIns:
     """Derive GetParametersIns from a RecordSet object."""
     config_record = recordset.configs_records["getparametersins.config"]
     # pylint: disable-next=protected-access
-    config_dict = _check_mapping_from_recordscalartype_to_scalar(config_record._data)
+    config_dict = _check_mapping_from_recordscalartype_to_scalar(config_record)
 
     return GetParametersIns(config=config_dict)
 
@@ -358,7 +377,7 @@ def recordset_to_getpropertiesins(recordset: RecordSet) -> GetPropertiesIns:
     """Derive GetPropertiesIns from a RecordSet object."""
     config_record = recordset.configs_records["getpropertiesins.config"]
     # pylint: disable-next=protected-access
-    config_dict = _check_mapping_from_recordscalartype_to_scalar(config_record._data)
+    config_dict = _check_mapping_from_recordscalartype_to_scalar(config_record)
 
     return GetPropertiesIns(config=config_dict)
 
@@ -377,7 +396,7 @@ def recordset_to_getpropertiesres(recordset: RecordSet) -> GetPropertiesRes:
     res_str = "getpropertiesres"
     config_record = recordset.configs_records[f"{res_str}.properties"]
     # pylint: disable-next=protected-access
-    properties = _check_mapping_from_recordscalartype_to_scalar(config_record._data)
+    properties = _check_mapping_from_recordscalartype_to_scalar(config_record)
 
     status = _extract_status_from_recordset(res_str, recordset=recordset)