pydoll-python 1.2.0__py3-none-any.whl

pydoll/events/page.py

@@ -0,0 +1,144 @@
+class PageEvents:
+    """
+    A class that defines constants for various page-related events.
+
+    These constants represent significant events in the lifecycle of a web
+    page, particularly in the context of web automation, testing,
+    or monitoring.
+    """
+
+    PAGE_LOADED = 'Page.loadEventFired'
+    """
+    Event triggered when the page has fully loaded.
+
+    This includes the loading of all resources, such as images and stylesheets.
+    It is typically used to perform actions that require the entire page to be
+    ready for interaction or manipulation.
+    """
+
+    DOM_CONTENT_LOADED = 'Page.domContentEventFired'
+    """
+    Event fired when the DOMContentLoaded event is fired.
+
+    This event indicates that the initial HTML document has been completely
+    loaded and parsed, which allows for immediate manipulation of the DOM
+    before external resources like images are fully loaded.
+    """
+
+    FILE_CHOOSER_OPENED = 'Page.fileChooserOpened'
+    """
+    Event indicating that a file chooser dialog has been opened.
+
+    This event is crucial for applications that require user interaction for
+    file uploads, allowing for tracking when a user is prompted to select
+    files.
+    """
+
+    FRAME_ATTACHED = 'Page.frameAttached'
+    """
+    Event that occurs when a frame is attached to the page.
+
+    This event is significant in scenarios involving iframes or nested browsing
+    contexts, enabling developers to manage and interact with newly added
+    frames.
+    """
+
+    FRAME_DETACHED = 'Page.frameDetached'
+    """
+    Event triggered when a frame is detached from the page.
+
+    This can happen when iframes are removed or navigated away, and it’s
+    important for cleanup and managing resources associated with those frames.
+    """
+
+    FRAME_NAVIGATED = 'Page.frameNavigated'
+    """
+    Event that indicates a frame has been navigated to a new URL.
+
+    This is essential for tracking navigation within iframes, allowing for
+    updates to the application state or user interface based on the content
+    of the frame.
+    """
+
+    JS_DIALOG_CLOSED = 'Page.javascriptDialogClosed'
+    """
+    Event fired when a JavaScript dialog (such as an alert or confirmation)
+    is closed.
+
+    This is useful for managing user interactions with dialogs, allowing for
+    actions to be taken after a dialog has been dismissed.
+    """
+
+    JS_DIALOG_OPENING = 'Page.javascriptDialogOpening'
+    """
+    Event triggered when a JavaScript dialog is about to open.
+
+    This event can be used to intervene in the opening of the dialog, such as
+    providing automated responses or logging dialog interactions.
+    """
+
+    LIFECYCLE_EVENT = 'Page.lifecycleEvent'
+    """
+    Event representing a generic lifecycle event for the page.
+
+    This event is a catch-all for various lifecycle-related events and can be
+    used for monitoring changes in the page state throughout its lifetime.
+    """
+
+    WINDOW_OPENED = 'Page.windowOpen'
+    """
+    Event that indicates a new window has been opened.
+
+    This is useful for applications that need to monitor or manage multiple
+    windows and their interactions, particularly in the context of pop-ups
+    or new tabs.
+    """
+
+    DOCUMENT_OPENED = 'Page.documentOpened'
+    """
+    Event that signifies a new document has been opened in the page.
+
+    This event is important for tracking changes in the document context,
+    particularly in environments where documents can be dynamically created
+    or loaded.
+    """
+
+    FRAME_STARTED_LOADING = 'Page.frameStartedLoading'
+    """
+    Event triggered when a frame starts loading content.
+
+    This event is useful for tracking the loading state of frames,
+    enabling developers to manage loading indicators or perform actions when
+    frames begin loading resources.
+    """
+
+    FRAME_STOPPED_LOADING = 'Page.frameStoppedLoading'
+    """
+    Event that indicates a frame has stopped loading content.
+
+    This can signify that a frame has successfully loaded or encountered an
+    error, allowing for appropriate handling of frame loading states.
+    """
+
+    DOWNLOAD_PROGRESS = 'Page.downloadProgress'
+    """
+    Event fired to indicate progress on a download operation.
+
+    This event provides updates on the download status, enabling the
+    application to inform users about ongoing downloads and their completion.
+    """
+
+    DOWNLOAD_WILL_BEGIN = 'Page.downloadWillBegin'
+    """
+    Event that occurs when a download is about to start.
+
+    This event is significant for tracking the initiation of downloads,
+    allowing for pre-download actions such as logging or user notifications.
+    """
+    NAVIGATED_WITHIN_DOCUMENT = 'Page.navigatedWithinDocument'
+    """
+    Event that indicates navigation within the same document.
+
+    This event is useful for tracking changes in the document state, such as
+    anchor links or in-page navigation, without requiring a full page reload.
+    """

pydoll/exceptions.py

@@ -0,0 +1,82 @@
+class ConnectionFailed(Exception):
+    message = 'Failed to connect to the browser'
+
+    def __str__(self):
+        return self.message
+
+
+class InvalidCommand(Exception):
+    message = 'The command provided is invalid'
+
+    def __str__(self):
+        return self.message
+
+
+class InvalidCallback(Exception):
+    message = 'The callback provided is invalid'
+
+    def __str__(self):
+        return self.message
+
+
+class NetworkError(Exception):
+    message = 'A network error occurred'
+
+    def __str__(self):
+        return self.message
+
+
+class InvalidResponse(Exception):
+    message = 'The response received is invalid'
+
+    def __str__(self):
+        return self.message
+
+
+class ReconnectionFailed(Exception):
+    message = 'Failed to reconnect to the browser'
+
+    def __str__(self):
+        return self.message
+
+
+class ResendCommandFailed(Exception):
+    message = 'Failed to resend the command'
+
+    def __str__(self):
+        return self.message
+
+
+class BrowserNotRunning(Exception):
+    message = 'The browser is not running'
+
+    def __str__(self):
+        return self.message
+
+
+class ElementNotFound(Exception):
+    message = 'The specified element was not found'
+
+    def __str__(self):
+        return self.message
+
+
+class ClickIntercepted(Exception):
+    message = 'The click was intercepted'
+
+    def __str__(self):
+        return self.message
+
+
+class ElementNotVisible(Exception):
+    message = 'The element is not visible'
+
+    def __str__(self):
+        return self.message
+
+
+class ElementNotInteractable(Exception):
+    message = 'The element is not interactable'
+
+    def __str__(self):
+        return self.message

pydoll/mixins/find_elements.py

@@ -0,0 +1,180 @@
+import asyncio
+
+from pydoll import exceptions
+from pydoll.commands.dom import DomCommands
+from pydoll.commands.runtime import RuntimeCommands
+
+
+def create_web_element(*args, **kwargs):
+    """
+    Creates a WebElement instance to avoid circular imports.
+    """
+    from pydoll.element import WebElement  # noqa: PLC0415
+
+    return WebElement(*args, **kwargs)
+
+
+class FindElementsMixin:
+    async def wait_element(
+        self,
+        by: DomCommands.SelectorType,
+        value: str,
+        timeout: int = 10,
+        raise_exc: bool = True,
+    ):
+        """
+        Waits for an element to be present in the DOM.
+
+        Args:
+            by (SelectorType): The type of selector to use.
+            value (str): The value of the selector.
+            timeout (int, optional): Time in seconds to wait for the element.
+            Defaults to 10.
+
+        Returns:
+            Element: The element found in the DOM.
+
+        Raises:
+            TimeoutError: If the element is not found within the timeout.
+        """
+        start_time = asyncio.get_event_loop().time()
+        while True:
+            try:
+                element = await self.find_element(by, value, raise_exc=False)
+                if element:
+                    return element
+            except exceptions.ElementNotFound:
+                pass
+
+            if asyncio.get_event_loop().time() - start_time > timeout:
+                if raise_exc:
+                    raise TimeoutError('Element not found')
+                return None
+
+            await asyncio.sleep(0.5)
+
+    async def find_element(
+        self, by: DomCommands.SelectorType, value: str, raise_exc: bool = True
+    ):
+        """
+        Finds an element on the current page using the specified selector.
+
+        Args:
+            by (SelectorType): The type of selector to use.
+            value (str): The value of the selector to use.
+
+        Returns:
+            dict: The response from the browser.
+
+        Raises:
+            ElementNotFound: If the element is not found and raise_exc is True.
+        """
+        if hasattr(self, '_object_id'):
+            command = DomCommands.find_element(by, value, self._object_id)
+        else:
+            command = DomCommands.find_element(by, value)
+
+        response = await self._execute_command(command)
+
+        if not response.get('result', {}).get('result', {}).get('objectId'):
+            if raise_exc:
+                raise exceptions.ElementNotFound('Element not found')
+            return None
+
+        object_id = response['result']['result']['objectId']
+        node_description = await self._describe_node(object_id=object_id)
+        attributes = node_description.get('attributes', [])
+
+        tag_name = node_description.get('nodeName', '').lower()
+        attributes.extend(['tag_name', tag_name])
+
+        return create_web_element(
+            object_id, self._connection_handler, by, value, attributes
+        )
+
+    async def find_elements(
+        self, by: DomCommands.SelectorType, value: str, raise_exc: bool = True
+    ):
+        """
+        Finds all elements on the current page using the specified selector.
+
+        Args:
+            by (SelectorType): The type of selector to use.
+            value (str): The value of the selector to use.
+
+        Returns:
+            list: A list of elements found on the page.
+
+        Raises:
+            ElementNotFound: If no elements are found and raise_exc is True.
+        """
+        if hasattr(self, '_object_id'):
+            command = DomCommands.find_elements(by, value, self._object_id)
+        else:
+            command = DomCommands.find_elements(by, value)
+
+        response = await self._execute_command(command)
+
+        if not response.get('result', {}).get('result', {}).get('objectId'):
+            if raise_exc:
+                raise exceptions.ElementNotFound('Element not found')
+            return []
+
+        object_id = response['result']['result']['objectId']
+        query_response = await self._execute_command(
+            RuntimeCommands.get_properties(object_id=object_id)
+        )
+        response = []
+        for query in query_response['result']['result']:
+            query_value = query.get('value', {})
+            if query_value and query_value['type'] == 'object':
+                response.append(query_value['objectId'])
+
+        elements = []
+        for object_id in response:
+            try:
+                node_description = await self._describe_node(
+                    object_id=object_id
+                )
+            except KeyError:
+                continue
+
+            attributes = node_description.get('attributes', [])
+            tag_name = node_description.get('nodeName', '').lower()
+            attributes.extend(['tag_name', tag_name])
+
+            elements.append(
+                create_web_element(
+                    object_id, self._connection_handler, by, value, attributes
+                )
+            )
+        return elements
+
+    async def _describe_node(self, object_id: str = '') -> dict:
+        """
+        Provides a detailed description of a specific node within the DOM.
+
+        Args:
+            node_id (int): The unique ID of the node to describe.
+
+        Returns:
+            dict: A dictionary containing the detailed description of the node.
+        """
+        response = await self._execute_command(
+            DomCommands.describe_node(object_id=object_id)
+        )
+        return response['result']['node']
+
+    async def _execute_command(self, command: dict) -> dict:
+        """
+        Executes a command on the page.
+
+        Args:
+            command (dict): The command to execute.
+
+        Returns:
+            dict: The result of the command execution.
+        """
+        return await self._connection_handler.execute_command(
+            command, timeout=60
+        )

pydoll/utils.py

@@ -0,0 +1,50 @@
+import base64
+import logging
+
+import aiohttp
+
+from pydoll import exceptions
+
+logger = logging.getLogger(__name__)
+
+
+def decode_image_to_bytes(image: str) -> bytes:
+    """
+    Decodes a base64 image string to bytes.
+
+    Args:
+        image (str): The base64 image string to decode.
+
+    Returns:
+        bytes: The decoded image as bytes.
+    """
+    return base64.b64decode(image)
+
+
+async def get_browser_ws_address(port: int) -> str:
+    """
+    Fetches the WebSocket address for the browser instance.
+
+    Returns:
+        str: The WebSocket address for the browser.
+
+    Raises:
+        ValueError: If the address cannot be fetched due to network errors
+        or missing data.
+    """
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                f'http://localhost:{port}/json/version'
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+                return data['webSocketDebuggerUrl']
+
+    except aiohttp.ClientError as e:
+        raise exceptions.NetworkError(f'Failed to get browser ws address: {e}')
+
+    except KeyError as e:
+        raise exceptions.InvalidResponse(
+            f'Failed to get browser ws address: {e}'
+        )

pydoll_python-1.2.0.dist-info/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pydoll_python-1.2.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.1
+Name: pydoll-python
+Version: 1.2.0
+Summary: 
+Author: Thalison Fernandes
+Author-email: thalissfernandes99@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: aiofiles (>=23.2.1,<24.0.0)
+Requires-Dist: aiohttp (>=3.9.5,<4.0.0)
+Requires-Dist: bs4 (>=0.0.2,<0.0.3)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: websockets (>=13.1,<14.0)
+Description-Content-Type: text/markdown
+
+
+<p align="center">
+    <h1>🚀 Pydoll: Async Web Automation in Python!</h1>
+</p>
+<br>
+<p align="center">
+    <img src="https://github.com/user-attachments/assets/c4615101-d932-4e79-8a08-f50fbc686e3b" alt="Alt text" />
+</p>
+
+<p align="center">
+    <img src="https://codecov.io/github/thalissonvs/pydoll/graph/badge.svg?token=40I938OGM9"/> 
+    <img src="https://github.com/thalissonvs/pydoll/actions/workflows/tests.yml/badge.svg" alt="Tests">
+    <img src="https://github.com/thalissonvs/pydoll/actions/workflows/ruff-ci.yml/badge.svg" alt="Ruff CI">
+    <img src="https://github.com/thalissonvs/pydoll/actions/workflows/release.yml/badge.svg" alt="Release">
+    <img src="https://tokei.rs/b1/github/thalissonvs/pydoll" alt="Total lines">
+    <img src="https://tokei.rs/b1/github/thalissonvs/pydoll?category=files" alt="Files">
+    <img src="https://tokei.rs/b1/github/thalissonvs/pydoll?category=comments" alt="Comments">
+    <img src="https://img.shields.io/github/issues/thalissonvs/pydoll?label=Issues" alt="GitHub issues">
+    <img src="https://img.shields.io/github/issues-closed/thalissonvs/pydoll?label=Closed issues" alt="GitHub closed issues">
+    <img src="https://img.shields.io/github/issues/thalissonvs/pydoll/bug?label=Bugs&color=red" alt="GitHub bug issues">
+    <img src="https://img.shields.io/github/issues/thalissonvs/pydoll/enhancement?label=Enhancements&color=purple" alt="GitHub enhancement issues">
+</p>
+
+
+Pydoll is an innovative Python library that's redefining Chromium browser automation! Unlike other solutions, Pydoll **completely eliminates the need for webdrivers**, providing a much more fluid and reliable automation experience.
+
+## ⭐ Extraordinary Features
+
+- **Zero Webdrivers!** Say goodbye to webdriver compatibility and configuration headaches
+- **Native Captcha Bypass!** Naturally passes through Cloudflare Turnstile and reCAPTCHA v3
+- **Performance** thanks to native asynchronous programming
+- **Realistic Interactions** that simulate human behavior
+- **Advanced Event System** for complex and reactive automations
+
+## Table of Contents
+
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Core Components](#-core-components)
+  - [Browser Interface](#browser-interface)
+  - [Page Interface](#page-interface)
+  - [WebElement Interface](#webelement-interface)
+- [Advanced Features](#-advanced-features)
+  - [Event System](#event-system)
+  - [Concurrent Scraping](#concurrent-scraping)
+  - [Proxy Configuration](#proxy-configuration)
+
+## 🔥 Installation
+
+```bash
+pip install git+https://github.com/thalissonvs/pydoll.git
+```
+
+## ⚡ Quick Start
+
+See how simple it is to get started - no webdriver configuration needed!
+
+```python
+import asyncio
+from pydoll.browser.chrome import Chrome
+from pydoll.constants import By
+
+async def main():
+    # Start the browser with no additional webdriver configuration!
+    async with Chrome() as browser:
+        await browser.start()
+        page = await browser.get_page()
+        
+        # Navigate through captcha-protected sites without worry
+        await page.go_to('https://example-with-cloudflare.com')
+        button = await page.find_element(By.CSS_SELECTOR, 'button')
+        await button.click()
+
+asyncio.run(main())
+```
+
+## 🎯 Core Components
+
+### Browser Interface
+
+Powerful interface for global browser control:
+
+```python
+async def browser_examples():
+    async with Chrome() as browser:
+        await browser.start()
+        # Control multiple pages with incredible ease
+        pages = [await browser.get_page() for _ in range(3)]
+        
+        # Advanced settings with a simple command
+        await browser.set_window_maximized()
+```
+
+### Page Interface
+
+Individual page control with surgical precision:
+
+```python
+async def page_examples():
+    page = await browser.get_page()
+    
+    # Smooth navigation, even on protected sites
+    await page.go_to('https://site-with-recaptcha.com')
+    
+    # Capture perfect screenshots
+    await page.get_screenshot('/screenshots/evidence.png')
+```
+
+### WebElement Interface
+
+Interact with elements like a real user:
+
+```python
+async def element_examples():
+    # Natural and precise interactions
+    input_field = await page.find_element(By.CSS_SELECTOR, 'input')
+    await input_field.type_keys('Hello World')  # Realistic typing!
+    
+    # Intuitive chained operations
+    dropdown = await page.find_element(By.CSS_SELECTOR, 'select')
+    await dropdown.select_option('value')
+
+    # Realistic clicks with offset
+    button = await page.find_element(By.CSS_SELECTOR, 'button')
+    await button.click(x_offset=5, y_offset=10)
+```
+
+## 🚀 Advanced Features
+
+### Event System
+
+Powerful event system for intelligent automation:
+
+```python
+from pydoll.events.page import PageEvents
+
+async def event_example():
+    await page.enable_page_events()
+    # React to events in real-time!
+    await page.on(PageEvents.PAGE_LOADED, 
+                  lambda e: print('Page loaded successfully!'))
+```
+
+### Concurrent Scraping
+
+Scrape multiple pages simultaneously with extraordinary performance:
+
+```python
+async def concurrent_example():
+    pages = [await browser.get_page() for _ in range(10)]
+    # Parallel scraping with intelligent resource management
+    results = await asyncio.gather(
+        *(scrape_page(page) for page in pages)
+    )
+    # Just declare the scrape_page method and see the magic happens!
+```
+
+### Proxy Configuration
+
+Robust proxy support, including authentication:
+
+```python
+async def proxy_example():
+    options = Options()
+    # Private or public proxies, you choose!
+    options.add_argument('--proxy-server=username:password@ip:port')
+    
+    async with Chrome(options=options) as browser:
+        await browser.start()
+```
+
+
+For exploring all available methods and additional features, check out:
+- Browser interface: [pydoll/browser/base.py](./pydoll/browser/base.py)
+- Page interface: [pydoll/browser/page.py](./pydoll/browser/page.py)
+- WebElement interface: [pydoll/element.py](./pydoll/element.py)
+- Chrome options: [Chromium Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches/)
+
+## 🎉 Start Now!
+
+Feel free to use, open issues and contributing!
+