Skip to content

Added more detailed docstrings to find_element() #14930

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Dec 27, 2024
Merged

Added more detailed docstrings to find_element() #14930

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
834b1f0
Added more detailed docstrings to find_element()
shbenzer Dec 23, 2024
12490d8
Merge branch 'trunk' into docstrings-py
diemol Dec 27, 2024
6abfce2
formatting
shbenzer Dec 27, 2024
6bf2081
undo commenting
shbenzer Dec 27, 2024
3295ea1
Merge branch 'trunk' into docstrings-py
shbenzer Dec 27, 2024
6d74a51
Merge branch 'trunk' into docstrings-py
diemol Dec 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions py/selenium/webdriver/remote/shadowroot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,31 @@ def __repr__(self) -> str:
)

def find_element(self, by: str = By.ID, value: str = None):
"""Find an element inside a shadow root given a By strategy and locator.

Parameters:
----------
by : selenium.webdriver.common.by.By
The locating strategy to use. Default is `By.ID`. Supported values include:
- By.ID: Locate by element ID.
- By.NAME: Locate by the `name` attribute.
- By.XPATH: Locate by an XPath expression.
- By.CSS_SELECTOR: Locate by a CSS selector.
- By.CLASS_NAME: Locate by the `class` attribute.
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
- By.LINK_TEXT: Locate a link element by its exact text.
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
- RelativeBy: Locate elements relative to a specified root element.

Example:
--------
element = driver.find_element(By.ID, 'foo')

Returns:
-------
WebElement
The first matching `WebElement` found on the page.
"""
if by == By.ID:
by = By.CSS_SELECTOR
value = f'[id="{value}"]'
Expand All @@ -53,6 +78,31 @@ 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):
"""Find elements inside a shadow root given a By strategy and locator.

Parameters:
----------
by : selenium.webdriver.common.by.By
The locating strategy to use. Default is `By.ID`. Supported values include:
- By.ID: Locate by element ID.
- By.NAME: Locate by the `name` attribute.
- By.XPATH: Locate by an XPath expression.
- By.CSS_SELECTOR: Locate by a CSS selector.
- By.CLASS_NAME: Locate by the `class` attribute.
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
- By.LINK_TEXT: Locate a link element by its exact text.
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
- RelativeBy: Locate elements relative to a specified root element.

Example:
--------
element = driver.find_element(By.ID, 'foo')

Returns:
-------
WebElement
list of `WebElements` matching locator strategy found on the page.
"""
if by == By.ID:
by = By.CSS_SELECTOR
value = f'[id="{value}"]'
Expand Down
52 changes: 42 additions & 10 deletions py/selenium/webdriver/remote/webdriver.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -772,12 +772,28 @@ def timeouts(self, timeouts) -> None:
def find_element(self, by=By.ID, value: Optional[str] = None) -> WebElement:
"""Find an element given a By strategy and locator.

:Usage:
::
Parameters:
----------
by : selenium.webdriver.common.by.By
The locating strategy to use. Default is `By.ID`. Supported values include:
- By.ID: Locate by element ID.
- By.NAME: Locate by the `name` attribute.
- By.XPATH: Locate by an XPath expression.
- By.CSS_SELECTOR: Locate by a CSS selector.
- By.CLASS_NAME: Locate by the `class` attribute.
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
- By.LINK_TEXT: Locate a link element by its exact text.
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
- RelativeBy: Locate elements relative to a specified root element.

Example:
--------
element = driver.find_element(By.ID, 'foo')

element = driver.find_element(By.ID, 'foo')

:rtype: WebElement
Returns:
-------
WebElement
The first matching `WebElement` found on the page.
"""
by, value = self.locator_converter.convert(by, value)

Expand All @@ -792,12 +808,28 @@ def find_element(self, by=By.ID, value: Optional[str] = None) -> WebElement:
def find_elements(self, by=By.ID, value: Optional[str] = None) -> List[WebElement]:
"""Find elements given a By strategy and locator.

:Usage:
::
Parameters:
----------
by : selenium.webdriver.common.by.By
The locating strategy to use. Default is `By.ID`. Supported values include:
- By.ID: Locate by element ID.
- By.NAME: Locate by the `name` attribute.
- By.XPATH: Locate by an XPath expression.
- By.CSS_SELECTOR: Locate by a CSS selector.
- By.CLASS_NAME: Locate by the `class` attribute.
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
- By.LINK_TEXT: Locate a link element by its exact text.
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
- RelativeBy: Locate elements relative to a specified root element.

Example:
--------
element = driver.find_element(By.ID, 'foo')

elements = driver.find_elements(By.CLASS_NAME, 'foo')

:rtype: list of WebElement
Returns:
-------
WebElement
list of `WebElements` matching locator strategy found on the page.
"""
by, value = self.locator_converter.convert(by, value)

Expand Down
52 changes: 42 additions & 10 deletions py/selenium/webdriver/remote/webelement.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,25 +397,57 @@ def _execute(self, command, params=None):
def find_element(self, by=By.ID, value=None) -> WebElement:
"""Find an element given a By strategy and locator.

:Usage:
::
Parameters:
----------
by : selenium.webdriver.common.by.By
The locating strategy to use. Default is `By.ID`. Supported values include:
- By.ID: Locate by element ID.
- By.NAME: Locate by the `name` attribute.
- By.XPATH: Locate by an XPath expression.
- By.CSS_SELECTOR: Locate by a CSS selector.
- By.CLASS_NAME: Locate by the `class` attribute.
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
- By.LINK_TEXT: Locate a link element by its exact text.
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
- RelativeBy: Locate elements relative to a specified root element.

Example:
--------
element = driver.find_element(By.ID, 'foo')

element = element.find_element(By.ID, 'foo')

:rtype: WebElement
Returns:
-------
WebElement
The first matching `WebElement` found on the page.
"""
by, value = self._parent.locator_converter.convert(by, value)
return self._execute(Command.FIND_CHILD_ELEMENT, {"using": by, "value": value})["value"]

def find_elements(self, by=By.ID, value=None) -> List[WebElement]:
"""Find elements given a By strategy and locator.

:Usage:
::
Parameters:
----------
by : selenium.webdriver.common.by.By
The locating strategy to use. Default is `By.ID`. Supported values include:
- By.ID: Locate by element ID.
- By.NAME: Locate by the `name` attribute.
- By.XPATH: Locate by an XPath expression.
- By.CSS_SELECTOR: Locate by a CSS selector.
- By.CLASS_NAME: Locate by the `class` attribute.
- By.TAG_NAME: Locate by the tag name (e.g., "input", "button").
- By.LINK_TEXT: Locate a link element by its exact text.
- By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
- RelativeBy: Locate elements relative to a specified root element.

Example:
--------
element = driver.find_element(By.ID, 'foo')

element = element.find_elements(By.CLASS_NAME, 'foo')

:rtype: list of WebElement
Returns:
-------
WebElement
list of `WebElements` matching locator strategy found on the page.
"""
by, value = self._parent.locator_converter.convert(by, value)
return self._execute(Command.FIND_CHILD_ELEMENTS, {"using": by, "value": value})["value"]
Expand Down
Loading