kahn-queue 0.1.1__tar.gz → 1.0.1__tar.gz

{kahn_queue-0.1.1/src/kahn_queue.egg-info → kahn_queue-1.0.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: kahn-queue
-Version: 0.1.1
-Summary: Kahn-style ready-queue for dependency scheduling
+Version: 1.0.1
+Summary: Lightweight Kahn-based ready queue for dependency-driven scheduling and workflows
 License: MIT
-Project-URL: Homepage, https://github.com/Flashlock/kahn-queue
+Project-URL: Homepage, https://flashlock.github.io/kahn-queue/
 Project-URL: Repository, https://github.com/Flashlock/kahn-queue
-Keywords: dag,scheduler,workflow,kahn
+Keywords: kahn queue,kahn-style scheduler,topological sort queue,dynamic topological sort,ready queue,dependency scheduler,dag scheduler,incremental topological sort,agent orchestration,parallel task scheduling,deterministic scheduler
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 
@@ -84,3 +84,32 @@ result = sched.get_result()
 # result.completed, result.failed, result.pruned — frozensets of ids
 done = sched.is_finished
 ```
+
+### Manual KahnQueue
+
+```python
+from dag import Dag
+from kahnQueue.default_kahn_queue import DefaultKahnQueue
+
+b = Dag.builder()
+lint = b.add("lint")
+compile = b.add("compile")
+test = b.add("test")
+b.connect(lint, compile).connect(compile, test)
+dag = b.build()
+
+q = DefaultKahnQueue(dag)
+
+ready = list(q.ready_ids())
+
+while ready:
+    id_ = ready.pop(0)
+
+    # do work for `id_` (e.g. run_step(dag[id_]))
+
+    promoted = q.pop(id_)
+    ready.extend(promoted)
+
+    # If a node fails, you can prune it (and its descendants):
+    # q.prune(id_)
+```

kahn_queue-0.1.1/PKG-INFO → kahn_queue-1.0.1/README.md

@@ -1,14 +1,3 @@
-Metadata-Version: 2.4
-Name: kahn-queue
-Version: 0.1.1
-Summary: Kahn-style ready-queue for dependency scheduling
-License: MIT
-Project-URL: Homepage, https://github.com/Flashlock/kahn-queue
-Project-URL: Repository, https://github.com/Flashlock/kahn-queue
-Keywords: dag,scheduler,workflow,kahn
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
 # kahn-queue (Python)
 
 ## Getting started
@@ -84,3 +73,32 @@ result = sched.get_result()
 # result.completed, result.failed, result.pruned — frozensets of ids
 done = sched.is_finished
 ```
+
+### Manual KahnQueue
+
+```python
+from dag import Dag
+from kahnQueue.default_kahn_queue import DefaultKahnQueue
+
+b = Dag.builder()
+lint = b.add("lint")
+compile = b.add("compile")
+test = b.add("test")
+b.connect(lint, compile).connect(compile, test)
+dag = b.build()
+
+q = DefaultKahnQueue(dag)
+
+ready = list(q.ready_ids())
+
+while ready:
+    id_ = ready.pop(0)
+
+    # do work for `id_` (e.g. run_step(dag[id_]))
+
+    promoted = q.pop(id_)
+    ready.extend(promoted)
+
+    # If a node fails, you can prune it (and its descendants):
+    # q.prune(id_)
+```

{kahn_queue-0.1.1 → kahn_queue-1.0.1}/pyproject.toml

@@ -4,15 +4,27 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kahn-queue"
-version = "0.1.1"
-description = "Kahn-style ready-queue for dependency scheduling"
+version = "1.0.1"
+description = "Lightweight Kahn-based ready queue for dependency-driven scheduling and workflows"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
-keywords = ["dag", "scheduler", "workflow", "kahn"]
+keywords = [
+  "kahn queue",
+  "kahn-style scheduler",
+  "topological sort queue",
+  "dynamic topological sort",
+  "ready queue",
+  "dependency scheduler",
+  "dag scheduler",
+  "incremental topological sort",
+  "agent orchestration",
+  "parallel task scheduling",
+  "deterministic scheduler",
+]
 
 [project.urls]
-Homepage = "https://github.com/Flashlock/kahn-queue"
+Homepage = "https://flashlock.github.io/kahn-queue/"
 Repository = "https://github.com/Flashlock/kahn-queue"
 
 # Layout: packages under src/ plus top-level modules (dag, scheduler, …).

{kahn_queue-0.1.1 → kahn_queue-1.0.1}/src/kahnQueue/concurrent_kahn_queue.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from threading import RLock
-from typing import List, Set
+from typing import List
 
 from dag import Dag, validate_node
 from kahnQueue.node_machine import NodeMachine
@@ -25,7 +25,7 @@ class ConcurrentKahnQueue(KahnQueue):
         ]
         self._locks = [RLock() for _ in range(dag.size())]
 
-    def pop(self, id: int) -> Set[int]:
+    def pop(self, id: int) -> List[int]:
         validate_node(id, self._dag.size())
         
         with self._locks[id]:
@@ -35,7 +35,7 @@ class ConcurrentKahnQueue(KahnQueue):
             
             machine.transition(NodeState.COMPLETE)
 
-            promoted: Set[int] = set()
+            promoted: set[int] = set()
             for cid in self._dag.targets(id):
                 with self._locks[cid]:
                     child = self._node_machines[cid]
@@ -44,12 +44,12 @@ class ConcurrentKahnQueue(KahnQueue):
                     if child.can_transition(NodeState.ACTIVE):
                         child.transition(NodeState.ACTIVE)
                         promoted.add(cid)
-            return promoted
+            return sorted(promoted)
 
-    def prune(self, id: int) -> Set[int]:
+    def prune(self, id: int) -> List[int]:
         validate_node(id, self._dag.size())
         
-        affected: Set[int] = set()
+        affected: set[int] = set()
         stack: List[int] = [id]
 
         while stack:
@@ -66,10 +66,9 @@ class ConcurrentKahnQueue(KahnQueue):
             # Adding targets outside the lock is safe as the DAG structure is immutable
             stack.extend(self._dag.targets(curr))
             
-        return affected
+        return sorted(affected)
 
-    def ready_ids(self) -> Set[int]:
-        return {
-            m.id for m in self._node_machines 
-            if m.is_(NodeState.READY)
-        }
+    def ready_ids(self) -> List[int]:
+        # Deterministic ordering for sequential callers; may not reflect a consistent snapshot
+        # under concurrent updates.
+        return [m.id for m in self._node_machines if m.is_(NodeState.READY)]

{kahn_queue-0.1.1 → kahn_queue-1.0.1}/src/kahnQueue/default_kahn_queue.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
-from collections import deque
-from typing import List, Set
+from typing import List
 
 from dag import Dag, validate_node
 from kahnQueue.node_machine import NodeMachine
@@ -17,7 +16,7 @@ class DefaultKahnQueue(KahnQueue):
             NodeMachine.create(i, dag.in_degree(i)) for i in range(dag.size())
         ]
 
-    def pop(self, id: int) -> Set[int]:
+    def pop(self, id: int) -> List[int]:
         validate_node(id, self._dag.size())
         machine = self._node_machines[id]
         
@@ -26,7 +25,7 @@ class DefaultKahnQueue(KahnQueue):
         
         machine.transition(NodeState.COMPLETE)
 
-        promoted: Set[int] = set()
+        promoted: List[int] = []
         for cid in self._dag.targets(id):
             child = self._node_machines[cid]
             child.decrement()
@@ -34,12 +33,12 @@ class DefaultKahnQueue(KahnQueue):
             # in a single-threaded queue.
             if child.is_(NodeState.READY):
                 child.transition(NodeState.ACTIVE)
-                promoted.add(cid)
+                promoted.append(cid)
         return promoted
 
-    def prune(self, id: int) -> Set[int]:
+    def prune(self, id: int) -> List[int]:
         validate_node(id, self._dag.size())
-        affected: Set[int] = set()
+        affected: set[int] = set()
         stack: List[int] = [id]
         
         while stack:
@@ -54,7 +53,8 @@ class DefaultKahnQueue(KahnQueue):
             affected.add(curr)
             stack.extend(self._dag.targets(curr))
             
-        return affected
+        return sorted(affected)
 
-    def ready_ids(self) -> Set[int]:
-        return {m.id for m in self._node_machines if m.is_(NodeState.READY)}
+    def ready_ids(self) -> List[int]:
+        # Deterministic: ids are scanned in ascending order.
+        return [m.id for m in self._node_machines if m.is_(NodeState.READY)]

kahn_queue-0.1.1/README.md → kahn_queue-1.0.1/src/kahn_queue.egg-info/PKG-INFO

@@ -1,3 +1,14 @@
+Metadata-Version: 2.4
+Name: kahn-queue
+Version: 1.0.1
+Summary: Lightweight Kahn-based ready queue for dependency-driven scheduling and workflows
+License: MIT
+Project-URL: Homepage, https://flashlock.github.io/kahn-queue/
+Project-URL: Repository, https://github.com/Flashlock/kahn-queue
+Keywords: kahn queue,kahn-style scheduler,topological sort queue,dynamic topological sort,ready queue,dependency scheduler,dag scheduler,incremental topological sort,agent orchestration,parallel task scheduling,deterministic scheduler
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
 # kahn-queue (Python)
 
 ## Getting started
@@ -73,3 +84,32 @@ result = sched.get_result()
 # result.completed, result.failed, result.pruned — frozensets of ids
 done = sched.is_finished
 ```
+
+### Manual KahnQueue
+
+```python
+from dag import Dag
+from kahnQueue.default_kahn_queue import DefaultKahnQueue
+
+b = Dag.builder()
+lint = b.add("lint")
+compile = b.add("compile")
+test = b.add("test")
+b.connect(lint, compile).connect(compile, test)
+dag = b.build()
+
+q = DefaultKahnQueue(dag)
+
+ready = list(q.ready_ids())
+
+while ready:
+    id_ = ready.pop(0)
+
+    # do work for `id_` (e.g. run_step(dag[id_]))
+
+    promoted = q.pop(id_)
+    ready.extend(promoted)
+
+    # If a node fails, you can prune it (and its descendants):
+    # q.prune(id_)
+```

{kahn_queue-0.1.1 → kahn_queue-1.0.1}/tests/test_concurrent_kahn_queue.py

@@ -17,7 +17,7 @@ def _force_node_state(q: ConcurrentKahnQueue, id_: int, state: NodeState) -> Non
 def test_basics_ready_ids_and_pop_validation():
     empty = Dag.builder().build()
     q0 = ConcurrentKahnQueue(empty)
-    assert q0.ready_ids() == set()
+    assert q0.ready_ids() == []
     with pytest.raises(IndexError):
         q0.pop(0)
 
@@ -28,7 +28,7 @@ def test_basics_ready_ids_and_pop_validation():
     chain.connect(root, mid).connect(mid, leaf)
     dag_chain = chain.build()
     qc = ConcurrentKahnQueue(dag_chain)
-    assert qc.ready_ids() == {root}
+    assert qc.ready_ids() == [root]
 
     join = Dag.builder()
     a = join.add("a")
@@ -37,13 +37,13 @@ def test_basics_ready_ids_and_pop_validation():
     join.connect(a, jn).connect(c, jn)
     dag_join = join.build()
     qj = ConcurrentKahnQueue(dag_join)
-    assert qj.ready_ids() == {a, c}
+    assert qj.ready_ids() == [a, c]
 
     one = Dag.builder()
     only = one.add("x")
     dag_one = one.build()
     q1 = ConcurrentKahnQueue(dag_one)
-    assert q1.ready_ids() == {only}
+    assert q1.ready_ids() == [only]
     with pytest.raises(ValueError) as ex:
         q1.pop(only)
     assert "Pop failed. Node" in str(ex.value)
@@ -64,7 +64,7 @@ def test_prune_collects_reachable_in_linear_and_fork_shapes():
     l = b1.add("l")
     b1.connect(r, m).connect(m, l)
     q1 = ConcurrentKahnQueue(b1.build())
-    assert q1.prune(r) == {r, m, l}
+    assert set(q1.prune(r)) == {r, m, l}
 
     b2 = Dag.builder()
     root = b2.add("root")
@@ -72,7 +72,7 @@ def test_prune_collects_reachable_in_linear_and_fork_shapes():
     right = b2.add("right")
     b2.connect(root, left).connect(root, right)
     q2 = ConcurrentKahnQueue(b2.build())
-    assert q2.prune(root) == {root, left, right}
+    assert set(q2.prune(root)) == {root, left, right}
 
 
 def test_prune_updates_ready_set():
@@ -83,9 +83,9 @@ def test_prune_updates_ready_set():
     b.connect(a, join).connect(c, join)
     dag = b.build()
     q = ConcurrentKahnQueue(dag)
-    assert q.ready_ids() == {a, c}
+    assert q.ready_ids() == [a, c]
     q.prune(a)
-    assert q.ready_ids() == {c}
+    assert q.ready_ids() == [c]
 
 
 def test_ready_ids_stable_under_sequential_repeats():
@@ -108,10 +108,10 @@ def test_prune_second_call_throws():
     r = b.add("r")
     dag = b.build()
     q = ConcurrentKahnQueue(dag)
-    assert q.prune(r) == {r}
-    assert q.ready_ids() == set()
+    assert q.prune(r) == [r]
+    assert q.ready_ids() == []
     # ConcurrentKahnQueue.prune is idempotent for already-pruned branches.
-    assert q.prune(r) == set()
+    assert q.prune(r) == []
     for id_ in q.ready_ids():
         Dag.validate_node(id_, dag.size())
 
@@ -125,10 +125,10 @@ def test_kahn_progression_pop_active_node_returns_promoted_dependents():
     dag = b.build()
     q = ConcurrentKahnQueue(dag)
     _force_node_state(q, root, NodeState.ACTIVE)
-    assert q.pop(root) == {mid}
-    assert q.pop(mid) == {leaf}
-    assert q.pop(leaf) == set()
-    assert q.ready_ids() == set()
+    assert q.pop(root) == [mid]
+    assert q.pop(mid) == [leaf]
+    assert q.pop(leaf) == []
+    assert q.ready_ids() == []
     for id_ in q.ready_ids():
         Dag.validate_node(id_, dag.size())
 
@@ -141,7 +141,7 @@ def test_concurrent_ready_ids_stress_reads_match_snapshot():
         b.connect(x, y)
         dag = b.build()
         q = ConcurrentKahnQueue(dag)
-        expected = {x}
+        expected = [x]
         assert q.ready_ids() == expected
 
         def worker():
@@ -166,9 +166,9 @@ def test_concurrent_disjoint_prune():
         with concurrent.futures.ThreadPoolExecutor(max_workers=2) as pool:
             f1 = pool.submit(q.prune, left)
             f2 = pool.submit(q.prune, right)
-            assert f1.result() == {left}
-            assert f2.result() == {right}
-        assert q.ready_ids() == set()
+            assert f1.result() == [left]
+            assert f2.result() == [right]
+        assert q.ready_ids() == []
 
 
 def test_concurrent_pop_failures_do_not_mutate_ready():
@@ -208,9 +208,9 @@ def test_concurrent_same_id_prune_contention():
             futures = [pool.submit(worker) for _ in range(8)]
             start.set()
             results = [f.result(timeout=30) for f in futures]
-        assert results.count({root}) == 1
-        assert results.count(set()) == 7
-        assert q.ready_ids() == set()
+        assert results.count([root]) == 1
+        assert results.count([]) == 7
+        assert q.ready_ids() == []
 
 
 def test_concurrent_overlapping_prune():
@@ -240,9 +240,9 @@ def test_concurrent_overlapping_prune():
 
         assert set(s1) | set(s2) == {r, m, l}
 
-        any_full = (s1 == {r, m, l}) or (s2 == {r, m, l})
+        any_full = (set(s1) == {r, m, l}) or (set(s2) == {r, m, l})
         if any_full:
-            assert q.ready_ids() == set()
+            assert q.ready_ids() == []
 
 
 def test_prune_mutation_visible_to_other_thread_after_future_get():
@@ -253,8 +253,8 @@ def test_prune_mutation_visible_to_other_thread_after_future_get():
     q = ConcurrentKahnQueue(dag)
     with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
         done = pool.submit(q.prune, left)
-        assert done.result(timeout=10) == {left}
-    assert q.ready_ids() == {right}
+        assert done.result(timeout=10) == [left]
+    assert q.ready_ids() == [right]
 
 
 def _get_prune_result_or_illegal_state(fut: "concurrent.futures.Future[set[int]]"):

{kahn_queue-0.1.1 → kahn_queue-1.0.1}/tests/test_default_kahn_queue.py

@@ -12,7 +12,7 @@ def _force_node_state(q: DefaultKahnQueue, id_: int, state: NodeState) -> None:
 def test_empty_dag_ready_ids_empty_and_pop_rejects_invalid_id():
     dag = Dag.builder().build()
     q = DefaultKahnQueue(dag)
-    assert q.ready_ids() == set()
+    assert q.ready_ids() == []
     with pytest.raises(IndexError):
         q.pop(0)
 
@@ -25,7 +25,7 @@ def test_ready_ids_contains_only_zero_in_degree_nodes():
     b.connect(root, mid).connect(mid, leaf)
     dag = b.build()
     q = DefaultKahnQueue(dag)
-    assert q.ready_ids() == {root}
+    assert q.ready_ids() == [root]
 
 
 def test_ready_ids_two_independent_roots():
@@ -36,7 +36,7 @@ def test_ready_ids_two_independent_roots():
     b.connect(a, join).connect(c, join)
     dag = b.build()
     q = DefaultKahnQueue(dag)
-    assert q.ready_ids() == {a, c}
+    assert q.ready_ids() == [a, c]
 
 
 def test_pop_throws_when_node_is_ready_not_active():
@@ -44,7 +44,7 @@ def test_pop_throws_when_node_is_ready_not_active():
     only = b.add("x")
     dag = b.build()
     q = DefaultKahnQueue(dag)
-    assert q.ready_ids() == {only}
+    assert q.ready_ids() == [only]
     with pytest.raises(ValueError) as ex:
         q.pop(only)
     assert "Pop failed. Node" in str(ex.value)
@@ -68,7 +68,7 @@ def test_prune_marks_root_and_reachable_descendants():
     b.connect(r, m).connect(m, l)
     dag = b.build()
     q = DefaultKahnQueue(dag)
-    assert q.prune(r) == {r, m, l}
+    assert set(q.prune(r)) == {r, m, l}
 
 
 def test_prune_fork_collects_all_branches():
@@ -79,7 +79,7 @@ def test_prune_fork_collects_all_branches():
     b.connect(root, left).connect(root, right)
     dag = b.build()
     q = DefaultKahnQueue(dag)
-    assert q.prune(root) == {root, left, right}
+    assert set(q.prune(root)) == {root, left, right}
 
 
 def test_prune_removes_ids_from_ready_set():
@@ -90,9 +90,9 @@ def test_prune_removes_ids_from_ready_set():
     b.connect(a, join).connect(c, join)
     dag = b.build()
     q = DefaultKahnQueue(dag)
-    assert q.ready_ids() == {a, c}
+    assert q.ready_ids() == [a, c]
     q.prune(a)
-    assert q.ready_ids() == {c}
+    assert q.ready_ids() == [c]
 
 
 def test_prune_second_call_throws():
@@ -100,10 +100,10 @@ def test_prune_second_call_throws():
     r = b.add("r")
     dag = b.build()
     q = DefaultKahnQueue(dag)
-    assert q.prune(r) == {r}
-    assert q.ready_ids() == set()
+    assert q.prune(r) == [r]
+    assert q.ready_ids() == []
     # DefaultKahnQueue.prune is idempotent for already-pruned branches.
-    assert q.prune(r) == set()
+    assert q.prune(r) == []
 
 
 def test_kahn_progression_pop_active_node_returns_promoted_dependents():
@@ -116,8 +116,8 @@ def test_kahn_progression_pop_active_node_returns_promoted_dependents():
     q = DefaultKahnQueue(dag)
 
     _force_node_state(q, root, NodeState.ACTIVE)
-    assert q.pop(root) == {mid}
-    assert q.pop(mid) == {leaf}
-    assert q.pop(leaf) == set()
-    assert q.ready_ids() == set()
+    assert q.pop(root) == [mid]
+    assert q.pop(mid) == [leaf]
+    assert q.pop(leaf) == []
+    assert q.ready_ids() == []