spatha 0.2.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
spatha/__init__.py ADDED
@@ -0,0 +1,12 @@
1
+ """Spatha — deterministic task DAG planning and execution."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ __version__ = version("spatha")
7
+ except PackageNotFoundError:
8
+ __version__ = "0.2.2"
9
+
10
+ from spatha.workflow import ExecutionWindow, TaskSpec, Workflow
11
+
12
+ __all__ = ["ExecutionWindow", "TaskSpec", "Workflow"]
spatha/py.typed ADDED
File without changes
spatha/workflow.py ADDED
@@ -0,0 +1,150 @@
1
+ """Signal-aware dependency DAG validation, planning, and execution."""
2
+
3
+ import time
4
+ from collections.abc import Callable
5
+ from datetime import datetime
6
+ from datetime import time as wall_time
7
+ from pathlib import Path
8
+
9
+ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
10
+ from scutum import file_lock
11
+
12
+
13
+ class ExecutionWindow(BaseModel):
14
+ """Inclusive start/exclusive end wall-clock window in UTC/local caller time."""
15
+
16
+ model_config = ConfigDict(frozen=True, extra="forbid")
17
+
18
+ start: wall_time
19
+ end: wall_time
20
+
21
+ @model_validator(mode="after")
22
+ def _must_be_forward_window(self) -> "ExecutionWindow":
23
+ if self.start >= self.end:
24
+ raise ValueError("execution window start must be before end")
25
+ return self
26
+
27
+ def contains(self, current: wall_time) -> bool:
28
+ return self.start <= current < self.end
29
+
30
+
31
+ class TaskSpec(BaseModel):
32
+ model_config = ConfigDict(frozen=True, extra="forbid")
33
+
34
+ name: str
35
+ depends_on: list[str] = Field(default_factory=list)
36
+ priority: int = 0
37
+ signals: list[str] = Field(default_factory=list)
38
+ window: ExecutionWindow | None = None
39
+
40
+ @field_validator("name")
41
+ @classmethod
42
+ def _name_is_path_safe(cls, value: str) -> str:
43
+ if not value or "/" in value or "\\" in value or value in {".", ".."}:
44
+ raise ValueError("task name must be non-empty and path-safe")
45
+ return value
46
+
47
+
48
+ class Workflow(BaseModel):
49
+ model_config = ConfigDict(frozen=True, extra="forbid")
50
+
51
+ tasks: list[TaskSpec] = Field(min_length=1)
52
+
53
+ @model_validator(mode="after")
54
+ def _validate_graph(self) -> "Workflow":
55
+ names = [task.name for task in self.tasks]
56
+ if len(set(names)) != len(names):
57
+ raise ValueError("workflow task names must be unique")
58
+ known = set(names)
59
+ missing = sorted(
60
+ {dep for task in self.tasks for dep in task.depends_on if dep not in known}
61
+ )
62
+ if missing:
63
+ raise ValueError(f"workflow has unknown dependencies: {', '.join(missing)}")
64
+ return self
65
+
66
+ def plan(self) -> list[TaskSpec]:
67
+ """Return a stable topological order, preferring higher priority tasks."""
68
+ by_name = {task.name: task for task in self.tasks}
69
+ remaining = {task.name: set(task.depends_on) for task in self.tasks}
70
+ ordered: list[TaskSpec] = []
71
+ while remaining:
72
+ ready = [name for name, deps in remaining.items() if not deps]
73
+ if not ready:
74
+ raise ValueError("workflow contains a dependency cycle")
75
+ ready.sort(key=lambda name: (-by_name[name].priority, name))
76
+ for name in ready:
77
+ ordered.append(by_name[name])
78
+ del remaining[name]
79
+ for deps in remaining.values():
80
+ deps.difference_update(ready)
81
+ return ordered
82
+
83
+ def ready_tasks(
84
+ self,
85
+ *,
86
+ completed: set[str] | frozenset[str] = frozenset(),
87
+ signals: set[str] | frozenset[str] = frozenset(),
88
+ now: wall_time | None = None,
89
+ ) -> list[TaskSpec]:
90
+ """Return runnable tasks, sorted by priority then name.
91
+
92
+ A task is runnable only when all dependencies and declared preparation
93
+ signals exist and its optional execution window contains ``now``.
94
+ """
95
+ current = now or datetime.now().time()
96
+ ready = [
97
+ task
98
+ for task in self.tasks
99
+ if task.name not in completed
100
+ and set(task.depends_on).issubset(completed)
101
+ and set(task.signals).issubset(signals)
102
+ and (task.window is None or task.window.contains(current))
103
+ ]
104
+ return sorted(ready, key=lambda task: (-task.priority, task.name))
105
+
106
+ def run(self, runner: Callable[[TaskSpec], None]) -> list[str]:
107
+ """Run tasks in plan order and return completed task names."""
108
+ completed: list[str] = []
109
+ for task in self.plan():
110
+ runner(task)
111
+ completed.append(task.name)
112
+ return completed
113
+
114
+ def run_ready(
115
+ self,
116
+ runner: Callable[[TaskSpec], None],
117
+ *,
118
+ completed: set[str] | None = None,
119
+ signals: set[str] | frozenset[str] = frozenset(),
120
+ now: wall_time | None = None,
121
+ lock_dir: Path | None = None,
122
+ lock_attempts: int = 5,
123
+ backoff_seconds: float = 0.1,
124
+ sleep: Callable[[float], None] = time.sleep,
125
+ ) -> list[str]:
126
+ """Run all currently runnable tasks until dependencies or signals block.
127
+
128
+ ``lock_dir`` enables cross-process task locks. The returned list only
129
+ contains tasks completed by this invocation, allowing an external
130
+ scheduler to persist the frontier and call this method again later.
131
+ """
132
+ completed_names = set(completed or ())
133
+ executed: list[str] = []
134
+ while True:
135
+ ready = self.ready_tasks(completed=completed_names, signals=signals, now=now)
136
+ if not ready:
137
+ return executed
138
+ for task in ready:
139
+ if lock_dir is None:
140
+ runner(task)
141
+ else:
142
+ with file_lock(
143
+ lock_dir / f"{task.name}.lock",
144
+ attempts=lock_attempts,
145
+ backoff_seconds=backoff_seconds,
146
+ sleep=sleep,
147
+ ):
148
+ runner(task)
149
+ completed_names.add(task.name)
150
+ executed.append(task.name)
@@ -0,0 +1,21 @@
1
+ Metadata-Version: 2.5
2
+ Name: spatha
3
+ Version: 0.2.2
4
+ Summary: Spatha — deterministic dependency DAG planning
5
+ Project-URL: Homepage, https://github.com/KooEric/de-arsenal
6
+ Project-URL: Repository, https://github.com/KooEric/de-arsenal
7
+ License-Expression: Apache-2.0
8
+ Classifier: License :: OSI Approved :: Apache Software License
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Requires-Python: >=3.11
14
+ Requires-Dist: de-scutum<0.3,>=0.2
15
+ Requires-Dist: pydantic>=2.7
16
+ Description-Content-Type: text/markdown
17
+
18
+ # Spatha
19
+
20
+ 준비 신호·의존성·priority·실행 window를 반영하는 결정적 workflow 실행기다.
21
+ `run_ready`는 외부 scheduler가 넘긴 신호와 완료 frontier를 사용한다.
@@ -0,0 +1,6 @@
1
+ spatha/__init__.py,sha256=alXjeXYgRiWSIq1heC0xNO-vxj5iPEboe_YyhOtmGpA,343
2
+ spatha/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
3
+ spatha/workflow.py,sha256=g3F4Vn1_0GLAgr3KVIW0i5OA8FNWWc8JZTLYNMKzndk,5541
4
+ spatha-0.2.2.dist-info/METADATA,sha256=4yEsiau2av9PS-oUa4V3NYljUBVgs9250v2cXpmBxSs,846
5
+ spatha-0.2.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
6
+ spatha-0.2.2.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.32.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any