diff --git a/py/selenium/webdriver/common/actions/action_builder.py b/py/selenium/webdriver/common/actions/action_builder.py index 63bfe6db57a34..8b7a90bf4302e 100644 --- a/py/selenium/webdriver/common/actions/action_builder.py +++ b/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)