tasks

基本情報 [必須]

項目	内容
モジュールパス	tasks/
種別	機能モジュール
ファイル数	5
サブモジュール数	1（backends）

概要 [必須]

Django のバックグラウンドタスク実行フレームワーク。@task デコレータで関数をタスクとして登録し、enqueue() / aenqueue() でバックエンドにキュー追加、call() / acall() で同期/非同期の直接呼び出しを行う。Task データクラスが関数と実行パラメータ（優先度、キュー名、バックエンド、実行時刻）をイミュータブルに保持し、TaskResult が実行結果（ステータス、エラー、戻り値、タイムスタンプ）を管理する。バックエンドは TASKS 設定から BaseConnectionHandler の仕組みで動的に生成・管理され、ConnectionProxy でデフォルトバックエンドへの遅延アクセスを提供する。タスクのライフサイクルイベント（enqueued / started / finished）はシグナルで通知され、ロギングハンドラーが標準で登録される。システムチェック機構によりバックエンド設定の妥当性を起動時に検証する。

設計パターン [必須]

パターン名	適用範囲	説明
Immutable Object	Task / TaskResult / TaskError / TaskContext	frozen=True の dataclass でイミュータブル性を保証
Decorator	task()	関数を Task インスタンスに変換するデコレータ
Factory	TaskBackendHandler.create_connection	設定からバックエンドインスタンスを動的生成
Strategy	Task.get_backend() / バックエンド切り替え	バックエンドによる実行戦略の変更
Proxy	default_task_backend (ConnectionProxy)	デフォルトバックエンドへの遅延アクセスプロキシ
Observer	task_enqueued / task_started / task_finished	シグナルによるライフサイクルイベント通知
Builder	Task.using()	パラメータ変更した新 Task を replace() で生成
Facade	init.py	サブモジュールの公開 API を単一パッケージに集約
Enum	TaskResultStatus	TextChoices による 4 状態の列挙

アーキテクチャ [必須]

モジュール構成

tasks/
├── __init__.py      - パッケージ初期化、TaskBackendHandler、公開 API の再エクスポート
├── base.py          - Task / TaskResult / TaskError / TaskContext / TaskResultStatus / task()
├── checks.py        - バックエンドのシステムチェック
├── exceptions.py    - タスク関連例外クラス
├── signals.py       - ライフサイクルシグナルとログハンドラー
└── backends/        - バックエンド実装（サブモジュール）

コンポーネント関連図

Mermaid形式:

graph TD
    USER["ユーザーコード"] -->|"@task"| TASK["base.py<br>Task"]
    TASK -->|"enqueue()"| HANDLER["__init__.py<br>TaskBackendHandler"]
    HANDLER --> BACKEND["backends/<br>バックエンド実装"]
    BACKEND --> RESULT["base.py<br>TaskResult"]
    TASK -->|"call()"| DIRECT["タスク関数直接実行"]
    BACKEND -->|"signal"| SIGNALS["signals.py<br>task_enqueued / started / finished"]
    SIGNALS --> LOG["ロギング"]
    TASK -->|"using()"| TASK2["新 Task インスタンス"]
    USER -->|"get_result()"| RESULT

機能一覧 [必須]

機能名	説明	主要ファイル
タスク定義	@task デコレータによる関数のタスク化	base.py
タスクキューイング	enqueue() / aenqueue() によるバックエンドへのキュー追加	base.py
タスク直接実行	call() / acall() による同期/非同期の直接呼び出し	base.py
パラメータ変更	using() による優先度・キュー名・実行時刻・バックエンドの変更	base.py
タスク結果管理	TaskResult によるステータス・エラー・戻り値・タイムスタンプの管理	base.py
結果再読み込み	refresh() / arefresh() によるバックエンドからの最新データ取得	base.py
バックエンド管理	TASKS 設定に基づくバックエンドの動的生成・管理	init.py
ライフサイクル通知	シグナルによるキュー追加・開始・完了イベントの通知	signals.py
ログ出力	タスクイベントの自動ログ出力（debug/info/error）	signals.py
設定チェック	バックエンド設定の妥当性検証	checks.py
例外階層	タスク関連例外の体系的な定義	exceptions.py

公開インターフェース [必須]

クラス / 関数

名前	種別	用途
Task	class (dataclass)	タスク定義（関数 + 実行パラメータ）
TaskResult	class (dataclass)	タスク実行結果の保持と管理
TaskResultStatus	class (TextChoices)	タスク結果のステータス列挙（READY/RUNNING/FAILED/SUCCESSFUL）
TaskContext	class (dataclass)	タスク実行時コンテキスト
TaskError	class (dataclass)	タスクエラー情報（例外クラスパス + トレースバック）
task	function	関数を Task に変換するデコレータ
task_backends	TaskBackendHandler	バックエンド接続ハンドラー
default_task_backend	ConnectionProxy	デフォルトバックエンドのプロキシ
TaskException	class	タスク例外の基底クラス
InvalidTask	class	不正な Task の例外
InvalidTaskBackend	class	不正なバックエンド設定の例外
TaskResultDoesNotExist	class	TaskResult が見つからない例外
TaskResultMismatch	class	TaskResult が別の Task に属する例外
task_enqueued	Signal	タスクキュー追加シグナル
task_started	Signal	タスク開始シグナル
task_finished	Signal	タスク完了シグナル
DEFAULT_TASK_BACKEND_ALIAS	str	デフォルトバックエンドエイリアス（"default"）
DEFAULT_TASK_QUEUE_NAME	str	デフォルトキュー名（"default"）

依存関係 [必須]

外部依存（このモジュールが依存する外部パッケージ）

パッケージ	主要クラス	用途
asgiref	async_to_sync, sync_to_async, Local	Task.call/acall の同期/非同期変換、バックエンドのスレッドローカル管理

外部依存（このモジュールが依存する内部モジュール）

依存先モジュール	主要クラス	用途
django/conf	settings	TASKS 設定の参照
django/core/checks	@checks.register	システムチェックの登録
django/core/exceptions	ImproperlyConfigured	InvalidTaskBackend の基底クラス
django/core/signals	setting_changed	設定変更シグナルの受信
django/db/models/enums	TextChoices	TaskResultStatus の基底クラス
django/dispatch	Signal, receiver	シグナルの定義とハンドラー登録
django/utils/connection	BaseConnectionHandler, ConnectionProxy	バックエンドハンドラーとプロキシ
django/utils/json	normalize_json	TaskResult の引数正規化
django/utils/module_loading	import_string	バックエンド/関数の動的インポート
django/utils/translation	pgettext_lazy	TaskResultStatus ラベルの遅延翻訳

内部依存（このモジュールに依存するもの）[最重要]

依存元モジュール	主要ファイル	用途
django/tasks/backends	base.py, dummy.py, immediate.py	Task, TaskResult, TaskResultStatus, TaskContext, TaskError, 例外クラス、シグナルのインポート
django/conf	global_settings.py	TASKS 設定のデフォルト値（ImmediateBackend）

データフロー [必須]

Mermaid形式:

flowchart TD
    USER["ユーザーコード"] -->|"@task"| DECORATOR["task()"]
    DECORATOR --> TASK["Task インスタンス"]
    TASK -->|"enqueue()"| BACKEND["バックエンド.enqueue()"]
    BACKEND --> SIG_E["task_enqueued シグナル"]
    BACKEND --> RESULT_READY["TaskResult<br>status=READY"]
    RESULT_READY -->|"バックエンド実行"| SIG_S["task_started シグナル"]
    SIG_S --> EXEC["func(*args, **kwargs)"]
    EXEC -->|"成功"| RESULT_OK["TaskResult<br>status=SUCCESSFUL"]
    EXEC -->|"失敗"| RESULT_NG["TaskResult<br>status=FAILED"]
    RESULT_OK --> SIG_F["task_finished シグナル"]
    RESULT_NG --> SIG_F
    USER -->|"get_result()"| RESULT_OK
    RESULT_OK -->|"return_value"| RV["戻り値"]
    RESULT_OK -->|"refresh()"| REFRESH["バックエンドから再取得"]

セキュリティ考慮 [必須]

観点	対策状況	詳細
入力検証	あり	Task.post_init でバックエンドのバリデーション。task() で run_after の静的定義を禁止
シリアライゼーション	あり	Task.reduce で pickle 用のカスタムシリアライズ。_reconstruct で復元時にモジュールパスを検証
例外クラス解決	あり	TaskError.exception_class で isclass / issubclass(BaseException) の検証
設定検証	あり	TaskBackendHandler が不正なバックエンドクラスの import を検出。check_tasks でバックエンド設定を検証
ログ出力	あり	タスクイベントの自動ログ出力。失敗時はトレースバック付き ERROR ログ

技術的負債・既知の問題 [必須]

種別	内容	影響範囲	優先度
設計	TaskResult.refresh() が frozen dataclass に対して object.setattr で直接属性を上書きする	base.py	低

拡張ポイント [必須]

変更内容	修正対象ファイル	手順・注意点
カスタムバックエンド	TASKS 設定	BACKEND にカスタムクラスのパスを指定。backends/base.py の BaseTaskBackend を継承
複数バックエンド	TASKS 設定	複数のエイリアスを定義し、@task(backend="alias") で切り替え
タスクパラメータ変更	対象コード	Task.using(priority=..., queue_name=..., run_after=..., backend=...) で新インスタンスを生成
カスタムシグナルハンドラー	対象アプリ	task_enqueued / task_started / task_finished に @receiver でハンドラーを登録
カスタム Task クラス	バックエンドの task_class	バックエンドの task_class 属性で Task のサブクラスを使用

注意点・特記事項 [必須]

• 設計上の制約: Task は frozen dataclass であり、パラメータ変更は using() による新インスタンス生成で行う。run_after は @task デコレータでは設定不可（using() のみ）
• パフォーマンス: TaskResult.refresh() は frozen dataclass に対して object.__setattr__ で直接更新するため、新インスタンス生成のオーバーヘッドを回避する
• 互換性: Task.call() / acall() は asgiref を使って同期/非同期の相互変換を行う。task_backends は BaseConnectionHandler を継承し、Django の DB / Cache 等と同じ接続管理パターンに従う

配下ドキュメント [必須]

サブモジュール

• backends.md - バックエンド実装（base / dummy / immediate）

ファイル

• init.py.md - パッケージ初期化、TaskBackendHandler、公開 API の再エクスポート
• base.py.md - Task / TaskResult / TaskError / TaskContext / TaskResultStatus / task()
• checks.py.md - バックエンドのシステムチェック
• exceptions.py.md - タスク関連例外クラス
• signals.py.md - ライフサイクルシグナルとログハンドラー