flwr-nightly 1.26.0.dev20251226__py3-none-any.whl → 1.26.0.dev20260121__py3-none-any.whl

flwr/app/__init__.py

@@ -15,7 +15,6 @@
 """Public Flower App APIs."""
 
 
-from flwr.common.constant import MessageType
 from flwr.common.context import Context
 from flwr.common.message import Message
 from flwr.common.record import (
@@ -27,7 +26,9 @@ from flwr.common.record import (
 )
 
 from .error import Error
+from .message_type import MessageType
 from .metadata import Metadata
+from .user_config import UserConfig, UserConfigValue
 
 __all__ = [
     "Array",
@@ -40,4 +41,6 @@ __all__ = [
     "Metadata",
     "MetricRecord",
     "RecordDict",
+    "UserConfig",
+    "UserConfigValue",
 ]

flwr/app/message_type.py

@@ -0,0 +1,29 @@
+# Copyright 2026 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.
+# ==============================================================================
+"""MessageType constants."""
+
+from __future__ import annotations
+
+
+class MessageType:
+    """Message type."""
+
+    TRAIN = "train"
+    EVALUATE = "evaluate"
+    QUERY = "query"
+
+    def __new__(cls) -> MessageType:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")

flwr/app/metadata.py

@@ -19,7 +19,10 @@ from __future__ import annotations
 
 from typing import cast
 
-from ..common.constant import MessageType, MessageTypeLegacy
+from flwr.app.message_type import MessageType
+from flwr.supercore.constant import SYSTEM_MESSAGE_TYPE
+
+from ..common.constant import MessageTypeLegacy
 
 
 class Metadata:  # pylint: disable=too-many-instance-attributes
@@ -194,7 +197,7 @@ def validate_message_type(message_type: str) -> bool:
         MessageType.TRAIN,
         MessageType.EVALUATE,
         MessageType.QUERY,
-        MessageType.SYSTEM,
+        SYSTEM_MESSAGE_TYPE,
     }
     if message_type in valid_types:
         return True

flwr/app/user_config.py

@@ -0,0 +1,19 @@
+# Copyright 2026 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.
+# ==============================================================================
+"""UserConfig type definition."""
+
+
+UserConfigValue = bool | float | int | str
+UserConfig = dict[str, UserConfigValue]

flwr/cli/app.py

@@ -14,6 +14,9 @@
 # ==============================================================================
 """Flower command line interface."""
 
+
+from typing import Any, TypedDict
+
 import typer
 from typer.main import get_command
 
@@ -22,8 +25,9 @@ from flwr.supercore.version import package_version
 from .app_cmd import publish as app_publish
 from .app_cmd import review as app_review
 from .build import build
+from .config import ls as config_list
 from .federation import ls as federation_list
-from .federation import show as federation_show
+from .flower_config import init_flwr_config
 from .install import install
 from .log import log
 from .login import login
@@ -36,6 +40,15 @@ from .supernode import ls as supernode_list
 from .supernode import register as supernode_register
 from .supernode import unregister as supernode_unregister
 
+
+class CommandKwargs(TypedDict):
+    """Keywords for typer command to make mypy happy."""
+
+    context_settings: dict[str, Any]
+
+
+ALLOW_EXTRAS: CommandKwargs = {"context_settings": {"allow_extra_args": True}}
+
 app = typer.Typer(
     help=typer.style(
         "flwr is the Flower command line interface.",
@@ -50,12 +63,12 @@ app.command()(new)
 app.command()(run)
 app.command()(build)
 app.command()(install)
-app.command()(log)
-app.command("list")(ls)
-app.command(hidden=True)(ls)
-app.command()(stop)
+app.command(**ALLOW_EXTRAS)(log)
+app.command("list", **ALLOW_EXTRAS)(ls)
+app.command(hidden=True, **ALLOW_EXTRAS)(ls)
+app.command(**ALLOW_EXTRAS)(stop)
 app.command()(login)
-app.command()(pull)
+app.command(**ALLOW_EXTRAS)(pull)
 
 # Create supernode command group
 supernode_app = typer.Typer(help="Manage SuperNodes")
@@ -80,14 +93,20 @@ federation_app.command("list")(federation_list)
 # Hide "ls" command (left as alias)
 federation_app.command(hidden=True)(federation_list)
 app.add_typer(federation_app, name="federation")
-federation_app.command()(federation_show)
+
+# Create config command group
+config_app = typer.Typer(help="Manage Configuration")
+config_app.command("list")(config_list)
+# Hide "ls" command (left as alias)
+config_app.command(hidden=True)(config_list)
+app.add_typer(config_app, name="config")
 
 typer_click_object = get_command(app)
 
 
 @app.callback(invoke_without_command=True)
-def version_callback(
-    ver: bool = typer.Option(
+def main(
+    version: bool = typer.Option(
         None,
         "-V",
         "--version",
@@ -95,8 +114,9 @@ def version_callback(
         help="Show the version and exit.",
     ),
 ) -> None:
-    """Print version."""
-    if ver:
+    """Flower CLI."""
+    init_flwr_config()
+    if version:
         typer.secho(f"Flower version: {package_version}", fg="blue")
         raise typer.Exit()
 

flwr/cli/auth_plugin/oidc_cli_plugin.py

@@ -17,6 +17,7 @@
 
 import json
 import time
+import webbrowser
 from collections.abc import Sequence
 from pathlib import Path
 from typing import Any
@@ -75,11 +76,17 @@ class OidcCliPlugin(CliAuthPlugin):
         LoginError
             If authentication times out.
         """
+        # Prompt user to login via browser
+        webbrowser.open(login_details.verification_uri_complete)
         typer.secho(
-            "Please log into your Flower account here: "
+            "A browser window has been opened for you to "
+            "log into your Flower account.\n"
+            "If it did not open automatically, use this URL:\n"
             f"{login_details.verification_uri_complete}",
             fg=typer.colors.BLUE,
         )
+
+        # Wait for user to complete login
         start_time = time.time()
         time.sleep(login_details.interval)
 

flwr/cli/config/__init__.py

@@ -0,0 +1,21 @@
+# Copyright 2026 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 `config` command."""
+
+from .ls import ls as ls
+
+__all__ = [
+    "ls",
+]

flwr/cli/config/ls.py

@@ -0,0 +1,104 @@
+# Copyright 2026 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 `config list` command."""
+
+
+import io
+import json
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from flwr.common.constant import CliOutputFormat
+from flwr.common.logger import print_json_error, redirect_output, restore_output
+
+from ..constant import SuperLinkConnectionTomlKey
+from ..flower_config import read_flower_config
+
+
+def ls(
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            case_sensitive=False,
+            help="Format output using 'default' view or 'json'",
+        ),
+    ] = CliOutputFormat.DEFAULT,
+) -> None:
+    """List all SuperLink connections."""
+    suppress_output = output_format == CliOutputFormat.JSON
+    captured_output = io.StringIO()
+    config_path = None
+
+    if suppress_output:
+        redirect_output(captured_output)
+
+    try:
+        # Load Flower Config
+        config, config_path = read_flower_config()
+
+        # Get `superlink` tables
+        superlink_connections = config.get(SuperLinkConnectionTomlKey.SUPERLINK, {})
+
+        # Get default, then pop from dict
+        default = superlink_connections.pop(SuperLinkConnectionTomlKey.DEFAULT, None)
+
+        connection_names = list(superlink_connections.keys())
+        restore_output()
+        if output_format == CliOutputFormat.JSON:
+            conn = {
+                SuperLinkConnectionTomlKey.SUPERLINK: connection_names,
+                SuperLinkConnectionTomlKey.DEFAULT: default,
+            }
+            Console().print_json(json.dumps(conn))
+        else:
+            typer.secho("SuperLink connections:", fg=typer.colors.BLUE)
+            # List SuperLink connections and highlight default
+            for k in connection_names:
+                typer.secho(f"  {k}", fg=typer.colors.GREEN, nl=False)
+                if k == default:
+                    typer.secho(
+                        f" ({SuperLinkConnectionTomlKey.DEFAULT})",
+                        fg=typer.colors.WHITE,
+                        nl=False,
+                    )
+                typer.echo()
+    except typer.Exit as err:
+        # log the error if json format requested
+        # else do nothing since it will be logged by typer
+        if suppress_output:
+            restore_output()
+            e_message = captured_output.getvalue()
+            print_json_error(e_message, err)
+
+    except 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"❌ An unexpected error occurred while listing the SuperLink "
+                f"connections in the Flower configuration file ({config_path}): {err}",
+                fg=typer.colors.RED,
+                err=True,
+            )
+
+    finally:
+        if suppress_output:
+            restore_output()
+        captured_output.close()

flwr/cli/config_migration.py

@@ -0,0 +1,300 @@
+# Copyright 2026 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.
+# ==============================================================================
+"""Utilities for migrating old TOML configurations to Flower config."""
+
+
+import re
+from pathlib import Path
+from typing import Any
+
+import click
+import typer
+
+from .config_utils import load_and_validate, validate_federation_in_project_config
+from .flower_config import (
+    init_flwr_config,
+    parse_superlink_connection,
+    set_default_superlink_connection,
+    write_superlink_connection,
+)
+
+CONFIG_MIGRATION_NOTICE = """
+##################################################################
+# CONFIGURATION MIGRATION NOTICE:
+#
+# What was previously called "federation config" for SuperLink
+# connections in pyproject.toml has been renamed and moved.
+#
+# These settings are now **SuperLink connection configuration**
+# and are defined in the Flower configuration file.
+#
+# The entries below are commented out intentionally and are kept
+# only as a migration reference.
+#
+# Docs: <link to Flower config docs>
+##################################################################
+
+"""
+
+CLI_NOTICE = (
+    typer.style("\n🌸 Heads up from Flower!\n\n", fg=typer.colors.MAGENTA, bold=True)
+    + "We detected legacy usage of this command that relies on connection\n"
+    + "settings from your pyproject.toml.\n\n"
+    + "Flower will migrate any relevant settings to the new Flower config.\n\n"
+    + "Learn more: https://flower.ai/docs\n"
+)
+
+
+def _is_legacy_usage(positional_arg_1: str | None, args: list[str]) -> bool:
+    """Check if legacy usage is detected in the given arguments."""
+    if positional_arg_1 is None:
+        return False
+
+    # If one and only one extra argument is given, assume legacy usage
+    if len(args) == 1:
+        return True
+
+    # If the first positional argument looks like a path, assume legacy usage
+    pth = Path(positional_arg_1)
+    if pth.is_absolute() or len(pth.parts) > 1 or positional_arg_1 in (".", ".."):
+        return True
+
+    # Lastly, check if a pyproject.toml file exists at the given path
+    if (pth / "pyproject.toml").exists():
+        return True
+
+    return False
+
+
+def _is_migratable(app: Path) -> tuple[bool, str | None]:
+    """Check if the given app path contains legacy TOML configuration.
+
+    Parameters
+    ----------
+    app : Path
+        Path to the Flower App.
+
+    Returns
+    -------
+    tuple[bool, str | None]
+        Returns (True, None) if migratable, else (False, reason).
+    """
+    toml_path = app / "pyproject.toml"
+    if not toml_path.exists():
+        return False, f"No pyproject.toml found in '{app}'"
+    config, errors, _ = load_and_validate(toml_path, check_module=False)
+    if config is None:
+        return False, f"Failed to load TOML configuration: {toml_path}"
+    if errors:
+        err_msg = f"Invalid TOML configuration found in '{toml_path}':\n"
+        err_msg += "\n".join(f"- {err}" for err in errors)
+        return False, err_msg
+    try:
+        _ = config["tool"]["flwr"]["federations"]
+        return True, None
+    except KeyError:
+        return False, f"No '[tool.flwr.federations]' section found in '{toml_path}'"
+
+
+def _migrate_pyproject_toml_to_flower_config(
+    app: Path, toml_federation: str | None
+) -> tuple[list[str], str | None]:
+    """Migrate old TOML configuration to Flower config."""
+    # Load and validate the old TOML configuration
+    toml_path = app / "pyproject.toml"
+    config, _, _ = load_and_validate(toml_path, check_module=False)
+    if config is None:
+        raise ValueError(f"Failed to load TOML configuration: {toml_path}")
+    validate_federation_in_project_config(toml_federation, config)
+
+    # Construct SuperLinkConnection
+    toml_federations: dict[str, Any] = config["tool"]["flwr"]["federations"]
+    migrated_conn_names: list[str] = []
+    for name, toml_fed_config in toml_federations.items():
+        if isinstance(toml_fed_config, dict):
+            # Resolve relative root-certificates path
+            if cert_path := toml_fed_config.get("root-certificates"):
+                if not Path(cert_path).is_absolute():
+                    toml_fed_config["root-certificates"] = str(
+                        (app / cert_path).resolve()
+                    )
+            # Parse and write SuperLink connection
+            conn = parse_superlink_connection(toml_fed_config, name)
+            write_superlink_connection(conn)
+            migrated_conn_names.append(name)
+
+    # Set default federation if applicable
+    default_toml_federation: str | None = toml_federations.get("default")
+    if default_toml_federation in toml_federations:
+        set_default_superlink_connection(default_toml_federation)
+
+    return migrated_conn_names, default_toml_federation
+
+
+def _comment_out_legacy_toml_config(app: Path) -> None:
+    """Comment out legacy TOML configuration in pyproject.toml."""
+    # Read pyproject.toml lines
+    toml_path = app / "pyproject.toml"
+    lines = toml_path.read_text(encoding="utf-8").splitlines(keepends=True)
+    section_pattern = re.compile(r"\s*\[(.*)\]")
+
+    # Comment out the [tool.flwr.federations] section
+    notice_added = False
+    in_federation_section = False
+    with toml_path.open("w", encoding="utf-8") as f:
+        for line in lines:
+            # Detect section headers
+            if match := section_pattern.match(line):
+                section = match.group(1)
+                in_federation_section = section.startswith("tool.flwr.federations")
+
+            # Comment out lines in the federation section
+            if in_federation_section:
+                if not notice_added:
+                    f.write(CONFIG_MIGRATION_NOTICE)
+                    notice_added = True
+                # Preserve empty lines and comment out others
+                f.write(f"# {line}" if line.strip() != "" else line)
+            else:
+                f.write(line)
+
+
+def migrate(
+    positional_arg_1: str | None,
+    args: list[str],
+    ignore_legacy_usage: bool = False,
+) -> None:
+    """Migrate legacy TOML configuration to Flower config.
+
+    Migrates SuperLink connection settings from `[tool.flwr.federations]` in
+    pyproject.toml to the new Flower config format when legacy usage is detected
+    or the migration is applicable.
+
+    `flwr run` should call `migrate(app, [], ignore_legacy_usage=True)` to skip
+    legacy usage check. Other CLI commands should call `migrate(superlink, ctx.args)`.
+
+    Parameters
+    ----------
+    positional_arg_1 : str | None
+        The first positional argument.
+    args : list[str]
+        Additional arguments. In legacy usage, this is the TOML federation name.
+    ignore_legacy_usage : bool (default: False)
+        Set to `True` only for `flwr run` command to skip legacy usage check.
+
+    Raises
+    ------
+    click.UsageError
+        If more than one extra argument is provided.
+    click.ClickException
+        If legacy usage detected but migration fails.
+
+    Examples
+    --------
+    The following usages will trigger migration if applicable:
+    - `flwr <CMD> . my-federation`
+    - `flwr <CMD> ./my-app`
+    - `flwr <CMD>`
+
+    The following usages will NOT trigger migration:
+    - `flwr <CMD> named-conn`
+
+    Notes
+    -----
+    This function will NOT return when legacy usage is detected to force the user
+    to adapt to the new usage pattern after migration.
+    """
+    # Initialize Flower config
+    init_flwr_config()
+
+    # Trigger the same typer error when detecting unexpected extra args
+    if len(args) > 1:
+        raise click.UsageError(f"Got unexpected extra arguments ({' '.join(args[1:])})")
+
+    # Determine app path for migration
+    arg1 = positional_arg_1
+    app = Path(arg1) if arg1 else Path(".")
+    app = app.resolve()
+
+    # Check if migration is applicable and if legacy usage is detected
+    is_migratable, reason = _is_migratable(app)
+    is_legacy = _is_legacy_usage(arg1, args) if not ignore_legacy_usage else False
+
+    # Print notice once if legacy usage detected or migration is applicable
+    if is_legacy or is_migratable:
+        typer.echo(CLI_NOTICE)
+
+    if not is_migratable:
+        # Raise error if legacy usage is detected but migration is not applicable
+        if is_legacy:
+            raise click.ClickException(
+                f"Cannot migrate configuration:\n{reason}. \nThis is expected if the "
+                "migration has been previously carried out. Use `--help` after your "
+                "command to see the new usage pattern."
+            )
+        return  # Nothing to migrate
+
+    # Perform migration
+    toml_federation = args[0] if len(args) == 1 else None
+    try:
+        migrated_conns, default_conn = _migrate_pyproject_toml_to_flower_config(
+            app, toml_federation
+        )
+    except Exception as e:
+        raise click.ClickException(
+            f"Failed to migrate legacy TOML configuration to Flower config:\n{e!r}"
+        ) from e
+
+    typer.secho("✅ Migration completed successfully!\n", fg=typer.colors.GREEN)
+
+    # Print migrated connections
+    typer.secho("Migrated SuperLink connections:", fg=typer.colors.BLUE)
+    for conn_name in migrated_conns:
+        typer.secho(f"  {conn_name}", fg=typer.colors.GREEN, nl=False)
+        if conn_name == default_conn:
+            typer.secho(" (default)", fg=typer.colors.WHITE, nl=False)
+        typer.echo()
+
+    _comment_out_legacy_toml_config(app)
+
+    if is_legacy:
+        # print usage
+        typer.secho("\nYou should now use the Flower CLI as follows:")
+        ctx = click.get_current_context()
+        typer.secho(ctx.get_usage() + "\n", bold=True)
+
+        # Abort if legacy usage is detected to force user to adapt to new usage
+        raise typer.Exit(code=1)
+
+
+def warn_if_federation_config_overrides(
+    federation_config_overrides: list[str] | None,
+) -> None:
+    """Warn if federation config overrides are provided.
+
+    Parameters
+    ----------
+    federation_config_overrides : list[str] | None
+        List of federation config override strings.
+    """
+    if federation_config_overrides is None:
+        return
+
+    typer.secho(
+        "⚠️ Warning: `--federation-config` option is deprecated and will be ignored.\n"
+        "Use Flower configuration files to set SuperLink connections.",
+        fg=typer.colors.YELLOW,
+        bold=True,
+    )