[py] Update docstrings to google pydoc format (#16511)

Co-authored-by: Corey Goldberg <[email protected]>

Author: iampopovich

py/selenium/webdriver/common/actions/action_builder.py

@@ -49,14 +49,11 @@ def __init__(
     def get_device_with(self, name: str) -> Optional[Union["WheelInput", "PointerInput", "KeyInput"]]:
         """Get the device with the given name.
 
-        Parameters:
-        -----------
-        name : str
-            The name of the device to get.
+        Args:
+            name: The name of the device to get.
 
         Returns:
-        --------
-        Optional[Union[WheelInput, PointerInput, KeyInput]] : The device with the given name.
+            The device with the given name, or None if not found.
         """
         return next(filter(lambda x: x == name, self.devices), None)
 
@@ -83,19 +80,15 @@ def wheel_action(self) -> WheelActions:
     def add_key_input(self, name: str) -> KeyInput:
         """Add a new key input device to the action builder.
 
-        Parameters:
-        -----------
-        name : str
-            The name of the key input device.
+        Args:
+            name: The name of the key input device.
 
         Returns:
-        --------
-        KeyInput : The newly created key input device.
+            The newly created key input device.
 
         Example:
-        --------
-        >>> action_builder = ActionBuilder(driver)
-        >>> action_builder.add_key_input(name="keyboard2")
+            >>> action_builder = ActionBuilder(driver)
+            >>> action_builder.add_key_input(name="keyboard2")
         """
         new_input = KeyInput(name)
         self._add_input(new_input)
@@ -104,25 +97,17 @@ def add_key_input(self, name: str) -> KeyInput:
     def add_pointer_input(self, kind: str, name: str) -> PointerInput:
         """Add a new pointer input device to the action builder.
 
-        Parameters:
-        -----------
-        kind : str
-            The kind of pointer input device.
-                - "mouse"
-                - "touch"
-                - "pen"
-
-        name : str
-            The name of the pointer input device.
+        Args:
+            kind: The kind of pointer input device. Valid values are "mouse",
+                "touch", or "pen".
+            name: The name of the pointer input device.
 
         Returns:
-        --------
-        PointerInput : The newly created pointer input device.
+            The newly created pointer input device.
 
         Example:
-        --------
-        >>> action_builder = ActionBuilder(driver)
-        >>> action_builder.add_pointer_input(kind="mouse", name="mouse")
+            >>> action_builder = ActionBuilder(driver)
+            >>> action_builder.add_pointer_input(kind="mouse", name="mouse")
         """
         new_input = PointerInput(kind, name)
         self._add_input(new_input)
@@ -131,19 +116,15 @@ def add_pointer_input(self, kind: str, name: str) -> PointerInput:
     def add_wheel_input(self, name: str) -> WheelInput:
         """Add a new wheel input device to the action builder.
 
-        Parameters:
-        -----------
-        name : str
-            The name of the wheel input device.
+        Args:
+            name: The name of the wheel input device.
 
         Returns:
-        --------
-        WheelInput : The newly created wheel input device.
+            The newly created wheel input device.
 
         Example:
-        --------
-        >>> action_builder = ActionBuilder(driver)
-        >>> action_builder.add_wheel_input(name="wheel2")
+            >>> action_builder = ActionBuilder(driver)
+            >>> action_builder.add_wheel_input(name="wheel2")
         """
         new_input = WheelInput(name)
         self._add_input(new_input)
@@ -153,11 +134,10 @@ def perform(self) -> None:
         """Performs all stored actions.
 
         Example:
-        --------
-        >>> action_builder = ActionBuilder(driver)
-        >>> keyboard = action_builder.key_input
-        >>> el = driver.find_element(id: "some_id")
-        >>> action_builder.click(el).pause(keyboard).pause(keyboard).pause(keyboard).send_keys("keys").perform()
+            >>> action_builder = ActionBuilder(driver)
+            >>> keyboard = action_builder.key_input
+            >>> el = driver.find_element(id: "some_id")
+            >>> action_builder.click(el).pause(keyboard).pause(keyboard).pause(keyboard).send_keys("keys").perform()
         """
         enc: dict[str, list[Any]] = {"actions": []}
         for device in self.devices:
@@ -171,21 +151,18 @@ def clear_actions(self) -> None:
         """Clears actions that are already stored on the remote end.
 
         Example:
-        --------
-        >>> action_builder = ActionBuilder(driver)
-        >>> keyboard = action_builder.key_input
-        >>> el = driver.find_element(By.ID, "some_id")
-        >>> action_builder.click(el).pause(keyboard).pause(keyboard).pause(keyboard).send_keys("keys")
-        >>> action_builder.clear_actions()
+            >>> action_builder = ActionBuilder(driver)
+            >>> keyboard = action_builder.key_input
+            >>> el = driver.find_element(By.ID, "some_id")
+            >>> action_builder.click(el).pause(keyboard).pause(keyboard).pause(keyboard).send_keys("keys")
+            >>> action_builder.clear_actions()
         """
         self.driver.execute(Command.W3C_CLEAR_ACTIONS)
 
     def _add_input(self, new_input: Union[KeyInput, PointerInput, WheelInput]) -> None:
         """Add a new input device to the action builder.
 
-        Parameters:
-        -----------
-        new_input : Union[KeyInput, PointerInput, WheelInput]
-            The new input device to add.
+        Args:
+            new_input: The new input device to add.
         """
         self.devices.append(new_input)

py/selenium/webdriver/common/bidi/browser.py

@@ -59,7 +59,6 @@ def get_state(self) -> str:
         """Gets the state of the client window.
 
         Returns:
-        -------
             str: The state of the client window (one of the ClientWindowState constants).
         """
         return self.state
@@ -68,7 +67,6 @@ def get_client_window(self) -> str:
         """Gets the client window identifier.
 
         Returns:
-        -------
             str: The client window identifier.
         """
         return self.client_window
@@ -77,7 +75,6 @@ def get_width(self) -> int:
         """Gets the width of the client window.
 
         Returns:
-        -------
             int: The width of the client window.
         """
         return self.width
@@ -86,7 +83,6 @@ def get_height(self) -> int:
         """Gets the height of the client window.
 
         Returns:
-        -------
             int: The height of the client window.
         """
         return self.height
@@ -95,7 +91,6 @@ def get_x(self) -> int:
         """Gets the x coordinate of the client window.
 
         Returns:
-        -------
             int: The x coordinate of the client window.
         """
         return self.x
@@ -104,7 +99,6 @@ def get_y(self) -> int:
         """Gets the y coordinate of the client window.
 
         Returns:
-        -------
             int: The y coordinate of the client window.
         """
         return self.y
@@ -113,7 +107,6 @@ def is_active(self) -> bool:
         """Checks if the client window is active.
 
         Returns:
-        -------
             bool: True if the client window is active, False otherwise.
         """
         return self.active
@@ -122,16 +115,13 @@ def is_active(self) -> bool:
     def from_dict(cls, data: dict) -> "ClientWindowInfo":
         """Creates a ClientWindowInfo instance from a dictionary.
 
-        Parameters:
-        -----------
+        Args:
             data: A dictionary containing the client window information.
 
         Returns:
-        -------
             ClientWindowInfo: A new instance of ClientWindowInfo.
 
         Raises:
-        ------
             ValueError: If required fields are missing or have invalid types.
         """
         try:
@@ -175,7 +165,7 @@ def from_dict(cls, data: dict) -> "ClientWindowInfo":
                 active=active,
             )
         except (KeyError, TypeError) as e:
-            raise ValueError(f"Invalid data format for ClientWindowInfo: {e}")
+            raise ValueError(f"Invalid data format for ClientWindowInfo: {e}") from e
 
 
 class Browser:
@@ -194,14 +184,12 @@ def create_user_context(
     ) -> str:
         """Creates a new user context.
 
-        Parameters:
-        -----------
-            accept_insecure_certs: Optional flag to accept insecure TLS certificates
-            proxy: Optional proxy configuration for the user context
-            unhandled_prompt_behavior: Optional configuration for handling user prompts
+        Args:
+            accept_insecure_certs: Optional flag to accept insecure TLS certificates.
+            proxy: Optional proxy configuration for the user context.
+            unhandled_prompt_behavior: Optional configuration for handling user prompts.
 
         Returns:
-        -------
             str: The ID of the created user context.
         """
         params: dict[str, Any] = {}
@@ -222,7 +210,6 @@ def get_user_contexts(self) -> list[str]:
         """Gets all user contexts.
 
         Returns:
-        -------
             List[str]: A list of user context IDs.
         """
         result = self.conn.execute(command_builder("browser.getUserContexts", {}))
@@ -231,16 +218,14 @@ def get_user_contexts(self) -> list[str]:
     def remove_user_context(self, user_context_id: str) -> None:
         """Removes a user context.
 
-        Parameters:
-        -----------
+        Args:
             user_context_id: The ID of the user context to remove.
 
         Raises:
-        ------
-            Exception: If the user context ID is "default" or does not exist.
+            ValueError: If the user context ID is "default" or does not exist.
         """
         if user_context_id == "default":
-            raise Exception("Cannot remove the default user context")
+            raise ValueError("Cannot remove the default user context")
 
         params = {"userContext": user_context_id}
         self.conn.execute(command_builder("browser.removeUserContext", params))
@@ -249,7 +234,6 @@ def get_client_windows(self) -> list[ClientWindowInfo]:
         """Gets all client windows.
 
         Returns:
-        -------
             List[ClientWindowInfo]: A list of client window information.
         """
         result = self.conn.execute(command_builder("browser.getClientWindows", {}))