combycode-dpe 2.0.3__tar.gz → 2.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 (23) hide show
  1. combycode_dpe-2.1.0/PKG-INFO +128 -0
  2. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/README.md +4 -2
  3. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/pyproject.toml +11 -2
  4. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/src/dpe/_paths.py +22 -2
  5. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/tests/test_paths.py +36 -0
  6. combycode_dpe-2.0.3/PKG-INFO +0 -11
  7. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/.gitignore +0 -0
  8. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/src/dpe/__init__.py +0 -0
  9. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/src/dpe/_accumulators.py +0 -0
  10. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/src/dpe/_cache.py +0 -0
  11. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/src/dpe/_context.py +0 -0
  12. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/src/dpe/_envelope.py +0 -0
  13. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/src/dpe/_runtime.py +0 -0
  14. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/template/meta.json +0 -0
  15. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/template/pyproject.toml +0 -0
  16. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/template/spec.yaml +0 -0
  17. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/template/src/__PKG__/__init__.py +0 -0
  18. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/template/src/__PKG__/main.py +0 -0
  19. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/template/tests/test_basic.py +0 -0
  20. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/tests/test_accumulators.py +0 -0
  21. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/tests/test_cache.py +0 -0
  22. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/tests/test_integration.py +0 -0
  23. {combycode_dpe-2.0.3 → combycode_dpe-2.1.0}/tests/test_stderr_events_conformance.py +0 -0
@@ -0,0 +1,128 @@
1
+ Metadata-Version: 2.5
2
+ Name: combycode-dpe
3
+ Version: 2.1.0
4
+ Summary: DPE framework for building streaming pipeline tools in Python
5
+ Project-URL: Homepage, https://github.com/combycode/dpe
6
+ Project-URL: Repository, https://github.com/combycode/dpe
7
+ Project-URL: Documentation, https://github.com/combycode/dpe/blob/main/frameworks/python/README.md
8
+ Project-URL: Issues, https://github.com/combycode/dpe/issues
9
+ Project-URL: Changelog, https://github.com/combycode/dpe/blob/main/CHANGELOG.md
10
+ License-Expression: AGPL-3.0-or-later
11
+ Requires-Python: >=3.11
12
+ Provides-Extra: dev
13
+ Requires-Dist: jsonschema>=4.20; extra == 'dev'
14
+ Requires-Dist: mypy>=1.10; extra == 'dev'
15
+ Requires-Dist: pytest>=8.0; extra == 'dev'
16
+ Description-Content-Type: text/markdown
17
+
18
+ # combycode-dpe (Python)
19
+
20
+ DPE framework for building streaming pipeline tools in Python.
21
+
22
+ A DPE tool is an independent program: it reads NDJSON envelopes from stdin,
23
+ processes each one, and writes NDJSON envelopes to stdout. The runner
24
+ (`dpe`) spawns it, pipes data through it, and routes its output to the
25
+ next stage. The framework handles the loop, the parsing, the queues, and
26
+ the error/trace plumbing — your code only writes the transform.
27
+
28
+ Requires Python 3.11+.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ pip install combycode-dpe
34
+ # or in a per-tool venv:
35
+ uv venv --seed .venv && .venv/bin/pip install combycode-dpe
36
+ ```
37
+
38
+ ## Hello tool
39
+
40
+ ```python
41
+ # src/my_tool/main.py
42
+ import dpe
43
+
44
+ def process_input(v, settings, ctx):
45
+ ctx.output(v) # pass-through
46
+
47
+ if __name__ == "__main__":
48
+ dpe.run()
49
+ ```
50
+
51
+ Run as a tool: `python src/my_tool/main.py '{"...settings JSON..."}'`. The
52
+ runner passes settings as `argv[1]` and pipes NDJSON through stdin/stdout.
53
+
54
+ `dpe.run()` introspects the calling module to find `process_input` and
55
+ any `process_<queue>` handlers — no manual registration needed.
56
+
57
+ ## Processor signature
58
+
59
+ ```python
60
+ def process_input(v, settings, ctx):
61
+ ...
62
+ ```
63
+
64
+ - `v` — envelope payload (a dict / list / scalar — whatever JSON parsed to).
65
+ - `settings` — argv[1] parsed once at startup.
66
+ - `ctx` — emits output, errors, logs, metadata; reads/writes shared
67
+ accumulators in `ctx.memory`.
68
+
69
+ ## Internal queues
70
+
71
+ ```python
72
+ import dpe
73
+
74
+ def process_input(v, settings, ctx):
75
+ ctx.emit("validate", v)
76
+
77
+ def process_validate(v, settings, ctx):
78
+ if v.get("ok"):
79
+ ctx.output(v)
80
+ else:
81
+ ctx.error(v, "validation failed")
82
+
83
+ if __name__ == "__main__":
84
+ dpe.run()
85
+ ```
86
+
87
+ `ctx.emit(queue, v)` enqueues for the named handler. `ctx.drain()` blocks
88
+ until every queue is empty.
89
+
90
+ ## Context API (essentials)
91
+
92
+ | Call | What it does |
93
+ |---|---|
94
+ | `ctx.output(v, id=None, src=None)` | Emit `{t:"d",...}` to stdout. `id`/`src` default to inherit. |
95
+ | `ctx.emit(queue, v)` | Push to internal queue, processed by `process_<queue>`. |
96
+ | `ctx.drain()` | Block until all queues are empty. |
97
+ | `ctx.error(v, msg)` | Write `{type:"error",input:v,error:msg,...}` to stderr. |
98
+ | `ctx.log(level, msg)` | Structured stderr log. |
99
+ | `ctx.meta(v)` | Emit `{t:"m", v}` envelope to stdout. |
100
+ | `ctx.memory` | Typed accumulators: `Number`, `Average`, `MinMax`, `Set`, `Map`, `Buffer`, `Boolean`, `BitMask`, `Trigger`. |
101
+
102
+ See `docs/frameworks.md` in the monorepo for the full reference.
103
+
104
+ ## Scaffolding
105
+
106
+ ```bash
107
+ dpe-dev scaffold --name my-tool --runtime python --out ./my-tool --description "what it does"
108
+ cd my-tool
109
+ dpe-dev build . # creates .venv, installs the tool with [dev] extras
110
+ dpe-dev test . # pytest inside the venv
111
+ ```
112
+
113
+ End-to-end stage testing happens via `dpe test <pipeline>:<stage>` once the
114
+ tool is wired into a pipeline — see `docs/testing.md`.
115
+
116
+ ## Optional speed-up
117
+
118
+ For bulk-hashing payloads, install `xxhash` and pass `algorithm="xxhash"`
119
+ to `dpe.hash_file()`. The framework falls back to `hashlib.blake2b` when
120
+ xxhash is missing.
121
+
122
+ ## Repo & licence
123
+
124
+ - Source: <https://github.com/combycode/dpe/tree/main/frameworks/python>
125
+ - Monorepo: <https://github.com/combycode/dpe>
126
+ - Issues: <https://github.com/combycode/dpe/issues>
127
+ - Changelog: <https://github.com/combycode/dpe/blob/main/CHANGELOG.md>
128
+ - Licence: AGPL-3.0-or-later
@@ -104,6 +104,8 @@ xxhash is missing.
104
104
 
105
105
  ## Repo & licence
106
106
 
107
- - Source: <https://github.com/combycode/dpe-framework-python>
108
- - Monorepo (canonical): <https://github.com/combycode/dpe>
107
+ - Source: <https://github.com/combycode/dpe/tree/main/frameworks/python>
108
+ - Monorepo: <https://github.com/combycode/dpe>
109
+ - Issues: <https://github.com/combycode/dpe/issues>
110
+ - Changelog: <https://github.com/combycode/dpe/blob/main/CHANGELOG.md>
109
111
  - Licence: AGPL-3.0-or-later
@@ -4,8 +4,9 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "combycode-dpe"
7
- version = "2.0.3"
7
+ version = "2.1.0"
8
8
  description = "DPE framework for building streaming pipeline tools in Python"
9
+ readme = "README.md"
9
10
  license = "AGPL-3.0-or-later"
10
11
  requires-python = ">=3.11"
11
12
  dependencies = []
@@ -14,7 +15,11 @@ dependencies = []
14
15
  dev = ["pytest>=8.0", "jsonschema>=4.20", "mypy>=1.10"]
15
16
 
16
17
  [project.urls]
17
- Repository = "https://github.com/combycode/dpe-framework-python"
18
+ Homepage = "https://github.com/combycode/dpe"
19
+ Repository = "https://github.com/combycode/dpe"
20
+ Documentation = "https://github.com/combycode/dpe/blob/main/frameworks/python/README.md"
21
+ Issues = "https://github.com/combycode/dpe/issues"
22
+ Changelog = "https://github.com/combycode/dpe/blob/main/CHANGELOG.md"
18
23
 
19
24
  [tool.hatch.build.targets.wheel]
20
25
  packages = ["src/dpe"]
@@ -49,3 +54,7 @@ no_implicit_optional = true
49
54
  warn_redundant_casts = true
50
55
  warn_unused_ignores = true
51
56
  check_untyped_defs = false
57
+
58
+ [tool.pytest.ini_options]
59
+ # Import the checkout's own src/ even when another copy of `dpe` is installed.
60
+ pythonpath = ["src"]
@@ -5,6 +5,8 @@ Input side (runtime, before processor): $token/subpath -> absolute path
5
5
  Output side (context.output / context.meta): absolute path -> $token/subpath
6
6
 
7
7
  Both sides are a no-op when the DPE_* env vars are not set.
8
+ ``DPE_PATH_TOKENS=off`` (also ``0`` / ``false`` / ``no``) turns the output side off; the
9
+ runner sets it from the variant's / stage's ``path_tokens``. Input resolution stays on.
8
10
  """
9
11
 
10
12
  import os
@@ -20,10 +22,18 @@ _TOKEN_MAP = [
20
22
  ]
21
23
 
22
24
 
25
+ def tokens_enabled_from_env() -> bool:
26
+ """True unless ``DPE_PATH_TOKENS`` is ``off``, ``0``, ``false`` or ``no`` (any case)."""
27
+ v = os.environ.get("DPE_PATH_TOKENS")
28
+ if v is None:
29
+ return True
30
+ return v.strip().lower() not in ("off", "0", "false", "no")
31
+
32
+
23
33
  class EnvPaths:
24
34
  """Resolved env prefix map. Build once at tool startup."""
25
35
 
26
- __slots__ = ("_entries",)
36
+ __slots__ = ("_entries", "_no_tokenize")
27
37
 
28
38
  def __init__(self, pairs: list[tuple[str, str]] | None = None):
29
39
  """
@@ -47,6 +57,16 @@ class EnvPaths:
47
57
  self._entries: list[tuple[str, str]] = sorted(
48
58
  raw, key=lambda e: len(e[1]), reverse=True
49
59
  )
60
+ self._no_tokenize = (not tokens_enabled_from_env()) if pairs is None else False
61
+
62
+ def with_tokenize(self, on: bool) -> "EnvPaths":
63
+ """Turn the output side (absolute path -> ``$token``) on or off."""
64
+ self._no_tokenize = not on
65
+ return self
66
+
67
+ def tokenize_enabled(self) -> bool:
68
+ """Whether :meth:`tokenize_value` rewrites anything."""
69
+ return not self._no_tokenize
50
70
 
51
71
  @classmethod
52
72
  def from_env(cls) -> "EnvPaths":
@@ -69,7 +89,7 @@ class EnvPaths:
69
89
 
70
90
  def tokenize_value(self, v: Any) -> Any:
71
91
  """Walk v, tokenizing absolute paths back to $token[/subpath] form."""
72
- if self.is_empty():
92
+ if self.is_empty() or self._no_tokenize:
73
93
  return v
74
94
  return self._walk(v, self._tokenize_str)
75
95
 
@@ -1,5 +1,7 @@
1
1
  """Tests for EnvPaths -- $token resolve/tokenize round-trip."""
2
2
 
3
+ import pytest
4
+
3
5
  from dpe._paths import EnvPaths
4
6
 
5
7
 
@@ -129,3 +131,37 @@ class TestNamedFactories:
129
131
  monkeypatch.setenv("DPE_INPUT", "/ignored")
130
132
  p = EnvPaths.from_pairs([("input", "/explicit")])
131
133
  assert p.resolve_value("$input/file") == "/explicit/file"
134
+
135
+
136
+ # ─── DPE_PATH_TOKENS switch ───────────────────────────────────────────────
137
+
138
+
139
+
140
+ def test_path_tokens_default_on(monkeypatch):
141
+ monkeypatch.setenv("DPE_STORAGE", "/abs/storage")
142
+ monkeypatch.delenv("DPE_PATH_TOKENS", raising=False)
143
+ p = EnvPaths.from_env()
144
+ assert p.tokenize_enabled()
145
+ assert p.tokenize_value({"f": "/abs/storage/x.json"}) == {"f": "$storage/x.json"}
146
+
147
+
148
+ @pytest.mark.parametrize("val", ["off", "OFF", " 0 ", "false", "No"])
149
+ def test_path_tokens_off_keeps_absolute_but_resolves(monkeypatch, val):
150
+ monkeypatch.setenv("DPE_STORAGE", "/abs/storage")
151
+ monkeypatch.setenv("DPE_PATH_TOKENS", val)
152
+ p = EnvPaths.from_env()
153
+ assert not p.tokenize_enabled()
154
+ assert p.tokenize_value({"f": "/abs/storage/x.json"}) == {"f": "/abs/storage/x.json"}
155
+ assert p.resolve_value("$storage/x.json") == "/abs/storage/x.json"
156
+
157
+
158
+ @pytest.mark.parametrize("val", ["on", "1", "true", "yes", ""])
159
+ def test_path_tokens_other_values_keep_it_on(monkeypatch, val):
160
+ monkeypatch.setenv("DPE_STORAGE", "/abs/storage")
161
+ monkeypatch.setenv("DPE_PATH_TOKENS", val)
162
+ assert EnvPaths.from_env().tokenize_enabled()
163
+
164
+
165
+ def test_with_tokenize_on_explicit_pairs():
166
+ p = EnvPaths.from_pairs([("storage", "/abs/storage")]).with_tokenize(False)
167
+ assert p.tokenize_value("/abs/storage/a") == "/abs/storage/a"
@@ -1,11 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: combycode-dpe
3
- Version: 2.0.3
4
- Summary: DPE framework for building streaming pipeline tools in Python
5
- Project-URL: Repository, https://github.com/combycode/dpe-framework-python
6
- License-Expression: AGPL-3.0-or-later
7
- Requires-Python: >=3.11
8
- Provides-Extra: dev
9
- Requires-Dist: jsonschema>=4.20; extra == 'dev'
10
- Requires-Dist: mypy>=1.10; extra == 'dev'
11
- Requires-Dist: pytest>=8.0; extra == 'dev'
File without changes