pydoll-python 1.2.0__py3-none-any.whl

pydoll/commands/browser.py

@@ -0,0 +1,108 @@
+class BrowserCommands:
+    """
+    BrowserCommands class provides a set of commands to interact with the
+    browser's main functionality based on CDP. These commands allow for
+    managing browser windows, such as closing windows, retrieving window IDs,
+    and adjusting window bounds (size and state).
+
+    The following operations can be performed:
+    - Close the browser.
+    - Get the ID of the current window.
+    - Set the size and position of a specific window.
+    - Maximize or minimize a specific window.
+
+    Each method generates a command that can be sent to the browser
+    as part of the communication with the browser's underlying API.
+    """
+
+    CLOSE = {'method': 'Browser.close'}
+    GET_WINDOW_ID = {'method': 'Browser.WindowID'}
+    SET_WINDOW_BOUNDS_TEMPLATE = {
+        'method': 'Browser.setWindowBounds',
+        'params': {},
+    }
+    SET_DOWNLOAD_BEHAVIOR = {
+        'method': 'Browser.setDownloadBehavior',
+        'params': {},
+    }
+
+    @classmethod
+    def set_download_path(cls, path: str) -> dict:
+        """
+        Generates the command to set the download path for the browser.
+
+        Args:
+            path (str): The path to set for downloads.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        command = cls.SET_DOWNLOAD_BEHAVIOR.copy()
+        command['params']['behavior'] = 'allow'
+        command['params']['downloadPath'] = path
+        return command
+
+    @classmethod
+    def close(cls) -> dict:
+        """
+        Generates the command to close the browser.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        return cls.CLOSE
+
+    @classmethod
+    def get_window_id(cls) -> dict:
+        """
+        Generates the command to get the ID of the current window.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        return cls.GET_WINDOW_ID
+
+    @classmethod
+    def set_window_bounds(cls, window_id: int, bounds: dict) -> dict:
+        """
+        Generates the command to set the bounds of a window.
+
+        Args:
+            window_id (int): The ID of the window to set the bounds for.
+            bounds (dict): The bounds to set for the window,
+                           which should include width, height,
+                           and optionally x and y coordinates.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        command = cls.SET_WINDOW_BOUNDS_TEMPLATE.copy()
+        command['params']['windowId'] = window_id
+        command['params']['bounds'] = bounds
+        return command
+
+    @classmethod
+    def set_window_maximized(cls, window_id: int) -> dict:
+        """
+        Generates the command to maximize a window.
+
+        Args:
+            window_id (int): The ID of the window to maximize.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        return cls.set_window_bounds(window_id, {'windowState': 'maximized'})
+
+    @classmethod
+    def set_window_minimized(cls, window_id: int) -> dict:
+        """
+        Generates the command to minimize a window.
+
+        Args:
+            window_id (int): The ID of the window to minimize.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        return cls.set_window_bounds(window_id, {'windowState': 'minimized'})

pydoll/commands/dom.py

@@ -0,0 +1,212 @@
+import copy
+from typing import Literal
+
+from pydoll.commands.runtime import RuntimeCommands
+from pydoll.constants import By, Scripts
+
+
+class DomCommands:
+    """
+    A class to define commands for interacting with the Document
+    Object Model (DOM) using the Chrome DevTools Protocol (CDP).
+    The commands allow for various operations on DOM nodes,
+    such as enabling the DOM domain, retrieving the
+    DOM document, describing nodes, and querying elements.
+
+    Attributes:
+        SelectorType (Literal): A type definition for supported selector types.
+    """
+
+    SelectorType = Literal[
+        By.CSS_SELECTOR, By.XPATH, By.CLASS_NAME, By.ID, By.TAG_NAME
+    ]
+
+    ENABLE = {'method': 'DOM.enable'}
+    DOM_DOCUMENT = {'method': 'DOM.getDocument'}
+    DESCRIBE_NODE_TEMPLATE = {'method': 'DOM.describeNode', 'params': {}}
+    FIND_ELEMENT_TEMPLATE = {'method': 'DOM.querySelector', 'params': {}}
+    FIND_ALL_ELEMENTS_TEMPLATE = {
+        'method': 'DOM.querySelectorAll',
+        'params': {},
+    }
+    BOX_MODEL_TEMPLATE = {'method': 'DOM.getBoxModel', 'params': {}}
+    RESOLVE_NODE_TEMPLATE = {'method': 'DOM.resolveNode', 'params': {}}
+    REQUEST_NODE_TEMPLATE = {'method': 'DOM.requestNode', 'params': {}}
+    GET_OUTER_HTML = {
+        'method': 'DOM.getOuterHTML',
+        'params': {},
+    }
+    SCROLL_INTO_VIEW_IF_NEEDED = {
+        'method': 'DOM.scrollIntoViewIfNeeded',
+        'params': {},
+    }
+
+    @classmethod
+    def scroll_into_view(cls, object_id: str) -> dict:
+        """Generates the command to scroll a specific DOM node into view."""
+        command = copy.deepcopy(cls.SCROLL_INTO_VIEW_IF_NEEDED)
+        command['params']['objectId'] = object_id
+        return command
+
+    @classmethod
+    def get_outer_html(cls, object_id: int) -> dict:
+        """Generates the command to get the outer HTML"""
+        command = copy.deepcopy(cls.GET_OUTER_HTML)
+        command['params']['objectId'] = object_id
+        return command
+
+    @classmethod
+    def dom_document(cls) -> dict:
+        """
+        Generates the command to get the root DOM node of the current page.
+        """
+        return cls.DOM_DOCUMENT
+
+    @classmethod
+    def request_node(cls, object_id: str) -> dict:
+        """Generates the command to request a specific DOM node by its object
+        ID."""
+        command = copy.deepcopy(cls.REQUEST_NODE_TEMPLATE)
+        command['params']['objectId'] = object_id
+        return command
+
+    @classmethod
+    def describe_node(cls, object_id: str) -> dict:
+        """Generates the command to describe a specific DOM node."""
+        command = copy.deepcopy(cls.DESCRIBE_NODE_TEMPLATE)
+        command['params']['objectId'] = object_id
+        return command
+
+    @classmethod
+    def box_model(cls, object_id: str) -> dict:
+        """
+        Generates the command to get the box model of a specific DOM node.
+        """
+        command = copy.deepcopy(cls.BOX_MODEL_TEMPLATE)
+        command['params']['objectId'] = object_id
+        return command
+
+    @classmethod
+    def enable_dom_events(cls) -> dict:
+        """Generates the command to enable the DOM domain."""
+        return cls.ENABLE
+
+    @classmethod
+    def get_current_url(cls) -> dict:
+        """Generates the command to get the current URL of the page."""
+        return RuntimeCommands.evaluate_script('window.location.href')
+
+    @classmethod
+    def find_element(
+        cls,
+        by: SelectorType,
+        value: str,
+        object_id: str = '',
+    ) -> dict:
+        """Generates a command to find a DOM element based on the specified
+        criteria."""
+        escaped_value = value.replace('"', '\\"')
+        match by:
+            case By.CLASS_NAME:
+                selector = f'.{escaped_value}'
+            case By.ID:
+                selector = f'#{escaped_value}'
+            case _:
+                selector = escaped_value
+        if object_id and not by == By.XPATH:
+            script = Scripts.RELATIVE_QUERY_SELECTOR.replace(
+                '{selector}', selector
+            )
+            command = RuntimeCommands.call_function_on(
+                object_id,
+                script,
+                return_by_value=False,
+            )
+        elif by == By.XPATH:
+            command = cls._find_element_by_xpath(value, object_id)
+        else:
+            command = RuntimeCommands.evaluate_script(
+                Scripts.QUERY_SELECTOR.replace('{selector}', selector)
+            )
+        return command
+
+    @classmethod
+    def find_elements(
+        cls,
+        by: SelectorType,
+        value: str,
+        object_id: str = '',
+    ) -> dict:
+        """Generates a command to find multiple DOM elements based on the
+        specified criteria."""
+        escaped_value = value.replace('"', '\\"')
+        match by:
+            case By.CLASS_NAME:
+                selector = f'.{escaped_value}'
+            case By.ID:
+                selector = f'#{escaped_value}'
+            case _:
+                selector = escaped_value
+        if object_id and not by == By.XPATH:
+            script = Scripts.RELATIVE_QUERY_SELECTOR_ALL.replace(
+                '{selector}', escaped_value
+            )
+            command = RuntimeCommands.call_function_on(
+                object_id,
+                script,
+                return_by_value=False,
+            )
+        elif by == By.XPATH:
+            command = cls._find_elements_by_xpath(value, object_id)
+        else:
+            command = RuntimeCommands.evaluate_script(
+                Scripts.QUERY_SELECTOR_ALL.replace('{selector}', selector)
+            )
+        return command
+
+    @classmethod
+    def _find_element_by_xpath(cls, xpath: str, object_id: str) -> dict:
+        """Creates a command to find a DOM element by XPath."""
+        escaped_value = xpath.replace('"', '\\"')
+        if object_id:
+            escaped_value = cls._ensure_relative_xpath(escaped_value)
+            script = Scripts.FIND_RELATIVE_XPATH_ELEMENT.replace(
+                '{escaped_value}', escaped_value
+            )
+            command = RuntimeCommands.call_function_on(
+                object_id,
+                script,
+                return_by_value=False,
+            )
+        else:
+            script = Scripts.FIND_XPATH_ELEMENT.replace(
+                '{escaped_value}', escaped_value
+            )
+            command = RuntimeCommands.evaluate_script(script)
+        return command
+
+    @classmethod
+    def _find_elements_by_xpath(cls, xpath: str, object_id: str) -> dict:
+        """Creates a command to find multiple DOM elements by XPath."""
+        escaped_value = xpath.replace('"', '\\"')
+        if object_id:
+            escaped_value = cls._ensure_relative_xpath(escaped_value)
+            script = Scripts.FIND_RELATIVE_XPATH_ELEMENTS.replace(
+                '{escaped_value}', escaped_value
+            )
+            command = RuntimeCommands.call_function_on(
+                object_id,
+                script,
+                return_by_value=False,
+            )
+        else:
+            script = Scripts.FIND_XPATH_ELEMENTS.replace(
+                '{escaped_value}', escaped_value
+            )
+            command = RuntimeCommands.evaluate_script(script)
+        return command
+
+    @staticmethod
+    def _ensure_relative_xpath(xpath: str) -> str:
+        """Ensures that the XPath expression is relative."""
+        return f'.{xpath}' if not xpath.startswith('.') else xpath

pydoll/commands/fetch.py

@@ -0,0 +1,308 @@
+class FetchCommands:
+    """
+    A collection of command templates for handling fetch events in the browser.
+
+    This class provides a structured way to create and manage commands related
+    to fetch operations intercepted by the Fetch API. Each command corresponds
+    to specific actions that can be performed on fetch requests, such as
+    continuing a fetch request, fulfilling a fetch response, or handling
+    authentication challenges.
+
+    Attributes:
+        CONTINUE_REQUEST (dict): Template for continuing an intercepted fetch
+            request.
+        CONTINUE_REQUEST_WITH_AUTH (dict): Template for continuing a fetch
+            request that requires authentication.
+        DISABLE (dict): Template for disabling fetch interception.
+        ENABLE (dict): Template for enabling fetch interception.
+        FAIL_REQUEST (dict): Template for simulating a failure in a fetch
+            request.
+        FULFILL_REQUEST (dict): Template for fulfilling a fetch request with
+            custom responses.
+        GET_RESPONSE_BODY (dict): Template for retrieving the response body of
+            a fetch request.
+        CONTINUE_RESPONSE (dict): Template for continuing a fetch response for
+            an intercepted request.
+    """
+
+    CONTINUE_REQUEST = {'method': 'Fetch.continueRequest', 'params': {}}
+    CONTINUE_REQUEST_WITH_AUTH = {
+        'method': 'Fetch.continueWithAuth',
+        'params': {},
+    }
+    DISABLE = {'method': 'Fetch.disable', 'params': {}}
+    ENABLE = {'method': 'Fetch.enable', 'params': {}}
+    FAIL_REQUEST = {'method': 'Fetch.failRequest', 'params': {}}
+    FULFILL_REQUEST = {'method': 'Fetch.fulfillRequest', 'params': {}}
+    GET_RESPONSE_BODY = {'method': 'Fetch.getResponseBody', 'params': {}}
+    CONTINUE_RESPONSE = {'method': 'Fetch.continueResponse', 'params': {}}
+
+    @classmethod
+    def continue_request(  # noqa: PLR0913, PLR0917
+        cls,
+        request_id: str,
+        url: str = '',
+        method: str = '',
+        post_data: str = '',
+        headers: dict = {},
+        intercept_response: bool = False,
+    ):
+        """
+        Creates a command to continue a paused fetch request.
+
+        This command allows the browser to resume a fetch operation that has
+        been intercepted. You can modify the fetch request URL, method,
+        headers, and body before continuing.
+
+        Args:
+            request_id (str): The ID of the fetch request to continue.
+            url (str, optional): The new URL for the fetch request. Defaults to
+                ''.
+            method (str, optional): The HTTP method to use (e.g., 'GET',
+                'POST'). Defaults to ''.
+            postData (str, optional): The body data to send with the fetch
+                request. Defaults to ''.
+            headers (dict, optional): A dictionary of HTTP headers to include
+              in the fetch request. Defaults to {}.
+            interceptResponse (bool, optional): Indicates if the response
+              should be intercepted. Defaults to False.
+
+        Returns:
+            dict: A command template for continuing the fetch request.
+        """
+        continue_request_template = cls.CONTINUE_REQUEST.copy()
+        continue_request_template['params']['requestId'] = request_id
+        if url:
+            continue_request_template['params']['url'] = url
+        if method:
+            continue_request_template['params']['method'] = method
+        if post_data:
+            continue_request_template['params']['postData'] = post_data
+        if headers:
+            continue_request_template['params']['headers'] = headers
+        if intercept_response:
+            continue_request_template['params']['interceptResponse'] = (
+                intercept_response
+            )
+        return continue_request_template
+
+    @classmethod
+    def continue_request_with_auth(
+        cls, request_id: str, proxy_username: str, proxy_password: str
+    ):
+        """
+        Creates a command to continue a paused fetch request with
+        authentication.
+
+        This command is used when the fetch operation requires authentication.
+        It provides the necessary credentials to continue the request.
+
+        Args:
+            request_id (str): The ID of the fetch request to continue.
+            proxy_username (str): The username for proxy authentication.
+            proxy_password (str): The password for proxy authentication.
+
+        Returns:
+            dict: A command template for continuing the fetch request with
+                authentication.
+        """
+        continue_request_with_auth_template = (
+            cls.CONTINUE_REQUEST_WITH_AUTH.copy()
+        )
+        continue_request_with_auth_template['params']['requestId'] = request_id
+        continue_request_with_auth_template['params'][
+            'authChallengeResponse'
+        ] = {
+            'response': 'ProvideCredentials',
+            'username': proxy_username,
+            'password': proxy_password,
+        }
+        return continue_request_with_auth_template
+
+    @classmethod
+    def disable_fetch_events(cls):
+        """
+        Creates a command to disable fetch interception.
+
+        This command stops the browser from intercepting fetch requests.
+
+        Returns:
+            dict: A command template for disabling fetch interception.
+        """
+        return cls.DISABLE
+
+    @classmethod
+    def enable_fetch_events(
+        cls, handle_auth_requests: bool, resource_type: str
+    ):
+        """
+        Creates a command to enable fetch interception.
+
+        This command allows the browser to start intercepting fetch requests.
+        You can specify whether to handle authentication challenges and the
+        types of resources to intercept.
+
+        Args:
+            handle_auth_requests (bool): Indicates if authentication requests
+                should be handled.
+            resource_type (str): The type of resource to intercept (e.g.,
+                'Document', 'Image').
+
+        Returns:
+            dict: A command template for enabling fetch interception.
+        """
+        enable_fetch_events_template = cls.ENABLE.copy()
+        enable_fetch_events_template['params']['patterns'] = [
+            {'urlPattern': '*'}
+        ]
+        if resource_type:
+            enable_fetch_events_template['params']['patterns'][0][
+                'resourceType'
+            ] = resource_type
+
+        enable_fetch_events_template['params']['handleAuthRequests'] = (
+            handle_auth_requests
+        )
+        return enable_fetch_events_template
+
+    @classmethod
+    def fail_request(cls, request_id: str, error_reason: str):
+        """
+        Creates a command to simulate a failure in a fetch request.
+
+        This command allows you to simulate a failure for a specific fetch
+        operation, providing a reason for the failure.
+
+        Args:
+            request_id (str): The ID of the fetch request to fail.
+            errorReason (str): A description of the failure reason.
+
+        Returns:
+            dict: A command template for failing the fetch request.
+        """
+        fail_request_template = cls.FAIL_REQUEST.copy()
+        fail_request_template['params']['requestId'] = request_id
+        fail_request_template['params']['errorReason'] = error_reason
+        return fail_request_template
+
+    @classmethod
+    def fulfill_request(  # noqa: PLR0913, PLR0917
+        cls,
+        request_id: str,
+        response_code: int,
+        response_headers: dict = {},
+        binary_response_headers: str = '',
+        body: str = '',
+        response_phrase: str = '',
+    ):
+        """
+        Creates a command to fulfill a fetch request with a custom response.
+
+        This command allows you to provide a custom response for a fetch
+        operation, including the HTTP status code, headers, and body content.
+
+        Args:
+            request_id (str): The ID of the fetch request to fulfill.
+            responseCode (int): The HTTP status code to return.
+            responseHeaders (dict, optional): A dictionary of response headers.
+                Defaults to {}.
+            binaryResponseHeaders (str, optional): Binary response headers.
+                Defaults to ''.
+            body (str, optional): The body content of the response. Defaults to
+                ''.
+            responsePhrase (str, optional): The response phrase (e.g., 'OK',
+                'Not Found'). Defaults to ''.
+
+        Returns:
+            dict: A command template for fulfilling the fetch request.
+        """
+        fulfill_request_template = cls.FULFILL_REQUEST.copy()
+        fulfill_request_template['params']['requestId'] = request_id
+        if response_code:
+            fulfill_request_template['params']['responseCode'] = response_code
+        if response_headers:
+            fulfill_request_template['params']['responseHeaders'] = (
+                response_headers
+            )
+        if binary_response_headers:
+            fulfill_request_template['params']['binaryResponseHeaders'] = (
+                binary_response_headers
+            )
+        if body:
+            fulfill_request_template['params']['body'] = body
+        if response_phrase:
+            fulfill_request_template['params']['responsePhrase'] = (
+                response_phrase
+            )
+        return fulfill_request_template
+
+    @classmethod
+    def get_response_body(cls, request_id: str):
+        """
+        Creates a command to retrieve the response body of a fetch request.
+
+        This command allows you to access the body of a completed fetch
+        operation, which can be useful for analyzing the response data.
+
+        Args:
+            request_id (str): The ID of the fetch request to retrieve the body
+                from.
+
+        Returns:
+            dict: A command template for getting the response body.
+        """
+        get_response_body_template = cls.GET_RESPONSE_BODY.copy()
+        get_response_body_template['params']['requestId'] = request_id
+        return get_response_body_template
+
+    @classmethod
+    def continue_response(
+        cls,
+        request_id: str,
+        response_code: int = '',
+        response_headers: dict = {},
+        binary_response_headers: str = '',
+        response_phrase: str = '',
+    ):
+        """
+        Creates a command to continue a fetch response for an intercepted
+        request.
+
+        This command allows the browser to continue the response flow for a
+        specific fetch request, including customizing the HTTP status code,
+        headers, and response phrase.
+
+        Args:
+            requestId (str): The ID of the fetch request to continue the
+                response for.
+            responseCode (int, optional): The HTTP status code to send.
+                Defaults to ''.
+            responseHeaders (dict, optional): A dictionary of response headers.
+                Defaults to {}.
+            binaryResponseHeaders (str, optional): Binary response headers.
+                Defaults to ''.
+            responsePhrase (str, optional): The response phrase (e.g., 'OK').
+                Defaults to ''.
+
+        Returns:
+            dict: A command template for continuing the fetch response.
+        """
+        continue_response_template = cls.CONTINUE_RESPONSE.copy()
+        continue_response_template['params']['requestId'] = request_id
+        if response_code:
+            continue_response_template['params']['responseCode'] = (
+                response_code
+            )
+        if response_headers:
+            continue_response_template['params']['responseHeaders'] = (
+                response_headers
+            )
+        if binary_response_headers:
+            continue_response_template['params']['binaryResponseHeaders'] = (
+                binary_response_headers
+            )
+        if response_phrase:
+            continue_response_template['params']['responsePhrase'] = (
+                response_phrase
+            )
+        return continue_response_template