flwr-nightly 1.16.0.dev20250224__py3-none-any.whl → 1.16.0.dev20250226__py3-none-any.whl

flwr/client/client_app.py

@@ -159,11 +159,15 @@ class ClientApp:
         # Message type did not match one of the known message types abvoe
         raise ValueError(f"Unknown message_type: {message.metadata.message_type}")
 
-    def train(self) -> Callable[[ClientAppCallable], ClientAppCallable]:
+    def train(
+        self, mods: Optional[list[Mod]] = None
+    ) -> Callable[[ClientAppCallable], ClientAppCallable]:
         """Return a decorator that registers the train fn with the client app.
 
         Examples
         --------
+        Registering a train function:
+
         >>> app = ClientApp()
         >>>
         >>> @app.train()
@@ -171,6 +175,17 @@ class ClientApp:
         >>>    print("ClientApp training running")
         >>>    # Create and return an echo reply message
         >>>    return message.create_reply(content=message.content())
+
+        Registering a train function with a function-specific modifier:
+
+        >>> from flwr.client.mod import message_size_mod
+        >>>
+        >>> app = ClientApp()
+        >>>
+        >>> @app.train(mods=[message_size_mod])
+        >>> def train(message: Message, context: Context) -> Message:
+        >>>    print("ClientApp training running with message size mod")
+        >>>    return message.create_reply(content=message.content())
         """
 
         def train_decorator(train_fn: ClientAppCallable) -> ClientAppCallable:
@@ -182,18 +197,22 @@ class ClientApp:
 
             # Register provided function with the ClientApp object
             # Wrap mods around the wrapped step function
-            self._train = make_ffn(train_fn, self._mods)
+            self._train = make_ffn(train_fn, self._mods + (mods or []))
 
             # Return provided function unmodified
             return train_fn
 
         return train_decorator
 
-    def evaluate(self) -> Callable[[ClientAppCallable], ClientAppCallable]:
+    def evaluate(
+        self, mods: Optional[list[Mod]] = None
+    ) -> Callable[[ClientAppCallable], ClientAppCallable]:
         """Return a decorator that registers the evaluate fn with the client app.
 
         Examples
         --------
+        Registering an evaluate function:
+
         >>> app = ClientApp()
         >>>
         >>> @app.evaluate()
@@ -201,6 +220,18 @@ class ClientApp:
         >>>    print("ClientApp evaluation running")
         >>>    # Create and return an echo reply message
         >>>    return message.create_reply(content=message.content())
+
+        Registering an evaluate function with a function-specific modifier:
+
+        >>> from flwr.client.mod import message_size_mod
+        >>>
+        >>> app = ClientApp()
+        >>>
+        >>> @app.evaluate(mods=[message_size_mod])
+        >>> def evaluate(message: Message, context: Context) -> Message:
+        >>>    print("ClientApp evaluation running with message size mod")
+        >>>    # Create and return an echo reply message
+        >>>    return message.create_reply(content=message.content())
         """
 
         def evaluate_decorator(evaluate_fn: ClientAppCallable) -> ClientAppCallable:
@@ -212,18 +243,22 @@ class ClientApp:
 
             # Register provided function with the ClientApp object
             # Wrap mods around the wrapped step function
-            self._evaluate = make_ffn(evaluate_fn, self._mods)
+            self._evaluate = make_ffn(evaluate_fn, self._mods + (mods or []))
 
             # Return provided function unmodified
             return evaluate_fn
 
         return evaluate_decorator
 
-    def query(self) -> Callable[[ClientAppCallable], ClientAppCallable]:
+    def query(
+        self, mods: Optional[list[Mod]] = None
+    ) -> Callable[[ClientAppCallable], ClientAppCallable]:
         """Return a decorator that registers the query fn with the client app.
 
         Examples
         --------
+        Registering a query function:
+
         >>> app = ClientApp()
         >>>
         >>> @app.query()
@@ -231,6 +266,18 @@ class ClientApp:
         >>>    print("ClientApp query running")
         >>>    # Create and return an echo reply message
         >>>    return message.create_reply(content=message.content())
+
+        Registering a query function with a function-specific modifier:
+
+        >>> from flwr.client.mod import message_size_mod
+        >>>
+        >>> app = ClientApp()
+        >>>
+        >>> @app.query(mods=[message_size_mod])
+        >>> def query(message: Message, context: Context) -> Message:
+        >>>    print("ClientApp query running with message size mod")
+        >>>    # Create and return an echo reply message
+        >>>    return message.create_reply(content=message.content())
         """
 
         def query_decorator(query_fn: ClientAppCallable) -> ClientAppCallable:
@@ -242,7 +289,7 @@ class ClientApp:
 
             # Register provided function with the ClientApp object
             # Wrap mods around the wrapped step function
-            self._query = make_ffn(query_fn, self._mods)
+            self._query = make_ffn(query_fn, self._mods + (mods or []))
 
             # Return provided function unmodified
             return query_fn

flwr/common/address.py

@@ -15,10 +15,13 @@
 """Flower IP address utils."""
 
 
+import re
 import socket
 from ipaddress import ip_address
 from typing import Optional
 
+import grpc
+
 IPV6: int = 6
 
 
@@ -101,3 +104,35 @@ def is_port_in_use(address: str) -> bool:
             return True
 
         return False
+
+
+def get_ip_address_from_servicer_context(context: grpc.ServicerContext) -> str:
+    """Extract the client's IPv4 or IPv6 address from the gRPC ServicerContext.
+
+    Parameters
+    ----------
+    context : grpc.ServicerContext
+        The gRPC ServicerContext object. The context.peer() returns a string like
+        "ipv4:127.0.0.1:56789" for IPv4 and "ipv6:[2001:db8::1]:54321" for IPv6.
+
+    Returns
+    -------
+    str
+        If one of the format matches, the function will return the client's IP address,
+        otherwise, it will raise a ValueError.
+    """
+    peer: str = context.peer()
+    # Match IPv4: "ipv4:IP:port"
+    ipv4_match = re.match(r"^ipv4:(?P<ip>[^:]+):", peer)
+    if ipv4_match:
+        return ipv4_match.group("ip")
+
+    # Match IPv6: "ipv6:[IP]:port"
+    ipv6_match = re.match(r"^ipv6:\[(?P<ip>[^\]]+)\]:", peer)
+    if ipv6_match:
+        return ipv6_match.group("ip")
+
+    raise ValueError(
+        f"Unsupported peer address format: {peer} for the transport protocol. "
+        "The supported formats are ipv4:IP:port and ipv6:[IP]:port."
+    )

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
 
+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/parametersrecord.py

@@ -15,10 +15,12 @@
 """ParametersRecord and Array."""
 
 
+from __future__ import annotations
+
 from collections import OrderedDict
 from dataclasses import dataclass
 from io import BytesIO
-from typing import Optional, cast
+from typing import Any, cast, overload
 
 import numpy as np
 
@@ -27,29 +29,64 @@ from ..typing import NDArray
 from .typeddict import TypedDict
 
 
+def _raise_array_init_error() -> None:
+    raise TypeError(
+        f"Invalid arguments for {Array.__qualname__}. Expected either a "
+        "NumPy ndarray, or explicit dtype/shape/stype/data values."
+    )
+
+
 @dataclass
 class Array:
     """Array type.
 
     A dataclass containing serialized data from an array-like or tensor-like object
-    along with some metadata about it.
+    along with metadata about it. The class can be initialized in one of two ways:
+
+    1. By specifying explicit values for `dtype`, `shape`, `stype`, and `data`.
+    2. By providing a NumPy ndarray (via the `ndarray` argument).
+
+    In scenario (2), the `dtype`, `shape`, `stype`, and `data` are automatically
+    derived from the input. In scenario (1), these fields must be specified manually.
 
     Parameters
     ----------
-    dtype : str
-        A string representing the data type of the serialised object (e.g. `np.float32`)
+    dtype : Optional[str] (default: None)
+        A string representing the data type of the serialized object (e.g. `"float32"`).
+        Only required if you are not passing in a ndarray.
 
-    shape : List[int]
-        A list representing the shape of the unserialized array-like object. This is
-        used to deserialize the data (depending on the serialization method) or simply
-        as a metadata field.
+    shape : Optional[list[int]] (default: None)
+        A list representing the shape of the unserialized array-like object. Only
+        required if you are not passing in a ndarray.
 
-    stype : str
-        A string indicating the type of serialisation mechanism used to generate the
-        bytes in `data` from an array-like or tensor-like object.
+    stype : Optional[str] (default: None)
+        A string indicating the serialization mechanism used to generate the bytes in
+        `data` from an array-like or tensor-like object. Only required if you are not
+        passing in a ndarray.
 
-    data: bytes
-        A buffer of bytes containing the data.
+    data : Optional[bytes] (default: None)
+        A buffer of bytes containing the data. Only required if you are not passing in
+        a ndarray.
+
+    ndarray : Optional[NDArray] (default: None)
+        A NumPy ndarray. If provided, the `dtype`, `shape`, `stype`, and `data`
+        fields are derived automatically from it.
+
+    Examples
+    --------
+    Initializing by specifying all fields directly:
+
+    >>> arr1 = Array(
+    >>>     dtype="float32",
+    >>>     shape=[3, 3],
+    >>>     stype="numpy.ndarray",
+    >>>     data=b"serialized_data...",
+    >>> )
+
+    Initializing with a NumPy ndarray:
+
+    >>> import numpy as np
+    >>> arr2 = Array(np.random.randn(3, 3))
     """
 
     dtype: str
@@ -57,6 +94,105 @@ class Array:
     stype: str
     data: bytes
 
+    @overload
+    def __init__(  # noqa: E704
+        self, dtype: str, shape: list[int], stype: str, data: bytes
+    ) -> None: ...
+
+    @overload
+    def __init__(self, ndarray: NDArray) -> None: ...  # noqa: E704
+
+    def __init__(  # pylint: disable=too-many-arguments, too-many-locals
+        self,
+        *args: Any,
+        dtype: str | None = None,
+        shape: list[int] | None = None,
+        stype: str | None = None,
+        data: bytes | None = None,
+        ndarray: NDArray | None = None,
+    ) -> None:
+        # Determine the initialization method and validate input arguments.
+        # Support two initialization formats:
+        # 1. Array(dtype: str, shape: list[int], stype: str, data: bytes)
+        # 2. Array(ndarray: NDArray)
+
+        # Initialize all arguments
+        # If more than 4 positional arguments are provided, raise an error.
+        if len(args) > 4:
+            _raise_array_init_error()
+        all_args = [None] * 4
+        for i, arg in enumerate(args):
+            all_args[i] = arg
+        init_method: str | None = None  # Track which init method is being used
+
+        # Try to assign a value to all_args[index] if it's not already set.
+        # If an initialization method is provided, update init_method.
+        def _try_set_arg(index: int, arg: Any, method: str) -> None:
+            # Skip if arg is None
+            if arg is None:
+                return
+            # Raise an error if all_args[index] is already set
+            if all_args[index] is not None:
+                _raise_array_init_error()
+            # Raise an error if a different initialization method is already set
+            nonlocal init_method
+            if init_method is not None and init_method != method:
+                _raise_array_init_error()
+            # Set init_method and all_args[index]
+            if init_method is None:
+                init_method = method
+            all_args[index] = arg
+
+        # Try to set keyword arguments in all_args
+        _try_set_arg(0, dtype, "direct")
+        _try_set_arg(1, shape, "direct")
+        _try_set_arg(2, stype, "direct")
+        _try_set_arg(3, data, "direct")
+        _try_set_arg(0, ndarray, "ndarray")
+
+        # Check if all arguments are correctly set
+        all_args = [arg for arg in all_args if arg is not None]
+
+        # Handle direct field initialization
+        if not init_method or init_method == "direct":
+            if (
+                len(all_args) == 4  # pylint: disable=too-many-boolean-expressions
+                and isinstance(all_args[0], str)
+                and isinstance(all_args[1], list)
+                and all(isinstance(i, int) for i in all_args[1])
+                and isinstance(all_args[2], str)
+                and isinstance(all_args[3], bytes)
+            ):
+                self.dtype, self.shape, self.stype, self.data = all_args
+                return
+
+        # Handle NumPy array
+        if not init_method or init_method == "ndarray":
+            if len(all_args) == 1 and isinstance(all_args[0], np.ndarray):
+                self.__dict__.update(self.from_numpy_ndarray(all_args[0]).__dict__)
+                return
+
+        _raise_array_init_error()
+
+    @classmethod
+    def from_numpy_ndarray(cls, ndarray: NDArray) -> Array:
+        """Create Array from NumPy ndarray."""
+        assert isinstance(
+            ndarray, np.ndarray
+        ), f"Expected NumPy ndarray, got {type(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,
+        )
+
     def numpy(self) -> NDArray:
         """Return the array as a NumPy array."""
         if self.stype != SType.NUMPY:
@@ -117,7 +253,6 @@ class ParametersRecord(TypedDict[str, Array]):
 
     >>> import numpy as np
     >>> from flwr.common import ParametersRecord
-    >>> from flwr.common import array_from_numpy
     >>>
     >>> # Let's create a simple NumPy array
     >>> arr_np = np.random.randn(3, 3)
@@ -128,7 +263,7 @@ class ParametersRecord(TypedDict[str, Array]):
     >>>      [-0.10758364,  1.97619858, -0.37120501]])
     >>>
     >>> # Let's create an Array out of it
-    >>> arr = array_from_numpy(arr_np)
+    >>> arr = Array(arr_np)
     >>>
     >>> # If we print it you'll see (note the binary data)
     >>> Array(dtype='float64', shape=[3,3], stype='numpy.ndarray', data=b'@\x99\x18...')
@@ -176,7 +311,7 @@ class ParametersRecord(TypedDict[str, Array]):
 
     def __init__(
         self,
-        array_dict: Optional[OrderedDict[str, Array]] = None,
+        array_dict: OrderedDict[str, Array] | None = None,
         keep_input: bool = False,
     ) -> None:
         super().__init__(_check_key, _check_value)

{flwr_nightly-1.16.0.dev20250224.dist-info → flwr_nightly-1.16.0.dev20250226.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: flwr-nightly
-Version: 1.16.0.dev20250224
+Version: 1.16.0.dev20250226
 Summary: Flower: A Friendly Federated AI Framework
 Home-page: https://flower.ai
 License: Apache-2.0

{flwr_nightly-1.16.0.dev20250224.dist-info → flwr_nightly-1.16.0.dev20250226.dist-info}/RECORD

@@ -74,7 +74,7 @@ flwr/cli/utils.py,sha256=D9XcpxzwkGPNdwX16o0kI-sYnRDMlWYyKNIpz6npRhQ,11236
 flwr/client/__init__.py,sha256=DGDoO0AEAfz-0CUFmLdyUUweAS64-07AOnmDfWUefK4,1192
 flwr/client/app.py,sha256=tNnef5wGVfqMiiGiWzAuULyy1QpvCKukiRmNi_a2cQc,34261
 flwr/client/client.py,sha256=8o58nd9o6ZFcMIaVYPGcV4MSjBG4H0oFgWiv8ZEO3oA,7895
-flwr/client/client_app.py,sha256=cTig-N00YzTucbo9zNi6I21J8PlbflU_8J_f5CI-Wpw,10390
+flwr/client/client_app.py,sha256=Vv4rfDcV9ycb9ZuUkhT_8wX7W1GIrALwlvRcUeVel3Y,12161
 flwr/client/clientapp/__init__.py,sha256=kZqChGnTChQ1WGSUkIlW2S5bc0d0mzDubCAmZUGRpEY,800
 flwr/client/clientapp/app.py,sha256=Us5Mw3wvGd_6P1zHOf3TNcRGBBulVZDo3LuZOs17WgM,8963
 flwr/client/clientapp/clientappio_servicer.py,sha256=5L6bjw_j3Mnx9kRFwYwxDNABKurBO5q1jZOWE_X11wQ,8522
@@ -112,7 +112,7 @@ flwr/client/supernode/__init__.py,sha256=SUhWOzcgXRNXk1V9UgB5-FaWukqqrOEajVUHEcP
 flwr/client/supernode/app.py,sha256=oBbggh56HoieksBkTdDHAJC8VUFbrmGOP0-D9wdcZek,9265
 flwr/client/typing.py,sha256=dxoTBnTMfqXr5J7G3y-uNjqxYCddvxhu89spfj4Lm2U,1048
 flwr/common/__init__.py,sha256=TVaoFEJE158aui1TPZQiJCDZX4RNHRyI8I55VC80HhI,3901
-flwr/common/address.py,sha256=9KNYE69WW_QVcyumsux3Qn1wmn4J7f13Y9nHASpvzbA,3018
+flwr/common/address.py,sha256=rRaN1JpiCJnit7ImEqZVxURQ69dPihRoyyWn_3I2wh4,4119
 flwr/common/args.py,sha256=MgkTUXACuySHyNdxrb7-pK0_R-S2Q7W5MnE3onYUf5I,5183
 flwr/common/auth_plugin/__init__.py,sha256=1Y8Oj3iB49IHDu9tvDih1J74Ygu7k85V9s2A4WORPyA,887
 flwr/common/auth_plugin/auth_plugin.py,sha256=wgDorBUB4IkK6twQ8vNawRVz7BDPmKdXZBNLqhU9RSs,3871
@@ -135,9 +135,9 @@ flwr/common/parameter.py,sha256=-bFAUayToYDF50FZGrBC1hQYJCQDtB2bbr3ZuVLMtdE,2095
 flwr/common/pyproject.py,sha256=vEAxl800XiJ1JNJDui8vuVV-08msnB6hLt7o95viZl0,1386
 flwr/common/record/__init__.py,sha256=LUixpq0Z-lMJwCIu1-4u5HfvRPjRMRgoAc6YJQ6UEOs,1055
 flwr/common/record/configsrecord.py,sha256=i40jOzBx04ysZKECwaw4FdUXMdY9HgdY8GAqKdTO1Lw,6486
-flwr/common/record/conversion_utils.py,sha256=n3I3SI2P6hUjyxbWNc0QAch-SEhfMK6Hm-UUaplAlUc,1393
+flwr/common/record/conversion_utils.py,sha256=ZcsM-vTm_rVtLXLFD2RY3N47V_hUr3ywTdtnpVXnOGU,1202
 flwr/common/record/metricsrecord.py,sha256=UywkEPbifiu_IyPUFoDJCi8WEVLujlqZERUWAWpc3vs,5752
-flwr/common/record/parametersrecord.py,sha256=SasHn35JRHsj8G1UT76FgRjaP4ZJasejvgjBV6HnaTg,7748
+flwr/common/record/parametersrecord.py,sha256=rR0LbeNrKrdK37CiAA56Z5WBq-ZzZ2YNSUkcmr5i2lI,12950
 flwr/common/record/recordset.py,sha256=qqIFdRZ0ivQhUhztpdxNIvCRDZQXY_zX0kKDEU9mhfM,8319
 flwr/common/record/typeddict.py,sha256=q5hL2xkXymuiCprHWb69mUmLpWQk_XXQq0hGQ69YPaw,3599
 flwr/common/recordset_compat.py,sha256=ViSwA26h6Q55ZmV1LLjSJpcKiipV-p_JpCj4wxdE-Ow,14230
@@ -327,8 +327,8 @@ flwr/superexec/exec_servicer.py,sha256=X10ILT-AoGMrB3IgI2mBe9i-QcIVUAl9bucuqVOPY
 flwr/superexec/exec_user_auth_interceptor.py,sha256=K06OU-l4LnYhTDg071hGJuOaQWEJbZsYi5qxUmmtiG0,3704
 flwr/superexec/executor.py,sha256=_B55WW2TD1fBINpabSSDRenVHXYmvlfhv-k8hJKU4lQ,3115
 flwr/superexec/simulation.py,sha256=WQDon15oqpMopAZnwRZoTICYCfHqtkvFSqiTQ2hLD_g,4088
-flwr_nightly-1.16.0.dev20250224.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-flwr_nightly-1.16.0.dev20250224.dist-info/METADATA,sha256=jmttkR3BVjew5ed7_TGqL_V6lwfQZnZ3kbZEpZXZDrU,15877
-flwr_nightly-1.16.0.dev20250224.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
-flwr_nightly-1.16.0.dev20250224.dist-info/entry_points.txt,sha256=JlNxX3qhaV18_2yj5a3kJW1ESxm31cal9iS_N_pf1Rk,538
-flwr_nightly-1.16.0.dev20250224.dist-info/RECORD,,
+flwr_nightly-1.16.0.dev20250226.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+flwr_nightly-1.16.0.dev20250226.dist-info/METADATA,sha256=9351LF7XOp_SkK7kJWKK2985bCbPYRocxMjwx2UE0bs,15877
+flwr_nightly-1.16.0.dev20250226.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+flwr_nightly-1.16.0.dev20250226.dist-info/entry_points.txt,sha256=JlNxX3qhaV18_2yj5a3kJW1ESxm31cal9iS_N_pf1Rk,538
+flwr_nightly-1.16.0.dev20250226.dist-info/RECORD,,