From 719af2dea1978f5117bfe23ad717f6ba6f19fcb1 Mon Sep 17 00:00:00 2001 From: Simon Benzer Date: Wed, 15 Jan 2025 20:05:21 -0500 Subject: [PATCH 1/3] [py] Added Docstrings to RelativeBy Class --- .../webdriver/support/relative_locator.py | 182 ++++++++++++++---- 1 file changed, 147 insertions(+), 35 deletions(-) diff --git a/py/selenium/webdriver/support/relative_locator.py b/py/selenium/webdriver/support/relative_locator.py index d1ccbc257ac3f..0069fed5db378 100644 --- a/py/selenium/webdriver/support/relative_locator.py +++ b/py/selenium/webdriver/support/relative_locator.py @@ -21,6 +21,8 @@ from typing import Union from typing import overload +import warnings + from selenium.common.exceptions import WebDriverException from selenium.webdriver.common.by import By from selenium.webdriver.common.by import ByType @@ -30,15 +32,28 @@ 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") From 82f76a3a4aa9f53a1f7e7907541d77ddf5567216 Mon Sep 17 00:00:00 2001 From: Simon Benzer Date: Wed, 15 Jan 2025 20:08:03 -0500 Subject: [PATCH 2/3] format.sh --- .../webdriver/support/relative_locator.py | 14 ++++---- scripts/format.sh | 32 +++++++++---------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/py/selenium/webdriver/support/relative_locator.py b/py/selenium/webdriver/support/relative_locator.py index 0069fed5db378..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 @@ -21,8 +22,6 @@ from typing import Union from typing import overload -import warnings - from selenium.common.exceptions import WebDriverException from selenium.webdriver.common.by import By from selenium.webdriver.common.by import ByType @@ -36,7 +35,7 @@ def with_tag_name(tag_name: str) -> "RelativeBy": ---------- tag_name : str The DOM tag of element to start searching. - + Returns: -------- RelativeBy @@ -52,8 +51,9 @@ def with_tag_name(tag_name: str) -> "RelativeBy": - 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.") + 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}) @@ -266,10 +266,10 @@ def near(self, element_or_locator: Union[WebElement, LocatorType, None] = None, ---------- 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 diff --git a/scripts/format.sh b/scripts/format.sh index df0156aa14efe..39f1e2ff39b07 100755 --- a/scripts/format.sh +++ b/scripts/format.sh @@ -14,22 +14,22 @@ section "Buildifier" echo " buildifier" >&2 bazel run //:buildifier -section "Java" -echo " google-java-format" >&2 -find "$PWD/java" -type f -name '*.java' | xargs "$GOOGLE_JAVA_FORMAT" --replace - -section "Javascript" -echo " javascript/node/selenium-webdriver - prettier" >&2 -NODE_WEBDRIVER="${WORKSPACE_ROOT}/javascript/node/selenium-webdriver" -bazel run //javascript:prettier -- "${NODE_WEBDRIVER}" --write "${NODE_WEBDRIVER}/.prettierrc" - -section "Ruby" -echo " rubocop" >&2 -bazel run //rb:lint - -section "Rust" -echo " rustfmt" >&2 -bazel run @rules_rust//:rustfmt +# section "Java" +# echo " google-java-format" >&2 +# find "$PWD/java" -type f -name '*.java' | xargs "$GOOGLE_JAVA_FORMAT" --replace + +# section "Javascript" +# echo " javascript/node/selenium-webdriver - prettier" >&2 +# NODE_WEBDRIVER="${WORKSPACE_ROOT}/javascript/node/selenium-webdriver" +# bazel run //javascript:prettier -- "${NODE_WEBDRIVER}" --write "${NODE_WEBDRIVER}/.prettierrc" + +# section "Ruby" +# echo " rubocop" >&2 +# bazel run //rb:lint + +# section "Rust" +# echo " rustfmt" >&2 +# bazel run @rules_rust//:rustfmt # TODO: use bazel target when rules_python supports formatting section "Python" From 5a13e45485990441136d1440f79d22cb8745ce55 Mon Sep 17 00:00:00 2001 From: Simon Benzer <69980130+shbenzer@users.noreply.github.com> Date: Wed, 15 Jan 2025 20:08:32 -0500 Subject: [PATCH 3/3] undo commenting --- scripts/format.sh | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/scripts/format.sh b/scripts/format.sh index 39f1e2ff39b07..df0156aa14efe 100755 --- a/scripts/format.sh +++ b/scripts/format.sh @@ -14,22 +14,22 @@ section "Buildifier" echo " buildifier" >&2 bazel run //:buildifier -# section "Java" -# echo " google-java-format" >&2 -# find "$PWD/java" -type f -name '*.java' | xargs "$GOOGLE_JAVA_FORMAT" --replace - -# section "Javascript" -# echo " javascript/node/selenium-webdriver - prettier" >&2 -# NODE_WEBDRIVER="${WORKSPACE_ROOT}/javascript/node/selenium-webdriver" -# bazel run //javascript:prettier -- "${NODE_WEBDRIVER}" --write "${NODE_WEBDRIVER}/.prettierrc" - -# section "Ruby" -# echo " rubocop" >&2 -# bazel run //rb:lint - -# section "Rust" -# echo " rustfmt" >&2 -# bazel run @rules_rust//:rustfmt +section "Java" +echo " google-java-format" >&2 +find "$PWD/java" -type f -name '*.java' | xargs "$GOOGLE_JAVA_FORMAT" --replace + +section "Javascript" +echo " javascript/node/selenium-webdriver - prettier" >&2 +NODE_WEBDRIVER="${WORKSPACE_ROOT}/javascript/node/selenium-webdriver" +bazel run //javascript:prettier -- "${NODE_WEBDRIVER}" --write "${NODE_WEBDRIVER}/.prettierrc" + +section "Ruby" +echo " rubocop" >&2 +bazel run //rb:lint + +section "Rust" +echo " rustfmt" >&2 +bazel run @rules_rust//:rustfmt # TODO: use bazel target when rules_python supports formatting section "Python"