网页元素

pydoll.elements.web_element.WebElement

WebElement(object_id, connection_handler, method=None, selector=None, attributes_list=[])

Bases: FindElementsMixin

DOM element wrapper for browser automation.

Provides comprehensive functionality for element interaction, inspection, and manipulation using Chrome DevTools Protocol commands.

Initialize WebElement wrapper.

PARAMETER	DESCRIPTION
object_id	Unique CDP object identifier for this DOM element. TYPE: str
connection_handler	Connection instance for browser communication. TYPE: ConnectionHandler
method	Search method used to find this element (for debugging). TYPE: Optional[str] DEFAULT: None
selector	Selector string used to find this element (for debugging). TYPE: Optional[str] DEFAULT: None
attributes_list	Flat list of alternating attribute names and values. TYPE: list[str] DEFAULT: []

value property

value

Element's value attribute (for form elements).

class_name property

class_name

Element's CSS class name(s).

id property

id

Element's ID attribute.

tag_name property

tag_name

Element's HTML tag name.

is_enabled property

is_enabled

Whether element is enabled (not disabled).

text async property

text

Visible text content of the element.

bounds async property

bounds

Element's bounding box coordinates.

Returns coordinates in CSS pixels relative to document origin.

inner_html async property

inner_html

Element's HTML content (actually returns outerHTML).

get_bounds_using_js async

get_bounds_using_js()

Get element bounds using JavaScript getBoundingClientRect().

Returns coordinates relative to viewport (alternative to bounds property).

get_parent_element async

get_parent_element()

Element's parent element.

get_children_elements async

get_children_elements(max_depth=1, tag_filter=[], raise_exc=False)

Retrieve all direct and nested child elements of this element.

PARAMETER	DESCRIPTION
max_depth	Maximum depth to traverse when finding children. Defaults to 1 for direct children only. TYPE: int DEFAULT: 1
tag_filter	List of HTML tag names to filter results. If empty, returns all child elements regardless of tag. Defaults to []. TYPE: list[str] DEFAULT: []

RETURNS	DESCRIPTION
list[WebElement]	list[WebElement]: List of child WebElement objects found within the specified depth and matching the tag filter criteria.

RAISES	DESCRIPTION
ElementNotFound	If no child elements are found for this element and raise_exc is True.

get_siblings_elements async

get_siblings_elements(tag_filter=[], raise_exc=False)

Retrieve all sibling elements of this element (elements at the same DOM level).

PARAMETER	DESCRIPTION
tag_filter	List of HTML tag names to filter results. If empty, returns all sibling elements regardless of tag. Defaults to []. TYPE: list[str] DEFAULT: []

RETURNS	DESCRIPTION
list[WebElement]	list[WebElement]: List of sibling WebElement objects that share the same parent as this element and match the tag filter criteria.

RAISES	DESCRIPTION
ElementNotFound	If no sibling elements are found for this element

take_screenshot async

take_screenshot(path, quality=100)

Capture screenshot of this element only.

Automatically scrolls element into view before capturing.

get_attribute

get_attribute(name)

Get element attribute value.

Note

Only provides attributes available when element was located. For dynamic attributes, consider using JavaScript execution.

scroll_into_view async

scroll_into_view()

Scroll element into visible viewport.

wait_until async

wait_until(*, is_visible=False, is_interactable=False, timeout=0)

Wait for element to meet specified conditions.

RAISES	DESCRIPTION
ValueError	If neither is_visible nor is_interactable is True.
WaitElementTimeout	If the condition is not met within timeout.

click_using_js async

click_using_js()

Click element using JavaScript click() method.

RAISES	DESCRIPTION
ElementNotVisible	If element is not visible.
ElementNotInteractable	If element couldn't be clicked.

Note

For elements, uses specialized selection approach. Element is automatically scrolled into view.

click async

click(x_offset=0, y_offset=0, hold_time=0.1)

Click element using simulated mouse events.

PARAMETER	DESCRIPTION
x_offset	Horizontal offset from element center. TYPE: int DEFAULT: 0
y_offset	Vertical offset from element center. TYPE: int DEFAULT: 0
hold_time	Duration to hold mouse button down. TYPE: float DEFAULT: 0.1

RAISES	DESCRIPTION
ElementNotVisible	If element is not visible.

Note

For elements, delegates to specialized JavaScript approach. Element is automatically scrolled into view.

insert_text async

insert_text(text)

Insert text in single operation (faster but less realistic than typing).

Note

Element should already be focused for text to be inserted correctly.

set_input_files async

set_input_files(files)

Set file paths for file input element.

PARAMETER	DESCRIPTION
files	list of absolute file paths to existing files. TYPE: list[str]

RAISES	DESCRIPTION
ElementNotAFileInput	If element is not a file input.

type_text async

type_text(text, interval=0.1)

Type text character by character with realistic timing.

More realistic than insert_text() but slower.

key_down async

key_down(key, modifiers=None)

Send key down event.

Note

Only sends key down without release. Pair with key_up() for complete keypress.

key_up async

key_up(key)

Send key up event (should follow corresponding key_down()).

press_keyboard_key async

press_keyboard_key(key, modifiers=None, interval=0.1)

Press and release keyboard key with configurable timing.

Better for special keys (Enter, Tab, etc.) than type_text().

is_visible async

is_visible()

Check if element is visible using comprehensive JavaScript visibility test.

is_on_top async

is_on_top()

Check if element is topmost at its center point (not covered by overlays).

is_interactable async

is_interactable()

Check if element is interactable based on visibility and position.

execute_script async

execute_script(script, return_by_value=False)

Execute JavaScript in element context.

Element is available as 'this' within the script.

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: dict[str, str]) -> 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: dict[str, str]) -> 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: dict[str, str]) -> 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: dict[str, str]) -> 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: dict[str, str]) -> 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.