ShadowRoot

pydoll.elements.shadow_root.ShadowRoot

ShadowRoot(object_id, connection_handler, mode=OPEN, host_element=None)

Bases: FindElementsMixin

Shadow root wrapper for shadow DOM traversal.

Provides element finding capabilities within shadow DOM boundaries using query() with CSS selectors. Use query() instead of find() — find() and XPath are not supported inside shadow roots.

Usage

shadow_host = await tab.find(id='my-component') shadow_root = await shadow_host.get_shadow_root() button = await shadow_root.query('#internal-button') await button.click()

Initialize shadow root wrapper.

PARAMETER	DESCRIPTION
object_id	CDP object ID for the shadow root node. TYPE: str
connection_handler	Browser connection for CDP commands. TYPE: ConnectionHandler
mode	Shadow root mode (open, closed, or user-agent). TYPE: ShadowRootType DEFAULT: OPEN
host_element	Reference to the shadow host element. TYPE: WebElement | None DEFAULT: None

mode property

mode

Shadow root mode (open, closed, or user-agent).

host_element property

host_element

Reference to the shadow host element, if available.

inner_html async property

inner_html

HTML content of the shadow root.

find async

find(id: Optional[str] = ..., class_name: Optional[str] = ..., name: Optional[str] = ..., tag_name: Optional[str] = ..., text: Optional[str] = ..., timeout: int = ..., find_all: Literal[False] = False, raise_exc: Literal[True] = True, **attributes) -> WebElement

find(id: Optional[str] = ..., class_name: Optional[str] = ..., name: Optional[str] = ..., tag_name: Optional[str] = ..., text: Optional[str] = ..., timeout: int = ..., find_all: Literal[False] = False, raise_exc: Literal[False] = False, **attributes) -> Optional[WebElement]

find(id: Optional[str] = ..., class_name: Optional[str] = ..., name: Optional[str] = ..., tag_name: Optional[str] = ..., text: Optional[str] = ..., timeout: int = ..., find_all: Literal[True] = True, raise_exc: Literal[True] = True, **attributes) -> list[WebElement]

find(id: Optional[str] = ..., class_name: Optional[str] = ..., name: Optional[str] = ..., tag_name: Optional[str] = ..., text: Optional[str] = ..., timeout: int = ..., find_all: Literal[True] = True, raise_exc: Literal[False] = False, **attributes) -> Optional[list[WebElement]]

find(id: Optional[str] = ..., class_name: Optional[str] = ..., name: Optional[str] = ..., tag_name: Optional[str] = ..., text: Optional[str] = ..., timeout: int = ..., find_all: bool = ..., raise_exc: bool = ..., **attributes) -> Union[WebElement, list[WebElement], None]

find(id=None, class_name=None, name=None, tag_name=None, text=None, timeout=0, find_all=False, raise_exc=True, **attributes)

Find element(s) using combination of common HTML attributes.

Flexible element location using standard attributes. Multiple attributes can be combined for specific selectors (builds XPath when multiple specified).

PARAMETER	DESCRIPTION
id	Element ID attribute value. TYPE: Optional[str] DEFAULT: None
class_name	CSS class name to match. TYPE: Optional[str] DEFAULT: None
name	Element name attribute value. TYPE: Optional[str] DEFAULT: None
tag_name	HTML tag name (e.g., "div", "input"). TYPE: Optional[str] DEFAULT: None
text	Text content to match within element. TYPE: Optional[str] DEFAULT: None
timeout	Maximum seconds to wait for elements to appear. TYPE: int DEFAULT: 0
find_all	If True, returns all matches; if False, first match only. TYPE: bool DEFAULT: False
raise_exc	Whether to raise exception if no elements found. TYPE: bool DEFAULT: True
**attributes	Additional HTML attributes to match. TYPE: dict[str, str] DEFAULT: {}

RETURNS	DESCRIPTION
Union[WebElement, list[WebElement], None]	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ValueError	If no search criteria provided.
ElementNotFound	If no elements found and raise_exc=True.
WaitElementTimeout	If timeout specified and no elements appear in time.
NotImplementedError	If called on a ShadowRoot (use query() with CSS instead).

query async

query(expression: str, timeout: int = ..., find_all: Literal[False] = False, raise_exc: Literal[True] = True) -> WebElement

query(expression: str, timeout: int = ..., find_all: Literal[False] = False, raise_exc: Literal[False] = False) -> Optional[WebElement]

query(expression: str, timeout: int = ..., find_all: Literal[True] = True, raise_exc: Literal[True] = True) -> list[WebElement]

query(expression: str, timeout: int = ..., find_all: Literal[True] = True, raise_exc: Literal[False] = False) -> Optional[list[WebElement]]

query(expression: str, timeout: int = ..., find_all: bool = ..., raise_exc: bool = ...) -> Union[WebElement, list[WebElement], None]

query(expression, timeout=0, find_all=False, raise_exc=True)

Find element(s) using raw CSS selector or XPath expression.

Direct access using CSS or XPath syntax. Selector type automatically determined based on expression pattern.

PARAMETER	DESCRIPTION
expression	Selector expression (CSS, XPath, ID with #, class with .). TYPE: str
timeout	Maximum seconds to wait for elements to appear. TYPE: int DEFAULT: 0
find_all	If True, returns all matches; if False, first match only. TYPE: bool DEFAULT: False
raise_exc	Whether to raise exception if no elements found. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Union[WebElement, list[WebElement], None]	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ElementNotFound	If no elements found and raise_exc=True.
WaitElementTimeout	If timeout specified and no elements appear in time.
NotImplementedError	If called with XPath on a ShadowRoot.

find_or_wait_element async

find_or_wait_element(by, value, timeout=0, find_all=False, raise_exc=True)

Core element finding method with optional waiting capability.

Searches for elements with flexible waiting. If timeout specified, repeatedly attempts to find elements with 0.5s delays until success or timeout. Used by higher-level find() and query() methods.

PARAMETER	DESCRIPTION
by	Selector strategy (CSS_SELECTOR, XPATH, ID, etc.). TYPE: By
value	Selector value to locate element(s). TYPE: str
timeout	Maximum seconds to wait (0 = no waiting). TYPE: int DEFAULT: 0
find_all	If True, returns all matches; if False, first match only. TYPE: bool DEFAULT: False
raise_exc	Whether to raise exception if no elements found. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Union[WebElement, list[WebElement], None]	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ElementNotFound	If no elements found with timeout=0 and raise_exc=True.
WaitElementTimeout	If elements not found within timeout and raise_exc=True.