API リファレンス

paprika_client の全公開関数。 Session は Page を継承するので page.* はセッションでもそのまま使えます。

接続

async_paprika.connect(base_url=None, *, token=None, timeout=180.0) → PaprikaClient

ハブへの接続。接続先は 引数 → PAPRIKA_HUB → http://localhost:8000。

async with async_paprika.connect() as cli:
    ...

with sync_paprika.connect() as cli:
    ...

use Paprika\Client\Paprika;

$cli = Paprika::connect();   // PAPRIKA_HUB or http://localhost:8000
// ...

同期版（sync_paprika）

async/await を使えない・使いたくない場面（簡単なスクリプト、ノートブック、既存の同期コード）向けに、 非同期 API を 1:1 でブロッキングに写した同期ファサードがあります。裏でバックグラウンドの asyncio ループに橋渡しするだけなので、メソッド名・引数・戻り値は async 版と同一（await を外すだけ）。

例1: セッションを動かす

Hacker News のトップ記事をクリックして、辿り着いた先の URL とタイトルを表示します。

from paprika_client import sync_paprika

with sync_paprika.connect() as cli:                      # await 不要
    with cli.session("https://news.ycombinator.com") as page:
        page.locator(".athing .titleline > a").first.click()
        st = page.state()
        print("url:  ", st["url"])
        print("title:", st["title"])

実行結果（例）:

url:   https://www.anthropic.com/research/glasswing-initial-update
title: Project Glasswing: An initial update \ Anthropic

例2: fetch で画像を一括取得

Wikipedia の記事を fetch ジョブで丸ごと取得し、保存された画像の URL を表示します。

from paprika_client import sync_paprika

with sync_paprika.connect() as cli:
    job = cli.fetch("https://en.wikipedia.org/wiki/Cat", scroll=True)
    imgs = cli.job_images(job["job_id"])
    print("status:", job["status"])
    print("images:", len(imgs))
    print("first 3:")
    for u in imgs[:3]:
        print(" ", u)

実行結果（例）:

status: completed
images: 49
first 3:
  http://paprika.lan:8000/jobs/08dbe3379087/assets/120px-Felis_chaus_-_…jpg
  http://paprika.lan:8000/jobs/08dbe3379087/assets/120px-Gustav_chocolate.jpg
  http://paprika.lan:8000/jobs/08dbe3379087/assets/120px-Orange_tabby_cat_…jpg

本リファレンスの cli.* / page.* / loc.* がそのまま（同期で）使えます。 connect(base_url=None, *, token=None, timeout=180.0, auto_start=True) が既定でループを起動します。 既定では各アクションが [paprika] page.X(...) 形式でログに流れます（無効化は PAPRIKA_CLIENT_ACTION_LOG=0）。

PHP SDK (Phase 1)

PHP からも同じハブを叩けます。同期・外部依存なし (ext-curl のみ)・PHP 8.1+。 Composer パッケージ paprika/client。命名は Python 版を snake_case → camelCase に直したもの (例: job_images → jobImages)。

現在の Phase 1 は Job API + Session ライフサイクル。 Page/Locator/walk は Phase 2 で対応予定です。

インストール

composer require paprika/client

例: fetch ジョブを投げて画像を集める

<?php
require 'vendor/autoload.php';

use Paprika\Client\Paprika;

$cli = Paprika::connect();   // PAPRIKA_HUB or http://localhost:8000
$job = $cli->fetch('https://en.wikipedia.org/wiki/Cat', scroll: true);
echo "status: {$job['status']}\n";

foreach ($cli->jobImages($job['job_id']) as $u) {
    echo $u, "\n";
}

例: ライブセッションを開く

use Paprika\Client\Paprika;
use Paprika\Client\Session;

$cli = Paprika::connect();
$cli->session('https://example.com', function (Session $sess) use ($cli) {
    echo "noVNC: ", $cli->baseUrl() . $sess->novncUrl, "\n";
    // Phase 2: $sess->goto(...), $sess->locator(...) ...
});

Phase 1 で使える $cli->* メソッド (Python 版と1:1)

Session の Phase 1 サーフェス

• プロパティ (readonly): $sess->sessionId / workerId / laneIdx / novncUrl
• $sess->close() — DELETE /sessions/{id} (idempotent / 安全)
• $sess->detach() — POST /sessions/{id}/detach。クロージャ form の自動 close をスキップ
• (Phase 2) goto / click / fill / locator / screenshot / state / outline / ...

例外

PaprikaClient (cli.*)

Job ライフサイクル

asset（画像・動画）取得

Page — ナビゲーション・操作

プロパティ（I/O なし）: page.url / session_id / worker_id / lane_idx / novnc_url / page_id。

await page.goto("https://example.com")
await page.fill("#email", "user@example.com")
await page.press("Enter")
await page.set_input_files("input[type=file]", ["a.jpg", "b.jpg"])

page.goto("https://example.com")
page.fill("#email", "user@example.com")
page.press("Enter")
page.set_input_files("input[type=file]", ["a.jpg", "b.jpg"])

Page — 取得・待機・状態

Page — JS 実行・ロケータ生成

page.evaluate(expression, *, await_promise=False) → 値

任意 JS を実行し評価値を返す（JSON 化可能な値のみ）。取得・待機・入力系はこれが土台。

title = await page.evaluate("document.title")
data  = await page.evaluate("fetch('/api').then(r=>r.json())", await_promise=True)

title = page.evaluate("document.title")
data  = page.evaluate("fetch('/api').then(r=>r.json())", await_promise=True)

Page — 収集・Cookie・LLM・永続状態

Page — タブ・ライフサイクル

Session 固有

Session は Page ＋ 複数タブ操作の拡張：

• シーケンス操作: len(sess) / sess[i] / for t in sess
• sess.front / front_index / current（プロパティ）— 前面タブ
• sess.refresh() → list[Page] — タブ一覧を再取得する
• sess.switch(idx=None) → dict — idx のタブを前面に
• sess.close_popups() → int — 既定タブ以外（popup）を全部閉じる

Locator

page.locator(sel) / get_by_*() が返す。解決はアクション時。

rows = page.locator(".item")
for r in await rows.all():
    print(await r.get_attribute("data-id"))
await rows.first.click()

rows = page.locator(".item")
for r in rows.all():
    print(r.get_attribute("data-id"))
rows.first.click()

サイト巡回（walk / Walker）

「サイト X のページを N 件巡回」のようなクロールを、キュー・重複除去・ドメイン/パスのフィルタ・ オフスコープ redirect 対応まで込みで回す高レベルヘルパー。手書きのループより堅牢です。 walk(page, **opts) は Visit を yield する非同期イテレータ（クラス版は Walker）。

from paprika_client import async_paprika, walk

async with async_paprika.connect() as cli:
    async with cli.session("https://example.com", parent_job_id="crawl") as page:
        async for visit in walk(page, target_pages=50, same_domain=True):
            print(visit.n, visit.depth, visit.url)
            await page.save_assets("out/images")   # 各ページで画像保存など

Visit は n / url / requested_url / depth / outline / page を持ちます（page はそのページに居る Page）。

ワンショットヘルパー

1 動作だけしてセッションを閉じる糖衣です。インポートは from paprika_client import snapshot, outline, state, run です。

例外