Refactor docstrings for clarity and conciseness across multiple files

Author: iampopovich

py/generate_api_module_listing.py

@@ -16,12 +16,13 @@
 # under the License.
 
 
-"""This script recursively scans the `selenium` package directory
-to find all modules, then generates the `py/docs/source/api.rst`
-file containing a listing of all modules in separate sections.
-The `api.rst` file is later used by `sphinx-autogen` to generate
-sphinx autodoc stub pages used in the Python API documentation.
-See `py/tox.ini` for how it is invoked.
+"""This script recursively scans the `selenium` package directory and generates an API listing.
+
+Recursively scans the `selenium` package directory to find all modules,
+then generates the `py/docs/source/api.rst` file containing a listing of all
+modules in separate sections. The `api.rst` file is later used by
+`sphinx-autogen` to generate sphinx autodoc stub pages used in the Python API
+documentation. See `py/tox.ini` for how it is invoked.
 """
 
 import os

py/selenium/common/exceptions.py

@@ -91,9 +91,7 @@ class NoSuchAttributeException(WebDriverException):
 
 
 class NoSuchShadowRootException(WebDriverException):
-    """Thrown when trying to access the shadow root of an element when it does
-    not have a shadow root attached.
-    """
+    """Thrown when trying to access the shadow root of an element when it does not have a shadow root attached."""
 
 
 class StaleElementReferenceException(WebDriverException):
@@ -121,11 +119,9 @@ def __init__(
 
 
 class InvalidElementStateException(WebDriverException):
-    """Thrown when a command could not be completed because the element is in
-    an invalid state.
+    """Thrown when a command could not be completed because the element is in an invalid state.
 
-    This can be caused by attempting to clear an element that isn't both
-    editable and resettable.
+    This can be caused by attempting to clear an element that isn't both editable and resettable.
     """
 
 
@@ -159,11 +155,9 @@ class NoAlertPresentException(WebDriverException):
 
 
 class ElementNotVisibleException(InvalidElementStateException):
-    """Thrown when an element is present on the DOM, but it is not visible, and
-    so is not able to be interacted with.
+    """Thrown when an element is present on the DOM, but it is not visible, and so is not able to be interacted with.
 
-    Most commonly encountered when trying to click or read text of an
-    element that is hidden from view.
+    Most commonly encountered when trying to click or read text of an element that is hidden from view.
     """
 
     def __init__(
@@ -175,9 +169,7 @@ def __init__(
 
 
 class ElementNotInteractableException(InvalidElementStateException):
-    """Thrown when an element is present in the DOM but interactions with that
-    element will hit another element due to paint order.
-    """
+    """Thrown when element interactions will hit another element due to paint order."""
 
     def __init__(
         self, msg: Optional[Any] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
@@ -195,9 +187,7 @@ class ElementNotSelectableException(InvalidElementStateException):
 
 
 class InvalidCookieDomainException(WebDriverException):
-    """Thrown when attempting to add a cookie under a different domain than the
-    current URL.
-    """
+    """Thrown when attempting to add a cookie under a different domain."""
 
 
 class UnableToSetCookieException(WebDriverException):
@@ -209,23 +199,17 @@ class TimeoutException(WebDriverException):
 
 
 class MoveTargetOutOfBoundsException(WebDriverException):
-    """Thrown when the target provided to the `ActionsChains` move() method is
-    invalid, i.e. out of document.
-    """
+    """Thrown when the target provided to the `ActionsChains` move() method is invalid, i.e. out of document."""
 
 
 class UnexpectedTagNameException(WebDriverException):
     """Thrown when a support class did not get an expected web element."""
 
 
 class InvalidSelectorException(WebDriverException):
-    """Thrown when the selector which is used to find an element does not
-    return a WebElement.
+    """Thrown when the selector used to find an element does not return a WebElement.
 
-    Currently this only happens when the selector is an xpath expression
-    and it is either syntactically invalid (i.e. it is not a xpath
-    expression) or the expression does not select WebElements (e.g.
-    "count(//input)").
+    Currently this only happens when the XPath expression is syntactically invalid or does not select WebElements.
     """
 
     def __init__(
@@ -257,20 +241,15 @@ class JavascriptException(WebDriverException):
 
 
 class NoSuchCookieException(WebDriverException):
-    """No cookie matching the given path name was found amongst the associated
-    cookies of the current browsing context's active document.
-    """
+    """Thrown when no cookie matching the given path name was found."""
 
 
 class ScreenshotException(WebDriverException):
     """A screen capture was made impossible."""
 
 
 class ElementClickInterceptedException(WebDriverException):
-    """The Element Click command could not be completed because the element
-    receiving the events is obscuring the element that was requested to be
-    clicked.
-    """
+    """Thrown when element click fails because another element obscures it."""
 
     def __init__(
         self, msg: Optional[Any] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
@@ -281,19 +260,15 @@ def __init__(
 
 
 class InsecureCertificateException(WebDriverException):
-    """Navigation caused the user agent to hit a certificate warning, which is
-    usually the result of an expired or invalid TLS certificate.
-    """
+    """Thrown when the user agent hits a certificate warning (expired or invalid TLS certificate)."""
 
 
 class InvalidCoordinatesException(WebDriverException):
     """The coordinates provided to an interaction's operation are invalid."""
 
 
 class InvalidSessionIdException(WebDriverException):
-    """Occurs if the given session id is not in the list of active sessions,
-    meaning the session either does not exist or that it's not active.
-    """
+    """Thrown when the given session id is not in the list of active sessions."""
 
     def __init__(
         self, msg: Optional[Any] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
@@ -315,9 +290,7 @@ def __init__(
 
 
 class UnknownMethodException(WebDriverException):
-    """The requested command matched a known URL but did not match any methods
-    for that URL.
-    """
+    """The requested command matched a known URL but did not match any methods for that URL."""
 
 
 class NoSuchDriverException(WebDriverException):

py/selenium/webdriver/chrome/service.py

@@ -24,8 +24,7 @@
 
 
 class Service(service.ChromiumService):
-    """A Service class that is responsible for the starting and stopping of
-    `chromedriver`.
+    """Service class responsible for starting and stopping the chromedriver executable.
 
     Args:
         executable_path: Install path of the chromedriver executable, defaults

py/selenium/webdriver/chromium/service.py

@@ -24,8 +24,7 @@
 
 
 class ChromiumService(service.Service):
-    """A Service class that is responsible for the starting and stopping the
-    WebDriver instance of the ChromiumDriver.
+    """Service class responsible for starting and stopping the ChromiumDriver WebDriver instance.
 
     Args:
         executable_path: Install path of the executable.

py/selenium/webdriver/common/action_chains.py

@@ -34,7 +34,9 @@
 
 
 class ActionChains:
-    """ActionChains are a way to automate low level interactions such as mouse
+    """Automate low-level interactions like mouse movements, button actions, key presses, and context menus.
+
+    ActionChains are a way to automate low level interactions such as mouse
     movements, mouse button actions, key press, and context menu interactions.
     This is useful for doing more complex actions like hover over and drag and
     drop.
@@ -94,9 +96,7 @@ def perform(self) -> None:
         self.w3c_actions.perform()
 
     def reset_actions(self) -> None:
-        """Clears actions that are already stored locally and on the remote
-        end.
-        """
+        """Clear actions stored locally and on the remote end."""
         self.w3c_actions.clear_actions()
         for device in self.w3c_actions.devices:
             device.clear_actions()
@@ -165,8 +165,7 @@ def double_click(self, on_element: WebElement | None = None) -> ActionChains:
         return self
 
     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.
+        """Hold down the left mouse button on an element, then move to target and release.
 
         Args:
             source: The element to mouse down.
@@ -177,8 +176,7 @@ def drag_and_drop(self, source: WebElement, target: WebElement) -> ActionChains:
         return self
 
     def drag_and_drop_by_offset(self, source: WebElement, xoffset: int, yoffset: int) -> ActionChains:
-        """Holds down the left mouse button on the source element, then moves
-        to the target offset and releases the mouse button.
+        """Hold down the left mouse button on an element, then move by offset and release.
 
         Args:
             source: The element to mouse down.
@@ -191,8 +189,7 @@ def drag_and_drop_by_offset(self, source: WebElement, xoffset: int, yoffset: int
         return self
 
     def key_down(self, value: str, element: WebElement | None = None) -> ActionChains:
-        """Sends a key press only, without releasing it. Should only be used
-        with modifier keys (Control, Alt and Shift).
+        """Send a key press only without releasing it (modifier keys only).
 
         Args:
             value: The modifier key to send. Values are defined in `Keys` class.
@@ -255,8 +252,9 @@ def move_to_element(self, to_element: WebElement) -> ActionChains:
         return self
 
     def move_to_element_with_offset(self, to_element: WebElement, xoffset: int, yoffset: int) -> ActionChains:
-        """Move the mouse by an offset of the specified element. Offsets are
-        relative to the in-view center point of the element.
+        """Move the mouse to an element with the specified offsets.
+
+        Offsets are relative to the in-view center point of the element.
 
         Args:
             to_element: The WebElement to move to.
@@ -318,8 +316,9 @@ def send_keys_to_element(self, element: WebElement, *keys_to_send: str) -> Actio
         return self
 
     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.
+        """Scroll the element into the viewport if it's outside it.
+
+        Scrolls the bottom of the element to the bottom of the viewport.
 
         Args:
             element: Which element to scroll into the viewport.
@@ -328,7 +327,9 @@ def scroll_to_element(self, element: WebElement) -> ActionChains:
         return self
 
     def scroll_by_amount(self, delta_x: int, delta_y: int) -> ActionChains:
-        """Scrolls by provided amounts with the origin in the top left corner
+        """Scroll by a provided amount with the origin in the top left corner.
+
+        Scrolls by provided amounts with the origin in the top left corner
         of the viewport.
 
         Args:
@@ -339,8 +340,9 @@ def scroll_by_amount(self, delta_x: int, delta_y: int) -> ActionChains:
         return self
 
     def scroll_from_origin(self, scroll_origin: ScrollOrigin, delta_x: int, delta_y: int) -> ActionChains:
-        """Scrolls by provided amount based on a provided origin. The scroll
-        origin is either the center of an element or the upper left of the
+        """Scroll by a provided amount based on a scroll origin (element or viewport).
+
+        The scroll origin is either the center of an element or the upper left of the
         viewport plus any offsets. If the origin is an element, and the element
         is not in the viewport, the bottom of the element will first be
         scrolled to the bottom of the viewport.

py/selenium/webdriver/common/bidi/browsing_context.py

@@ -812,7 +812,9 @@ def get_tree(
         max_depth: Optional[int] = None,
         root: Optional[str] = None,
     ) -> list[BrowsingContextInfo]:
-        """Returns a tree of all descendent navigables including the given parent itself, or all top-level contexts
+        """Get a tree of all descendent navigables including the given parent itself.
+
+        Returns a tree of all descendent navigables including the given parent itself, or all top-level contexts
         when no parent is provided.
 
         Args:
@@ -917,8 +919,7 @@ def print(
         scale: float = 1.0,
         shrink_to_fit: bool = True,
     ) -> str:
-        """Creates a paginated representation of a document, and returns it as a PDF document represented as a
-        Base64-encoded string.
+        """Create a paginated PDF representation of the document as a Base64-encoded string.
 
         Args:
             context: The browsing context ID.