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://your-hub.example:8000/jobs/08dbe3379087/assets/120px-Felis_chaus_-_…jpg
  http://your-hub.example:8000/jobs/08dbe3379087/assets/120px-Gustav_chocolate.jpg
  http://your-hub.example: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

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

現在は Job API + Session ライフサイクル（投入・状態取得・アセット・セッション開閉）まで対応しています。 Page/Locator/walk は順次対応予定です。当面 Page 操作が必要なときは Python 版または HTTP API をご利用ください。

インストール

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";
    // 順次対応: $sess->goto(...), $sess->locator(...) ...
});

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

Session の現行サーフェス

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

例外

PaprikaClient (cli.*)

Job ライフサイクル

asset（画像・動画）取得

Page クラス全メソッド

Page クラスの全メソッド (ナビゲーション・取得・JS 実行・収集・拡張機能コマンド・タブ操作) は単独ページに分けました。引数・戻り値・例まで含む詳細はこちらへ:

→ Page クラス リファレンス

Page クラスへの古いアンカー (#nav, #getters, #evaluate, #assets, #agent-ext, #tabs) は api-page.html へ自動転送されます。

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_*() が返す要素参照。解決はアクション時です（click() や wait_for() を呼んだ時点で初めて DOM を探します）。

全メソッド（クリック・入力・取得・状態判定・チェーン・待機）と用例は Locator リファレンス に集約しました。

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）。

全オプション（15 項目）・Visit フィールド・attempt 跨ぎ再開・パスの正規表現フィルタなどの完全リファレンスは walk リファレンス に集約しました。

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")   # 各ページで画像保存など

ワンショットヘルパー

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

ライブログ（WebSocket）

ジョブの実行ログを **リアルタイム** で受信する WebSocket。長時間ジョブやライブ表示で使います。

ws://<hub>/jobs/{job_id}/events?since=N

メッセージは JSON 1 行（{type: "log" | "done" | "error", data: ...}）。since= で途中接続・再接続にも追従できます。

仕様・JS/Python の実装例・再接続戦略は WebSocket リファレンス を参照。

例外