flwr 1.16.0__py3-none-any.whl → 1.18.0__py3-none-any.whl

flwr/client/app.py

@@ -1,4 +1,4 @@
-# Copyright 2020 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.
@@ -158,33 +158,33 @@ def start_client(
 
     Examples
     --------
-    Starting a gRPC client with an insecure server connection:
-
-    >>> start_client(
-    >>>     server_address=localhost:8080,
-    >>>     client_fn=client_fn,
-    >>> )
-
-    Starting an SSL-enabled gRPC client using system certificates:
-
-    >>> def client_fn(context: Context):
-    >>>     return FlowerClient().to_client()
-    >>>
-    >>> start_client(
-    >>>     server_address=localhost:8080,
-    >>>     client_fn=client_fn,
-    >>>     insecure=False,
-    >>> )
-
-    Starting an SSL-enabled gRPC client using provided certificates:
-
-    >>> from pathlib import Path
-    >>>
-    >>> start_client(
-    >>>     server_address=localhost:8080,
-    >>>     client_fn=client_fn,
-    >>>     root_certificates=Path("/crts/root.pem").read_bytes(),
-    >>> )
+    Starting a gRPC client with an insecure server connection::
+
+        start_client(
+            server_address=localhost:8080,
+            client_fn=client_fn,
+        )
+
+    Starting a TLS-enabled gRPC client using system certificates::
+
+        def client_fn(context: Context):
+            return FlowerClient().to_client()
+
+        start_client(
+            server_address=localhost:8080,
+            client_fn=client_fn,
+            insecure=False,
+        )
+
+    Starting a TLS-enabled gRPC client using provided certificates::
+
+        from pathlib import Path
+
+        start_client(
+            server_address=localhost:8080,
+            client_fn=client_fn,
+            root_certificates=Path("/crts/root.pem").read_bytes(),
+        )
     """
     msg = (
         "flwr.client.start_client() is deprecated."
@@ -495,8 +495,9 @@ def start_client_internal(
                     context = run_info_store.retrieve_context(run_id=run_id)
                     # Create an error reply message that will never be used to prevent
                     # the used-before-assignment linting error
-                    reply_message = message.create_error_reply(
-                        error=Error(code=ErrorCode.UNKNOWN, reason="Unknown")
+                    reply_message = Message(
+                        Error(code=ErrorCode.UNKNOWN, reason="Unknown"),
+                        reply_to=message,
                     )
 
                     # Handle app loading and task message
@@ -593,8 +594,9 @@ def start_client_internal(
                         log(ERROR, "%s raised an exception", exc_entity, exc_info=ex)
 
                         # Create error message
-                        reply_message = message.create_error_reply(
-                            error=Error(code=e_code, reason=reason)
+                        reply_message = Message(
+                            Error(code=e_code, reason=reason),
+                            reply_to=message,
                         )
                     else:
                         # No exception, update node state
@@ -682,30 +684,30 @@ def start_numpy_client(
 
     Examples
     --------
-    Starting a gRPC client with an insecure server connection:
-
-    >>> start_numpy_client(
-    >>>     server_address=localhost:8080,
-    >>>     client=FlowerClient(),
-    >>> )
-
-    Starting an SSL-enabled gRPC client using system certificates:
-
-    >>> start_numpy_client(
-    >>>     server_address=localhost:8080,
-    >>>     client=FlowerClient(),
-    >>>     insecure=False,
-    >>> )
-
-    Starting an SSL-enabled gRPC client using provided certificates:
-
-    >>> from pathlib import Path
-    >>>
-    >>> start_numpy_client(
-    >>>     server_address=localhost:8080,
-    >>>     client=FlowerClient(),
-    >>>     root_certificates=Path("/crts/root.pem").read_bytes(),
-    >>> )
+    Starting a gRPC client with an insecure server connection::
+
+        start_numpy_client(
+            server_address=localhost:8080,
+            client=FlowerClient(),
+        )
+
+    Starting a TLS-enabled gRPC client using system certificates::
+
+        start_numpy_client(
+            server_address=localhost:8080,
+            client=FlowerClient(),
+            insecure=False,
+        )
+
+    Starting a TLS-enabled gRPC client using provided certificates::
+
+        from pathlib import Path
+
+        start_numpy_client(
+            server_address=localhost:8080,
+            client=FlowerClient(),
+            root_certificates=Path("/crts/root.pem").read_bytes(),
+        )
     """
     mssg = (
         "flwr.client.start_numpy_client() is deprecated. \n\tInstead, use "

flwr/client/client.py

@@ -1,4 +1,4 @@
-# Copyright 2020 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/client/client_app.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.
@@ -27,10 +27,13 @@ from flwr.client.message_handler.message_handler import (
 from flwr.client.mod.utils import make_ffn
 from flwr.client.typing import ClientFnExt, Mod
 from flwr.common import Context, Message, MessageType
-from flwr.common.logger import warn_deprecated_feature, warn_preview_feature
+from flwr.common.logger import warn_deprecated_feature
+from flwr.common.message import validate_message_type
 
 from .typing import ClientAppCallable
 
+DEFAULT_ACTION = "default"
+
 
 def _alert_erroneous_client_fn() -> None:
     raise ValueError(
@@ -92,16 +95,16 @@ class ClientApp:
 
     Examples
     --------
-    Assuming a typical `Client` implementation named `FlowerClient`, you can wrap it in
-    a `ClientApp` as follows:
-
-    >>> class FlowerClient(NumPyClient):
-    >>>     # ...
-    >>>
-    >>> def client_fn(context: Context):
-    >>>    return FlowerClient().to_client()
-    >>>
-    >>> app = ClientApp(client_fn)
+    Assuming a typical ``Client`` implementation named ``FlowerClient``, you can wrap
+    it in a ``ClientApp`` as follows::
+
+        class FlowerClient(NumPyClient):
+            # ...
+
+        def client_fn(context: Context):
+           return FlowerClient().to_client()
+
+        app = ClientApp(client_fn)
     """
 
     def __init__(
@@ -110,6 +113,7 @@ class ClientApp:
         mods: Optional[list[Mod]] = None,
     ) -> None:
         self._mods: list[Mod] = mods if mods is not None else []
+        self._registered_funcs: dict[str, ClientAppCallable] = {}
 
         # Create wrapper function for `handle`
         self._call: Optional[ClientAppCallable] = None
@@ -129,10 +133,7 @@ class ClientApp:
             # Wrap mods around the wrapped handle function
             self._call = make_ffn(ffn, mods if mods is not None else [])
 
-        # Step functions
-        self._train: Optional[ClientAppCallable] = None
-        self._evaluate: Optional[ClientAppCallable] = None
-        self._query: Optional[ClientAppCallable] = None
+        # Lifespan function
         self._lifespan = _empty_lifespan
 
     def __call__(self, message: Message, context: Context) -> Message:
@@ -142,159 +143,189 @@ class ClientApp:
             if self._call:
                 return self._call(message, context)
 
-            # Execute message using a new
-            if message.metadata.message_type == MessageType.TRAIN:
-                if self._train:
-                    return self._train(message, context)
-                raise ValueError("No `train` function registered")
-            if message.metadata.message_type == MessageType.EVALUATE:
-                if self._evaluate:
-                    return self._evaluate(message, context)
-                raise ValueError("No `evaluate` function registered")
-            if message.metadata.message_type == MessageType.QUERY:
-                if self._query:
-                    return self._query(message, context)
-                raise ValueError("No `query` function registered")
-
-            # Message type did not match one of the known message types abvoe
-            raise ValueError(f"Unknown message_type: {message.metadata.message_type}")
+            # Get the category and the action
+            # A valid message type is of the form "<category>" or "<category>.<action>",
+            # where <category> must be "train"/"evaluate"/"query", and <action> is a
+            # valid Python identifier
+            if not validate_message_type(message.metadata.message_type):
+                raise ValueError(
+                    f"Invalid message type: {message.metadata.message_type}"
+                )
+
+            category, action = message.metadata.message_type, DEFAULT_ACTION
+            if "." in category:
+                category, action = category.split(".")
+
+            # Check if the function is registered
+            if (full_name := f"{category}.{action}") in self._registered_funcs:
+                return self._registered_funcs[full_name](message, context)
+
+            raise ValueError(f"No {category} function registered with name '{action}'")
 
     def train(
-        self, mods: Optional[list[Mod]] = None
+        self, action: str = DEFAULT_ACTION, *, mods: Optional[list[Mod]] = None
     ) -> Callable[[ClientAppCallable], ClientAppCallable]:
-        """Return a decorator that registers the train fn with the client app.
+        """Register a train function with the ``ClientApp``.
+
+        Parameters
+        ----------
+        action : str (default: "default")
+            The action name used to route messages. Defaults to "default".
+        mods : Optional[list[Mod]] (default: None)
+            A list of function-specific modifiers.
+
+        Returns
+        -------
+        Callable[[ClientAppCallable], ClientAppCallable]
+            A decorator that registers a train function with the ``ClientApp``.
 
         Examples
         --------
-        Registering a train function:
-
-        >>> app = ClientApp()
-        >>>
-        >>> @app.train()
-        >>> def train(message: Message, context: Context) -> Message:
-        >>>    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())
-        """
+        Registering a train function::
 
-        def train_decorator(train_fn: ClientAppCallable) -> ClientAppCallable:
-            """Register the train fn with the ServerApp object."""
-            if self._call:
-                raise _registration_error(MessageType.TRAIN)
+            app = ClientApp()
 
-            warn_preview_feature("ClientApp-register-train-function")
+            @app.train()
+            def train(message: Message, context: Context) -> Message:
+                print("Executing default train function")
+                # Create and return an echo reply message
+                return Message(message.content, reply_to=message)
 
-            # Register provided function with the ClientApp object
-            # Wrap mods around the wrapped step function
-            self._train = make_ffn(train_fn, self._mods + (mods or []))
+        Registering a train function with a custom action name::
 
-            # Return provided function unmodified
-            return train_fn
+            app = ClientApp()
 
-        return train_decorator
+            # Messages with `message_type="train.custom_action"` will be
+            # routed to this function.
+            @app.train("custom_action")
+            def custom_action(message: Message, context: Context) -> Message:
+                print("Executing train function for custom action")
+                return Message(message.content, reply_to=message)
+
+        Registering a train function with a function-specific Flower Mod::
+
+            from flwr.client.mod import message_size_mod
+
+            app = ClientApp()
+
+            # Using the `mods` argument to apply a function-specific mod.
+            @app.train(mods=[message_size_mod])
+            def train(message: Message, context: Context) -> Message:
+                print("Executing train function with message size mod")
+                # Create and return an echo reply message
+                return Message(message.content, reply_to=message)
+        """
+        return _get_decorator(self, MessageType.TRAIN, action, mods)
 
     def evaluate(
-        self, mods: Optional[list[Mod]] = None
+        self, action: str = DEFAULT_ACTION, *, mods: Optional[list[Mod]] = None
     ) -> Callable[[ClientAppCallable], ClientAppCallable]:
-        """Return a decorator that registers the evaluate fn with the client app.
+        """Register an evaluate function with the ``ClientApp``.
+
+        Parameters
+        ----------
+        action : str (default: "default")
+            The action name used to route messages. Defaults to "default".
+        mods : Optional[list[Mod]] (default: None)
+            A list of function-specific modifiers.
+
+        Returns
+        -------
+        Callable[[ClientAppCallable], ClientAppCallable]
+            A decorator that registers an evaluate function with the ``ClientApp``.
 
         Examples
         --------
-        Registering an evaluate function:
-
-        >>> app = ClientApp()
-        >>>
-        >>> @app.evaluate()
-        >>> def evaluate(message: Message, context: Context) -> Message:
-        >>>    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())
-        """
+        Registering an evaluate function::
 
-        def evaluate_decorator(evaluate_fn: ClientAppCallable) -> ClientAppCallable:
-            """Register the evaluate fn with the ServerApp object."""
-            if self._call:
-                raise _registration_error(MessageType.EVALUATE)
+            app = ClientApp()
 
-            warn_preview_feature("ClientApp-register-evaluate-function")
+            @app.evaluate()
+            def evaluate(message: Message, context: Context) -> Message:
+                print("Executing default evaluate function")
+                # Create and return an echo reply message
+                return Message(message.content, reply_to=message)
 
-            # Register provided function with the ClientApp object
-            # Wrap mods around the wrapped step function
-            self._evaluate = make_ffn(evaluate_fn, self._mods + (mods or []))
+        Registering an evaluate function with a custom action name::
 
-            # Return provided function unmodified
-            return evaluate_fn
+            app = ClientApp()
+
+            # Messages with `message_type="evaluate.custom_action"` will be
+            # routed to this function.
+            @app.evaluate("custom_action")
+            def custom_action(message: Message, context: Context) -> Message:
+                print("Executing evaluate function for custom action")
+                return Message(message.content, reply_to=message)
+
+        Registering an evaluate function with a function-specific Flower Mod::
+
+            from flwr.client.mod import message_size_mod
 
-        return evaluate_decorator
+            app = ClientApp()
+
+            # Using the `mods` argument to apply a function-specific mod.
+            @app.evaluate(mods=[message_size_mod])
+            def evaluate(message: Message, context: Context) -> Message:
+                print("Executing evaluate function with message size mod")
+                # Create and return an echo reply message
+                return Message(message.content, reply_to=message)
+        """
+        return _get_decorator(self, MessageType.EVALUATE, action, mods)
 
     def query(
-        self, mods: Optional[list[Mod]] = None
+        self, action: str = DEFAULT_ACTION, *, mods: Optional[list[Mod]] = None
     ) -> Callable[[ClientAppCallable], ClientAppCallable]:
-        """Return a decorator that registers the query fn with the client app.
+        """Register a query function with the ``ClientApp``.
+
+        Parameters
+        ----------
+        action : str (default: "default")
+            The action name used to route messages. Defaults to "default".
+        mods : Optional[list[Mod]] (default: None)
+            A list of function-specific modifiers.
+
+        Returns
+        -------
+        Callable[[ClientAppCallable], ClientAppCallable]
+            A decorator that registers a query function with the ``ClientApp``.
 
         Examples
         --------
-        Registering a query function:
-
-        >>> app = ClientApp()
-        >>>
-        >>> @app.query()
-        >>> def query(message: Message, context: Context) -> Message:
-        >>>    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())
-        """
+        Registering a query function::
 
-        def query_decorator(query_fn: ClientAppCallable) -> ClientAppCallable:
-            """Register the query fn with the ServerApp object."""
-            if self._call:
-                raise _registration_error(MessageType.QUERY)
+            app = ClientApp()
 
-            warn_preview_feature("ClientApp-register-query-function")
+            @app.query()
+            def query(message: Message, context: Context) -> Message:
+                print("Executing default query function")
+                # Create and return an echo reply message
+                return Message(message.content, reply_to=message)
 
-            # Register provided function with the ClientApp object
-            # Wrap mods around the wrapped step function
-            self._query = make_ffn(query_fn, self._mods + (mods or []))
+        Registering a query function with a custom action name::
 
-            # Return provided function unmodified
-            return query_fn
+            app = ClientApp()
+
+            # Messages with `message_type="query.custom_action"` will be
+            # routed to this function.
+            @app.query("custom_action")
+            def custom_action(message: Message, context: Context) -> Message:
+                print("Executing query function for custom action")
+                return Message(message.content, reply_to=message)
+
+        Registering a query function with a function-specific Flower Mod::
+
+            from flwr.client.mod import message_size_mod
 
-        return query_decorator
+            app = ClientApp()
+
+            # Using the `mods` argument to apply a function-specific mod.
+            @app.query(mods=[message_size_mod])
+            def query(message: Message, context: Context) -> Message:
+                print("Executing query function with message size mod")
+                # Create and return an echo reply message
+                return Message(message.content, reply_to=message)
+        """
+        return _get_decorator(self, MessageType.QUERY, action, mods)
 
     def lifespan(
         self,
@@ -308,24 +339,25 @@ class ClientApp:
 
         Examples
         --------
-        >>> app = ClientApp()
-        >>>
-        >>> @app.lifespan()
-        >>> def lifespan(context: Context) -> None:
-        >>>     # Perform initialization tasks before the app starts
-        >>>     print("Initializing ClientApp")
-        >>>
-        >>>     yield  # ClientApp is running
-        >>>
-        >>>     # Perform cleanup tasks after the app stops
-        >>>     print("Cleaning up ClientApp")
+        ::
+
+                app = ClientApp()
+
+                @app.lifespan()
+                def lifespan(context: Context) -> None:
+                    # Perform initialization tasks before the app starts
+                    print("Initializing ClientApp")
+
+                    yield  # ClientApp is running
+
+                    # Perform cleanup tasks after the app stops
+                    print("Cleaning up ClientApp")
         """
 
         def lifespan_decorator(
             lifespan_fn: Callable[[Context], Iterator[None]]
         ) -> Callable[[Context], Iterator[None]]:
             """Register the lifespan fn with the ServerApp object."""
-            warn_preview_feature("ClientApp-register-lifespan-function")
 
             @contextmanager
             def decorated_lifespan(context: Context) -> Iterator[None]:
@@ -365,32 +397,65 @@ class LoadClientAppError(Exception):
     """Error when trying to load `ClientApp`."""
 
 
+def _get_decorator(
+    app: ClientApp, category: str, action: str, mods: Optional[list[Mod]]
+) -> Callable[[ClientAppCallable], ClientAppCallable]:
+    """Get the decorator for the given category and action."""
+    # pylint: disable=protected-access
+    if app._call:
+        raise _registration_error(category)
+
+    def decorator(fn: ClientAppCallable) -> ClientAppCallable:
+
+        # Check if the name is a valid Python identifier
+        if not action.isidentifier():
+            raise ValueError(
+                f"Cannot register {category} function with name '{action}'. "
+                "The name must follow Python's function naming rules."
+            )
+
+        # Check if the name is already registered
+        full_name = f"{category}.{action}"  # Full name of the message type
+        if full_name in app._registered_funcs:
+            raise ValueError(
+                f"Cannot register {category} function with name '{action}'. "
+                f"A {category} function with the name '{action}' is already registered."
+            )
+
+        # Register provided function with the ClientApp object
+        app._registered_funcs[full_name] = make_ffn(fn, app._mods + (mods or []))
+
+        # Return provided function unmodified
+        return fn
+
+    # pylint: enable=protected-access
+    return decorator
+
+
 def _registration_error(fn_name: str) -> ValueError:
     return ValueError(
         f"""Use either `@app.{fn_name}()` or `client_fn`, but not both.
 
         Use the `ClientApp` with an existing `client_fn`:
 
-        >>> class FlowerClient(NumPyClient):
-        >>>     # ...
-        >>>
-        >>> def client_fn(context: Context):
-        >>>     return FlowerClient().to_client()
-        >>>
-        >>> app = ClientApp(
-        >>>     client_fn=client_fn,
-        >>> )
+        class FlowerClient(NumPyClient):
+            # ...
+
+            def client_fn(context: Context):
+                return FlowerClient().to_client()
+
+            app = ClientApp(
+                client_fn=client_fn,
+            )
 
         Use the `ClientApp` with a custom {fn_name} function:
 
-        >>> app = ClientApp()
-        >>>
-        >>> @app.{fn_name}()
-        >>> def {fn_name}(message: Message, context: Context) -> Message:
-        >>>    print("ClientApp {fn_name} running")
-        >>>    # Create and return an echo reply message
-        >>>    return message.create_reply(
-        >>>        content=message.content()
-        >>>    )
+            app = ClientApp()
+
+            @app.{fn_name}()
+            def {fn_name}(message: Message, context: Context) -> Message:
+                print("ClientApp {fn_name} running")
+                # Create and return an echo reply message
+                return Message(message.content, reply_to=message)
         """,
     )

flwr/client/clientapp/__init__.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.