dataloom-engine 0.6.0__tar.gz → 0.7.0__tar.gz

{dataloom_engine-0.6.0 → dataloom_engine-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataloom-engine
-Version: 0.6.0
+Version: 0.7.0
 Summary: DataLoom: a lightweight and efficient thread orchestration engine for data pipelines.
 Author-email: Dioni Padilha <dionipdl@gmail.com>
 License: MIT
@@ -17,6 +17,7 @@ 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: Typing :: Typed
 Requires-Python: >=3.9
@@ -188,6 +189,51 @@ DataLoom is built around a weaving metaphor:
 - **Processor:** the business logic. Turns raw data into information.
 - **Sink:** the final destination. Where the finished product is deposited (e.g. `JsonFileSink`, `CsvFileSink`, or any destination via `CallbackSink`).
 
+## 🧶 Threading model
+
+Knowing which thread runs each extension point is what makes writing
+safe Processors, Sinks and Hooks straightforward:
+
+| Your code                                      | Runs on                                          |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `Source.__iter__`                              | the thread that called `loom.start()` (producer) |
+| `Processor.process` / `Sink.send`              | the Weaver threads, **concurrently**             |
+| `hooks.on_error` / `hooks.on_batch_processed`  | the Weaver threads, **concurrently**             |
+| `hooks.on_start` / `hooks.on_stop` / `Sink.close` | the thread that called `start()` / `stop()`   |
+
+Practical consequences:
+
+- **Processors and Sinks must be thread-safe** if they touch shared
+  state (the built-in sinks are; `CallbackSink` callables must be).
+- **Hooks run on the hot path**: keep `on_batch_processed` fast and
+  thread-safe.
+- **Shutdown semantics:** `stop()` (or leaving the `with` block) drains
+  the items already queued, then joins the Weavers — pass
+  `stop(timeout=...)` to bound the wait. A pipeline whose source was
+  exhausted ends as `COMPLETED`; an interrupted one (external `stop()`,
+  `Ctrl+C`) ends as `STOPPED`; a source error ends as `FAILED`.
+
+## 📊 Benchmarks
+
+Reproducible, zero-dependency benchmarks live in
+[`benchmarks/throughput.py`](benchmarks/throughput.py):
+
+```bash
+python benchmarks/throughput.py
+```
+
+Reference numbers from a 4-vCPU Linux container (treat them as an order
+of magnitude — run it on your own hardware):
+
+| Scenario                                   | Result           |
+| ------------------------------------------ | ---------------- |
+| I/O-bound, 200 items × 10ms, 8 weavers     | **7.8x** speedup over sequential |
+| No-op processor (pure engine overhead)     | ~51,000 items/s (~20µs per item) |
+
+The rule of thumb the second number gives you: if your per-item work
+costs less than ~20µs, a plain loop beats any orchestration — DataLoom
+pays off when each item does real I/O or meaningful work.
+
 ## 🛠️ Development and Testing
 
 To contribute to the project or run the test suite:

{dataloom_engine-0.6.0 → dataloom_engine-0.7.0}/README.md

@@ -154,6 +154,51 @@ DataLoom is built around a weaving metaphor:
 - **Processor:** the business logic. Turns raw data into information.
 - **Sink:** the final destination. Where the finished product is deposited (e.g. `JsonFileSink`, `CsvFileSink`, or any destination via `CallbackSink`).
 
+## 🧶 Threading model
+
+Knowing which thread runs each extension point is what makes writing
+safe Processors, Sinks and Hooks straightforward:
+
+| Your code                                      | Runs on                                          |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `Source.__iter__`                              | the thread that called `loom.start()` (producer) |
+| `Processor.process` / `Sink.send`              | the Weaver threads, **concurrently**             |
+| `hooks.on_error` / `hooks.on_batch_processed`  | the Weaver threads, **concurrently**             |
+| `hooks.on_start` / `hooks.on_stop` / `Sink.close` | the thread that called `start()` / `stop()`   |
+
+Practical consequences:
+
+- **Processors and Sinks must be thread-safe** if they touch shared
+  state (the built-in sinks are; `CallbackSink` callables must be).
+- **Hooks run on the hot path**: keep `on_batch_processed` fast and
+  thread-safe.
+- **Shutdown semantics:** `stop()` (or leaving the `with` block) drains
+  the items already queued, then joins the Weavers — pass
+  `stop(timeout=...)` to bound the wait. A pipeline whose source was
+  exhausted ends as `COMPLETED`; an interrupted one (external `stop()`,
+  `Ctrl+C`) ends as `STOPPED`; a source error ends as `FAILED`.
+
+## 📊 Benchmarks
+
+Reproducible, zero-dependency benchmarks live in
+[`benchmarks/throughput.py`](benchmarks/throughput.py):
+
+```bash
+python benchmarks/throughput.py
+```
+
+Reference numbers from a 4-vCPU Linux container (treat them as an order
+of magnitude — run it on your own hardware):
+
+| Scenario                                   | Result           |
+| ------------------------------------------ | ---------------- |
+| I/O-bound, 200 items × 10ms, 8 weavers     | **7.8x** speedup over sequential |
+| No-op processor (pure engine overhead)     | ~51,000 items/s (~20µs per item) |
+
+The rule of thumb the second number gives you: if your per-item work
+costs less than ~20µs, a plain loop beats any orchestration — DataLoom
+pays off when each item does real I/O or meaningful work.
+
 ## 🛠️ Development and Testing
 
 To contribute to the project or run the test suite:

{dataloom_engine-0.6.0 → dataloom_engine-0.7.0}/dataloom_engine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataloom-engine
-Version: 0.6.0
+Version: 0.7.0
 Summary: DataLoom: a lightweight and efficient thread orchestration engine for data pipelines.
 Author-email: Dioni Padilha <dionipdl@gmail.com>
 License: MIT
@@ -17,6 +17,7 @@ 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: Typing :: Typed
 Requires-Python: >=3.9
@@ -188,6 +189,51 @@ DataLoom is built around a weaving metaphor:
 - **Processor:** the business logic. Turns raw data into information.
 - **Sink:** the final destination. Where the finished product is deposited (e.g. `JsonFileSink`, `CsvFileSink`, or any destination via `CallbackSink`).
 
+## 🧶 Threading model
+
+Knowing which thread runs each extension point is what makes writing
+safe Processors, Sinks and Hooks straightforward:
+
+| Your code                                      | Runs on                                          |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `Source.__iter__`                              | the thread that called `loom.start()` (producer) |
+| `Processor.process` / `Sink.send`              | the Weaver threads, **concurrently**             |
+| `hooks.on_error` / `hooks.on_batch_processed`  | the Weaver threads, **concurrently**             |
+| `hooks.on_start` / `hooks.on_stop` / `Sink.close` | the thread that called `start()` / `stop()`   |
+
+Practical consequences:
+
+- **Processors and Sinks must be thread-safe** if they touch shared
+  state (the built-in sinks are; `CallbackSink` callables must be).
+- **Hooks run on the hot path**: keep `on_batch_processed` fast and
+  thread-safe.
+- **Shutdown semantics:** `stop()` (or leaving the `with` block) drains
+  the items already queued, then joins the Weavers — pass
+  `stop(timeout=...)` to bound the wait. A pipeline whose source was
+  exhausted ends as `COMPLETED`; an interrupted one (external `stop()`,
+  `Ctrl+C`) ends as `STOPPED`; a source error ends as `FAILED`.
+
+## 📊 Benchmarks
+
+Reproducible, zero-dependency benchmarks live in
+[`benchmarks/throughput.py`](benchmarks/throughput.py):
+
+```bash
+python benchmarks/throughput.py
+```
+
+Reference numbers from a 4-vCPU Linux container (treat them as an order
+of magnitude — run it on your own hardware):
+
+| Scenario                                   | Result           |
+| ------------------------------------------ | ---------------- |
+| I/O-bound, 200 items × 10ms, 8 weavers     | **7.8x** speedup over sequential |
+| No-op processor (pure engine overhead)     | ~51,000 items/s (~20µs per item) |
+
+The rule of thumb the second number gives you: if your per-item work
+costs less than ~20µs, a plain loop beats any orchestration — DataLoom
+pays off when each item does real I/O or meaningful work.
+
 ## 🛠️ Development and Testing
 
 To contribute to the project or run the test suite:

{dataloom_engine-0.6.0 → dataloom_engine-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dataloom-engine"
-version = "0.6.0"
+version = "0.7.0"
 description = "DataLoom: a lightweight and efficient thread orchestration engine for data pipelines."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -23,6 +23,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
 ]
@@ -68,9 +69,9 @@ select = [
     "B",  # flake8-bugbear
 ]
 
-# Sem python_version fixo: versões novas do mypy não aceitam mais alvo 3.9,
-# e os stubs do numpy exigem alvo >= 3.12. A compatibilidade com 3.9 é
-# garantida pela matriz de testes do CI, que executa nessa versão.
+# No pinned python_version: recent mypy releases no longer accept a 3.9
+# target, and the numpy stubs require >= 3.12. Compatibility with 3.9 is
+# guaranteed by the CI test matrix, which runs on that version.
 [tool.mypy]
 files = ["dataloom_engine"]
 check_untyped_defs = true
@@ -78,7 +79,7 @@ warn_redundant_casts = true
 no_implicit_optional = true
 
 [[tool.mypy.overrides]]
-# numpy é usado apenas nas implementações de demonstração; ignorar stubs
-# ausentes mantém o check estável em ambientes sem os type stubs resolvidos
+# numpy is only used by the demo implementations; ignoring missing stubs
+# keeps the check stable in environments without resolved type stubs
 module = "numpy.*"
 ignore_missing_imports = true