lightpanda-py 0.1.0__tar.gz

lightpanda_py-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Binary downloads (created during build)
+src/lightpanda/bin/
+
+.DS_Store

lightpanda_py-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: lightpanda-py
+Version: 0.1.0
+Summary: Python wrapper for Lightpanda browser with CDP server and Playwright integration for lightweight web scraping and automation
+Author-email: Tom Clesius <tomclesius@gmail.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# lightpanda-py
+
+Python bindings for [Lightpanda](https://github.com/lightpanda-io/browser), a fast headless browser for AI agents and web automation.
+
+## Installation
+
+```bash
+pip install lightpanda-py
+# or
+uv add lightpanda-py
+```
+
+## Usage
+
+### Quick fetch
+
+```python
+import lightpanda
+
+response = lightpanda.fetch("https://example.com")
+print(response.text)
+
+# JSON APIs
+response = lightpanda.fetch("https://httpbin.org/ip")
+data = response.json()
+```
+
+### 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()
+```
+
+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()
+```
+
+## License
+
+MIT

lightpanda_py-0.1.0/README.md

@@ -0,0 +1,63 @@
+# lightpanda-py
+
+Python bindings for [Lightpanda](https://github.com/lightpanda-io/browser), a fast headless browser for AI agents and web automation.
+
+## Installation
+
+```bash
+pip install lightpanda-py
+# or
+uv add lightpanda-py
+```
+
+## Usage
+
+### Quick fetch
+
+```python
+import lightpanda
+
+response = lightpanda.fetch("https://example.com")
+print(response.text)
+
+# JSON APIs
+response = lightpanda.fetch("https://httpbin.org/ip")
+data = response.json()
+```
+
+### 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()
+```
+
+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()
+```
+
+## License
+
+MIT

lightpanda_py-0.1.0/hatch_build.py

@@ -0,0 +1,61 @@
+import json
+import platform
+import urllib.request
+from pathlib import Path
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+GITHUB_RELEASES = "https://api.github.com/repos/lightpanda-io/browser/releases"
+RELEASE_TAG = "nightly"
+
+PLATFORMS = {
+    "Darwin": "macos",
+    "Linux": "linux",
+}
+ARCHITECTURES = {
+    "arm64": "aarch64",
+    "aarch64": "aarch64",
+    "x86_64": "x86_64",
+    "AMD64": "x86_64",
+}
+
+
+class BinaryDownloadHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        os_name, arch = self._detect_platform()
+        bin_dir = Path(self.root) / "src" / "lightpanda" / "bin"
+        bin_dir.mkdir(parents=True, exist_ok=True)
+        binary_path = bin_dir / f"lightpanda-{arch}-{os_name}"
+
+        if not binary_path.is_file() or binary_path.stat().st_size == 0:
+            url = self._find_release_url(os_name, arch)
+            self._download_file(url, binary_path)
+
+    def _detect_platform(self) -> tuple[str, str]:
+        system, machine = platform.system(), platform.machine()
+        if system not in PLATFORMS:
+            raise RuntimeError(f"Unsupported OS: {system}")
+        if machine not in ARCHITECTURES:
+            raise RuntimeError(f"Unsupported arch: {machine}")
+        return PLATFORMS[system], ARCHITECTURES[machine]
+
+    def _find_release_url(self, os_name: str, arch: str) -> str:
+        binary_name = f"lightpanda-{arch}-{os_name}"
+        request = urllib.request.Request(GITHUB_RELEASES)
+        request.add_header("Accept", "application/vnd.github.v3+json")
+        with urllib.request.urlopen(request, timeout=30) as response:
+            releases = json.loads(response.read().decode())
+
+        for r in releases:
+            if r.get("tag_name") == RELEASE_TAG:
+                for asset in r.get("assets", []):
+                    if asset.get("name") == binary_name:
+                        return asset["browser_download_url"]
+                raise RuntimeError(f"Binary '{binary_name}' not found in release")
+        raise RuntimeError(f"Release '{RELEASE_TAG}' not found")
+
+    def _download_file(self, url: str, dest: Path) -> None:
+        with urllib.request.urlopen(url, timeout=300) as response:
+            dest.write_bytes(response.read())
+        dest.chmod(0o755)

lightpanda_py-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "lightpanda-py"
+version = "0.1.0"
+description = "Python wrapper for Lightpanda browser with CDP server and Playwright integration for lightweight web scraping and automation"
+readme = "README.md"
+authors = [{ name = "Tom Clesius", email = "tomclesius@gmail.com" }]
+requires-python = ">=3.13"
+dependencies = []
+
+[build-system]
+requires = ["hatchling>=1.21.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.hooks.custom]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/lightpanda", "hatch_build.py", "README.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lightpanda"]
+artifacts = ["src/lightpanda/bin/lightpanda-*"]

lightpanda_py-0.1.0/src/lightpanda/__init__.py

@@ -0,0 +1,113 @@
+import json
+import subprocess
+from pathlib import Path
+from typing import Literal
+import os
+
+os.environ.setdefault("LIGHTPANDA_DISABLE_TELEMETRY", "true")
+
+BINARY = str(list((Path(__file__).parent / "bin").glob("lightpanda-*"))[0])
+
+
+def build_cmd(*args, **options):
+    cmd = [BINARY, *args]
+    for key, value in options.items():
+        if value is None:
+            continue
+        elif value is True:
+            cmd.append(f"--{key}")
+        elif value is not False:
+            cmd.extend([f"--{key}", str(value)])
+    return cmd
+
+
+class Response:
+    def __init__(self, html: str) -> None:
+        self.html = html
+
+    @property
+    def text(self):
+        return self.html
+
+    def json(self):
+        return json.loads(self.html.split("<pre>")[1].split("</pre>")[0])
+
+
+def serve(
+    host: str = "127.0.0.1",
+    port: int = 9222,
+    timeout: int | None = 10,
+    log_level: Literal["debug", "info", "warning", "error"] = "error",
+    http_proxy: str | None = None,
+    http_timeout: int | None = None,
+) -> subprocess.Popen:
+    """
+    Start Lightpanda browser process with CDP server.
+
+    Args:
+        host: Host to bind the CDP server to (default: "127.0.0.1")
+        port: Port to bind the CDP server to (default: 9222)
+        timeout: Connection timeout in seconds (default: 10)
+        log_level: Logging level (default: "error")
+        http_proxy: HTTP proxy URL (optional)
+        http_timeout: HTTP request timeout in seconds (optional)
+
+    Returns:
+        subprocess.Popen: The process object for the Lightpanda browser
+
+    Example:
+        >>> proc = lightpanda.serve(host='127.0.0.1', port=9222)
+        >>> # Do your magic ✨
+        >>> proc.kill()
+    """
+    cmd = build_cmd(
+        "serve",
+        host=host,
+        port=port,
+        timeout=timeout,
+        log_level=log_level,
+        http_proxy=http_proxy,
+        http_timeout=http_timeout,
+    )
+    proc = subprocess.Popen(cmd)
+    print(f"🐼 Running Lightpanda's CDP server... {{ pid: {proc.pid} }}")
+    return proc
+
+
+def fetch(
+    url: str,
+    *,
+    with_base: bool = False,
+    log_level: Literal["debug", "info", "warning", "error"] = "error",
+    http_proxy: str | None = None,
+    http_timeout: int | None = None,
+) -> Response:
+    """
+    Fetch a page with an ephemeral Lightpanda browser.
+
+    Args:
+        url: The url to fetch
+        log_level: Logging level (default: "error")
+        http_proxy: HTTP proxy URL (optional)
+        http_timeout: HTTP request timeout in seconds (optional)
+
+    Returns:
+        Response: A convenience wrapper around the text response
+
+    Example:
+        >>> response = lightpanda.fetch("http://example.com")
+        >>> json = response.json()
+    """
+    cmd = build_cmd(
+        "fetch",
+        url,
+        dump=True,
+        with_base=with_base,
+        log_level=log_level,
+        http_proxy=http_proxy,
+        http_timeout=http_timeout,
+    )
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"lightpanda failed: {result.stderr}")
+    return Response(result.stdout)