Skip to content

Commit 5508e80

Browse files
shbenzerdiemol
shbenzer
and
diemol
authored
Added more detailed docstrings to find_element() (#14930)
* Added more detailed docstrings to find_element() * formatting * undo commenting --------- Co-authored-by: Diego Molina <[email protected]>
1 parent 85781b3 commit 5508e80

File tree

3 files changed

+135
-20
lines changed

3 files changed

+135
-20
lines changed

‎py/selenium/webdriver/remote/shadowroot.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,32 @@ def __repr__(self) -> str:
4040
)
4141

4242
def find_element(self, by: str = By.ID, value: str = None):
43+
"""Find an element inside a shadow root given a By strategy and
44+
locator.
45+
46+
Parameters:
47+
----------
48+
by : selenium.webdriver.common.by.By
49+
The locating strategy to use. Default is `By.ID`. Supported values include:
50+
- By.ID: Locate by element ID.
51+
- By.NAME: Locate by the `name` attribute.
52+
- By.XPATH: Locate by an XPath expression.
53+
- By.CSS_SELECTOR: Locate by a CSS selector.
54+
- By.CLASS_NAME: Locate by the `class` attribute.
55+
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
56+
- By.LINK_TEXT: Locate a link element by its exact text.
57+
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
58+
- RelativeBy: Locate elements relative to a specified root element.
59+
60+
Example:
61+
--------
62+
element = driver.find_element(By.ID, 'foo')
63+
64+
Returns:
65+
-------
66+
WebElement
67+
The first matching `WebElement` found on the page.
68+
"""
4369
if by == By.ID:
4470
by = By.CSS_SELECTOR
4571
value = f'[id="{value}"]'
@@ -53,6 +79,31 @@ def find_element(self, by: str = By.ID, value: str = None):
5379
return self._execute(Command.FIND_ELEMENT_FROM_SHADOW_ROOT, {"using": by, "value": value})["value"]
5480

5581
def find_elements(self, by: str = By.ID, value: str = None):
82+
"""Find elements inside a shadow root given a By strategy and locator.
83+
84+
Parameters:
85+
----------
86+
by : selenium.webdriver.common.by.By
87+
The locating strategy to use. Default is `By.ID`. Supported values include:
88+
- By.ID: Locate by element ID.
89+
- By.NAME: Locate by the `name` attribute.
90+
- By.XPATH: Locate by an XPath expression.
91+
- By.CSS_SELECTOR: Locate by a CSS selector.
92+
- By.CLASS_NAME: Locate by the `class` attribute.
93+
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
94+
- By.LINK_TEXT: Locate a link element by its exact text.
95+
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
96+
- RelativeBy: Locate elements relative to a specified root element.
97+
98+
Example:
99+
--------
100+
element = driver.find_element(By.ID, 'foo')
101+
102+
Returns:
103+
-------
104+
WebElement
105+
list of `WebElements` matching locator strategy found on the page.
106+
"""
56107
if by == By.ID:
57108
by = By.CSS_SELECTOR
58109
value = f'[id="{value}"]'

‎py/selenium/webdriver/remote/webdriver.py‎

Lines changed: 42 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -772,12 +772,28 @@ def timeouts(self, timeouts) -> None:
772772
def find_element(self, by=By.ID, value: Optional[str] = None) -> WebElement:
773773
"""Find an element given a By strategy and locator.
774774
775-
:Usage:
776-
::
775+
Parameters:
776+
----------
777+
by : selenium.webdriver.common.by.By
778+
The locating strategy to use. Default is `By.ID`. Supported values include:
779+
- By.ID: Locate by element ID.
780+
- By.NAME: Locate by the `name` attribute.
781+
- By.XPATH: Locate by an XPath expression.
782+
- By.CSS_SELECTOR: Locate by a CSS selector.
783+
- By.CLASS_NAME: Locate by the `class` attribute.
784+
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
785+
- By.LINK_TEXT: Locate a link element by its exact text.
786+
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
787+
- RelativeBy: Locate elements relative to a specified root element.
788+
789+
Example:
790+
--------
791+
element = driver.find_element(By.ID, 'foo')
777792
778-
element = driver.find_element(By.ID, 'foo')
779-
780-
:rtype: WebElement
793+
Returns:
794+
-------
795+
WebElement
796+
The first matching `WebElement` found on the page.
781797
"""
782798
by, value = self.locator_converter.convert(by, value)
783799

@@ -792,12 +808,28 @@ def find_element(self, by=By.ID, value: Optional[str] = None) -> WebElement:
792808
def find_elements(self, by=By.ID, value: Optional[str] = None) -> List[WebElement]:
793809
"""Find elements given a By strategy and locator.
794810
795-
:Usage:
796-
::
811+
Parameters:
812+
----------
813+
by : selenium.webdriver.common.by.By
814+
The locating strategy to use. Default is `By.ID`. Supported values include:
815+
- By.ID: Locate by element ID.
816+
- By.NAME: Locate by the `name` attribute.
817+
- By.XPATH: Locate by an XPath expression.
818+
- By.CSS_SELECTOR: Locate by a CSS selector.
819+
- By.CLASS_NAME: Locate by the `class` attribute.
820+
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
821+
- By.LINK_TEXT: Locate a link element by its exact text.
822+
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
823+
- RelativeBy: Locate elements relative to a specified root element.
824+
825+
Example:
826+
--------
827+
element = driver.find_element(By.ID, 'foo')
797828
798-
elements = driver.find_elements(By.CLASS_NAME, 'foo')
799-
800-
:rtype: list of WebElement
829+
Returns:
830+
-------
831+
WebElement
832+
list of `WebElements` matching locator strategy found on the page.
801833
"""
802834
by, value = self.locator_converter.convert(by, value)
803835

‎py/selenium/webdriver/remote/webelement.py‎

Lines changed: 42 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -397,25 +397,57 @@ def _execute(self, command, params=None):
397397
def find_element(self, by=By.ID, value=None) -> WebElement:
398398
"""Find an element given a By strategy and locator.
399399
400-
:Usage:
401-
::
400+
Parameters:
401+
----------
402+
by : selenium.webdriver.common.by.By
403+
The locating strategy to use. Default is `By.ID`. Supported values include:
404+
- By.ID: Locate by element ID.
405+
- By.NAME: Locate by the `name` attribute.
406+
- By.XPATH: Locate by an XPath expression.
407+
- By.CSS_SELECTOR: Locate by a CSS selector.
408+
- By.CLASS_NAME: Locate by the `class` attribute.
409+
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
410+
- By.LINK_TEXT: Locate a link element by its exact text.
411+
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
412+
- RelativeBy: Locate elements relative to a specified root element.
413+
414+
Example:
415+
--------
416+
element = driver.find_element(By.ID, 'foo')
402417
403-
element = element.find_element(By.ID, 'foo')
404-
405-
:rtype: WebElement
418+
Returns:
419+
-------
420+
WebElement
421+
The first matching `WebElement` found on the page.
406422
"""
407423
by, value = self._parent.locator_converter.convert(by, value)
408424
return self._execute(Command.FIND_CHILD_ELEMENT, {"using": by, "value": value})["value"]
409425

410426
def find_elements(self, by=By.ID, value=None) -> List[WebElement]:
411427
"""Find elements given a By strategy and locator.
412428
413-
:Usage:
414-
::
429+
Parameters:
430+
----------
431+
by : selenium.webdriver.common.by.By
432+
The locating strategy to use. Default is `By.ID`. Supported values include:
433+
- By.ID: Locate by element ID.
434+
- By.NAME: Locate by the `name` attribute.
435+
- By.XPATH: Locate by an XPath expression.
436+
- By.CSS_SELECTOR: Locate by a CSS selector.
437+
- By.CLASS_NAME: Locate by the `class` attribute.
438+
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
439+
- By.LINK_TEXT: Locate a link element by its exact text.
440+
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
441+
- RelativeBy: Locate elements relative to a specified root element.
442+
443+
Example:
444+
--------
445+
element = driver.find_element(By.ID, 'foo')
415446
416-
element = element.find_elements(By.CLASS_NAME, 'foo')
417-
418-
:rtype: list of WebElement
447+
Returns:
448+
-------
449+
WebElement
450+
list of `WebElements` matching locator strategy found on the page.
419451
"""
420452
by, value = self._parent.locator_converter.convert(by, value)
421453
return self._execute(Command.FIND_CHILD_ELEMENTS, {"using": by, "value": value})["value"]

0 commit comments

Comments
 (0)