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

T `module-attribute`

T = TypeVar('T')

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=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.

query `async`

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.

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.

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:

# 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.