Pydoll

https://pydoll.tech/docs/
Admin
Pydoll is an asynchronous web automation library for Python that eliminates the need for webdrivers...
Tokens:321,070
Snippets:3,601
Trust Score:7.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Mypy Installation and Usage

Source: https://pydoll.tech/docs/deep-dive/fundamentals/typing-system

Shows how to install and run the mypy static type checker. Includes an example of mypy's output when it finds type errors.

```bash
pip install mypy
mypy your_script.py
```

--------------------------------

### Pydoll Installation Simplicity

Source: https://pydoll.tech/docs/features/core-concepts

Demonstrates the straightforward installation process for Pydoll, contrasting it with the more involved setup often required for Selenium.

```bash
# Selenium setup:
$ pip install selenium
$ brew install chromedriver  # or download, chmod +x, add to PATH...
$ chromedriver --version     # does it match your Chrome?

# Pydoll setup:
$ pip install pydoll-python  # That's it!
```

--------------------------------

### start(headless=False)

Source: https://pydoll.tech/docs/api/browser/edge

Starts the browser process and establishes a CDP connection.

```APIDOC
## start(headless=False)

### Description
Start browser process and establish CDP connection.

### Parameters
- **headless** (bool) - Optional - Deprecated. Use options.headless = True instead.

### Returns
- **Tab** - Initial tab for interaction.

### Raises
- **FailedToStartBrowser** - If the browser fails to start or connect.
```

--------------------------------

### Basic Linux Chrome Server Setup

Source: https://pydoll.tech/docs/features/advanced/remote-connections

Start Chrome with remote debugging enabled on port 9222, accessible only from localhost. Ensure Chrome is installed and executable.

```bash
# Basic setup - only accessible from localhost
google-chrome \
  --remote-debugging-port=9222 \
  --headless=new \
  --no-sandbox \
  --disable-dev-shm-usage \
  --user-data-dir=/tmp/chrome-profile
```

--------------------------------

### Set Installation and Country Metadata

Source: https://pydoll.tech/docs/features/configuration/browser-preferences

Configure installation-specific metadata such as country ID, default apps installation state, enterprise profile GUID, and default search provider. Use country IDs to match target regions for realistic fingerprinting.

```python
import uuid
from pydoll.browser.options import ChromiumOptions

options = ChromiumOptions()
options.browser_preferences = {
    # Country ID at install (affects default settings and locale)
    'countryid_at_install': 16978,          # Varies by country (e.g., 16978 for Brazil)

    # Default apps installation state
    'default_apps_install_state': 3,        # 0=not installed, 1=installed, 3=migrated

    # Enterprise profile GUID (for managed browsers)
    'enterprise_profile_guid': str(uuid.uuid4()),

    # Default search provider
    'default_search_provider': {
        'guid': ''                          # Empty for default (Google)
    }
}

```

--------------------------------

### Start Browser and Interact with Initial Tab

Source: https://pydoll.tech/docs/features/browser-management/tabs

Shows how to start a browser instance and interact with the automatically created initial tab, including navigating to a URL and executing JavaScript to get the page title.

```python
import asyncio
from pydoll.browser.chromium import Chrome

async def start_browser():
    async with Chrome() as browser:
        # Initial tab is created automatically
        tab = await browser.start()

        print(f"Tab created with target ID: {tab._target_id}")
        await tab.go_to('https://example.com')

        title = await tab.execute_script('return document.title')
        print(f"Page title: {title}")

asyncio.run(start_browser())

```

--------------------------------

### Get Installability Errors

Source: https://pydoll.tech/docs/api/commands/page

Creates a command to retrieve installability errors.

```python
get_installability_errors()
```

--------------------------------

### Start HTTP and SOCKS5 Proxies

Source: https://pydoll.tech/docs/deep-dive/network/build-proxy

Initializes and starts both an HTTP and a SOCKS5 proxy concurrently. Ensure asyncio is imported.

```python
async def main():
    http_proxy = HTTPProxy(
        port=8080, username='user', password='pass'
    )
    socks5_proxy = SOCKS5Proxy(
        port=1080, username='user', password='pass'
    )
    await asyncio.gather(http_proxy.start(), socks5_proxy.start())
```

--------------------------------

### Start Browser Process and Connection

Source: https://pydoll.tech/docs/deep-dive/architecture/browser-domain

The start() method orchestrates the browser launch, including resolving the binary location, setting up the user data directory, starting the browser process, verifying the CDP endpoint, configuring proxy authentication, and creating the initial Tab object. It returns the first valid tab for ergonomic convenience.

```python
async def start(self, headless: bool = False) -> Tab:
    # 1. Resolve binary location
    binary_location = self.options.binary_location or self._get_default_binary_location()

    # 2. Setup user data directory (temp or persistent)
    self._setup_user_dir()

    # 3. Extract proxy credentials (if private proxy)
    proxy_config = self._proxy_manager.get_proxy_credentials()

    # 4. Start browser process with arguments
    self._browser_process_manager.start_browser_process(
        binary_location, self._connection_port, self.options.arguments
    )

    # 5. Verify CDP endpoint is responsive
    await self._verify_browser_running()

    # 6. Configure proxy authentication (via Fetch domain)
    await self._configure_proxy(proxy_config[0], proxy_config[1])

    # 7. Get first valid target and create Tab
    valid_tab_id = await self._get_valid_tab_id(await self.get_targets())
    tab = Tab(self, target_id=valid_tab_id, connection_port=self._connection_port)
    self._tabs_opened[valid_tab_id] = tab

    return tab

```

--------------------------------

### Quick Start: Configure Chromium Browser Options

Source: https://pydoll.tech/docs/features/configuration/browser-options

Set up basic browser options like headless mode, start timeout, page load state, and add command-line arguments.

```python
import asyncio
from pydoll.browser.chromium import Chrome
from pydoll.browser.options import ChromiumOptions
from pydoll.constants import PageLoadState

async def main():
    # Create and configure options
    options = ChromiumOptions()

    # Basic configuration
    options.headless = True
    options.start_timeout = 15
    options.page_load_state = PageLoadState.INTERACTIVE

    # Add command-line arguments
    options.add_argument('--disable-gpu')
    options.add_argument('--window-size=1920,1080')

    # Helper methods for common settings
    options.block_notifications = True
    options.block_popups = True
    options.set_default_download_directory('/tmp/downloads')

    # Use the configured options
    async with Chrome(options=options) as browser:
        tab = await browser.start()
        await tab.go_to('https://example.com')

asyncio.run(main())
```

--------------------------------

### Initialize and Start Async HTTP Proxy

Source: https://pydoll.tech/docs/deep-dive/network/build-proxy

Sets up and starts the asynchronous HTTP proxy server, binding to a specified host and port. It logs the listening address and runs indefinitely.

```python
import asyncio
import base64
import contextlib
import logging
from urllib.parse import urlparse

logger = logging.getLogger(__name__)


class HTTPProxy:
    """Async HTTP/HTTPS proxy with optional Basic authentication."""

    def __init__(self, host='0.0.0.0', port=8080, username=None, password=None):
        self.host = host
        self.port = port
        self.username = username
        self.password = password

    async def start(self):
        server = await asyncio.start_server(
            self._handle_client, self.host, self.port
        )
        logger.info(f'HTTP proxy listening on {self.host}:{self.port}')
        async with server:
            await server.serve_forever()
```

--------------------------------

### Browser Process Management - Start

Source: https://pydoll.tech/docs/deep-dive/architecture/browser-domain

Starts the browser process by constructing command-line arguments, spawning a subprocess, and monitoring its startup.

```python
class BrowserProcessManager:
    def start_browser_process(self, binary, port, arguments):
        """
        1. Constructs command-line with binary path + arguments
        2. Spawns subprocess with proper stdio handling
        3. Monitors process startup
        4. Stores process handle for later termination
        """


```

--------------------------------

### Start Screencast

Source: https://pydoll.tech/docs/api/commands/page

Creates a command to initiate a screencast with specified format and quality settings.

```python
start_screencast(format, quality=None, max_width=None, max_height=None, every_nth_frame=None)
```

--------------------------------

### Navigate and Request Example

Source: https://pydoll.tech/docs/deep-dive/architecture/browser-requests-architecture

This example demonstrates a workaround for CORS issues by first navigating to the target domain to establish a same-origin context before making the request.

```python
await tab.go_to('https://different-domain.com')
response = await tab.request.get('https://different-domain.com/api')

```

--------------------------------

### Fetch API Request Example

Source: https://pydoll.tech/docs/deep-dive/architecture/browser-requests-architecture

A simplified JavaScript example demonstrating a Fetch API GET request. It shows how custom headers can be sent and mentions that the browser automatically adds cookies, authorization, and standard headers.

```javascript
// Simplified representation
(async () => {
    const response = await fetch(url, {
        method: 'GET',
        headers: {'X-Custom': 'value'},
        // Browser automatically adds:
        // - Cookie header
        // - Authorization if set
        // - Standard headers (User-Agent, Accept, etc.)
    });

    return {
        status: response.status,
        url: response.url,  // Final URL after redirects
        text: await response.text(),
        content: new Uint8Array(await response.arrayBuffer()),
        json: response.headers.get('Content-Type')?.includes('application/json')
            ? await response.clone().json()
            : null
    };
})();

```

--------------------------------

### Start Browser Process

Source: https://pydoll.tech/docs/api/browser/edge

Launches the browser process and establishes a CDP connection.

```python
start(headless=False)
```

--------------------------------

### Troubleshoot Browser Startup Issues

Source: https://pydoll.tech/docs/features/configuration/browser-options

Adjust browser options to resolve issues where the browser fails to start. This includes increasing the start timeout and specifying the binary location.

```python
# Increase timeout
options.start_timeout = 30

# Check binary location
options.binary_location = '/path/to/chrome'

# Docker/CI issues
options.add_argument('--no-sandbox')
options.add_argument('--disable-dev-shm-usage')

```

--------------------------------

### Quick Stealth Setup with Browser Preferences

Source: https://pydoll.tech/docs/features/configuration/browser-preferences

Configure browser preferences to simulate a used browser profile and enable common features for anti-detection. This setup fakes usage history, sets a realistic homepage, and enables features like Safe Browsing and autofill.

```python
import asyncio
import time
from pydoll.browser.chromium import Chrome
from pydoll.browser.options import ChromiumOptions

async def quick_stealth():
    options = ChromiumOptions()

    # Simulate a 60-day-old browser
    fake_timestamp = int(time.time()) - (60 * 24 * 60 * 60)

    options.browser_preferences = {
        # Fake usage history
        'profile': {
            'last_engagement_time': fake_timestamp,
            'exited_cleanly': True,
            'exit_type': 'Normal'
        },

        # Realistic homepage
        'homepage': 'https://www.google.com',
        'session': {
            'restore_on_startup': 1,
            'startup_urls': ['https://www.google.com']
        },

        # Enable features real users have
        'enable_do_not_track': False,  # Most users don't enable this
        'safebrowsing': {'enabled': True},
        'autofill': {'enabled': True},
        'search': {'suggest_enabled': True},
        'dns_prefetching': {'enabled': True}
    }

    async with Chrome(options=options) as browser:
        tab = await browser.start()
        await tab.go_to('https://bot-detection-site.com')
        print("Stealth mode activated!")

asyncio.run(quick_stealth())

```

--------------------------------

### Pydoll vs. Selenium Setup Comparison

Source: https://pydoll.tech/docs/features/core-concepts

Illustrates the simplified setup for Pydoll compared to Selenium, highlighting the absence of version management issues for browser drivers.

```python
# With Selenium, you might see:
# SessionNotCreatedException: This version of ChromeDriver only supports Chrome version 120

# With Pydoll, you just need Chrome installed:
async with Chrome() as browser:
    tab = await browser.start()  # Works with any Chrome version
```

--------------------------------

### enable

Source: https://pydoll.tech/docs/api/commands/fetch

Creates a command to start intercepting fetch requests.

```APIDOC
## enable(handle_auth_requests, url_pattern='*', resource_type=None, request_stage=None)

### Description
Creates a command to enable fetch interception. This allows the browser to start intercepting fetch requests based on the provided criteria.

### Parameters
- **handle_auth_requests** (bool) - Required - Indicates if authentication requests should be handled.
- **url_pattern** (str) - Optional - Pattern to match URLs for interception (default: '*').
- **resource_type** (Optional[ResourceType]) - Optional - The type of resource to intercept.
- **request_stage** (Optional[RequestStage]) - Optional - The stage of the request to intercept.

### Returns
- **EnableCommand** - A command for enabling fetch interception.
```

--------------------------------

### Testing Remote Chrome Server Setup

Source: https://pydoll.tech/docs/features/advanced/remote-connections

A collection of shell commands to verify Chrome server setup, network accessibility, and WebSocket endpoint.

```bash
# 1. Check if Chrome is running
ps aux | grep chrome

# 2. Check if port is listening
netstat -tulpn | grep 9222
# Or
ss -tulpn | grep 9222

# 3. Test local access
curl http://localhost:9222/json/version

# 4. Test remote access (from client machine)
curl http://SERVER_IP:9222/json/version

# 5. Check WebSocket URL
curl http://SERVER_IP:9222/json/version | jq -r '.webSocketDebuggerUrl'

# 6. List all available targets (tabs/pages)
curl http://SERVER_IP:9222/json/list

```

--------------------------------

### TCP Handshake Example Values

Source: https://pydoll.tech/docs/deep-dive/network/network-fundamentals

Illustrative examples of TCP handshake parameters for different operating systems. Actual values may vary.

```text
Windows 10/11 (modern builds):
    Window Size: 65535
    MSS: 1460
    Options: MSS, NOP, WS, NOP, NOP, SACK_PERM
    TTL: 128

Linux (kernel 5.x+, Ubuntu 20.04+):
    Window Size: 29200
    MSS: 1460
    Options: MSS, SACK_PERM, TS, NOP, WS
    TTL: 64

macOS (Monterey+):
    Window Size: 65535
    TTL: 64

```

--------------------------------

### Install Pydoll from GitHub

Source: https://pydoll.tech/docs

Install the latest development version of Pydoll directly from its GitHub repository.

```bash
$ pip install git+https://github.com/autoscrape-labs/pydoll.git
```

--------------------------------

### Comprehensive File Upload Example

Source: https://pydoll.tech/docs/features/automation/file-operations

This example demonstrates various file upload scenarios: direct input for single files, using file choosers for single documents, and handling multiple files via the file chooser. It covers scenarios with visible input elements and custom upload buttons.

```python
import asyncio
from pathlib import Path
from pydoll.browser.chromium import Chrome

async def comprehensive_upload_example():
    async with Chrome() as browser:
        tab = await browser.start()
        await tab.go_to('https://example.com/upload-form')

        # Scenario 1: Direct input for profile picture (single file)
        avatar_input = await tab.find(id='avatar-upload')
        avatar_path = Path.home() / 'Pictures' / 'profile.jpg'
        await avatar_input.set_input_files(avatar_path)

        # Wait a bit for preview to load
        await asyncio.sleep(1)

        # Scenario 2: File chooser for document upload
        document_path = Path.cwd() / 'documents' / 'resume.pdf'
        async with tab.expect_file_chooser(files=document_path):
            # Custom styled button that triggers file chooser
            upload_btn = await tab.find(class_name='btn-upload-document')
            await upload_btn.click()

        # Wait for upload confirmation
        await asyncio.sleep(2)

        # Scenario 3: Multiple files via file chooser
        certs_dir = Path('certs')
        certificates = [
            certs_dir / 'certificate1.pdf',
            certs_dir / 'certificate2.pdf',
            certs_dir / 'certificate3.pdf'
        ]
        async with tab.expect_file_chooser(files=certificates):
            add_certs_btn = await tab.find(text='Add Certificates')
            await add_certs_btn.click()

        # Submit the complete form
        submit_button = await tab.find(type='submit')
        await submit_button.click()

        # Wait for success message
        success_msg = await tab.find(class_name='success-message', timeout=10)
        message_text = await success_msg.text
        print(f"Upload result: {message_text}")

asyncio.run(comprehensive_upload_example())

```

--------------------------------

### ShadowRoot Usage Example

Source: https://pydoll.tech/docs/api/elements/shadow_root

Demonstrates how to retrieve a shadow root from a host element and query for internal elements.

```python
shadow_host = await tab.find(id='my-component') shadow_root = await shadow_host.get_shadow_root() button = await shadow_root.query('#internal-button') await button.click()
```

--------------------------------

### Query Method Usage

Source: https://pydoll.tech/docs/api/elements/mixins

Basic usage example for the query method.

```python
query(expression, timeout=0, find_all=False, raise_exc=True)
```

--------------------------------

### Advanced Request Configurations

Source: https://pydoll.tech/docs/api/browser/requests

Examples for sending custom parameters, uploading files, and submitting form data.

```python
# Request with custom headers and parameters
response = await tab.request.get("/search", 
    params={"q": "python", "limit": 10},
    headers={
        "User-Agent": "Custom Bot 1.0",
        "Accept": "application/json"
    }
)

# File upload simulation
response = await tab.request.post("/upload",
    data={"description": "Test file"},
    files={"file": ("test.txt", "file content", "text/plain")}
)

# Form data submission
response = await tab.request.post("/login",
    data={"username": "user", "password": "pass"}
)
```

--------------------------------

### Record Network Traffic and Save as HAR

Source: https://pydoll.tech/docs/features/network/network-recording

Quick start example to record all network traffic during a page navigation and save it to a HAR file. Ensure you have asyncio and Chrome browser setup.

```python
import asyncio
from pydoll.browser.chromium import Chrome

async def record_traffic():
    async with Chrome() as browser:
        tab = await browser.start()

        async with tab.request.record() as capture:
            await tab.go_to('https://example.com')

        # Save the capture as a HAR file
        capture.save('flow.har')
        print(f'Captured {len(capture.entries)} requests')

asyncio.run(record_traffic())
```

--------------------------------

### Managing Per-Context Configurations

Source: https://pydoll.tech/docs/features/browser-management/contexts

This example demonstrates how to create and manage multiple browser contexts, each with specific configurations like proxy servers and user agents. It shows the lifecycle of creating contexts, using them, and cleaning them up.

```python
import asyncio
from pydoll.browser.chromium import Chrome

async def context_config_manager():
    async with Chrome() as browser:
        await browser.start()

        # Define configurations for different scenarios
        configs = {
            'us_user': {
                'proxy': 'http://us-proxy.example.com:8080',
                'user_agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
            },
            'eu_user': {
                'proxy': 'http://eu-proxy.example.com:8080',
                'user_agent': 'Mozilla/5.0 (X11; Linux x86_64)'
            },
            'mobile_user': {
                'proxy': None,
                'user_agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)'
            }
        }

        contexts = {}

        # Create context for each configuration
        for name, config in configs.items():
            if config['proxy']:
                context_id = await browser.create_browser_context(
                    proxy_server=config['proxy']
                )
            else:
                context_id = await browser.create_browser_context()

            # Create tab and set user agent
            tab = await browser.new_tab(browser_context_id=context_id)
            # Note: User agent would be set via CDP or options, simplified here

            contexts[name] = {'context_id': context_id, 'tab': tab}

        # Use different contexts for different scenarios
        for name, data in contexts.items():
            tab = data['tab']
            await tab.go_to('https://httpbin.org/headers')
            await asyncio.sleep(2)
            print(f"\n{name} configuration active")

        # Cleanup
        for data in contexts.values():
            await data['tab'].close()
            await browser.delete_browser_context(data['context_id'])

asyncio.run(context_config_manager())

```

--------------------------------

### Enable network monitoring

Source: https://pydoll.tech/docs/api/commands/network

Starts network monitoring with optional buffer size configurations for data capture.

```python
enable(max_total_buffer_size=None, max_resource_buffer_size=None, max_post_data_size=None)
```

--------------------------------

### Quick Start: Keyboard API Usage

Source: https://pydoll.tech/docs/features/automation/keyboard-control

Demonstrates basic keyboard operations including pressing a key, executing a hotkey, and manual key down/up sequences with modifiers.

```python
from pydoll.browser.chromium import Chrome
from pydoll.constants import Key

async with Chrome() as browser:
    tab = await browser.start()
    await tab.go_to('https://example.com')

    # Press and release a key
    await tab.keyboard.press(Key.ENTER)

    # Execute a hotkey combination
    await tab.keyboard.hotkey(Key.CONTROL, Key.S)  # Ctrl+S

    # Manual control
    await tab.keyboard.down(Key.SHIFT)
    await tab.keyboard.press(Key.ARROWRIGHT)
    await tab.keyboard.up(Key.SHIFT)
```

--------------------------------

### Dockerfile for Chrome with Remote Debugging

Source: https://pydoll.tech/docs/features/advanced/remote-connections

Installs Google Chrome and exposes the remote debugging port. Ensure Chrome is started with the correct flags for remote access.

```dockerfile
# Install Chrome
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    ca-certificates \
    && wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list \
    && apt-get update \
    && apt-get install -y google-chrome-stable \
    && rm -rf /var/lib/apt/lists/*

# Expose debugging port
EXPOSE 9222

# Start Chrome with remote debugging
CMD ["google-chrome", \
     "--remote-debugging-port=9222", \
     "--remote-debugging-address=0.0.0.0", \
     "--headless=new", \
     "--no-sandbox", \
     "--disable-dev-shm-usage", \
     "--disable-gpu", \
     "--user-data-dir=/tmp/chrome-profile"]

```

--------------------------------

### Basic XPath Path Expressions

Source: https://pydoll.tech/docs/deep-dive/guides/selectors-guide

Use absolute or relative paths to select elements. `//` selects from anywhere, while `/` starts from the root. Use `find_all=True` to get all matches.

```python
# Absolute path (from root)
await tab.query("/html/body/div")                 # First div at exact path
```

```python
# Relative path (from anywhere)
await tab.query("//div")                          # First <div> element
```

```python
await tab.query("//div", find_all=True)           # All <div> elements
```

```python
await tab.query("//div/p")                        # First <p> inside any <div>
```

```python
await tab.query("//div/p", find_all=True)         # All <p> inside any <div>
```

```python
# Current node
await tab.query("./div")                          # First <div> relative to current
```

```python
# Parent node
await tab.query("..")                             # Parent of current node
```

--------------------------------

### Launching Google Chrome with Pydoll

Source: https://pydoll.tech/docs/features/core-concepts

Basic example of launching Google Chrome using Pydoll's unified API. Ensure Chrome is installed and accessible in your environment.

```python
from pydoll.browser.chromium import Chrome

async with Chrome() as browser:
    tab = await browser.start()

```

--------------------------------

### Initialize Options

Source: https://pydoll.tech/docs/api/browser/edge

Retrieves the configuration options for the browser instance.

```python
options = options_manager.initialize_options()
```

--------------------------------

### CDP DOM Domain: Get Frame Owner (JSON)

Source: https://pydoll.tech/docs/deep-dive/fundamentals/iframes-and-contexts

Example JSON response from the DOM.getFrameOwner() CDP command, returning the backendNodeId of the iframe element that hosts a given frame.

```json
{
  "backendNodeId": 456
}

```

--------------------------------

### Start Maximized

Source: https://pydoll.tech/docs/features/configuration/browser-options

Open the browser window in a maximized state. Ideal for UI testing and full-screen captures.

```python
options.add_argument('--start-maximized')
```

--------------------------------

### CDP Page Domain: Get Frame Tree (JSON)

Source: https://pydoll.tech/docs/deep-dive/fundamentals/iframes-and-contexts

Example JSON response from the Page.getFrameTree() CDP command, illustrating the hierarchical structure of frames within a page, including parent-child relationships.

```json
{
  "frameTree": {
    "frame": {
      "id": "main-frame-id",
      "url": "https://example.com",
      "securityOrigin": "https://example.com",
      "mimeType": "text/html"
    },
    "childFrames": [
      {
        "frame": {
          "id": "child-frame-id",
          "parentId": "main-frame-id",
          "url": "https://widget.com/embed"
        }
      }
    ]
  }
}

```

--------------------------------

### Chrome(options=None, connection_port=None)

Source: https://pydoll.tech/docs/api/browser/chrome

Initialize a new Chrome browser instance.

```APIDOC
## Chrome Constructor

### Description
Initializes a Chrome browser instance for CDP automation.

### Parameters
- **options** (Optional[ChromiumOptions]) - Optional - Chrome configuration options.
- **connection_port** (Optional[int]) - Optional - CDP WebSocket port (random if None).
```

--------------------------------

### Create Basic and Proxied Browser Contexts

Source: https://pydoll.tech/docs/features/browser-management/contexts

Shows how to create a basic browser context, a context with a proxy server, and a context with an authenticated proxy. Use these for network isolation or specific routing needs.

```python
import asyncio
from pydoll.browser.chromium import Chrome

async def create_context_example():
    async with Chrome() as browser:
        await browser.start()

        # Create basic context
        context_id = await browser.create_browser_context()
        print(f"Created context: {context_id}")

        # Create context with proxy
        proxied_context = await browser.create_browser_context(
            proxy_server='http://proxy.example.com:8080',
            proxy_bypass_list='localhost,127.0.0.1'
        )
        print(f"Created proxied context: {proxied_context}")

        # Create context with authenticated proxy
        auth_context = await browser.create_browser_context(
            proxy_server='http://user:pass@proxy.example.com:8080'
        )
        print(f"Created auth context: {auth_context}")

asyncio.run(create_context_example())
```

--------------------------------

### Practical Example: Finding Product Cards and Details

Source: https://pydoll.tech/docs/features/element-finding

Demonstrates finding repeating elements like product cards and then searching within each card for specific details like title, price, and a button. This is useful for e-commerce sites or tables.

```python
import asyncio
from pydoll.browser.chromium import Chrome

async def practical_example():
    async with Chrome() as browser:
        tab = await browser.start()
        await tab.go_to('https://example.com/products')

        # Find all product cards on the page
        product_cards = await tab.find(class_name="product-card", find_all=True)

        for card in product_cards:
            # Within each card, find ALL descendants with these classes
            title = await card.find(class_name="product-title")
            price = await card.find(class_name="product-price")

            # Get the button that's anywhere inside this card
            buy_button = await card.find(tag_name="button", text="Buy Now")

            title_text = await title.text
            price_text = await price.text

            print(f"Product: {title_text}, Price: {price_text}")

            # Click buy button
            await buy_button.click()

asyncio.run(practical_example())

```

--------------------------------

### Start Event Worker

Source: https://pydoll.tech/docs/api/connection/managers

Start the background worker for processing queued events.

```python
start()
```

--------------------------------

### GET - Retrieve Resource

Source: https://pydoll.tech/docs/features/network/http-requests

Retrieves a resource by sending a GET request to its endpoint.

```APIDOC
## GET /users

### Description
Retrieves a resource by sending a GET request to its endpoint.

### Method
GET

### Endpoint
`https://api.example.com/users`
```

--------------------------------

### Basic Browser Context Example

Source: https://pydoll.tech/docs/features/browser-management/contexts

Demonstrates creating and using isolated browser contexts. Use this to manage separate browsing sessions with distinct cookies and storage.

```python
import asyncio
from pydoll.browser.chromium import Chrome

async def basic_context_example():
    async with Chrome() as browser:
        # Start browser with initial tab in default context
        initial_tab = await browser.start()
        await initial_tab.go_to('https://example.com')

        # Create isolated context
        context_id = await browser.create_browser_context()

        # New tab in isolated context
        isolated_tab = await browser.new_tab('https://example.com', browser_context_id=context_id)

        # Both tabs are completely isolated - different cookies, storage, etc.
        await initial_tab.execute_script("localStorage.setItem('user', 'Alice')")
        await isolated_tab.execute_script("localStorage.setItem('user', 'Bob')")

        # Verify isolation
        user_default = await initial_tab.execute_script("return localStorage.getItem('user')")
        user_isolated = await isolated_tab.execute_script("return localStorage.getItem('user')")

        print(f"Default context: {user_default}")  # Alice
        print(f"Isolated context: {user_isolated}")  # Bob

asyncio.run(basic_context_example())

```

--------------------------------

### get(url, params=None, **kwargs)

Source: https://pydoll.tech/docs/api/browser/requests

Execute a GET request for retrieving data.

```APIDOC
## get(url, params=None, **kwargs)

### Description
Execute a GET request for retrieving data.

### Parameters
- **url** (str) - Required - Target URL to retrieve data from.
- **params** (Optional[dict[str, str]]) - Optional - Query parameters to append to URL. Default: None.
- **kwargs** (dict) - Optional - Additional fetch options. Default: {}.

### Returns
- **Response** - Response object with retrieved data.
```

--------------------------------

### Get Object Properties

Source: https://pydoll.tech/docs/api/commands/runtime

Creates a command to get properties of a JavaScript object.

```python
get_properties(object_id, own_properties=None, accessor_properties_only=None, generate_preview=None, non_indexed_properties_only=None)
```

--------------------------------

### Creating Browser Contexts

Source: https://pydoll.tech/docs/features/browser-management/contexts

Demonstrates how to create new browser contexts, including basic contexts, contexts with proxy settings, and contexts with authenticated proxies.

```APIDOC
## Creating Contexts

### Description
This section shows how to create new browser contexts. You can create a basic context, or configure it with proxy settings, including authentication.

### Method Signature
```python
async def create_browser_context(
    self,
    proxy_server: Optional[str] = None,
    proxy_bypass_list: Optional[str] = None,
    **kwargs
) -> str:
```

### Parameters
*   **proxy_server** (Optional[str]) - The proxy server URL, including authentication if needed (e.g., `http://user:pass@proxy.example.com:8080`).
*   **proxy_bypass_list** (Optional[str]) - A comma-separated list of hosts to bypass the proxy.
*   **kwargs** - Additional keyword arguments for context creation.

### Request Example
```python
import asyncio
from pydoll.browser.chromium import Chrome

async def create_context_example():
    async with Chrome() as browser:
        await browser.start()

        # Create basic context
        context_id = await browser.create_browser_context()
        print(f"Created context: {context_id}")

        # Create context with proxy
        proxied_context = await browser.create_browser_context(
            proxy_server='http://proxy.example.com:8080',
            proxy_bypass_list='localhost,127.0.0.1'
        )
        print(f"Created proxied context: {proxied_context}")

        # Create context with authenticated proxy
        auth_context = await browser.create_browser_context(
            proxy_server='http://user:pass@proxy.example.com:8080'
        )
        print(f"Created auth context: {auth_context}")

asyncio.run(create_context_example())
```
```

--------------------------------

### Simple GET Request

Source: https://pydoll.tech/docs/features/network/http-requests

Perform a basic GET request to retrieve data from a specified URL.

```python
# Simple GET
response = await tab.request.get('https://api.example.com/users')
```

--------------------------------

### Quick Start: Mouse Operations

Source: https://pydoll.tech/docs/features/automation/mouse-control

Demonstrates basic mouse operations including moving, clicking, right-clicking, double-clicking, and dragging. Requires importing Chrome and MouseButton.

```python
from pydoll.browser.chromium import Chrome
from pydoll.protocol.input.types import MouseButton

async with Chrome() as browser:
    tab = await browser.start()
    await tab.go_to('https://example.com')

    # Move cursor to position
    await tab.mouse.move(500, 300)

    # Click at position
    await tab.mouse.click(500, 300)

    # Right-click
    await tab.mouse.click(500, 300, button=MouseButton.RIGHT)

    # Double-click
    await tab.mouse.double_click(500, 300)

    # Drag from one position to another
    await tab.mouse.drag(100, 200, 500, 400)

```

--------------------------------

### GET Request with Query Parameters

Source: https://pydoll.tech/docs/features/network/http-requests

Make a GET request with URL-encoded query parameters to filter or specify search criteria.

```python
# GET with query parameters
response = await tab.request.get(
    'https://api.example.com/search',
    params={'q': 'python', 'limit': '10'}
)
```

--------------------------------

### Install Pydoll with pip

Source: https://pydoll.tech/docs

Install the latest stable version of Pydoll using pip. Ensure you have a virtual environment activated first.

```bash
pip install pydoll-python
```

--------------------------------

### Basic Browser Automation with Chrome

Source: https://pydoll.tech/docs/api

Demonstrates starting a Chrome browser instance, opening a tab, navigating to a URL, finding an element, and clicking it. Requires `async with` context management.

```python
from pydoll.browser.chromium import Chrome

async with Chrome() as browser:
    tab = await browser.start()
    await tab.go_to("https://example.com")
    element = await tab.find(id="my-element")
    await element.click()

```

--------------------------------

### Configure Browser Start Timeout

Source: https://pydoll.tech/docs/features/configuration/browser-options

Adjust the start_timeout property to control how long Pydoll waits for the browser to start and respond. The default is 10 seconds.

```python
options = ChromiumOptions()
options.start_timeout = 20  # seconds (default: 10)
```

--------------------------------

### Basic CSS Selector Examples

Source: https://pydoll.tech/docs/deep-dive/guides/selectors-guide

Demonstrates basic CSS selectors for element, ID, and class selection. Use `find_all=True` to retrieve all matching elements.

```python
await tab.query("#login-form")
await tab.query(".submit-button")
await tab.query("div.container > p.intro")
await tab.query("input[type='email'][required]")
await tab.query("ul.menu li:first-child")
```

```python
# Element selector
await tab.query("div")              # First <div> element
await tab.query("div", find_all=True)  # All <div> elements
await tab.query("button")           # First <button> element
```

```python
# ID selector
await tab.query("#username")        # Element with id="username"
```

```python
# Class selector
await tab.query(".submit-btn")      # First element with class="submit-btn"
await tab.query(".submit-btn", find_all=True)  # All elements with class
await tab.query(".btn.primary")     # First element with both classes
```

```python
# Universal selector
await tab.query("*", find_all=True) # All elements
```

--------------------------------

### Example User-Agent Client Hints Headers

Source: https://pydoll.tech/docs/deep-dive/fingerprinting/browser-fingerprinting

These headers provide structured information about the client's browser and operating system. They are sent by modern Chromium browsers.

```http
Sec-CH-UA: "Chromium";v="120", "Google Chrome";v="120", "Not:A-Brand";v="99"
Sec-CH-UA-Mobile: ?0
Sec-CH-UA-Platform: "Windows"
```

--------------------------------

### Basic XPath Selector Examples

Source: https://pydoll.tech/docs/deep-dive/guides/selectors-guide

Provides examples of common XPath selectors for text matching, parent traversal, and selecting siblings. XPath is powerful for complex DOM relationships.

```python
# Powerful XPath examples
await tab.query("//button[contains(text(), 'Submit')]")
await tab.query("//input[@name='email']/parent::div")
await tab.query("//td[text()='John']/following-sibling::td[2]")
await tab.query("//div[contains(@class, 'product') and @data-price > 100]")
```

--------------------------------

### Initialize Chrome Browser

Source: https://pydoll.tech/docs/api/browser/chrome

Create a new instance of the Chrome browser with optional configuration and connection settings.

```python
Chrome(options=None, connection_port=None)
```

--------------------------------

### Create page targets

Source: https://pydoll.tech/docs/api/commands/target

Initialize a new tab with specific dimensions and context settings.

```python
# Create a new tab
page_target = await create_target(
    connection,
    url="https://example.com",
    width=1920,
    height=1080,
    browser_context_id=None  # Default context
)
```

--------------------------------

### Advanced Request Interception Example

Source: https://pydoll.tech/docs/features/network/interception

This example shows how to block ads, mock API responses, and add authentication headers to requests. It requires enabling fetch events and defining a handler for paused requests.

```python
import asyncio
import base64
import json
from pydoll.browser.chromium import Chrome
from pydoll.protocol.fetch.events import FetchEvent, RequestPausedEvent
from pydoll.protocol.fetch.types import HeaderEntry
from pydoll.protocol.network.types import ErrorReason

async def advanced_interception():
    async with Chrome() as browser:
        tab = await browser.start()

        stats = {
            'blocked': 0,
            'mocked': 0,
            'modified': 0,
            'continued': 0
        }

        async def intelligent_handler(event: RequestPausedEvent):
            request_id = event['params']['requestId']
            url = event['params']['request']['url']
            resource_type = event['params']['resourceType']
            method = event['params']['request']['method']

            try:
                # Block ads and trackers
                if any(tracker in url for tracker in ['analytics', 'ads', 'tracking']):
                    stats['blocked'] += 1
                    print(f"🚫 Blocked tracker: {url[:50]}")
                    await tab.fail_request(request_id, ErrorReason.BLOCKED_BY_CLIENT)

                # Mock API responses
                elif '/api/config' in url:
                    stats['mocked'] += 1
                    mock_config = {'feature_x': True, 'debug_mode': False}
                    body = base64.b64encode(json.dumps(mock_config).encode()).decode()
                    headers: list[HeaderEntry] = [
                        {'name': 'Content-Type', 'value': 'application/json'},
                    ]
                    print(f"🎭 Mocked config API")
                    await tab.fulfill_request(
                        request_id, 200, headers, body, 'OK'
                    )

                # Add auth headers to API requests
                elif '/api/' in url and method == 'GET':
                    stats['modified'] += 1
                    headers: list[HeaderEntry] = [
                        {'name': 'Authorization', 'value': 'Bearer token-123'},
                    ]
                    print(f"✨ Added auth to: {url[:50]}")
                    await tab.continue_request(request_id, headers=headers)

                # Continue everything else normally
                else:
                    stats['continued'] += 1
                    await tab.continue_request(request_id)

            except Exception as e:
                print(f"⚠️  Error handling request: {e}")
                # Always continue on error to prevent hanging
                await tab.continue_request(request_id)

        # Enable interception
        await tab.enable_fetch_events()
        await tab.on(FetchEvent.REQUEST_PAUSED, intelligent_handler)

        # Navigate
        await tab.go_to('https://example.com')
        await asyncio.sleep(5)

        # Print stats
        print(f"\n📊 Interception Statistics:")
        print(f"   Blocked: {stats['blocked']}")
        print(f"   Mocked: {stats['mocked']}")
        print(f"   Modified: {stats['modified']}")
        print(f"   Continued: {stats['continued']}")
        print(f"   Total: {sum(stats.values())}")

        # Cleanup
        await tab.disable_fetch_events()

asyncio.run(advanced_interception())

```

--------------------------------

### Page.frameStartedNavigating

Source: https://pydoll.tech/docs/api/protocol/page

Fired when a navigation starts.

```APIDOC
## Page.frameStartedNavigating

### Description
Fired when a navigation starts for both renderer-initiated and browser-initiated navigations.

### Parameters
- **frameId** (FrameId) - ID of the frame that is being navigated.
- **url** (str) - The URL the navigation started with.
- **loaderId** (LoaderId) - Loader identifier.
- **navigationType** (str) - Type of navigation (e.g., reload, historySameDocument, etc.).
```

--------------------------------

### Ergonomic Tab Creation

Source: https://pydoll.tech/docs/deep-dive/architecture/browser-domain

Demonstrates a design choice where the start() method returns a Tab instance for convenience, simplifying single-tab automation scripts.

```python
# With start() returning Tab
tab = await browser.start()

# Without (pure design)
await browser.start()
tab = await browser.new_tab()
```

--------------------------------

### tab.request.get

Source: https://pydoll.tech/docs/api/browser/requests

Performs an HTTP GET request.

```APIDOC
## GET [url]

### Description
Performs an HTTP GET request to the specified URL.

### Parameters
#### Query Parameters
- **params** (dict) - Optional - Dictionary of query parameters to append to the URL.
- **headers** (dict) - Optional - Dictionary of custom HTTP headers.
```

--------------------------------

### Initialize Browser Managers

Source: https://pydoll.tech/docs/api/browser/managers

Instantiate ProxyManager and TempDirManager for advanced browser configuration.

```python
from pydoll.browser.managers.proxy_manager import ProxyManager
from pydoll.browser.managers.temp_dir_manager import TempDirManager

# Managers are used internally by browser classes
# Direct usage is for advanced scenarios only
proxy_manager = ProxyManager()
temp_manager = TempDirManager()
```

--------------------------------

### get_browser_contexts

Source: https://pydoll.tech/docs/api/commands/target

Generates a command to get all browser contexts.

```APIDOC
## get_browser_contexts()

### Description
Generates a command to get all browser contexts created with createBrowserContext.

### Returns
- **Command** (GetBrowserContextsCommand) - The CDP command to get all browser contexts.
```

--------------------------------

### Basic Browser Automation

Source: https://pydoll.tech/docs/api

Demonstrates the basic usage pattern for launching a browser, starting a tab, navigating to a URL, finding an element, and clicking it.

```APIDOC
## Basic Browser Automation

### Description
This example shows how to initialize a Chrome browser instance, open a new tab, navigate to a website, locate an element by its ID, and perform a click action.

### Method
```python
async with Chrome() as browser:
    tab = await browser.start()
    await tab.go_to("https://example.com")
    element = await tab.find(id="my-element")
    await element.click()
```
```

--------------------------------

### Nginx Reverse Proxy Setup Commands

Source: https://pydoll.tech/docs/features/advanced/remote-connections

Commands to create the password file, enable the Nginx site configuration, and reload Nginx to apply changes.

```bash
# Create password file
sudo htpasswd -c /etc/nginx/.htpasswd admin

# Enable site
sudo ln -s /etc/nginx/sites-available/chrome-remote /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

```

--------------------------------

### run_if_waiting_for_debugger()

Source: https://pydoll.tech/docs/api/commands/runtime

Resumes a target that was paused on start via waitForDebuggerOnStart.

```APIDOC
## run_if_waiting_for_debugger()

### Description
Resumes a target that was paused on start via waitForDebuggerOnStart. Used after auto-attaching to a worker/service worker target so the target can continue execution once overrides have been applied.

### Returns
- **RunIfWaitingForDebuggerCommand** - Command to resume a paused target.
```

--------------------------------

### Initialize Chromium Options

Source: https://pydoll.tech/docs/api/browser/managers

Validate and configure the ChromiumOptions instance.

```python
initialize_options()
```

--------------------------------

### Simulate Mouse and Keyboard Events

Source: https://pydoll.tech/docs/api/commands/input

Demonstrates how to manually dispatch mouse and keyboard events using the ConnectionHandler.

```python
from pydoll.commands.input_commands import dispatch_mouse_event, dispatch_key_event
from pydoll.connection.connection_handler import ConnectionHandler

# Simulate mouse click
connection = ConnectionHandler()
await dispatch_mouse_event(
    connection, 
    type="mousePressed", 
    x=100, 
    y=200, 
    button="left"
)

# Simulate keyboard typing
await dispatch_key_event(
    connection,
    type="keyDown",
    key="Enter"
)
```

--------------------------------

### get_frame

Source: https://pydoll.tech/docs/api/browser/tab

Gets a Tab object for interacting with iframe content.

```APIDOC
## get_frame(frame)

### Description
Get Tab object for interacting with iframe content.

### Parameters
- **frame** (WebElement) - Required - Tab representing the iframe tag.

### Returns
- **IFrame** - Tab instance configured for iframe interaction.
```

--------------------------------

### Execute GET Request

Source: https://pydoll.tech/docs/api/browser/requests

Retrieves data from a target URL.

```python
get(url, params=None, **kwargs)
```

--------------------------------

### Create Headless Browser Contexts

Source: https://pydoll.tech/docs/features/browser-management/contexts

Demonstrates creating multiple isolated browser contexts in headless mode. Headless mode is recommended for production and CI/CD environments for faster, lighter execution.

```python
import asyncio
from pydoll.browser.chromium import Chrome, ChromiumOptions

async def headless_contexts():
    options = ChromiumOptions()
    options.headless = True  # No visible windows

    async with Chrome(options=options) as browser:
        # Start browser with initial tab in default context
        initial_tab = await browser.start()
        await initial_tab.go_to('https://example.com/page0')

        # Create 4 more contexts - no windows opened, all in background
        contexts = []
        for i in range(1, 5):
            context_id = await browser.create_browser_context()
            tab = await browser.new_tab(f'https://example.com/page{i}', browser_context_id=context_id)
            contexts.append((context_id, tab))

        print(f"Created {len(contexts) + 1} isolated contexts (1 default + {len(contexts)} custom, invisible)")

        # Cleanup
        for context_id, tab in contexts:
            await tab.close()
            await browser.delete_browser_context(context_id)

asyncio.run(headless_contexts())
```

--------------------------------

### get_properties()

Source: https://pydoll.tech/docs/api/commands/runtime

Creates a command to get properties of a JavaScript object.

```APIDOC
## get_properties(object_id, ...)

### Description
Creates a command to get properties of a JavaScript object.

### Parameters
- **object_id** (str) - Required - ID of the object to get properties for.
- **own_properties** (Optional[bool]) - Optional - Whether to return only own properties.
- **accessor_properties_only** (Optional[bool]) - Optional - Whether to return only accessor properties.
- **generate_preview** (Optional[bool]) - Optional - Whether to generate previews for property values.
- **non_indexed_properties_only** (Optional[bool]) - Optional - Whether to return only non-indexed properties.

### Returns
- **GetPropertiesCommand** - Command object to get object properties.
```

--------------------------------

### Enable Headless Mode

Source: https://pydoll.tech/docs/features/configuration/browser-options

Configure headless mode using the .headless property or by adding the appropriate command-line argument. The new headless mode (--headless=new) is recommended for better compatibility.

```python
options = ChromiumOptions()
options.headless = True  # Automatically adds --headless argument

# Or manually
options.add_argument('--headless')
options.add_argument('--headless=new')  # New headless mode (Chrome 109+)
```

--------------------------------

### Define FRAME_STARTED_NAVIGATING event

Source: https://pydoll.tech/docs/api/protocol/page

Represents the event fired when a navigation starts.

```python
FRAME_STARTED_NAVIGATING = 'Page.frameStartedNavigating'
```
Tokens:
Raw