Improving help info for call command (detailed information about endpoint and body).

Author: krulis-martin

README.md

@@ -144,7 +144,23 @@ The client can also be extended with plugins that can streamline common request
     recodex info swagger
     ```
 
-### Examples
+## Examples
 
 The following examples can be used as snippets to quickly perform common tasks (just replace parameters as needed).
 
+### Group management
+
+**Add a student to a group:**
+```bash
+recodex call groups.add_student <group-id> <user-id>
+```
+
+**Remove a student from a group:**
+```bash
+recodex call groups.remove_student <group-id> <user-id>
+```
+
+**Add a member (admin) to a group (this does not work for students):**
+```bash
+recodex call groups.add_member <group-id> <user-id> --body {\"type\":\"admin\"}
+```

src/recodex_cli/call_command/help_printer.py

@@ -15,22 +15,7 @@ class HelpPrinter:
     body_panel: Panel | None = None
     console: Console | None = None
 
-    def __get_param_panel(self, params: list[dict], title) -> Panel:
-        rows_tokenized = []
-        for param in params:
-            rows_tokenized.append(cmd_utils.get_param_info_text_tokens(param))
-
-        rows = ["" for i in range(len(rows_tokenized))]
-
-        self.__add_text_token(rows, rows_tokenized, "name", "bright_cyan")
-        self.__add_text_token(rows, rows_tokenized, "type", "yellow")
-        self.__add_text_token(rows, rows_tokenized, "opt", "magenta")
-        self.__add_text_token(rows, rows_tokenized, "desc")
-
-        text = "\n".join(rows)
-        return self.__create_panel(text, title)
-
-    def __add_text_token(
+    def _add_text_token(
             self,
             texts: list[str],
             token_dicts: list[dict[str, str]],
@@ -53,7 +38,7 @@ def __add_text_token(
             token = f"[{color}]{token}[/{color}]"
             texts[i] += token
 
-    def __create_panel(self, text: str, title: str) -> Panel:
+    def _create_panel(self, text: str, title: str) -> Panel:
         # escape opening brackets
 
         return Panel(
@@ -63,38 +48,74 @@ def __create_panel(self, text: str, title: str) -> Panel:
             title_align="left",
         )
 
-    def __prepare(self, ctx: click.Context, endpoint: str, verbose: bool):
+    def _prepare_param_table(self, rows_tokenized: list[dict]) -> str:
+        rows = ["" for i in range(len(rows_tokenized))]
+        self._add_text_token(rows, rows_tokenized, "name", "bright_cyan")
+        self._add_text_token(rows, rows_tokenized, "type", "yellow")
+        self._add_text_token(rows, rows_tokenized, "opt", "magenta")
+        self._add_text_token(rows, rows_tokenized, "desc")
+        return "\n".join(rows)
+
+    def _get_param_panel(self, params: list[dict], title: str) -> Panel:
+        rows_tokenized = []
+        for param in params:
+            rows_tokenized.append(cmd_utils.get_param_info_text_tokens(param))
+
+        return self._create_panel(self._prepare_param_table(rows_tokenized), title)
+
+    def _get_body_panel(self, body_schema: dict | None, body_types: list[str], title: str) -> Panel:
+        if not body_types:
+            body_types = ["[unknown]"]
+
+        types_text = "[bright_black]A body is required of the following type(s):[/bright_black] " + ", ".join(
+            body_types)
+        if body_schema is None:
+            return self._create_panel(types_text, title)
+
+        types_text += "\n[bright_black]Body schema:[/bright_black]\n"
+        rows_tokenized = cmd_utils.get_body_params_info_text_tokens(body_schema)
+        return self._create_panel(types_text + self._prepare_param_table(rows_tokenized), title)
+
+    def _prepare(self, ctx: click.Context, endpoint: str, verbose: bool):
         self.ctx = ctx
         self.formatter = ctx.make_formatter()
 
         self.print_detail = endpoint != ""
         if self.print_detail:
             def __init():
-                presenter, action = cmd_utils.execute_with_verbosity(
+                self.presenter, self.action = cmd_utils.execute_with_verbosity(
                     lambda: cmd_utils.parse_endpoint_or_throw(endpoint),
                     verbose
                 )
                 endpoint_resolver = EndpointResolver()
                 self.console = Console()
-                path_params = endpoint_resolver.get_path_params(presenter, action)
-                query_params = endpoint_resolver.get_query_params(presenter, action)
+                path_params = endpoint_resolver.get_path_params(self.presenter, self.action)
+                query_params = endpoint_resolver.get_query_params(self.presenter, self.action)
+                body_schema = endpoint_resolver.get_request_body_schema(self.presenter, self.action)
+                body_types = endpoint_resolver.get_request_body_types(self.presenter, self.action)
 
+                self.description = endpoint_resolver.get_endpoint_description(self.presenter, self.action)
                 self.path_panel, self.query_panel, self.body_panel = None, None, None
                 if len(path_params) > 0:
-                    self.path_panel = self.__get_param_panel(path_params, "Path Parameters Detail")
+                    self.path_panel = self._get_param_panel(path_params, "Path Parameters Detail")
                 if len(query_params) > 0:
-                    self.query_panel = self.__get_param_panel(query_params, "Query Parameters Detail")
-                if endpoint_resolver.endpoint_has_body(presenter, action):
-                    self.body_panel = self.__create_panel("The endpoint expects a JSON body.", "Body Detail")
+                    self.query_panel = self._get_param_panel(query_params, "Query Parameters Detail")
+                if endpoint_resolver.endpoint_has_body(self.presenter, self.action):
+                    self.body_panel = self._get_body_panel(body_schema, body_types, "Body Detail")
             cmd_utils.execute_with_verbosity(__init, verbose)
 
     def print(self, ctx: click.Context, endpoint: str, verbose: bool):
-        self.__prepare(ctx, endpoint, verbose)
+        self._prepare(ctx, endpoint, verbose)
         self.ctx.command.format_help(self.ctx, self.formatter)
 
         if self.print_detail:
             if self.console is None:
                 raise Exception("The Console was not instantiated properly.")
+            self.console.print("\n[bold]Endpoint Detail[/bold]:")
+            self.console.print(f"Presenter: [yellow]{self.presenter}[/yellow]")
+            self.console.print(f"Action: [yellow]{self.action}[/yellow]")
+            self.console.print(f"Description: [bright_black]{self.description}[/bright_black]\n")
+
             if self.path_panel:
                 self.console.print(self.path_panel)
             if self.query_panel:

src/recodex_cli/console.py

@@ -22,7 +22,7 @@
 
 
 @app.command()
-def call(
+def call(  # noqa: C901
     endpoint: Annotated[
         str, typer.Argument(help="Endpoint identifier in <presenter.action> format", is_eager=True)
     ] = "",

src/recodex_cli/utils/cmd_utils.py

@@ -117,19 +117,42 @@ def get_param_info_text_tokens(param: dict) -> dict:
     """
 
     # get info
-    name = param["name"]
-    desc = param["description"]
-    type = param["schema"]["type"]
-    if param["schema"]["nullable"]:
+    schema = param.get("schema", {})
+    type = schema.get("type", "?")
+    if schema.get("nullable", False):
         type += "|null"
-    required = param["required"]
 
     tokens = {
-        "name": name,
+        "name": param.get("name", ""),
         "type": f"[{type}]",
+        "opt": "" if param.get("required", False) else "[OPT]",
+        "desc": param.get("description", "")
     }
-    if not required:
-        tokens["opt"] = "[OPT]"
-    tokens["desc"] = desc
 
     return tokens
+
+
+def get_body_params_info_text_tokens(schema: dict) -> list[dict]:
+    """Parses a body schema and yields a description of the body parameters.
+
+    Returns:
+        list[dict]: List of top-level parameters, each represented as a dictionary containing
+        the name, type, desc, opt keys describing the body parameter.
+    """
+
+    params = []
+    required = schema.get("required", [])
+
+    for name, prop in schema.get("properties", {}).items():
+        type = prop.get("type", "?")
+        if prop.get("nullable", False):
+            type += "|null"
+        tokens = {
+            "name": name,
+            "type": f"[{type}]",
+            "desc": prop.get("description", ""),
+            "opt": "" if name in required else "[OPT]"
+        }
+        params.append(tokens)
+
+    return params