walk — サイト巡回(BFS / DFS)

Paprika の walk() / Walker でサイトを BFS/DFS で巡回する完全リファレンス — start_url / target_pages / same_domain / allowed_domains / allow_paths / deny_paths / order / max_depth / per_page_timeout_s / persist_state / host_dedup / recrawl_patterns、Visit のフィールド、ベストプラクティス。

walk() はサイトを BFS / DFS で巡回しながら 1 ページずつ Visit を yield する非同期イテレータです。キュー・重複除去・ドメインとパスのフィルタ・オフスコープ redirect 対応まで内部で処理するので、自前の BFS ループより堅牢です。

全体像は Client インストール / ガイド / 目的別の例は ユースケース。

最小例

import asyncio
from paprika_client import paprika, walk

async def main():
    async with paprika() 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(f"[{visit.n}/{visit.target}] depth={visit.depth} {visit.url}")
                await page.save_assets("out/images")

asyncio.run(main())

• walk(page, **opts) は Visit を yield する AsyncIterator。クラス版は Walker（ステートを覗きたいとき）。
• ループ中で await page.save_assets(...) などを呼べば、そのページのアセットを保存できます。

walk は async のみ。sync_paprika から直接は使えません（asyncio.run() でラップしてください）。

オプション一覧（完全版）

Visit のフィールド

walk() が yield するのは Visit インスタンス。ページの読み込みに成功したときだけ yield されます（失敗・オフドメイン・フィルタ除外は無音でスキップ）。

進捗を表示する典型:

async for visit in walk(page, target_pages=200):
    print(f"[{visit.n}/{visit.target}] depth={visit.depth} {visit.url}")

巡回範囲の絞り込み

同じドメインだけ

walk(page, target_pages=200, same_domain=True)

複数ドメインを許可

walk(
    page,
    target_pages=500,
    allowed_domains=["example.com", "cdn.example.com"],
)

パスを許可・除外（正規表現）

walk(
    page,
    target_pages=300,
    allow_paths=[r"^/articles/"],
    deny_paths=[r"^/admin/", r"\.pdf$"],
)

deny_defaults=True（既定）のときは、管理画面・ログイン・カート・印刷ビューなどの経験則的な除外もあわせて適用されます。

階層・順序

walk(page, target_pages=300, max_depth=2, order="dfs")

失敗の扱い

walk() は成功した訪問だけ yield します。失敗ページ・オフドメイン redirect・フィルタ除外は walker が無音でスキップするので、ループ内で握りつぶす必要はありません。

各ページ内の処理が落ちた場合だけ try で囲ってください:

async for visit in walk(page, target_pages=300):
    try:
        await page.save_assets("out/images")
    except Exception as e:
        print(f"  skip {visit.url}: {e}")

attempt 跨ぎで再開

persist_state=True（既定）のとき、walker の進捗（crawled / queue）は parent job のディスクに保存されます。途中で止まっても、同じ parent_job_id で再開すれば続きから走ります。

async with cli.session("https://example.com", parent_job_id="crawl-001") as page:
    async for visit in walk(page, target_pages=10000, persist_state=True):
        ...

クラス版 Walker

walk() は内部で Walker を作っています。ステートを覗きたい / 別の場所で組み立てたい場合に使います。

from paprika_client import Walker

walker = Walker(page, target_pages=200, same_domain=True)
async for visit in walker:
    ...
print(len(walker.crawled), "pages crawled")
print(len(walker.queue), "still in queue")

ベストプラクティス

• target_pages を明示する — 無限に走らせないための基本。
• max_depth で浅く保つ — フッタの外部リンクから無関係なドメインに迷い込まないように。
• ループ内のサンプル数は visit.n を使う — 自分で i++ カウントしない（dedup でスキップされるとずれる）。
• requested_url と url の食い違いに注意 — 強制リダイレクトされたページを記録するなら visit.url を、リンク元 URL を残したいなら visit.requested_url を。
• 長時間クロールは persist_state=True — 失敗時に最初からやり直さずに済みます。

関連

• API リファレンス: walk
• ガイド: サイトを巡回（walk）
• ユースケース: サイト全体をアーカイブ