spatha 0.2.2__tar.gz
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-0.2.2/.gitignore +12 -0
- spatha-0.2.2/PKG-INFO +21 -0
- spatha-0.2.2/README.md +4 -0
- spatha-0.2.2/pyproject.toml +26 -0
- spatha-0.2.2/src/spatha/__init__.py +12 -0
- spatha-0.2.2/src/spatha/py.typed +0 -0
- spatha-0.2.2/src/spatha/workflow.py +150 -0
- spatha-0.2.2/tests/test_workflow.py +76 -0
spatha-0.2.2/.gitignore
ADDED
spatha-0.2.2/PKG-INFO
ADDED
|
@@ -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를 사용한다.
|
spatha-0.2.2/README.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "spatha"
|
|
3
|
+
version = "0.2.2"
|
|
4
|
+
description = "Spatha — deterministic dependency DAG planning"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
license = "Apache-2.0"
|
|
8
|
+
dependencies = ["de-scutum>=0.2,<0.3", "pydantic>=2.7"]
|
|
9
|
+
classifiers = [
|
|
10
|
+
"Programming Language :: Python :: 3",
|
|
11
|
+
"Programming Language :: Python :: 3.11",
|
|
12
|
+
"Programming Language :: Python :: 3.12",
|
|
13
|
+
"License :: OSI Approved :: Apache Software License",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
]
|
|
16
|
+
|
|
17
|
+
[project.urls]
|
|
18
|
+
Homepage = "https://github.com/KooEric/de-arsenal"
|
|
19
|
+
Repository = "https://github.com/KooEric/de-arsenal"
|
|
20
|
+
|
|
21
|
+
[build-system]
|
|
22
|
+
requires = ["hatchling"]
|
|
23
|
+
build-backend = "hatchling.build"
|
|
24
|
+
|
|
25
|
+
[tool.hatch.build.targets.wheel]
|
|
26
|
+
packages = ["src/spatha"]
|
|
@@ -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"]
|
|
File without changes
|
|
@@ -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,76 @@
|
|
|
1
|
+
from datetime import time
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
|
|
4
|
+
import pytest
|
|
5
|
+
from pydantic import ValidationError
|
|
6
|
+
from spatha import ExecutionWindow, TaskSpec, Workflow
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def test_plan_is_topological_and_priority_stable() -> None:
|
|
10
|
+
workflow = Workflow(
|
|
11
|
+
tasks=[
|
|
12
|
+
TaskSpec(name="load"),
|
|
13
|
+
TaskSpec(name="quality", depends_on=["load"], priority=1),
|
|
14
|
+
TaskSpec(name="lineage", depends_on=["load"], priority=2),
|
|
15
|
+
]
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
assert [task.name for task in workflow.plan()] == ["load", "lineage", "quality"]
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def test_run_calls_tasks_in_plan_order() -> None:
|
|
22
|
+
workflow = Workflow(tasks=[TaskSpec(name="a"), TaskSpec(name="b", depends_on=["a"])])
|
|
23
|
+
seen: list[str] = []
|
|
24
|
+
|
|
25
|
+
assert workflow.run(lambda task: seen.append(task.name)) == ["a", "b"]
|
|
26
|
+
assert seen == ["a", "b"]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def test_unknown_dependency_duplicate_and_cycle_are_rejected() -> None:
|
|
30
|
+
with pytest.raises(ValidationError, match="unknown dependencies"):
|
|
31
|
+
Workflow(tasks=[TaskSpec(name="a", depends_on=["missing"])])
|
|
32
|
+
with pytest.raises(ValidationError, match="unique"):
|
|
33
|
+
Workflow(tasks=[TaskSpec(name="a"), TaskSpec(name="a")])
|
|
34
|
+
cycle = Workflow.model_construct(
|
|
35
|
+
tasks=[TaskSpec(name="a", depends_on=["b"]), TaskSpec(name="b", depends_on=["a"])]
|
|
36
|
+
)
|
|
37
|
+
with pytest.raises(ValueError, match="cycle"):
|
|
38
|
+
cycle.plan()
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def test_ready_tasks_require_signals_and_execution_window() -> None:
|
|
42
|
+
workflow = Workflow(
|
|
43
|
+
tasks=[
|
|
44
|
+
TaskSpec(name="load", signals=["raw_ready"]),
|
|
45
|
+
TaskSpec(
|
|
46
|
+
name="publish",
|
|
47
|
+
depends_on=["load"],
|
|
48
|
+
window=ExecutionWindow(start=time(9), end=time(17)),
|
|
49
|
+
),
|
|
50
|
+
]
|
|
51
|
+
)
|
|
52
|
+
assert workflow.ready_tasks(signals=set(), now=time(10)) == []
|
|
53
|
+
assert [task.name for task in workflow.ready_tasks(signals={"raw_ready"}, now=time(10))] == [
|
|
54
|
+
"load"
|
|
55
|
+
]
|
|
56
|
+
assert workflow.ready_tasks(completed={"load"}, now=time(18)) == []
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def test_run_ready_releases_dependencies_and_uses_task_locks(tmp_path: Path) -> None:
|
|
60
|
+
workflow = Workflow(
|
|
61
|
+
tasks=[
|
|
62
|
+
TaskSpec(name="load", signals=["raw_ready"]),
|
|
63
|
+
TaskSpec(name="publish", depends_on=["load"]),
|
|
64
|
+
]
|
|
65
|
+
)
|
|
66
|
+
seen: list[str] = []
|
|
67
|
+
|
|
68
|
+
result = workflow.run_ready(
|
|
69
|
+
lambda task: seen.append(task.name),
|
|
70
|
+
signals={"raw_ready"},
|
|
71
|
+
lock_dir=tmp_path,
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
assert result == ["load", "publish"]
|
|
75
|
+
assert seen == result
|
|
76
|
+
assert list(tmp_path.glob("*.lock")) == []
|