interlocking 0.0.1__py3-none-any.whl

interlocking/__init__.py

@@ -0,0 +1,49 @@
+"""
+interlocking
+=======
+One track, one train.
+Easy to run. Explicit to control.
+
+分散環境におけるバックグラウンドタスクの「運行管理」フレームワーク。
+
+公開 API::
+
+    from interlocking import Line, Coupler
+    from interlocking import InterlockingCLI, TrainDispatcher, LocalStation
+"""
+from .cli import ExitCode, InterlockingCLI
+from .dispatcher import Train, TrainDispatcher, TrainMiddleware
+from .line import Line
+from .models import (
+    Coupler,
+    SignalBlockedError,
+    SignalStatus,
+    StaleLockError,
+    TrainRecord,
+    TrainResult,
+)
+from .station import LocalStation, S3Station, Station
+
+__all__ = [
+    # CLI ビルダー
+    "InterlockingCLI",
+    "ExitCode",
+    # 路線定義（Router）
+    "Line",
+    # モデル
+    "Coupler",
+    "TrainRecord",
+    "TrainResult",
+    # ディスパッチャー
+    "Train",
+    "TrainDispatcher",
+    "TrainMiddleware",
+    # 例外
+    "SignalBlockedError",
+    "StaleLockError",
+    # ストレージ
+    "Station",
+    "SignalStatus",
+    "LocalStation",
+    "S3Station",
+]

interlocking/cli.py

@@ -0,0 +1,264 @@
+"""
+interlocking.cli
+===========
+interlocking を使った CLI の共通ビルダー。
+
+argparse の2ステップインターフェースに準拠する::
+
+    cli = InterlockingCLI(
+        dispatcher=dispatcher,
+        prog="sails-task2",
+        description="SAILSタスク実行コマンド",
+    )
+    args = cli.parse_args()          # パーサー構築 + 引数解析
+    context.setup_logging(args.log_config)
+    sys.exit(cli.execute(args))      # タスク実行。結果を終了コード（ExitCode）で返す
+"""
+from __future__ import annotations
+
+import argparse
+import inspect
+import sys
+from enum import IntEnum
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Optional,
+    Tuple,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from .dispatcher import TrainDispatcher
+from .models import Coupler, TrainResult
+
+
+class ExitCode(IntEnum):
+    """CLI の終了コード。cron など上位のオーケストレーターが結果を判別するための規約。"""
+
+    SUCCESS = 0
+    FAILED = 1   # タスクが失敗した
+    USAGE = 2    # argparse の引数エラー（argparse が返す。interlocking はこの値を他の用途に使わない）
+    BLOCKED = 3  # 赤信号（他の列車が運行中）で実行されなかった
+    STALE = 4    # 前回ロックの残骸（stale）で実行されなかった。復旧が必要
+    SKIPPED = 5  # Middleware が実行を見送った
+
+
+def _exit_code(result: TrainResult) -> ExitCode:
+    """depart() の結果を終了コードに変換する。判断できないときは失敗扱いにする。"""
+    if result.status == "success":
+        return ExitCode.SUCCESS
+    if result.status == "blocked":
+        return ExitCode.STALE if result.is_stale else ExitCode.BLOCKED
+    if result.status == "skipped":
+        return ExitCode.SKIPPED
+    return ExitCode.FAILED
+
+# InterlockingCLI 内部で使用する共通キー（params の抄出時に除外）
+_INTERLOCKING_PARAM_KEYS: frozenset = frozenset({
+    "command", "track_id", "line", "force", "allow_stale_takeover", "stale_after", "run_id", "run_by", "parser",
+})
+
+
+def _setup_argparsers(registry: Dict[str, Tuple[Callable, str]], parsers: Any, line_name: Optional[str] = None) -> None:
+    """路線 registry から argparse サブパーサーを構築する。
+
+    関数の型ヒント (Annotated[Type, "help"]) から引数定義を自動生成する。
+    Annotated でない引数（Coupler 以外）はエラーとなる。
+
+    Args:
+        registry:  TrainDispatcher.registry（line_name でフィルタ済みを推奨）。
+        parsers:   argparse の add_subparsers() の戻り値。
+        line_name: 指定時は "line_name:track_name" の track_name 部分をサブコマンド名にする。
+    """
+    for track_id, (func, help_text) in registry.items():
+        # InterlockingCLI 経由の場合は track_name 部分のみをサブコマンド名にする
+        display_name = track_id.split(":", 1)[1] if line_name and ":" in track_id else track_id
+        parser = parsers.add_parser(display_name, help=help_text)
+        parser.set_defaults(track_id=track_id)
+        parser.add_argument("command", choices=["start", "abort"])
+
+        try:
+            type_hints = get_type_hints(func, include_extras=True)
+        except Exception:
+            type_hints = {}
+
+        sig = inspect.signature(func)
+
+        for param_name, param in sig.parameters.items():
+            hint = param.annotation if param.annotation is not inspect.Parameter.empty else None
+            type_hint = type_hints.get(param_name)
+            if type_hint is not None:
+                hint = type_hint
+            if hint is None:
+                continue
+
+            is_coupler = False
+            try:
+                if hint is Coupler:
+                    is_coupler = True
+                elif hasattr(hint, '__name__') and hint.__name__ == 'Coupler':
+                    is_coupler = True
+                elif isinstance(hint, str) and hint == 'Coupler':
+                    is_coupler = True
+            except Exception:
+                pass
+            if is_coupler:
+                continue
+
+            origin = get_origin(hint)
+            has_metadata = hasattr(hint, '__metadata__')
+            import typing
+            is_annotated = (
+                has_metadata or
+                (origin is not None and (
+                    origin is getattr(typing, 'Annotated', None) or
+                    str(origin) == 'typing.Annotated'
+                ))
+            )
+            if not is_annotated:
+                raise TypeError(
+                    f"タスク '{track_id}' の引数 '{param_name}' には "
+                    f"Annotated[Type, 'ヘルプメッセージ'] が必要です。"
+                )
+
+            args = get_args(hint)
+            actual_type = args[0]
+            help_msg = hint.__metadata__[0] if hint.__metadata__ else ""
+            arg_default = (
+                param.default if param.default is not inspect.Parameter.empty else None
+            )
+            if actual_type is bool:
+                parser.add_argument(f"--{param_name}", action="store_true", help=help_msg)
+            else:
+                parser.add_argument(f"--{param_name}", type=actual_type, default=arg_default, help=help_msg)
+
+        parser.add_argument("--force", action="store_true", help="信号を無視して実行する（安全装置をすべて解除する）")
+        parser.add_argument(
+            "--allow-stale-takeover", dest="allow_stale_takeover", action="store_true",
+            help="stale（前回ロックの残骸）なロックだけを引き継いで実行する",
+        )
+        parser.add_argument(
+            "--stale-after", dest="stale_after", type=int, default=600,
+            help="この秒数が経過したロックを stale（前回ロックの残骸）とみなす (default=600)",
+        )
+        parser.add_argument("--run-by", dest="run_by", default=None, help="実行ユーザー名 (記録用)")
+        parser.add_argument("--run-id", dest="run_id", default=None, help="実行ID (記録用)")
+
+
+class InterlockingCLI:
+    """interlocking CLI のビルダー。
+
+    argparse の2ステップに準拠した設計:
+      parse_args() でパーサーを構築して引数を解析し、
+      execute() でタスクを実行する。
+
+    3フェーズでパーサーを構築する:
+      Phase 1 (Discovery): dispatcher.lines のキーだけでトップレベルパーサーを構成。
+      Phase 2 (Loading):   指定路線のモジュールを import し line 属性を取得。
+                           line.register_to(dispatcher) でタスクを登録する。
+      Phase 3 (Mapping):   登録済みタスクから詳細パーサーを構築する。
+
+    Args:
+        dispatcher:      構築済みの TrainDispatcher。
+        prog:            CLI プログラム名（argparse の prog）。
+        description:     CLI の説明文。
+        extra_arguments: ルートパーサーに追加する引数を設定するコールバック。
+    """
+
+    def __init__(
+        self,
+        dispatcher: TrainDispatcher,
+        prog: str = "interlocking",
+        description: str = "",
+        extra_arguments: Optional[Callable[[argparse.ArgumentParser], None]] = None,
+    ) -> None:
+        self.dispatcher = dispatcher
+        self.prog = prog
+        self.description = description
+        self.extra_arguments = extra_arguments
+
+    def parse_args(self, argv: Optional[list] = None) -> argparse.Namespace:
+        """パーサーを構築して引数を解析する。
+
+        argparse の parse_args() に相当するステップ。
+        戻り値の Namespace を execute() に渡すことでタスクを実行する。
+
+        Args:
+            argv: パース対象の引数リスト。None のとき sys.argv[1:] を使用。
+
+        Returns:
+            解析済みの argparse.Namespace。
+        """
+        _argv = argv if argv is not None else sys.argv[1:]
+
+        root = argparse.ArgumentParser(prog=self.prog, description=self.description)
+        root.set_defaults(parser=root, track_id=None)
+
+        if self.extra_arguments:
+            self.extra_arguments(root)
+
+        line_subparsers = root.add_subparsers(dest="line", help="line name")
+
+        # Phase 1: 路線名だけでパーサーを構成（import なし）
+        line_parsers: Dict[str, argparse.ArgumentParser] = {}
+        for line in self.dispatcher.lines:
+            lp = line_subparsers.add_parser(line)
+            lp.set_defaults(parser=lp, track_id=None)
+            line_parsers[line] = lp
+
+        # Phase 2: 指定路線をロードし登録
+        temp_parser = argparse.ArgumentParser(add_help=False)
+        if self.extra_arguments:
+            self.extra_arguments(temp_parser)
+        temp_parser.add_argument('line', nargs='?', choices=list(self.dispatcher.lines))
+        temp_args, _ = temp_parser.parse_known_args(_argv)
+        if temp_args.line:
+            self.dispatcher.load_line(temp_args.line)
+
+        # Phase 3: 登録済みタスクから詳細パーサーを構築。路線別にフィルタして track_name だけをサブコマンド名にする。
+        for line, lp in line_parsers.items():
+            track_subparsers = lp.add_subparsers(dest="track_id", help="タスク名")
+            line_registry = {
+                track_id: entry
+                for track_id, entry in self.dispatcher.registry.items()
+                if track_id.startswith(f"{line}:")
+            }
+            _setup_argparsers(line_registry, track_subparsers, line)
+
+        return root.parse_args(_argv)
+
+    def execute(self, args: argparse.Namespace) -> int:
+        """parse_args() の結果を受け取ってタスクを実行し、結果を終了コードで返す。
+
+        sys.exit() は呼ばない（Python コードから呼ぶライブラリ利用を妨げない）。
+        スクリプトでは ``sys.exit(cli.execute(args))`` として終了コードを伝える。
+
+        Args:
+            args: parse_args() が返した Namespace。
+
+        Returns:
+            :class:`ExitCode`（int）。成功 0 / 失敗 1 / 赤信号 3 / stale 4 / 見送り 5。
+            引数エラー（2）は parse_args() が argparse の標準動作で終了する。
+        """
+        if args.track_id is None:
+            args.parser.print_help()
+            return ExitCode.SUCCESS
+
+        if args.command == "abort":
+            self.dispatcher.abort(args.track_id, run_by=getattr(args, "run_by", None))
+            return ExitCode.SUCCESS
+
+        params = {k: v for k, v in vars(args).items() if k not in _INTERLOCKING_PARAM_KEYS}
+        result = self.dispatcher.depart(
+            args.track_id,
+            params,
+            force=args.force,
+            allow_stale_takeover=args.allow_stale_takeover,
+            stale_after=args.stale_after,
+            run_id=getattr(args, "run_id", None),
+            run_by=getattr(args, "run_by", None),
+        )
+        return _exit_code(result)