textual-tui

Textual アプリケーション

アプリ、固定された依存関係、エントリーポイント、TCSS、テスト、実際のユーザーワークフローを確認します。独自の描画を行う前に、組み込みウィジェットとコンポジションを選びます。アプリケーションの状態を長時間実行される処理から分離し、キーボード操作を第一級の機能として扱います。すべてのアプリにダッシュボード、モードシステム、コマンドパレットを必須にしないでください。

構成を選ぶ

小規模なツールでは単一の App を使えます。ユーザーのコンテキストが変わる場合は Screen を、短時間の割り込みには ModalScreen を、ローカルな手順には ContentSwitcher を、独立した最上位の画面スタックが本当に必要な場合はモードを使います。スタイル設定とテストには安定した ID と意味的なクラスを使い、幅の広いペインより先に狭いターミナル向けのレイアウトを整えます。動作が要件に合う場合は、DataTable、Tree/DirectoryTree、MarkdownViewer、TextArea、組み込みの入力ウィジェットを優先します。行数のヒューリスティックを満たすためだけに、まとまりのあるコンポーネントを分割しないでください。

必要に応じて、アーキテクチャ、 ウィジェット、または 画面を参照してください。

レスポンシブな処理と状態

並行処理の動作を変更する前に、リアクティビティとワーカーを参照してください。非同期ワーカーはイベントループを共有します。ブロッキング呼び出しは、async def や @work でラップしてもノンブロッキングにはなりません。非同期 API を使い、ブロッキング I/O には thread=True を使い、負荷の高い CPU 処理には適切なプロセスまたはネイティブの方法を使います。

排他的なキャンセルはトランザクションのロールバックではなく、スレッドが停止したことを保証するものでもありません。リクエストのリビジョンを保持し、UI スレッドで結果を適用する際に再確認します。ワーカーの失敗、キャンセル、データなし、データ取得成功を区別します。キャンセルされたリモート書き込みが、すでに実行されている場合もあります。

reactive は更新関連の状態を制御します。var は自動更新やレイアウトを行わずに、リアクティブ機能を保持します。どちらも、リアクティブな動作が不要な場合に通常のフィールドを使う代わりにはなりません。計算メソッドは軽量かつ純粋に保ち、watcher ではブロッキング処理を行わないでください。マウント前のリアクティブ値は、意図を明確にして初期化します。

既存のプロジェクトとソースツール

SKILL_DIR はアプリのリポジトリではなく、このスキルがインストールされたディレクトリを指すように解決します。inspect/audit ヘルパーが示すのはヒューリスティックに基づくソース上の手掛かりであり、アーキテクチャ、実行時のレスポンシブな動作、機能の不足を証明するものではありません。変更する前に、警告対象のコードを読んでください。ヒューリスティックの警告を消すことだけを目的に、パレット、ブラウザー、エクスポート、ブレークポイントの仕組みを追加しないでください。

dump_dom_and_bindings.py は run_test のもとでアプリをインポートして実行します。起動時の処理やネットワーク、ファイルシステムへのアクセスが実行される場合があります。偽のサービスと適切な設定を用意した、認可済みの隔離テスト環境でのみ実行してください。これはソースを受動的に読むものではありません。生成される Pilot テストやスナップショットツールも同様です。

安全なひな形生成

スターターテンプレートは引き続き利用できますが、生成結果はデフォルトでプレビューされます。

python "$SKILL_DIR/scripts/scaffold_textual_app.py" --list-templates
python "$SKILL_DIR/scripts/scaffold_textual_app.py" \
  --template data-explorer --module my_app --class-name MyApp --app-title 'My App'

レンダリングされたアプリ、TCSS、テストを確認してください。書き込むには、親ディレクトリがすでに存在する新しい最終ディレクトリを指定して、--write --output-dir を追加します。強制上書きや自動的な pyproject/CI の設定オプションはありません。自由入力のタイトルは AST の文字列値として挿入され、識別子は検証され、選択されたすべてのテンプレートは書き込み前に解析されます。生成される Python は実行されず、ast.unparse によって再フォーマットされます。書き込みに失敗すると、非公開の不完全な下書きが残る場合があります。複数ファイルに対するアトミックなトランザクションではありません。

チャットのスターターについては、リクエストの所有権とテストを参照してください。明示的な停止アクション、下書きの保持、遅れて届いた結果のチェックは、提供されるサンプルの一部です。ワーカーデコレーターから推測すべき動作ではありません。

選択した出力をアプリに慎重に統合します。新しい汎用ビルドシステムをそのままコピーするのではなく、既存のプロジェクトと現在サポートされている Python／ツールのバージョンに照らして、パッケージングと CI を確認してください。以前の独立した emit ヘルパーは、任意で使える出発点のひな形であり、現行の依存関係／CI ポリシーでも、自動アップグレードの手段でもありません。

ランタイム、配信、テスト

devtools/console/serve については、インストール済みの textual-dev CLI ヘルプを使用してください。serve では、ファイルシステムとサービス権限を持つサーバー側アプリが公開されます。これはサンドボックスでも、自動的に認証境界が設けられる仕組みでもありません。ブラウザーで配信する前に、ネットワークのバインド、認証、テナントの分離、ダウンロード用に提供するファイルを正確に確認してください。ユーザー入力のテキストやターミナル／マークアップのエスケープシーケンスは、信頼できない表示データとして扱ってください。

run_test/Pilot を使って、変更した動作をテストしてください。実際のアサーション、失敗／キャンセル、フォーカスとキーボード操作、狭い／広いサイズ、ティアダウンを含めてください。視覚的なレイアウトが主なリスクとなる場合はスナップショットを使用してください。ただし、すべての変更に必須のノルマとして課すものではありません。固定時間の sleep は、ワーカーやレイアウトが安定した証拠にはなりません。上限時間を設け、観測可能な状態を待ってください。ヘッドレステストだけでは、実際のすべてのターミナル／ブラウザーで同じように描画されることは証明できません。ログをさかのぼって読んでいるときに常に自動で末尾へ移動するのではなく、ユーザーのスクロール位置を維持してください。

パッチ、実際に実行したテストコマンドと結果、未テストのターミナル／ブラウザー経路を報告してください。スターター、構文解析、ゴールデンスクリーンショットだけで本番利用可能だと主張しないでください。テスト、ブラウザー配信、パッケージ化は、該当箇所を参照するための資料として維持してください。

メンテナー向け：python "$SKILL_DIR/scripts/self_check.py" は、すべてのローカルスターター出力を解析します。python -m unittest discover -s "$SKILL_DIR/tests" -v は、スキャフォールドエンジンをテストします。どちらも生成されたアプリを実行しません。

2026-09-13 に確認した情報源：Textual のメタデータ、ワーカー、リアクティビティ、テスト。