flwr-nightly 1.23.0.dev20251004__py3-none-any.whl → 1.23.0.dev20251006__py3-none-any.whl

flwr/cli/supernode/ls.py

@@ -15,10 +15,16 @@
 """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
+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,
@@ -26,10 +32,23 @@ from flwr.cli.config_utils import (
     process_loaded_project_config,
     validate_federation_in_project_config,
 )
-from flwr.common.constant import FAB_CONFIG_FILE
+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"),
@@ -38,14 +57,202 @@ def ls(  # pylint: disable=R0914
         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."""
-    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+    # 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
+            )
 
-    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
+        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
     )
-    exit_if_no_address(federation_config, "supernode ls")
+    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/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/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/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.dev20251004.dist-info → flwr_nightly-1.23.0.dev20251006.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.23.0.dev20251004
+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.dev20251004.dist-info → flwr_nightly-1.23.0.dev20251006.dist-info}/RECORD

@@ -89,7 +89,7 @@ flwr/cli/stop.py,sha256=TR9F61suTxNUzGIktUdoBhXwdRtCdvzGhy3qCuvcfBg,5000
 flwr/cli/supernode/__init__.py,sha256=DVrTcyCg9NFll6glPLAAA6WPi7boxu6pFY_PRqIyHMk,893
 flwr/cli/supernode/create.py,sha256=MloB7Rr-CE_37jH5lFoM8OsaSPUzWt0TSSB_GMwND5E,1959
 flwr/cli/supernode/delete.py,sha256=_oCfBnoeUFPLEq_1EAqQp_CHEdzIEP2N_vHZsFTgWn0,1958
-flwr/cli/supernode/ls.py,sha256=j850KQEMpS0rdpL8m9icx7DlRMDRtns6I_iTwUudC_0,1801
+flwr/cli/supernode/ls.py,sha256=KZZHQczmXi4vmgMJlBntD893fYQ9a7ZJum-8K_BPWAw,8550
 flwr/cli/utils.py,sha256=3bCu_MndtJD2S5MPG9VKi7SxG0No8S651pcfBVb29Y8,14397
 flwr/client/__init__.py,sha256=Q0MIF442vLIGSkcwHKq_sIfECQynLARJrumAscq2Q6E,1241
 flwr/client/client.py,sha256=3HAchxvknKG9jYbB7swNyDj-e5vUWDuMKoLvbT7jCVM,7895
@@ -223,8 +223,8 @@ flwr/proto/message_pb2.py,sha256=giymevXYEUdpIO-3A0XKsmRabXW1xSz0sIo5oOlbQ8Y,519
 flwr/proto/message_pb2.pyi,sha256=EzXZHy2mtabofrd_ZgKSI6M4QH-soIaRZIZBPwBGPv0,11260
 flwr/proto/message_pb2_grpc.py,sha256=1oboBPFxaTEXt9Aw7EAj8gXHDCNMhZD2VXqocC9l_gk,159
 flwr/proto/message_pb2_grpc.pyi,sha256=ff2TSiLVnG6IVQcTGzb2DIH3XRSoAvAo_RMcvbMFyc0,76
-flwr/proto/node_pb2.py,sha256=gvFzmkEBB4Prp9y27RZKDoy1O5r56GqN-wpCdjoW5BA,1508
-flwr/proto/node_pb2.pyi,sha256=THEURTmlD-23XOULcu2AH6Mvy7pl2N9eWUSntCutO8o,2060
+flwr/proto/node_pb2.py,sha256=_5UD-yH9Y-qtAP-gO3LZeDH_WoSFfjXmNvngsb9G-YM,1534
+flwr/proto/node_pb2.pyi,sha256=kmLGmDIqudRtveUop_uVU6w696ahPB_b-O94k3HQIpU,2226
 flwr/proto/node_pb2_grpc.py,sha256=1oboBPFxaTEXt9Aw7EAj8gXHDCNMhZD2VXqocC9l_gk,159
 flwr/proto/node_pb2_grpc.pyi,sha256=ff2TSiLVnG6IVQcTGzb2DIH3XRSoAvAo_RMcvbMFyc0,76
 flwr/proto/recorddict_pb2.py,sha256=eVkcnxMTFa3rvknRNiFuJ8z8xxPqgw7bV04aFiTe1j4,5290
@@ -413,7 +413,7 @@ flwr/superlink/servicer/control/control_account_auth_interceptor.py,sha256=Tbi4W
 flwr/superlink/servicer/control/control_event_log_interceptor.py,sha256=5uBl6VcJlUOgCF0d4kmsmJc1Rs1qxyouaZv0-uH2axs,5969
 flwr/superlink/servicer/control/control_grpc.py,sha256=xajQdX9WuKJmyXZJOaMZKeiSwgSCrile1NOErOiXR5w,4270
 flwr/superlink/servicer/control/control_license_interceptor.py,sha256=T3AzmRt-PPwyTq3hrdpmZHQd5_CpPOk7TtnFZrB-JRY,3349
-flwr/superlink/servicer/control/control_servicer.py,sha256=KUj45Fu5d6jugLWBkWzPre0l3TqD13NYQCWr-KeiSZ0,17134
+flwr/superlink/servicer/control/control_servicer.py,sha256=DJaHBHNRS_9UVuqAk9ELu-1IfmFNVbt3SilYG1awaXQ,19092
 flwr/supernode/__init__.py,sha256=KgeCaVvXWrU3rptNR1y0oBp4YtXbAcrnCcJAiOoWkI4,707
 flwr/supernode/cli/__init__.py,sha256=JuEMr0-s9zv-PEWKuLB9tj1ocNfroSyNJ-oyv7ati9A,887
 flwr/supernode/cli/flower_supernode.py,sha256=7aBm0z03OU-npVd1onLCvUotyhSvlZLxAnFkGVMhZcw,8670
@@ -428,7 +428,7 @@ flwr/supernode/servicer/__init__.py,sha256=lucTzre5WPK7G1YLCfaqg3rbFWdNSb7ZTt-ca
 flwr/supernode/servicer/clientappio/__init__.py,sha256=7Oy62Y_oijqF7Dxi6tpcUQyOpLc_QpIRZ83NvwmB0Yg,813
 flwr/supernode/servicer/clientappio/clientappio_servicer.py,sha256=nIHRu38EWK-rpNOkcgBRAAKwYQQWFeCwu0lkO7OPZGQ,10239
 flwr/supernode/start_client_internal.py,sha256=Y9S1-QlO2WP6eo4JvWzIpfaCoh2aoE7bjEYyxNNnlyg,20777
-flwr_nightly-1.23.0.dev20251004.dist-info/METADATA,sha256=FPuw2y1PTpLtwP57ebIlqnjcBAPRKdklE0aTY43CYRE,14559
-flwr_nightly-1.23.0.dev20251004.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-flwr_nightly-1.23.0.dev20251004.dist-info/entry_points.txt,sha256=hxHD2ixb_vJFDOlZV-zB4Ao32_BQlL34ftsDh1GXv14,420
-flwr_nightly-1.23.0.dev20251004.dist-info/RECORD,,
+flwr_nightly-1.23.0.dev20251006.dist-info/METADATA,sha256=BcU_7czuKJh5AnBvuRlID49gmN3-GSBQ01gQ2KtmLBQ,14559
+flwr_nightly-1.23.0.dev20251006.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+flwr_nightly-1.23.0.dev20251006.dist-info/entry_points.txt,sha256=hxHD2ixb_vJFDOlZV-zB4Ao32_BQlL34ftsDh1GXv14,420
+flwr_nightly-1.23.0.dev20251006.dist-info/RECORD,,