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

flwr/common/record/{configsrecord.py → configrecord.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.
@@ -12,13 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""ConfigsRecord."""
+"""ConfigRecord."""
 
 
+from logging import WARN
 from typing import Optional, get_args
 
-from flwr.common.typing import ConfigsRecordValues, ConfigsScalar
+from flwr.common.typing import ConfigRecordValues, ConfigScalar
 
+from ..logger import log
 from .typeddict import TypedDict
 
 
@@ -28,20 +30,20 @@ def _check_key(key: str) -> None:
         raise TypeError(f"Key must be of type `str` but `{type(key)}` was passed.")
 
 
-def _check_value(value: ConfigsRecordValues) -> None:
-    def is_valid(__v: ConfigsScalar) -> None:
+def _check_value(value: ConfigRecordValues) -> None:
+    def is_valid(__v: ConfigScalar) -> None:
         """Check if value is of expected type."""
-        if not isinstance(__v, get_args(ConfigsScalar)):
+        if not isinstance(__v, get_args(ConfigScalar)):
             raise TypeError(
                 "Not all values are of valid type."
-                f" Expected `{ConfigsRecordValues}` but `{type(__v)}` was passed."
+                f" Expected `{ConfigRecordValues}` but `{type(__v)}` was passed."
             )
 
     if isinstance(value, list):
         # If your lists are large (e.g. 1M+ elements) this will be slow
         # 1s to check 10M element list on a M2 Pro
         # In such settings, you'd be better of treating such config as
-        # an array and pass it to a ParametersRecord.
+        # an array and pass it to a ArrayRecord.
         # Empty lists are valid
         if len(value) > 0:
             is_valid(value[0])
@@ -51,24 +53,24 @@ def _check_value(value: ConfigsRecordValues) -> None:
             if not all(isinstance(v, value_type) for v in value):
                 raise TypeError(
                     "All values in a list must be of the same valid type. "
-                    f"One of {ConfigsScalar}."
+                    f"One of {ConfigScalar}."
                 )
     else:
         is_valid(value)
 
 
-class ConfigsRecord(TypedDict[str, ConfigsRecordValues]):
+class ConfigRecord(TypedDict[str, ConfigRecordValues]):
     """Configs record.
 
-    A :code:`ConfigsRecord` is a Python dictionary designed to ensure that
-    each key-value pair adheres to specified data types. A :code:`ConfigsRecord`
+    A :code:`ConfigRecord` is a Python dictionary designed to ensure that
+    each key-value pair adheres to specified data types. A :code:`ConfigRecord`
     is one of the types of records that a
-    `flwr.common.RecordSet <flwr.common.RecordSet.html#recordset>`_ supports and
+    `flwr.common.RecordDict <flwr.common.RecordDict.html#recorddict>`_ supports and
     can therefore be used to construct :code:`common.Message` objects.
 
     Parameters
     ----------
-    configs_dict : Optional[Dict[str, ConfigsRecordValues]]
+    config_dict : Optional[Dict[str, ConfigRecordValues]]
         A dictionary that stores basic types (i.e. `str`, `int`, `float`, `bytes` as
         defined in `ConfigsScalar`) and lists of such types (see
         `ConfigsScalarList`).
@@ -80,20 +82,20 @@ class ConfigsRecord(TypedDict[str, ConfigsRecordValues]):
 
     Examples
     --------
-    The usage of a :code:`ConfigsRecord` is envisioned for sending configuration values
+    The usage of a :code:`ConfigRecord` is envisioned for sending configuration values
     telling the target node how to perform a certain action (e.g. train/evaluate a model
     ). You can use standard Python built-in types such as :code:`float`, :code:`str`
     , :code:`bytes`. All types allowed are defined in
-    :code:`flwr.common.ConfigsRecordValues`. While lists are supported, we
-    encourage you to use a :code:`ParametersRecord` instead if these are of high
+    :code:`flwr.common.ConfigRecordValues`. While lists are supported, we
+    encourage you to use a :code:`ArrayRecord` instead if these are of high
     dimensionality.
 
-    Let's see some examples of how to construct a :code:`ConfigsRecord` from scratch:
+    Let's see some examples of how to construct a :code:`ConfigRecord` from scratch:
 
-    >>> from flwr.common import ConfigsRecord
+    >>> from flwr.common import ConfigRecord
     >>>
-    >>> # A `ConfigsRecord` is a specialized Python dictionary
-    >>> record = ConfigsRecord({"lr": 0.1, "batch-size": 128})
+    >>> # A `ConfigRecord` is a specialized Python dictionary
+    >>> record = ConfigRecord({"lr": 0.1, "batch-size": 128})
     >>> # You can add more content to an existing record
     >>> record["compute-average"] = True
     >>> # It also supports lists
@@ -101,24 +103,24 @@ class ConfigsRecord(TypedDict[str, ConfigsRecordValues]):
     >>> # And string values (among other types)
     >>> record["path-to-S3"] = "s3://bucket_name/folder1/fileA.json"
 
-    Just like the other types of records in a :code:`flwr.common.RecordSet`, types are
+    Just like the other types of records in a :code:`flwr.common.RecordDict`, types are
     enforced. If you need to add a custom data structure or object, we recommend to
     serialise it into bytes and save it as such (bytes are allowed in a
-    :code:`ConfigsRecord`)
+    :code:`ConfigRecord`)
     """
 
     def __init__(
         self,
-        configs_dict: Optional[dict[str, ConfigsRecordValues]] = None,
+        config_dict: Optional[dict[str, ConfigRecordValues]] = None,
         keep_input: bool = True,
     ) -> None:
 
         super().__init__(_check_key, _check_value)
-        if configs_dict:
-            for k in list(configs_dict.keys()):
-                self[k] = configs_dict[k]
+        if config_dict:
+            for k in list(config_dict.keys()):
+                self[k] = config_dict[k]
                 if not keep_input:
-                    del configs_dict[k]
+                    del config_dict[k]
 
     def count_bytes(self) -> int:
         """Return number of Bytes stored in this object.
@@ -126,7 +128,7 @@ class ConfigsRecord(TypedDict[str, ConfigsRecordValues]):
         This function counts booleans as occupying 1 Byte.
         """
 
-        def get_var_bytes(value: ConfigsScalar) -> int:
+        def get_var_bytes(value: ConfigScalar) -> int:
             """Return Bytes of value passed."""
             var_bytes = 0
             if isinstance(value, bool):
@@ -161,3 +163,47 @@ class ConfigsRecord(TypedDict[str, ConfigsRecordValues]):
             num_bytes += len(k)
 
         return num_bytes
+
+
+class ConfigsRecord(ConfigRecord):
+    """Deprecated class ``ConfigsRecord``, use ``ConfigRecord`` instead.
+
+    This class exists solely for backward compatibility with legacy
+    code that previously used ``ConfigsRecord``. It has been renamed
+    to ``ConfigRecord``.
+
+    .. warning::
+        ``ConfigsRecord`` is deprecated and will be removed in a future release.
+        Use ``ConfigRecord`` instead.
+
+    Examples
+    --------
+    Legacy (deprecated) usage::
+
+        from flwr.common import ConfigsRecord
+
+        record = ConfigsRecord()
+
+    Updated usage::
+
+        from flwr.common import ConfigRecord
+
+        record = ConfigRecord()
+    """
+
+    _warning_logged = False
+
+    def __init__(
+        self,
+        config_dict: Optional[dict[str, ConfigRecordValues]] = None,
+        keep_input: bool = True,
+    ):
+        if not ConfigsRecord._warning_logged:
+            ConfigsRecord._warning_logged = True
+            log(
+                WARN,
+                "The `ConfigsRecord` class has been renamed to `ConfigRecord`. "
+                "Support for `ConfigsRecord` will be removed in a future release. "
+                "Please update your code accordingly.",
+            )
+        super().__init__(config_dict, keep_input)

flwr/common/record/conversion_utils.py

@@ -15,26 +15,17 @@
 """Conversion utility functions for Records."""
 
 
-from io import BytesIO
-
-import numpy as np
-
-from ..constant import SType
+from ..logger import warn_deprecated_feature
 from ..typing import NDArray
-from .parametersrecord import Array
+from .arrayrecord import Array
+
+WARN_DEPRECATED_MESSAGE = (
+    "`array_from_numpy` is deprecated. Instead, use the `Array(ndarray)` class "
+    "directly or `Array.from_numpy_ndarray(ndarray)`."
+)
 
 
 def array_from_numpy(ndarray: NDArray) -> Array:
     """Create Array from NumPy ndarray."""
-    buffer = BytesIO()
-    # WARNING: NEVER set allow_pickle to true.
-    # Reason: loading pickled data can execute arbitrary code
-    # Source: https://numpy.org/doc/stable/reference/generated/numpy.save.html
-    np.save(buffer, ndarray, allow_pickle=False)
-    data = buffer.getvalue()
-    return Array(
-        dtype=str(ndarray.dtype),
-        shape=list(ndarray.shape),
-        stype=SType.NUMPY,
-        data=data,
-    )
+    warn_deprecated_feature(WARN_DEPRECATED_MESSAGE)
+    return Array.from_numpy_ndarray(ndarray)

flwr/common/record/{metricsrecord.py → metricrecord.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.
@@ -12,13 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""MetricsRecord."""
+"""MetricRecord."""
 
 
+from logging import WARN
 from typing import Optional, get_args
 
-from flwr.common.typing import MetricsRecordValues, MetricsScalar
+from flwr.common.typing import MetricRecordValues, MetricScalar
 
+from ..logger import log
 from .typeddict import TypedDict
 
 
@@ -28,20 +30,20 @@ def _check_key(key: str) -> None:
         raise TypeError(f"Key must be of type `str` but `{type(key)}` was passed.")
 
 
-def _check_value(value: MetricsRecordValues) -> None:
-    def is_valid(__v: MetricsScalar) -> None:
+def _check_value(value: MetricRecordValues) -> None:
+    def is_valid(__v: MetricScalar) -> None:
         """Check if value is of expected type."""
-        if not isinstance(__v, get_args(MetricsScalar)) or isinstance(__v, bool):
+        if not isinstance(__v, get_args(MetricScalar)) or isinstance(__v, bool):
             raise TypeError(
                 "Not all values are of valid type."
-                f" Expected `{MetricsRecordValues}` but `{type(__v)}` was passed."
+                f" Expected `{MetricRecordValues}` but `{type(__v)}` was passed."
             )
 
     if isinstance(value, list):
         # If your lists are large (e.g. 1M+ elements) this will be slow
         # 1s to check 10M element list on a M2 Pro
         # In such settings, you'd be better of treating such metric as
-        # an array and pass it to a ParametersRecord.
+        # an array and pass it to an ArrayRecord.
         # Empty lists are valid
         if len(value) > 0:
             is_valid(value[0])
@@ -51,26 +53,26 @@ def _check_value(value: MetricsRecordValues) -> None:
             if not all(isinstance(v, value_type) for v in value):
                 raise TypeError(
                     "All values in a list must be of the same valid type. "
-                    f"One of {MetricsScalar}."
+                    f"One of {MetricScalar}."
                 )
     else:
         is_valid(value)
 
 
-class MetricsRecord(TypedDict[str, MetricsRecordValues]):
+class MetricRecord(TypedDict[str, MetricRecordValues]):
     """Metrics recod.
 
-    A :code:`MetricsRecord` is a Python dictionary designed to ensure that
-    each key-value pair adheres to specified data types. A :code:`MetricsRecord`
+    A :code:`MetricRecord` is a Python dictionary designed to ensure that
+    each key-value pair adheres to specified data types. A :code:`MetricRecord`
     is one of the types of records that a
-    `flwr.common.RecordSet <flwr.common.RecordSet.html#recordset>`_ supports and
+    `flwr.common.RecordDict <flwr.common.RecordDict.html#recorddict>`_ supports and
     can therefore be used to construct :code:`common.Message` objects.
 
     Parameters
     ----------
-    metrics_dict : Optional[Dict[str, MetricsRecordValues]]
+    metric_dict : Optional[Dict[str, MetricRecordValues]]
         A dictionary that stores basic types (i.e. `int`, `float` as defined
-        in `MetricsScalar`) and list of such types (see `MetricsScalarList`).
+        in `MetricScalar`) and list of such types (see `MetricScalarList`).
     keep_input : bool (default: True)
         A boolean indicating whether metrics should be deleted from the input
         dictionary immediately after adding them to the record. When set
@@ -79,7 +81,7 @@ class MetricsRecord(TypedDict[str, MetricsRecordValues]):
 
     Examples
     --------
-    The usage of a :code:`MetricsRecord` is envisioned for communicating results
+    The usage of a :code:`MetricRecord` is envisioned for communicating results
     obtained when a node performs an action. A few typical examples include:
     communicating the training accuracy after a model is trained locally by a
     :code:`ClientApp`, reporting the validation loss obtained at a :code:`ClientApp`,
@@ -87,43 +89,43 @@ class MetricsRecord(TypedDict[str, MetricsRecordValues]):
     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:`MetricsRecord` from scratch:
+    Let's see some examples of how to construct a :code:`MetricRecord` from scratch:
 
-    >>> from flwr.common import MetricsRecord
+    >>> from flwr.common import MetricRecord
     >>>
-    >>> # A `MetricsRecord` is a specialized Python dictionary
-    >>> record = MetricsRecord({"accuracy": 0.94})
+    >>> # 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:`MetricsRecord`, value types allowed are those in defined in
-    :code:`flwr.common.MetricsRecordValues`. Similarly, only :code:`str` keys are
+    :code:`MetricRecord`, value types allowed are those in defined in
+    :code:`flwr.common.MetricRecordValues`. Similarly, only :code:`str` keys are
     allowed.
 
-    >>> from flwr.common import MetricsRecord
+    >>> from flwr.common import MetricRecord
     >>>
-    >>> record = MetricsRecord() # an empty record
+    >>> 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:`ConfigsRecord` or
-    :code:`ParametersRecord`.
+    If you need a more versatily type of record try :code:`ConfigRecord` or
+    :code:`ArrayRecord`.
     """
 
     def __init__(
         self,
-        metrics_dict: Optional[dict[str, MetricsRecordValues]] = None,
+        metric_dict: Optional[dict[str, MetricRecordValues]] = None,
         keep_input: bool = True,
-    ):
+    ) -> None:
         super().__init__(_check_key, _check_value)
-        if metrics_dict:
-            for k in list(metrics_dict.keys()):
-                self[k] = metrics_dict[k]
+        if metric_dict:
+            for k in list(metric_dict.keys()):
+                self[k] = metric_dict[k]
                 if not keep_input:
-                    del metrics_dict[k]
+                    del metric_dict[k]
 
     def count_bytes(self) -> int:
         """Return number of Bytes stored in this object."""
@@ -140,3 +142,47 @@ class MetricsRecord(TypedDict[str, MetricsRecordValues]):
             # We also count the bytes footprint of the keys
             num_bytes += len(k)
         return num_bytes
+
+
+class MetricsRecord(MetricRecord):
+    """Deprecated class ``MetricsRecord``, use ``MetricRecord`` instead.
+
+    This class exists solely for backward compatibility with legacy
+    code that previously used ``MetricsRecord``. It has been renamed
+    to ``MetricRecord``.
+
+    .. warning::
+        ``MetricsRecord`` is deprecated and will be removed in a future release.
+        Use ``MetricRecord`` instead.
+
+    Examples
+    --------
+    Legacy (deprecated) usage::
+
+        from flwr.common import MetricsRecord
+
+        record = MetricsRecord()
+
+    Updated usage::
+
+        from flwr.common import MetricRecord
+
+        record = MetricRecord()
+    """
+
+    _warning_logged = False
+
+    def __init__(
+        self,
+        metric_dict: Optional[dict[str, MetricRecordValues]] = None,
+        keep_input: bool = True,
+    ):
+        if not MetricsRecord._warning_logged:
+            MetricsRecord._warning_logged = True
+            log(
+                WARN,
+                "The `MetricsRecord` class has been renamed to `MetricRecord`. "
+                "Support for `MetricsRecord` will be removed in a future release. "
+                "Please update your code accordingly.",
+            )
+        super().__init__(metric_dict, keep_input)