Element Mixins

The mixins module provides reusable functionality that can be mixed into element classes to extend their capabilities.

Find Elements Mixin

The FindElementsMixin provides element finding capabilities to classes that include it.

pydoll.elements.mixins.find_elements_mixin

logger `module-attribute`

logger = logging.getLogger(__name__)

FindElementsMixin

Mixin providing comprehensive element finding and waiting capabilities.

Implements DOM element location using various selector strategies (CSS, XPath, etc.) with support for single/multiple element finding and configurable waiting. Classes using this mixin gain powerful element discovery without implementing complex location logic themselves.

find `async`

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

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

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

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

find(id: str | None = ..., class_name: str | None = ..., name: str | None = ..., tag_name: str | None = ..., text: str | None = ..., timeout: int = ..., find_all: bool = ..., raise_exc: bool = ..., **attributes) -> 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: `str \| None` DEFAULT: `None`
`class_name`	CSS class name to match. TYPE: `str \| None` DEFAULT: `None`
`name`	Element name attribute value. TYPE: `str \| None` DEFAULT: `None`
`tag_name`	HTML tag name (e.g., "div", "input"). TYPE: `str \| None` DEFAULT: `None`
`text`	Text content to match within element. TYPE: `str \| None` 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
`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) -> WebElement | None

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) -> list[WebElement] | None

query(expression: str, timeout: int = ..., find_all: bool = ..., raise_exc: bool = ...) -> 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
`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.

query_script `async`

query_script(function_declaration, arguments=None, execution_context_id=None)

Run a JavaScript function that returns elements and wrap them as WebElements.

The function runs with the search root bound to this (document on a Tab, the frame document on an iframe element, the element itself on a WebElement, the root on a ShadowRoot) in the same execution context and iframe routing that query() uses. It may return a single Element, a NodeList, an array of Elements, or null.

PARAMETER	DESCRIPTION
`function_declaration`	JavaScript function source, e.g. `function(tag) { return this.querySelectorAll(tag); }`. TYPE: `str`
`arguments`	CDP call arguments passed positionally to the function. TYPE: `list[CallArgument] \| None` DEFAULT: `None`
`execution_context_id`	Run in this execution context of the frame (for example an isolated world created with `Page.createIsolatedWorld`) with `this` bound to that context's `document`. Ignored when the root is a non-iframe element, whose object id already fixes the context. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[WebElement]`	WebElements for every element the function returned, in return order.

RAISES	DESCRIPTION
`ScriptException`	If the function throws or fails to compile.
`CommandFailed`	If the browser rejects the command itself.

execute_command `async`

execute_command(command, timeout=60)

Send a raw CDP command through this object's session.

The command is routed exactly like the object's own operations: a Tab sends it to the page session, a WebElement inside an out-of-process iframe sends it to that frame's session. Build commands with the factories in pydoll.commands or pass a plain {'method': ..., 'params': ...} dict for methods pydoll does not wrap.

PARAMETER	DESCRIPTION
`command`	CDP command to send. TYPE: `Command[T_CommandParams, T_CommandResponse]`
`timeout`	Seconds to wait for the browser's answer. TYPE: `int` DEFAULT: `60`

RETURNS	DESCRIPTION
`T_CommandResponse`	The browser's response, with the domain result under `'result'`.

RAISES	DESCRIPTION
`CommandFailed`	If the browser answers with an error.
`CommandExecutionTimeout`	If no answer arrives within `timeout`.

create_web_element

create_web_element(*args, **kwargs)

Create WebElement instance avoiding circular imports.

Factory method that dynamically imports WebElement at runtime to prevent circular import dependencies.

Usage

Mixins are typically used internally by the library to compose functionality. The FindElementsMixin is used by classes like Tab and WebElement to provide element finding methods:

SyncAsync

# These methods come from FindElementsMixin
element = tab.find(id="username")
elements = tab.find(class_name="item", find_all=True)
element = tab.query("#submit-button")

# These methods come from FindElementsMixin
element = await tab.find(id="username")
elements = await tab.find(class_name="item", find_all=True)
element = await tab.query("#submit-button")

Available Methods

The FindElementsMixin provides several methods for finding elements:

find() - Modern element finding with keyword arguments
query() - CSS selector and XPath queries
find_element() - Legacy element finding method
find_elements() - Legacy method for finding multiple elements

Modern vs Legacy

The find() method is the modern, recommended approach for finding elements. The find_element() and find_elements() methods are maintained for backward compatibility.