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 +12 -0
- spatha/py.typed +0 -0
- spatha/workflow.py +150 -0
- spatha-0.2.2.dist-info/METADATA +21 -0
- spatha-0.2.2.dist-info/RECORD +6 -0
- spatha-0.2.2.dist-info/WHEEL +4 -0
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,,
|