flwr-nightly 1.23.0.dev20251005__tar.gz → 1.23.0.dev20251006__tar.gz

{flwr_nightly-1.23.0.dev20251005 → flwr_nightly-1.23.0.dev20251006}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.23.0.dev20251005
+Version: 1.23.0.dev20251006
 Summary: Flower: A Friendly Federated AI Framework
 License: Apache-2.0
 Keywords: Artificial Intelligence,Federated AI,Federated Analytics,Federated Evaluation,Federated Learning,Flower,Machine Learning

flwr_nightly-1.23.0.dev20251006/py/flwr/cli/supernode/ls.py

@@ -0,0 +1,258 @@
+# 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 `supernode list` command."""
+
+
+import io
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Annotated, Optional, cast
+
+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,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat
+from flwr.common.date import format_timedelta, isoformat8601_utc
+from flwr.common.logger import print_json_error, redirect_output, restore_output
+from flwr.proto.control_pb2 import (  # pylint: disable=E0611
+    ListNodesCliRequest,
+    ListNodesCliResponse,
+)
+from flwr.proto.control_pb2_grpc import ControlStub
+from flwr.proto.node_pb2 import NodeInfo  # pylint: disable=E0611
+
+from ..utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
+
+_NodeListType = tuple[int, str, str, str, str, str, str, str]
+
+
+def ls(  # pylint: disable=R0914
+    ctx: typer.Context,
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation"),
+    ] = None,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            case_sensitive=False,
+            help="Format output using 'default' view or 'json'",
+        ),
+    ] = CliOutputFormat.DEFAULT,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable verbose output",
+        ),
+    ] = False,
+) -> None:
+    """List SuperNodes in the federation."""
+    # Resolve command used (list or ls)
+    command_name = cast(str, ctx.command.name) if ctx.command else "ls"
+
+    suppress_output = output_format == CliOutputFormat.JSON
+    captured_output = io.StringIO()
+    try:
+        if suppress_output:
+            redirect_output(captured_output)
+        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
+        )
+        exit_if_no_address(federation_config, f"supernode {command_name}")
+        channel = None
+        try:
+            auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
+            channel = init_channel(app, federation_config, auth_plugin)
+            stub = ControlStub(channel)
+            typer.echo("📄 Listing all nodes...")
+            formatted_nodes = _list_nodes(stub)
+            restore_output()
+            if output_format == CliOutputFormat.JSON:
+                Console().print_json(_to_json(formatted_nodes, verbose=verbose))
+            else:
+                Console().print(_to_table(formatted_nodes, verbose=verbose))
+
+        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.secho(
+                f"{err}",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+    finally:
+        if suppress_output:
+            restore_output()
+        captured_output.close()
+
+
+def _list_nodes(stub: ControlStub) -> list[_NodeListType]:
+    """List all nodes."""
+    with flwr_cli_grpc_exc_handler():
+        res: ListNodesCliResponse = stub.ListNodesCli(ListNodesCliRequest())
+
+    return _format_nodes(list(res.nodes_info), res.now)
+
+
+def _format_nodes(
+    nodes_info: list[NodeInfo], now_isoformat: str
+) -> list[_NodeListType]:
+    """Format node information for display."""
+
+    def _format_datetime(dt_str: Optional[str]) -> str:
+        dt = datetime.fromisoformat(dt_str) if dt_str else None
+        return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
+
+    formatted_nodes: list[_NodeListType] = []
+    # Add rows
+    for node in sorted(nodes_info, key=lambda x: datetime.fromisoformat(x.created_at)):
+
+        # Calculate elapsed times
+        elapsed_time_activated = timedelta()
+        if node.last_activated_at:
+            end_time = datetime.fromisoformat(now_isoformat)
+            elapsed_time_activated = end_time - datetime.fromisoformat(
+                node.last_activated_at
+            )
+
+        formatted_nodes.append(
+            (
+                node.node_id,
+                node.owner_aid,
+                node.status,
+                _format_datetime(node.created_at),
+                _format_datetime(node.last_activated_at),
+                _format_datetime(node.last_deactivated_at),
+                _format_datetime(node.deleted_at),
+                format_timedelta(elapsed_time_activated),
+            )
+        )
+
+    return formatted_nodes
+
+
+def _to_table(nodes_info: list[_NodeListType], verbose: bool) -> Table:
+    """Format the provided node list to a rich Table."""
+    table = Table(header_style="bold cyan", show_lines=True)
+
+    # Add columns
+    table.add_column(
+        Text("Node ID", justify="center"), style="bright_white", no_wrap=True
+    )
+    table.add_column(Text("Owner", justify="center"), style="dim white")
+    table.add_column(Text("Status", justify="center"))
+    table.add_column(Text("Elapsed", justify="center"))
+    table.add_column(Text("Status Changed @", justify="center"), style="dim white")
+
+    for row in nodes_info:
+        (
+            node_id,
+            owner_aid,
+            status,
+            _,
+            last_activated_at,
+            last_deactivated_at,
+            deleted_at,
+            elapse_activated,
+        ) = row
+
+        if status == "online":
+            status_style = "green"
+            time_at = last_activated_at
+        elif status == "offline":
+            status_style = "bright_yellow"
+            time_at = last_deactivated_at
+        elif status == "deleted":
+            if not verbose:
+                continue
+            status_style = "red"
+            time_at = deleted_at
+        elif status == "created":
+            status_style = "blue"
+            time_at = "N/A"
+        else:
+            raise ValueError(f"Unexpected node status '{status}'")
+
+        formatted_row = (
+            f"[bold]{node_id}[/bold]",
+            f"{owner_aid}",
+            f"[{status_style}]{status}",
+            f"[cyan]{elapse_activated}[/cyan]" if status == "online" else "",
+            time_at,
+        )
+        table.add_row(*formatted_row)
+
+    return table
+
+
+def _to_json(nodes_info: list[_NodeListType], verbose: bool) -> str:
+    """Format node list to a JSON formatted string."""
+    nodes_list = []
+    for row in nodes_info:
+        (
+            node_id,
+            owner_aid,
+            status,
+            created_at,
+            activated_at,
+            deactivated_at,
+            deleted_at,
+            elapse_activated,
+        ) = row
+
+        if status == "deleted" and not verbose:
+            continue
+
+        nodes_list.append(
+            {
+                "node-id": node_id,
+                "owner-aid": owner_aid,
+                "status": status,
+                "created-at": created_at,
+                "online-at": activated_at,
+                "online-elapsed": elapse_activated,
+                "offline-at": deactivated_at,
+                "deleted-at": deleted_at,
+            }
+        )
+
+    return json.dumps({"success": True, "nodes": nodes_list})

{flwr_nightly-1.23.0.dev20251005 → flwr_nightly-1.23.0.dev20251006}/py/flwr/proto/node_pb2.py

@@ -14,7 +14,7 @@ _sym_db = _symbol_database.Default()
 
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x15\x66lwr/proto/node.proto\x12\nflwr.proto\"\x17\n\x04Node\x12\x0f\n\x07node_id\x18\x01 \x01(\x04\"\xb6\x01\n\x08NodeInfo\x12\x0f\n\x07node_id\x18\x01 \x01(\x04\x12\x11\n\towner_aid\x18\x02 \x01(\t\x12\x12\n\ncreated_at\x18\x03 \x01(\t\x12\x14\n\x0c\x61\x63tivated_at\x18\x04 \x01(\t\x12\x16\n\x0e\x64\x65\x61\x63tivated_at\x18\x05 \x01(\t\x12\x12\n\ndeleted_at\x18\x06 \x01(\t\x12\x14\n\x0conline_until\x18\x07 \x01(\x02\x12\x1a\n\x12heartbeat_interval\x18\x08 \x01(\x02\x62\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x15\x66lwr/proto/node.proto\x12\nflwr.proto\"\x17\n\x04Node\x12\x0f\n\x07node_id\x18\x01 \x01(\x04\"\xd0\x01\n\x08NodeInfo\x12\x0f\n\x07node_id\x18\x01 \x01(\x04\x12\x11\n\towner_aid\x18\x02 \x01(\t\x12\x0e\n\x06status\x18\x03 \x01(\t\x12\x12\n\ncreated_at\x18\x04 \x01(\t\x12\x19\n\x11last_activated_at\x18\x05 \x01(\t\x12\x1b\n\x13last_deactivated_at\x18\x06 \x01(\t\x12\x12\n\ndeleted_at\x18\x07 \x01(\t\x12\x14\n\x0conline_until\x18\x08 \x01(\x02\x12\x1a\n\x12heartbeat_interval\x18\t \x01(\x02\x62\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
@@ -24,5 +24,5 @@ if _descriptor._USE_C_DESCRIPTORS == False:
   _globals['_NODE']._serialized_start=37
   _globals['_NODE']._serialized_end=60
   _globals['_NODEINFO']._serialized_start=63
-  _globals['_NODEINFO']._serialized_end=245
+  _globals['_NODEINFO']._serialized_end=271
 # @@protoc_insertion_point(module_scope)

{flwr_nightly-1.23.0.dev20251005 → flwr_nightly-1.23.0.dev20251006}/py/flwr/proto/node_pb2.pyi

@@ -25,17 +25,19 @@ class NodeInfo(google.protobuf.message.Message):
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
     NODE_ID_FIELD_NUMBER: builtins.int
     OWNER_AID_FIELD_NUMBER: builtins.int
+    STATUS_FIELD_NUMBER: builtins.int
     CREATED_AT_FIELD_NUMBER: builtins.int
-    ACTIVATED_AT_FIELD_NUMBER: builtins.int
-    DEACTIVATED_AT_FIELD_NUMBER: builtins.int
+    LAST_ACTIVATED_AT_FIELD_NUMBER: builtins.int
+    LAST_DEACTIVATED_AT_FIELD_NUMBER: builtins.int
     DELETED_AT_FIELD_NUMBER: builtins.int
     ONLINE_UNTIL_FIELD_NUMBER: builtins.int
     HEARTBEAT_INTERVAL_FIELD_NUMBER: builtins.int
     node_id: builtins.int
     owner_aid: typing.Text
+    status: typing.Text
     created_at: typing.Text
-    activated_at: typing.Text
-    deactivated_at: typing.Text
+    last_activated_at: typing.Text
+    last_deactivated_at: typing.Text
     deleted_at: typing.Text
     online_until: builtins.float
     heartbeat_interval: builtins.float
@@ -43,12 +45,13 @@ class NodeInfo(google.protobuf.message.Message):
         *,
         node_id: builtins.int = ...,
         owner_aid: typing.Text = ...,
+        status: typing.Text = ...,
         created_at: typing.Text = ...,
-        activated_at: typing.Text = ...,
-        deactivated_at: typing.Text = ...,
+        last_activated_at: typing.Text = ...,
+        last_deactivated_at: typing.Text = ...,
         deleted_at: typing.Text = ...,
         online_until: builtins.float = ...,
         heartbeat_interval: builtins.float = ...,
         ) -> None: ...
-    def ClearField(self, field_name: typing_extensions.Literal["activated_at",b"activated_at","created_at",b"created_at","deactivated_at",b"deactivated_at","deleted_at",b"deleted_at","heartbeat_interval",b"heartbeat_interval","node_id",b"node_id","online_until",b"online_until","owner_aid",b"owner_aid"]) -> None: ...
+    def ClearField(self, field_name: typing_extensions.Literal["created_at",b"created_at","deleted_at",b"deleted_at","heartbeat_interval",b"heartbeat_interval","last_activated_at",b"last_activated_at","last_deactivated_at",b"last_deactivated_at","node_id",b"node_id","online_until",b"online_until","owner_aid",b"owner_aid","status",b"status"]) -> None: ...
 global___NodeInfo = NodeInfo

{flwr_nightly-1.23.0.dev20251005 → flwr_nightly-1.23.0.dev20251006}/py/flwr/superlink/servicer/control/control_servicer.py

@@ -18,6 +18,7 @@
 import hashlib
 import time
 from collections.abc import Generator
+from datetime import timedelta
 from logging import ERROR, INFO
 from typing import Any, Optional, cast
 
@@ -65,6 +66,7 @@ from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     StreamLogsRequest,
     StreamLogsResponse,
 )
+from flwr.proto.node_pb2 import NodeInfo  # pylint: disable=E0611
 from flwr.server.superlink.linkstate import LinkState, LinkStateFactory
 from flwr.supercore.ffs import FfsFactory
 from flwr.supercore.object_store import ObjectStore, ObjectStoreFactory
@@ -418,7 +420,61 @@ class ControlServicer(control_pb2_grpc.ControlServicer):
     ) -> ListNodesCliResponse:
         """List all SuperNodes."""
         log(INFO, "ControlServicer.ListNodesCli")
-        return ListNodesCliResponse()
+
+        nodes_info = []
+        # A node created (but not connected)
+        nodes_info.append(
+            NodeInfo(
+                node_id=15390646978706312628,
+                owner_aid="owner_aid_1",
+                status="created",
+                created_at=(now()).isoformat(),
+                last_activated_at="",
+                last_deactivated_at="",
+                deleted_at="",
+            )
+        )
+
+        # A node created and connected
+        nodes_info.append(
+            NodeInfo(
+                node_id=2941141058168602545,
+                owner_aid="owner_aid_2",
+                status="online",
+                created_at=(now()).isoformat(),
+                last_activated_at=(now() + timedelta(hours=0.5)).isoformat(),
+                last_deactivated_at="",
+                deleted_at="",
+            )
+        )
+
+        # A node created and deleted (never connected)
+        nodes_info.append(
+            NodeInfo(
+                node_id=906971720890549292,
+                owner_aid="owner_aid_3",
+                status="deleted",
+                created_at=(now()).isoformat(),
+                last_activated_at="",
+                last_deactivated_at="",
+                deleted_at=(now() + timedelta(hours=1)).isoformat(),
+            )
+        )
+
+        # A node created, deactivate and then deleted
+        nodes_info.append(
+            NodeInfo(
+                node_id=1781174086018058152,
+                owner_aid="owner_aid_4",
+                status="offline",
+                created_at=(now()).isoformat(),
+                last_activated_at=(now() + timedelta(hours=0.5)).isoformat(),
+                last_deactivated_at=(now() + timedelta(hours=1)).isoformat(),
+                deleted_at=(now() + timedelta(hours=1.5)).isoformat(),
+            )
+        )
+
+        return ListNodesCliResponse(nodes_info=nodes_info, now=now().isoformat())
 
 
 def _create_list_runs_response(

{flwr_nightly-1.23.0.dev20251005 → flwr_nightly-1.23.0.dev20251006}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "flwr-nightly"
-version = "1.23.0.dev20251005"
+version = "1.23.0.dev20251006"
 description = "Flower: A Friendly Federated AI Framework"
 license = "Apache-2.0"
 authors = ["The Flower Authors <hello@flower.ai>"]

flwr_nightly-1.23.0.dev20251005/py/flwr/cli/supernode/ls.py

@@ -1,51 +0,0 @@
-# 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 `supernode list` command."""
-
-
-from pathlib import Path
-from typing import Annotated, Optional
-
-import typer
-
-from flwr.cli.config_utils import (
-    exit_if_no_address,
-    load_and_validate,
-    process_loaded_project_config,
-    validate_federation_in_project_config,
-)
-from flwr.common.constant import FAB_CONFIG_FILE
-
-
-def ls(  # pylint: disable=R0914
-    app: Annotated[
-        Path,
-        typer.Argument(help="Path of the Flower project"),
-    ] = Path("."),
-    federation: Annotated[
-        Optional[str],
-        typer.Argument(help="Name of the federation"),
-    ] = None,
-) -> None:
-    """List SuperNodes in the federation."""
-    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
-    )
-    exit_if_no_address(federation_config, "supernode ls")