Metadata-Version: 2.4
Name: browser_dog
Version: 0.1.0
Summary: A stealthy Chrome automation toolkit driven by cookies, with anti-detection and smooth scrolling.
Author-email: Chandler Song <275737875@qq.com>
License: MIT
Keywords: selenium,automation,browser,cookies,anti-detection,scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: selenium>=4.0.0
Requires-Dist: colorama
Dynamic: license-file

# 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

```bash
pip install browser_dog
```

## Quick Start

### Basic Usage

```python
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)

```python
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

```python
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

```python
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](https://chrome.google.com/webstore/detail/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

```python
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

```python
@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](LICENSE) file for details.
