flwr 1.23.0__py3-none-any.whl → 1.24.0__py3-none-any.whl

flwr/cli/new/new.py

@@ -16,23 +16,24 @@
 
 
 import io
-import json
 import re
 import zipfile
 from enum import Enum
 from pathlib import Path
 from string import Template
-from typing import Annotated, Optional
+from typing import Annotated
 
 import requests
 import typer
 
-from flwr.supercore.constant import APP_ID_PATTERN, PLATFORM_API_URL
+from flwr.supercore.constant import PLATFORM_API_URL
 
 from ..utils import (
     is_valid_project_name,
+    parse_app_spec,
     prompt_options,
     prompt_text,
+    request_download_link,
     sanitize_project_name,
 )
 
@@ -100,7 +101,7 @@ def render_and_create(file_path: Path, template: str, context: dict[str, str]) -
 
 
 def print_success_prompt(
-    package_name: str, llm_challenge_str: Optional[str] = None
+    package_name: str, llm_challenge_str: str | None = None
 ) -> None:
     """Print styled setup instructions for running a new Flower App after creation."""
     prompt = typer.style(
@@ -181,55 +182,31 @@ def _download_zip_to_memory(presigned_url: str) -> io.BytesIO:
         r = requests.get(presigned_url, timeout=60)
         r.raise_for_status()
     except requests.RequestException as e:
-        raise typer.BadParameter(f"ZIP download failed: {e}") from e
+        typer.secho(
+            f"ZIP download failed: {e}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1) from e
 
     buf = io.BytesIO(r.content)
     # Validate it's a zip
     if not zipfile.is_zipfile(buf):
-        raise typer.BadParameter("Downloaded file is not a valid ZIP")
+        typer.secho(
+            "Downloaded file is not a valid ZIP",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
     buf.seek(0)
     return buf
 
 
-def _request_download_link(identifier: str) -> str:
-    """Request download link from Flower platform API."""
-    url = f"{PLATFORM_API_URL}/hub/fetch-zip"
-    headers = {
-        "Content-Type": "application/json",
-        "Accept": "application/json",
-    }
-    body = {
-        "identifier": identifier,  # send raw string of identifier
-    }
-
-    try:
-        resp = requests.post(url, headers=headers, data=json.dumps(body), timeout=20)
-    except requests.RequestException as e:
-        raise typer.BadParameter(f"Unable to connect to Platform API: {e}") from e
-
-    if resp.status_code == 404:
-        raise typer.BadParameter(f"'{identifier}' not found in Platform API")
-    if not resp.ok:
-        raise typer.BadParameter(
-            f"Platform API request failed with "
-            f"status {resp.status_code}. Details: {resp.text}"
-        )
-
-    data = resp.json()
-    if "zip_url" not in data:
-        raise typer.BadParameter("Invalid response from Platform API")
-    return str(data["zip_url"])
-
-
-def download_remote_app_via_api(identifier: str) -> None:
+def download_remote_app_via_api(app_spec: str) -> None:
     """Download App from Platform API."""
-    # Parse @user/app just to derive local dir name
-    m = re.match(APP_ID_PATTERN, identifier)
-    if not m:
-        raise typer.BadParameter(
-            "Invalid remote app ID. Expected format: '@user_name/app_name'."
-        )
-    app_name = m.group("app")
+    # Validate app version and ID format
+    app_id, app_version = parse_app_spec(app_spec)
+    app_name = app_id.split("/")[1]
 
     project_dir = Path.cwd() / app_name
     if project_dir.exists():
@@ -244,12 +221,14 @@ def download_remote_app_via_api(identifier: str) -> None:
 
     print(
         typer.style(
-            f"\n🔗 Requesting download link for {identifier}...",
+            f"\n🔗 Requesting download link for {app_id}...",
             fg=typer.colors.GREEN,
             bold=True,
         )
     )
-    presigned_url = _request_download_link(identifier)
+    # Fetch ZIP downloading URL
+    url = f"{PLATFORM_API_URL}/hub/fetch-zip"
+    presigned_url = request_download_link(app_id, app_version, url, "zip_url")
 
     print(
         typer.style(
@@ -276,15 +255,19 @@ def download_remote_app_via_api(identifier: str) -> None:
 # pylint: disable=too-many-locals,too-many-branches,too-many-statements
 def new(
     app_name: Annotated[
-        Optional[str],
-        typer.Argument(help="The name of the Flower App"),
+        str | None,
+        typer.Argument(
+            help="Flower app name. For remote apps, use the format "
+            "'@account_name/app_name' or '@account_name/app_name==x.y.z'. "
+            "Version is optional (defaults to latest)."
+        ),
     ] = None,
     framework: Annotated[
-        Optional[MlFramework],
+        MlFramework | None,
         typer.Option(case_sensitive=False, help="The ML framework to use"),
     ] = None,
     username: Annotated[
-        Optional[str],
+        str | None,
         typer.Option(case_sensitive=False, help="The Flower username of the author"),
     ] = None,
 ) -> None:

flwr/cli/new/templates/app/code/task.pytorch.py.tpl

@@ -84,6 +84,7 @@ def train(net, trainloader, epochs, lr, device):
 def test(net, testloader, device):
     """Validate the model on the test set."""
     net.to(device)
+    net.eval()
     criterion = torch.nn.CrossEntropyLoss()
     correct, loss = 0, 0.0
     with torch.no_grad():

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
     "torch==2.8.0",
     "torchvision==0.23.0",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets>=0.5.0",
     "torch==2.4.0",
     "trl==0.8.1",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets>=0.5.0",
     "torch>=2.7.1",
     "transformers>=4.30.0,<5.0",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "jax==0.4.30",
     "jaxlib==0.4.30",
     "scikit-learn==1.6.1",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
     "mlx==0.29.0",
 ]

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "numpy>=2.0.2",
 ]
 

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

@@ -14,10 +14,10 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
-    "torch==2.7.1",
-    "torchvision==0.22.1",
+    "torch>=2.7.1",
+    "torchvision>=0.22.1",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
     "torch==2.7.1",
     "torchvision==0.22.1",

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
     "scikit-learn>=1.6.1",
 ]

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

@@ -14,9 +14,9 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets[vision]>=0.5.0",
-    "tensorflow>=2.11.1,<2.18.0",
+    "tensorflow>=2.18.0",
 ]
 
 [tool.hatch.build.targets.wheel]

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

@@ -14,7 +14,7 @@ description = ""
 license = "Apache-2.0"
 # Dependencies for your Flower App
 dependencies = [
-    "flwr[simulation]>=1.23.0",
+    "flwr[simulation]>=1.24.0",
     "flwr-datasets>=0.5.0",
     "xgboost>=2.0.0",
 ]

flwr/cli/pull.py

@@ -16,7 +16,7 @@
 
 
 from pathlib import Path
-from typing import Annotated, Optional
+from typing import Annotated
 
 import typer
 
@@ -50,22 +50,26 @@ def pull(  # pylint: disable=R0914
         typer.Argument(help="Path of the Flower App to run."),
     ] = Path("."),
     federation: Annotated[
-        Optional[str],
+        str | None,
         typer.Argument(help="Name of the federation."),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
         ),
     ] = None,
 ) -> None:
-    """Pull artifacts from a Flower run."""
+    """Pull artifacts from a Flower run.
+
+    Retrieve a download URL for artifacts generated during a completed Flower run. The
+    artifacts can then be downloaded from the provided URL.
+    """
     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, errors, warnings = load_and_validate(pyproject_path, check_module=False)
     config = process_loaded_project_config(config, errors, warnings)
     federation, federation_config = validate_federation_in_project_config(
         federation, config, federation_config_overrides
@@ -88,6 +92,7 @@ def pull(  # pylint: disable=R0914
                 "obtained.",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1)
 

flwr/cli/run/run.py

@@ -20,7 +20,7 @@ import io
 import json
 import subprocess
 from pathlib import Path
-from typing import Annotated, Any, Optional, cast
+from typing import Annotated, Any, cast
 
 import typer
 from rich.console import Console
@@ -45,25 +45,31 @@ from flwr.common.serde import config_record_to_proto, fab_to_proto, user_config_
 from flwr.common.typing import Fab
 from flwr.proto.control_pb2 import StartRunRequest  # pylint: disable=E0611
 from flwr.proto.control_pb2_grpc import ControlStub
+from flwr.supercore.constant import NOOP_FEDERATION
 
 from ..log import start_stream
-from ..utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
+from ..utils import (
+    flwr_cli_grpc_exc_handler,
+    init_channel,
+    load_cli_auth_plugin,
+    parse_app_spec,
+)
 
 CONN_REFRESH_PERIOD = 60  # Connection refresh period for log streaming (seconds)
 
 
-# pylint: disable-next=too-many-locals, R0913, R0917
+# pylint: disable-next=too-many-locals, too-many-branches, R0913, R0917
 def run(
     app: Annotated[
         Path,
         typer.Argument(help="Path of the Flower App to run."),
     ] = Path("."),
     federation: Annotated[
-        Optional[str],
+        str | None,
         typer.Argument(help="Name of the federation to run the app on."),
     ] = None,
     run_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--run-config",
             "-c",
@@ -71,7 +77,7 @@ def run(
         ),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
@@ -100,11 +106,25 @@ def run(
     try:
         if suppress_output:
             redirect_output(captured_output)
+
+        # Determine if app is remote
+        app_spec = None
+        if (app_str := str(app)).startswith("@"):
+            # Validate app version and ID format
+            _ = parse_app_spec(app_str)
+            app_spec = app_str
+        is_remote_app = app_spec is not None
+
         typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
 
-        pyproject_path = app / "pyproject.toml" if app else None
-        config, errors, warnings = load_and_validate(path=pyproject_path)
+        # Disable the validation for remote apps
+        pyproject_path = app / "pyproject.toml" if not is_remote_app else None
+        # `./pyproject.toml` will be loaded when `pyproject_path` is None
+        config, errors, warnings = load_and_validate(
+            pyproject_path, check_module=not is_remote_app
+        )
         config = process_loaded_project_config(config, errors, warnings)
+
         federation, federation_config = validate_federation_in_project_config(
             federation, config, federation_config_overrides
         )
@@ -117,6 +137,7 @@ def run(
                 run_config_overrides,
                 stream,
                 output_format,
+                app_spec,
             )
         else:
             _run_without_control_api(
@@ -132,6 +153,7 @@ def run(
                 f"{err}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
     finally:
         if suppress_output:
@@ -144,22 +166,32 @@ def _run_with_control_api(
     app: Path,
     federation: str,
     federation_config: dict[str, Any],
-    config_overrides: Optional[list[str]],
+    config_overrides: list[str] | None,
     stream: bool,
     output_format: str,
+    app_spec: str | None,
 ) -> None:
     channel = None
+    is_remote_app = app_spec is not None
     try:
         auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
         channel = init_channel(app, federation_config, auth_plugin)
         stub = ControlStub(channel)
 
-        fab_bytes = build_fab_from_disk(app)
-        fab_hash = hashlib.sha256(fab_bytes).hexdigest()
-        config = cast(dict[str, Any], load_toml(app / FAB_CONFIG_FILE))
-        fab_id, fab_version = get_metadata_from_config(config)
+        # Build FAB if local app
+        if not is_remote_app:
+            fab_bytes = build_fab_from_disk(app)
+            fab_hash = hashlib.sha256(fab_bytes).hexdigest()
+            config = cast(dict[str, Any], load_toml(app / FAB_CONFIG_FILE))
+            fab_id, fab_version = get_metadata_from_config(config)
+            fab = Fab(fab_hash, fab_bytes, {})
+        # Skip FAB build if remote app
+        else:
+            # Use empty values for FAB
+            fab_id = fab_version = fab_hash = ""
+            fab = Fab(fab_hash, b"", {})
 
-        fab = Fab(fab_hash, fab_bytes, {})
+        real_federation: str = federation_config.get("federation", NOOP_FEDERATION)
 
         # Construct a `ConfigRecord` out of a flattened `UserConfig`
         fed_config = flatten_dict(federation_config.get("options", {}))
@@ -168,7 +200,9 @@ def _run_with_control_api(
         req = StartRunRequest(
             fab=fab_to_proto(fab),
             override_config=user_config_to_proto(parse_config_args(config_overrides)),
+            federation=real_federation,
             federation_options=config_record_to_proto(c_record),
+            app_spec=app_spec or "",
         )
         with flwr_cli_grpc_exc_handler():
             res = stub.StartRun(req)
@@ -178,23 +212,35 @@ def _run_with_control_api(
                 f"🎊 Successfully started run {res.run_id}", fg=typer.colors.GREEN
             )
         else:
-            typer.secho("❌ Failed to start run", fg=typer.colors.RED)
+            if is_remote_app:
+                typer.secho(
+                    "❌ Failed to start run. Please check that the provided "
+                    "app identifier (@account_name/app_name) is correct.",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+            else:
+                typer.secho("❌ Failed to start run", fg=typer.colors.RED, err=True)
             raise typer.Exit(code=1)
 
         if output_format == CliOutputFormat.JSON:
-            run_output = json.dumps(
-                {
-                    "success": res.HasField("run_id"),
-                    "run-id": res.run_id if res.HasField("run_id") else None,
-                    "fab-id": fab_id,
-                    "fab-name": fab_id.rsplit("/", maxsplit=1)[-1],
-                    "fab-version": fab_version,
-                    "fab-hash": fab_hash[:8],
-                    "fab-filename": get_fab_filename(config, fab_hash),
-                }
-            )
+            # Only include FAB metadata if we actually built a local FAB
+            payload: dict[str, Any] = {
+                "success": res.HasField("run_id"),
+                "run-id": res.run_id if res.HasField("run_id") else None,
+            }
+            if not is_remote_app:
+                payload.update(
+                    {
+                        "fab-id": fab_id,
+                        "fab-name": fab_id.rsplit("/", maxsplit=1)[-1],
+                        "fab-version": fab_version,
+                        "fab-hash": fab_hash[:8],
+                        "fab-filename": get_fab_filename(config, fab_hash),
+                    }
+                )
             restore_output()
-            Console().print_json(run_output)
+            Console().print_json(json.dumps(payload))
 
         if stream:
             start_stream(res.run_id, channel, CONN_REFRESH_PERIOD)
@@ -204,14 +250,14 @@ def _run_with_control_api(
 
 
 def _run_without_control_api(
-    app: Optional[Path],
+    app: Path | None,
     federation_config: dict[str, Any],
-    config_overrides: Optional[list[str]],
+    config_overrides: list[str] | None,
     federation: str,
 ) -> None:
     try:
         num_supernodes = federation_config["options"]["num-supernodes"]
-        verbose: Optional[bool] = federation_config["options"].get("verbose")
+        verbose: bool | None = federation_config["options"].get("verbose")
         backend_cfg = federation_config["options"].get("backend", {})
     except KeyError as err:
         typer.secho(
@@ -222,6 +268,7 @@ def _run_without_control_api(
             "options.num-supernodes = 10\n",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1) from err
 

flwr/cli/run_utils.py

@@ -0,0 +1,130 @@
+# 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Flower command line interface utils."""
+
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+from flwr.common.date import format_timedelta, isoformat8601_utc
+from flwr.common.typing import Run
+
+
+@dataclass
+class RunRow:  # pylint: disable=too-many-instance-attributes
+    """Represents a single run's data for display.
+
+    Attributes
+    ----------
+    run_id : int
+        The unique identifier for the run.
+    federation : str
+        The federation name.
+    fab_id : str
+        The Flower App Bundle identifier.
+    fab_version : str
+        The FAB version string.
+    fab_hash : str
+        The SHA-256 hash of the FAB.
+    status_text : str
+        The formatted status text.
+    elapsed : str
+        The formatted elapsed time.
+    pending_at : str
+        Timestamp when run entered pending state.
+    starting_at : str
+        Timestamp when run entered starting state.
+    running_at : str
+        Timestamp when run entered running state.
+    finished_at : str
+        Timestamp when run finished.
+    """
+
+    run_id: int
+    federation: str
+    fab_id: str
+    fab_version: str
+    fab_hash: str
+    status_text: str
+    elapsed: str
+    pending_at: str
+    starting_at: str
+    running_at: str
+    finished_at: str
+
+
+def format_runs(runs: list[Run], now_isoformat: str) -> list[RunRow]:
+    """Format runs to a list of RunRow objects.
+
+    Parameters
+    ----------
+    runs : list[Run]
+        List of Run objects to format.
+    now_isoformat : str
+        Current timestamp in ISO format for calculating elapsed time.
+
+    Returns
+    -------
+    list[RunRow]
+        List of formatted RunRow objects sorted by pending_at timestamp.
+    """
+
+    def _format_datetime(dt: datetime | None) -> str:
+        return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
+
+    run_list: list[RunRow] = []
+
+    # Add rows
+    for run in sorted(runs, key=lambda x: datetime.fromisoformat(x.pending_at)):
+        # Combine status and sub-status into a single string
+        if run.status.sub_status == "":
+            status_text = run.status.status
+        else:
+            status_text = f"{run.status.status}:{run.status.sub_status}"
+
+        # Convert isoformat to datetime
+        pending_at = datetime.fromisoformat(run.pending_at) if run.pending_at else None
+        starting_at = (
+            datetime.fromisoformat(run.starting_at) if run.starting_at else None
+        )
+        running_at = datetime.fromisoformat(run.running_at) if run.running_at else None
+        finished_at = (
+            datetime.fromisoformat(run.finished_at) if run.finished_at else None
+        )
+
+        # Calculate elapsed time
+        elapsed_time = timedelta()
+        if running_at:
+            if finished_at:
+                end_time = finished_at
+            else:
+                end_time = datetime.fromisoformat(now_isoformat)
+            elapsed_time = end_time - running_at
+
+        row = RunRow(
+            run_id=run.run_id,
+            federation=run.federation,
+            fab_id=run.fab_id,
+            fab_version=run.fab_version,
+            fab_hash=run.fab_hash,
+            status_text=status_text,
+            elapsed=format_timedelta(elapsed_time),
+            pending_at=_format_datetime(pending_at),
+            starting_at=_format_datetime(starting_at),
+            running_at=_format_datetime(running_at),
+            finished_at=_format_datetime(finished_at),
+        )
+        run_list.append(row)
+    return run_list