interlocking 0.0.1__tar.gz

interlocking-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alpine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

interlocking-0.0.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: interlocking
+Version: 0.0.1
+Summary: A lightweight task dispatcher with explicit control.
+Keywords: task-runner,batch,exclusive-lock,cli,mutex,distributed-lock
+Author: alpine
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Utilities
+Requires-Dist: boto3>1.40.0,<2 ; extra == 'aws'
+Requires-Python: >=3.11
+Provides-Extra: aws
+Description-Content-Type: text/markdown
+
+# Interlocking
+
+> One track, one train.  
+> Easy to run. Explicit to control.
+
+interlocking は、分散環境におけるバックグラウンドタスクの「運行管理」フレームワークです。
+鉄道メタファーにより、バッチタスクのライフサイクル（排他制御・実行記録・CLI 統合）を統一された方法で管理します。
+
+## 特長
+
+- **排他制御**: 同じタスクを同時に走らせない。
+- **実行記録**: 直近の実行結果を記録し、次回実行に引き継ぐ（`Coupler`）。
+- **CLI 統合**: 型ヒントからコマンドラインを組み立て、結果を終了コードで返す。
+- **差し込み**: `Station`（ストレージ）や `TrainMiddleware` で、振る舞いを拡張できる。
+
+## 最小構成
+
+```python
+# tasks.py
+from typing import Annotated
+from interlocking import Line, Coupler
+
+line = Line()
+
+@line.track(name="daily", help="日次処理")
+def daily_task(c: Coupler, target_date: Annotated[str, "対象日付 (YYYY-MM-DD)"]) -> dict:
+    last_id = c.last_data.get("last_id", 0)
+    # ... 処理 ...
+    return {"last_id": 9999}
+```
+
+```python
+# main.py
+import sys
+
+from interlocking import TrainDispatcher, LocalStation, InterlockingCLI
+
+dispatcher = TrainDispatcher(
+    station=LocalStation(base_path=".interlocking"),
+    lines={"batch": "tasks:line"},
+)
+
+cli = InterlockingCLI(dispatcher=dispatcher, prog="my-task", description="バッチタスク")
+sys.exit(cli.execute(cli.parse_args()))  # 結果を終了コードで伝える
+```
+
+```bash
+python main.py batch daily start --target-date 2026-04-01
+```
+
+詳しくは [docs/user/interlocking.md](docs/user/interlocking.md) を参照してください。
+
+## 開発
+
+```bash
+uv sync
+uv run pytest
+```
+
+設計方針は [.github/copilot-instructions.md](.github/copilot-instructions.md) の Design Principles、決定事項は [docs/dev/adr/](docs/dev/adr/) を参照してください。
+
+## ライセンス
+
+MIT

interlocking-0.0.1/README.md

@@ -0,0 +1,64 @@
+# Interlocking
+
+> One track, one train.  
+> Easy to run. Explicit to control.
+
+interlocking は、分散環境におけるバックグラウンドタスクの「運行管理」フレームワークです。
+鉄道メタファーにより、バッチタスクのライフサイクル（排他制御・実行記録・CLI 統合）を統一された方法で管理します。
+
+## 特長
+
+- **排他制御**: 同じタスクを同時に走らせない。
+- **実行記録**: 直近の実行結果を記録し、次回実行に引き継ぐ（`Coupler`）。
+- **CLI 統合**: 型ヒントからコマンドラインを組み立て、結果を終了コードで返す。
+- **差し込み**: `Station`（ストレージ）や `TrainMiddleware` で、振る舞いを拡張できる。
+
+## 最小構成
+
+```python
+# tasks.py
+from typing import Annotated
+from interlocking import Line, Coupler
+
+line = Line()
+
+@line.track(name="daily", help="日次処理")
+def daily_task(c: Coupler, target_date: Annotated[str, "対象日付 (YYYY-MM-DD)"]) -> dict:
+    last_id = c.last_data.get("last_id", 0)
+    # ... 処理 ...
+    return {"last_id": 9999}
+```
+
+```python
+# main.py
+import sys
+
+from interlocking import TrainDispatcher, LocalStation, InterlockingCLI
+
+dispatcher = TrainDispatcher(
+    station=LocalStation(base_path=".interlocking"),
+    lines={"batch": "tasks:line"},
+)
+
+cli = InterlockingCLI(dispatcher=dispatcher, prog="my-task", description="バッチタスク")
+sys.exit(cli.execute(cli.parse_args()))  # 結果を終了コードで伝える
+```
+
+```bash
+python main.py batch daily start --target-date 2026-04-01
+```
+
+詳しくは [docs/user/interlocking.md](docs/user/interlocking.md) を参照してください。
+
+## 開発
+
+```bash
+uv sync
+uv run pytest
+```
+
+設計方針は [.github/copilot-instructions.md](.github/copilot-instructions.md) の Design Principles、決定事項は [docs/dev/adr/](docs/dev/adr/) を参照してください。
+
+## ライセンス
+
+MIT

interlocking-0.0.1/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[project]
+name = "interlocking"
+version = "0.0.1"
+description = "A lightweight task dispatcher with explicit control."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+keywords = [
+    "task-runner",
+    "batch",
+    "exclusive-lock",
+    "cli",
+    "mutex",
+    "distributed-lock",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+    "Topic :: Utilities",
+]
+
+[[project.authors]]
+name = "alpine"
+
+[project.scripts]
+
+[project.optional-dependencies]
+aws = ["boto3>1.40.0,<2"]
+
+[dependency-groups]
+dev = [
+    "interlocking[aws]",
+    "ruff",
+    "pyyaml>=6.0.3",
+    "pytest>=7.0.0",
+    "pytest-mock>=3.10.0",
+    "pytest-env>=1.2.0",
+    "moto[s3]>=5.2.5",
+]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E2",
+    "E4",
+    "E7",
+    "E9",
+    "W",
+    "F",
+    "INP",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"docker/*.py" = ["INP"]
+"examples/**/*.py" = ["INP"]
+"scripts/*.py" = ["INP"]
+"tests/*.py" = ["INP"]
+"var/*.py" = ["INP"]
+
+[tool.pytest.ini_options]
+cache_dir = "var/.pytest_cache"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-m 'not moto and not seaweedfs'"
+markers = [
+    "moto: moto server（実 HTTP）を使う結合テスト。既定では実行しない（`pytest -m moto` で実行）",
+    "seaweedfs: ローカルの SeaweedFS（S3 互換）を使う結合テスト。既定では実行しない（`pytest -m seaweedfs` で実行）",
+]
+
+[tool.pytest_env]

interlocking-0.0.1/pyproject.toml.orig

@@ -0,0 +1,102 @@
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[project]
+name = "interlocking"
+version = "0.0.1"
+description = "A lightweight task dispatcher with explicit control."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+]
+authors = [
+    { name = "alpine" },
+]
+keywords = [
+    "task-runner",
+    "batch",
+    "exclusive-lock",
+    "cli",
+    "mutex",
+    "distributed-lock",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+    "Topic :: Utilities",
+]
+[project.scripts]
+
+
+[project.optional-dependencies]
+aws = [
+    "boto3>1.40.0,<2",
+]
+
+[dependency-groups]
+dev = [
+    "interlocking[aws]",
+    # -- ruff --
+    "ruff",
+    #-- dev-docs skill --
+    "pyyaml>=6.0.3",
+    # pytest
+    "pytest>=7.0.0",
+    "pytest-mock>=3.10.0",
+    "pytest-env>=1.2.0",
+    "moto[s3]>=5.2.5",
+]
+
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+# https://docs.astral.sh/ruff/configuration/
+src = ["src"]
+
+[tool.ruff.lint]
+# https://docs.astral.sh/ruff/rules/
+select = [
+    # pycodestyle (E, W)
+    "E2",
+    "E4",
+    "E7",
+    "E9",
+    "W",
+
+    # Pyflakes (F)
+    "F",
+
+    # flake8-no-pep420 (INP)
+    "INP",
+
+    # pep8-naming (N)
+    #"N",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"docker/*.py" = ["INP"]
+"examples/**/*.py" = ["INP"]
+"scripts/*.py" = ["INP"]
+"tests/*.py" = ["INP"]
+"var/*.py" = ["INP"]
+
+
+[tool.pytest.ini_options]
+cache_dir = "var/.pytest_cache"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-m 'not moto and not seaweedfs'"
+markers = [
+    "moto: moto server（実 HTTP）を使う結合テスト。既定では実行しない（`pytest -m moto` で実行）",
+    "seaweedfs: ローカルの SeaweedFS（S3 互換）を使う結合テスト。既定では実行しない（`pytest -m seaweedfs` で実行）",
+]
+
+[tool.pytest_env]

interlocking-0.0.1/src/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-0.0.1/src/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)