Metadata-Version: 2.4
Name: StealthPlex
Version: 0.0.5
Summary: Multi-engine stealth fetch layer for Python scraping—anti-bot bypass from TLS fingerprinting to CDP browsers, with optional auto-escalation.
Project-URL: Homepage, https://github.com/SSujitX/StealthPlex
Project-URL: Repository, https://github.com/SSujitX/StealthPlex
Project-URL: Documentation, https://github.com/SSujitX/StealthPlex#readme
Project-URL: Issues, https://github.com/SSujitX/StealthPlex/issues
Project-URL: Changelog, https://github.com/SSujitX/StealthPlex/releases
Author: SSujitX
License-Expression: MIT
Keywords: anti-bot,bot-detection,cloudflare,cloudscraper,curl-cffi,http-client,scraping,scrapling,seleniumbase,stealth,tls-fingerprint,wreq
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Provides-Extra: all
Requires-Dist: cloudscraper; extra == 'all'
Requires-Dist: curl-cffi; extra == 'all'
Requires-Dist: scrapling[fetchers]; extra == 'all'
Requires-Dist: seleniumbase; extra == 'all'
Requires-Dist: wreq; extra == 'all'
Provides-Extra: cloudscraper
Requires-Dist: cloudscraper; extra == 'cloudscraper'
Provides-Extra: curl-cffi
Requires-Dist: curl-cffi; extra == 'curl-cffi'
Provides-Extra: scrapling
Requires-Dist: scrapling[fetchers]; extra == 'scrapling'
Provides-Extra: seleniumbase
Requires-Dist: seleniumbase; extra == 'seleniumbase'
Provides-Extra: wreq
Requires-Dist: wreq; extra == 'wreq'
Description-Content-Type: text/markdown

<p align="center">
  <img
    src="https://github.com/SSujitX/StealthPlex/raw/master/stealthplex_logo.png"
    alt="StealthPlex Logo"
    width="150"
  />
</p>


# StealthPlex


**Stealth web scraping when basic HTTP gets blocked** — Cloudflare (Turnstile, interstitial), Akamai, Imperva, Datadome, and similar bot walls.

StealthPlex wraps the tools you'd reach for anyway — [wreq](https://github.com/0x676e67/wreq-python), [curl_cffi](https://github.com/lexiforest/curl_cffi), [cloudscraper](https://github.com/VeNoMouS/cloudscraper), [Scrapling](https://github.com/D4Vinci/Scrapling), and [SeleniumBase](https://github.com/seleniumbase/SeleniumBase) — behind a single `Fetch()` interface with **built-in stealth**: randomized browser fingerprints (User-Agent, Sec-CH-UA, Sec-Fetch-*, Accept-Language, Referer), automatic TLS/JA3 impersonation, and serial engine escalation from fast HTTP all the way to stealth browser UC/CDP automation (headed on Windows/macOS, auto-Xvfb on Linux).

```python
from StealthPlex import Fetch

# Zero config — stealth headers + serial engine fallback
fetch = Fetch()
resp = fetch.get("https://protected-site.com")
print(resp.text)      # HTML
print(resp.json())    # or JSON
print(resp.engine)    # which engine bypassed
```

**Fallback chain:** curl_cffi → wreq → cloudscraper → scrapling → seleniumbase  
Each request gets **randomized stealth fingerprints**. If one engine gets blocked, the next one takes over automatically.

## Install

### 1. Installation

StealthPlex core has no default engine dependencies to remain lightweight. You must install at least one engine extra to perform requests.

#### Recommended: Install all engines

Using **uv**:
```bash
uv add StealthPlex --extra all
```

Using **pip**:
```bash
pip install "StealthPlex[all]"
```

#### Install individual engines

##### wreq (Rust TLS / HTTP2 Impersonation)
Using **uv**:
```bash
uv add StealthPlex --extra wreq
```

Using **pip**:
```bash
pip install "StealthPlex[wreq]"
```

##### curl_cffi (libcurl Impersonation)
Using **uv**:
```bash
uv add StealthPlex --extra curl_cffi
```

Using **pip**:
```bash
pip install "StealthPlex[curl_cffi]"
```

##### cloudscraper (Cloudflare Solver)
Using **uv**:
```bash
uv add StealthPlex --extra cloudscraper
```

Using **pip**:
```bash
pip install "StealthPlex[cloudscraper]"
```

##### scrapling (Playwright-based Stealth Browser)
Using **uv**:
```bash
uv add StealthPlex --extra scrapling
```

Using **pip**:
```bash
pip install "StealthPlex[scrapling]"
```

##### seleniumbase (UC/CDP Mode Browser)
Using **uv**:
```bash
uv add StealthPlex --extra seleniumbase
```

Using **pip**:
```bash
pip install "StealthPlex[seleniumbase]"
```

#### Install multiple specific engines

Using **uv**:
```bash
uv add StealthPlex --extra curl_cffi --extra seleniumbase
```

Using **pip**:
```bash
pip install "StealthPlex[curl_cffi,seleniumbase]"
```

### 2. Upgrading Engines (Bypass Updates)

Because anti-bot protections change constantly, you should keep all engine packages updated to their latest versions:

Using **uv**:
```bash
uv add --upgrade "StealthPlex[all]"
```

Using **pip** (requires `--upgrade-strategy eager` to force upgrade of all extra engines):
```bash
pip install --upgrade --upgrade-strategy eager "StealthPlex[all]"
```



## Engines

| Engine | Extra | Layer | Upstream | Detailed Docs |
|--------|-------|-------|----------|---------------|
| `wreq` | `wreq` | L1 | [0x676e67/wreq-python](https://github.com/0x676e67/wreq-python) | [wreq Guide](StealthPlex/engines/wreq/README.md) |
| `curl_cffi` | `curl_cffi` | L1 | [lexiforest/curl_cffi](https://github.com/lexiforest/curl_cffi) | [curl_cffi Guide](StealthPlex/engines/curl_cffi/README.md) |
| `cloudscraper` | `cloudscraper` | L2 | [VeNoMouS/cloudscraper](https://github.com/VeNoMouS/cloudscraper) | [cloudscraper Guide](StealthPlex/engines/cloudscraper/README.md) |
| `scrapling` | `scrapling` | L3 | [D4Vinci/Scrapling](https://github.com/D4Vinci/Scrapling) | [scrapling Guide](StealthPlex/engines/scrapling/README.md) |
| `seleniumbase` | `seleniumbase` | L4 | [seleniumbase/SeleniumBase](https://github.com/seleniumbase/SeleniumBase) | [seleniumbase Guide](StealthPlex/engines/seleniumbase/README.md) |

---

## Quick Start — Stealth Fallback (Default)

Just call `Fetch()` — no engine needed. StealthPlex injects stealth headers and walks the engine chain serially until one bypasses.

### Basic GET — Parse HTML or JSON

```python
from StealthPlex import Fetch

fetch = Fetch()

# GET with full stealth headers auto-injected
resp = fetch.get("https://httpbin.org/get")
print(resp.status_code)
print(resp.text)                           # raw HTML/text
print(resp.json())                         # auto-parse JSON
print(resp.engine)                         # "wreq", "curl_cffi", etc.
print(resp.attempts)                       # ("wreq",) or ("wreq", "curl_cffi")
print(resp.ok)                             # True if status < 400
```

### POST with JSON body

```python
from StealthPlex import Fetch

fetch = Fetch()
resp = fetch.post(
    "https://httpbin.org/post",
    json={"username": "admin", "password": "secret"},
    headers={"X-Custom": "value"},
)
print(resp.json())
```

### PUT, DELETE, PATCH, HEAD, OPTIONS

```python
from StealthPlex import Fetch

fetch = Fetch()

# PUT with raw data
resp = fetch.put("https://httpbin.org/put", data="update payload")
print(resp.json())

# DELETE
resp = fetch.delete("https://httpbin.org/delete")
print(resp.status_code)

# PATCH with JSON
resp = fetch.patch("https://httpbin.org/patch", json={"key": "val"})
print(resp.json())

# HEAD (status + headers only)
resp = fetch.head("https://httpbin.org/get")
print(resp.status_code, resp.headers)

# OPTIONS
resp = fetch.options("https://httpbin.org/get")
print(resp.status_code)
```

### Custom Headers, Cookies, Params, Redirects

```python
from StealthPlex import Fetch

fetch = Fetch()

# All parameters work with full IDE autocomplete
resp = fetch.get(
    "https://httpbin.org/get",
    headers={"Authorization": "Bearer token123"},
    cookies={"session": "abc123"},
    params={"q": "stealth scraping", "page": "1"},
    timeout=30.0,
    allow_redirects=False,         # or redirect=False
)
print(resp.status_code)
print(resp.json())
```

### Custom Fallback Order

```python
from StealthPlex import Fetch

# Only try these two engines in this order
fetch = Fetch(fallback=["curl_cffi", "cloudscraper"])
resp = fetch.get("https://example.com")
print(resp.engine)
```

---

## Engine-Specific Examples

For full upstream API access (types, autocomplete, docs), bind to a specific engine:

#### wreq (TLS Impersonation - Async)
```python
import asyncio
from StealthPlex import Fetch

async def main():
    fetch = Fetch(engine="wreq")
    response = await fetch.get("https://example.com", emulation=fetch.Emulation.Firefox149)
    print(await response.text())

asyncio.run(main())
```

#### curl_cffi (TLS Impersonation - Sync/Async)
```python
from StealthPlex import Fetch

fetch = Fetch(engine="curl_cffi")
response = fetch.get("https://example.com", impersonate="chrome124")
print(response.text)
```

#### cloudscraper (Cloudflare Session Bypass)
```python
from StealthPlex import Fetch

fetch = Fetch(engine="cloudscraper")
scraper = fetch.create_scraper(browser="chrome")
response = scraper.get("https://example.com")
print(response.text)
```

#### scrapling (Stealth Browser Fetch & Selector)
```python
from StealthPlex import Fetch

fetch = Fetch(engine="scrapling")
response = fetch.fetcher.fetch("https://example.com")
print(response.text)
```

#### seleniumbase (Hard-Target Browser UC/CDP Automation)
```python
from StealthPlex import Fetch

fetch = Fetch(engine="seleniumbase")
with fetch.SB(uc=True) as sb:
    sb.activate_cdp_mode("https://example.com")
    sb.sleep(2.0)
    print(sb.get_page_source())
```

---

## API Summary

| Need | Use | Docs |
|------|-----|------|
| **Stealth auto-bypass (recommended)** | **`Fetch()`** | — |
| Custom engine order | `Fetch(fallback=["wreq", "curl_cffi"])` | — |
| Full [wreq](https://github.com/0x676e67/wreq-python) API | `Fetch(engine="wreq")` | [Guide](StealthPlex/engines/wreq/README.md) |
| Full [curl_cffi](https://github.com/lexiforest/curl_cffi) API | `Fetch(engine="curl_cffi")` | [Guide](StealthPlex/engines/curl_cffi/README.md) |
| Full [cloudscraper](https://github.com/VeNoMouS/cloudscraper) API | `Fetch(engine="cloudscraper")` | [Guide](StealthPlex/engines/cloudscraper/README.md) |
| Adaptive fetch ([Scrapling](https://github.com/D4Vinci/Scrapling)) | `Fetch(engine="scrapling")` | [Guide](StealthPlex/engines/scrapling/README.md) |
| Full [SeleniumBase](https://github.com/seleniumbase/SeleniumBase) API | `Fetch(engine="seleniumbase")` | [Guide](StealthPlex/engines/seleniumbase/README.md) |
| Shortcuts | `curl_fetch()`, `wreq_fetch()`, `cloudscraper_fetch()`, `scrapling_fetch()`, `seleniumbase_fetch()` | — |
