Make key the canonical parameter, deprecate auth_key

src/frequenz/client/dispatch/__main__.py

@@ -173,14 +173,14 @@ def format_line(key: str, value: str, color: str = "cyan") -> str:
 )
 @click.option(
     "--api-key",
-    help="API key for authentication (deprecated, use --auth-key or DISPATCH_API_AUTH_KEY)",
+    help="API key for authentication",
     envvar="DISPATCH_API_KEY",
     show_envvar=True,
     required=False,
 )
 @click.option(
     "--auth-key",
-    help="API auth key for authentication",
+    help="API auth key for authentication (deprecated, use --api-key or DISPATCH_API_KEY)",
     envvar="DISPATCH_API_AUTH_KEY",
     show_envvar=True,
     required=False,
@@ -213,16 +213,16 @@ async def cli(  # pylint: disable=too-many-arguments, too-many-positional-argume
     if ctx.obj is None:
         ctx.obj = {}
 
-    key = auth_key or api_key
+    key = api_key or auth_key
 
     if not key:
         raise click.BadParameter(
-            "You must provide an API auth key using --auth-key or "
-            "the DISPATCH_API_AUTH_KEY environment variable."
+            "You must provide an API key using --api-key or "
+            "the DISPATCH_API_KEY environment variable."
         )
 
     click.echo(f"Using API URL: {url}", err=True)
-    click.echo(f"Using API Auth Key: {key[:4]}{'*' * 8}", err=True)
+    click.echo(f"Using API Key: {key[:4]}{'*' * 8}", err=True)
 
     if sign_secret:
         if len(sign_secret) > 8:
@@ -232,12 +232,12 @@ async def cli(  # pylint: disable=too-many-arguments, too-many-positional-argume
         else:
             click.echo("Using API Signing Secret (not shown).", err=True)
 
-    if api_key and auth_key is None:
+    if auth_key and api_key is None:
         click.echo(
             click.style(
-                "Deprecation Notice: The --api-key option and the DISPATCH_API_KEY environment "
-                "variable are deprecated. "
-                "Please use --auth-key or set the DISPATCH_API_AUTH_KEY environment variable.",
+                "Deprecation Notice: The --auth-key option and the DISPATCH_API_AUTH_KEY "
+                "environment variable are deprecated. "
+                "Please use --api-key or set the DISPATCH_API_KEY environment variable.",
                 fg="red",
                 bold=True,
             ),
@@ -246,14 +246,14 @@ async def cli(  # pylint: disable=too-many-arguments, too-many-positional-argume
 
     ctx.obj["client"] = DispatchApiClient(
         server_url=url,
-        auth_key=key,
+        key=key,
         sign_secret=sign_secret,
         connect=True,
     )
 
     ctx.obj["params"] = {
         "url": url,
-        "auth_key": key,
+        "key": key,
         "sign_secret": sign_secret,
     }
 
@@ -602,7 +602,7 @@ async def repl(
 ) -> None:
     """Start an interactive interface."""
     await interactive_mode(
-        obj["params"]["url"], obj["params"]["auth_key"], obj["params"]["sign_secret"]
+        obj["params"]["url"], obj["params"]["key"], obj["params"]["sign_secret"]
     )
 
 
@@ -643,7 +643,7 @@ async def delete(
         raise click.ClickException("Some deletions failed.")
 
 
-async def interactive_mode(url: str, auth_key: str, sign_secret: str | None) -> None:
+async def interactive_mode(url: str, key: str, sign_secret: str | None) -> None:
     """Interactive mode for the CLI."""
     hist_file = os.path.expanduser("~/.dispatch_cli_history.txt")
     session: PromptSession[str] = PromptSession(history=FileHistory(filename=hist_file))
@@ -684,7 +684,7 @@ async def display_help() -> None:
         else:
             # Split, but keep quoted strings together
             params = (
-                ["--url", url, "--auth-key", auth_key]
+                ["--url", url, "--api-key", key]
                 + (["--sign-secret", sign_secret] if sign_secret else [])
                 + shlex.split(user_input)
             )

src/frequenz/client/dispatch/_client.py

@@ -2,6 +2,7 @@
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
 """Dispatch API client for Python."""
+
 from __future__ import annotations
 
 import warnings
@@ -59,8 +60,8 @@ def __init__(
         self,
         *,
         server_url: str,
-        auth_key: str | None = None,
         key: str | None = None,
+        auth_key: str | None = None,
         sign_secret: str | None = None,
         connect: bool = True,
         call_timeout: timedelta = timedelta(seconds=60),
@@ -70,26 +71,26 @@ def __init__(
 
         Args:
             server_url: The URL of the server to connect to.
-            auth_key: API key to use for authentication.
-            key: Deprecated, use `auth_key` instead.
+            key: API key to use for authentication.
+            auth_key: Deprecated, use `key` instead.
             sign_secret: Optional secret for signing requests.
             connect: Whether to connect to the service immediately.
             call_timeout: Timeout for gRPC calls, default is 60 seconds.
             stream_timeout: Timeout for gRPC streams, default is 5 minutes.
 
         Raises:
-            TypeError: If neither `auth_key` nor `key` is provided.
+            TypeError: If neither `key` nor `auth_key` is provided.
         """
-        if key is not None:
+        if auth_key is not None:
             warnings.warn(
-                "The `key` parameter is deprecated, use `auth_key` instead.",
+                "The `auth_key` parameter is deprecated, use `key` instead.",
                 DeprecationWarning,
                 stacklevel=2,
             )
-        auth_key = auth_key or key
-        if auth_key is None:
+        key = key or auth_key
+        if key is None:
             raise TypeError(
-                "__init__() missing 1 required keyword-only argument: 'auth_key'"
+                "__init__() missing 1 required keyword-only argument: 'key'"
             )
 
         super().__init__(
@@ -100,7 +101,7 @@ def __init__(
                 port=DEFAULT_DISPATCH_PORT,
                 ssl=SslOptions(enabled=True),
             ),
-            auth_key=auth_key,
+            auth_key=key,
             sign_secret=sign_secret,
         )
         self._streams: dict[
@@ -159,7 +160,7 @@ async def list(
 
         ```python
         client = DispatchApiClient(
-            auth_key="key",
+            key="key",
             sign_secret="secret", # Optional so far
             server_url="grpc://dispatch.url.goes.here.example.com"
         )

src/frequenz/client/dispatch/test/client.py

@@ -24,7 +24,7 @@ def __init__(
         self,
     ) -> None:
         """Initialize the mock client."""
-        super().__init__(server_url="mock", auth_key="what", connect=False)
+        super().__init__(server_url="mock", key="what", connect=False)
         self._stuba: FakeService = FakeService()
 
     @property