[py] Support RelativeBy in type annotations

Author: gryznar

py/selenium/webdriver/remote/shadowroot.py

@@ -16,9 +16,12 @@
 # under the License.
 
 from hashlib import md5 as md5_hash
+from typing import List, Optional, Union
 
-from ..common.by import By
+from ..common.by import By, ByType
+from ..support.relative_locator import RelativeBy
 from .command import Command
+from .webelement import WebElement
 
 
 class ShadowRoot:
@@ -43,7 +46,9 @@ def __repr__(self) -> str:
     def id(self) -> str:
         return self._id
 
-    def find_element(self, by: str = By.ID, value: str = None):
+    def find_element(
+        self, by: Union[ByType, RelativeBy] = By.ID, value: Optional[str] = None,
+    ) -> WebElement:
         """Find an element inside a shadow root given a By strategy and
         locator.
 
@@ -82,7 +87,9 @@ def find_element(self, by: str = By.ID, value: str = None):
 
         return self._execute(Command.FIND_ELEMENT_FROM_SHADOW_ROOT, {"using": by, "value": value})["value"]
 
-    def find_elements(self, by: str = By.ID, value: str = None):
+    def find_elements(
+        self, by: Union[ByType, RelativeBy] = By.ID, value: Optional[str] = None,
+    ) -> List[WebElement]:
         """Find elements inside a shadow root given a By strategy and locator.
 
         Parameters:

py/selenium/webdriver/remote/webdriver.py

@@ -45,7 +45,7 @@
 from selenium.webdriver.common.bidi.script import Script
 from selenium.webdriver.common.bidi.session import Session
 from selenium.webdriver.common.bidi.storage import Storage
-from selenium.webdriver.common.by import By
+from selenium.webdriver.common.by import By, ByType
 from selenium.webdriver.common.options import ArgOptions, BaseOptions
 from selenium.webdriver.common.print_page_options import PrintOptions
 from selenium.webdriver.common.timeouts import Timeouts
@@ -875,7 +875,7 @@ def timeouts(self, timeouts) -> None:
         """
         _ = self.execute(Command.SET_TIMEOUTS, timeouts._to_json())["value"]
 
-    def find_element(self, by=By.ID, value: Optional[str] = None) -> WebElement:
+    def find_element(self, by: Union[ByType, RelativeBy] = By.ID, value: Optional[str] = None) -> WebElement:
         """Find an element given a By strategy and locator.
 
         Parameters:
@@ -911,7 +911,7 @@ def find_element(self, by=By.ID, value: Optional[str] = None) -> WebElement:
 
         return self.execute(Command.FIND_ELEMENT, {"using": by, "value": value})["value"]
 
-    def find_elements(self, by=By.ID, value: Optional[str] = None) -> List[WebElement]:
+    def find_elements(self, by: Union[ByType, RelativeBy] = By.ID, value: Optional[str] = None) -> List[WebElement]:
         """Find elements given a By strategy and locator.
 
         Parameters:

py/selenium/webdriver/support/event_firing_webdriver.py

@@ -15,14 +15,16 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Any, List, Tuple
+from typing import Any, List, Optional, Tuple, Union
 
 from selenium.common.exceptions import WebDriverException
 from selenium.webdriver.common.by import By
+from selenium.webdriver.common.by import ByType
 from selenium.webdriver.remote.webdriver import WebDriver
 from selenium.webdriver.remote.webelement import WebElement
 
 from .abstract_event_listener import AbstractEventListener
+from .relative_locator import RelativeBy
 
 
 def _wrap_elements(result, ef_driver):
@@ -187,10 +189,10 @@ def clear(self) -> None:
     def send_keys(self, *value) -> None:
         self._dispatch("change_value_of", (self._webelement, self._driver), "send_keys", value)
 
-    def find_element(self, by=By.ID, value=None) -> WebElement:
+    def find_element(self, by: Union[ByType, RelativeBy] = By.ID, value: Optional[str] = None) -> WebElement:
         return self._dispatch("find", (by, value, self._driver), "find_element", (by, value))
 
-    def find_elements(self, by=By.ID, value=None) -> List[WebElement]:
+    def find_elements(self, by: Union[ByType, RelativeBy] = By.ID, value: Optional[str] = None) -> List[WebElement]:
         return self._dispatch("find", (by, value, self._driver), "find_elements", (by, value))
 
     def _dispatch(self, l_call, l_args, d_call, d_args):

py/selenium/webdriver/support/expected_conditions.py

@@ -27,7 +27,9 @@
     WebDriverException,
 )
 from selenium.webdriver.common.alert import Alert
+from selenium.webdriver.common.by import ByType
 from selenium.webdriver.remote.webdriver import WebDriver, WebElement
+from selenium.webdriver.support.relative_locator import RelativeBy
 
 """
  * Canned "Expected Conditions" which are generally useful within webdriver
@@ -38,6 +40,7 @@
 T = TypeVar("T")
 
 WebDriverOrWebElement = Union[WebDriver, WebElement]
+LocatorType = Union[Tuple[ByType, str], Tuple[RelativeBy, None]]
 
 
 def title_is(title: str) -> Callable[[WebDriver], bool]:
@@ -79,7 +82,7 @@ def _predicate(driver: WebDriver):
     return _predicate
 
 
-def presence_of_element_located(locator: Tuple[str, str]) -> Callable[[WebDriverOrWebElement], WebElement]:
+def presence_of_element_located(locator: LocatorType) -> 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.
 
@@ -189,7 +192,7 @@ def _predicate(driver: WebDriver):
 
 
 def visibility_of_element_located(
-    locator: Tuple[str, str],
+    locator: LocatorType,
 ) -> 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
@@ -272,7 +275,7 @@ def _element_if_visible(element: WebElement, visibility: bool = True) -> Union[L
     return element if element.is_displayed() == visibility else False
 
 
-def presence_of_all_elements_located(locator: Tuple[str, str]) -> Callable[[WebDriverOrWebElement], List[WebElement]]:
+def presence_of_all_elements_located(locator: LocatorType) -> Callable[[WebDriverOrWebElement], List[WebElement]]:
     """An expectation for checking that there is at least one element present
     on a web page.
 
@@ -299,7 +302,7 @@ def _predicate(driver: WebDriverOrWebElement):
     return _predicate
 
 
-def visibility_of_any_elements_located(locator: Tuple[str, str]) -> Callable[[WebDriverOrWebElement], List[WebElement]]:
+def visibility_of_any_elements_located(locator: LocatorType) -> Callable[[WebDriverOrWebElement], List[WebElement]]:
     """An expectation for checking that there is at least one element visible
     on a web page.
 
@@ -327,7 +330,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def visibility_of_all_elements_located(
-    locator: Tuple[str, str],
+    locator: LocatorType,
 ) -> 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
@@ -363,7 +366,7 @@ def _predicate(driver: WebDriverOrWebElement):
     return _predicate
 
 
-def text_to_be_present_in_element(locator: Tuple[str, str], text_: str) -> Callable[[WebDriverOrWebElement], bool]:
+def text_to_be_present_in_element(locator: LocatorType, text_: str) -> Callable[[WebDriverOrWebElement], bool]:
     """An expectation for checking if the given text is present in the
     specified element.
 
@@ -399,7 +402,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def text_to_be_present_in_element_value(
-    locator: Tuple[str, str], text_: str
+    locator: LocatorType, text_: str
 ) -> Callable[[WebDriverOrWebElement], bool]:
     """An expectation for checking if the given text is present in the
     element's value.
@@ -436,7 +439,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def text_to_be_present_in_element_attribute(
-    locator: Tuple[str, str], attribute_: str, text_: str
+    locator: LocatorType, attribute_: str, text_: str
 ) -> Callable[[WebDriverOrWebElement], bool]:
     """An expectation for checking if the given text is present in the
     element's attribute.
@@ -477,7 +480,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def frame_to_be_available_and_switch_to_it(
-    locator: Union[Tuple[str, str], str, WebElement],
+    locator: Union[LocatorType, str, WebElement],
 ) -> Callable[[WebDriver], bool]:
     """An expectation for checking whether the given frame is available to
     switch to.
@@ -517,7 +520,7 @@ def _predicate(driver: WebDriver):
 
 
 def invisibility_of_element_located(
-    locator: Union[WebElement, Tuple[str, str]],
+    locator: Union[WebElement, LocatorType],
 ) -> Callable[[WebDriverOrWebElement], Union[WebElement, bool]]:
     """An Expectation for checking that an element is either invisible or not
     present on the DOM.
@@ -565,7 +568,7 @@ def _predicate(driver: WebDriverOrWebElement):
 
 
 def invisibility_of_element(
-    element: Union[WebElement, Tuple[str, str]],
+    element: Union[WebElement, LocatorType],
 ) -> Callable[[WebDriverOrWebElement], Union[WebElement, bool]]:
     """An Expectation for checking that an element is either invisible or not
     present on the DOM.
@@ -592,7 +595,7 @@ def invisibility_of_element(
 
 
 def element_to_be_clickable(
-    mark: Union[WebElement, Tuple[str, str]],
+    mark: Union[WebElement, LocatorType],
 ) -> Callable[[WebDriverOrWebElement], Union[Literal[False], WebElement]]:
     """An Expectation for checking an element is visible and enabled such that
     you can click it.
@@ -687,7 +690,7 @@ def _predicate(_):
     return _predicate
 
 
-def element_located_to_be_selected(locator: Tuple[str, str]) -> Callable[[WebDriverOrWebElement], bool]:
+def element_located_to_be_selected(locator: LocatorType) -> Callable[[WebDriverOrWebElement], bool]:
     """An expectation for the element to be located is selected.
 
     Parameters:
@@ -743,7 +746,7 @@ def _predicate(_):
 
 
 def element_located_selection_state_to_be(
-    locator: Tuple[str, str], is_selected: bool
+    locator: LocatorType, is_selected: bool
 ) -> Callable[[WebDriverOrWebElement], bool]:
     """An expectation to locate an element and check if the selection state
     specified is in that state.
@@ -858,7 +861,7 @@ def _predicate(driver: WebDriver):
     return _predicate
 
 
-def element_attribute_to_include(locator: Tuple[str, str], attribute_: str) -> Callable[[WebDriverOrWebElement], bool]:
+def element_attribute_to_include(locator: LocatorType, attribute_: str) -> Callable[[WebDriverOrWebElement], bool]:
     """An expectation for checking if the given attribute is included in the
     specified element.