flwr 1.13.1__py3-none-any.whl → 1.15.0__py3-none-any.whl

flwr/cli/ls.py

@@ -15,27 +15,27 @@
 """Flower command line interface `ls` command."""
 
 
+import io
+import json
 from datetime import datetime, timedelta
-from logging import DEBUG
 from pathlib import Path
-from typing import Annotated, Any, Optional
+from typing import Annotated, Optional
 
-import grpc
 import typer
 from rich.console import Console
 from rich.table import Table
 from rich.text import Text
 
 from flwr.cli.config_utils import (
+    exit_if_no_address,
     load_and_validate,
-    validate_certificate_in_federation_config,
+    process_loaded_project_config,
     validate_federation_in_project_config,
-    validate_project_config,
 )
-from flwr.common.constant import FAB_CONFIG_FILE, SubStatus
+from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE
+from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat, SubStatus
 from flwr.common.date import format_timedelta, isoformat8601_utc
-from flwr.common.grpc import GRPC_MAX_MESSAGE_LENGTH, create_channel
-from flwr.common.logger import log
+from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.common.serde import run_from_proto
 from flwr.common.typing import Run
 from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
@@ -44,8 +44,12 @@ from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
 )
 from flwr.proto.exec_pb2_grpc import ExecStub
 
+from .utils import init_channel, try_obtain_cli_auth_plugin, unauthenticated_exc_handler
 
-def ls(
+_RunListType = tuple[int, str, str, str, str, str, str, str, str]
+
+
+def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
     app: Annotated[
         Path,
         typer.Argument(help="Path of the Flower project"),
@@ -54,6 +58,13 @@ def ls(
         Optional[str],
         typer.Argument(help="Name of the federation"),
     ] = None,
+    federation_config_overrides: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--federation-config",
+            help=FEDERATION_CONFIG_HELP_MESSAGE,
+        ),
+    ] = None,
     runs: Annotated[
         bool,
         typer.Option(
@@ -68,94 +79,101 @@ def ls(
             help="Specific run ID to display",
         ),
     ] = None,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            case_sensitive=False,
+            help="Format output using 'default' view or 'json'",
+        ),
+    ] = CliOutputFormat.DEFAULT,
 ) -> None:
-    """List runs."""
-    # Load and validate federation config
-    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
-
-    pyproject_path = app / FAB_CONFIG_FILE if app else None
-    config, errors, warnings = load_and_validate(path=pyproject_path)
-    config = validate_project_config(config, errors, warnings)
-    federation, federation_config = validate_federation_in_project_config(
-        federation, config
-    )
-
-    if "address" not in federation_config:
-        typer.secho(
-            "❌ `flwr ls` currently works with Exec API. Ensure that the correct"
-            "Exec API address is provided in the `pyproject.toml`.",
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1)
-
+    """List the details of one provided run ID or all runs in a Flower federation.
+
+    The following details are displayed:
+
+    - **Run ID:** Unique identifier for the run.
+    - **FAB:** Name of the FAB associated with the run (``{FAB_ID} (v{FAB_VERSION})``).
+    - **Status:** Current status of the run (pending, starting, running, finished).
+    - **Elapsed:** Time elapsed since the run started (``HH:MM:SS``).
+    - **Created At:** Timestamp when the run was created.
+    - **Running At:** Timestamp when the run started running.
+    - **Finished At:** Timestamp when the run finished.
+
+    All timestamps follow ISO 8601, UTC and are formatted as ``YYYY-MM-DD HH:MM:SSZ``.
+    """
+    suppress_output = output_format == CliOutputFormat.JSON
+    captured_output = io.StringIO()
     try:
-        if runs and run_id is not None:
-            raise ValueError(
-                "The options '--runs' and '--run-id' are mutually exclusive."
+        if suppress_output:
+            redirect_output(captured_output)
+        # Load and validate federation config
+        typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+
+        pyproject_path = app / FAB_CONFIG_FILE if app else None
+        config, errors, warnings = load_and_validate(path=pyproject_path)
+        config = process_loaded_project_config(config, errors, warnings)
+        federation, federation_config = validate_federation_in_project_config(
+            federation, config, federation_config_overrides
+        )
+        exit_if_no_address(federation_config, "ls")
+        channel = None
+        try:
+            if runs and run_id is not None:
+                raise ValueError(
+                    "The options '--runs' and '--run-id' are mutually exclusive."
+                )
+            auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
+            channel = init_channel(app, federation_config, auth_plugin)
+            stub = ExecStub(channel)
+
+            # Display information about a specific run ID
+            if run_id is not None:
+                typer.echo(f"🔍 Displaying information for run ID {run_id}...")
+                restore_output()
+                _display_one_run(stub, run_id, output_format)
+            # By default, list all runs
+            else:
+                typer.echo("📄 Listing all runs...")
+                restore_output()
+                _list_runs(stub, output_format)
+
+        except ValueError as err:
+            if suppress_output:
+                redirect_output(captured_output)
+            typer.secho(
+                f"❌ {err}",
+                fg=typer.colors.RED,
+                bold=True,
             )
-
-        channel = _init_channel(app, federation_config)
-        stub = ExecStub(channel)
-
-        # Display information about a specific run ID
-        if run_id is not None:
-            typer.echo(f"🔍 Displaying information for run ID {run_id}...")
-            _display_one_run(stub, run_id)
-        # By default, list all runs
+            raise typer.Exit(code=1) from err
+        finally:
+            if channel:
+                channel.close()
+    except (typer.Exit, Exception) as err:  # pylint: disable=broad-except
+        if suppress_output:
+            restore_output()
+            e_message = captured_output.getvalue()
+            print_json_error(e_message, err)
         else:
-            typer.echo("📄 Listing all runs...")
-            _list_runs(stub)
-
-    except ValueError as err:
-        typer.secho(
-            f"❌ {err}",
-            fg=typer.colors.RED,
-            bold=True,
-        )
-        raise typer.Exit(code=1) from err
+            typer.secho(
+                f"{err}",
+                fg=typer.colors.RED,
+                bold=True,
+            )
     finally:
-        channel.close()
-
+        if suppress_output:
+            restore_output()
+        captured_output.close()
 
-def on_channel_state_change(channel_connectivity: str) -> None:
-    """Log channel connectivity."""
-    log(DEBUG, channel_connectivity)
 
-
-def _init_channel(app: Path, federation_config: dict[str, Any]) -> grpc.Channel:
-    """Initialize gRPC channel to the Exec API."""
-    insecure, root_certificates_bytes = validate_certificate_in_federation_config(
-        app, federation_config
-    )
-    channel = create_channel(
-        server_address=federation_config["address"],
-        insecure=insecure,
-        root_certificates=root_certificates_bytes,
-        max_message_length=GRPC_MAX_MESSAGE_LENGTH,
-        interceptors=None,
-    )
-    channel.subscribe(on_channel_state_change)
-    return channel
-
-
-def _format_run_table(run_dict: dict[int, Run], now_isoformat: str) -> Table:
-    """Format run status as a rich Table."""
-    table = Table(header_style="bold cyan", show_lines=True)
+def _format_runs(run_dict: dict[int, Run], now_isoformat: str) -> list[_RunListType]:
+    """Format runs to a list."""
 
     def _format_datetime(dt: Optional[datetime]) -> str:
         return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
 
-    # Add columns
-    table.add_column(
-        Text("Run ID", justify="center"), style="bright_white", overflow="fold"
-    )
-    table.add_column(Text("FAB", justify="center"), style="dim white")
-    table.add_column(Text("Status", justify="center"))
-    table.add_column(Text("Elapsed", justify="center"), style="blue")
-    table.add_column(Text("Created At", justify="center"), style="dim white")
-    table.add_column(Text("Running At", justify="center"), style="dim white")
-    table.add_column(Text("Finished At", justify="center"), style="dim white")
+    run_list: list[_RunListType] = []
 
     # Add rows
     for run in sorted(
@@ -167,15 +185,6 @@ def _format_run_table(run_dict: dict[int, Run], now_isoformat: str) -> Table:
         else:
             status_text = f"{run.status.status}:{run.status.sub_status}"
 
-        # Style the status based on its value
-        sub_status = run.status.sub_status
-        if sub_status == SubStatus.COMPLETED:
-            status_style = "green"
-        elif sub_status == SubStatus.FAILED:
-            status_style = "red"
-        else:
-            status_style = "yellow"
-
         # Convert isoformat to datetime
         pending_at = datetime.fromisoformat(run.pending_at) if run.pending_at else None
         running_at = datetime.fromisoformat(run.running_at) if run.running_at else None
@@ -192,37 +201,136 @@ def _format_run_table(run_dict: dict[int, Run], now_isoformat: str) -> Table:
                 end_time = datetime.fromisoformat(now_isoformat)
             elapsed_time = end_time - running_at
 
-        table.add_row(
-            f"[bold]{run.run_id}[/bold]",
-            f"{run.fab_id} (v{run.fab_version})",
+        run_list.append(
+            (
+                run.run_id,
+                run.fab_id,
+                run.fab_version,
+                run.fab_hash,
+                status_text,
+                format_timedelta(elapsed_time),
+                _format_datetime(pending_at),
+                _format_datetime(running_at),
+                _format_datetime(finished_at),
+            )
+        )
+    return run_list
+
+
+def _to_table(run_list: list[_RunListType]) -> Table:
+    """Format the provided run list to a rich Table."""
+    table = Table(header_style="bold cyan", show_lines=True)
+
+    # Add columns
+    table.add_column(
+        Text("Run ID", justify="center"), style="bright_white", overflow="fold"
+    )
+    table.add_column(Text("FAB", justify="center"), style="dim white")
+    table.add_column(Text("Status", justify="center"))
+    table.add_column(Text("Elapsed", justify="center"), style="blue")
+    table.add_column(Text("Created At", justify="center"), style="dim white")
+    table.add_column(Text("Running At", justify="center"), style="dim white")
+    table.add_column(Text("Finished At", justify="center"), style="dim white")
+
+    for row in run_list:
+        (
+            run_id,
+            fab_id,
+            fab_version,
+            _,
+            status_text,
+            elapsed,
+            created_at,
+            running_at,
+            finished_at,
+        ) = row
+        # Style the status based on its value
+        sub_status = status_text.rsplit(":", maxsplit=1)[-1]
+        if sub_status == SubStatus.COMPLETED:
+            status_style = "green"
+        elif sub_status == SubStatus.FAILED:
+            status_style = "red"
+        else:
+            status_style = "yellow"
+
+        formatted_row = (
+            f"[bold]{run_id}[/bold]",
+            f"{fab_id} (v{fab_version})",
             f"[{status_style}]{status_text}[/{status_style}]",
-            format_timedelta(elapsed_time),
-            _format_datetime(pending_at),
-            _format_datetime(running_at),
-            _format_datetime(finished_at),
+            elapsed,
+            created_at,
+            running_at,
+            finished_at,
         )
+        table.add_row(*formatted_row)
+
     return table
 
 
+def _to_json(run_list: list[_RunListType]) -> str:
+    """Format run status list to a JSON formatted string."""
+    runs_list = []
+    for row in run_list:
+        (
+            run_id,
+            fab_id,
+            fab_version,
+            fab_hash,
+            status_text,
+            elapsed,
+            created_at,
+            running_at,
+            finished_at,
+        ) = row
+        runs_list.append(
+            {
+                "run-id": run_id,
+                "fab-id": fab_id,
+                "fab-name": fab_id.split("/")[-1],
+                "fab-version": fab_version,
+                "fab-hash": fab_hash[:8],
+                "status": status_text,
+                "elapsed": elapsed,
+                "created-at": created_at,
+                "running-at": running_at,
+                "finished-at": finished_at,
+            }
+        )
+
+    return json.dumps({"success": True, "runs": runs_list})
+
+
 def _list_runs(
     stub: ExecStub,
+    output_format: str = CliOutputFormat.DEFAULT,
 ) -> None:
     """List all runs."""
-    res: ListRunsResponse = stub.ListRuns(ListRunsRequest())
+    with unauthenticated_exc_handler():
+        res: ListRunsResponse = stub.ListRuns(ListRunsRequest())
     run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
 
-    Console().print(_format_run_table(run_dict, res.now))
+    formatted_runs = _format_runs(run_dict, res.now)
+    if output_format == CliOutputFormat.JSON:
+        Console().print_json(_to_json(formatted_runs))
+    else:
+        Console().print(_to_table(formatted_runs))
 
 
 def _display_one_run(
     stub: ExecStub,
     run_id: int,
+    output_format: str = CliOutputFormat.DEFAULT,
 ) -> None:
     """Display information about a specific run."""
-    res: ListRunsResponse = stub.ListRuns(ListRunsRequest(run_id=run_id))
+    with unauthenticated_exc_handler():
+        res: ListRunsResponse = stub.ListRuns(ListRunsRequest(run_id=run_id))
     if not res.run_dict:
         raise ValueError(f"Run ID {run_id} not found")
 
     run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
 
-    Console().print(_format_run_table(run_dict, res.now))
+    formatted_runs = _format_runs(run_dict, res.now)
+    if output_format == CliOutputFormat.JSON:
+        Console().print_json(_to_json(formatted_runs))
+    else:
+        Console().print(_to_table(formatted_runs))

flwr/cli/new/__init__.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `new` command."""
 
+
 from .new import new as new
 
 __all__ = [

flwr/cli/new/new.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `new` command."""
 
+
 import re
 from enum import Enum
 from pathlib import Path
@@ -81,7 +82,7 @@ def render_template(template: str, data: dict[str, str]) -> str:
 def create_file(file_path: Path, content: str) -> None:
     """Create file including all nessecary directories and write content into file."""
     file_path.parent.mkdir(exist_ok=True)
-    file_path.write_text(content)
+    file_path.write_text(content, encoding="utf-8")
 
 
 def render_and_create(file_path: Path, template: str, context: dict[str, str]) -> None:

flwr/cli/new/templates/app/.gitignore.tpl

@@ -3,6 +3,9 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# Flower directory
+.flwr
+
 # C extensions
 *.so
 

flwr/cli/new/templates/app/README.md.tpl

@@ -18,8 +18,9 @@ Refer to the [How to Run Simulations](https://flower.ai/docs/framework/how-to-ru
 
 ## Run with the Deployment Engine
 
-> \[!NOTE\]
-> An update to this example will show how to run this Flower application with the Deployment Engine and TLS certificates, or with Docker.
+Follow this [how-to guide](https://flower.ai/docs/framework/how-to-run-flower-with-deployment-engine.html) to run the same app in this example but with Flower's Deployment Engine. After that, you might be intersted in setting up [secure TLS-enabled communications](https://flower.ai/docs/framework/how-to-enable-tls-connections.html) and [SuperNode authentication](https://flower.ai/docs/framework/how-to-authenticate-supernodes.html) in your federation. 
+
+You can run Flower on Docker too! Check out the [Flower with Docker](https://flower.ai/docs/framework/docker/index.html) documentation.
 
 ## Resources
 

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

@@ -8,10 +8,10 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.13.0",
-    "flwr-datasets[vision]>=0.3.0",
-    "torch==2.2.1",
-    "torchvision==0.17.1",
+    "flwr[simulation]>=1.15.0",
+    "flwr-datasets[vision]>=0.5.0",
+    "torch==2.5.1",
+    "torchvision==0.20.1",
 ]
 
 [tool.hatch.metadata]

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

@@ -8,14 +8,14 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.13.0",
-    "flwr-datasets>=0.3.0",
+    "flwr[simulation]>=1.15.0",
+    "flwr-datasets>=0.5.0",
     "torch==2.3.1",
     "trl==0.8.1",
-    "bitsandbytes==0.43.0",
+    "bitsandbytes==0.45.0",
     "scipy==1.13.0",
     "peft==0.6.2",
-    "transformers==4.43.1",
+    "transformers==4.47.0",
     "sentencepiece==0.2.0",
     "omegaconf==2.3.0",
     "hf_transfer==0.1.8",

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

@@ -8,13 +8,13 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.13.0",
-    "flwr-datasets>=0.3.0",
-    "torch==2.2.1",
+    "flwr[simulation]>=1.15.0",
+    "flwr-datasets>=0.5.0",
+    "torch==2.5.1",
     "transformers>=4.30.0,<5.0",
     "evaluate>=0.4.0,<1.0",
     "datasets>=2.0.0, <3.0",
-    "scikit-learn>=1.3.1, <2.0",
+    "scikit-learn>=1.6.1, <2.0",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -8,10 +8,10 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.13.0",
+    "flwr[simulation]>=1.15.0",
     "jax==0.4.30",
     "jaxlib==0.4.30",
-    "scikit-learn==1.3.2",
+    "scikit-learn==1.6.1",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -8,10 +8,9 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.13.0",
-    "flwr-datasets[vision]>=0.3.0",
-    "mlx==0.16.1",
-    "numpy==1.24.4",
+    "flwr[simulation]>=1.15.0",
+    "flwr-datasets[vision]>=0.5.0",
+    "mlx==0.21.1",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -8,8 +8,8 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.13.0",
-    "numpy>=1.21.0",
+    "flwr[simulation]>=1.15.0",
+    "numpy>=2.0.2",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -8,10 +8,10 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.13.0",
-    "flwr-datasets[vision]>=0.3.0",
-    "torch==2.2.1",
-    "torchvision==0.17.1",
+    "flwr[simulation]>=1.15.0",
+    "flwr-datasets[vision]>=0.5.0",
+    "torch==2.5.1",
+    "torchvision==0.20.1",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -8,9 +8,9 @@ version = "1.0.0"
 description = ""
 license = "Apache-2.0"
 dependencies = [
-    "flwr[simulation]>=1.13.0",
-    "flwr-datasets[vision]>=0.3.0",
-    "scikit-learn>=1.1.1",
+    "flwr[simulation]>=1.15.0",
+    "flwr-datasets[vision]>=0.5.0",
+    "scikit-learn>=1.6.1",
 ]
 
 [tool.hatch.build.targets.wheel]

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

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

flwr/cli/run/__init__.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `run` command."""
 
+
 from .run import run as run
 
 __all__ = [