nakalbrowser 0.1.0__tar.gz

nakalbrowser-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: nakalbrowser
+Version: 0.1.0
+Summary: Nakal Browser — light, powerful CDP browser automation for Python
+Author: NakalBrowser
+License: MIT
+Project-URL: Homepage, https://github.com/nakalbrowser/nakalbrowser
+Project-URL: Documentation, https://github.com/nakalbrowser/nakalbrowser
+Keywords: browser,automation,cdp,chrome,scraping,nakal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websocket-client>=1.6.0
+Provides-Extra: http
+Requires-Dist: curl_cffi>=0.6.0; extra == "http"
+Provides-Extra: parse
+Requires-Dist: selectolax>=0.3.21; extra == "parse"
+Provides-Extra: proc
+Requires-Dist: psutil>=5.9.0; extra == "proc"
+Provides-Extra: cloak
+Requires-Dist: cloakbrowser>=0.4.0; extra == "cloak"
+Provides-Extra: captcha
+Provides-Extra: all
+Requires-Dist: nakalbrowser[cloak,http,parse,proc]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: nakalbrowser[http]; extra == "dev"
+
+<p align="center">
+  <img src="BannerGithubBrowser.png" alt="Nakal Browser" width="100%">
+</p>
+
+<h1 align="center">Nakal Browser</h1>
+
+<p align="center">
+  <b>Lightweight browser automation for Python — fast, stealth, production-ready</b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10+-blue?style=flat-square&logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
+  <img src="https://img.shields.io/badge/CDP-pure-red?style=flat-square" alt="CDP">
+  <img src="https://img.shields.io/badge/version-0.1.0-orange?style=flat-square" alt="Version">
+</p>
+
+---
+
+## Features
+
+- **Pure CDP** — no chromedriver, no webdriver, direct Chrome DevTools Protocol
+- **Rush** — HTTP requests + JavaScript rendering in one class
+- **Playwright-style locators** — `bot.locator("h1").click()` with auto-wait
+- **Stealth built-in** — fingerprint, humanize, proxy, multi-account
+- **Any Chromium** — Chrome, Edge, CloakBrowser, or custom binary
+- **Farm** — run multiple accounts in parallel
+- **Network capture** — sniff requests, intercept, mock responses
+- **AI Agent ready** — snapshot, extract, a11y for LLM integration
+
+---
+
+## Install
+
+```bash
+pip install nakalbrowser
+```
+
+```bash
+python -m nakalbrowser doctor   # check environment
+```
+
+---
+
+## Quick start
+
+```python
+from nakalbrowser import Engine
+
+with Engine(headless=True) as bot:
+    bot.open("https://example.com")
+    print(bot.title)
+    print(bot.find("h1").text)
+    bot.find("a").click()
+```
+
+---
+
+## Rush — HTTP + JS hybrid
+
+```python
+from nakalbrowser import Rush
+
+# Pure HTTP (fast, no browser)
+with Rush(impersonate="chrome") as r:
+    resp = r.get("https://api.example.com/data")
+    print(resp.json)
+
+# Need JS? Render with browser
+with Rush(headless=True) as r:
+    r.render("https://spa.example.com", wait_for=".content", wait_until="networkidle")
+    print(r.find("h1").text)
+```
+
+---
+
+## Locators
+
+```python
+bot.locator("h1").click()
+bot.locator("#email").fill("user@example.com")
+bot.get_by_role("button", name="Submit").click()
+bot.get_by_text("Welcome").expect().to_have_text("Welcome")
+bot.locator("h1").expect().to_be_visible(timeout=5)
+bot.locator("form").locator("input[type=text]").fill("x")
+```
+
+---
+
+## Multi-account & Proxy
+
+```python
+from nakalbrowser import Engine, Face, Profile, Proxy
+
+face = Face.from_seed("acc01", os="windows")
+prof = Profile.create("acc01", solid=True, proxy="socks5://user:pass@host:1080")
+with Engine(profile=prof, headless=True) as bot:
+    bot.open("https://example.com")
+```
+
+---
+
+## Farm — parallel execution
+
+```python
+from nakalbrowser import Farm, Profile
+
+profiles = [Profile.create(f"acc_{i}", solid=True) for i in range(10)]
+farm = Farm(profiles=profiles, concurrency=3, headless=True)
+results = farm.run(lambda bot, prof: bot.open("https://target.com") or bot.title)
+```
+
+---
+
+## Mouse & Keyboard
+
+```python
+bot.mouse.click(100, 200)
+bot.mouse.drag(0, 0, 500, 500)
+bot.keyboard.type("Hello World")
+bot.keyboard.hotkey("Control", "a")
+```
+
+---
+
+## Network
+
+```python
+# Capture
+bot.sniff.start("**/api/**")
+bot.open("https://example.com")
+for c in bot.sniff.all():
+    print(c.method, c.url, c.status)
+
+# Mock
+bot.intercept.fulfill("*/api/data", body='{"ok": true}', content_type="application/json")
+```
+
+---
+
+## AI Agent
+
+```python
+with Engine(headless=True) as bot:
+    bot.open("https://example.com")
+    state = bot.snapshot(markdown=True)    # compact state for LLM
+    data = bot.extract({"title": "h1", "links": "a@href[]"})
+    bot.find("text:Learn more").click()
+```
+
+---
+
+## API
+
+| Class | What it does |
+|---|---|
+| `Engine` | Main browser controller |
+| `Rush` | HTTP + JS render |
+| `Face` | Fingerprint (save/load) |
+| `Profile` | Multi-account bundle |
+| `Proxy` | Proxy parse + auth bridge |
+| `Farm` | Concurrent multi-profile |
+| `Locator` | Playwright-style finder |
+| `Mouse` / `Keyboard` | Precise input |
+| `Page` / `Node` / `Ghost` | Tab / element / missing |
+| `Pane` / `Shell` | iframe / shadow DOM |
+
+Plus: `sniff`, `intercept`, `until`, `download`, `save_state` / `load_state`
+
+---
+
+## CLI
+
+```bash
+python -m nakalbrowser doctor
+python -m nakalbrowser open https://example.com --headless
+```
+
+---
+
+## Browser
+
+```python
+Engine()                       # auto-detect
+Engine(browser="chrome")       # force Chrome
+Engine(browser="edge")         # force Edge
+Engine(browser_path="...")     # custom path
+```
+
+---
+
+## Docs
+
+| File | Content |
+|---|---|
+| [docs/USAGE.md](docs/USAGE.md) | Full guide |
+| [docs/AGENTS.md](docs/AGENTS.md) | Project structure for AI agents |
+
+---
+
+## License
+
+MIT

nakalbrowser-0.1.0/README.md

@@ -0,0 +1,203 @@
+<p align="center">
+  <img src="BannerGithubBrowser.png" alt="Nakal Browser" width="100%">
+</p>
+
+<h1 align="center">Nakal Browser</h1>
+
+<p align="center">
+  <b>Lightweight browser automation for Python — fast, stealth, production-ready</b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10+-blue?style=flat-square&logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
+  <img src="https://img.shields.io/badge/CDP-pure-red?style=flat-square" alt="CDP">
+  <img src="https://img.shields.io/badge/version-0.1.0-orange?style=flat-square" alt="Version">
+</p>
+
+---
+
+## Features
+
+- **Pure CDP** — no chromedriver, no webdriver, direct Chrome DevTools Protocol
+- **Rush** — HTTP requests + JavaScript rendering in one class
+- **Playwright-style locators** — `bot.locator("h1").click()` with auto-wait
+- **Stealth built-in** — fingerprint, humanize, proxy, multi-account
+- **Any Chromium** — Chrome, Edge, CloakBrowser, or custom binary
+- **Farm** — run multiple accounts in parallel
+- **Network capture** — sniff requests, intercept, mock responses
+- **AI Agent ready** — snapshot, extract, a11y for LLM integration
+
+---
+
+## Install
+
+```bash
+pip install nakalbrowser
+```
+
+```bash
+python -m nakalbrowser doctor   # check environment
+```
+
+---
+
+## Quick start
+
+```python
+from nakalbrowser import Engine
+
+with Engine(headless=True) as bot:
+    bot.open("https://example.com")
+    print(bot.title)
+    print(bot.find("h1").text)
+    bot.find("a").click()
+```
+
+---
+
+## Rush — HTTP + JS hybrid
+
+```python
+from nakalbrowser import Rush
+
+# Pure HTTP (fast, no browser)
+with Rush(impersonate="chrome") as r:
+    resp = r.get("https://api.example.com/data")
+    print(resp.json)
+
+# Need JS? Render with browser
+with Rush(headless=True) as r:
+    r.render("https://spa.example.com", wait_for=".content", wait_until="networkidle")
+    print(r.find("h1").text)
+```
+
+---
+
+## Locators
+
+```python
+bot.locator("h1").click()
+bot.locator("#email").fill("user@example.com")
+bot.get_by_role("button", name="Submit").click()
+bot.get_by_text("Welcome").expect().to_have_text("Welcome")
+bot.locator("h1").expect().to_be_visible(timeout=5)
+bot.locator("form").locator("input[type=text]").fill("x")
+```
+
+---
+
+## Multi-account & Proxy
+
+```python
+from nakalbrowser import Engine, Face, Profile, Proxy
+
+face = Face.from_seed("acc01", os="windows")
+prof = Profile.create("acc01", solid=True, proxy="socks5://user:pass@host:1080")
+with Engine(profile=prof, headless=True) as bot:
+    bot.open("https://example.com")
+```
+
+---
+
+## Farm — parallel execution
+
+```python
+from nakalbrowser import Farm, Profile
+
+profiles = [Profile.create(f"acc_{i}", solid=True) for i in range(10)]
+farm = Farm(profiles=profiles, concurrency=3, headless=True)
+results = farm.run(lambda bot, prof: bot.open("https://target.com") or bot.title)
+```
+
+---
+
+## Mouse & Keyboard
+
+```python
+bot.mouse.click(100, 200)
+bot.mouse.drag(0, 0, 500, 500)
+bot.keyboard.type("Hello World")
+bot.keyboard.hotkey("Control", "a")
+```
+
+---
+
+## Network
+
+```python
+# Capture
+bot.sniff.start("**/api/**")
+bot.open("https://example.com")
+for c in bot.sniff.all():
+    print(c.method, c.url, c.status)
+
+# Mock
+bot.intercept.fulfill("*/api/data", body='{"ok": true}', content_type="application/json")
+```
+
+---
+
+## AI Agent
+
+```python
+with Engine(headless=True) as bot:
+    bot.open("https://example.com")
+    state = bot.snapshot(markdown=True)    # compact state for LLM
+    data = bot.extract({"title": "h1", "links": "a@href[]"})
+    bot.find("text:Learn more").click()
+```
+
+---
+
+## API
+
+| Class | What it does |
+|---|---|
+| `Engine` | Main browser controller |
+| `Rush` | HTTP + JS render |
+| `Face` | Fingerprint (save/load) |
+| `Profile` | Multi-account bundle |
+| `Proxy` | Proxy parse + auth bridge |
+| `Farm` | Concurrent multi-profile |
+| `Locator` | Playwright-style finder |
+| `Mouse` / `Keyboard` | Precise input |
+| `Page` / `Node` / `Ghost` | Tab / element / missing |
+| `Pane` / `Shell` | iframe / shadow DOM |
+
+Plus: `sniff`, `intercept`, `until`, `download`, `save_state` / `load_state`
+
+---
+
+## CLI
+
+```bash
+python -m nakalbrowser doctor
+python -m nakalbrowser open https://example.com --headless
+```
+
+---
+
+## Browser
+
+```python
+Engine()                       # auto-detect
+Engine(browser="chrome")       # force Chrome
+Engine(browser="edge")         # force Edge
+Engine(browser_path="...")     # custom path
+```
+
+---
+
+## Docs
+
+| File | Content |
+|---|---|
+| [docs/USAGE.md](docs/USAGE.md) | Full guide |
+| [docs/AGENTS.md](docs/AGENTS.md) | Project structure for AI agents |
+
+---
+
+## License
+
+MIT

nakalbrowser-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nakalbrowser"
+version = "0.1.0"
+description = "Nakal Browser — light, powerful CDP browser automation for Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "NakalBrowser" }]
+keywords = ["browser", "automation", "cdp", "chrome", "scraping", "nakal"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: WWW/HTTP :: Browsers",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "websocket-client>=1.6.0",
+]
+
+[project.optional-dependencies]
+http = ["curl_cffi>=0.6.0"]
+parse = ["selectolax>=0.3.21"]
+proc = ["psutil>=5.9.0"]
+cloak = ["cloakbrowser>=0.4.0"]
+captcha = []  # use env TWOCAPTCHA_API_KEY + built-in TwoCaptcha helper
+all = ["nakalbrowser[http,parse,proc,cloak]"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.23", "nakalbrowser[http]"]
+
+[project.urls]
+Homepage = "https://github.com/nakalbrowser/nakalbrowser"
+Documentation = "https://github.com/nakalbrowser/nakalbrowser"
+
+[project.scripts]
+nakalbrowser = "nakalbrowser.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nakalbrowser = ["py.typed"]

nakalbrowser-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nakalbrowser-0.1.0/src/nakalbrowser/__init__.py

@@ -0,0 +1,119 @@
+from .boot.boot import Boot
+from .cloak.face import Face
+from .core.errors import (
+    BrowserConnectError,
+    BrowserMissingError,
+    CDPError,
+    ClickError,
+    DownloadError,
+    ElementLostError,
+    ElementNotFoundError,
+    ExpectError,
+    FrameError,
+    InterceptError,
+    JSError,
+    LocatorError,
+    NakalError,
+    PageDisconnectedError,
+    WaitTimeoutError,
+    error_dict,
+)
+from .core.knob import Knob
+from .dom.ghost import Ghost
+from .dom.interact import Keyboard, Mouse
+from .dom.locator import Locator
+from .dom.node import Node
+from .dom.shell import Shell
+from .engine.engine import Engine
+from .fleet.profile import Profile
+from .net.download import Download, Loot
+from .net.sniff import Catch, Intercept, Sniff
+from .net.state import load_state, save_state
+from .page.page import Page
+from .page.pane import Pane
+from .page.rush import Pulse, Rush
+from .proxy.proxy import Proxy
+from .tune.until import Until
+from .util.cleanup import cleanup_path, cleanup_temp, list_temp_profiles
+from .util.geoip import lookup_egress
+from .version import __version__
+
+
+def __getattr__(name: str):
+    if name in ("Farm", "FarmResult"):
+        from .fleet.farm import Farm, FarmResult
+
+        return Farm if name == "Farm" else FarmResult
+    if name == "AsyncEngine":
+        from .engine.async_engine import AsyncEngine
+
+        return AsyncEngine
+    if name in ("TwoCaptcha", "CaptchaError", "inject_recaptcha_token", "inject_turnstile_token"):
+        from .ai import captcha as _c
+
+        return getattr(_c, name)
+    if name in ("snapshot", "a11y", "extract", "snapshot_markdown"):
+        from .ai import snapshot as _s
+
+        return getattr(_s, name)
+    raise AttributeError(f"module 'nakalbrowser' has no attribute {name}")
+
+
+__all__ = [
+    "Engine",
+    "Boot",
+    "Page",
+    "Node",
+    "Rush",
+    "Pulse",
+    "Ghost",
+    "Face",
+    "Profile",
+    "Proxy",
+    "Knob",
+    "Sniff",
+    "Intercept",
+    "Catch",
+    "Until",
+    "Download",
+    "Loot",
+    "Farm",
+    "FarmResult",
+    "AsyncEngine",
+    "Pane",
+    "Shell",
+    "Locator",
+    "Mouse",
+    "Keyboard",
+    "save_state",
+    "load_state",
+    "snapshot",
+    "snapshot_markdown",
+    "a11y",
+    "extract",
+    "TwoCaptcha",
+    "CaptchaError",
+    "inject_recaptcha_token",
+    "inject_turnstile_token",
+    "error_dict",
+    "NakalError",
+    "BrowserConnectError",
+    "BrowserMissingError",
+    "CDPError",
+    "PageDisconnectedError",
+    "ElementNotFoundError",
+    "ElementLostError",
+    "ClickError",
+    "WaitTimeoutError",
+    "LocatorError",
+    "JSError",
+    "ExpectError",
+    "InterceptError",
+    "DownloadError",
+    "FrameError",
+    "cleanup_temp",
+    "cleanup_path",
+    "list_temp_profiles",
+    "lookup_egress",
+    "__version__",
+]

nakalbrowser-0.1.0/src/nakalbrowser/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

nakalbrowser-0.1.0/src/nakalbrowser/ai/__init__.py

@@ -0,0 +1,18 @@
+from .captcha import (
+    CaptchaError,
+    TwoCaptcha,
+    inject_recaptcha_token,
+    inject_turnstile_token,
+)
+from .snapshot import a11y, extract, snapshot, snapshot_markdown
+
+__all__ = [
+    "snapshot",
+    "snapshot_markdown",
+    "a11y",
+    "extract",
+    "TwoCaptcha",
+    "CaptchaError",
+    "inject_recaptcha_token",
+    "inject_turnstile_token",
+]