Merge branch 'trunk' into null-support-1

Author: RenderMichael

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

@@ -49,6 +49,17 @@ def __init__(
         self.driver = driver
 
     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.
+
+        Returns:
+        --------
+        Optional[Union[WheelInput, PointerInput, KeyInput]] : The device with the given name.
+        """
         return next(filter(lambda x: x == name, self.devices), None)
 
     @property
@@ -72,21 +83,83 @@ def wheel_action(self) -> WheelActions:
         return self._wheel_action
 
     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.
+
+        Returns:
+        --------
+        KeyInput : The newly created key input device.
+
+        Example:
+        --------
+        >>> action_builder = ActionBuilder(driver)
+        >>> action_builder.add_key_input(name="keyboard2")
+        """
         new_input = KeyInput(name)
         self._add_input(new_input)
         return new_input
 
     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.
+
+        Returns:
+        --------
+        PointerInput : The newly created pointer input device.
+
+        Example:
+        --------
+        >>> action_builder = ActionBuilder(driver)
+        >>> action_builder.add_pointer_input(kind="mouse", name="mouse")
+        """
         new_input = PointerInput(kind, name)
         self._add_input(new_input)
         return new_input
 
     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.
+
+        Returns:
+        --------
+        WheelInput : The newly created wheel input device.
+
+        Example:
+        --------
+        >>> action_builder = ActionBuilder(driver)
+        >>> action_builder.add_wheel_input(name="wheel2")
+        """
         new_input = WheelInput(name)
         self._add_input(new_input)
         return new_input
 
     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()
+        """
         enc = {"actions": []}
         for device in self.devices:
             encoded = device.encode()
@@ -96,8 +169,24 @@ def perform(self) -> None:
         self.driver.execute(Command.W3C_ACTIONS, enc)
 
     def clear_actions(self) -> None:
-        """Clears actions that are already stored on the remote end."""
+        """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()
+        """
         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.
+        """
         self.devices.append(new_input)