pydoll-python 1.2.0__py3-none-any.whl

pydoll/element.py

@@ -0,0 +1,313 @@
+import asyncio
+import json
+
+import aiofiles
+from bs4 import BeautifulSoup
+
+from pydoll import exceptions
+from pydoll.commands.dom import DomCommands
+from pydoll.commands.input import InputCommands
+from pydoll.commands.page import PageCommands
+from pydoll.commands.runtime import RuntimeCommands
+from pydoll.connection.connection import ConnectionHandler
+from pydoll.constants import Scripts
+from pydoll.mixins.find_elements import FindElementsMixin
+from pydoll.utils import decode_image_to_bytes
+
+
+class WebElement(FindElementsMixin):
+    def __init__(
+        self,
+        object_id: str,
+        connection_handler: ConnectionHandler,
+        method: str = None,
+        selector: str = None,
+        attributes_list: list = [],
+    ):
+        """
+        Initializes the WebElement instance.
+
+        Args:
+            node (dict): The node description from the browser.
+            connection_handler (ConnectionHandler): The connection instance.
+        """
+        self._object_id = object_id
+        self._search_method = method
+        self._selector = selector
+        self._connection_handler = connection_handler
+        self._attributes = {}
+        self._def_attributes(attributes_list)
+
+    def __repr__(self):
+        attrs = ', '.join(f'{k}={v!r}' for k, v in self._attributes.items())
+        return (
+            f'{self.__class__.__name__}({attrs})(object_id={self._object_id})'
+        )
+
+    def _def_attributes(self, attributes_list: list):
+        for i in range(0, len(attributes_list), 2):
+            key = attributes_list[i]
+            key = key if key != 'class' else 'class_name'
+            value = attributes_list[i + 1]
+            self._attributes[key] = value
+
+    @property
+    def value(self) -> str:
+        """
+        Retrieves the value of the element.
+
+        Returns:
+            str: The value of the element.
+        """
+        return self._attributes.get('value')
+
+    @property
+    def class_name(self) -> str:
+        """
+        Retrieves the class name of the
+        element.
+
+        Returns:
+            str: The class name of the
+            element.
+
+        """
+        return self._attributes.get('class_name')
+
+    @property
+    def id(self) -> str:
+        """
+        Retrieves the id of the element.
+
+        Returns:
+            str: The id of the element.
+        """
+        return self._attributes.get('id')
+
+    @property
+    def is_enabled(self) -> bool:
+        """
+        Retrieves the enabled status of the element.
+
+        Returns:
+            bool: The enabled status of the element.
+        """
+        return bool('disabled' not in self._attributes.keys())
+
+    @property
+    async def bounds(self) -> list:
+        """
+        Asynchronously retrieves the bounding box of the element.
+
+        Returns:
+            dict: The bounding box of the element.
+        """
+        command = DomCommands.box_model(object_id=self._object_id)
+        response = await self._execute_command(command)
+        return response['result']['model']['content']
+
+    @property
+    async def inner_html(self) -> str:
+        """
+        Retrieves the inner HTML of the element.
+
+        Returns:
+            str: The inner HTML of the element.
+        """
+        command = DomCommands.get_outer_html(self._object_id)
+        response = await self._execute_command(command)
+        return response['result']['outerHTML']
+
+    async def get_bounds_using_js(self) -> list:
+        """
+        Retrieves the bounding box of the element using JavaScript.
+
+        Returns:
+            list: The bounding box of the element.
+        """
+        response = await self._execute_script(
+            Scripts.BOUNDS, return_by_value=True
+        )
+        return json.loads(response['result']['result']['value'])
+
+    async def _execute_script(
+        self, script: str, return_by_value: bool = False
+    ):
+        """
+        Executes a JavaScript script on the element.
+
+        Args:
+            script (str): The JavaScript script to execute.
+        """
+        return await self._execute_command(
+            RuntimeCommands.call_function_on(
+                self._object_id, script, return_by_value
+            )
+        )
+
+    async def _is_element_visible(self):
+        """
+        Verifies if the element is visible using JavaScript.
+        It uses the getBoundingClientRect method to check if the element is
+        within the viewport and the width and height are greater than 0.
+
+        Returns:
+            bool: True if the element is visible, False otherwise.
+        """
+        result = await self._execute_script(
+            Scripts.ELEMENT_VISIBLE, return_by_value=True
+        )
+        return result['result']['result']['value']
+
+    async def _is_element_on_top(self):
+        """
+        Verifies if the element is on top of the page using JavaScript.
+        It uses the elementFromPoint method to check if the element is the
+        topmost element at the center of its bounding box.
+
+        Returns:
+            bool: True if the element is on top of the page, False otherwise.
+        """
+        result = await self._execute_script(
+            Scripts.ELEMENT_ON_TOP, return_by_value=True
+        )
+        return result['result']['result']['value']
+
+    async def get_screenshot(self, path: str):
+        """
+        Takes a screenshot of the element.
+
+        Args:
+            path (str): The path where the screenshot will be saved.
+        """
+        bounds = await self.get_bounds_using_js()
+        clip = {
+            'x': bounds['x'],
+            'y': bounds['y'],
+            'width': bounds['width'],
+            'height': bounds['height'],
+            'scale': 1,
+        }
+        screenshot = await self._connection_handler.execute_command(
+            PageCommands.screenshot(format='jpeg', clip=clip)
+        )
+        async with aiofiles.open(path, 'wb') as file:
+            image_bytes = decode_image_to_bytes(screenshot['result']['data'])
+            await file.write(image_bytes)
+
+    async def get_element_text(self) -> str:
+        """
+        Retrieves the text of the element.
+
+        Returns:
+            str: The text of the element.
+        """
+        outer_html = await self.inner_html
+        soup = BeautifulSoup(outer_html, 'html.parser')
+        text_inside = soup.get_text(strip=True)
+        return text_inside
+
+    def get_attribute(self, name: str) -> str:
+        """
+        Retrieves the attribute value of the element.
+
+        Args:
+            name (str): The name of the attribute.
+
+        Returns:
+            str: The value of the attribute.
+        """
+        return self._attributes.get(name)
+
+    async def scroll_into_view(self):
+        """
+        Scrolls the element into view.
+        """
+        command = DomCommands.scroll_into_view(object_id=self._object_id)
+        await self._execute_command(command)
+
+    async def click_using_js(self):
+        if self._is_option_tag():
+            return await self.click_option_tag()
+
+        await self.scroll_into_view()
+
+        if not await self._is_element_visible():
+            raise exceptions.ElementNotVisible(
+                'Element is not visible on the page.'
+            )
+
+        result = await self._execute_script(
+            Scripts.CLICK, return_by_value=True
+        )
+        clicked = result['result']['result']['value']
+        if not clicked:
+            raise exceptions.ElementNotInteractable(
+                'Element is not interactable.'
+            )
+
+    async def click(self, x_offset: int = 0, y_offset: int = 0):
+        if self._is_option_tag():
+            return await self.click_option_tag()
+
+        if not await self._is_element_visible():
+            raise exceptions.ElementNotVisible(
+                'Element is not visible on the page.'
+            )
+
+        await self.scroll_into_view()
+
+        try:
+            element_bounds = await self.bounds
+            position_to_click = self._calculate_center(element_bounds)
+            position_to_click = (
+                position_to_click[0] + x_offset,
+                position_to_click[1] + y_offset,
+            )
+        except KeyError:
+            element_bounds = await self.get_bounds_using_js()
+            position_to_click = (
+                element_bounds['x'] + element_bounds['width'] / 2,
+                element_bounds['y'] + element_bounds['height'] / 2,
+            )
+
+        press_command = InputCommands.mouse_press(*position_to_click)
+        release_command = InputCommands.mouse_release(*position_to_click)
+        await self._connection_handler.execute_command(press_command)
+        await asyncio.sleep(0.1)
+        await self._connection_handler.execute_command(release_command)
+
+    async def click_option_tag(self):
+        script = Scripts.CLICK_OPTION_TAG.replace('{self.value}', self.value)
+        await self._execute_command(RuntimeCommands.evaluate_script(script))
+
+    async def send_keys(self, text: str):
+        """
+        Sends a sequence of keys to the element.
+
+        Args:
+            text (str): The text to send to the element.
+        """
+        await self._execute_command(InputCommands.insert_text(text))
+
+    async def type_keys(self, text: str):
+        """
+        Types in a realistic manner by sending keys one by one.
+
+        Args:
+            text (str): The text to send to the element.
+        """
+        for char in text:
+            await self._execute_command(InputCommands.key_press(char))
+            await asyncio.sleep(0.1)
+
+    def _is_option_tag(self):
+        return self._attributes['tag_name'].lower() == 'option'
+
+    @staticmethod
+    def _calculate_center(bounds: list) -> tuple:
+        x_values = [bounds[i] for i in range(0, len(bounds), 2)]
+        y_values = [bounds[i] for i in range(1, len(bounds), 2)]
+        x_center = sum(x_values) / len(x_values)
+        y_center = sum(y_values) / len(y_values)
+        return x_center, y_center

pydoll/events/__init__.py

@@ -0,0 +1,13 @@
+from pydoll.events.browser import BrowserEvents
+from pydoll.events.dom import DomEvents
+from pydoll.events.fetch import FetchEvents
+from pydoll.events.network import NetworkEvents
+from pydoll.events.page import PageEvents
+
+__all__ = [
+    'BrowserEvents',
+    'DomEvents',
+    'FetchEvents',
+    'NetworkEvents',
+    'PageEvents',
+]

pydoll/events/browser.py

@@ -0,0 +1,26 @@
+class BrowserEvents:
+    """
+    A class to define the browser events available through the
+    Chrome DevTools Protocol (CDP). These events allow for monitoring
+    specific actions and states within the browser, such as downloads.
+    """
+
+    DOWNLOAD_PROGRESS = 'Browser.downloadProgress'
+    """
+    Event triggered when the download progress updates.
+
+    This event provides details about the ongoing download,
+    including the amount downloaded and the total size.
+    It is part of the CDP's capabilities for monitoring
+    download activities in the browser.
+    """
+
+    DOWNLOAD_WILL_BEGIN = 'Browser.downloadWillBegin'
+    """
+    Event triggered when a download is about to start.
+
+    This event notifies listeners before the download begins,
+    providing an opportunity to handle or react to download events.
+    This is part of the CDP's support for download management
+    in the browser.
+    """

pydoll/events/dom.py

@@ -0,0 +1,108 @@
+class DomEvents:
+    """
+    A class to define the DOM events available through the
+    Chrome DevTools Protocol (CDP). These events allow for monitoring
+    changes and updates within the Document Object Model (DOM)
+    of a web page, enabling developers to react to specific
+    modifications and interactions with the DOM elements.
+    """
+
+    ATTRIBUTE_MODIFIED = 'DOM.attributeModified'
+    """
+    Event triggered when an attribute of a DOM node is modified.
+
+    This event provides information about the node affected and the
+    attribute that was changed. It is part of the CDP's capabilities
+    for tracking DOM changes and allows developers to respond
+    to attribute modifications in real time.
+    """
+
+    ATTRIBUTE_REMOVED = 'DOM.attributeRemoved'
+    """
+    Event triggered when an attribute of a DOM node is removed.
+
+    This event indicates that an attribute has been deleted from a
+    node, allowing developers to manage state or perform cleanup
+    based on the changes. It is supported by the CDP to ensure
+    developers can monitor DOM manipulations effectively.
+    """
+
+    CHARACTER_DATA_MODIFIED = 'DOM.characterDataModified'
+    """
+    Event triggered when the character data of a DOM node is modified.
+
+    This event informs listeners about changes in the text content
+    of a node, which is essential for applications that need to
+    reflect real-time updates in the UI based on data changes.
+    """
+
+    CHILD_NODE_COUNT_UPDATED = 'DOM.childNodeCountUpdated'
+    """
+    Event triggered when the number of child nodes of a DOM node is updated.
+
+    This event alerts developers when the number of children changes,
+    allowing them to react to structural changes in the DOM tree.
+    """
+
+    CHILD_NODE_INSERTED = 'DOM.childNodeInserted'
+    """
+    Event triggered when a new child node is inserted into a DOM node.
+
+    This event notifies listeners of new additions to the DOM,
+    enabling actions such as updating UI components or handling
+    related data.
+    """
+
+    CHILD_NODE_REMOVED = 'DOM.childNodeRemoved'
+    """
+    Event triggered when a child node is removed from a DOM node.
+
+    This event indicates that a child has been deleted, allowing
+    developers to manage their state or trigger updates based on
+    the removal of elements in the DOM.
+    """
+
+    DOCUMENT_UPDATED = 'DOM.documentUpdated'
+    """
+    Event triggered when the DOM document is updated.
+
+    This event signifies that changes have occurred at the document
+    level, prompting developers to refresh or update their views
+    accordingly.
+    """
+
+    SCROLLABLE_FLAG_UPDATED = 'DOM.scrollableFlagUpdated'
+    """
+    Event triggered when the scrollable flag of a DOM node is updated.
+
+    This event is useful for determining which elements in the DOM
+    can be scrolled, allowing for enhanced user interactions and
+    responsive designs.
+    """
+
+    SHADOW_ROOT_POPPED = 'DOM.shadowRootPopped'
+    """
+    Event triggered when a shadow root is popped from the stack.
+
+    This event indicates that a shadow DOM context has been removed,
+    which is relevant for applications utilizing shadow DOM features
+    for encapsulated styling and markup.
+    """
+
+    SHADOW_ROOT_PUSHED = 'DOM.shadowRootPushed'
+    """
+    Event triggered when a shadow root is pushed onto the stack.
+
+    This event signifies that a new shadow DOM context has been
+    created, allowing developers to manage and respond to changes
+    in encapsulated DOM structures.
+    """
+
+    TOP_LAYER_ELEMENTS_UPDATED = 'DOM.topLayerElementsUpdated'
+    """
+    Event triggered when the top layer elements in the DOM are updated.
+
+    This event allows for monitoring changes in the most visible
+    elements in the DOM, which is essential for managing UI states
+    and rendering updates.
+    """

pydoll/events/fetch.py

@@ -0,0 +1,29 @@
+class FetchEvents:
+    """
+    A class to define the Fetch events available through the
+    Chrome DevTools Protocol (CDP). These events are related to
+    the management of network requests, allowing developers to
+    intercept, modify, and monitor HTTP requests and responses
+    made by the browser.
+    """
+
+    AUTH_REQUIRED = 'Fetch.authRequired'
+    """
+    Event triggered when authentication is required for a network
+    request.
+
+    This event allows developers to respond to authentication
+    challenges, enabling them to provide credentials or take
+    appropriate actions when the requested resource requires
+    authentication.
+    """
+
+    REQUEST_PAUSED = 'Fetch.requestPaused'
+    """
+    Event triggered when a network request is paused.
+
+    This event is particularly useful for developers who want to
+    analyze or modify requests before they are sent. When a request
+    is paused, it gives the opportunity to inspect the request data
+    or alter headers before resuming it.
+    """

pydoll/events/network.py

@@ -0,0 +1,160 @@
+class NetworkEvents:
+    """
+    A class that defines constants for various network-related events.
+
+    These constants can be used to identify and handle network interactions in
+    applications, particularly in event-driven architectures or APIs that
+    monitor network activity.
+    """
+
+    DATA_RECEIVED = 'Network.dataReceived'
+    """
+    Event triggered when data is received over the network.
+
+    This can include responses from HTTP requests, incoming WebSocket messages,
+    or data from other network interactions. Useful for tracking incoming data
+    flow.
+    """
+
+    EVENT_SOURCE_MESSAGE_RECEIVED = 'Network.eventSourceMessageReceived'
+    """
+    Event fired when a message is received from an EventSource.
+
+    Typically used for server-sent events (SSE), this event indicates that a
+    new message has been sent from the server to the client, enabling real-time
+    updates.
+    """
+
+    LOADING_FAILED = 'Network.loadingFailed'
+    """
+    Event that indicates a failure in loading a network resource.
+
+    This can occur due to various reasons, such as network errors, resource
+    not found, or permission issues. This event is critical for error handling
+    and debugging.
+    """
+
+    LOADING_FINISHED = 'Network.loadingFinished'
+    """
+    Event fired when a network loading operation is completed.
+
+    This event is triggered regardless of whether the loading was successful
+    or failed, making it useful for cleaning up or updating the user interface
+    after loading operations.
+    """
+
+    REQUEST_SERVED_FROM_CACHE = 'Network.requestServedFromCache'
+    """
+    Event indicating that a network request was fulfilled from the cache.
+
+    This helps identify when data is being retrieved from cache instead of
+    making a new network request, which can improve performance and reduce
+    latency.
+    """
+
+    REQUEST_WILL_BE_SENT = 'Network.requestWillBeSent'
+    """
+    Event triggered just before a network request is sent.
+
+    This is useful for logging, modifying request headers, or performing
+    actions before the actual request is made. It allows developers to
+    intercept and examine requests.
+    """
+
+    RESPONSE_RECEIVED = 'Network.responseReceived'
+    """
+    Event that indicates a response has been received from a network request.
+
+    This event contains details about the response, such as status codes,
+    headers, and the body of the response. It's crucial for processing the
+    results of network requests.
+    """
+
+    WEB_SOCKET_CLOSED = 'Network.webSocketClosed'
+    """
+    Event that occurs when a WebSocket connection has been closed.
+
+    This can happen due to normal closure, errors, or network interruptions.
+    Handling this event is important for managing WebSocket connections and
+    reconnection logic.
+    """
+
+    WEB_SOCKET_CREATED = 'Network.webSocketCreated'
+    """
+    Event fired when a new WebSocket connection is established.
+
+    This indicates that a WebSocket connection is active and ready for
+    communication, allowing developers to set up message handlers or perform
+    other initialization tasks.
+    """
+
+    WEB_SOCKET_FRAME_ERROR = 'Network.webSocketFrameError'
+    """
+    Event indicating that there was an error with a frame in a WebSocket
+    communication.
+
+    This can be used to handle specific frame-related errors and improve the
+    robustness of WebSocket implementations by allowing for error logging and
+    corrective actions.
+    """
+
+    WEB_SOCKET_FRAME_RECEIVED = 'Network.webSocketFrameReceived'
+    """
+    Event fired when a frame is received through a WebSocket.
+
+    This is essential for processing incoming messages and performing actions
+    based on the content of those messages.
+    """
+
+    WEB_SOCKET_FRAME_SENT = 'Network.webSocketFrameSent'
+    """
+    Event representing a frame that has been sent through a WebSocket.
+
+    This event can be used for logging sent messages, monitoring communication,
+    or performing actions after a message has been sent.
+    """
+
+    WEB_TRANSPORT_CLOSED = 'Network.webTransportClosed'
+    """
+    Event indicating that a web transport connection has been closed.
+
+    Web transport connections are often used for low-latency communication.
+    Handling this event is vital for ensuring that resources are properly
+    released and that the application can react to disconnections.
+    """
+
+    WEB_TRANSPORT_CONNECTION_ESTABLISHED = (
+        'Network.webTransportConnectionEstablished'
+    )
+    """
+    Event fired when a web transport connection is successfully established.
+
+    This signifies that the connection is ready for use, allowing for
+    immediate data transmission and interaction.
+    """
+
+    WEB_TRANSPORT_CREATED = 'Network.webTransportCreated'
+    """
+    Event that signifies that a new web transport connection has been created.
+
+    This is useful for setting up communication channels and initializing
+    necessary resources for the newly created transport.
+    """
+
+    POLICY_UPDATED = 'Network.policyUpdated'
+    """
+    Event that indicates that the network policy has been updated.
+
+    This might relate to security, access controls, or other network-related
+    policies that affect how requests and responses are handled. It’s important
+    for maintaining compliance and security in applications.
+    """
+
+    REQUEST_INTERCEPTED = 'Network.requestIntercepted'
+    """
+    Event fired when a network request has been intercepted.
+
+    This is often used in service workers or other intermediary layers to
+    modify or block requests before they reach the network. Handling this event
+    is crucial for implementing custom request logic or caching strategies.
+    """