pydoll-python 1.2.0__py3-none-any.whl

pydoll/commands/input.py

@@ -0,0 +1,106 @@
+class InputCommands:
+    """
+    A class to define input commands for simulating user interactions
+    with the browser using the Chrome DevTools Protocol (CDP).
+    The commands allow for simulating mouse clicks and keyboard presses.
+    """
+
+    CLICK_ELEMENT_TEMPLATE = {
+        'method': 'Input.dispatchMouseEvent',
+        'params': {},
+    }
+    KEY_PRESS_TEMPLATE = {'method': 'Input.dispatchKeyEvent', 'params': {}}
+    INSERT_TEXT_TEMPLATE = {'method': 'Input.insertText', 'params': {}}
+
+    @classmethod
+    def mouse_press(cls, x: int, y: int) -> dict:
+        """
+        Generates the command to simulate pressing the mouse button on a
+        specific location.
+
+        Args:
+            x (int): The x-coordinate of the mouse press.
+            y (int): The y-coordinate of the mouse press.
+
+        This command utilizes the CDP to simulate a mouse press event at
+        the specified coordinates.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        command = cls.CLICK_ELEMENT_TEMPLATE.copy()
+        command['params'] = {
+            'type': 'mousePressed',
+            'button': 'left',
+            'x': x,
+            'y': y,
+            'clickCount': 1,
+            'modifiers': 0,
+        }
+        return command
+
+    @classmethod
+    def mouse_release(cls, x: int, y: int) -> dict:
+        """
+        Generates the command to simulate releasing the mouse button.
+
+        Args:
+            x (int): The x-coordinate of the mouse release.
+            y (int): The y-coordinate of the mouse release.
+
+        This command uses the CDP to simulate a mouse release event at
+        the specified coordinates.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        command = cls.CLICK_ELEMENT_TEMPLATE.copy()
+        command['params'] = {
+            'type': 'mouseReleased',
+            'button': 'left',
+            'x': x,
+            'y': y,
+            'clickCount': 1,
+            'modifiers': 0,
+        }
+        return command
+
+    @classmethod
+    def key_press(cls, char: str) -> dict:
+        """
+        Generates the command to simulate pressing a key on the keyboard.
+
+        Args:
+            char (str): The character to be pressed.
+
+        This command utilizes the CDP to simulate a keyboard event for
+        the specified character.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        command = cls.KEY_PRESS_TEMPLATE.copy()
+        command['params'] = {
+            'type': 'char',
+            'text': char,
+        }
+        return command
+
+    @classmethod
+    def insert_text(cls, text: str) -> dict:
+        """
+        Generates the command to insert text into an input field.
+
+        Args:
+            text (str): The text to be inserted.
+
+        This command uses the CDP to simulate typing text into an input field.
+
+        Returns:
+            dict: The command to be sent to the browser.
+        """
+        command = cls.INSERT_TEXT_TEMPLATE.copy()
+        command['params'] = {
+            'text': text,
+        }
+        return command

pydoll/commands/network.py

@@ -0,0 +1,334 @@
+import copy
+
+
+class NetworkCommands:
+    """
+    This class encapsulates the network commands of the
+    Chrome DevTools Protocol (CDP).
+
+    CDP allows developers to interact with the Chrome browser's internal
+    mechanisms to inspect, manipulate, and monitor network operations,
+    which can be invaluable for debugging web applications, testing network
+    behaviors, and optimizing performance.
+
+    The commands defined in this class provide functionality for:
+    - Managing browser cache and cookies.
+    - Enabling and disabling network events.
+    - Retrieving and modifying request and response data.
+    - Customizing HTTP headers and user agent strings.
+    - Blocking specific URLs to prevent unwanted network traffic.
+    """
+
+    CLEAR_BROWSER_CACHE = {'method': 'Network.clearBrowserCache'}
+    CLEAR_BROWSER_COOKIES = {'method': 'Network.clearBrowserCookies'}
+    DELETE_COOKIES_TEMPLATE = {'method': 'Network.deleteCookies', 'params': {}}
+    DISABLE = {'method': 'Network.disable'}
+    ENABLE = {'method': 'Network.enable'}
+    GET_COOKIES_TEMPLATE = {'method': 'Network.getCookies', 'params': {}}
+    GET_REQUEST_POST_DATA_TEMPLATE = {
+        'method': 'Network.getRequestPostData',
+        'params': {},
+    }
+    GET_RESPONSE_BODY_TEMPLATE = {
+        'method': 'Network.getResponseBody',
+        'params': {},
+    }
+    SET_CACHE_DISABLED_TEMPLATE = {
+        'method': 'Network.setCacheDisabled',
+        'params': {},
+    }
+    SET_COOKIE_TEMPLATE = {'method': 'Network.setCookie', 'params': {}}
+    SET_COOKIES_TEMPLATE = {'method': 'Network.setCookies', 'params': {}}
+    SET_EXTRA_HTTP_HEADERS_TEMPLATE = {
+        'method': 'Network.setExtraHTTPHeaders',
+        'params': {},
+    }
+    SET_USERAGENT_OVERRIDE_TEMPLATE = {
+        'method': 'Network.setUserAgentOverride',
+        'params': {},
+    }
+    GET_ALL_COOKIES = {'method': 'Network.getAllCookies'}
+    SEARCH_IN_RESPONSE_TEMPLATE = {
+        'method': 'Network.searchInResponseBody',
+        'params': {},
+    }
+    SET_BLOCKED_URLS = {'method': 'Network.setBlockedURLs', 'params': {}}
+
+    @classmethod
+    def clear_browser_cache(cls):
+        """
+        Command to clear the browser's cache.
+
+        This is useful when you want to ensure that your application retrieves
+        the most up-to-date resources from the server instead of loading
+        potentially stale data from the cache.
+        """
+        return cls.CLEAR_BROWSER_CACHE
+
+    @classmethod
+    def clear_browser_cookies(cls):
+        """
+        Command to clear all cookies stored in the browser.
+
+        This can be beneficial for testing scenarios where you need
+        to simulate a fresh user session without any previously stored
+        cookies that might affect the application's behavior.
+        """
+        return cls.CLEAR_BROWSER_COOKIES
+
+    @classmethod
+    def delete_cookies(cls, name: str, url: str = ''):
+        """
+        Creates a command to delete a specific cookie by name.
+
+        Args:
+            name (str): The name of the cookie to delete.
+            url (str, optional): The URL associated with the cookie.
+            If specified, only the cookie matching both the name and
+            URL will be deleted. If omitted, all cookies with the given
+            name will be deleted regardless of URL.
+
+        Returns:
+            dict: A command to delete the specified cookie.
+        """
+        delete_cookies_template = copy.deepcopy(cls.DELETE_COOKIES_TEMPLATE)
+        delete_cookies_template['params']['name'] = name
+        if url:
+            delete_cookies_template['params']['url'] = url
+        return delete_cookies_template
+
+    @classmethod
+    def disable_network_events(cls):
+        """
+        Command to disable network event notifications.
+
+        Use this command when you want to temporarily suspend the emission of
+        network events, which can be useful during specific operations
+        where you don't want to be notified about every network request
+        and response.
+        """
+        return cls.DISABLE
+
+    @classmethod
+    def enable_network_events(cls):
+        """
+        Command to enable network event notifications.
+
+        This allows you to start receiving network-related events again after
+        they have been disabled. It's essential to call this before you expect
+        to receive network events.
+        """
+        return cls.ENABLE
+
+    @classmethod
+    def get_cookies(cls, urls: list[str] = []):
+        """
+        Creates a command to retrieve cookies from specified URLs.
+
+        Args:
+            urls (list[str], optional): A list of URLs for which to retrieve
+                cookies. If not provided, cookies from all URLs will
+                be fetched.
+
+        Returns:
+            dict: A command to get cookies associated with the specified URLs.
+        """
+        get_cookies_template = copy.deepcopy(cls.GET_COOKIES_TEMPLATE)
+        if urls:
+            get_cookies_template['params']['urls'] = urls
+        return get_cookies_template
+
+    @classmethod
+    def get_request_post_data(cls, request_id: str):
+        """
+        Creates a command to retrieve POST data associated with a specific
+        request.
+
+        Args:
+            request_id (str): The unique identifier of the network
+                request whose POST data is to be retrieved.
+
+        Returns:
+            dict: A command to get the POST data for the specified request.
+        """
+        get_request_post_data_template = copy.deepcopy(
+            cls.GET_REQUEST_POST_DATA_TEMPLATE
+        )
+        get_request_post_data_template['params']['requestId'] = request_id
+        return get_request_post_data_template
+
+    @classmethod
+    def get_response_body(cls, request_id: str):
+        """
+        Creates a command to retrieve the body of a response for a specific
+        request.
+
+        Args:
+            request_id (str): The unique identifier of the request
+                for which the response body is to be fetched.
+
+        Returns:
+            dict: A command to get the response body associated with the
+                specified request.
+        """
+        get_response_body_template = copy.deepcopy(
+            cls.GET_RESPONSE_BODY_TEMPLATE
+        )
+        get_response_body_template['params']['requestId'] = request_id
+        return get_response_body_template
+
+    @classmethod
+    def set_cache_disabled(cls, cache_disabled: bool):
+        """
+        Creates a command to enable or disable the browser cache.
+
+        Args:
+            cache_disabled (bool): Set to True to disable caching, or False to
+                enable it.
+
+        Returns:
+            dict: A command to set the cache state in the browser.
+        """
+        set_cache_disabled_template = copy.deepcopy(
+            cls.SET_CACHE_DISABLED_TEMPLATE
+        )
+        set_cache_disabled_template['params']['cacheDisabled'] = cache_disabled
+        return set_cache_disabled_template
+
+    @classmethod
+    def set_cookie(cls, name: str, value: str, url: str = ''):
+        """
+        Creates a command to set a specific cookie.
+
+        Args:
+            name (str): The name of the cookie.
+            value (str): The value of the cookie.
+            url (str, optional): The URL associated with the cookie.
+                If provided, the cookie will be valid for this URL only.
+
+        Returns:
+            dict: A command to set the specified cookie in the browser.
+        """
+        set_cookie_template = copy.deepcopy(cls.SET_COOKIE_TEMPLATE)
+        set_cookie_template['params']['name'] = name
+        set_cookie_template['params']['value'] = value
+        if url:
+            set_cookie_template['params']['url'] = url
+        return set_cookie_template
+
+    @classmethod
+    def set_cookies(cls, cookies: list[dict]):
+        """
+        Creates a command to set multiple cookies at once.
+
+        Args:
+            cookies (list[dict]): A list of dictionaries, each representing a
+                cookie with its properties (name, value, url, etc.).
+
+        Returns:
+            dict: A command to set the specified cookies in the browser.
+        """
+        set_cookies_template = copy.deepcopy(cls.SET_COOKIES_TEMPLATE)
+        set_cookies_template['params']['cookies'] = cookies
+        return set_cookies_template
+
+    @classmethod
+    def set_extra_http_headers(cls, headers: dict):
+        """
+        Creates a command to set additional HTTP headers for subsequent network
+        requests.
+
+        Args:
+            headers (dict): A dictionary of headers to include in all future
+                requests.
+
+        Returns:
+            dict: A command to set extra HTTP headers for the browser's network
+                requests.
+        """
+        set_extra_http_headers_template = copy.deepcopy(
+            cls.SET_EXTRA_HTTP_HEADERS_TEMPLATE
+        )
+        set_extra_http_headers_template['params']['headers'] = headers
+        return set_extra_http_headers_template
+
+    @classmethod
+    def set_useragent_override(cls, user_agent: str):
+        """
+        Creates a command to override the user agent string used in network
+        requests.
+
+        Args:
+            user_agent (str): The user agent string to set for future network
+                requests.
+
+        Returns:
+            dict: A command to override the browser's user agent for network
+                requests.
+        """
+        set_useragent_override_template = copy.deepcopy(
+            cls.SET_USERAGENT_OVERRIDE_TEMPLATE
+        )
+        set_useragent_override_template['params']['userAgent'] = user_agent
+        return set_useragent_override_template
+
+    @classmethod
+    def get_all_cookies(cls):
+        """
+        Command to retrieve all cookies stored in the browser.
+
+        This can be useful for diagnostics, testing, or ensuring that your
+        application behaves as expected when accessing cookies.
+        """
+        return cls.GET_ALL_COOKIES
+
+    @classmethod
+    def search_in_response(
+        cls,
+        request_id: str,
+        query: str,
+        case_sensitive: bool = False,
+        is_regex: bool = False,
+    ):
+        """
+        Creates a command to search for a specific query in the response body
+        of a network request.
+
+        Args:
+            request_id (str): The unique identifier of the request to search
+                within.
+            query (str): The string to search for within the response body.
+            case_sensitive (bool, optional): Whether the search should be case
+                sensitive. Defaults to False.
+            is_regex (bool, optional): Whether the query should be treated as a
+                regular expression. Defaults to False.
+
+        Returns:
+            dict: A command to search the specified query within the response
+                body of the given request.
+        """
+        search_in_response_template = copy.deepcopy(
+            cls.SEARCH_IN_RESPONSE_TEMPLATE
+        )
+        search_in_response_template['params']['requestId'] = request_id
+        search_in_response_template['params']['query'] = query
+        search_in_response_template['params']['caseSensitive'] = case_sensitive
+        search_in_response_template['params']['isRegex'] = is_regex
+        return search_in_response_template
+
+    @classmethod
+    def set_blocked_urls(cls, urls: list[str]):
+        """
+        Creates a command to block specific URLs from being requested by the
+        browser.
+
+        Args:
+            urls (list[str]): A list of URL patterns to block. The browser will
+                not make requests to any URLs matching these patterns.
+
+        Returns:
+            dict: A command to set the specified URLs as blocked.
+        """
+        set_blocked_urls_template = copy.deepcopy(cls.SET_BLOCKED_URLS)
+        set_blocked_urls_template['params']['urls'] = urls
+        return set_blocked_urls_template

pydoll/commands/page.py

@@ -0,0 +1,187 @@
+class PageCommands:
+    """
+    PageCommands class provides a set of commands to interact with the
+    Page domain of the Chrome DevTools Protocol (CDP). These commands enable
+    users to perform operations related to web pages, such as capturing
+    screenshots, navigating to URLs, refreshing pages, printing to PDF,
+    and enabling the Page domain.
+
+    The following operations can be performed:
+    - Capture a screenshot of the current page.
+    - Navigate to a specified URL.
+    - Refresh the current page, with an option to ignore the cache.
+    - Print the current page to a PDF document.
+    - Enable the Page domain for further interactions.
+
+    Each method generates a command that can be sent to the browser as part of
+    the DevTools Protocol communication.
+    """
+
+    SCREENSHOT_TEMPLATE = {
+        'method': 'Page.captureScreenshot',
+        'params': {},
+    }
+    GO_TO_TEMPLATE = {'method': 'Page.navigate', 'params': {}}
+    REFRESH_TEMPLATE = {'method': 'Page.reload', 'params': {}}
+    PRINT_TO_PDF_TEMPLATE = {'method': 'Page.printToPDF', 'params': {}}
+    ENABLE_PAGE = {'method': 'Page.enable'}
+    DISABLE_PAGE = {'method': 'Page.disable'}
+    SET_DOWNLOAD_BEHAVIOR = {
+        'method': 'Page.setDownloadBehavior',
+        'params': {},
+    }
+    HANDLE_DIALOG = {'method': 'Page.handleJavaScriptDialog', 'params': {}}
+    CLOSE = {'method': 'Page.close'}
+
+    @classmethod
+    def handle_dialog(cls, accept: bool = True) -> dict:
+        """
+        Generates the command to handle a JavaScript dialog.
+
+        Args:
+            accept (bool): Whether to accept the dialog.
+                           If True, the dialog will be accepted.
+                           If False, the dialog will be dismissed.
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method and parameters for handling the dialog.
+        """
+        command = cls.HANDLE_DIALOG.copy()
+        command['params']['accept'] = accept
+        return command
+
+    @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 where the downloaded files should be saved.
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method and parameters for setting
+                  the download path.
+        """
+        command = cls.SET_DOWNLOAD_BEHAVIOR.copy()
+        command['params']['behavior'] = 'allow'
+        command['params']['downloadPath'] = path
+        return command
+
+    @classmethod
+    def screenshot(
+        cls, format: str = 'jpeg', quality: int = 100, clip: dict = None
+    ) -> dict:
+        """
+        Generates the command to capture a screenshot of the current page.
+
+        Args:
+            format (str): The format of the image to be captured.
+                          Can be 'png' or 'jpeg'.
+            quality (int): The quality of the image to be captured,
+                           applicable only if the format is 'jpeg'.
+                           Value should be between 0 (lowest quality)
+                           and 100 (highest quality).
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method and parameters for the screenshot.
+        """
+        command = cls.SCREENSHOT_TEMPLATE.copy()
+        command['params']['format'] = format
+        command['params']['quality'] = quality
+        if clip:
+            command['params']['clip'] = clip
+        return command
+
+    @classmethod
+    def go_to(cls, url: str) -> dict:
+        """
+        Generates the command to navigate to a specific URL.
+
+        Args:
+            url (str): The URL to navigate to. It should be a valid URL format.
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method and parameters for navigation.
+        """
+        command = cls.GO_TO_TEMPLATE.copy()
+        command['params']['url'] = url
+        return command
+
+    @classmethod
+    def refresh(cls, ignore_cache: bool = False) -> dict:
+        """
+        Generates the command to refresh the current page.
+
+        Args:
+            ignore_cache (bool): Whether to ignore the cache when refreshing.
+                                 If True, the cached resources will not be
+                                 used.
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method and parameters for page refresh.
+        """
+        command = cls.REFRESH_TEMPLATE.copy()
+        command['params']['ignoreCache'] = ignore_cache
+        return command
+
+    @classmethod
+    def print_to_pdf(
+        cls, scale: int = 1, paper_width: float = 8.5, paper_height: float = 11
+    ) -> dict:
+        """
+        Generates the command to print the current page to a PDF.
+
+        Args:
+            scale (int): The scale of the page to print. Default is 1 (100%).
+            paper_width (float): The width of the paper to print on, in inches.
+                Default is 8.5 inches.
+            paper_height (float): The height of the paper to print on,
+                in inches. Default is 11 inches.
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method and parameters for printing to PDF.
+        """
+        command = cls.PRINT_TO_PDF_TEMPLATE.copy()
+        command['params']['scale'] = scale
+        command['params']['paperWidth'] = paper_width
+        command['params']['paperHeight'] = paper_height
+        return command
+
+    @classmethod
+    def enable_page(cls) -> dict:
+        """
+        Generates the command to enable the Page domain.
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method to enable the Page domain.
+        """
+        return cls.ENABLE_PAGE
+
+    @classmethod
+    def disable_page(cls) -> dict:
+        """
+        Generates the command to disable the Page domain.
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method to disable the Page domain.
+        """
+        return cls.DISABLE_PAGE
+
+    @classmethod
+    def close(cls) -> dict:
+        """
+        Generates the command to close the current page.
+
+        Returns:
+            dict: The command to be sent to the browser,
+                  containing the method to close the current page.
+        """
+        return cls.CLOSE

pydoll/commands/runtime.py

@@ -0,0 +1,45 @@
+import copy
+
+
+class RuntimeCommands:
+    EVALUATE_TEMPLATE = {'method': 'Runtime.evaluate', 'params': {}}
+    CALL_FUNCTION_ON_TEMPLATE = {
+        'method': 'Runtime.callFunctionOn',
+        'params': {},
+    }
+    GET_PROPERTIES = {
+        'method': 'Runtime.getProperties',
+        'params': {},
+    }
+
+    @classmethod
+    def get_properties(cls, object_id: str) -> dict:
+        """Generates the command to get the properties of a specific object."""
+        command = copy.deepcopy(cls.GET_PROPERTIES)
+        command['params']['objectId'] = object_id
+        command['params']['ownProperties'] = True
+        return command
+
+    @classmethod
+    def call_function_on(
+        cls,
+        object_id: str,
+        function_declaration: str,
+        return_by_value: bool = False,
+    ) -> dict:
+        """Generates the command to call a function on a specific object."""
+        command = copy.deepcopy(cls.CALL_FUNCTION_ON_TEMPLATE)
+        command['params']['objectId'] = object_id
+        command['params']['functionDeclaration'] = function_declaration
+        command['params']['returnByValue'] = return_by_value
+        return command
+
+    @classmethod
+    def evaluate_script(cls, expression: str) -> dict:
+        """Generates the command to evaluate JavaScript code."""
+        command = copy.deepcopy(cls.EVALUATE_TEMPLATE)
+        command['params'] = {
+            'expression': expression,
+            'returnByValue': False,
+        }
+        return command

pydoll/commands/storage.py

@@ -0,0 +1,18 @@
+class StorageCommands:
+    CLEAR_COOKIES = {'method': 'Storage.clearCookies', 'params': {}}
+    SET_COOKIES = {'method': 'Storage.setCookies', 'params': {}}
+    GET_COOKIES = {'method': 'Storage.getCookies', 'params': {}}
+
+    @classmethod
+    def clear_cookies(cls) -> dict:
+        return cls.CLEAR_COOKIES
+
+    @classmethod
+    def set_cookies(cls, cookies: list) -> dict:
+        set_cookies = cls.SET_COOKIES.copy()
+        set_cookies['params']['cookies'] = cookies
+        return set_cookies
+
+    @classmethod
+    def get_cookies(cls) -> dict:
+        return cls.GET_COOKIES