interlocking 0.0.1__py3-none-any.whl

interlocking/line.py

@@ -0,0 +1,78 @@
+"""
+interlocking.line
+============
+Line クラス。FastAPI の APIRouter に相当する「路線定義」。
+
+Station・TrainDispatcher に依存しないため、モジュールレベルで安全にインスタンス化できる。
+タスクモジュールで line = Line() を生成し @line.track() でタスクを定義する。
+InterlockingCLI の Phase 2 で line.register_to(dispatcher, line_name) が呼ばれ TrainDispatcher に登録される。
+track_id は register_to 時に "line_name:track_name" 形式で自動構築される。
+
+使用例::
+
+    # tasks.py
+    from interlocking import Line, Coupler
+    from typing import Annotated
+
+    line = Line()
+
+    @line.track(name="daily", help="日次レポート生成")
+    def daily_report(
+        c: Coupler,
+        target_date: Annotated[str, "対象日付 (YYYY-MM-DD)"],
+    ) -> dict:
+        ...
+
+    # registry.py
+    LINES = {
+        "report": "myapp.tasks:line",
+    }
+    # → track_id = "report:daily" として登録される
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, List
+
+if TYPE_CHECKING:
+    from .dispatcher import TrainDispatcher
+
+# registry の値の型: (func, help)
+_LineEntry = tuple[Callable, str]
+
+
+class Line:
+    """路線定義。タスクを収集し TrainDispatcher に登録する。
+
+    Station に依存しないため、モジュールレベルで安全に生成できる。
+    InterlockingCLI が Phase 2 でモジュールをロードし、
+    line.register_to(dispatcher) を呼んで TrainDispatcher に委譲する。
+    """
+
+    def __init__(self) -> None:
+        self._entries: List[tuple[str, _LineEntry]] = []
+
+    def track(self, name: str, help: str = "") -> Callable:
+        """タスク定義デコレーター。
+
+        Args:
+            name: タスク名（路線内で一意な短い名前）。"line_name:" プレフィックスは不要。
+            help: ヘルプ文字列。
+        """
+        def decorator(func: Callable) -> Callable:
+            self._entries.append((name, (func, help)))
+            return func
+        return decorator
+
+    def register_to(self, dispatcher: "TrainDispatcher", line_name: str) -> None:
+        """収集したタスクを TrainDispatcher に登録する。
+
+        track_id を "line_name:track_name" 形式で構築して登録する。
+        InterlockingCLI の Phase 2 から呼ばれる。
+
+        Args:
+            dispatcher: 登録先のディスパッチャー。
+            line_name:  LINES で定義された路線名（"report" など）。
+        """
+        for track_name, (func, help_text) in self._entries:
+            track_id = f"{line_name}:{track_name}"
+            dispatcher.register(track_id, func, help_text)

interlocking/models.py

@@ -0,0 +1,191 @@
+"""
+interlocking.models
+==============
+コアデータモデル。TrainRecord と Coupler を定義する。
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field, fields
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class SignalStatus(Enum):
+    """Station.check_signal() が報告するロック状態。
+
+    Station は状態を報告するだけで、例外の送出や引き継ぎの判断は Train が行う。
+    """
+
+    CLEAR = "clear"      # 進行可（ロックを取得した）
+    BLOCKED = "blocked"  # 通常の赤信号（他の列車が運行中）
+    STALE = "stale"      # 前回ロックの残骸（ロックは未取得。引き継ぎ待ち）
+
+
+@dataclass
+class TrainRecord:
+    """列車の運行記録。タスクごとの直近 1 回分の状態（Simple State）。
+
+    タスク完了時（成功・失敗）に保存される。abort は status を aborted に更新し、aborted_at / aborted_by を
+    記録する。data / run_id などは保持し（Coupler.last_data を失わない）、error_* はクリアする。
+    abort されたハング中の実行は run_id を持たないため、run_id は最後に完了した実行のもの。
+
+    Attributes:
+        track_id:    タスク識別子（"line_name:track_name" 形式）。
+        run_id:      実行ID。始発（初回実行）では None。
+        run_by:      実行ユーザー。始発では None。
+        track_help:  タスクの説明文（@track の help から設定される）。
+        data:        タスクの戻り値。次回実行時に Coupler.last_data で参照される。
+        status:      実行状態。idle / running / success / failed / aborted。
+        started_at:  開始時刻（Unix タイムスタンプ）。
+        arrived_at:  到着時刻（Unix タイムスタンプ）。
+        force:       force=True（安全装置をすべて解除）で実行された。
+        allow_stale_takeover: allow_stale_takeover=True で実行された。
+        error_type:  失敗したときの例外の型名。
+        error_message: 失敗したときの例外メッセージ。
+        aborted_at:  abort を実行した時刻（Unix タイムスタンプ）。未実行は 0。
+        aborted_by:  abort を実行したユーザー。
+        extra:       このバージョンが知らないキー。Station 拡張や新しいバージョンの
+                     記録を読んでも壊れないよう保持し、保存時にそのまま書き戻す。
+    """
+    track_id: str
+    run_id: Optional[str] = None
+    run_by: Optional[str] = None
+    track_help: Optional[str] = None
+    data: Optional[dict] = None
+    status: str = "idle"
+    started_at: float = 0.0
+    arrived_at: float = 0.0
+    force: bool = False
+    allow_stale_takeover: bool = False
+    error_type: Optional[str] = None
+    error_message: Optional[str] = None
+    aborted_at: float = 0.0
+    aborted_by: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def aborted(self) -> bool:
+        """abort が実行されたかどうか。"""
+        return self.aborted_at > 0
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TrainRecord":
+        """dict から復元する。未知のキーは extra に保持し、エラーにしない。"""
+        known = {f.name for f in fields(cls)}
+        kwargs = {k: v for k, v in data.items() if k in known}
+        unknown = {k: v for k, v in data.items() if k not in known}
+        extra = dict(kwargs.pop("extra", None) or {})
+        extra.update(unknown)
+        return cls(**kwargs, extra=extra)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON シリアライズ可能な dict を返す。extra はトップレベルに展開する。"""
+        data = asdict(self)
+        extra = data.pop("extra")
+        return {**extra, **data}
+
+    @property
+    def elapsed(self) -> float:
+        """経過時間（秒）。started_at と arrived_at から計算される。"""
+        if self.arrived_at > 0 and self.started_at > 0:
+            return round(self.arrived_at - self.started_at, 1)
+        return 0.0
+
+
+@dataclass
+class TrainResult:
+    """TrainDispatcher.depart() の実行結果。
+
+    Attributes:
+        track_id: タスク識別子。
+        run_id:   実行ID。
+        status:   success / failed / blocked / skipped。
+                  blocked は赤信号（多重起動）で実行されなかった場合、
+                  skipped は Middleware が prepare()/run() を呼ばなかった場合。
+        data:     タスクの戻り値（dict 以外・未実行の場合は None）。
+        elapsed:  経過時間（秒）。
+        error:    failed のときの例外。シリアライズ時は文字列化される。
+        is_stale: blocked のうち、前回ロックの残骸（stale）が原因だった場合 True。
+                  復旧には abort か allow_stale_takeover が必要。
+    """
+    track_id: str
+    run_id: Optional[str]
+    status: str
+    data: Optional[dict] = None
+    elapsed: float = 0.0
+    error: Optional[BaseException] = None
+    is_stale: bool = False
+
+    def to_dict(self) -> dict:
+        """JSON シリアライズ可能な dict を返す（Lambda の戻り値など）。"""
+        return {
+            "track_id": self.track_id,
+            "run_id": self.run_id,
+            "status": self.status,
+            "data": self.data,
+            "elapsed": self.elapsed,
+            "error": None if self.error is None else f"{type(self.error).__name__}: {self.error}",
+            "is_stale": self.is_stale,
+        }
+
+
+class SignalBlockedError(Exception):
+    """多重起動が検出されたとき raise される。Train.prepare() から発生する。
+
+    Attributes:
+        track_id: ブロックされたタスク識別子（"line_name:track_name" 形式）。
+    """
+
+    def __init__(self, track_id: str) -> None:
+        self.track_id = track_id
+        super().__init__(f"Signal RED: {track_id} is already in operation.")
+
+
+class StaleLockError(SignalBlockedError):
+    """前回ロックの残骸（stale）が検出されたとき raise される。
+
+    赤信号の一種。自動では引き継がない。復旧は abort か allow_stale_takeover で行う。
+    """
+
+    def __init__(self, track_id: str) -> None:
+        self.track_id = track_id
+        Exception.__init__(
+            self,
+            f"Signal RED (stale): {track_id} has a leftover lock from a previous run. "
+            "Recover with abort, or run with allow_stale_takeover.",
+        )
+
+
+@dataclass
+class Coupler:
+    """連結器。今回(current)と前回(last_stop)の TrainRecord を繋ぐ。
+
+    列車が連結されているイメージ。始発（初回実行）では last_stop は
+    run_id=None の空の TrainRecord。
+
+    Attributes:
+        current:    今回の出発記録（run_id, run_by など）。
+        last_stop:  前回の到着記録。始発時は空の TrainRecord。
+        stale_lock: stale ロックを allow_stale_takeover で引き継いで実行した場合 True。
+    """
+    current: TrainRecord
+    last_stop: TrainRecord
+    stale_lock: bool = False
+
+    @property
+    def last_data(self) -> Optional[dict]:
+        """前回の戻り値（前回の記録の data）。前回の data が None のとき（始発・失敗など）は None。"""
+        return self.last_stop.data
+
+    @property
+    def first_departure(self) -> bool:
+        """始発（初回実行）かどうか。"""
+        return self.last_stop.run_id is None
+
+    @property
+    def extra(self) -> dict:
+        """ログの extra に渡す dict。"""
+        return {
+            "run_id": self.current.run_id,
+            "run_by": self.current.run_by,
+        }