Refactor docstrings for clarity and conciseness in multiple files

Author: iampopovich

py/selenium/webdriver/support/expected_conditions.py

@@ -74,8 +74,7 @@ def _predicate(driver: WebDriver):
 
 
 def presence_of_element_located(locator: tuple[str, str]) -> Callable[[WebDriverOrWebElement], WebElement]:
-    """An expectation for checking that an element is present on the DOM of a
-    page. This does not necessarily mean that the element is visible.
+    """Check that an element is present on the DOM (not necessarily visible).
 
     Args:
         locator: Used to find the element.
@@ -97,8 +96,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def url_contains(url: str) -> Callable[[WebDriver], bool]:
-    """An expectation for checking that the current url contains a case-
-    sensitive substring.
+    """Check that the current url contains a case-sensitive substring.
 
     Args:
         url: The fragment of url expected.
@@ -149,8 +147,7 @@ def _predicate(driver: WebDriver):
 
 
 def url_changes(url: str) -> Callable[[WebDriver], bool]:
-    """An expectation for checking the current url is different than a given
-    string.
+    """Check that the current url differs from a given string.
 
     Args:
         url: The expected url, which must not be an exact match.
@@ -168,9 +165,7 @@ def _predicate(driver: WebDriver):
 def visibility_of_element_located(
     locator: tuple[str, str],
 ) -> Callable[[WebDriverOrWebElement], Union[Literal[False], WebElement]]:
-    """An expectation for checking that an element is present on the DOM of a
-    page and visible. Visibility means that the element is not only displayed
-    but also has a height and width that is greater than 0.
+    """Check that an element is present on the DOM and visible (has size).
 
     Args:
         locator: Used to find the element.
@@ -195,11 +190,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def visibility_of(element: WebElement) -> Callable[[Any], Union[Literal[False], WebElement]]:
-    """An expectation for checking that an element, known to be present on the
-    DOM of a page, is visible.
-
-    Visibility means that the element is not only displayed but also has
-    a height and width that is greater than 0.
+    """Check that an element is visible (present on DOM and has size).
 
     Args:
         element: The WebElement to check.
@@ -221,8 +212,7 @@ def _predicate(_):
 
 
 def _element_if_visible(element: WebElement, visibility: bool = True) -> Union[Literal[False], WebElement]:
-    """An expectation for checking that an element, known to be present on the
-    DOM of a page, is of the expected visibility.
+    """Check if an element has the expected visibility state.
 
     Args:
         element: The WebElement to check.
@@ -235,8 +225,7 @@ def _element_if_visible(element: WebElement, visibility: bool = True) -> Union[L
 
 
 def presence_of_all_elements_located(locator: tuple[str, str]) -> Callable[[WebDriverOrWebElement], list[WebElement]]:
-    """An expectation for checking that there is at least one element present
-    on a web page.
+    """Check that all elements matching the locator are present on the DOM.
 
     Args:
         locator: Used to find the element.
@@ -258,8 +247,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def visibility_of_any_elements_located(locator: tuple[str, str]) -> Callable[[WebDriverOrWebElement], list[WebElement]]:
-    """An expectation for checking that there is at least one element visible
-    on a web page.
+    """Check that at least one element is visible on the web page.
 
     Args:
         locator: Used to find the element.
@@ -283,9 +271,7 @@ def _predicate(driver: WebDriverOrWebElement):
 def visibility_of_all_elements_located(
     locator: tuple[str, str],
 ) -> Callable[[WebDriverOrWebElement], Union[list[WebElement], Literal[False]]]:
-    """An expectation for checking that all elements are present on the DOM of
-    a page and visible. Visibility means that the elements are not only
-    displayed but also has a height and width that is greater than 0.
+    """Check that all elements are present on the DOM and visible (have size).
 
     Args:
         locator: Used to find the elements.
@@ -314,8 +300,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def text_to_be_present_in_element(locator: tuple[str, str], text_: str) -> Callable[[WebDriverOrWebElement], bool]:
-    """An expectation for checking if the given text is present in the
-    specified element.
+    """Check that the given text is present in the specified element.
 
     Args:
         locator: Used to find the element.
@@ -346,8 +331,7 @@ def _predicate(driver: WebDriverOrWebElement):
 def text_to_be_present_in_element_value(
     locator: tuple[str, str], text_: str
 ) -> Callable[[WebDriverOrWebElement], bool]:
-    """An expectation for checking if the given text is present in the
-    element's value.
+    """Check that the given text is present in the element's value.
 
     Args:
         locator: Used to find the element.
@@ -380,8 +364,7 @@ def _predicate(driver: WebDriverOrWebElement):
 def text_to_be_present_in_element_attribute(
     locator: tuple[str, str], attribute_: str, text_: str
 ) -> Callable[[WebDriverOrWebElement], bool]:
-    """An expectation for checking if the given text is present in the
-    element's attribute.
+    """Check that the given text is present in the element's attribute.
 
     Args:
         locator: Used to find the element.
@@ -415,11 +398,7 @@ def _predicate(driver: WebDriverOrWebElement):
 def frame_to_be_available_and_switch_to_it(
     locator: Union[tuple[str, str], str, WebElement],
 ) -> Callable[[WebDriver], bool]:
-    """An expectation for checking whether the given frame is available to
-    switch to.
-
-    If the frame is available it switches the given driver to the
-    specified frame.
+    """Check that the given frame is available and switch to it.
 
     Args:
         locator: Used to find the frame.
@@ -449,8 +428,7 @@ def _predicate(driver: WebDriver):
 def invisibility_of_element_located(
     locator: Union[WebElement, tuple[str, str]],
 ) -> Callable[[WebDriverOrWebElement], Union[WebElement, bool]]:
-    """An Expectation for checking that an element is either invisible or not
-    present on the DOM.
+    """Check that an element is either invisible or not present on the DOM.
 
     Args:
         locator: Used to find the element.
@@ -492,8 +470,7 @@ def _predicate(driver: WebDriverOrWebElement):
 def invisibility_of_element(
     element: Union[WebElement, tuple[str, str]],
 ) -> Callable[[WebDriverOrWebElement], Union[WebElement, bool]]:
-    """An Expectation for checking that an element is either invisible or not
-    present on the DOM.
+    """Check that an element is either invisible or not present on the DOM.
 
     Args:
         element: Used to find the element.
@@ -515,8 +492,7 @@ def invisibility_of_element(
 def element_to_be_clickable(
     mark: Union[WebElement, tuple[str, str]],
 ) -> Callable[[WebDriverOrWebElement], Union[Literal[False], WebElement]]:
-    """An Expectation for checking an element is visible and enabled such that
-    you can click it.
+    """Check that an element is visible and enabled so it can be clicked.
 
     Args:
         mark: Used to find the element.
@@ -646,8 +622,7 @@ def _predicate(_):
 def element_located_selection_state_to_be(
     locator: tuple[str, str], is_selected: bool
 ) -> Callable[[WebDriverOrWebElement], bool]:
-    """An expectation to locate an element and check if the selection state
-    specified is in that state.
+    """Check that an element's selection state matches the expected state.
 
     Args:
         locator: Used to find the element.
@@ -696,9 +671,8 @@ def _predicate(driver: WebDriver):
     return _predicate
 
 
-def new_window_is_opened(current_handles: list[str]) -> Callable[[WebDriver], bool]:
-    """An expectation that a new window will be opened and have the number of
-    windows handles increase.
+def new_window_is_opened(current_handles: set[str]) -> Callable[[WebDriver], bool]:
+    """Check that a new window has been opened (window handles count increased).
 
     Args:
         current_handles: The current window handles.
@@ -719,9 +693,8 @@ def _predicate(driver: WebDriver):
     return _predicate
 
 
-def alert_is_present() -> Callable[[WebDriver], Union[Alert, Literal[False]]]:
-    """An expectation for checking if an alert is currently present and
-    switching to it.
+def alert_is_present() -> Callable[[WebDriver], Union[Alert, bool]]:
+    """Check that an alert is present and switch to it.
 
     Returns:
         The Alert once it is located.
@@ -745,8 +718,7 @@ def _predicate(driver: WebDriver):
 
 
 def element_attribute_to_include(locator: tuple[str, str], attribute_: str) -> Callable[[WebDriverOrWebElement], bool]:
-    """An expectation for checking if the given attribute is included in the
-    specified element.
+    """Check if the given attribute is included in the specified element.
 
     Args:
         locator: Used to find the element.

py/selenium/webdriver/support/relative_locator.py

@@ -64,9 +64,9 @@ def locate_with(by: ByType, using: str) -> "RelativeBy":
 
 
 class RelativeBy:
-    """Gives the opportunity to find elements based on their relative location
-    on the page from a root element. It is recommended that you use the helper
-    function to create it.
+    """Find elements based on their relative location from a root element.
+
+    It is recommended that you use the helper function to create instances.
 
     Example:
     --------
@@ -80,8 +80,7 @@ class RelativeBy:
     LocatorType = dict[ByType, str]
 
     def __init__(self, root: Optional[dict[ByType, str]] = None, filters: Optional[list] = None):
-        """Creates a new RelativeBy object. It is preferred if you use the
-        `locate_with` method as this signature could change.
+        """Create a RelativeBy object (prefer using `locate_with` instead).
 
         Args:
             root: A dict with `By` enum as the key and the search query as the value
@@ -309,9 +308,7 @@ def near(self, element_or_locator: Union[WebElement, LocatorType, None] = None,
         return self
 
     def to_dict(self) -> dict:
-        """Create a dict that will be passed to the driver to start searching
-        for the element.
-        """
+        """Create a dict to be passed to the driver for element searching."""
         return {
             "relative": {
                 "root": self.root,

py/selenium/webdriver/support/select.py

@@ -23,15 +23,17 @@
 
 class Select:
     def __init__(self, webelement: WebElement) -> None:
-        """Constructor. A check is made that the given element is, indeed, a
-        SELECT tag. If it is not, then an UnexpectedTagNameException is thrown.
+        """Constructor. A check is made that the given element is a SELECT tag.
 
         Args:
             webelement: SELECT element to wrap
 
         Example:
             from selenium.webdriver.support.ui import Select
             Select(driver.find_element(By.TAG_NAME, "select")).select_by_index(2)
+
+        Raises:
+            UnexpectedTagNameException: If the element is not a SELECT tag
         """
         if webelement.tag_name.lower() != "select":
             raise UnexpectedTagNameException(f"Select only works on <select> elements, not on {webelement.tag_name}")
@@ -46,16 +48,12 @@ def options(self) -> list[WebElement]:
 
     @property
     def all_selected_options(self) -> list[WebElement]:
-        """Returns a list of all selected options belonging to this select
-        tag.
-        """
+        """Return a list of all selected options belonging to this select tag."""
         return [opt for opt in self.options if opt.is_selected()]
 
     @property
     def first_selected_option(self) -> WebElement:
-        """The first selected option in this select tag (or the currently
-        selected option in a normal select).
-        """
+        """Return the first selected option or the currently selected option."""
         for opt in self.options:
             if opt.is_selected():
                 return opt
@@ -87,8 +85,7 @@ def select_by_value(self, value: str) -> None:
             raise NoSuchElementException(f"Cannot locate option with value: {value}")
 
     def select_by_index(self, index: int) -> None:
-        """Select the option at the given index. This is done by examining the
-        "index" attribute of an element, and not merely by counting.
+        """Select the option at the given index by examining the "index" attribute.
 
         Args:
             index: The option at this index will be selected
@@ -185,8 +182,7 @@ def deselect_by_value(self, value: str) -> None:
             raise NoSuchElementException(f"Could not locate element with value: {value}")
 
     def deselect_by_index(self, index: int) -> None:
-        """Deselect the option at the given index. This is done by examining
-        the "index" attribute of an element, and not merely by counting.
+        """Deselect the option at the given index by examining the "index" attribute.
 
         Args:
             index: The option at this index will be deselected

py/selenium/webdriver/webkitgtk/options.py

@@ -29,10 +29,7 @@ def __init__(self) -> None:
 
     @property
     def binary_location(self) -> str:
-        """
-        Returns:
-            The location of the browser binary, otherwise an empty string.
-        """
+        """Return the location of the browser binary or an empty string."""
         return self._binary_location
 
     @binary_location.setter
@@ -45,11 +42,8 @@ def binary_location(self, value: str) -> None:
         self._binary_location = value
 
     @property
-    def overlay_scrollbars_enabled(self):
-        """
-        Returns:
-            Whether overlay scrollbars should be enabled.
-        """
+    def overlay_scrollbars_enabled(self) -> bool:
+        """Return whether overlay scrollbars should be enabled."""
         return self._overlay_scrollbars_enabled
 
     @overlay_scrollbars_enabled.setter
@@ -61,10 +55,8 @@ def overlay_scrollbars_enabled(self, value) -> None:
         """
         self._overlay_scrollbars_enabled = value
 
-    def to_capabilities(self):
-        """Creates a capabilities with all the options that have been set and
-        returns a dictionary with everything.
-        """
+    def to_capabilities(self)-> dict:
+        """Create a capabilities dictionary with all set options."""
         caps = self._caps
 
         browser_options = {}

py/selenium/webdriver/webkitgtk/service.py

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

py/selenium/webdriver/webkitgtk/webdriver.py

@@ -49,9 +49,7 @@ def __init__(
         self._is_remote = False
 
     def quit(self):
-        """Closes the browser and shuts down the WebKitGTKDriver executable
-        that is started when starting the WebKitGTKDriver.
-        """
+        """Close the browser and shut down the WebKitGTK driver executable."""
         try:
             super().quit()
         except http_client.BadStatusLine: