tinyorch 0.0.1__tar.gz โ†’ 0.1.1__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.
tinyorch-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Murilegus
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,148 @@
1
+ Metadata-Version: 2.4
2
+ Name: tinyorch
3
+ Version: 0.1.1
4
+ Summary: A tiny, zero-dependency orchestrator for single-node, item-level pipelines.
5
+ Author: Murilegus
6
+ Author-email: Murilegus <murilegus@outlook.com>
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Typing :: Typed
14
+ Requires-Python: >=3.12
15
+ Project-URL: Homepage, https://github.com/murilegus/tinyorch
16
+ Project-URL: Repository, https://github.com/murilegus/tinyorch
17
+ Project-URL: Issues, https://github.com/murilegus/tinyorch/issues
18
+ Description-Content-Type: text/markdown
19
+
20
+ # ๐Ÿ”€ tinyorch
21
+
22
+ [![ci](https://github.com/murilegus/tinyorch/actions/workflows/ci.yml/badge.svg)](https://github.com/murilegus/tinyorch/actions/workflows/ci.yml)
23
+ [![PyPI](https://img.shields.io/pypi/v/tinyorch)](https://pypi.org/project/tinyorch/)
24
+ [![Python](https://img.shields.io/pypi/pyversions/tinyorch)](https://pypi.org/project/tinyorch/)
25
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
26
+
27
+ A tiny, zero-dependency orchestrator for single-node, item-level pipelines.
28
+
29
+ ๐Ÿšง **Status**: alpha โ€” phase 1 released (0.1), phase 2 in progress. See [Roadmap](#-roadmap).
30
+
31
+ ## ๐Ÿš€ Quickstart
32
+
33
+ ```bash
34
+ pip install tinyorch
35
+ ```
36
+
37
+ ```python
38
+ import asyncio
39
+ from tinyorch import task, flow, current_run
40
+
41
+
42
+ @task
43
+ async def fetch(url: str) -> str:
44
+ await asyncio.sleep(0.1) # pretend to hit the network
45
+ return f"<html>{url}</html>"
46
+
47
+
48
+ @task
49
+ def parse(html: str) -> list[str]:
50
+ return html.split()
51
+
52
+
53
+ @flow
54
+ async def crawl(urls: list[str]) -> int:
55
+ for url in urls:
56
+ parse(await fetch(url))
57
+ run = current_run()
58
+ return len(run.calls) if run else 0
59
+
60
+
61
+ print(asyncio.run(crawl(["a", "b", "c"]))) # 6 task calls recorded
62
+ ```
63
+
64
+ A `@task` is a plain callable with metadata: outside a flow it just runs.
65
+ Inside a `@flow`, every call is recorded on the current `RunContext`
66
+ (`current_run()`), which also tracks the flow's own timing and failure.
67
+ Sync and async functions both work; the wrapped signature is preserved for
68
+ type checkers.
69
+
70
+
71
+ ## ๐Ÿค” Why tinyorch?
72
+
73
+ tinyorch is for the job that is **too small for Prefect, too finite for Flink,
74
+ and too painful as a bare script**: a few thousand to a few million items
75
+ (URLs, documents, records) flowing through I/O-heavy stages on one machine,
76
+ where any stage can fail halfway.
77
+
78
+ Three families of tools already exist for pipelines. Each is right for its
79
+ sweet spot and awkward outside it:
80
+
81
+ | | Workflow orchestrators<br>Airflow ยท Prefect ยท Dagster | Stream processors<br>Flink ยท Bytewax ยท Faust | Bare script<br>`asyncio.gather` + `tenacity` | **tinyorch** |
82
+ |---|---|---|---|---|
83
+ | Input | bounded, per task | **unbounded**, per event | bounded | bounded, per item |
84
+ | Execution | one stage finishes before the next starts | continuous | ad hoc | pipelined, bounded buffers |
85
+ | Resume after crash | per task / per run | cluster checkpoints | hand-rolled or none | per item |
86
+ | Shared resources (browser, LLM client) | per process, awkward | n/a | manual | first-class |
87
+ | Infra | server + database | cluster | none | none |
88
+ | Sweet spot | multi-team, multi-machine DAGs | 24/7 event streams | one-off | one node, 10ยณโ€“10โถ items, crash-prone I/O |
89
+
90
+ The architectural difference tinyorch is built around: in a stage-at-a-time
91
+ orchestrator, data crossing a task boundary is materialized (in RAM or an
92
+ object store) before the next stage starts. tinyorch instead pipelines items
93
+ through stages with bounded buffers and checkpoints each item, so a rerun only
94
+ does what is left and memory stays flat regardless of input size.
95
+
96
+ ![Stage-at-a-time orchestrators vs tinyorch pipelining](https://raw.githubusercontent.com/murilegus/tinyorch/main/docs/assets/stage-vs-pipelined.svg)
97
+
98
+ **tinyorch is not a stream processor.** It takes a *bounded* input and
99
+ executes it with streaming semantics. There are no windows, no event time, no
100
+ unbounded sources, no distributed state. If you need those, use Flink.
101
+
102
+ **It is not a replacement for Prefect or Airflow either.** When the pipeline
103
+ outgrows one machine or one team, those are the tools to move to; tinyorch
104
+ aims to make that boundary obvious rather than blurry.
105
+
106
+
107
+ ## ๐Ÿ—๏ธ Architecture
108
+
109
+ The core is stdlib-only and defines Protocols; everything that touches the
110
+ outside world (state stores, browsers, LLM clients, CLI) is an adapter shipped
111
+ as an optional extra.
112
+
113
+ ![tinyorch architecture](https://raw.githubusercontent.com/murilegus/tinyorch/main/docs/assets/architecture.svg)
114
+
115
+
116
+ ## ๐Ÿšซ Non-goals
117
+
118
+ - **Multi-node scheduling** or a long-running scheduler service โ€” one process,
119
+ one machine, started by cron, a Cloud Run Job or your own code
120
+ - **Unbounded / event-time stream processing** โ€” input is finite; no windows,
121
+ watermarks or distributed state
122
+ - **A full web UI** with authentication and multi-tenancy โ€” a local, read-only
123
+ run viewer is planned as an optional extra
124
+ - **Time-based backfills** in the Airflow sense โ€” runs are keyed by input, not
125
+ by schedule interval
126
+
127
+
128
+ ## ๐Ÿงญ Roadmap
129
+
130
+ | Phase | Scope | Status |
131
+ |---|---|---|
132
+ | 1 | `@task` / `@flow`, run tracking, typed public API | โœ… 0.1 |
133
+ | 2 | Pipelining: streaming tasks, bounded buffers, concurrent execution | ๐Ÿšง next |
134
+ | 3 | Per-item checkpoints, resumable runs, pluggable state store | planned |
135
+ | 4 | Resources with lifecycle and injection; process workers for CPU-bound tasks | planned |
136
+ | 5 | Dogfooding on a real crawl + LLM pipeline; CLI | planned |
137
+
138
+ Progress is tracked in [GitHub milestones](https://github.com/murilegus/tinyorch/milestones).
139
+
140
+
141
+ ## ๐Ÿ“„ Documentation
142
+
143
+ - [`docs/design/`](docs/design/) โ€” design decisions are recorded as ADRs.
144
+
145
+
146
+ ## ๐ŸŽซ License
147
+
148
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -0,0 +1,129 @@
1
+ # ๐Ÿ”€ tinyorch
2
+
3
+ [![ci](https://github.com/murilegus/tinyorch/actions/workflows/ci.yml/badge.svg)](https://github.com/murilegus/tinyorch/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/tinyorch)](https://pypi.org/project/tinyorch/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/tinyorch)](https://pypi.org/project/tinyorch/)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7
+
8
+ A tiny, zero-dependency orchestrator for single-node, item-level pipelines.
9
+
10
+ ๐Ÿšง **Status**: alpha โ€” phase 1 released (0.1), phase 2 in progress. See [Roadmap](#-roadmap).
11
+
12
+ ## ๐Ÿš€ Quickstart
13
+
14
+ ```bash
15
+ pip install tinyorch
16
+ ```
17
+
18
+ ```python
19
+ import asyncio
20
+ from tinyorch import task, flow, current_run
21
+
22
+
23
+ @task
24
+ async def fetch(url: str) -> str:
25
+ await asyncio.sleep(0.1) # pretend to hit the network
26
+ return f"<html>{url}</html>"
27
+
28
+
29
+ @task
30
+ def parse(html: str) -> list[str]:
31
+ return html.split()
32
+
33
+
34
+ @flow
35
+ async def crawl(urls: list[str]) -> int:
36
+ for url in urls:
37
+ parse(await fetch(url))
38
+ run = current_run()
39
+ return len(run.calls) if run else 0
40
+
41
+
42
+ print(asyncio.run(crawl(["a", "b", "c"]))) # 6 task calls recorded
43
+ ```
44
+
45
+ A `@task` is a plain callable with metadata: outside a flow it just runs.
46
+ Inside a `@flow`, every call is recorded on the current `RunContext`
47
+ (`current_run()`), which also tracks the flow's own timing and failure.
48
+ Sync and async functions both work; the wrapped signature is preserved for
49
+ type checkers.
50
+
51
+
52
+ ## ๐Ÿค” Why tinyorch?
53
+
54
+ tinyorch is for the job that is **too small for Prefect, too finite for Flink,
55
+ and too painful as a bare script**: a few thousand to a few million items
56
+ (URLs, documents, records) flowing through I/O-heavy stages on one machine,
57
+ where any stage can fail halfway.
58
+
59
+ Three families of tools already exist for pipelines. Each is right for its
60
+ sweet spot and awkward outside it:
61
+
62
+ | | Workflow orchestrators<br>Airflow ยท Prefect ยท Dagster | Stream processors<br>Flink ยท Bytewax ยท Faust | Bare script<br>`asyncio.gather` + `tenacity` | **tinyorch** |
63
+ |---|---|---|---|---|
64
+ | Input | bounded, per task | **unbounded**, per event | bounded | bounded, per item |
65
+ | Execution | one stage finishes before the next starts | continuous | ad hoc | pipelined, bounded buffers |
66
+ | Resume after crash | per task / per run | cluster checkpoints | hand-rolled or none | per item |
67
+ | Shared resources (browser, LLM client) | per process, awkward | n/a | manual | first-class |
68
+ | Infra | server + database | cluster | none | none |
69
+ | Sweet spot | multi-team, multi-machine DAGs | 24/7 event streams | one-off | one node, 10ยณโ€“10โถ items, crash-prone I/O |
70
+
71
+ The architectural difference tinyorch is built around: in a stage-at-a-time
72
+ orchestrator, data crossing a task boundary is materialized (in RAM or an
73
+ object store) before the next stage starts. tinyorch instead pipelines items
74
+ through stages with bounded buffers and checkpoints each item, so a rerun only
75
+ does what is left and memory stays flat regardless of input size.
76
+
77
+ ![Stage-at-a-time orchestrators vs tinyorch pipelining](https://raw.githubusercontent.com/murilegus/tinyorch/main/docs/assets/stage-vs-pipelined.svg)
78
+
79
+ **tinyorch is not a stream processor.** It takes a *bounded* input and
80
+ executes it with streaming semantics. There are no windows, no event time, no
81
+ unbounded sources, no distributed state. If you need those, use Flink.
82
+
83
+ **It is not a replacement for Prefect or Airflow either.** When the pipeline
84
+ outgrows one machine or one team, those are the tools to move to; tinyorch
85
+ aims to make that boundary obvious rather than blurry.
86
+
87
+
88
+ ## ๐Ÿ—๏ธ Architecture
89
+
90
+ The core is stdlib-only and defines Protocols; everything that touches the
91
+ outside world (state stores, browsers, LLM clients, CLI) is an adapter shipped
92
+ as an optional extra.
93
+
94
+ ![tinyorch architecture](https://raw.githubusercontent.com/murilegus/tinyorch/main/docs/assets/architecture.svg)
95
+
96
+
97
+ ## ๐Ÿšซ Non-goals
98
+
99
+ - **Multi-node scheduling** or a long-running scheduler service โ€” one process,
100
+ one machine, started by cron, a Cloud Run Job or your own code
101
+ - **Unbounded / event-time stream processing** โ€” input is finite; no windows,
102
+ watermarks or distributed state
103
+ - **A full web UI** with authentication and multi-tenancy โ€” a local, read-only
104
+ run viewer is planned as an optional extra
105
+ - **Time-based backfills** in the Airflow sense โ€” runs are keyed by input, not
106
+ by schedule interval
107
+
108
+
109
+ ## ๐Ÿงญ Roadmap
110
+
111
+ | Phase | Scope | Status |
112
+ |---|---|---|
113
+ | 1 | `@task` / `@flow`, run tracking, typed public API | โœ… 0.1 |
114
+ | 2 | Pipelining: streaming tasks, bounded buffers, concurrent execution | ๐Ÿšง next |
115
+ | 3 | Per-item checkpoints, resumable runs, pluggable state store | planned |
116
+ | 4 | Resources with lifecycle and injection; process workers for CPU-bound tasks | planned |
117
+ | 5 | Dogfooding on a real crawl + LLM pipeline; CLI | planned |
118
+
119
+ Progress is tracked in [GitHub milestones](https://github.com/murilegus/tinyorch/milestones).
120
+
121
+
122
+ ## ๐Ÿ“„ Documentation
123
+
124
+ - [`docs/design/`](docs/design/) โ€” design decisions are recorded as ADRs.
125
+
126
+
127
+ ## ๐ŸŽซ License
128
+
129
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -0,0 +1,96 @@
1
+ [project]
2
+ name = "tinyorch"
3
+ version = "0.1.1"
4
+ description = "A tiny, zero-dependency orchestrator for single-node, item-level pipelines."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.12"
9
+ classifiers = [
10
+ "Development Status :: 3 - Alpha",
11
+ "Programming Language :: Python :: 3",
12
+ "Programming Language :: Python :: 3.12",
13
+ "Programming Language :: Python :: 3.13",
14
+ "Typing :: Typed",
15
+ ]
16
+ dependencies = []
17
+
18
+ [[project.authors]]
19
+ name = "Murilegus"
20
+ email = "murilegus@outlook.com"
21
+
22
+ [project.urls]
23
+ Homepage = "https://github.com/murilegus/tinyorch"
24
+ Repository = "https://github.com/murilegus/tinyorch"
25
+ Issues = "https://github.com/murilegus/tinyorch/issues"
26
+
27
+ [dependency-groups]
28
+ dev = [
29
+ "basedpyright>=1.40.2",
30
+ "pytest>=9.1.1",
31
+ "pytest-asyncio>=1.4.0",
32
+ "pytest-cov>=7.1.0",
33
+ "ruff>=0.17.2",
34
+ ]
35
+
36
+ [build-system]
37
+ requires = ["uv_build>=0.13.1,<0.14.0"]
38
+ build-backend = "uv_build"
39
+
40
+ [tool.basedpyright]
41
+ include = [
42
+ "src",
43
+ "tests",
44
+ ]
45
+ typeCheckingMode = "strict"
46
+ failOnWarnings = true
47
+
48
+ [[tool.basedpyright.executionEnvironments]]
49
+ root = "tests"
50
+
51
+ [tool.pytest.ini_options]
52
+ asyncio_mode = "auto"
53
+ testpaths = ["tests"]
54
+ addopts = "--cov=tinyorch --cov-report=term-missing --cov-fail-under=95"
55
+
56
+ [tool.coverage.run]
57
+ branch = true
58
+ source = ["tinyorch"]
59
+
60
+ [tool.coverage.report]
61
+ exclude_also = [
62
+ "if TYPE_CHECKING:",
63
+ "@overload",
64
+ '\.\.\.',
65
+ ]
66
+
67
+ [tool.ruff]
68
+ target-version = "py312"
69
+ line-length = 100
70
+ src = [
71
+ "src",
72
+ "tests",
73
+ ]
74
+
75
+ [tool.ruff.lint]
76
+ select = ["ALL"]
77
+ ignore = [
78
+ "D",
79
+ "COM812",
80
+ "ISC001",
81
+ ]
82
+
83
+ [tool.ruff.lint.flake8-copyright]
84
+ notice-rgx = '(?i)SPDX-FileCopyrightText:\s+ยฉ?\s*\d{4}'
85
+
86
+ [tool.ruff.lint.per-file-ignores]
87
+ "tests/**" = [
88
+ "S101",
89
+ "ANN",
90
+ "PLR2004",
91
+ "EM",
92
+ "TRY003",
93
+ ]
94
+
95
+ [tool.ruff.lint.isort]
96
+ known-first-party = ["tinyorch"]
@@ -0,0 +1,81 @@
1
+ [project]
2
+ name = "tinyorch"
3
+ version = "0.1.1"
4
+ description = "A tiny, zero-dependency orchestrator for single-node, item-level pipelines."
5
+ readme = "README.md"
6
+ authors = [{ name = "Murilegus", email = "murilegus@outlook.com" }]
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ requires-python = ">=3.12"
10
+ classifiers = [
11
+ "Development Status :: 3 - Alpha",
12
+ "Programming Language :: Python :: 3",
13
+ "Programming Language :: Python :: 3.12",
14
+ "Programming Language :: Python :: 3.13",
15
+ "Typing :: Typed",
16
+ ]
17
+ dependencies = []
18
+
19
+ [dependency-groups]
20
+ dev = [
21
+ "basedpyright>=1.40.2",
22
+ "pytest>=9.1.1",
23
+ "pytest-asyncio>=1.4.0",
24
+ "pytest-cov>=7.1.0",
25
+ "ruff>=0.17.2",
26
+ ]
27
+
28
+ [project.urls]
29
+ Homepage = "https://github.com/murilegus/tinyorch"
30
+ Repository = "https://github.com/murilegus/tinyorch"
31
+ Issues = "https://github.com/murilegus/tinyorch/issues"
32
+
33
+ [build-system]
34
+ requires = ["uv_build>=0.13.1,<0.14.0"]
35
+ build-backend = "uv_build"
36
+
37
+ [tool.basedpyright]
38
+ include = ["src", "tests"]
39
+ typeCheckingMode = "strict"
40
+ failOnWarnings = true
41
+
42
+ [[tool.basedpyright.executionEnvironments]]
43
+ root = "tests"
44
+
45
+ [tool.pytest.ini_options]
46
+ asyncio_mode = "auto"
47
+ testpaths = ["tests"]
48
+ addopts = "--cov=tinyorch --cov-report=term-missing --cov-fail-under=95"
49
+
50
+ [tool.coverage.run]
51
+ branch = true
52
+ source = ["tinyorch"]
53
+
54
+ [tool.coverage.report]
55
+ exclude_also = [
56
+ "if TYPE_CHECKING:",
57
+ "@overload",
58
+ "\\.\\.\\.",
59
+ ]
60
+
61
+ [tool.ruff]
62
+ target-version = "py312"
63
+ line-length = 100
64
+ src = ["src", "tests"]
65
+
66
+ [tool.ruff.lint]
67
+ select = ["ALL"]
68
+ ignore = [
69
+ "D",
70
+ "COM812",
71
+ "ISC001",
72
+ ]
73
+
74
+ [tool.ruff.lint.flake8-copyright]
75
+ notice-rgx = "(?i)SPDX-FileCopyrightText:\\s+ยฉ?\\s*\\d{4}"
76
+
77
+ [tool.ruff.lint.per-file-ignores]
78
+ "tests/**" = ["S101", "ANN", "PLR2004", "EM", "TRY003"]
79
+
80
+ [tool.ruff.lint.isort]
81
+ known-first-party = ["tinyorch"]
@@ -0,0 +1,21 @@
1
+ # SPDX-FileCopyrightText: ยฉ 2026 Murilegus <murilegus@outlook.com>
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ from importlib.metadata import version
5
+
6
+ from tinyorch._api import flow, task
7
+ from tinyorch._context import RunContext, TaskCall, current_run
8
+ from tinyorch._flow import Flow
9
+ from tinyorch._task import Task
10
+
11
+ __version__ = version("tinyorch")
12
+ __all__ = [
13
+ "Flow",
14
+ "RunContext",
15
+ "Task",
16
+ "TaskCall",
17
+ "__version__",
18
+ "current_run",
19
+ "flow",
20
+ "task",
21
+ ]
@@ -0,0 +1,40 @@
1
+ # SPDX-FileCopyrightText: ยฉ 2026 Murilegus <murilegus@outlook.com>
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ from __future__ import annotations
5
+
6
+ from typing import TYPE_CHECKING, overload
7
+
8
+ from tinyorch._flow import Flow
9
+ from tinyorch._task import Task
10
+
11
+ if TYPE_CHECKING:
12
+ from collections.abc import Callable
13
+
14
+
15
+ @overload
16
+ def task[**P, R](fn: Callable[P, R], /) -> Task[P, R]: ...
17
+ @overload
18
+ def task[**P, R](*, name: str | None = None) -> Callable[[Callable[P, R]], Task[P, R]]: ...
19
+ def task(fn: Callable[..., object] | None = None, /, *, name: str | None = None) -> object:
20
+ if fn is not None:
21
+ return Task(fn, name=name)
22
+
23
+ def decorator[**P, R](f: Callable[P, R]) -> Task[P, R]:
24
+ return Task(f, name=name)
25
+
26
+ return decorator
27
+
28
+
29
+ @overload
30
+ def flow[**P, R](fn: Callable[P, R], /) -> Flow[P, R]: ...
31
+ @overload
32
+ def flow[**P, R](*, name: str | None = None) -> Callable[[Callable[P, R]], Flow[P, R]]: ...
33
+ def flow(fn: Callable[..., object] | None = None, /, *, name: str | None = None) -> object:
34
+ if fn is not None:
35
+ return Flow(fn, name=name)
36
+
37
+ def decorator[**P, R](f: Callable[P, R]) -> Flow[P, R]:
38
+ return Flow(f, name=name)
39
+
40
+ return decorator
@@ -0,0 +1,54 @@
1
+ # SPDX-FileCopyrightText: ยฉ 2026 Murilegus <murilegus@outlook.com>
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ from __future__ import annotations
5
+
6
+ import time
7
+ import uuid
8
+ from contextlib import contextmanager
9
+ from contextvars import ContextVar
10
+ from dataclasses import dataclass, field
11
+ from typing import TYPE_CHECKING
12
+
13
+ if TYPE_CHECKING:
14
+ from collections.abc import Generator
15
+
16
+
17
+ @dataclass(slots=True)
18
+ class RunContext:
19
+ flow_name: str
20
+ run_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
21
+ started_at: float = field(default_factory=time.monotonic)
22
+ calls: list[TaskCall] = field(default_factory=list)
23
+ ended_at: float | None = None
24
+ error: BaseException | None = None
25
+ parent: RunContext | None = None
26
+
27
+
28
+ @dataclass(slots=True)
29
+ class TaskCall:
30
+ task_name: str
31
+ started_at: float = field(default_factory=time.monotonic)
32
+ ended_at: float | None = None
33
+ error: BaseException | None = None
34
+
35
+
36
+ _current: ContextVar[RunContext | None] = ContextVar("tinyorch_run", default=None)
37
+
38
+
39
+ def current_run() -> RunContext | None:
40
+ return _current.get()
41
+
42
+
43
+ @contextmanager
44
+ def enter_run(flow_name: str) -> Generator[RunContext, None, None]:
45
+ ctx = RunContext(flow_name=flow_name, parent=_current.get())
46
+ token = _current.set(ctx)
47
+ try:
48
+ yield ctx
49
+ except BaseException as exc:
50
+ ctx.error = exc
51
+ raise
52
+ finally:
53
+ ctx.ended_at = time.monotonic()
54
+ _current.reset(token)
@@ -0,0 +1,55 @@
1
+ # SPDX-FileCopyrightText: ยฉ 2026 Murilegus <murilegus@outlook.com>
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ from __future__ import annotations
5
+
6
+ import inspect
7
+ from typing import TYPE_CHECKING, cast, override
8
+
9
+ from tinyorch._context import enter_run
10
+
11
+ if TYPE_CHECKING:
12
+ from collections.abc import Awaitable, Callable
13
+
14
+
15
+ class Flow[**P, R]:
16
+ def __init__(self, fn: Callable[P, R], *, name: str | None = None) -> None:
17
+ self.fn: Callable[P, R] = fn
18
+ self.name: str = name or fn.__name__
19
+ self.is_async: bool = inspect.iscoroutinefunction(fn)
20
+ self.__name__: str = fn.__name__
21
+ self.__qualname__: str = fn.__qualname__
22
+ self.__module__: str = fn.__module__
23
+ self.__doc__: str | None = fn.__doc__
24
+ self.__wrapped__: Callable[P, R] = fn
25
+
26
+ def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
27
+ if self.is_async:
28
+ return cast("R", self._run_async(*args, **kwargs))
29
+ return self._run_sync(*args, **kwargs)
30
+
31
+ def _run_sync(self, *args: P.args, **kwargs: P.kwargs) -> R:
32
+ with enter_run(self.name):
33
+ return self.fn(*args, **kwargs)
34
+
35
+ async def _run_async(self, *args: P.args, **kwargs: P.kwargs) -> object:
36
+ with enter_run(self.name):
37
+ return await self._await(*args, **kwargs)
38
+
39
+ # see #2
40
+ def _await(self, *args: P.args, **kwargs: P.kwargs) -> Awaitable[object]:
41
+ return cast("Awaitable[object]", self.fn(*args, **kwargs))
42
+
43
+ @property
44
+ def _key(self) -> tuple[str, str]:
45
+ return (self.fn.__module__, self.fn.__qualname__)
46
+
47
+ @override
48
+ def __eq__(self, other: object) -> bool:
49
+ if not isinstance(other, Flow):
50
+ return NotImplemented
51
+ return self._key == other._key
52
+
53
+ @override
54
+ def __hash__(self) -> int:
55
+ return hash(self._key)
@@ -0,0 +1,81 @@
1
+ # SPDX-FileCopyrightText: ยฉ 2026 Murilegus <murilegus@outlook.com>
2
+ # SPDX-License-Identifier: MIT
3
+
4
+ from __future__ import annotations
5
+
6
+ import inspect
7
+ import time
8
+ from typing import TYPE_CHECKING, cast, override
9
+
10
+ from tinyorch._context import RunContext, TaskCall, current_run
11
+
12
+ if TYPE_CHECKING:
13
+ from collections.abc import Awaitable, Callable
14
+
15
+
16
+ class Task[**P, R]:
17
+ def __init__(self, fn: Callable[P, R], *, name: str | None = None) -> None:
18
+ self.fn: Callable[P, R] = fn
19
+ self.name: str = name or fn.__name__
20
+ self.is_async: bool = inspect.iscoroutinefunction(fn)
21
+ self.__name__: str = fn.__name__
22
+ self.__qualname__: str = fn.__qualname__
23
+ self.__module__: str = fn.__module__
24
+ self.__doc__: str | None = fn.__doc__
25
+ self.__wrapped__: Callable[P, R] = fn
26
+
27
+ def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
28
+ if self.is_async:
29
+ return cast("R", self._run_async(*args, **kwargs))
30
+ return self._run_sync(*args, **kwargs)
31
+
32
+ def _run_sync(self, *args: P.args, **kwargs: P.kwargs) -> R:
33
+ ctx = current_run()
34
+ if ctx is None:
35
+ return self.fn(*args, **kwargs)
36
+
37
+ call = self._record(ctx)
38
+ try:
39
+ return self.fn(*args, **kwargs)
40
+ except BaseException as exc:
41
+ call.error = exc
42
+ raise
43
+ finally:
44
+ call.ended_at = time.monotonic()
45
+
46
+ async def _run_async(self, *args: P.args, **kwargs: P.kwargs) -> object:
47
+ ctx = current_run()
48
+ if ctx is None:
49
+ return await self._await(*args, **kwargs)
50
+
51
+ call = self._record(ctx)
52
+ try:
53
+ return await self._await(*args, **kwargs)
54
+ except BaseException as exc:
55
+ call.error = exc
56
+ raise
57
+ finally:
58
+ call.ended_at = time.monotonic()
59
+
60
+ def _record(self, ctx: RunContext) -> TaskCall:
61
+ call = TaskCall(task_name=self.name)
62
+ ctx.calls.append(call)
63
+ return call
64
+
65
+ # see #2
66
+ def _await(self, *args: P.args, **kwargs: P.kwargs) -> Awaitable[object]:
67
+ return cast("Awaitable[object]", self.fn(*args, **kwargs))
68
+
69
+ @property
70
+ def _key(self) -> tuple[str, str]:
71
+ return (self.fn.__module__, self.fn.__qualname__)
72
+
73
+ @override
74
+ def __eq__(self, other: object) -> bool:
75
+ if not isinstance(other, Task):
76
+ return NotImplemented
77
+ return self._key == other._key
78
+
79
+ @override
80
+ def __hash__(self) -> int:
81
+ return hash(self._key)
tinyorch-0.0.1/PKG-INFO DELETED
@@ -1,24 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: tinyorch
3
- Version: 0.0.1
4
- Summary: A tiny, zero-dependency orchestrator for single-node streaming pipelines.
5
- Author: Murilegus
6
- Author-email: Murilegus <murilegus@outlook.com>
7
- License-Expression: MIT
8
- Classifier: Development Status :: 1 - Planning
9
- Requires-Python: >=3.12
10
- Project-URL: Homepage, https://github.com/murilegus/tinyorch
11
- Project-URL: Repository, https://github.com/murilegus/tinyorch
12
- Project-URL: Issues, https://github.com/murilegus/tinyorch/issues
13
- Description-Content-Type: text/markdown
14
-
15
- # ๐Ÿ”€ tinyorch
16
-
17
- A tiny, zero-dependency orchestrator for single-node streaming pipelines.
18
-
19
- ๐Ÿšง **Status**: Placeholder release to reserve the package name on PyPI.
20
-
21
-
22
- ## ๐Ÿ“„ License
23
-
24
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
tinyorch-0.0.1/README.md DELETED
@@ -1,10 +0,0 @@
1
- # ๐Ÿ”€ tinyorch
2
-
3
- A tiny, zero-dependency orchestrator for single-node streaming pipelines.
4
-
5
- ๐Ÿšง **Status**: Placeholder release to reserve the package name on PyPI.
6
-
7
-
8
- ## ๐Ÿ“„ License
9
-
10
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -1,22 +0,0 @@
1
- [project]
2
- name = "tinyorch"
3
- version = "0.0.1"
4
- description = "A tiny, zero-dependency orchestrator for single-node streaming pipelines."
5
- readme = "README.md"
6
- license = "MIT"
7
- requires-python = ">=3.12"
8
- classifiers = ["Development Status :: 1 - Planning"]
9
- dependencies = []
10
-
11
- [[project.authors]]
12
- name = "Murilegus"
13
- email = "murilegus@outlook.com"
14
-
15
- [project.urls]
16
- Homepage = "https://github.com/murilegus/tinyorch"
17
- Repository = "https://github.com/murilegus/tinyorch"
18
- Issues = "https://github.com/murilegus/tinyorch/issues"
19
-
20
- [build-system]
21
- requires = ["uv_build>=0.13.1,<0.14.0"]
22
- build-backend = "uv_build"
@@ -1,19 +0,0 @@
1
- [project]
2
- name = "tinyorch"
3
- version = "0.0.1"
4
- description = "A tiny, zero-dependency orchestrator for single-node streaming pipelines."
5
- readme = "README.md"
6
- authors = [{ name = "Murilegus", email = "murilegus@outlook.com" }]
7
- license = "MIT"
8
- requires-python = ">=3.12"
9
- classifiers = ["Development Status :: 1 - Planning"]
10
- dependencies = []
11
-
12
- [project.urls]
13
- Homepage = "https://github.com/murilegus/tinyorch"
14
- Repository = "https://github.com/murilegus/tinyorch"
15
- Issues = "https://github.com/murilegus/tinyorch/issues"
16
-
17
- [build-system]
18
- requires = ["uv_build>=0.13.1,<0.14.0"]
19
- build-backend = "uv_build"
@@ -1,4 +0,0 @@
1
-
2
- from importlib.metadata import version
3
-
4
- __version__ = version("tinyorch")