Adds support for kwargs and default arguments in the python client, and improves how parameter information is displayed in the "view API" page

.changeset/tiny-bars-greet.md

@@ -0,0 +1,8 @@
+---
+"@gradio/app": minor
+"@gradio/atoms": minor
+"gradio": minor
+"gradio_client": minor
+---
+
+feat:Adds support for kwargs and default arguments in the python client, and improves how parameter information is displayed in the "view API" page

client/python/gradio_client/client.py

@@ -33,6 +33,7 @@
 
 from gradio_client import utils
 from gradio_client.compatibility import EndpointV3Compatibility
+from gradio_client.data_classes import ParameterInfo
 from gradio_client.documentation import document
 from gradio_client.exceptions import AuthenticationError
 from gradio_client.utils import (
@@ -400,6 +401,7 @@ def predict(
         *args,
         api_name: str | None = None,
         fn_index: int | None = None,
+        **kwargs,
     ) -> Any:
         """
         Calls the Gradio API and returns the result (this is a blocking call).
@@ -421,7 +423,9 @@ def predict(
             raise ValueError(
                 "Cannot call predict on this function as it may run forever. Use submit instead."
             )
-        return self.submit(*args, api_name=api_name, fn_index=fn_index).result()
+        return self.submit(
+            *args, api_name=api_name, fn_index=fn_index, **kwargs
+        ).result()
 
     def new_helper(self, fn_index: int) -> Communicator:
         return Communicator(
@@ -437,6 +441,7 @@ def submit(
         api_name: str | None = None,
         fn_index: int | None = None,
         result_callbacks: Callable | list[Callable] | None = None,
+        **kwargs,
     ) -> Job:
         """
         Creates and returns a Job object which calls the Gradio API in a background thread. The job can be used to retrieve the status and result of the remote API call.
@@ -458,9 +463,13 @@ def submit(
             >> 9.0
         """
         inferred_fn_index = self._infer_fn_index(api_name, fn_index)
+        endpoint = self.endpoints[inferred_fn_index]
+
+        if isinstance(endpoint, Endpoint):
+            args = utils.construct_args(endpoint.parameters_info, args, kwargs)
 
         helper = None
-        if self.endpoints[inferred_fn_index].protocol in (
+        if endpoint.protocol in (
             "ws",
             "sse",
             "sse_v1",
@@ -469,7 +478,7 @@ def submit(
             "sse_v3",
         ):
             helper = self.new_helper(inferred_fn_index)
-        end_to_end_fn = self.endpoints[inferred_fn_index].make_end_to_end_fn(helper)
+        end_to_end_fn = endpoint.make_end_to_end_fn(helper)
         future = self.executor.submit(end_to_end_fn, *args)
 
         job = Job(
@@ -637,9 +646,12 @@ def reset_session(self) -> None:
     def _render_endpoints_info(
         self,
         name_or_index: str | int,
-        endpoints_info: dict[str, list[dict[str, Any]]],
+        endpoints_info: dict[str, list[ParameterInfo]],
     ) -> str:
-        parameter_names = [p["label"] for p in endpoints_info["parameters"]]
+        parameter_info = endpoints_info["parameters"]
+        parameter_names = [
+            p.get("parameter_name") or p["label"] for p in parameter_info
+        ]
         parameter_names = [utils.sanitize_parameter_names(p) for p in parameter_names]
         rendered_parameters = ", ".join(parameter_names)
         if rendered_parameters:
@@ -659,15 +671,23 @@ def _render_endpoints_info(
 
         human_info = f"\n - predict({rendered_parameters}{final_param}) -> {rendered_return_values}\n"
         human_info += "    Parameters:\n"
-        if endpoints_info["parameters"]:
-            for info in endpoints_info["parameters"]:
+        if parameter_info:
+            for info in parameter_info:
                 desc = (
                     f" ({info['python_type']['description']})"
                     if info["python_type"].get("description")
                     else ""
                 )
+                default_value = info.get("parameter_default")
+                default_info = (
+                    "(required)"
+                    if not info.get("parameter_has_default", False)
+                    else f"(not required, defaults to {default_value})"
+                )
                 type_ = info["python_type"]["type"]
-                human_info += f"     - [{info['component']}] {utils.sanitize_parameter_names(info['label'])}: {type_}{desc} \n"
+                if info.get("parameter_has_default", False) and default_value is None:
+                    type_ += " | None"
+                human_info += f"     - [{info['component']}] {utils.sanitize_parameter_names(info.get('parameter_name') or info['label'])}: {type_} {default_info} {desc} \n"
         else:
             human_info += "     - None\n"
         human_info += "    Returns:\n"
@@ -982,6 +1002,8 @@ def __init__(
         self.output_component_types = [
             self._get_component_type(id_) for id_ in dependency["outputs"]
         ]
+        self.parameters_info = self._get_parameters_info()
+
         self.root_url = client.src + "/" if not client.src.endswith("/") else client.src
         self.is_continuous = dependency.get("types", {}).get("continuous", False)
 
@@ -1001,6 +1023,13 @@ def _get_component_type(self, component_id: int):
             component["type"] == "state",
         )
 
+    def _get_parameters_info(self) -> list[ParameterInfo] | None:
+        if not self.client._info:
+            self._info = self.client._get_api_info()
+        if self.api_name in self._info["named_endpoints"]:
+            return self._info["named_endpoints"][self.api_name]["parameters"]
+        return None
+
     @staticmethod
     def value_is_file(component: dict) -> bool:
         # This is still hacky as it does not tell us which part of the payload is a file.

client/python/gradio_client/data_classes.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TypedDict
+from typing import Any, TypedDict
 
 from typing_extensions import NotRequired
 
@@ -15,3 +15,14 @@ class FileData(TypedDict):
     orig_name: NotRequired[str]  # original filename
     mime_type: NotRequired[str]
     is_stream: NotRequired[bool]
+
+
+class ParameterInfo(TypedDict):
+    label: str
+    parameter_name: NotRequired[str]
+    parameter_has_default: NotRequired[bool]
+    parameter_default: NotRequired[Any]
+    type: dict
+    python_type: dict
+    component: str
+    example_input: Any

client/python/gradio_client/utils.py

@@ -17,14 +17,17 @@
 from enum import Enum
 from pathlib import Path
 from threading import Lock
-from typing import Any, Callable, Literal, Optional, TypedDict
+from typing import TYPE_CHECKING, Any, Callable, Literal, Optional, TypedDict
 
 import fsspec.asyn
 import httpx
 import huggingface_hub
 from huggingface_hub import SpaceStage
 from websockets.legacy.protocol import WebSocketCommonProtocol
 
+if TYPE_CHECKING:
+    from gradio_client.data_classes import ParameterInfo
+
 API_URL = "api/predict/"
 SSE_URL_V0 = "queue/join"
 SSE_DATA_URL_V0 = "queue/data"
@@ -1063,3 +1066,54 @@ def file(filepath_or_url: str | Path):
         raise ValueError(
             f"File {s} does not exist on local filesystem and is not a valid URL."
         )
+
+
+def construct_args(
+    parameters_info: list[ParameterInfo] | None, args: tuple, kwargs: dict
+) -> list:
+    class _Keywords(Enum):
+        NO_VALUE = "NO_VALUE"  # Used as a sentinel to determine if nothing is provided as a parameter for an argument
+
+    _args = list(args)
+    if parameters_info is None:
+        if kwargs:
+            raise ValueError(
+                "This endpoint does not support key-word arguments Please click on 'view API' in the footer of the Gradio app to see usage."
+            )
+        return _args
+    num_args = len(args)
+    _args = _args + [_Keywords.NO_VALUE] * (len(parameters_info) - num_args)
+
+    kwarg_arg_mapping = {}
+    kwarg_names = []
+    for index, param_info in enumerate(parameters_info):
+        if "parameter_name" in param_info:
+            kwarg_arg_mapping[param_info["parameter_name"]] = index
+            kwarg_names.append(param_info["parameter_name"])
+        else:
+            kwarg_names.append("argument {index}")
+        if (
+            param_info.get("parameter_has_default", False)
+            and _args[index] == _Keywords.NO_VALUE
+        ):
+            _args[index] = param_info.get("parameter_default")
+
+    for key, value in kwargs.items():
+        if key in kwarg_arg_mapping:
+            if kwarg_arg_mapping[key] < num_args:
+                raise ValueError(
+                    f"Parameter `{key}` is already set as a positional argument. Please click on 'view API' in the footer of the Gradio app to see usage."
+                )
+            else:
+                _args[kwarg_arg_mapping[key]] = value
+        else:
+            raise ValueError(
+                f"Parameter `{key}` is not a valid key-word argument. Please click on 'view API' in the footer of the Gradio app to see usage."
+            )
+
+    if _Keywords.NO_VALUE in _args:
+        raise ValueError(
+            f"No value provided for required argument: {kwarg_names[_args.index(_Keywords.NO_VALUE)]}"
+        )
+
+    return _args

client/python/test/conftest.py

@@ -41,6 +41,38 @@ def calculator(num1, operation, num2):
     return demo
 
 
+@pytest.fixture
+def calculator_demo_with_defaults():
+    def calculator(num1, operation=None, num2=100):
+        if operation is None or operation == "add":
+            return num1 + num2
+        elif operation == "subtract":
+            return num1 - num2
+        elif operation == "multiply":
+            return num1 * num2
+        elif operation == "divide":
+            if num2 == 0:
+                raise gr.Error("Cannot divide by zero!")
+            return num1 / num2
+
+    demo = gr.Interface(
+        calculator,
+        [
+            gr.Number(value=10),
+            gr.Radio(["add", "subtract", "multiply", "divide"]),
+            gr.Number(),
+        ],
+        "number",
+        examples=[
+            [5, "add", 3],
+            [4, "divide", 2],
+            [-4, "multiply", 2.5],
+            [0, "subtract", 1.2],
+        ],
+    )
+    return demo
+
+
 @pytest.fixture
 def state_demo():
     demo = gr.Interface(

client/python/test/test_client.py

@@ -601,6 +601,33 @@ def return_bad():
             assert pred[0] == data[0]
 
 
+class TestClientPredictionsWithKwargs:
+    def test_no_default_params(self, calculator_demo):
+        with connect(calculator_demo) as client:
+            result = client.predict(
+                num1=3, operation="add", num2=3, api_name="/predict"
+            )
+            assert result == 6
+
+            result = client.predict(33, operation="add", num2=3, api_name="/predict")
+            assert result == 36
+
+    def test_default_params(self, calculator_demo_with_defaults):
+        with connect(calculator_demo_with_defaults) as client:
+            result = client.predict(num2=10, api_name="/predict")
+            assert result == 20
+
+            result = client.predict(num2=33, operation="multiply", api_name="/predict")
+            assert result == 330
+
+    def test_missing_params(self, calculator_demo):
+        with connect(calculator_demo) as client:
+            with pytest.raises(
+                ValueError, match="No value provided for required argument: num2"
+            ):
+                client.predict(num1=3, operation="add", api_name="/predict")
+
+
 class TestStatusUpdates:
     @patch("gradio_client.client.Endpoint.make_end_to_end_fn")
     def test_messages_passed_correctly(self, mock_make_end_to_end_fn, calculator_demo):
@@ -952,13 +979,19 @@ def test_api_info_of_local_demo(self, calculator_demo):
                 "parameters": [
                     {
                         "label": "num1",
+                        "parameter_name": "num1",
+                        "parameter_has_default": False,
+                        "parameter_default": None,
                         "type": {"type": "number"},
                         "python_type": {"type": "float", "description": ""},
                         "component": "Number",
                         "example_input": 3,
                     },
                     {
                         "label": "operation",
+                        "parameter_name": "operation",
+                        "parameter_has_default": False,
+                        "parameter_default": None,
                         "type": {
                             "enum": ["add", "subtract", "multiply", "divide"],
                             "title": "Radio",
@@ -973,6 +1006,9 @@ def test_api_info_of_local_demo(self, calculator_demo):
                     },
                     {
                         "label": "num2",
+                        "parameter_name": "num2",
+                        "parameter_has_default": False,
+                        "parameter_default": None,
                         "type": {"type": "number"},
                         "python_type": {"type": "float", "description": ""},
                         "component": "Number",
@@ -1046,6 +1082,9 @@ def test_layout_components_in_output(self, hello_world_with_group):
                         "parameters": [
                             {
                                 "label": "name",
+                                "parameter_name": "name",
+                                "parameter_has_default": True,
+                                "parameter_default": "",
                                 "type": {"type": "string"},
                                 "python_type": {"type": "str", "description": ""},
                                 "component": "Textbox",
@@ -1077,6 +1116,9 @@ def test_layout_and_state_components_in_output(
                         "parameters": [
                             {
                                 "label": "name",
+                                "parameter_name": "name",
+                                "parameter_has_default": True,
+                                "parameter_default": "",
                                 "type": {"type": "string"},
                                 "python_type": {"type": "str", "description": ""},
                                 "component": "Textbox",
@@ -1093,10 +1135,7 @@ def test_layout_and_state_components_in_output(
                             {
                                 "label": "count",
                                 "type": {"type": "number"},
-                                "python_type": {
-                                    "type": "float",
-                                    "description": "",
-                                },
+                                "python_type": {"type": "float", "description": ""},
                                 "component": "Number",
                             },
                         ],
@@ -1107,10 +1146,7 @@ def test_layout_and_state_components_in_output(
                             {
                                 "label": "count",
                                 "type": {"type": "number"},
-                                "python_type": {
-                                    "type": "float",
-                                    "description": "",
-                                },
+                                "python_type": {"type": "float", "description": ""},
                                 "component": "Number",
                             }
                         ],
@@ -1121,10 +1157,7 @@ def test_layout_and_state_components_in_output(
                             {
                                 "label": "count",
                                 "type": {"type": "number"},
-                                "python_type": {
-                                    "type": "float",
-                                    "description": "",
-                                },
+                                "python_type": {"type": "float", "description": ""},
                                 "component": "Number",
                             }
                         ],