Metadata-Version: 2.4
Name: browsernative
Version: 2.2.0
Summary: Lightning-fast web scraping Python SDK - 11x faster than traditional scrapers
Home-page: https://github.com/monostate/browsernative-python
Author: BNCA Team
Author-email: BNCA Team <support@monostate.ai>
License: MIT
Project-URL: Homepage, https://bnca.monostate.ai
Project-URL: Documentation, https://docs.bnca.dev
Project-URL: Repository, https://github.com/monostate/browsernative-python
Project-URL: Issues, https://github.com/monostate/browsernative-python/issues
Keywords: web scraping,browser automation,ai analysis,screenshot,pdf parsing,data extraction,web crawler,html parser,content extraction
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: websocket-client>=1.6.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: twine>=3.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# browsernative

> Python client for the Browser Native web scraping API

[![PyPI](https://img.shields.io/pypi/v/browsernative.svg)](https://pypi.org/project/browsernative/)
[![Python](https://img.shields.io/pypi/pyversions/browsernative.svg)](https://pypi.org/project/browsernative/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Lightweight client for scraping, screenshots, and AI analysis via the Browser Native API. Single dependency (`requests`).

## Install

```bash
pip install browsernative
```

Get an API key at [bnca.monostate.ai](https://bnca.monostate.ai).

## Usage

```python
from browsernative import BrowserNativeClient

client = BrowserNativeClient('your-api-key')

# Scrape
result = client.scrape('https://example.com')

# Force a specific scraping method
result = client.scrape('https://example.com', method='lightpanda')

# Screenshot
screenshot = client.screenshot('https://example.com')

# Quick screenshot (faster, no content extraction)
quick = client.quickshot('https://example.com')

# AI Q&A
answer = client.analyze('https://example.com', 'What is this site about?')
```

### Convenience functions

```python
from browsernative import quick_scrape, quick_shot, quick_analyze, bulk_scrape

content = quick_scrape('https://example.com', 'your-api-key')
shot = quick_shot('https://example.com', 'your-api-key')
answer = quick_analyze('https://example.com', 'What is this?', 'your-api-key')
```

### Bulk scraping

```python
urls = ['https://site1.com', 'https://site2.com', 'https://site3.com']

result = client.bulk_scrape(
    urls,
    concurrency=5,
    continue_on_error=True,
    progress_callback=lambda p: print(f"{p['percentage']:.1f}%"),
)

print(f"{result['stats']['successful']}/{result['stats']['total']} succeeded")
```

### Context manager

```python
with BrowserNativeClient('your-api-key') as client:
    result = client.scrape('https://example.com')
    # Session closed automatically
```

## API Reference

### Client options

```python
client = BrowserNativeClient(
    api_key='your-api-key',
    base_url='https://bnca-api.fly.dev',  # API endpoint
    timeout=30,                            # Seconds
    retries=2,                             # Retry attempts
    verbose=False,                         # Debug logging
)
```

### Methods

| Method | Description |
|--------|-------------|
| `scrape(url, **opts)` | Extract structured content |
| `screenshot(url, **opts)` | Screenshot with content extraction |
| `quickshot(url, **opts)` | Fast screenshot only |
| `analyze(url, question, **opts)` | AI-powered Q&A |
| `bulk_scrape(urls, **opts)` | Scrape multiple URLs concurrently |
| `get_usage(days=30)` | Account usage statistics |
| `health_check()` | API health status |

### Scrape options

Pass as keyword arguments:

- `method` -- `'auto'`, `'direct'`, `'lightpanda'`, or `'puppeteer'`
- `include_screenshot` -- Include screenshot in response
- `wait_for_selector` -- CSS selector to wait for
- `user_agent` -- Custom user agent

### Response shape

```python
{
    'success': True,
    'data': { 'title': ..., 'content': ..., ... },
    'responseTime': 1234,
    'attempt': 1,
}
```

### Browser sessions

Persistent browser sessions with real-time control over WebSocket:

```python
session = client.create_session(mode='auto')

session.goto('https://example.com')
session.click('#login')
session.type('#email', 'user@example.com')
state = session.get_page_state(includeScreenshot=True)
session.screenshot()

# Listen for backend fallback events
session.on('fallback', lambda e: print(f"{e['from']} -> {e['to']}: {e['reason']}"))

session.close()
```

Modes: `auto` (LightPanda + Chrome fallback), `headless`, `visual`, `computer-use`.

#### Computer use mode

For AI agents that control the browser by pixel coordinates:

```python
session = client.create_session(mode='computer-use', screen_width=1280, screen_height=800)

session.goto('https://example.com')
session.click_at(640, 400)
session.type_text('hello world')
session.mouse_move(100, 200)
session.drag(10, 20, 300, 400)
session.scroll_at(640, 400, 'down', 5)
pos = session.get_cursor_position()
size = session.get_screen_size()
screenshot = session.screenshot()

# VNC streaming URL
print(session.vnc_url)

session.close()
```

Requires `websocket-client`: `pip install websocket-client`

## Requirements

- Python 3.9+
- `requests` (installed automatically)
- `websocket-client` (for browser sessions)

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).

## License

MIT
