flwr-nightly 1.23.0.dev20250930__py3-none-any.whl → 1.26.0.dev20260121__py3-none-any.whl

flwr/__init__.py

@@ -15,18 +15,29 @@
 """Flower main package."""
 
 
-from flwr.common.version import package_version as _package_version
+import importlib
 
-from . import app, client, clientapp, common, server, serverapp, simulation
+from flwr.supercore.version import package_version as _package_version
+
+from . import app, clientapp, serverapp
 
 __all__ = [
     "app",
-    "client",
     "clientapp",
-    "common",
-    "server",
     "serverapp",
-    "simulation",
 ]
 
 __version__ = _package_version
+
+
+# Lazy imports for legacy support
+_lazy_imports = {"simulation", "server", "client", "common"}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import for legacy support."""
+    if name in _lazy_imports:
+        module = importlib.import_module(f"{__name__}.{name}")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

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/error.py

@@ -17,7 +17,7 @@
 
 from __future__ import annotations
 
-from typing import Optional, cast
+from typing import cast
 
 DEFAULT_TTL = 43200  # This is 12 hours
 MESSAGE_INIT_ERROR_MESSAGE = (
@@ -54,7 +54,7 @@ class Error:
     @property
     def reason(self) -> str | None:
         """Reason reported about the error."""
-        return cast(Optional[str], self.__dict__["_reason"])
+        return cast(str | None, self.__dict__["_reason"])
 
     def __repr__(self) -> str:
         """Return a string representation of this instance."""

flwr/app/exception.py

@@ -15,11 +15,11 @@
 """Flower application exceptions."""
 
 
-class AppExitException(BaseException):
+class AppExitException(Exception):
     """Base exception for all application-level errors in ServerApp and ClientApp.
 
-    When raised, the process will exit and report a telemetry event with the associated
-    exit code. This is not intended to be caught by user code.
+    When raised (and not suppressed), the process will exit and report a telemetry event
+    with the associated exit code.
     """
 
     # Default exit code — subclasses must override

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,12 +14,20 @@
 # ==============================================================================
 """Flower command line interface."""
 
+
+from typing import Any, TypedDict
+
 import typer
 from typer.main import get_command
 
-from flwr.common.version import package_version
+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 .flower_config import init_flwr_config
 from .install import install
 from .log import log
 from .login import login
@@ -28,6 +36,18 @@ from .new import new
 from .pull import pull
 from .run import run
 from .stop import stop
+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(
@@ -43,18 +63,50 @@ app.command()(new)
 app.command()(run)
 app.command()(build)
 app.command()(install)
-app.command()(log)
-app.command()(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")
+supernode_app.command()(supernode_register)
+supernode_app.command()(supernode_unregister)
+# Make it appear as "list"
+supernode_app.command("list")(supernode_list)
+# Hide "ls" command (left as alias)
+supernode_app.command(hidden=True)(supernode_list)
+app.add_typer(supernode_app, name="supernode")
+
+# Create app command group
+app_app = typer.Typer(help="Manage Apps")
+app_app.command()(app_review)
+app_app.command()(app_publish)
+app.add_typer(app_app, name="app")
+
+# Create federation command group
+federation_app = typer.Typer(help="Manage Federations")
+# Make it appear as "list"
+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")
+
+# 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",
@@ -62,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/{new/templates/app/code → app_cmd}/__init__.py

@@ -12,4 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower CLI `new` command app / code templates."""
+"""Flower command line interface `app` command."""
+
+from .publish import publish as publish
+from .review import review as review
+
+__all__ = [
+    "publish",
+    "review",
+]

flwr/cli/app_cmd/publish.py

@@ -0,0 +1,285 @@
+# 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 `app publish` command."""
+
+
+from contextlib import ExitStack
+from pathlib import Path
+from typing import IO, Annotated
+
+import requests
+import typer
+from requests import Response
+
+from flwr.common.constant import FAB_CONFIG_FILE
+from flwr.supercore.constant import (
+    APP_PUBLISH_EXCLUDE_PATTERNS,
+    APP_PUBLISH_INCLUDE_PATTERNS,
+    MAX_DIR_DEPTH,
+    MAX_FILE_BYTES,
+    MAX_FILE_COUNT,
+    MAX_TOTAL_BYTES,
+    MIME_MAP,
+    PLATFORM_API_URL,
+    UTF8,
+)
+from flwr.supercore.version import package_version as flwr_version
+
+from ..auth_plugin.oidc_cli_plugin import OidcCliPlugin
+from ..config_utils import (
+    load_and_validate,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from ..constant import FEDERATION_CONFIG_HELP_MESSAGE
+from ..utils import build_pathspec, load_cli_auth_plugin, load_gitignore_patterns
+
+
+# pylint: disable=too-many-locals
+def publish(
+    app: Annotated[
+        Path,
+        typer.Argument(
+            help="Project directory to upload (defaults to current directory)."
+        ),
+    ] = Path("."),
+    federation: Annotated[
+        str | None,
+        typer.Argument(
+            help="Name of the federation used for login before publishing app."
+        ),
+    ] = None,
+    federation_config_overrides: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--federation-config",
+            help=FEDERATION_CONFIG_HELP_MESSAGE,
+        ),
+    ] = None,
+) -> None:
+    """Publish a Flower App to the Flower Platform.
+
+    This command uploads your app project to the Flower Platform. Files are filtered
+    based on .gitignore patterns and allowed file extensions.
+    """
+    # Load configs
+    pyproject_path = app / FAB_CONFIG_FILE if app else None
+    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
+    )
+
+    # Load the authentication plugin
+    auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
+    auth_plugin.load_tokens()
+    if not isinstance(auth_plugin, OidcCliPlugin) or not auth_plugin.access_token:
+        typer.secho(
+            "❌ Please log in before publishing app.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Load token from the plugin
+    token = auth_plugin.access_token
+
+    # Collect & validate app files
+    file_paths = _collect_file_paths(app)
+    _validate_files(file_paths)
+
+    # Build and POST multipart
+    with ExitStack() as stack:
+        files_param = _build_multipart_files_param(app, file_paths, stack)
+        try:
+            resp = _post_files(files_param, token)
+        except requests.RequestException as err:
+            typer.secho(f"❌ Network error: {err}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1) from err
+
+    if resp.ok:
+        typer.secho("🎊 Upload successful", fg=typer.colors.GREEN, bold=True)
+        return  # success
+
+    # Error path:
+    msg = f"❌ Upload failed with status {resp.status_code}"
+    if resp.text:
+        msg += f": {resp.text}"
+    typer.secho(msg, fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=1)
+
+
+def _depth_of(relative_path_to_root: Path) -> int:
+    """Return depth that is number of parts (directories) in the relative path
+    (excluding filename).
+
+    Example: "a/b/c.py" -> depth 2
+    Interpret "directory depth" as number of directories: len(parts) - 1
+    """
+    return max(0, len(relative_path_to_root.parts) - 1)
+
+
+def _detect_mime(path: Path) -> str:
+    """Detect files' MIME."""
+    return MIME_MAP.get(path.suffix.lower(), "text/plain; charset=utf-8")
+
+
+def _collect_file_paths(root: Path) -> list[Path]:
+    """Return list of file paths that match include/exclude patterns."""
+    # Build include/exclude pathspecs
+    # Note: This should be a temporary solution until we have a complete mechanism
+    # for configurable inclusion and exclusion rules.
+    # Note: Unlike Git, we do not support nested .gitignore files in subdirectories.
+    gitignore_patterns = tuple(load_gitignore_patterns(root / ".gitignore"))
+    exclude_pathspec = build_pathspec(gitignore_patterns + APP_PUBLISH_EXCLUDE_PATTERNS)
+    include_pathspec = build_pathspec(APP_PUBLISH_INCLUDE_PATTERNS)
+
+    # Walk the directory tree
+    file_paths: list[Path] = []
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+
+        # Skip excluded or not included files
+        # Note: pathspec requires POSIX style relative paths
+        relative_path = path.relative_to(root)
+        posix = relative_path.as_posix()
+        if exclude_pathspec.match_file(posix) or not include_pathspec.match_file(posix):
+            typer.echo(typer.style(f"Skip: {path}", fg=typer.colors.YELLOW))
+            continue
+
+        # Check max depth
+        if _depth_of(relative_path) > MAX_DIR_DEPTH:
+            typer.secho(
+                f"Error: '{path}' "
+                f"exceeds the maximum directory depth "
+                f"of {MAX_DIR_DEPTH}.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=2)
+
+        file_paths.append(path)
+
+    # Sort for deterministic ordering
+    file_paths.sort(key=lambda path: path.as_posix())
+    return file_paths
+
+
+def _validate_files(file_paths: list[Path]) -> None:
+    """Validate files against upload constraints.
+
+    Checks file count, individual file size, total size, and UTF-8 encoding.
+    """
+    if len(file_paths) == 0:
+        typer.secho(
+            "Nothing to upload: no files matched after applying .gitignore and "
+            "allowed extensions.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    if len(file_paths) > MAX_FILE_COUNT:
+        typer.secho(
+            f"Too many files: {len(file_paths)} > allowed maximum of {MAX_FILE_COUNT}.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # Calculate files size
+    total_size = 0
+    for path in file_paths:
+        file_size = path.stat().st_size
+        total_size += file_size
+
+        # Check single file size
+        if file_size > MAX_FILE_BYTES:
+            typer.secho(
+                f"File too large: '{path.as_posix()}' is {file_size:,} bytes, "
+                f"exceeding the per-file limit of {MAX_FILE_BYTES:,} bytes.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=2)
+
+        # Ensure we can decode as UTF-8.
+        try:
+            path.read_text(encoding=UTF8)
+        except UnicodeDecodeError as err:
+            typer.secho(
+                f"Encoding error: '{path}' is not UTF-8 encoded.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=2) from err
+
+    # Check total files size
+    if total_size > MAX_TOTAL_BYTES:
+        typer.secho(
+            "Total size of all files is too large: "
+            f"{total_size:,} bytes > {MAX_TOTAL_BYTES:,} bytes.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # Print validation passed prompt
+    typer.echo(typer.style("✅ Validation passed", fg=typer.colors.GREEN, bold=True))
+    typer.echo(f"{len(file_paths)} files, {total_size:,} bytes in total")
+
+
+def _build_multipart_files_param(
+    root: Path,
+    file_paths: list[Path],
+    stack: ExitStack,
+) -> list[tuple[str, tuple[str, IO[bytes], str]]]:
+    """Build multipart/form-data files parameter for HTTP upload.
+
+    Returns list of tuples: (field_name, (filename, file_object, content_type)).
+    File handles are registered with ExitStack for proper cleanup.
+    """
+    form: list[tuple[str, tuple[str, IO[bytes], str]]] = []
+    for path in file_paths:
+        # Detect MIME (content type)
+        mime = _detect_mime(path)
+
+        # Open file and register with ExitStack
+        # pylint: disable-next=consider-using-with
+        fobj = stack.enter_context(open(path.resolve(), "rb"))
+        typer.echo(f"Attach {path} ({mime}, {path.stat().st_size:,} bytes)")
+
+        # Get relative POSIX path
+        relative_posix = path.relative_to(root).as_posix()
+
+        # Append to form data (key, (filename, fileobj, mime))
+        form.append(("files", (relative_posix, fobj, mime)))
+    return form
+
+
+def _post_files(
+    files_param: list[tuple[str, tuple[str, IO[bytes], str]]],
+    token: str,
+) -> Response:
+    """POST multipart with one part per file."""
+    url = f"{PLATFORM_API_URL}/hub/apps/publish"
+    headers = {"Authorization": f"Bearer {token}"}
+    body = {"flwr_version": flwr_version}
+
+    resp = requests.post(
+        url, files=files_param, headers=headers, json=body, timeout=120
+    )
+    return resp