semvec/pypi-packages huggingface dataset:
thespis 0.1.0b1
Anti-detection plugin for Playwright automation
License: MIT
Requires Python: >=3.8
Keywords: automation, bot-detection, playwright, stealth, web-scraping

# Thespis

<p align="center">
  <img src="assets/thespis.png" width="150" height="150" alt="Thespis" />
</p>

<p align="center">
  <img src="https://img.shields.io/badge/status-beta-orange" alt="Beta">
  <img src="https://img.shields.io/badge/python-3.8+-blue" alt="Python">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
</p>

<p align="center">
  <strong>Make Playwright automation undetectable</strong>
</p>

> **Note:** This project is currently in beta. Features are stable but may change based on feedback.

## Why Use Thespis?

Websites detect Playwright because of `navigator.webdriver` and other automation signals.

**Results:** Tested against [CreepJS](https://abrahamjuliot.github.io/creepjs/):

| Metric                  | Real Browser | With Thespis | Without Thespis |
| ----------------------- | ------------ | ------------ | --------------- |
| **Like Headless**       | 25%          | **31%**      | 44%             |
| **Headless Detection**  | 0%           | **0%**       | 33%             |

## Quick Start

### Basic Example (Sync)

```python
from playwright.sync_api import sync_playwright
from thespis import stealth_sync

with sync_playwright() as p:
    # Launch browser with special flag (REQUIRED!)
    browser = p.chromium.launch(
        headless=False,
        args=['--disable-blink-features=AutomationControlled']
    )

    # Create page and apply stealth
    page = browser.new_page()
    stealth_sync(page)

    page.goto("https://bot.sannysoft.com")
    page.screenshot(path="test.png")

    browser.close()
```

## Important: Required Flag

**This flag is CRITICAL:**

```python
args=['--disable-blink-features=AutomationControlled']
```

Without it, `navigator.webdriver` stays `true` and detection fails.

## Docker (Production)

For servers without displays, use Docker with Xvfb:

```bash
# Build image
docker-compose build

# Run test script
docker-compose run --rm thespis

# Run your own script
docker-compose run --rm thespis python your_script.py
```

**Why Docker?**

- Runs `headless=False` on servers (31% detection score)
- No visible windows (uses virtual display)

### Recommended Full Configuration

```python
# Launch browser
browser = p.chromium.launch(
    headless=False,
    args=[
        '--disable-blink-features=AutomationControlled',
        '--disable-dev-shm-usage',
        '--no-sandbox',
    ]
)

# Create realistic context
context = browser.new_context(
    viewport={'width': 1366, 'height': 768},
    user_agent='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
    locale='en-US',
    timezone_id='America/New_York',
)

page = context.new_page()
stealth_sync(page)
```