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

flwr/cli/build.py

@@ -138,6 +138,8 @@ def build(
                 and f.name != "pyproject.toml"  # Exclude the original pyproject.toml
             ]
 
+            all_files.sort()
+
             for file_path in all_files:
                 # Read the file content manually
                 with open(file_path, "rb") as f:

flwr/cli/log.py

@@ -38,6 +38,10 @@ from flwr.proto.exec_pb2_grpc import ExecStub
 from .utils import init_channel, try_obtain_cli_auth_plugin, unauthenticated_exc_handler
 
 
+class AllLogsRetrieved(BaseException):
+    """Raised when all logs are retrieved."""
+
+
 def start_stream(
     run_id: int, channel: grpc.Channel, refresh_period: int = CONN_REFRESH_PERIOD
 ) -> None:
@@ -56,10 +60,10 @@ def start_stream(
         # pylint: disable=E1101
         if e.code() == grpc.StatusCode.NOT_FOUND:
             logger(ERROR, "Invalid run_id `%s`, exiting", run_id)
-        if e.code() == grpc.StatusCode.CANCELLED:
-            pass
         else:
             raise e
+    except AllLogsRetrieved:
+        pass
     finally:
         channel.close()
 
@@ -94,6 +98,7 @@ def stream_logs(
         with unauthenticated_exc_handler():
             for res in stub.StreamLogs(req, timeout=duration):
                 print(res.log_output, end="")
+        raise AllLogsRetrieved()
     except grpc.RpcError as e:
         # pylint: disable=E1101
         if e.code() != grpc.StatusCode.DEADLINE_EXCEEDED:
@@ -108,27 +113,21 @@ def stream_logs(
 def print_logs(run_id: int, channel: grpc.Channel, timeout: int) -> None:
     """Print logs from the beginning of a run."""
     stub = ExecStub(channel)
-    req = StreamLogsRequest(run_id=run_id)
+    req = StreamLogsRequest(run_id=run_id, after_timestamp=0.0)
 
     try:
-        while True:
-            try:
-                with unauthenticated_exc_handler():
-                    # Enforce timeout for graceful exit
-                    for res in stub.StreamLogs(req, timeout=timeout):
-                        print(res.log_output)
-            except grpc.RpcError as e:
-                # pylint: disable=E1101
-                if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
-                    break
-                if e.code() == grpc.StatusCode.NOT_FOUND:
-                    logger(ERROR, "Invalid run_id `%s`, exiting", run_id)
-                    break
-                if e.code() == grpc.StatusCode.CANCELLED:
-                    break
-                raise e
-    except KeyboardInterrupt:
-        logger(DEBUG, "Stream interrupted by user")
+        with unauthenticated_exc_handler():
+            # Enforce timeout for graceful exit
+            for res in stub.StreamLogs(req, timeout=timeout):
+                print(res.log_output)
+                break
+    except grpc.RpcError as e:
+        if e.code() == grpc.StatusCode.NOT_FOUND:  # pylint: disable=E1101
+            logger(ERROR, "Invalid run_id `%s`, exiting", run_id)
+        elif e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:  # pylint: disable=E1101
+            pass
+        else:
+            raise e
     finally:
         channel.close()
         logger(DEBUG, "Channel closed")

flwr/cli/new/templates/app/pyproject.baseline.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "flwr-datasets[vision]>=0.5.0",
     "torch==2.5.1",
     "torchvision==0.20.1",

flwr/cli/new/templates/app/pyproject.flowertune.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "flwr-datasets>=0.5.0",
     "torch==2.3.1",
     "trl==0.8.1",

flwr/cli/new/templates/app/pyproject.huggingface.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "flwr-datasets>=0.5.0",
     "torch==2.5.1",
     "transformers>=4.30.0,<5.0",

flwr/cli/new/templates/app/pyproject.jax.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "jax==0.4.30",
     "jaxlib==0.4.30",
     "scikit-learn==1.6.1",

flwr/cli/new/templates/app/pyproject.mlx.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "flwr-datasets[vision]>=0.5.0",
     "mlx==0.21.1",
 ]

flwr/cli/new/templates/app/pyproject.numpy.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "numpy>=2.0.2",
 ]
 

flwr/cli/new/templates/app/pyproject.pytorch.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "flwr-datasets[vision]>=0.5.0",
     "torch==2.5.1",
     "torchvision==0.20.1",

flwr/cli/new/templates/app/pyproject.sklearn.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "flwr-datasets[vision]>=0.5.0",
     "scikit-learn>=1.6.1",
 ]

flwr/cli/new/templates/app/pyproject.tensorflow.toml.tpl

@@ -8,7 +8,7 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.15.2",
+    "flwr[simulation]>=1.16.0",
     "flwr-datasets[vision]>=0.5.0",
     "tensorflow>=2.11.1,<2.18.0",
 ]

flwr/client/client_app.py

@@ -16,6 +16,8 @@
 
 
 import inspect
+from collections.abc import Iterator
+from contextlib import contextmanager
 from typing import Callable, Optional
 
 from flwr.client.client import Client
@@ -71,6 +73,11 @@ def _inspect_maybe_adapt_client_fn_signature(client_fn: ClientFnExt) -> ClientFn
     return client_fn
 
 
+@contextmanager
+def _empty_lifespan(_: Context) -> Iterator[None]:
+    yield
+
+
 class ClientAppException(Exception):
     """Exception raised when an exception is raised while executing a ClientApp."""
 
@@ -95,15 +102,6 @@ class ClientApp:
     >>>    return FlowerClient().to_client()
     >>>
     >>> app = ClientApp(client_fn)
-
-    If the above code is in a Python module called `client`, it can be started as
-    follows:
-
-    >>> flower-client-app client:app --insecure
-
-    In this `client:app` example, `client` refers to the Python module `client.py` in
-    which the previous code lives in and `app` refers to the global attribute `app` that
-    points to an object of type `ClientApp`.
     """
 
     def __init__(
@@ -135,35 +133,41 @@ class ClientApp:
         self._train: Optional[ClientAppCallable] = None
         self._evaluate: Optional[ClientAppCallable] = None
         self._query: Optional[ClientAppCallable] = None
+        self._lifespan = _empty_lifespan
 
     def __call__(self, message: Message, context: Context) -> Message:
         """Execute `ClientApp`."""
-        # Execute message using `client_fn`
-        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}")
-
-    def train(self) -> Callable[[ClientAppCallable], ClientAppCallable]:
+        with self._lifespan(context):
+            # Execute message using `client_fn`
+            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}")
+
+    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,13 +289,77 @@ 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
 
         return query_decorator
 
+    def lifespan(
+        self,
+    ) -> Callable[
+        [Callable[[Context], Iterator[None]]], Callable[[Context], Iterator[None]]
+    ]:
+        """Return a decorator that registers the lifespan fn with the client app.
+
+        The decorated function should accept a `Context` object and use `yield`
+        to define enter and exit behavior.
+
+        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")
+        """
+
+        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]:
+                # Execute the code before `yield` in lifespan_fn
+                try:
+                    if not isinstance(it := lifespan_fn(context), Iterator):
+                        raise StopIteration
+                    next(it)
+                except StopIteration:
+                    raise RuntimeError(
+                        "lifespan function should yield at least once."
+                    ) from None
+
+                try:
+                    # Enter the context
+                    yield
+                finally:
+                    try:
+                        # Execute the code after `yield` in lifespan_fn
+                        next(it)
+                    except StopIteration:
+                        pass
+                    else:
+                        raise RuntimeError("lifespan function should only yield once.")
+
+            # Register provided function with the ClientApp object
+            # Ignore mypy error because of different argument names (`_` vs `context`)
+            self._lifespan = decorated_lifespan  # type: ignore
+
+            # Return provided function unmodified
+            return lifespan_fn
+
+        return lifespan_decorator
+
 
 class LoadClientAppError(Exception):
     """Error when trying to load `ClientApp`."""

flwr/client/clientapp/app.py

@@ -16,6 +16,7 @@
 
 
 import argparse
+import gc
 import time
 from logging import DEBUG, ERROR, INFO
 from typing import Optional
@@ -160,6 +161,9 @@ def run_clientapp(  # pylint: disable=R0914
                 stub=stub, token=token, message=reply_message, context=context
             )
 
+            del client_app, message, context, run, fab, reply_message
+            gc.collect()
+
             # Reset token to `None` to prevent flwr-clientapp from trying to pull the
             # same inputs again
             token = None

flwr/client/message_handler/message_handler.py

@@ -82,7 +82,7 @@ def handle_control_message(message: Message) -> tuple[Optional[Message], int]:
         recordset = RecordSet()
         recordset.configs_records["config"] = ConfigsRecord({"reason": reason})
         out_message = message.create_reply(recordset)
-        # Return TaskRes and sleep duration
+        # Return Message and sleep duration
         return out_message, sleep_duration
 
     # Any other message

flwr/client/rest_client/connection.py

@@ -66,9 +66,7 @@ except ModuleNotFoundError:
 
 PATH_CREATE_NODE: str = "api/v0/fleet/create-node"
 PATH_DELETE_NODE: str = "api/v0/fleet/delete-node"
-PATH_PULL_TASK_INS: str = "api/v0/fleet/pull-task-ins"
 PATH_PULL_MESSAGES: str = "/api/v0/fleet/pull-messages"
-PATH_PUSH_TASK_RES: str = "api/v0/fleet/push-task-res"
 PATH_PUSH_MESSAGES: str = "/api/v0/fleet/push-messages"
 PATH_PING: str = "api/v0/fleet/ping"
 PATH_GET_RUN: str = "/api/v0/fleet/get-run"
@@ -280,7 +278,7 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         node = None
 
     def receive() -> Optional[Message]:
-        """Receive next task from server."""
+        """Receive next Message from server."""
         # Get Node
         if node is None:
             log(ERROR, "Node instance missing")
@@ -309,11 +307,11 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         if message_proto is not None:
             message = message_from_proto(message_proto)
             metadata = copy(message.metadata)
-            log(INFO, "[Node] POST /%s: success", PATH_PULL_TASK_INS)
+            log(INFO, "[Node] POST /%s: success", PATH_PULL_MESSAGES)
         return message
 
     def send(message: Message) -> None:
-        """Send task result back to server."""
+        """Send Message result back to server."""
         # Get Node
         if node is None:
             log(ERROR, "Node instance missing")
@@ -345,7 +343,7 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         log(
             INFO,
             "[Node] POST /%s: success, created result %s",
-            PATH_PUSH_TASK_RES,
+            PATH_PUSH_MESSAGES,
             res.results,  # pylint: disable=no-member
         )
 

flwr/client/supernode/__init__.py

@@ -15,10 +15,8 @@
 """Flower SuperNode."""
 
 
-from .app import run_client_app as run_client_app
 from .app import run_supernode as run_supernode
 
 __all__ = [
-    "run_client_app",
     "run_supernode",
 ]

flwr/client/supernode/app.py

@@ -16,7 +16,7 @@
 
 
 import argparse
-from logging import DEBUG, ERROR, INFO, WARN
+from logging import DEBUG, INFO, WARN
 from pathlib import Path
 from typing import Optional
 
@@ -98,16 +98,6 @@ def run_supernode() -> None:
     )
 
 
-def run_client_app() -> None:
-    """Run Flower client app."""
-    event(EventType.RUN_CLIENT_APP_ENTER)
-    log(
-        ERROR,
-        "The command `flower-client-app` has been replaced by `flwr run`.",
-    )
-    register_exit_handlers(event_type=EventType.RUN_CLIENT_APP_LEAVE)
-
-
 def _parse_args_run_supernode() -> argparse.ArgumentParser:
     """Parse flower-supernode command line arguments."""
     parser = argparse.ArgumentParser(

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/args.py

@@ -43,7 +43,8 @@ def add_args_flwr_app_common(parser: argparse.ArgumentParser) -> None:
         "--insecure",
         action="store_true",
         help="Run the server without HTTPS, regardless of whether certificate "
-        "paths are provided. By default, the server runs with HTTPS enabled. "
+        "paths are provided. Data transmitted between the gRPC client and server "
+        "is not encrypted. By default, the server runs with HTTPS enabled. "
         "Use this flag only if you understand the risks.",
     )
 
@@ -99,7 +100,12 @@ def try_obtain_server_certificates(
 ) -> Optional[tuple[bytes, bytes, bytes]]:
     """Validate and return the CA cert, server cert, and server private key."""
     if args.insecure:
-        log(WARN, "Option `--insecure` was set. Starting insecure HTTP server.")
+        log(
+            WARN,
+            "Option `--insecure` was set. Starting insecure HTTP server with "
+            "unencrypted communication (TLS disabled). Proceed only if you understand "
+            "the risks.",
+        )
         return None
     # Check if certificates are provided
     if args.ssl_certfile and args.ssl_keyfile and args.ssl_ca_certfile:

flwr/common/auth_plugin/auth_plugin.py

@@ -20,6 +20,7 @@ from collections.abc import Sequence
 from pathlib import Path
 from typing import Optional, Union
 
+from flwr.common.typing import UserInfo
 from flwr.proto.exec_pb2_grpc import ExecStub
 
 from ..typing import UserAuthCredentials, UserAuthLoginDetails
@@ -49,7 +50,7 @@ class ExecAuthPlugin(ABC):
     @abstractmethod
     def validate_tokens_in_metadata(
         self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> bool:
+    ) -> tuple[bool, Optional[UserInfo]]:
         """Validate authentication tokens in the provided metadata."""
 
     @abstractmethod