flwr-nightly 1.26.0.dev20260117__py3-none-any.whl → 1.26.0.dev20260120__py3-none-any.whl

flwr/cli/config_migration.py

@@ -57,8 +57,11 @@ CLI_NOTICE = (
 )
 
 
-def _is_legacy_usage(superlink: str, args: list[str]) -> bool:
+def _is_legacy_usage(superlink: str | None, args: list[str]) -> bool:
     """Check if legacy usage is detected in the given arguments."""
+    if superlink is None:
+        return False
+
     # If one and only one extra argument is given, assume legacy usage
     if len(args) == 1:
         return True
@@ -75,26 +78,34 @@ def _is_legacy_usage(superlink: str, args: list[str]) -> bool:
     return False
 
 
-def _check_is_migratable(app: Path) -> None:
-    """Check if the given app path contains legacy TOML configuration."""
+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():
-        raise FileNotFoundError(f"No pyproject.toml found in '{app}'")
+        return False, f"No pyproject.toml found in '{app}'"
     config, errors, _ = load_and_validate(toml_path, check_module=False)
     if config is None:
-        raise ValueError(f"Failed to load TOML configuration: {toml_path}")
+        return False, f"Failed to load TOML configuration: {toml_path}"
     if errors:
-        raise ValueError(
-            f"Invalid TOML configuration found in '{toml_path}':\n"
-            + "\n".join(f"- {err}" for err in 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
+        return True, None
     except KeyError:
-        raise ValueError(
-            f"No '[tool.flwr.federations]' section found in '{toml_path}'"
-        ) from None
+        return False, f"No '[tool.flwr.federations]' section found in '{toml_path}'"
 
 
 def _migrate_pyproject_toml_to_flower_config(
@@ -161,23 +172,81 @@ def _comment_out_legacy_toml_config(app: Path) -> None:
 
 
 def migrate(
-    app: Path,
-    toml_federation: str | None,
+    superlink: str | None,
+    args: list[str],
+    ignore_legacy_usage: bool = False,
 ) -> None:
-    """Migrate legacy TOML configuration to Flower config."""
+    """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(superlink, [], ignore_legacy_usage=True)` to skip
+    legacy usage check. Other CLI commands should call `migrate(superlink, ctx.args)`.
+
+    Parameters
+    ----------
+    superlink : str | None
+        Value of the `[SUPERLINK]` argument provided to the CLI command.
+    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()
 
-    # Print migration notice
-    typer.echo(CLI_NOTICE)
+    # 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:])})")
 
-    # Check if migration is applicable
+    # Determine app path for migration
+    app = Path(superlink) if superlink else Path(".")
     app = app.resolve()
-    try:
-        _check_is_migratable(app)
-    except (FileNotFoundError, ValueError) as e:
-        raise click.ClickException(f"Cannot migrate configuration:\n{e}") from e
 
+    # Check if migration is applicable and if legacy usage is detected
+    is_migratable, reason = _is_migratable(app)
+    is_legacy = _is_legacy_usage(superlink, 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
@@ -197,29 +266,13 @@ def migrate(
             typer.secho(" (default)", fg=typer.colors.WHITE, nl=False)
         typer.echo()
 
-    # 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)
-
     _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)
 
-def migrate_if_legacy_usage(
-    superlink: str,
-    args: list[str],
-) -> None:
-    """Migrate legacy TOML configuration to Flower config if legacy usage is
-    detected."""
-    # 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:])})")
-
-    # Skip migration if no legacy usage is detected
-    if not _is_legacy_usage(superlink, args):
-        return
-
-    migrate(
-        app=Path(superlink),
-        toml_federation=args[0] if len(args) == 1 else None,
-    )
+        # Abort if legacy usage is detected to force user to adapt to new usage
+        raise typer.Exit(code=1)

flwr/cli/config_utils.py

@@ -307,16 +307,9 @@ def load_certificate_in_connection(
     typer.Exit
         If the configuration is invalid or the certificate file cannot be read.
     """
-    if connection.insecure is None:
-        raise ValueError(
-            f"SuperLink connection '{connection.name}' is missing insecure setting."
-        )
-
-    insecure = connection.insecure
-
     # Process root certificates
     if root_certificates := connection.root_certificates:
-        if insecure:
+        if connection.insecure:
             typer.secho(
                 "❌ `root-certificates` were provided but the `insecure` parameter "
                 "is set to `True`.",

flwr/cli/flower_config.py

@@ -215,11 +215,12 @@ def serialize_superlink_connection(connection: SuperLinkConnection) -> dict[str,
     dict[str, Any]
         Dictionary representation suitable for TOML serialization.
     """
+    # pylint: disable=protected-access
     conn_dict: dict[str, Any] = {
         SuperLinkConnectionTomlKey.ADDRESS: connection.address,
         SuperLinkConnectionTomlKey.ROOT_CERTIFICATES: connection.root_certificates,
-        SuperLinkConnectionTomlKey.INSECURE: connection.insecure,
-        SuperLinkConnectionTomlKey.ENABLE_ACCOUNT_AUTH: connection.enable_account_auth,
+        SuperLinkConnectionTomlKey.INSECURE: connection._insecure,
+        SuperLinkConnectionTomlKey.ENABLE_ACCOUNT_AUTH: connection._enable_account_auth,
         SuperLinkConnectionTomlKey.FEDERATION: connection.federation,
     }
     # Remove None values

flwr/cli/pull.py

@@ -40,10 +40,7 @@ from .utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
 def pull(  # pylint: disable=R0914
     run_id: Annotated[
         int,
-        typer.Option(
-            "--run-id",
-            help="Run ID to pull artifacts from.",
-        ),
+        typer.Argument(help="Run ID to pull artifacts from."),
     ],
     app: Annotated[
         Path,

flwr/cli/typing.py

@@ -23,6 +23,8 @@ from flwr.cli.constant import (
     SuperLinkConnectionTomlKey,
 )
 
+_ERROR_MSG_FMT = "SuperLinkConnection.%s is None"
+
 
 @dataclass
 class SimulationClientResources:
@@ -91,16 +93,70 @@ class SuperLinkSimulationOptions:
 
 @dataclass
 class SuperLinkConnection:
-    """SuperLink connection configuration for CLI commands."""
+    """SuperLink connection configuration for CLI commands.
+
+    Attributes
+    ----------
+    name : str
+         The name of the connection configuration.
+    address : str
+        The address of the SuperLink (Control API).
+    root_certificates : str
+         The absolute path to the root CA certificate file.
+    insecure : bool (default: False)
+         Whether to use an insecure channel. If True, the
+         connection will not use TLS encryption.
+    enable_account_auth : bool (default: False)
+         Whether to enable account authentication.
+    federation : str
+         The name of the federation to interface with.
+    options : SuperLinkSimulationOptions
+         Configuration options for the simulation runtime.
+    """
 
     name: str
     address: str | None = None
     root_certificates: str | None = None
-    insecure: bool | None = None
-    enable_account_auth: bool | None = None
+    _insecure: bool | None = None
+    _enable_account_auth: bool | None = None
     federation: str | None = None
     options: SuperLinkSimulationOptions | None = None
 
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def __init__(
+        self,
+        name: str,
+        address: str | None = None,
+        root_certificates: str | None = None,
+        insecure: bool | None = None,
+        enable_account_auth: bool | None = None,
+        federation: str | None = None,
+        options: SuperLinkSimulationOptions | None = None,
+    ) -> None:
+        self.name = name
+        self.address = address
+        self.root_certificates = root_certificates
+        self._insecure = insecure
+        self._enable_account_auth = enable_account_auth
+        self.federation = federation
+        self.options = options
+
+        self.__post_init__()
+
+    @property
+    def insecure(self) -> bool:
+        """Return the insecure flag or its default (False) if unset."""
+        if self._insecure is None:
+            return False
+        return self._insecure
+
+    @property
+    def enable_account_auth(self) -> bool:
+        """Return the enable_account_auth flag or its default (False) if unset."""
+        if self._enable_account_auth is None:
+            return False
+        return self._enable_account_auth
+
     def __post_init__(self) -> None:
         """Validate SuperLink connection configuration."""
         err_prefix = f"Invalid value for key '%s' in connection '{self.name}': "
@@ -126,17 +182,17 @@ class SuperLinkConnection:
                     f"'{self.root_certificates}'."
                 )
 
-        if self.insecure is not None and not isinstance(self.insecure, bool):
+        if self._insecure is not None and not isinstance(self._insecure, bool):
             raise ValueError(
                 err_prefix % SuperLinkConnectionTomlKey.INSECURE
-                + f"expected bool, but got {type(self.insecure).__name__}."
+                + f"expected bool, but got {type(self._insecure).__name__}."
             )
-        if self.enable_account_auth is not None and not isinstance(
-            self.enable_account_auth, bool
+        if self._enable_account_auth is not None and not isinstance(
+            self._enable_account_auth, bool
         ):
             raise ValueError(
                 err_prefix % SuperLinkConnectionTomlKey.ENABLE_ACCOUNT_AUTH
-                + f"expected bool, but got {type(self.enable_account_auth).__name__}."
+                + f"expected bool, but got {type(self._enable_account_auth).__name__}."
             )
 
         if self.federation is not None and not isinstance(self.federation, str):

flwr/cli/utils.py

@@ -458,13 +458,17 @@ def init_channel(
     return channel
 
 
-def init_channel_from_connection(connection: SuperLinkConnection) -> grpc.Channel:
+def init_channel_from_connection(
+    connection: SuperLinkConnection, auth_plugin: CliAuthPlugin | None = None
+) -> grpc.Channel:
     """Initialize gRPC channel to the Control API.
 
     Parameters
     ----------
     connection : SuperLinkConnection
         SuperLink connection configuration.
+    auth_plugin : CliAuthPlugin | None (default: None)
+        Authentication plugin instance for handling credentials.
 
     Returns
     -------
@@ -474,21 +478,15 @@ def init_channel_from_connection(connection: SuperLinkConnection) -> grpc.Channe
     root_certificates_bytes = load_certificate_in_connection(connection)
 
     # Load authentication plugin
-    auth_plugin = load_cli_auth_plugin_from_connection(connection)
+    if auth_plugin is None:
+        auth_plugin = load_cli_auth_plugin_from_connection(connection)
 
     # Load tokens
     auth_plugin.load_tokens()
 
-    # Ensure address and insecure are set
-    if connection.address is None or connection.insecure is None:
-        raise ValueError(
-            f"Couldn't create channel. SuperLink connection '{connection.name}'"
-            " is missing address or insecure setting."
-        )
-
     # Create the gRPC channel
     channel = create_channel(
-        server_address=connection.address,
+        server_address=connection.address,  # type: ignore
         insecure=connection.insecure,
         root_certificates=root_certificates_bytes,
         max_message_length=GRPC_MAX_MESSAGE_LENGTH,

flwr/supercore/constant.py

@@ -64,6 +64,16 @@ MESSAGE_TIME_ENTRY_MAX_AGE_SECONDS = 3600
 # System message type
 SYSTEM_MESSAGE_TYPE = "system"
 
+# SQLite PRAGMA settings for optimal performance and correctness
+SQLITE_PRAGMAS = (
+    ("journal_mode", "WAL"),  # Enable Write-Ahead Logging for better concurrency
+    ("synchronous", "NORMAL"),
+    ("foreign_keys", "ON"),
+    ("cache_size", "-64000"),  # 64MB cache
+    ("temp_store", "MEMORY"),  # In-memory temp tables
+    ("mmap_size", "268435456"),  # 256MB memory-mapped I/O
+)
+
 
 class NodeStatus:
     """Event log writer types."""

flwr/supercore/credential_store/__init__.py

@@ -0,0 +1,33 @@
+# 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.
+# ==============================================================================
+"""Credential store for Flower."""
+
+
+from .credential_store import CredentialStore
+from .file_credential_store import FileCredentialStore
+
+
+def get_credential_store() -> CredentialStore:
+    """Get the credential store instance.
+
+    Currently, only FileCredentialStore is implemented.
+    """
+    return FileCredentialStore()
+
+
+__all__ = [
+    "CredentialStore",
+    "get_credential_store",
+]

flwr/supercore/credential_store/credential_store.py

@@ -0,0 +1,34 @@
+# 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.
+# ==============================================================================
+"""Abstract base classes for credential store."""
+
+
+from abc import ABC, abstractmethod
+
+
+class CredentialStore(ABC):
+    """Abstract base class for credential store."""
+
+    @abstractmethod
+    def set(self, key: str, value: bytes) -> None:
+        """Set a credential in the store."""
+
+    @abstractmethod
+    def get(self, key: str) -> bytes | None:
+        """Get a credential from the store."""
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete a credential from the store."""

flwr/supercore/credential_store/file_credential_store.py

@@ -0,0 +1,76 @@
+# 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.
+# ==============================================================================
+"""File-based credential store implementation."""
+
+
+import base64
+from pathlib import Path
+from typing import cast
+
+import yaml
+
+from ..utils import get_flwr_home
+from .credential_store import CredentialStore
+
+CREDENTIAL_FILE_PATH = get_flwr_home() / "credentials.yaml"
+
+
+class FileCredentialStore(CredentialStore):
+    """File-based credential store implementation."""
+
+    def __init__(self, file_path: Path | None = None) -> None:
+        """Initialize the file credential store.
+
+        Parameters
+        ----------
+        file_path : Path | None
+            Path to the credentials file. If None, uses default path.
+        """
+        self.file_path = file_path or CREDENTIAL_FILE_PATH
+
+    def _load_credentials(self) -> dict[str, str]:
+        """Load credentials from file."""
+        if not self.file_path.exists():
+            return {}
+        with self.file_path.open("r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+            return cast(dict[str, str], data) if data else {}
+
+    def _save_credentials(self, credentials: dict[str, str]) -> None:
+        """Save credentials to file."""
+        self.file_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.file_path.open("w", encoding="utf-8") as f:
+            yaml.safe_dump(credentials, f)
+
+    def set(self, key: str, value: bytes) -> None:
+        """Set a credential in the store."""
+        credentials = self._load_credentials()
+        credentials[key] = base64.b64encode(value).decode("utf-8")
+        self._save_credentials(credentials)
+
+    def get(self, key: str) -> bytes | None:
+        """Get a credential from the store."""
+        credentials = self._load_credentials()
+        encoded_value = credentials.get(key)
+        if encoded_value is None:
+            return None
+        return base64.b64decode(encoded_value)
+
+    def delete(self, key: str) -> None:
+        """Delete a credential from the store."""
+        credentials = self._load_credentials()
+        if key in credentials:
+            del credentials[key]
+            self._save_credentials(credentials)