[py] Added Docstrings to RelativeBy Class and Added Missing Deprecation Warning to with_tag_name() (SeleniumHQ#15097)

Author: shbenzer

py/selenium/webdriver/support/relative_locator.py

@@ -14,6 +14,7 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
+import warnings
 from typing import Dict
 from typing import List
 from typing import NoReturn
@@ -30,15 +31,29 @@
 def with_tag_name(tag_name: str) -> "RelativeBy":
     """Start searching for relative objects using a tag name.
 
-    Note: This method may be removed in future versions, please use
-    `locate_with` instead.
-
-    :Args:
-        - tag_name: the DOM tag of element to start searching.
-    :Returns:
-        - RelativeBy: use this object to create filters within a
-              `find_elements` call.
+    Parameters:
+    ----------
+    tag_name : str
+        The DOM tag of element to start searching.
+
+    Returns:
+    --------
+    RelativeBy
+        Use this object to create filters within a `find_elements` call.
+
+    Raises:
+    -------
+    WebDriverException
+        If `tag_name` is None.
+
+    Notes:
+    ------
+    - This method is deprecated and may be removed in future versions.
+    - Please use `locate_with` instead.
     """
+    warnings.warn(
+        "This method is deprecated and may be removed in future versions. " "Please use `locate_with` instead."
+    )
     if not tag_name:
         raise WebDriverException("tag_name can not be null")
     return RelativeBy({By.CSS_SELECTOR: tag_name})
@@ -47,12 +62,23 @@ def with_tag_name(tag_name: str) -> "RelativeBy":
 def locate_with(by: ByType, using: str) -> "RelativeBy":
     """Start searching for relative objects your search criteria with By.
 
-    :Args:
-        - by: The value from `By` passed in.
-        - using: search term to find the element with.
-    :Returns:
-        - RelativeBy: use this object to create filters within a
-              `find_elements` call.
+    Parameters:
+    ----------
+    by : ByType
+        The method to find the element.
+
+    using : str
+        The value from `By` passed in.
+
+    Returns:
+    --------
+    RelativeBy
+        Use this object to create filters within a `find_elements` call.
+
+    Example:
+    --------
+    >>> lowest = driver.find_element(By.ID, "below")
+    >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
     """
     assert by is not None, "Please pass in a by argument"
     assert using is not None, "Please pass in a using argument"
@@ -65,13 +91,12 @@ class RelativeBy:
     function to create it.
 
     Example:
-        lowest = driver.find_element(By.ID, "below")
-
-        elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
-
-        ids = [el.get_attribute('id') for el in elements]
-        assert "above" in ids
-        assert "mid" in ids
+    --------
+    >>> lowest = driver.find_element(By.ID, "below")
+    >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
+    >>> ids = [el.get_attribute('id') for el in elements]
+    >>> assert "above" in ids
+    >>> assert "mid" in ids
     """
 
     LocatorType = Dict[ByType, str]
@@ -80,9 +105,13 @@ def __init__(self, root: Optional[Dict[ByType, str]] = None, filters: Optional[L
         """Creates a new RelativeBy object. It is preferred if you use the
         `locate_with` method as this signature could change.
 
-        :Args:
-            root - A dict with `By` enum as the key and the search query as the value
-            filters - A list of the filters that will be searched. If none are passed
+        Attributes:
+        ----------
+        root : Dict[By, str]
+            - A dict with `By` enum as the key and the search query as the value
+
+        filters : List
+            - A list of the filters that will be searched. If none are passed
                 in please use the fluent API on the object to create the filters
         """
         self.root = root
@@ -97,8 +126,24 @@ def above(self, element_or_locator: None = None) -> "NoReturn": ...
     def above(self, element_or_locator: Union[WebElement, LocatorType, None] = None) -> "RelativeBy":
         """Add a filter to look for elements above.
 
-        :Args:
-            - element_or_locator: Element to look above
+        Parameters:
+        ----------
+        element_or_locator : Union[WebElement, Dict, None]
+            Element to look above
+
+        Returns:
+        --------
+        RelativeBy
+
+        Raises:
+        -------
+        WebDriverException
+            If `element_or_locator` is None.
+
+        Example:
+        --------
+        >>> lowest = driver.find_element(By.ID, "below")
+        >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
         """
         if not element_or_locator:
             raise WebDriverException("Element or locator must be given when calling above method")
@@ -115,8 +160,24 @@ def below(self, element_or_locator: None = None) -> "NoReturn": ...
     def below(self, element_or_locator: Union[WebElement, Dict, None] = None) -> "RelativeBy":
         """Add a filter to look for elements below.
 
-        :Args:
-            - element_or_locator: Element to look below
+        Parameters:
+        ----------
+        element_or_locator : Union[WebElement, Dict, None]
+            Element to look below
+
+        Returns:
+        --------
+        RelativeBy
+
+        Raises:
+        -------
+        WebDriverException
+            If `element_or_locator` is None.
+
+        Example:
+        --------
+        >>> highest = driver.find_element(By.ID, "high")
+        >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").below(highest))
         """
         if not element_or_locator:
             raise WebDriverException("Element or locator must be given when calling below method")
@@ -133,8 +194,24 @@ def to_left_of(self, element_or_locator: None = None) -> "NoReturn": ...
     def to_left_of(self, element_or_locator: Union[WebElement, Dict, None] = None) -> "RelativeBy":
         """Add a filter to look for elements to the left of.
 
-        :Args:
-            - element_or_locator: Element to look to the left of
+        Parameters:
+        ----------
+        element_or_locator : Union[WebElement, Dict, None]
+            Element to look to the left of
+
+        Returns:
+        --------
+        RelativeBy
+
+        Raises:
+        -------
+        WebDriverException
+            If `element_or_locator` is None.
+
+        Example:
+        --------
+        >>> right = driver.find_element(By.ID, "right")
+        >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").to_left_of(right))
         """
         if not element_or_locator:
             raise WebDriverException("Element or locator must be given when calling to_left_of method")
@@ -151,8 +228,24 @@ def to_right_of(self, element_or_locator: None = None) -> "NoReturn": ...
     def to_right_of(self, element_or_locator: Union[WebElement, Dict, None] = None) -> "RelativeBy":
         """Add a filter to look for elements right of.
 
-        :Args:
-            - element_or_locator: Element to look right of
+        Parameters:
+        ----------
+        element_or_locator : Union[WebElement, Dict, None]
+            Element to look right of
+
+        Returns:
+        --------
+        RelativeBy
+
+        Raises:
+        -------
+        WebDriverException
+            If `element_or_locator` is None.
+
+        Example:
+        --------
+        >>> left = driver.find_element(By.ID, "left")
+        >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").to_right_of(left))
         """
         if not element_or_locator:
             raise WebDriverException("Element or locator must be given when calling to_right_of method")
@@ -241,9 +334,28 @@ def near(self, element_or_locator: None = None, distance: int = 50) -> "NoReturn
     def near(self, element_or_locator: Union[WebElement, LocatorType, None] = None, distance: int = 50) -> "RelativeBy":
         """Add a filter to look for elements near.
 
-        :Args:
-            - element_or_locator: Element to look near by the element or within a distance
-            - distance: distance in pixel
+        Parameters:
+        ----------
+        element_or_locator : Union[WebElement, Dict, None]
+            Element to look near by the element or within a distance
+
+        distance : int
+            Distance in pixel
+
+        Returns:
+        --------
+        RelativeBy
+
+        Raises:
+        -------
+        WebDriverException
+            - If `element_or_locator` is None
+            - If `distance` is less than or equal to 0.
+
+        Example:
+        --------
+        >>> near = driver.find_element(By.ID, "near")
+        >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").near(near, 50))
         """
         if not element_or_locator:
             raise WebDriverException("Element or locator must be given when calling near method")