Mixins de Elementos

O módulo de mixins (mixins) fornece funcionalidade reutilizável que pode ser misturada em classes de elementos para estender suas capacidades.

Mixin Find Elements

O FindElementsMixin fornece capacidades de localização de elementos para as classes que o incluem.

pydoll.elements.mixins.find_elements_mixin

logger `module-attribute`

logger = 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: 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[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: 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: 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.

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.

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.

Uso

Mixins são tipicamente usados internamente pela biblioteca para compor funcionalidades. O FindElementsMixin é usado por classes como Tab e WebElement para fornecer métodos de localização de elementos:

# Estes métodos vêm do FindElementsMixin
element = await tab.find(id="username")
elements = await tab.find(class_name="item", find_all=True)
element = await tab.query("#submit-button")

Métodos Disponíveis

O FindElementsMixin fornece vários métodos para encontrar elementos:

find() - Localização de elementos moderna com argumentos nomeados (keyword arguments)
query() - Consultas de seletor CSS e XPath
find_element() - Método de localização de elemento legado
find_elements() - Método legado para encontrar múltiplos elementos

Moderno vs. Legado

O método find() é a abordagem moderna e recomendada para encontrar elementos. Os métodos find_element() e find_elements() são mantidos para compatibilidade com versões anteriores.