flwr 1.23.0__py3-none-any.whl → 1.25.0__py3-none-any.whl

flwr/cli/auth_plugin/noop_auth_plugin.py

@@ -17,7 +17,6 @@
 
 from collections.abc import Sequence
 from pathlib import Path
-from typing import Optional, Union
 
 from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
 from flwr.proto.control_pb2_grpc import ControlStub
@@ -26,33 +25,77 @@ from .auth_plugin import CliAuthPlugin, LoginError
 
 
 class NoOpCliAuthPlugin(CliAuthPlugin):
-    """No-operation implementation of the CliAuthPlugin."""
+    """No-operation implementation of the CliAuthPlugin.
+
+    This plugin is used when account authentication is not enabled. It provides stub
+    implementations of all authentication methods that perform no actions.
+    """
 
     @staticmethod
     def login(
         login_details: AccountAuthLoginDetails,
         control_stub: ControlStub,
     ) -> AccountAuthCredentials:
-        """Raise LoginError as no-op plugin does not support login."""
+        """Raise LoginError as no-op plugin does not support login.
+
+        Parameters
+        ----------
+        login_details : AccountAuthLoginDetails
+            Login details (unused).
+        control_stub : ControlStub
+            Control stub (unused).
+
+        Returns
+        -------
+        AccountAuthCredentials
+            This method never returns as it always raises an exception.
+
+        Raises
+        ------
+        LoginError
+            Always raised to indicate authentication is not enabled.
+        """
         raise LoginError("Account authentication is not enabled on this SuperLink.")
 
     def __init__(self, credentials_path: Path) -> None:
         pass
 
     def store_tokens(self, credentials: AccountAuthCredentials) -> None:
-        """Do nothing."""
+        """Do nothing (no-op implementation)."""
 
     def load_tokens(self) -> None:
-        """Do nothing."""
+        """Do nothing (no-op implementation)."""
 
     def write_tokens_to_metadata(
-        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Sequence[tuple[str, Union[str, bytes]]]:
-        """Return the metadata unchanged."""
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> Sequence[tuple[str, str | bytes]]:
+        """Return the metadata unchanged.
+
+        Parameters
+        ----------
+        metadata : Sequence[tuple[str, str | bytes]]
+            The original metadata.
+
+        Returns
+        -------
+        Sequence[tuple[str, str | bytes]]
+            The same metadata, unmodified.
+        """
         return metadata
 
     def read_tokens_from_metadata(
-        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Optional[AccountAuthCredentials]:
-        """Return None."""
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> AccountAuthCredentials | None:
+        """Return None (no tokens to read).
+
+        Parameters
+        ----------
+        metadata : Sequence[tuple[str, str | bytes]]
+            The metadata to read from (unused).
+
+        Returns
+        -------
+        None
+            Always returns None as no authentication is performed.
+        """
         return None

flwr/cli/auth_plugin/oidc_cli_plugin.py

@@ -19,7 +19,7 @@ import json
 import time
 from collections.abc import Sequence
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 import typer
 
@@ -40,11 +40,15 @@ from .auth_plugin import CliAuthPlugin, LoginError
 
 
 class OidcCliPlugin(CliAuthPlugin):
-    """Flower OIDC auth plugin for CLI."""
+    """Flower OIDC authentication plugin for CLI.
+
+    This plugin implements OpenID Connect (OIDC) device flow authentication for CLI
+    access to Flower SuperLink.
+    """
 
     def __init__(self, credentials_path: Path):
-        self.access_token: Optional[str] = None
-        self.refresh_token: Optional[str] = None
+        self.access_token: str | None = None
+        self.refresh_token: str | None = None
         self.credentials_path = credentials_path
 
     @staticmethod
@@ -52,7 +56,25 @@ class OidcCliPlugin(CliAuthPlugin):
         login_details: AccountAuthLoginDetails,
         control_stub: ControlStub,
     ) -> AccountAuthCredentials:
-        """Authenticate the account and retrieve authentication credentials."""
+        """Authenticate the account and retrieve authentication credentials.
+
+        Parameters
+        ----------
+        login_details : AccountAuthLoginDetails
+            Login details containing device code and verification URI.
+        control_stub : ControlStub
+            Control stub for making authentication requests.
+
+        Returns
+        -------
+        AccountAuthCredentials
+            The access and refresh tokens.
+
+        Raises
+        ------
+        LoginError
+            If authentication times out.
+        """
         typer.secho(
             "Please log into your Flower account here: "
             f"{login_details.verification_uri_complete}",
@@ -108,14 +130,15 @@ class OidcCliPlugin(CliAuthPlugin):
             self.refresh_token = refresh_token
 
     def write_tokens_to_metadata(
-        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Sequence[tuple[str, Union[str, bytes]]]:
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> Sequence[tuple[str, str | bytes]]:
         """Write authentication tokens to the provided metadata."""
         if self.access_token is None or self.refresh_token is None:
             typer.secho(
                 "❌ Missing authentication tokens. Please login first.",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1)
 
@@ -125,8 +148,8 @@ class OidcCliPlugin(CliAuthPlugin):
         ]
 
     def read_tokens_from_metadata(
-        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Optional[AccountAuthCredentials]:
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> AccountAuthCredentials | None:
         """Read authentication tokens from the provided metadata."""
         metadata_dict = dict(metadata)
         access_token = metadata_dict.get(ACCESS_TOKEN_KEY)

flwr/cli/build.py

@@ -17,10 +17,9 @@
 
 import hashlib
 import zipfile
-from collections.abc import Iterable
 from io import BytesIO
 from pathlib import Path
-from typing import Annotated, Any, Optional, Union
+from typing import Annotated, Any
 
 import pathspec
 import tomli
@@ -37,13 +36,28 @@ from flwr.common.constant import (
 )
 
 from .config_utils import load_and_validate
-from .utils import is_valid_project_name
+from .utils import build_pathspec, is_valid_project_name, load_gitignore_patterns
 
 
 def write_to_zip(
-    zipfile_obj: zipfile.ZipFile, filename: str, contents: Union[bytes, str]
+    zipfile_obj: zipfile.ZipFile, filename: str, contents: bytes | str
 ) -> zipfile.ZipFile:
-    """Set a fixed date and write contents to a zip file."""
+    """Set a fixed date and write contents to a zip file.
+
+    Parameters
+    ----------
+    zipfile_obj : zipfile.ZipFile
+        The ZipFile object to write to.
+    filename : str
+        Name of the file within the zip archive.
+    contents : bytes | str
+        The file contents to write.
+
+    Returns
+    -------
+    ZipFile
+        The modified ZipFile object.
+    """
     zip_info = zipfile.ZipInfo(filename)
     zip_info.date_time = FAB_DATE
     zipfile_obj.writestr(zip_info, contents)
@@ -51,7 +65,21 @@ def write_to_zip(
 
 
 def get_fab_filename(config: dict[str, Any], fab_hash: str) -> str:
-    """Get the FAB filename based on the given config and FAB hash."""
+    """Get the FAB filename based on the given config and FAB hash.
+
+    Parameters
+    ----------
+    config : dict[str, Any]
+        The project configuration dictionary.
+    fab_hash : str
+        The SHA-256 hash of the FAB file.
+
+    Returns
+    -------
+    str
+        The formatted FAB filename in the pattern:
+        <publisher>.<name>.<version>.<hash_prefix>.fab
+    """
     publisher = config["tool"]["flwr"]["app"]["publisher"]
     name = config["project"]["name"]
     version = config["project"]["version"].replace(".", "-")
@@ -62,7 +90,7 @@ def get_fab_filename(config: dict[str, Any], fab_hash: str) -> str:
 # pylint: disable=too-many-locals, too-many-statements
 def build(
     app: Annotated[
-        Optional[Path],
+        Path | None,
         typer.Option(help="Path of the Flower App to bundle into a FAB"),
     ] = None,
 ) -> None:
@@ -83,6 +111,7 @@ def build(
             f"❌ The path {app} is not a valid path to a Flower app.",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -93,6 +122,7 @@ def build(
             "and can only contain letters, digits, and hyphens.",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -103,6 +133,7 @@ def build(
             + "\n".join([f"- {line}" for line in errors]),
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -152,7 +183,7 @@ def build_fab_from_disk(app: Path) -> bytes:
     all_files = [f for f in app.rglob("*") if f.is_file()]
 
     # Create dict mapping relative paths to Path objects
-    files_dict: dict[str, Union[bytes, Path]] = {
+    files_dict: dict[str, bytes | Path] = {
         # Ensure consistent path separators across platforms
         str(file_path.relative_to(app)).replace("\\", "/"): file_path
         for file_path in all_files
@@ -162,7 +193,7 @@ def build_fab_from_disk(app: Path) -> bytes:
     return build_fab_from_files(files_dict)
 
 
-def build_fab_from_files(files: dict[str, Union[bytes, Path]]) -> bytes:
+def build_fab_from_files(files: dict[str, bytes | Path]) -> bytes:
     r"""Build a FAB from in-memory files and return the FAB as bytes.
 
     This is the core FAB building function that works with in-memory data.
@@ -196,7 +227,7 @@ def build_fab_from_files(files: dict[str, Union[bytes, Path]]) -> bytes:
         fab_bytes = build_fab_from_files(files)
     """
 
-    def to_bytes(content: Union[bytes, Path]) -> bytes:
+    def to_bytes(content: bytes | Path) -> bytes:
         return content.read_bytes() if isinstance(content, Path) else content
 
     # Extract, load, and parse pyproject.toml
@@ -267,23 +298,34 @@ def build_fab_from_files(files: dict[str, Union[bytes, Path]]) -> bytes:
     return fab_bytes
 
 
-def build_pathspec(patterns: Iterable[str]) -> pathspec.PathSpec:
-    """Build a PathSpec from a list of patterns."""
-    return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
-
-
 def get_fab_include_pathspec() -> pathspec.PathSpec:
-    """Get the PathSpec for files to include in a FAB."""
+    """Get the PathSpec for files to include in a FAB.
+
+    Returns
+    -------
+    PathSpec
+        PathSpec object with default include patterns for FAB files.
+    """
     return build_pathspec(FAB_INCLUDE_PATTERNS)
 
 
-def get_fab_exclude_pathspec(gitignore_content: Optional[bytes]) -> pathspec.PathSpec:
+def get_fab_exclude_pathspec(gitignore_content: bytes | None) -> pathspec.PathSpec:
     """Get the PathSpec for files to exclude from a FAB.
 
     If gitignore_content is provided, its patterns will be combined with the default
     exclude patterns.
+
+    Parameters
+    ----------
+    gitignore_content : bytes | None
+        Optional gitignore file content as bytes.
+
+    Returns
+    -------
+    PathSpec
+        PathSpec object with combined exclude patterns.
     """
     patterns = list(FAB_EXCLUDE_PATTERNS)
     if gitignore_content:
-        patterns += gitignore_content.decode("UTF-8").splitlines()
+        patterns += load_gitignore_patterns(gitignore_content)
     return pathspec.PathSpec.from_lines("gitwildmatch", patterns)

flwr/cli/cli_account_auth_interceptor.py

@@ -15,7 +15,8 @@
 """Flower run interceptor."""
 
 
-from typing import Any, Callable, Union
+from collections.abc import Callable
+from typing import Any
 
 import grpc
 
@@ -26,16 +27,17 @@ from flwr.proto.control_pb2 import (  # pylint: disable=E0611
 
 from .auth_plugin import CliAuthPlugin
 
-Request = Union[
-    StartRunRequest,
-    StreamLogsRequest,
-]
+Request = StartRunRequest | StreamLogsRequest
 
 
 class CliAccountAuthInterceptor(
     grpc.UnaryUnaryClientInterceptor, grpc.UnaryStreamClientInterceptor  # type: ignore
 ):
-    """CLI interceptor for account authentication."""
+    """CLI interceptor for account authentication.
+
+    This interceptor adds authentication tokens to gRPC metadata for CLI requests and
+    handles token refresh from response metadata.
+    """
 
     def __init__(self, auth_plugin: CliAuthPlugin):
         self.auth_plugin = auth_plugin
@@ -46,7 +48,22 @@ class CliAccountAuthInterceptor(
         client_call_details: grpc.ClientCallDetails,
         request: Request,
     ) -> grpc.Call:
-        """Send and receive tokens via metadata."""
+        """Send and receive tokens via metadata.
+
+        Parameters
+        ----------
+        continuation : Callable[[Any, Any], Any]
+            The next interceptor or handler in the chain.
+        client_call_details : grpc.ClientCallDetails
+            Details of the RPC call as a NamedTuple.
+        request : Request
+            The RPC request object.
+
+        Returns
+        -------
+        grpc.Call
+            The RPC response.
+        """
         new_metadata = self.auth_plugin.write_tokens_to_metadata(
             client_call_details.metadata or []
         )

flwr/cli/config_utils.py

@@ -16,7 +16,7 @@
 
 
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 import tomli
 import typer
@@ -30,7 +30,7 @@ from flwr.common.config import (
 )
 
 
-def get_fab_metadata(fab_file: Union[Path, bytes]) -> tuple[str, str]:
+def get_fab_metadata(fab_file: Path | bytes) -> tuple[str, str]:
     """Extract the fab_id and the fab_version from a FAB file or path.
 
     Parameters
@@ -48,9 +48,9 @@ def get_fab_metadata(fab_file: Union[Path, bytes]) -> tuple[str, str]:
 
 
 def load_and_validate(
-    path: Optional[Path] = None,
+    path: Path | None = None,
     check_module: bool = True,
-) -> tuple[Optional[dict[str, Any]], list[str], list[str]]:
+) -> tuple[dict[str, Any] | None, list[str], list[str]]:
     """Load and validate pyproject.toml as dict.
 
     Parameters
@@ -89,8 +89,20 @@ def load_and_validate(
     return (config, errors, warnings)
 
 
-def load(toml_path: Path) -> Optional[dict[str, Any]]:
-    """Load pyproject.toml and return as dict."""
+def load(toml_path: Path) -> dict[str, Any] | None:
+    """Load pyproject.toml and return as dict.
+
+    Parameters
+    ----------
+    toml_path : Path
+        Path to the pyproject.toml file.
+
+    Returns
+    -------
+    dict[str, Any] | None
+        Parsed TOML configuration as dictionary, or None if file doesn't exist
+        or has invalid TOML syntax.
+    """
     if not toml_path.is_file():
         return None
 
@@ -102,12 +114,31 @@ def load(toml_path: Path) -> Optional[dict[str, Any]]:
 
 
 def process_loaded_project_config(
-    config: Union[dict[str, Any], None], errors: list[str], warnings: list[str]
+    config: dict[str, Any] | None, errors: list[str], warnings: list[str]
 ) -> dict[str, Any]:
     """Process and return the loaded project configuration.
 
     This function handles errors and warnings from the `load_and_validate` function,
     exits on critical issues, and returns the validated configuration.
+
+    Parameters
+    ----------
+    config : dict[str, Any] | None
+        The loaded configuration dictionary, or None if loading failed.
+    errors : list[str]
+        List of error messages from validation.
+    warnings : list[str]
+        List of warning messages from validation.
+
+    Returns
+    -------
+    dict[str, Any]
+        The validated configuration dictionary.
+
+    Raises
+    ------
+    typer.Exit
+        If config is None or contains critical errors.
     """
     if config is None:
         typer.secho(
@@ -116,6 +147,7 @@ def process_loaded_project_config(
             + "\n".join([f"- {line}" for line in errors]),
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -133,11 +165,32 @@ def process_loaded_project_config(
 
 
 def validate_federation_in_project_config(
-    federation: Optional[str],
+    federation: str | None,
     config: dict[str, Any],
-    overrides: Optional[list[str]] = None,
+    overrides: list[str] | None = None,
 ) -> tuple[str, dict[str, Any]]:
-    """Validate the federation name in the Flower project configuration."""
+    """Validate the federation name in the Flower project configuration.
+
+    Parameters
+    ----------
+    federation : str | None
+        Name of the federation, or None to use default from config.
+    config : dict[str, Any]
+        The project configuration dictionary.
+    overrides : list[str] | None
+        List of configuration override strings. Default is None.
+
+    Returns
+    -------
+    tuple[str, dict[str, Any]]
+        A tuple of (federation_name, federation_config).
+
+    Raises
+    ------
+    typer.Exit
+        If no federation name provided and no default found, or if federation
+        doesn't exist in config.
+    """
     federation = federation or config["tool"]["flwr"]["federations"].get("default")
 
     if federation is None:
@@ -147,6 +200,7 @@ def validate_federation_in_project_config(
             "`options.num-supernodes` value).",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -162,6 +216,7 @@ def validate_federation_in_project_config(
             + "\n".join(available_feds),
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -175,7 +230,7 @@ def validate_federation_in_project_config(
 
 def validate_certificate_in_federation_config(
     app: Path, federation_config: dict[str, Any]
-) -> tuple[bool, Optional[bytes]]:
+) -> tuple[bool, bytes | None]:
     """Validate the certificates in the Flower project configuration.
 
     Accepted configurations:
@@ -207,6 +262,7 @@ def validate_certificate_in_federation_config(
                 "is set to `True`.",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1)
 
@@ -218,6 +274,7 @@ def validate_certificate_in_federation_config(
                 f"❌ Failed to read certificate file `{root_certificates}`: {e}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
             raise typer.Exit(code=1) from e
     else:
@@ -227,19 +284,49 @@ def validate_certificate_in_federation_config(
 
 
 def exit_if_no_address(federation_config: dict[str, Any], cmd: str) -> None:
-    """Exit if the provided federation_config has no "address" key."""
+    """Exit if the provided federation_config has no "address" key.
+
+    Parameters
+    ----------
+    federation_config : dict[str, Any]
+        The federation configuration dictionary to check.
+    cmd : str
+        The command name to display in the error message.
+
+    Raises
+    ------
+    typer.Exit
+        If 'address' key is not present in federation_config.
+    """
     if "address" not in federation_config:
         typer.secho(
             f"❌ `flwr {cmd}` currently works with a SuperLink. Ensure that the "
             "correct SuperLink (Control API) address is provided in `pyproject.toml`.",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
 
 def get_insecure_flag(federation_config: dict[str, Any]) -> bool:
-    """Extract and validate the `insecure` flag from the federation configuration."""
+    """Extract and validate the `insecure` flag from the federation configuration.
+
+    Parameters
+    ----------
+    federation_config : dict[str, Any]
+        The federation configuration dictionary.
+
+    Returns
+    -------
+    bool
+        The insecure flag value. Returns False if not specified.
+
+    Raises
+    ------
+    typer.Exit
+        If insecure value is not a boolean type.
+    """
     insecure_value = federation_config.get("insecure")
 
     if insecure_value is None:
@@ -252,5 +339,6 @@ def get_insecure_flag(federation_config: dict[str, Any]) -> bool:
         "(`insecure = true` or `insecure = false`)",
         fg=typer.colors.RED,
         bold=True,
+        err=True,
     )
     raise typer.Exit(code=1)

flwr/cli/{new/templates/app/code/flwr_tune → federation}/__init__.py

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