drissionpage-dev

DrissionPage Dev

概要

このスキルを使うと、references/docs/ にある公式ドキュメントを参照し、一貫したワークフローに従って、信頼性の高い DrissionPage の Python オートメーションを構築できます。

設定の優先事項

• 長時間の「クエリ待機」フローでは、DrissionPage のネイティブな待機 API を使用しないでください。代わりに、静的な HTML（tab.html／スナップショット）をポーリングし、parsel.Selector（または同等の HTML パーサー）で解析して状態の遷移を検出してください。
• DrissionPage のネイティブな「準備完了」チェックの信頼性が低い場合は、使用しないでください。代わりに、安定したページマーカー（メインコンテンツのマウント、CAPTCHA／オーバーレイの表示または消失など）を静的な DOM から解析して、準備完了チェックを実装してください。
• 開発中にローカルのオートメーションブラウザーを起動する場合は、ChromiumOptions().auto_port(True) をデフォルトで使用してください。これにより DrissionPage は、デフォルトの 127.0.0.1:9222 のインスタンスと競合するのではなく、分離されたポートとユーザーデータディレクトリで新しいブラウザーを起動します。
• 特定の既存ブラウザー、固定のデバッグポート、再利用するプロファイル、または外部管理のブラウザープロセスへの接続が必要なタスクでは、auto_port(True) を有効にしないでください。その場合は、set_local_port()、set_address()、set_user_data_path() を明示的に設定してください。
• run_js(..., as_expr=True) は式のみのモードとして扱ってください。この形式では return を決して含めないでください。スクリプトに return、制御フロー、または複数の文が必要な場合は、デフォルトの関数本体モードを使用してください。原因不明のポーリング失敗をデバッグする場合は、まずこの不一致を確認してください。DrissionPage は as_expr=True と return の併用時に例外を発生させます。
• run_js()／run_js_loaded()／run_async_js() には、DrissionPage がサポートするプリミティブ型の引数のみを渡してください。Python の list、dict、None、カスタムオブジェクト、その他の複雑な値を直接渡さないでください。複雑なデータは json.dumps() でシリアライズし、JavaScript 内で JSON.parse() を使って解析してください。また、None などのオプショナルな値は、run_js() を呼び出す前に空文字列などの明示的なプリミティブ値に正規化してください。

フェーズゲート付きワークフロー

以下のレガシーワークフローの詳細に進む前に、このフェーズゲートに従ってください。

開発フェーズ

1. オートメーションの目標を明確にし、SessionPage、ChromiumPage、WebPage のいずれかを選択します。
2. インタラクションを実装する前に、起動方法を明示的に設定します。
3. 実際の DOM または同梱ドキュメントから、安定したページマーカーとセレクターを特定します。
4. まずは最小限で信頼できる経路を実装します。ページ遷移、待機／準備完了チェック、要素の特定、操作／抽出、結果の検証を行います。
5. ダウンロード、アップロード、ネットワークのリスニング、複数タブの処理、フォールバックのポーリングは、基本の経路が機能してから追加します。
6. 待機、リトライ、JavaScript の実行、例外処理を、ページ状態の失敗を黙って握りつぶすのではなく、観測できるようにします。

検査フェーズ

引き継ぎ前に、次の固定チェックリストを実行してください。

• 選択したページモードが、対象（HTTP のみ、ブラウザーでレンダリング、またはブラウザー／セッションの混在動作）に適合していることを確認します。
• 特定の管理対象ブラウザーへの接続が必要な場合を除き、破棄可能な開発用ブラウザーの起動に auto_port(True) が使用されていることを確認します。
• ロケーターが実際の DOM、または同梱の DrissionPage のロケーターに関するドキュメントに照らして確認されていることを確認します。
• 待機に安定したページマーカーまたは明示的な準備完了条件が使われ、長時間のクエリ待機が信頼性の低いネイティブな準備完了チェックに依存していないことを確認します。
• run_js(..., as_expr=True) に式のみの JavaScript が含まれ、サポートされているプリミティブ型の引数のみが渡されていることを確認します。
• ポーリング、リトライ、クリーンアップ、フォールバックの各経路における例外処理が必要なものに限定され、状況を示す情報とともにログに記録されることを確認します。
• スクリプトに、エンドツーエンドのオートメーションフローを実証する実行可能なスモークテストの経路があることを確認します。

レガシーワークフロー

1) 目的を明確にして、モードを選択する

• 対象データが HTTP レスポンス経由で取得でき、JS のレンダリングが不要な場合は、SessionPage を優先してください。
• 実際の Chromium ブラウザーを実行する必要がある場合（JS のレンダリング、複雑なログイン、ボット対策フロー、ファイルダイアログなど）は、ChromiumPage を優先してください。
• 同じオブジェクトでブラウザー操作とパケットの送受信（モード切り替え）の両方が必要な場合は、WebPage を優先してください。

ドキュメント：

• references/docs/🌏 导入 - DrissionPage官网.md（主要クラスとインポートパス）
• references/docs/⭐ 模式切换 - DrissionPage官网.md と references/docs/🗺️ 模式切换 - DrissionPage官网.md（モード切り替え）

2) オブジェクトを作成し、起動時の設定を行う

• ブラウザーの起動パラメーターには ChromiumOptions を使用してください。オプションはブラウザーの起動時にのみ適用され、既存のブラウザーへの接続時には適用されない点に注意してください。
• 日常的なローカル開発では、まず auto_port(True) を使用してください。DrissionPage が 127.0.0.1:9222 を試し、自動化対象ではない Chrome や古いポートを見つけて BrowserConnectError を発生させる、よくある失敗を回避できます。
• ブラウザーの起動モードは、明示的に選択してください。
  • 開発やデバッグ中に使い捨ての新しいブラウザーを起動する場合は、auto_port(True) を使用してください。
  • 既存のブラウザーへの再接続が意図的に必要な場合に限り、固定ポートまたは明示的なアドレスを使用してください。
• SessionPage／WebPage の s モードの設定には SessionOptions を使用してください。
• 全体的な動作（要素が見つからない場合に例外を発生させるかどうかなど）には Settings を使用してください。

ドキュメント：

• references/docs/🌏 导入 - DrissionPage官网.md
• references/docs/🛩️ 创建页面对象 - DrissionPage官网.md
• references/docs/🛩️ 启动配置 - DrissionPage官网.md
• references/docs/⚙️ 全局设置 - DrissionPage官网.md

3) 公式の構文で要素を特定する

• 特定構文の正確な情報源としてドキュメントを使用し、セレクター形式を推測しないでください。
• リファクタリングの際は、ロケーターを一元管理し、スリープより明示的な待機を優先してください。

ドキュメント：

• references/docs/🔦 概述 - DrissionPage官网.md
• references/docs/🔦 定位语法 - DrissionPage官网.md
• references/docs/🔦 语法速查表 - DrissionPage官网.md
• references/docs/🔦 相对定位 - DrissionPage官网.md
• references/docs/🔦 在结果列表中筛选 - DrissionPage官网.md

4) 操作、待機、フレーム／タブへの対応

• 安定性を高めるため、専用の待機 API を使用し、タイムアウトを重要な要素として扱ってください。
• iframe は明示的に処理してください。
• 新しいウィンドウ／タブを扱う場合は、タブ管理 API を使用してください。

ドキュメント：

• references/docs/🛰️ 元素交互 - DrissionPage官网.md
• references/docs/🛰️ 等待 - DrissionPage官网.md
• references/docs/🛰️ iframe 操作 - DrissionPage官网.md
• references/docs/🛰️ 标签页管理 - DrissionPage官网.md

5) ダウンロード、アップロード、ネットワークのデバッグ

• ダウンロードには、ドキュメントに記載された download／ブラウザーのダウンロードフローを使用してください。
• アップロードにはアップロードのドキュメントを参照し、安定したファイル選択方法を優先してください。
• 不安定なフローをデバッグするには、スクリーンショット／録画、コンソールログ、ネットワークの監視を使用してください。

ドキュメント：

• references/docs/⭐ 下载文件 - DrissionPage官网.md
• references/docs/⤵️ download方法 - DrissionPage官网.md
• references/docs/⤵️ 浏览器下载 - DrissionPage官网.md
• references/docs/🛰️ 上传文件 - DrissionPage官网.md
• references/docs/🛰️ 截图和录像 - DrissionPage官网.md
• references/docs/🛰️ 获取控制台信息 - DrissionPage官网.md
• references/docs/🛰️ 监听网络数据 - DrissionPage官网.md

6) 例外とトラブルシューティング

• DrissionPage の例外は意図的に捕捉して処理し、すべてを一括して捕捉しないでください。
• run_js() のポーリングや待機では、スクリプトの形式やページ状態の不具合を隠す可能性のある例外を黙って握りつぶさないでください。例外のコンテキストをログに記録するか、例外の種類を絞り込み、as_expr=True と return の併用のような誤りが直ちに表面化するようにしてください。
• run_js() が list や NoneType などのサポートされていない引数型エラーを発生させる場合は、呼び出し元を修正してプリミティブ型だけを渡してください。セレクター配列の場合は json.dumps(selectors) を渡し、スクリプト内で JSON.parse(arguments[0]) を使用してください。
• 動作が想定と異なる場合は、FAQ を参照してください。

ドキュメント：

• references/docs/⚙️ 异常的使用 - DrissionPage官网.md
• references/docs/❓ 常见问题 - DrissionPage官网.md

クイック検索レシピ（Codex 向け）

• 同梱ドキュメントをキーワードで検索します：

  • rg -n -S "<keyword>" references/docs
  • 英語の用語を大文字と小文字を区別せずに検索する場合：rg -n -i "<keyword>" references/docs

• API 名がわかっている場合は、識別子で検索します：

  • rg -n -S "\\bChromiumPage\\b" references/docs
  • rg -n -S "\\bSessionPage\\b" references/docs

最小限のスターターコード

パラメーターと戻り値の情報は、ドキュメントを正としてください。

from DrissionPage import ChromiumPage, WebPage, SessionPage
from DrissionPage import ChromiumOptions, SessionOptions
from DrissionPage.common import Settings

co = ChromiumOptions()
co.auto_port(True)  # Default for local development: isolated port + user data dir

page = ChromiumPage(addr_or_opts=co)