Metadata-Version: 2.4
Name: lightpanda-py
Version: 0.2.8
Summary: Python wrapper for Lightpanda browser with CDP server and Playwright integration for lightweight web scraping and automation
Project-URL: Homepage, https://github.com/tclesius/lightpanda-py
Project-URL: Repository, https://github.com/tclesius/lightpanda-py
Project-URL: Issues, https://github.com/tclesius/lightpanda-py/issues
Author-email: Tom Clesius <tomclesius@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# lightpanda-py

Embedded [Lightpanda](https://github.com/lightpanda-io/browser) for Python, a fast headless browser for AI agents and web automation.

## Installation

```bash
pip install lightpanda-py
# or
uv add lightpanda-py
```

No extra setup - the Lightpanda binary is bundled in the package.

## Usage

### Fetch

Spin up an ephemeral browser to fetch a page:

```python
import lightpanda

response = lightpanda.fetch("https://example.com")
print(response.text)

# JSON APIs
response = lightpanda.fetch("https://httpbin.org/ip")
data = response.json()

# Markdown output
response = lightpanda.fetch("https://example.com", dump="markdown")

# Strip JS/CSS from output
response = lightpanda.fetch("https://example.com", strip_mode="js,css")

# Wait for network idle before dump
response = lightpanda.fetch("https://example.com", wait_until="networkidle")
```

### CDP Server

Start a CDP server to use with Playwright, Puppeteer, or any CDP client:

```python
import lightpanda

proc = lightpanda.serve(host="127.0.0.1", port=9222)
# 🐼 Running Lightpanda's CDP server... { pid: 12345 }

# Connect with your favorite CDP client...

proc.kill()
```

Write browser logs to files:

```python
import lightpanda

stdout = open("lightpanda.out.log", "w")
stderr = open("lightpanda.err.log", "w")

proc = lightpanda.serve(stdout=stdout, stderr=stderr)

proc.kill()
```

With Playwright:

```python
import lightpanda
from playwright.sync_api import sync_playwright

proc = lightpanda.serve()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.content())
    browser.close()

proc.kill()
```

### MCP Server

Start a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio:

```python
import lightpanda, json

proc = lightpanda.mcp()

proc.stdin.write(b'{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}\n')
proc.stdin.flush()
print(json.loads(proc.stdout.readline()))  # list of available tools

proc.kill()
```

### Version

```python
import lightpanda

print(lightpanda.version())
```

## Development

The bundled Lightpanda browser version is pinned in `.browser-version`.

Download the pinned browser for local development:

```bash
scripts/get-browser
```

By default this downloads the macOS arm64 binary. To use another asset or browser version:

```bash
scripts/get-browser lightpanda-x86_64-linux
scripts/get-browser lightpanda-aarch64-macos 0.2.9
```

Available raw browser assets:

- `lightpanda-aarch64-macos` - macOS arm64
- `lightpanda-x86_64-macos` - macOS x86_64
- `lightpanda-aarch64-linux` - Linux arm64
- `lightpanda-x86_64-linux` - Linux x86_64

## License

MIT
