[py] Cleanup and convert more doctrings to google-style (#16503)

Author: iampopovich

py/selenium/webdriver/common/action_chains.py

@@ -69,9 +69,9 @@ class ActionChains:
     def __init__(self, driver: WebDriver, duration: int = 250, devices: list[AnyDevice] | None = None) -> None:
         """Creates a new ActionChains.
 
-        :Args:
-         - driver: The WebDriver instance which performs user actions.
-         - duration: override the default 250 msecs of DEFAULT_MOVE_DURATION in PointerInput
+        Args:
+            driver: The WebDriver instance which performs user actions.
+            duration: override the default 250 msecs of DEFAULT_MOVE_DURATION in PointerInput
         """
         self._driver = driver
         mouse = None
@@ -101,9 +101,9 @@ def reset_actions(self) -> None:
     def click(self, on_element: WebElement | None = None) -> ActionChains:
         """Clicks an element.
 
-        :Args:
-         - on_element: The element to click.
-           If None, clicks on current mouse position.
+        Args:
+            on_element: The element to click.
+                If None, clicks on current mouse position.
         """
         if on_element:
             self.move_to_element(on_element)
@@ -117,9 +117,9 @@ def click(self, on_element: WebElement | None = None) -> ActionChains:
     def click_and_hold(self, on_element: WebElement | None = None) -> ActionChains:
         """Holds down the left mouse button on an element.
 
-        :Args:
-         - on_element: The element to mouse down.
-           If None, clicks on current mouse position.
+        Args:
+            on_element: The element to mouse down.
+                If None, clicks on current mouse position.
         """
         if on_element:
             self.move_to_element(on_element)
@@ -132,9 +132,9 @@ def click_and_hold(self, on_element: WebElement | None = None) -> ActionChains:
     def context_click(self, on_element: WebElement | None = None) -> ActionChains:
         """Performs a context-click (right click) on an element.
 
-        :Args:
-         - on_element: The element to context-click.
-           If None, clicks on current mouse position.
+        Args:
+            on_element: The element to context-click.
+                If None, clicks on current mouse position.
         """
         if on_element:
             self.move_to_element(on_element)
@@ -148,9 +148,9 @@ def context_click(self, on_element: WebElement | None = None) -> ActionChains:
     def double_click(self, on_element: WebElement | None = None) -> ActionChains:
         """Double-clicks an element.
 
-        :Args:
-         - on_element: The element to double-click.
-           If None, clicks on current mouse position.
+        Args:
+            on_element: The element to double-click.
+                If None, clicks on current mouse position.
         """
         if on_element:
             self.move_to_element(on_element)
@@ -165,9 +165,9 @@ def drag_and_drop(self, source: WebElement, target: WebElement) -> ActionChains:
         """Holds down the left mouse button on the source element, then moves
         to the target element and releases the mouse button.
 
-        :Args:
-         - source: The element to mouse down.
-         - target: The element to mouse up.
+        Args:
+            source: The element to mouse down.
+            target: The element to mouse up.
         """
         self.click_and_hold(source)
         self.release(target)
@@ -177,10 +177,10 @@ def drag_and_drop_by_offset(self, source: WebElement, xoffset: int, yoffset: int
         """Holds down the left mouse button on the source element, then moves
         to the target offset and releases the mouse button.
 
-        :Args:
-         - source: The element to mouse down.
-         - xoffset: X offset to move to.
-         - yoffset: Y offset to move to.
+        Args:
+            source: The element to mouse down.
+            xoffset: X offset to move to.
+            yoffset: Y offset to move to.
         """
         self.click_and_hold(source)
         self.move_by_offset(xoffset, yoffset)
@@ -191,10 +191,10 @@ def key_down(self, value: str, element: WebElement | None = None) -> ActionChain
         """Sends a key press only, without releasing it. Should only be used
         with modifier keys (Control, Alt and Shift).
 
-        :Args:
-         - value: The modifier key to send. Values are defined in `Keys` class.
-         - element: The element to send keys.
-           If None, sends a key to current focused element.
+        Args:
+            value: The modifier key to send. Values are defined in `Keys` class.
+            element: The element to send keys.
+                If None, sends a key to current focused element.
 
         Example, pressing ctrl+c::
 
@@ -211,10 +211,10 @@ def key_down(self, value: str, element: WebElement | None = None) -> ActionChain
     def key_up(self, value: str, element: WebElement | None = None) -> ActionChains:
         """Releases a modifier key.
 
-        :Args:
-         - value: The modifier key to send. Values are defined in Keys class.
-         - element: The element to send keys.
-           If None, sends a key to current focused element.
+        Args:
+            value: The modifier key to send. Values are defined in Keys class.
+            element: The element to send keys.
+                If None, sends a key to current focused element.
 
         Example, pressing ctrl+c::
 
@@ -231,9 +231,9 @@ def key_up(self, value: str, element: WebElement | None = None) -> ActionChains:
     def move_by_offset(self, xoffset: int, yoffset: int) -> ActionChains:
         """Moving the mouse to an offset from current mouse position.
 
-        :Args:
-         - xoffset: X offset to move to, as a positive or negative integer.
-         - yoffset: Y offset to move to, as a positive or negative integer.
+        Args:
+            xoffset: X offset to move to, as a positive or negative integer.
+            yoffset: Y offset to move to, as a positive or negative integer.
         """
 
         self.w3c_actions.pointer_action.move_by(xoffset, yoffset)
@@ -244,8 +244,8 @@ def move_by_offset(self, xoffset: int, yoffset: int) -> ActionChains:
     def move_to_element(self, to_element: WebElement) -> ActionChains:
         """Moving the mouse to the middle of an element.
 
-        :Args:
-         - to_element: The WebElement to move to.
+        Args:
+            to_element: The WebElement to move to.
         """
 
         self.w3c_actions.pointer_action.move_to(to_element)
@@ -257,10 +257,10 @@ def move_to_element_with_offset(self, to_element: WebElement, xoffset: int, yoff
         """Move the mouse by an offset of the specified element. Offsets are
         relative to the in-view center point of the element.
 
-        :Args:
-         - to_element: The WebElement to move to.
-         - xoffset: X offset to move to, as a positive or negative integer.
-         - yoffset: Y offset to move to, as a positive or negative integer.
+        Args:
+            to_element: The WebElement to move to.
+            xoffset: X offset to move to, as a positive or negative integer.
+            yoffset: Y offset to move to, as a positive or negative integer.
         """
 
         self.w3c_actions.pointer_action.move_to(to_element, int(xoffset), int(yoffset))
@@ -279,9 +279,9 @@ def pause(self, seconds: float | int) -> ActionChains:
     def release(self, on_element: WebElement | None = None) -> ActionChains:
         """Releasing a held mouse button on an element.
 
-        :Args:
-         - on_element: The element to mouse up.
-           If None, releases on current mouse position.
+        Args:
+            on_element: The element to mouse up.
+                If None, releases on current mouse position.
         """
         if on_element:
             self.move_to_element(on_element)
@@ -294,9 +294,9 @@ def release(self, on_element: WebElement | None = None) -> ActionChains:
     def send_keys(self, *keys_to_send: str) -> ActionChains:
         """Sends keys to current focused element.
 
-        :Args:
-         - keys_to_send: The keys to send.  Modifier keys constants can be found in the
-           'Keys' class.
+        Args:
+            keys_to_send: The keys to send. Modifier keys constants can be found in the
+                'Keys' class.
         """
         typing = keys_to_typing(keys_to_send)
 
@@ -309,10 +309,10 @@ def send_keys(self, *keys_to_send: str) -> ActionChains:
     def send_keys_to_element(self, element: WebElement, *keys_to_send: str) -> ActionChains:
         """Sends keys to an element.
 
-        :Args:
-         - element: The element to send keys.
-         - keys_to_send: The keys to send.  Modifier keys constants can be found in the
-           'Keys' class.
+        Args:
+            element: The element to send keys.
+            keys_to_send: The keys to send. Modifier keys constants can be found in the
+                'Keys' class.
         """
         self.click(element)
         self.send_keys(*keys_to_send)
@@ -322,8 +322,8 @@ def scroll_to_element(self, element: WebElement) -> ActionChains:
         """If the element is outside the viewport, scrolls the bottom of the
         element to the bottom of the viewport.
 
-        :Args:
-         - element: Which element to scroll into the viewport.
+        Args:
+            element: Which element to scroll into the viewport.
         """
 
         self.w3c_actions.wheel_action.scroll(origin=element)
@@ -333,9 +333,9 @@ def scroll_by_amount(self, delta_x: int, delta_y: int) -> ActionChains:
         """Scrolls by provided amounts with the origin in the top left corner
         of the viewport.
 
-        :Args:
-         - delta_x: Distance along X axis to scroll using the wheel. A negative value scrolls left.
-         - delta_y: Distance along Y axis to scroll using the wheel. A negative value scrolls up.
+        Args:
+            delta_x: Distance along X axis to scroll using the wheel. A negative value scrolls left.
+            delta_y: Distance along Y axis to scroll using the wheel. A negative value scrolls up.
         """
 
         self.w3c_actions.wheel_action.scroll(delta_x=delta_x, delta_y=delta_y)
@@ -348,13 +348,13 @@ def scroll_from_origin(self, scroll_origin: ScrollOrigin, delta_x: int, delta_y:
         is not in the viewport, the bottom of the element will first be
         scrolled to the bottom of the viewport.
 
-        :Args:
-         - origin: Where scroll originates (viewport or element center) plus provided offsets.
-         - delta_x: Distance along X axis to scroll using the wheel. A negative value scrolls left.
-         - delta_y: Distance along Y axis to scroll using the wheel. A negative value scrolls up.
+        Args:
+            scroll_origin: Where scroll originates (viewport or element center) plus provided offsets.
+            delta_x: Distance along X axis to scroll using the wheel. A negative value scrolls left.
+            delta_y: Distance along Y axis to scroll using the wheel. A negative value scrolls up.
 
-         :Raises: If the origin with offset is outside the viewport.
-          - MoveTargetOutOfBoundsException - If the origin with offset is outside the viewport.
+        Raises:
+            MoveTargetOutOfBoundsException: If the origin with offset is outside the viewport.
         """
 
         if not isinstance(scroll_origin, ScrollOrigin):

py/selenium/webdriver/common/alert.py

@@ -47,8 +47,8 @@ class Alert:
     def __init__(self, driver) -> None:
         """Creates a new Alert.
 
-        :Args:
-         - driver: The WebDriver instance which performs user actions.
+        Args:
+            driver: The WebDriver instance which performs user actions.
         """
         self.driver = driver
 
@@ -64,17 +64,15 @@ def dismiss(self) -> None:
     def accept(self) -> None:
         """Accepts the alert available.
 
-        :Usage:
-            ::
-
-                Alert(driver).accept()  # Confirm a alert dialog.
+        Example:
+            Alert(driver).accept()  # Confirm a alert dialog.
         """
         self.driver.execute(Command.W3C_ACCEPT_ALERT)
 
     def send_keys(self, keysToSend: str) -> None:
         """Send Keys to the Alert.
 
-        :Args:
-         - keysToSend: The text to be sent to Alert.
+        Args:
+            keysToSend: The text to be sent to Alert.
         """
         self.driver.execute(Command.W3C_SET_ALERT_VALUE, {"value": keys_to_typing(keysToSend), "text": keysToSend})

py/selenium/webdriver/common/log.py

@@ -57,9 +57,7 @@ def __init__(self, driver, bidi_session) -> None:
     async def mutation_events(self) -> AsyncGenerator[dict[str, Any], None]:
         """Listen for mutation events and emit them as they are found.
 
-        :Usage:
-             ::
-
+        Example:
                async with driver.log.mutation_events() as event:
                     pages.load("dynamic.html")
                     driver.find_element(By.ID, "reveal").click()
@@ -101,9 +99,7 @@ async def add_js_error_listener(self) -> AsyncGenerator[dict[str, Any], None]:
         """Listen for JS errors and when the contextmanager exits check if
         there were JS Errors.
 
-        :Usage:
-             ::
-
+        Example:
                 async with driver.log.add_js_error_listener() as error:
                     driver.find_element(By.ID, "throwing-mouseover").click()
                 assert bool(error)
@@ -124,12 +120,10 @@ async def add_js_error_listener(self) -> AsyncGenerator[dict[str, Any], None]:
     async def add_listener(self, event_type) -> AsyncGenerator[dict[str, Any], None]:
         """Listen for certain events that are passed in.
 
-        :Args:
-         - event_type: The type of event that we want to look at.
-
-        :Usage:
-             ::
+        Args:
+            event_type: The type of event that we want to look at.
 
+        Example:
                 async with driver.log.add_listener(Console.log) as messages:
                     driver.execute_script("console.log('I like cheese')")
                 assert messages["message"] == "I love cheese"