taskflow-tr 0.1.0__py3-none-any.whl

task_flow/__init__.py

@@ -0,0 +1,13 @@
+from .api import CompiledFunction, TransformedFunction, compile, transform
+from .runtime import Executor, InlineExecutor, ProcessExecutor, ThreadExecutor
+
+__all__ = [
+    "CompiledFunction",
+    "Executor",
+    "InlineExecutor",
+    "ProcessExecutor",
+    "ThreadExecutor",
+    "TransformedFunction",
+    "compile",
+    "transform",
+]

task_flow/api.py

@@ -0,0 +1,121 @@
+import functools
+from typing import Any, Callable, Optional
+
+from task_flow.compiler import Compiler
+from task_flow.ir import GraphIR
+from task_flow.printer import get_printer
+from task_flow.runtime import InlineExecutor, ProcessExecutor, ThreadExecutor
+
+_MISSING = object()
+_FORMATS = {"dict", "json", "mermaid", "graphviz"}
+_EXECUTORS = {"inline", "thread", "process"}
+
+
+class CompiledFunction:
+    def __init__(self, python_function: Callable[..., Any], default_format: str = "json"):
+        self.python_function = python_function
+        self._graph_ir = Compiler(python_function).compile()
+        self.default_format = _validate_format(default_format)
+        functools.update_wrapper(self, python_function)
+
+    @property
+    def graph_ir(self) -> GraphIR:
+        return self._graph_ir
+
+    def __str__(self) -> str:
+        return self.__format__("")
+
+    def __format__(self, format_spec: str) -> str:
+        format_name = self.default_format if format_spec == "" else _validate_format(format_spec)
+        rendered = get_printer(format_name).print(self.graph_ir)
+        return repr(rendered) if format_name == "dict" else rendered
+
+
+class TransformedFunction:
+    def __init__(self, compiled: CompiledFunction, executor_name: str, workers: Optional[int]):
+        self.compiled = compiled
+        self.executor_name = executor_name
+        self.workers = workers
+        functools.update_wrapper(self, compiled.python_function)
+
+    @property
+    def graph_ir(self) -> GraphIR:
+        return self.compiled.graph_ir
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        executor = _create_executor(self.executor_name, self.workers)
+        with executor:
+            return executor.run(self.compiled, args=args, kwargs=kwargs)
+
+    def __str__(self) -> str:
+        return str(self.compiled)
+
+    def __format__(self, format_spec: str) -> str:
+        return self.compiled.__format__(format_spec)
+
+
+def _validate_format(format_name: str) -> str:
+    if format_name not in _FORMATS:
+        raise ValueError(
+            "unknown graph format %r; expected one of: dict, json, mermaid, graphviz" % format_name
+        )
+    return format_name
+
+
+def compile(function: Any = _MISSING, *, format: Any = _MISSING) -> Any:
+    if function is _MISSING:
+        if format is _MISSING:
+            raise TypeError("compile() requires format when called with parentheses")
+        format_name = _validate_format(format)
+
+        def decorator(target: Callable[..., Any]) -> CompiledFunction:
+            return CompiledFunction(target, default_format=format_name)
+
+        return decorator
+    if format is not _MISSING:
+        raise TypeError("use compile(format=...) as a decorator")
+    if not callable(function):
+        raise TypeError("compile expects a Python function")
+    return CompiledFunction(function, default_format="json")
+
+
+def transform(
+    function: Any = _MISSING, *, executor: Any = _MISSING, workers: Optional[int] = None
+) -> Any:
+    if function is _MISSING:
+        if executor is _MISSING:
+            raise TypeError("transform() requires executor when called with parentheses")
+        executor_name = _validate_executor(executor, workers)
+
+        def decorator(target: Callable[..., Any]) -> TransformedFunction:
+            return TransformedFunction(CompiledFunction(target), executor_name, workers)
+
+        return decorator
+    if executor is not _MISSING:
+        raise TypeError("use transform(executor=...) as a decorator")
+    if workers is not None:
+        raise TypeError("workers requires an explicit executor")
+    if not callable(function):
+        raise TypeError("transform expects a Python function")
+    return TransformedFunction(CompiledFunction(function), "inline", None)
+
+
+def _validate_executor(executor_name: str, workers: Optional[int]) -> str:
+    if executor_name not in _EXECUTORS:
+        raise ValueError(
+            "unknown executor %r; expected one of: inline, thread, process" % executor_name
+        )
+    if executor_name == "inline":
+        if workers is not None:
+            raise ValueError("inline executor does not accept workers")
+    elif not isinstance(workers, int) or isinstance(workers, bool) or workers <= 0:
+        raise ValueError("thread and process executors require positive integer workers")
+    return executor_name
+
+
+def _create_executor(executor_name: str, workers: Optional[int]):
+    if executor_name == "inline":
+        return InlineExecutor()
+    if executor_name == "thread":
+        return ThreadExecutor(thread_num=workers)  # type: ignore[arg-type]
+    return ProcessExecutor(process_num=workers)  # type: ignore[arg-type]

task_flow/compiler/__init__.py

@@ -0,0 +1,4 @@
+from .builder import GraphBuilder
+from .compiler import Compiler, UnsupportedSyntaxError
+
+__all__ = ["Compiler", "GraphBuilder", "UnsupportedSyntaxError"]

task_flow/compiler/builder.py

@@ -0,0 +1,61 @@
+import re
+from collections import defaultdict
+from typing import Any, Callable, Tuple
+
+from task_flow.ir import GraphIR, NodeIR
+
+
+class GraphBuilder:
+    def __init__(self, name: str):
+        self.name = name
+        self._nodes = []  # type: List[NodeIR]
+        self._inputs = []  # type: List[Tuple[str, str]]
+        self._outputs = ()  # type: Tuple[str, ...]
+        self._output_kind = "none"
+        self._counts = defaultdict(int)  # type: DefaultDict[str, int]
+
+    @staticmethod
+    def _slug(value: str) -> str:
+        value = re.sub(r"[^0-9A-Za-z_.]+", "_", value).strip("_")
+        return value or "anonymous"
+
+    def _next_id(self, kind: str, name: str) -> str:
+        base = "%s.%s" % (kind, self._slug(name))
+        self._counts[base] += 1
+        occurrence = self._counts[base]
+        return base if occurrence == 1 else "%s.%s" % (base, occurrence)
+
+    def add_input(self, name: str) -> str:
+        node_id = self._next_id("input", name)
+        self._nodes.append(NodeIR(node_id, "input", name, None, ()))
+        self._inputs.append((name, node_id))
+        return node_id
+
+    def add_constant(self, value: Any) -> str:
+        node_id = self._next_id("constant", type(value).__name__)
+        self._nodes.append(NodeIR(node_id, "constant", repr(value), None, (), value=value))
+        return node_id
+
+    def add_call(
+        self, operation: Callable[..., Any], dependencies: Tuple[str, ...], name: str = ""
+    ) -> str:
+        operation_name = name or getattr(operation, "__qualname__", operation.__class__.__name__)
+        module = getattr(operation, "__module__", "")
+        display_name = "%s.%s" % (module, operation_name) if module else operation_name
+        node_id = self._next_id("call", display_name)
+        self._nodes.append(NodeIR(node_id, "call", display_name, operation, dependencies))
+        return node_id
+
+    def set_outputs(self, outputs: Tuple[str, ...], output_kind: str) -> None:
+        self._outputs = outputs
+        self._output_kind = output_kind
+
+    def build(self) -> GraphIR:
+        return GraphIR(
+            "1.0",
+            self.name,
+            tuple(self._nodes),
+            tuple(self._inputs),
+            self._outputs,
+            self._output_kind,
+        )

task_flow/compiler/compiler.py

@@ -0,0 +1,161 @@
+import ast
+import inspect
+import operator
+import textwrap
+from typing import Any, Callable
+
+from task_flow.ir import GraphIR
+
+from .builder import GraphBuilder
+
+
+class UnsupportedSyntaxError(ValueError):
+    pass
+
+
+_BINARY_OPERATIONS = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv,
+}
+
+
+class Compiler(ast.NodeVisitor):
+    def __init__(self, function: Callable[..., Any]):
+        self.function = function
+        self.builder = GraphBuilder(function.__name__)
+        self.visible = {}  # type: Dict[str, str]
+        self.environment = dict(function.__globals__)
+        closure = inspect.getclosurevars(function)
+        self.environment.update(closure.globals)
+        self.environment.update(closure.nonlocals)
+        self.environment.update(closure.builtins)
+        self._returned = False
+
+    def compile(self) -> GraphIR:
+        try:
+            source = textwrap.dedent(inspect.getsource(self.function))
+        except (OSError, TypeError) as exc:
+            raise ValueError(
+                "cannot read source for function %s" % self.function.__qualname__
+            ) from exc
+        module = ast.parse(source)
+        function_node = next(
+            (node for node in module.body if isinstance(node, ast.FunctionDef)), None
+        )
+        if function_node is None:
+            raise UnsupportedSyntaxError("only regular Python functions are supported")
+        self.visit(function_node)
+        if not self._returned:
+            self.builder.set_outputs((), "none")
+        return self.builder.build()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        if node.args.posonlyargs or node.args.kwonlyargs or node.args.vararg or node.args.kwarg:
+            raise UnsupportedSyntaxError(
+                "positional-only, keyword-only and variadic parameters are not supported"
+            )
+        if node.args.defaults or node.args.kw_defaults:
+            raise UnsupportedSyntaxError("default parameters are not supported")
+        for argument in node.args.args:
+            self.visible[argument.arg] = self.builder.add_input(argument.arg)
+        for statement in node.body:
+            self.visit(statement)
+            if self._returned:
+                break
+
+    def generic_visit(self, node: ast.AST) -> None:
+        raise UnsupportedSyntaxError("unsupported syntax: %s" % type(node).__name__)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        if len(node.targets) != 1:
+            raise UnsupportedSyntaxError("chained assignment is not supported")
+        target = node.targets[0]
+        if isinstance(target, (ast.Tuple, ast.List)):
+            if not isinstance(node.value, type(target)):
+                raise UnsupportedSyntaxError("unpacking requires a matching literal")
+            if len(target.elts) != len(node.value.elts):
+                raise UnsupportedSyntaxError("unpacking target size mismatch")
+            for target_item, value_item in zip(target.elts, node.value.elts):
+                self._assign_name(target_item, self._compile_expression(value_item))
+            return
+        self._assign_name(target, self._compile_expression(node.value))
+
+    def _assign_name(self, target: ast.AST, node_id: str) -> None:
+        if not isinstance(target, ast.Name):
+            raise UnsupportedSyntaxError("only name assignment is supported")
+        self.visible[target.id] = node_id
+
+    def visit_Expr(self, node: ast.Expr) -> None:
+        self._compile_expression(node.value)
+
+    def visit_Return(self, node: ast.Return) -> None:
+        if self._returned:
+            raise UnsupportedSyntaxError("multiple return statements are not supported")
+        self._returned = True
+        if node.value is None or (
+            isinstance(node.value, ast.Constant) and node.value.value is None
+        ):
+            self.builder.set_outputs((), "none")
+        elif isinstance(node.value, ast.Tuple):
+            self.builder.set_outputs(
+                tuple(self._compile_expression(item) for item in node.value.elts), "tuple"
+            )
+        elif isinstance(node.value, ast.List):
+            self.builder.set_outputs(
+                tuple(self._compile_expression(item) for item in node.value.elts), "list"
+            )
+        else:
+            self.builder.set_outputs((self._compile_expression(node.value),), "single")
+
+    def _compile_expression(self, node: ast.AST) -> str:
+        if isinstance(node, ast.Name):
+            if node.id not in self.visible:
+                raise UnsupportedSyntaxError("unknown local name: %s" % node.id)
+            return self.visible[node.id]
+        if isinstance(node, ast.Constant):
+            return self.builder.add_constant(node.value)
+        if isinstance(node, ast.BinOp):
+            operation = _BINARY_OPERATIONS.get(type(node.op))
+            if operation is None:
+                raise UnsupportedSyntaxError(
+                    "unsupported binary operation: %s" % type(node.op).__name__
+                )
+            return self.builder.add_call(
+                operation,
+                (self._compile_expression(node.left), self._compile_expression(node.right)),
+            )
+        if isinstance(node, ast.Call):
+            return self._compile_call(node)
+        raise UnsupportedSyntaxError("unsupported expression: %s" % type(node).__name__)
+
+    def _compile_call(self, node: ast.Call) -> str:
+        if node.keywords:
+            raise UnsupportedSyntaxError("keyword call arguments are not supported")
+        function = self._resolve_callable(node.func)
+        return self.builder.add_call(
+            function, tuple(self._compile_expression(item) for item in node.args)
+        )
+
+    def _resolve_callable(self, node: ast.AST) -> Callable[..., Any]:
+        value = (
+            self.environment.get(node.id)
+            if isinstance(node, ast.Name)
+            else self._resolve_value(node)
+            if isinstance(node, ast.Attribute)
+            else None
+        )
+        if not callable(value):
+            raise UnsupportedSyntaxError("cannot resolve callable from source")
+        return value
+
+    def _resolve_value(self, node: ast.AST) -> Any:
+        if isinstance(node, ast.Name):
+            if node.id not in self.environment:
+                raise UnsupportedSyntaxError("unknown global name: %s" % node.id)
+            return self.environment[node.id]
+        if isinstance(node, ast.Attribute):
+            return getattr(self._resolve_value(node.value), node.attr)
+        raise UnsupportedSyntaxError("unsupported callable reference")

task_flow/ir/__init__.py

@@ -0,0 +1,3 @@
+from .graph import GraphIR, NodeIR
+
+__all__ = ["GraphIR", "NodeIR"]

task_flow/ir/graph.py

@@ -0,0 +1,68 @@
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Iterator, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class NodeIR:
+    id: str
+    kind: str
+    name: str
+    operation: Optional[Callable[..., Any]]
+    dependencies: Tuple[str, ...]
+    value: Any = None
+
+    def __post_init__(self) -> None:
+        if self.kind not in {"input", "constant", "call"}:
+            raise ValueError("unknown node kind: %s" % self.kind)
+        if self.kind == "call" and self.operation is None:
+            raise ValueError("call node %s requires an operation" % self.id)
+        if self.kind != "call" and self.operation is not None:
+            raise ValueError("%s node %s cannot define an operation" % (self.kind, self.id))
+
+
+@dataclass(frozen=True)
+class GraphIR:
+    ir_version: str
+    name: str
+    nodes: Tuple[NodeIR, ...]
+    inputs: Tuple[Tuple[str, str], ...]
+    outputs: Tuple[str, ...]
+    output_kind: str
+
+    def __post_init__(self) -> None:
+        if self.ir_version != "1.0":
+            raise ValueError("unsupported GraphIR version: %s" % self.ir_version)
+        if self.output_kind not in {"none", "single", "tuple", "list"}:
+            raise ValueError("unknown output kind: %s" % self.output_kind)
+        node_map = self.node_map
+        if len(node_map) != len(self.nodes):
+            raise ValueError("GraphIR node IDs must be unique")
+        for node in self.nodes:
+            for dependency in node.dependencies:
+                if dependency not in node_map:
+                    raise ValueError("node %s depends on missing node %s" % (node.id, dependency))
+        input_ids = []
+        input_names = []
+        for name, node_id in self.inputs:
+            if name in input_names:
+                raise ValueError("duplicate input name: %s" % name)
+            if node_id in input_ids:
+                raise ValueError("duplicate input node: %s" % node_id)
+            if node_id not in node_map or node_map[node_id].kind != "input":
+                raise ValueError("invalid input node: %s" % node_id)
+            input_names.append(name)
+            input_ids.append(node_id)
+        for output in self.outputs:
+            if output not in node_map:
+                raise ValueError("invalid output node: %s" % output)
+        if self.output_kind == "single" and len(self.outputs) != 1:
+            raise ValueError("single output requires one node")
+        if self.output_kind == "none" and self.outputs:
+            raise ValueError("none output cannot contain output nodes")
+
+    @property
+    def node_map(self) -> Dict[str, NodeIR]:
+        return {node.id: node for node in self.nodes}
+
+    def __iter__(self) -> Iterator[NodeIR]:
+        return iter(self.nodes)

task_flow/printer/__init__.py

@@ -0,0 +1,3 @@
+from .printer import DictPrinter, GraphvizPrinter, JsonPrinter, MermaidPrinter, get_printer
+
+__all__ = ["DictPrinter", "GraphvizPrinter", "JsonPrinter", "MermaidPrinter", "get_printer"]

task_flow/printer/printer.py

@@ -0,0 +1,112 @@
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+from task_flow.ir import GraphIR, NodeIR
+
+
+def _operation_name(node: NodeIR) -> Any:
+    if node.operation is None:
+        return None
+    module = getattr(node.operation, "__module__", "")
+    name = getattr(node.operation, "__qualname__", node.operation.__class__.__name__)
+    return "%s.%s" % (module, name) if module else name
+
+
+class Printer(ABC):
+    @abstractmethod
+    def print(self, graph: GraphIR) -> Any:
+        raise NotImplementedError
+
+
+class DictPrinter(Printer):
+    def print(self, graph: GraphIR) -> Dict[str, Any]:
+        nodes = []
+        for node in graph.nodes:
+            item = {
+                "id": node.id,
+                "kind": node.kind,
+                "name": node.name,
+                "dependencies": list(node.dependencies),
+            }
+            operation = _operation_name(node)
+            if operation is not None:
+                item["operation"] = operation
+            if node.kind == "constant":
+                item["value"] = node.value
+            nodes.append(item)
+        return {
+            "ir_version": graph.ir_version,
+            "name": graph.name,
+            "inputs": [{"name": name, "node": node_id} for name, node_id in graph.inputs],
+            "outputs": list(graph.outputs),
+            "output_kind": graph.output_kind,
+            "nodes": nodes,
+        }
+
+
+class JsonPrinter(Printer):
+    def print(self, graph: GraphIR) -> str:
+        return json.dumps(DictPrinter().print(graph), indent=2, ensure_ascii=False, default=repr)
+
+
+def _mermaid_text(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ")
+
+
+class MermaidPrinter(Printer):
+    def print(self, graph: GraphIR) -> str:
+        lines = ["flowchart TD"]
+        for index, node in enumerate(graph.nodes):
+            alias = "n%s" % index
+            shape = (
+                '(["%s"])'
+                if node.kind == "input"
+                else '{{"%s"}}'
+                if node.kind == "constant"
+                else '["%s"]'
+            )
+            lines.append("    %s%s" % (alias, shape % _mermaid_text(node.name)))
+        aliases = {node.id: "n%s" % index for index, node in enumerate(graph.nodes)}
+        for node in graph.nodes:
+            for dependency in node.dependencies:
+                lines.append("    %s --> %s" % (aliases[dependency], aliases[node.id]))
+        return "\n".join(lines)
+
+
+def _dot_text(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+class GraphvizPrinter(Printer):
+    def print(self, graph: GraphIR) -> str:
+        lines = ['digraph "%s" {' % _dot_text(graph.name)]
+        aliases = {node.id: "n%s" % index for index, node in enumerate(graph.nodes)}
+        shapes = {"input": "oval", "constant": "diamond", "call": "box"}
+        for node in graph.nodes:
+            lines.append(
+                '  %s [label="%s", shape=%s];'
+                % (aliases[node.id], _dot_text(node.name), shapes[node.kind])
+            )
+        for node in graph.nodes:
+            for dependency in node.dependencies:
+                lines.append("  %s -> %s;" % (aliases[dependency], aliases[node.id]))
+        lines.append("}")
+        return "\n".join(lines)
+
+
+_PRINTERS = {
+    "dict": DictPrinter,
+    "json": JsonPrinter,
+    "mermaid": MermaidPrinter,
+    "graphviz": GraphvizPrinter,
+}
+
+
+def get_printer(format_name: str) -> Printer:
+    try:
+        return _PRINTERS[format_name]()
+    except KeyError as exc:
+        raise ValueError(
+            "unknown graph format %r; expected one of: %s" % (format_name, ", ".join(_PRINTERS))
+        ) from exc

task_flow/runtime/__init__.py

@@ -0,0 +1,3 @@
+from .executor import Executor, InlineExecutor, ProcessExecutor, ThreadExecutor
+
+__all__ = ["Executor", "InlineExecutor", "ProcessExecutor", "ThreadExecutor"]

task_flow/runtime/executor.py

@@ -0,0 +1,140 @@
+import multiprocessing
+from abc import ABC, abstractmethod
+from concurrent.futures import (
+    FIRST_COMPLETED,
+    Future,
+    ProcessPoolExecutor,
+    ThreadPoolExecutor,
+    wait,
+)
+from typing import Any, Dict, Optional, Tuple
+
+from task_flow.ir import GraphIR, NodeIR
+
+__all__ = ["Executor", "InlineExecutor", "ProcessExecutor", "ThreadExecutor"]
+
+
+class Executor(ABC):
+    def __enter__(self) -> "Executor":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        self.close()
+        return False
+
+    def close(self) -> None:
+        pass
+
+    def run(
+        self, function: Any, args: Tuple[Any, ...] = (), kwargs: Optional[Dict[str, Any]] = None
+    ) -> Any:
+        if not hasattr(function, "graph_ir") or not hasattr(function, "python_function"):
+            raise TypeError("Executor.run expects a CompiledFunction")
+        kwargs = {} if kwargs is None else dict(kwargs)
+        bound = __import__("inspect").signature(function.python_function).bind(*args, **kwargs)
+        graph = function.graph_ir  # type: GraphIR
+        values = {}  # type: Dict[str, Any]
+        for name, node_id in graph.inputs:
+            values[node_id] = bound.arguments[name]
+        for node in graph.nodes:
+            if node.kind == "constant":
+                values[node.id] = node.value
+
+        calls = [node for node in graph.nodes if node.kind == "call"]
+        waiting = {
+            node.id: sum(dependency not in values for dependency in node.dependencies)
+            for node in calls
+        }
+        children = {}  # type: Dict[str, list]
+        for node in calls:
+            for dependency in node.dependencies:
+                children.setdefault(dependency, []).append(node.id)
+        node_map = graph.node_map
+        pending = {}  # type: Dict[Future, NodeIR]
+
+        def submit(node: NodeIR) -> None:
+            inputs = tuple(values[dependency] for dependency in node.dependencies)
+            pending[self._submit(node, inputs)] = node
+
+        for node in calls:
+            if waiting[node.id] == 0:
+                submit(node)
+
+        completed = 0
+        while pending:
+            future = self._wait_any(tuple(pending))
+            node = pending.pop(future)
+            values[node.id] = future.result()
+            completed += 1
+            for child_id in children.get(node.id, ()):
+                waiting[child_id] -= 1
+                if waiting[child_id] == 0:
+                    submit(node_map[child_id])
+
+        if completed != len(calls):
+            blocked = sorted(node.id for node in calls if node.id not in values)
+            raise ValueError("GraphIR contains a cycle or unresolved dependencies: %s" % blocked)
+        return self._build_result(graph, values)
+
+    @staticmethod
+    def _build_result(graph: GraphIR, values: Dict[str, Any]) -> Any:
+        results = tuple(values[node_id] for node_id in graph.outputs)
+        if graph.output_kind == "none":
+            return None
+        if graph.output_kind == "single":
+            return results[0]
+        if graph.output_kind == "list":
+            return list(results)
+        return results
+
+    @abstractmethod
+    def _submit(self, node: NodeIR, inputs: Tuple[Any, ...]) -> Future:
+        raise NotImplementedError
+
+    @abstractmethod
+    def _wait_any(self, futures: Tuple[Future, ...]) -> Future:
+        raise NotImplementedError
+
+
+class InlineExecutor(Executor):
+    def _submit(self, node: NodeIR, inputs: Tuple[Any, ...]) -> Future:
+        future = Future()
+        try:
+            future.set_result(node.operation(*inputs))  # type: ignore[misc]
+        except BaseException as exc:
+            future.set_exception(exc)
+        return future
+
+    def _wait_any(self, futures: Tuple[Future, ...]) -> Future:
+        return futures[0]
+
+
+class _PoolExecutor(Executor):
+    pool = None
+
+    def _submit(self, node: NodeIR, inputs: Tuple[Any, ...]) -> Future:
+        return self.pool.submit(node.operation, *inputs)
+
+    def _wait_any(self, futures: Tuple[Future, ...]) -> Future:
+        done, _ = wait(futures, return_when=FIRST_COMPLETED)
+        return next(iter(done))
+
+    def close(self) -> None:
+        if self.pool is not None:
+            self.pool.shutdown(wait=True)
+
+
+class ThreadExecutor(_PoolExecutor):
+    def __init__(self, thread_num: int):
+        if thread_num <= 0:
+            raise ValueError("thread_num must be positive")
+        self.pool = ThreadPoolExecutor(max_workers=thread_num)
+
+
+class ProcessExecutor(_PoolExecutor):
+    def __init__(self, process_num: int):
+        if process_num <= 0:
+            raise ValueError("process_num must be positive")
+        methods = multiprocessing.get_all_start_methods()
+        context = multiprocessing.get_context("fork") if "fork" in methods else None
+        self.pool = ProcessPoolExecutor(max_workers=process_num, mp_context=context)

taskflow_tr-0.1.0.dist-info/METADATA

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: taskflow-tr
+Version: 0.1.0
+Summary: Compile Python functions into GraphIR DAGs and execute them inline, with threads, or with processes.
+Author-email: gaoxinge <gaoxx5@gmail.com>
+Maintainer-email: gaoxinge <gaoxx5@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 gaoxinge
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/gaoxinge/task_flow
+Project-URL: Repository, https://github.com/gaoxinge/task_flow
+Project-URL: Issues, https://github.com/gaoxinge/task_flow/issues
+Project-URL: Documentation, https://github.com/gaoxinge/task_flow#readme
+Keywords: dag,graph-ir,workflow,concurrency,threading,multiprocessing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: examples
+Requires-Dist: flask>=2; extra == "examples"
+Requires-Dist: grpcio>=1.48; extra == "examples"
+Requires-Dist: grpcio-tools>=1.48; extra == "examples"
+Requires-Dist: protobuf>=3.20; extra == "examples"
+Requires-Dist: requests>=2; extra == "examples"
+Dynamic: license-file
+
+# taskflow-tr
+
+taskflow-tr 将一小部分 Python 函数编译成静态 `GraphIR`，可打印计算图，也可使用串行、线程池或进程池执行。PyPI 发行名是 `taskflow-tr`，Python 导入名是 `task_flow`。
+
+## 环境与安装
+
+项目最低支持 Python 3.8。通过 PyPI 安装核心包：
+
+```bash
+pip install taskflow-tr
+```
+
+如需运行 README 中的 HTTP 和 gRPC 集成示例：
+
+```bash
+pip install "taskflow-tr[examples]"
+```
+
+项目开发环境使用 [uv](https://docs.astral.sh/uv/) 管理：
+
+```bash
+uv sync --all-groups
+```
+
+## 直接执行函数
+
+`@transform` 默认使用 `InlineExecutor`：
+
+```python
+from task_flow import transform
+
+
+@transform
+def add(a, b):
+    return a + b
+
+
+assert add(2, b=1) == 3
+```
+
+显式使用线程池或进程池时必须指定工作数量：
+
+```python
+@transform(executor="thread", workers=4)
+def threaded_add(a, b):
+    return a + b
+
+
+@transform(executor="process", workers=4)
+def process_add(a, b):
+    return a + b
+```
+
+`@transform()` 是非法形式；带括号时必须显式传入 `executor`。
+
+## 编译和打印 GraphIR
+
+`@compile` 只编译函数，不绑定执行策略。`print()` 默认输出 JSON：
+
+```python
+from task_flow import compile
+
+
+@compile
+def add(a, b):
+    return a + b
+
+
+print(add)
+print(format(add, "dict"))
+print(format(add, "mermaid"))
+print(format(add, "graphviz"))
+```
+
+也可以在装饰时改变默认打印格式：
+
+```python
+@compile(format="mermaid")
+def workflow(a, b):
+    return a + b
+
+
+print(workflow)
+```
+
+支持 `dict`、`json`、`mermaid` 和 `graphviz` 四种格式。Graphviz 格式返回 DOT 源码，不要求 Runtime 安装 Graphviz。
+
+`@compile()` 是非法形式；带括号时必须显式传入 `format`。
+
+## 显式选择 Executor
+
+编译结果可以被不同 Executor 重复执行，无需重新编译：
+
+```python
+from task_flow import InlineExecutor, ProcessExecutor, ThreadExecutor
+
+
+with InlineExecutor() as executor:
+    assert executor.run(add, args=(2,), kwargs={"b": 1}) == 3
+
+with ThreadExecutor(thread_num=4) as executor:
+    assert executor.run(add, args=(2, 1)) == 3
+
+with ProcessExecutor(process_num=4) as executor:
+    assert executor.run(add, args=(2, 1)) == 3
+```
+
+线程执行适合 I/O 或会释放 GIL 的扩展调用；进程执行适合 CPU 密集型 Python 代码。进程池中的调用函数与参数必须能被 `pickle` 序列化，应优先使用模块顶层命名函数，避免 lambda 和局部函数。
+
+## 完整示例
+
+### 并行计算与 Graphviz 输出
+
+下面的计算图包含四个相互独立的运算节点，线程 Executor 可以并发执行它们：
+
+```python
+import time
+from operator import add, floordiv, mul, sub
+
+from task_flow import compile, transform
+
+
+def delayed(operation, x, y):
+    time.sleep(0.1)
+    return operation(x, y)
+
+
+def add0(x, y):
+    return delayed(add, x, y)
+
+
+def sub0(x, y):
+    return delayed(sub, x, y)
+
+
+def mul0(x, y):
+    return delayed(mul, x, y)
+
+
+def div0(x, y):
+    return delayed(floordiv, x, y)
+
+
+@transform(executor="thread", workers=4)
+def compute_graph(a, b):
+    result_add = add0(a, b)
+    result_sub = sub0(a, b)
+    result_mul = mul0(a, b)
+    result_div = div0(a, b)
+    return result_add, result_sub, result_mul, result_div
+
+
+assert compute_graph(2, 1) == (3, 1, 2, 2)
+
+
+@compile(format="graphviz")
+def printable_graph(a, b):
+    result_add = a + b
+    result_sub = a - b
+    result_mul = a * b
+    result_div = a // b
+    return result_add, result_sub, result_mul, result_div
+
+
+print(printable_graph)  # 输出 DOT 源码
+```
+
+### 集成 HTTP 服务
+
+HTTP 和 gRPC 只是 `TransformedFunction` 的调用入口，调度逻辑仍由 taskflow-tr 管理。安装示例依赖：
+
+```bash
+uv sync --extra examples
+```
+
+使用 Flask 暴露计算接口：
+
+```python
+from flask import Flask, jsonify, request
+
+
+app = Flask(__name__)
+
+
+@app.post("/compute")
+def compute():
+    inputs = request.get_json()
+    x, y, z, w = compute_graph(inputs["x"], inputs["y"])
+    return jsonify({"x": x, "y": y, "z": z, "w": w})
+
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=8000)
+```
+
+请求示例：
+
+```python
+import requests
+
+
+response = requests.post(
+    "http://127.0.0.1:8000/compute",
+    json={"x": 2, "y": 1},
+    timeout=30,
+)
+assert response.json() == {"x": 3, "y": 1, "z": 2, "w": 2}
+```
+
+### 集成 gRPC 服务
+
+先定义 `compute.proto`：
+
+```proto
+syntax = "proto3";
+package example;
+
+message Inputs {
+    int32 x = 1;
+    int32 y = 2;
+}
+
+message Outputs {
+    int32 x = 1;
+    int32 y = 2;
+    int32 z = 3;
+    int32 w = 4;
+}
+
+service App {
+    rpc Compute (Inputs) returns (Outputs);
+}
+```
+
+生成 Python 代码：
+
+```bash
+uv run python -m grpc_tools.protoc \
+  -I. \
+  --python_out=. \
+  --grpc_python_out=. \
+  compute.proto
+```
+
+在生成的服务接口中调用同一个 `compute_graph`：
+
+```python
+from concurrent import futures
+
+import grpc
+import compute_pb2
+import compute_pb2_grpc
+
+
+class App(compute_pb2_grpc.AppServicer):
+    def Compute(self, inputs, context):
+        x, y, z, w = compute_graph(inputs.x, inputs.y)
+        return compute_pb2.Outputs(x=x, y=y, z=z, w=w)
+
+
+server = grpc.server(futures.ThreadPoolExecutor(max_workers=3))
+compute_pb2_grpc.add_AppServicer_to_server(App(), server)
+server.add_insecure_port("0.0.0.0:8000")
+server.start()
+server.wait_for_termination()
+```
+
+## V1 编译范围
+
+V1 支持普通位置或关键字参数、常量、简单赋值、普通函数调用、`+`、`-`、`*`、`/`、`//`，以及 `None`、单值、tuple 和 list 返回。条件、循环、递归、可变参数、默认参数和关键字调用参数尚未纳入 V1。
+
+总体流程：
+
+```text
+Python Source -> Python AST -> GraphIR -> Executor -> Result
+                                  |
+                                  +-> Printer -> dict / JSON / Mermaid / Graphviz
+```
+
+V1 不包含 Planner、ExecutablePlanIR、Dask、Ray 或 MPI 后端。设计说明见 [`docs/v1/dev.md`](docs/v1/dev.md)。
+
+## 开发
+
+```bash
+uv run pytest
+uv run python -m benchmarks.benchmark_executor
+```

taskflow_tr-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+task_flow/__init__.py,sha256=jw7xigbwdpbVjGB8RP-EYPJSsVU0KUxzNgFLjbiMcFk,335
+task_flow/api.py,sha256=Zv7wfgqEcfOZWJWumORSGd43w3AzjYIBCdKZ30zqfUA,4642
+task_flow/compiler/__init__.py,sha256=g2_LuWHt5rqbKaaVbDO2iJKQ5fD6EcgrWbfXJeQ6pgU,155
+task_flow/compiler/builder.py,sha256=ULLO6Tgu08yeRwGxda08qQqOcDW4zp6guzhctKdsPjI,2249
+task_flow/compiler/compiler.py,sha256=BrM6225_365fSrTTmepnloRT7geyF9kY8ztXTM7ChCw,6652
+task_flow/ir/__init__.py,sha256=hHuEgw5BDUGO9iso2p0C_0MATIbd2uZLyFIFCaznO0U,68
+task_flow/ir/graph.py,sha256=kWA0CWvLp0zb5oCl2Luojttx80YGong-XBmRZ4_eF8o,2721
+task_flow/printer/__init__.py,sha256=DyyN0Chjp6Fphh_wgSivXbUlSA0m5roCSmI75VXrPj8,186
+task_flow/printer/printer.py,sha256=Xs6hFdbYo-WqaUU6YARGprwepnS4iF9cv-RjmTx6Wh8,3712
+task_flow/runtime/__init__.py,sha256=ANHuKxQ0rcTvCNxOh50Cws0lKAIKVVMYdjTUcZRRRA4,159
+task_flow/runtime/executor.py,sha256=9W96zKAmnq9Eedp3XKhgdH6CKTLRTQNLOnW4jW1ic-4,4876
+taskflow_tr-0.1.0.dist-info/licenses/LICENSE,sha256=0-vpht0C3dJgVh7KnbT1wjz--5Yd_jznV74lQuSthEQ,1065
+taskflow_tr-0.1.0.dist-info/METADATA,sha256=6WQb4-DTHmx2jRXm6ufEXwyNEJ2kFPWvYXBBZIbJBSE,8963
+taskflow_tr-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+taskflow_tr-0.1.0.dist-info/top_level.txt,sha256=oMr2tOAseQ0qj3RIu9FTFz9Chwk5q_mq6Q0T8WHEFu0,10
+taskflow_tr-0.1.0.dist-info/RECORD,,

taskflow_tr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

taskflow_tr-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gaoxinge
+
+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.

taskflow_tr-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+task_flow