diff --git a/py/selenium/webdriver/support/relative_locator.py b/py/selenium/webdriver/support/relative_locator.py index d1ccbc257ac3f..db4292697c592 100644 --- a/py/selenium/webdriver/support/relative_locator.py +++ b/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") @@ -169,9 +262,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")