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()
Using Context Manager (Recommended)
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
- Install the Chrome extension EditThisCookie
- Navigate to your target website and login
- 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 filebase_url: Base URL to initialize the browserheadless: 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:
-
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.
-
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.
-
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.
-
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.
-
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.