Skip to main content

Browser Dog

A stealthy Chrome automation toolkit driven by cookies, with anti-detection and smooth scrolling.

Features

  • Anti-Detection: Random User-Agent, CDP injection, webdriver property hiding
  • Robust Cookie Loading: Expiry filtering, sameSite compatibility, redundant field cleanup
  • Smooth Scrolling: Human-like progressive scrolling simulation
  • Captcha Detection: Automatic detection of blocks and captchas with screenshot debugging
  • Context Manager: Automatic resource cleanup to prevent zombie processes
  • Retry Mechanism: Built-in retry decorator for resilient operations

Installation

pip install browser_dog

Quick Start

Basic Usage

from browser_dog import BrowserDog

# Initialize with cookies and base URL
dog = BrowserDog('cookies.json', 'https://example.com', headless=False)
driver = dog.get_driver()

# Navigate and interact
driver.get("https://example.com/page")
dog.medium_wait()

# Get page content
html = driver.page_source
print(html)

# Clean up
dog.close()
from browser_dog import BrowserDog

with BrowserDog('cookies.json', 'https://example.com') as dog:
    driver = dog.get_driver()
    driver.get("https://example.com/page")
    
    # Scroll smoothly
    dog.scroll_to_bottom()
    dog.scroll_to_top()
    
    # Check for blocks
    if dog.detect_block_or_captcha():
        print("Blocked!")

Using Retry Decorator

from browser_dog import BrowserDog, retry

dog = BrowserDog('cookies.json', 'https://example.com')

@retry(max_retries=3, delay=2)
def fetch_data():
    driver = dog.get_driver()
    driver.get("https://example.com/api")
    return driver.page_source

data = fetch_data()

Headless Mode

from browser_dog import BrowserDog

dog = BrowserDog('cookies.json', 'https://example.com', headless=True)
driver = dog.get_driver()

Preparing Cookies

  1. Install the Chrome extension EditThisCookie
  2. Navigate to your target website and login
  3. Export cookies to a JSON file (e.g., cookies.json)

Project Structure

browser_dog-0.1.0/
├── browser_dog/
│   ├── __init__.py          # Package exports (BrowserDog, retry)
│   └── browser.py           # Core BrowserDog class implementation
├── LICENSE                  # MIT License
├── README.md                # This file
└── pyproject.toml           # Package configuration (PEP 621)

API Reference

BrowserDog

Constructor

BrowserDog(cookies_json: str, base_url: str, headless: bool = False)
  • cookies_json: Path to cookies JSON file
  • base_url: Base URL to initialize the browser
  • headless: Enable headless mode (default: False)

Methods

Method Description
get_driver() Returns the Selenium WebDriver instance
close() Safely closes the browser
scroll_to_bottom() Smooth scroll to page bottom
scroll_to_top() Smooth scroll to page top
scroll_to_middle() Instant scroll to page middle
scroll_to_random() Instant scroll to random position
detect_block_or_captcha() Detect captcha or block (returns bool)
take_screenshot(name) Save screenshot for debugging
short_wait() Wait 1-3 seconds
medium_wait() Wait 3-5 seconds
long_wait() Wait 5-10 seconds

retry Decorator

@retry(max_retries: int = 3, delay: int = 2)

Automatically retries failed operations with exponential backoff.

Disclaimer

This tool is provided for educational, research, and legitimate automation testing purposes only. By using Browser Dog, you agree to the following:

  1. Lawful Use Only: You must not use this tool for any illegal activities, including but not limited to malicious web scraping, unauthorized data collection, bypassing security measures, or violating the terms of service of any website or platform.

  2. Compliance with Laws and Policies: You are solely responsible for ensuring that your use of this tool complies with all applicable local, national, and international laws, regulations, and the terms of service of the websites you interact with.

  3. No Warranty: This software is provided "as is" without warranty of any kind. The authors and contributors assume no liability for any claims, damages, or losses arising from the use of this tool.

  4. User Responsibility: You assume full responsibility for any risks associated with using this tool, including but not limited to account suspension, legal action, or reputational damage resulting from misuse or unauthorized use.

  5. Ethical Use: Respect website policies, rate limits, and privacy rights. Do not use this tool to harvest personal data, conduct unauthorized surveillance, or engage in any activity that infringes on the rights of others.

The authors of this project expressly disclaim any responsibility for misuse, abuse, or any unlawful activities conducted using this software. If you are uncertain whether your intended use complies with applicable laws or policies, consult with a legal professional before proceeding.

License

MIT License - see LICENSE file for details.

Metadata

Release files for browser-dog 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for browser-dog 0.1.0
File Size Uploaded Provenance Actions
browser_dog-0.1.0.tar.gz 8.1 kB Without provenance Details for browser_dog-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for browser-dog 0.1.0
File Interpreter ABI Platform Actions
browser_dog-0.1.0-py3-none-any.whl Python 3 none any Details for browser_dog-0.1.0-py3-none-any.whl

Total release size: 16.1 kB

Release files / browser_dog-0.1.0.tar.gz

Download URL browser_dog-0.1.0.tar.gz
Size 8.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c8601a8120575b7c50932c74a23646a13e12bc8b56451ad120812893ca5523d0
BLAKE2b-256 checksum
How to use checksums
25668b15660cdc83e1e872ab688bb20da7b6b19b6f8a6f2e628bb1a8598c9aef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.15

Release files / browser_dog-0.1.0-py3-none-any.whl

Download URL browser_dog-0.1.0-py3-none-any.whl
Size 8.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f2d395ba6568fbe42829a9c3170636e9b17ab684cac092927709431ee524d277
BLAKE2b-256 checksum
How to use checksums
09d25a46cf703d5a0000f31406d04b3621e80a7d1f949c4800f0caa7272f4eb5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.15

Security for browser-dog 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page