tasktronaut 0.1.0__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.
Files changed (32) hide show
  1. tasktronaut-0.1.0/LICENSE +21 -0
  2. tasktronaut-0.1.0/PKG-INFO +30 -0
  3. tasktronaut-0.1.0/README.md +10 -0
  4. tasktronaut-0.1.0/pyproject.toml +99 -0
  5. tasktronaut-0.1.0/setup.cfg +4 -0
  6. tasktronaut-0.1.0/tasktronaut/__init__.py +14 -0
  7. tasktronaut-0.1.0/tasktronaut/backend.py +129 -0
  8. tasktronaut-0.1.0/tasktronaut/backends/__init__.py +0 -0
  9. tasktronaut-0.1.0/tasktronaut/backends/rq.py +86 -0
  10. tasktronaut-0.1.0/tasktronaut/builder.py +151 -0
  11. tasktronaut-0.1.0/tasktronaut/context.py +2 -0
  12. tasktronaut-0.1.0/tasktronaut/decorators.py +28 -0
  13. tasktronaut-0.1.0/tasktronaut/errors.py +6 -0
  14. tasktronaut-0.1.0/tasktronaut/process.py +203 -0
  15. tasktronaut-0.1.0/tasktronaut/py.typed +0 -0
  16. tasktronaut-0.1.0/tasktronaut/steps.py +32 -0
  17. tasktronaut-0.1.0/tasktronaut/types.py +53 -0
  18. tasktronaut-0.1.0/tasktronaut/utils.py +26 -0
  19. tasktronaut-0.1.0/tasktronaut.egg-info/PKG-INFO +30 -0
  20. tasktronaut-0.1.0/tasktronaut.egg-info/SOURCES.txt +30 -0
  21. tasktronaut-0.1.0/tasktronaut.egg-info/dependency_links.txt +1 -0
  22. tasktronaut-0.1.0/tasktronaut.egg-info/requires.txt +1 -0
  23. tasktronaut-0.1.0/tasktronaut.egg-info/top_level.txt +1 -0
  24. tasktronaut-0.1.0/tests/test_backend.py +96 -0
  25. tasktronaut-0.1.0/tests/test_builder.py +189 -0
  26. tasktronaut-0.1.0/tests/test_context.py +9 -0
  27. tasktronaut-0.1.0/tests/test_decorators.py +29 -0
  28. tasktronaut-0.1.0/tests/test_errors.py +15 -0
  29. tasktronaut-0.1.0/tests/test_examples.py +211 -0
  30. tasktronaut-0.1.0/tests/test_process.py +147 -0
  31. tasktronaut-0.1.0/tests/test_steps.py +35 -0
  32. tasktronaut-0.1.0/tests/test_utils.py +27 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Chris Stefano
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,30 @@
1
+ Metadata-Version: 2.4
2
+ Name: tasktronaut
3
+ Version: 0.1.0
4
+ Summary: A simple task orchestration library for running complex processes or workflows in Python.
5
+ Author-email: Chris Stefano <virtualstaticvoid@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: homepage, https://github.com/virtualstaticvoid/tasktronaut
8
+ Project-URL: documentation, https://pytorch-geometric.readthedocs.io
9
+ Project-URL: repository, https://github.com/virtualstaticvoid/tasktronaut.git
10
+ Project-URL: changelog, https://github.com/virtualstaticvoid/tasktronaut/blob/main/CHANGELOG.md
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Programming Language :: Python
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Requires-Python: >=3.10
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: pydantic>=2.12.4
19
+ Dynamic: license-file
20
+
21
+ # tasktronaut
22
+
23
+ A lightweight task orchestration library for building and running complex workflows in Python.
24
+
25
+ Define workflows using a simple expressive DSL, with minimal boilerplate. Once defined, processes
26
+ can be queued and executed with support for both sequential and concurrent DAG based execution.
27
+
28
+ ## License
29
+
30
+ MIT Copyright (c) 2025 Chris Stefano
@@ -0,0 +1,10 @@
1
+ # tasktronaut
2
+
3
+ A lightweight task orchestration library for building and running complex workflows in Python.
4
+
5
+ Define workflows using a simple expressive DSL, with minimal boilerplate. Once defined, processes
6
+ can be queued and executed with support for both sequential and concurrent DAG based execution.
7
+
8
+ ## License
9
+
10
+ MIT Copyright (c) 2025 Chris Stefano
@@ -0,0 +1,99 @@
1
+ [project]
2
+ name = "tasktronaut"
3
+ version = "0.1.0"
4
+ description = "A simple task orchestration library for running complex processes or workflows in Python."
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [
10
+ { name = "Chris Stefano", email = "virtualstaticvoid@gmail.com" },
11
+ ]
12
+ classifiers = [
13
+ "Development Status :: 5 - Production/Stable",
14
+ "Programming Language :: Python",
15
+ "Programming Language :: Python :: 3.13",
16
+ "Programming Language :: Python :: 3 :: Only",
17
+ ]
18
+ dependencies = [
19
+ "pydantic>=2.12.4",
20
+ ]
21
+
22
+ [dependency-groups]
23
+ dev = [
24
+ { include-group = "build" },
25
+ { include-group = "dagster" },
26
+ { include-group = "django-rq" },
27
+ { include-group = "rq" },
28
+ { include-group = "test" },
29
+ "ruff>=0.14.4",
30
+ "pylint>=4.0.2",
31
+ "mypy>=1.18.2",
32
+ ]
33
+ rq = [
34
+ "redis>=7.0.1",
35
+ "rq>=2.6.0",
36
+ ]
37
+ django-rq = [
38
+ "django-rq>=3.1",
39
+ ]
40
+ dagster = [
41
+ "dagster>=1.12.0",
42
+ ]
43
+ test = [
44
+ "pytest>=8.4.2",
45
+ "pytest-cov>=7.0.0",
46
+ ]
47
+ build = [
48
+ "setuptools>=80.9.0",
49
+ "wheel>=0.45.1",
50
+ ]
51
+ docs = [
52
+ "sphinx>=5.0",
53
+ "sphinx-rtd-theme>=1.0",
54
+ ]
55
+
56
+ [project.urls]
57
+ homepage = "https://github.com/virtualstaticvoid/tasktronaut"
58
+ documentation = "https://pytorch-geometric.readthedocs.io"
59
+ repository = "https://github.com/virtualstaticvoid/tasktronaut.git"
60
+ changelog = "https://github.com/virtualstaticvoid/tasktronaut/blob/main/CHANGELOG.md"
61
+
62
+ [tool.ruff.format]
63
+ quote-style = "double"
64
+
65
+ [tool.ruff.lint.pydocstyle]
66
+ convention = "pep257"
67
+
68
+ [tool.pylint]
69
+ disable = [
70
+ # for now, disable docstring checks
71
+ "C0114", # missing-module-docstring
72
+ "C0115", # missing-class-docstring
73
+ "C0116", # missing-function-docstring
74
+ ]
75
+
76
+ [tool.mypy]
77
+ check_untyped_defs = true
78
+ show_column_numbers = true
79
+ strict_optional = true
80
+ warn_redundant_casts = true
81
+ warn_return_any = true
82
+ warn_unused_ignores = true
83
+
84
+ [tool.pytest.ini_options]
85
+ testpaths = ["tests"]
86
+ python_files = "test*.py"
87
+ addopts = "--cov=tasktronaut --cov-report=term --cov-report html"
88
+
89
+ [tool.coverage.run]
90
+ branch = true
91
+ parallel = true
92
+ source = ["tasktronaut"]
93
+
94
+ [tool.coverage.report]
95
+ show_missing = true
96
+
97
+ [build-system]
98
+ requires = ["setuptools>=80.9.0", "wheel>=0.45.1"]
99
+ build-backend = "setuptools.build_meta"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,14 @@
1
+ from .backend import Backend
2
+ from .builder import Builder
3
+ from .context import Context
4
+ from .decorators import task
5
+ from .process import ExecutionMode, ProcessDefinition
6
+
7
+ __all__ = (
8
+ "Backend",
9
+ "Builder",
10
+ "Context",
11
+ "ExecutionMode",
12
+ "ProcessDefinition",
13
+ "task",
14
+ )
@@ -0,0 +1,129 @@
1
+ import logging
2
+ from abc import ABC, abstractmethod
3
+ from typing import Any, Dict, List, Optional, Protocol, Union
4
+
5
+ from .context import Context
6
+ from .errors import CancelProcessError, NonRetryableProcessError
7
+ from .types import Description
8
+ from .utils import load_definition
9
+
10
+ logger = logging.getLogger(__name__)
11
+
12
+
13
+ class Job(Protocol):
14
+ def cancel(self): # pragma: no cover
15
+ pass
16
+
17
+ def delete_dependents(self): # pragma: no cover
18
+ pass
19
+
20
+
21
+ # pylint: disable=too-many-arguments,too-many-positional-arguments
22
+ class Backend(ABC):
23
+ @abstractmethod
24
+ def enqueue_perform_start(
25
+ self,
26
+ identifier: str,
27
+ module_name: str,
28
+ definition_class: str,
29
+ depends_on: Optional[Job] = None,
30
+ ) -> Job: # pragma: no cover
31
+ pass
32
+
33
+ @staticmethod
34
+ def perform_start(
35
+ identifier: str,
36
+ module_name: str,
37
+ definition_class: str,
38
+ ):
39
+ definition = load_definition(module_name, definition_class)
40
+ definition.on_started(identifier)
41
+
42
+ @abstractmethod
43
+ def enqueue_perform_task(
44
+ self,
45
+ identifier: str,
46
+ module_name: str,
47
+ definition_class: str,
48
+ function_name: str,
49
+ description: Description,
50
+ kwargs: Dict[str, Any],
51
+ depends_on: Optional[Job] = None,
52
+ ) -> Job: # pragma: no cover
53
+ pass
54
+
55
+ @classmethod
56
+ def perform_task(
57
+ cls,
58
+ job: Job,
59
+ identifier: str,
60
+ module_name: str,
61
+ definition_class: str,
62
+ function_name: str,
63
+ description: Description,
64
+ kwargs: Dict[str, Any],
65
+ ):
66
+ definition = load_definition(module_name, definition_class)
67
+ task_func = getattr(definition, function_name)
68
+ context = Context()
69
+ try:
70
+ with definition.around_task(
71
+ identifier=identifier,
72
+ step=function_name,
73
+ description=description,
74
+ ):
75
+ task_func(context=context, **kwargs)
76
+
77
+ except NonRetryableProcessError as e:
78
+ logger.error(
79
+ "Failed to execute task '%s', a non-retryable error was raised.",
80
+ function_name,
81
+ exc_info=True,
82
+ stack_info=True,
83
+ )
84
+ definition.on_failed(identifier, function_name, e)
85
+ # re-raise error to fail job
86
+ raise
87
+
88
+ except CancelProcessError:
89
+ logger.error(
90
+ "Failed to execute task '%s', the process was cancelled.",
91
+ function_name,
92
+ exc_info=True,
93
+ stack_info=True,
94
+ )
95
+ job.cancel()
96
+ job.delete_dependents() # clean up
97
+ definition.on_cancelled(identifier)
98
+ # ignore error
99
+
100
+ except Exception as e:
101
+ logger.error(
102
+ "Failed to execute task '%s' due to an unhandled error. "
103
+ "The task will be retried.",
104
+ function_name,
105
+ exc_info=True,
106
+ stack_info=True,
107
+ )
108
+ definition.on_failed(identifier, function_name, e)
109
+ # re-raise error to fail job
110
+ raise
111
+
112
+ @abstractmethod
113
+ def enqueue_perform_complete(
114
+ self,
115
+ identifier: str,
116
+ module_name: str,
117
+ definition_class: str,
118
+ depends_on: Optional[Union[Job, List[Job]]] = None,
119
+ ) -> Job: # pragma: no cover
120
+ pass
121
+
122
+ @staticmethod
123
+ def perform_complete(
124
+ identifier: str,
125
+ module_name: str,
126
+ definition_class: str,
127
+ ):
128
+ definition = load_definition(module_name, definition_class)
129
+ definition.on_completed(identifier)
File without changes
@@ -0,0 +1,86 @@
1
+ from typing import Any, Dict, List, Optional, Union, cast
2
+
3
+ import rq
4
+
5
+ from ..backend import Backend, Job
6
+ from ..types import Description
7
+
8
+
9
+ # pylint: disable=too-many-arguments,too-many-positional-arguments
10
+ class RqBackend(Backend):
11
+ def __init__(self, queue: rq.Queue):
12
+ self.queue = queue
13
+
14
+ def enqueue_perform_start(
15
+ self,
16
+ identifier: str,
17
+ module_name: str,
18
+ definition_class: str,
19
+ depends_on: Optional[Job] = None,
20
+ ) -> Job:
21
+ return self.queue.enqueue(
22
+ self.perform_start,
23
+ identifier=identifier,
24
+ module_name=module_name,
25
+ definition_class=definition_class,
26
+ depends_on=depends_on,
27
+ )
28
+
29
+ def enqueue_perform_task(
30
+ self,
31
+ identifier: str,
32
+ module_name: str,
33
+ definition_class: str,
34
+ function_name: str,
35
+ description: Optional[str],
36
+ kwargs: Dict[str, Any],
37
+ depends_on: Optional[Job] = None,
38
+ ) -> Job:
39
+ # NOTE: `description` and `kwargs` are used by rq
40
+ return self.queue.enqueue(
41
+ self.rq_perform_task,
42
+ identifier=identifier,
43
+ module_name=module_name,
44
+ definition_class=definition_class,
45
+ function_name=function_name,
46
+ task_description=description,
47
+ task_kwargs=kwargs,
48
+ depends_on=depends_on,
49
+ )
50
+
51
+ @classmethod
52
+ def rq_perform_task(
53
+ cls,
54
+ identifier: str,
55
+ module_name: str,
56
+ definition_class: str,
57
+ function_name: str,
58
+ task_description: Description,
59
+ task_kwargs: Dict[str, Any],
60
+ ):
61
+ job = cast(Job, rq.get_current_job())
62
+
63
+ super().perform_task(
64
+ job=job,
65
+ identifier=identifier,
66
+ module_name=module_name,
67
+ definition_class=definition_class,
68
+ function_name=function_name,
69
+ description=task_description,
70
+ kwargs=task_kwargs,
71
+ )
72
+
73
+ def enqueue_perform_complete(
74
+ self,
75
+ identifier: str,
76
+ module_name: str,
77
+ definition_class: str,
78
+ depends_on: Optional[Union[Job, List[Job]]] = None,
79
+ ) -> Job:
80
+ return self.queue.enqueue(
81
+ self.perform_complete,
82
+ identifier=identifier,
83
+ module_name=module_name,
84
+ definition_class=definition_class,
85
+ depends_on=depends_on,
86
+ )
@@ -0,0 +1,151 @@
1
+ from contextlib import contextmanager
2
+ from types import SimpleNamespace
3
+ from typing import Any, Dict, Optional, TYPE_CHECKING, Type, cast
4
+
5
+ from pydantic import TypeAdapter, ValidationError
6
+
7
+ from .steps import Step
8
+ from .types import (
9
+ BuilderIterator,
10
+ Description,
11
+ ForEachMethod,
12
+ Options,
13
+ ProcessDefinitionType,
14
+ TaskMethod,
15
+ TransformMethod,
16
+ Value,
17
+ )
18
+
19
+ if TYPE_CHECKING:
20
+ from .process import Process
21
+
22
+
23
+ class Builder:
24
+ def __init__(
25
+ self,
26
+ process: "Process",
27
+ kwargs: Dict[str, Any],
28
+ options: Optional[Options] = None,
29
+ description: Description = None,
30
+ ):
31
+ self.process = process
32
+ self.description = description
33
+ self.options = self._convert_options(options)
34
+ self.kwargs = kwargs
35
+
36
+ @staticmethod
37
+ def _convert_options(options: Optional[Options] = None) -> SimpleNamespace:
38
+ if options:
39
+ if isinstance(options, SimpleNamespace):
40
+ return options
41
+ if isinstance(options, dict):
42
+ return SimpleNamespace(**options)
43
+ return SimpleNamespace()
44
+
45
+ def expected_arguments(self, **kwargs: Optional[Type]):
46
+ # NOTE: this doesn't check for additional arguments
47
+ for name, expected_type in kwargs.items():
48
+ if name not in self.kwargs:
49
+ raise TypeError(f"Argument '{name}' not found.")
50
+
51
+ if expected_type is not None:
52
+ arg_type = self.kwargs[name]
53
+ type_adapter = TypeAdapter(expected_type)
54
+ try:
55
+ type_adapter.validate_python(arg_type)
56
+ except ValidationError as e:
57
+ raise ValueError(
58
+ f"Argument '{name}' is expected to be of type '{arg_type}'."
59
+ ) from e
60
+
61
+ @contextmanager
62
+ def concurrent(self, description: Description = None) -> BuilderIterator:
63
+ from .process import ConcurrentProcess # pylint: disable=import-outside-toplevel
64
+
65
+ yield from self._build_process(ConcurrentProcess, description)
66
+
67
+ @contextmanager
68
+ def sequential(self, description: Description = None) -> BuilderIterator:
69
+ from .process import SequentialProcess # pylint: disable=import-outside-toplevel
70
+
71
+ yield from self._build_process(SequentialProcess, description)
72
+
73
+ def _build_process(
74
+ self, process_type: Type["Process"], description: Description = None
75
+ ) -> BuilderIterator:
76
+ builder = Builder(
77
+ process=process_type(
78
+ identifier=self.process.identifier,
79
+ definition=self.process.definition,
80
+ ),
81
+ options=self.options,
82
+ description=description or self.description,
83
+ kwargs=self.kwargs,
84
+ )
85
+ yield builder
86
+ self.process.steps.append(builder.process)
87
+
88
+ def task(
89
+ self,
90
+ func: TaskMethod,
91
+ description: Description = None,
92
+ ):
93
+ self.process.steps.append(
94
+ Step(
95
+ func=func,
96
+ description=(
97
+ description or getattr(func, "description", self.description)
98
+ ),
99
+ kwargs=self.kwargs,
100
+ )
101
+ )
102
+
103
+ def sub_process(
104
+ self,
105
+ definition: ProcessDefinitionType,
106
+ description: Description = None,
107
+ ):
108
+ builder = Builder(
109
+ process=definition.create_process(
110
+ identifier=self.process.identifier,
111
+ definition=definition,
112
+ ),
113
+ options=self.options,
114
+ description=description or self.description,
115
+ kwargs=self.kwargs,
116
+ )
117
+ definition().define_process(builder)
118
+ self.process.steps.append(builder.process)
119
+
120
+ def each(
121
+ self,
122
+ func: ForEachMethod,
123
+ description: Description = None,
124
+ ) -> BuilderIterator:
125
+ for kwargs in func(**self.kwargs.copy()):
126
+ kwargs, desc = kwargs if isinstance(kwargs, tuple) else (kwargs, None)
127
+ yield Builder(
128
+ process=self.process,
129
+ options=self.options,
130
+ description=desc or description or self.description,
131
+ kwargs=kwargs,
132
+ )
133
+
134
+ @contextmanager
135
+ def transform(
136
+ self,
137
+ func: TransformMethod,
138
+ description: Description = None,
139
+ ) -> BuilderIterator:
140
+ kwargs = func(**self.kwargs.copy())
141
+ kwargs, desc = kwargs if isinstance(kwargs, tuple) else (kwargs, None)
142
+
143
+ yield Builder(
144
+ process=self.process,
145
+ options=self.options,
146
+ description=desc or description or self.description,
147
+ kwargs=kwargs,
148
+ )
149
+
150
+ def option(self, name: str, default: Optional[Value] = None) -> Value:
151
+ return cast(Value, getattr(self.options, name, default))
@@ -0,0 +1,2 @@
1
+ class Context: # pylint: disable=too-few-public-methods
2
+ pass
@@ -0,0 +1,28 @@
1
+ from typing import Callable, Optional, Union, cast, overload
2
+
3
+ from .types import DecoratedTaskMethod, Description, UndecoratedTaskMethod
4
+
5
+
6
+ @overload
7
+ def task(func: UndecoratedTaskMethod, /) -> DecoratedTaskMethod: ...
8
+
9
+
10
+ @overload
11
+ def task(
12
+ *, description: Description = None
13
+ ) -> Callable[[UndecoratedTaskMethod], DecoratedTaskMethod]: ...
14
+
15
+
16
+ def task(
17
+ func: Optional[UndecoratedTaskMethod] = None,
18
+ /,
19
+ *,
20
+ description: Description = None,
21
+ ) -> Union[Callable[[UndecoratedTaskMethod], DecoratedTaskMethod], DecoratedTaskMethod]:
22
+ def _wrapper(f: UndecoratedTaskMethod) -> DecoratedTaskMethod:
23
+ setattr(f, "description", description)
24
+ return cast(DecoratedTaskMethod, f)
25
+
26
+ if func is not None:
27
+ return _wrapper(func)
28
+ return _wrapper
@@ -0,0 +1,6 @@
1
+ class NonRetryableProcessError(Exception): # pragma: no cover
2
+ pass
3
+
4
+
5
+ class CancelProcessError(Exception): # pragma: no cover
6
+ pass