dirigent-block-jq 0.17.2__tar.gz

dirigent_block_jq-0.17.2/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Morten Olav Hansen <morten@winterop.com>. All rights reserved.
+
+This source code and accompanying documentation are the property of
+Morten Olav Hansen. No license, express or implied, is granted to use, copy,
+modify, merge, publish, distribute, sublicense, or sell copies of this
+software or its derivatives.
+
+The source is published for reference only. Any use beyond reading
+requires written permission from the copyright holder.
+
+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 COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+Third-party components redistributed with this software, and the licences they
+carry, are listed in THIRD_PARTY_NOTICES.md.

dirigent_block_jq-0.17.2/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: dirigent-block-jq
+Version: 0.17.2
+Summary: The jq engine for dirigent's transform verbs: transform.jq, map.jq and filter.jq.
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: dirigent-common==0.17.2
+Requires-Dist: dirigent-plugin==0.17.2
+Requires-Dist: jq>=1.8
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# dirigent-block-jq
+
+The jq engine for the transform verbs: `transform.jq` reshapes a whole value with a jq
+program, `map.jq` replaces every element of a list with what a program makes of it, and
+`filter.jq` keeps the elements a program answers true for.
+
+A jq program is evaluated in a child process rather than in the worker, because jq holds the
+GIL for as long as a program runs and there is no way to interrupt one. The runner that child
+starts is a module of this package, run by path so it costs jq and the standard library to
+start.

dirigent_block_jq-0.17.2/README.md

@@ -0,0 +1,10 @@
+# dirigent-block-jq
+
+The jq engine for the transform verbs: `transform.jq` reshapes a whole value with a jq
+program, `map.jq` replaces every element of a list with what a program makes of it, and
+`filter.jq` keeps the elements a program answers true for.
+
+A jq program is evaluated in a child process rather than in the worker, because jq holds the
+GIL for as long as a program runs and there is no way to interrupt one. The runner that child
+starts is a module of this package, run by path so it costs jq and the standard library to
+start.

dirigent_block_jq-0.17.2/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "dirigent-block-jq"
+version = "0.17.2"
+description = "The jq engine for dirigent's transform verbs: transform.jq, map.jq and filter.jq."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "dirigent-common==0.17.2",
+    "dirigent-plugin==0.17.2",
+    "jq>=1.8",
+]
+
+[project.entry-points."dirigent.plugins.v1"]
+block-jq = "dirigent_block_jq:plugin"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.dirigent-common]
+workspace = true
+
+[tool.uv.sources.dirigent-plugin]
+workspace = true

dirigent_block_jq-0.17.2/pyproject.toml.orig

@@ -0,0 +1,28 @@
+[project]
+name = "dirigent-block-jq"
+version = "0.17.2"
+description = "The jq engine for dirigent's transform verbs: transform.jq, map.jq and filter.jq."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "dirigent-common==0.17.2",
+    "dirigent-plugin==0.17.2",
+    "jq>=1.8",
+]
+
+[project.entry-points."dirigent.plugins.v1"]
+block-jq = "dirigent_block_jq:plugin"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+dirigent-common = { workspace = true }
+dirigent-plugin = { workspace = true }

dirigent_block_jq-0.17.2/src/dirigent_block_jq/__init__.py

@@ -0,0 +1,24 @@
+"""The jq engine for the transform verbs: reshaping a value, and the element-wise pair."""
+
+from dirigent_block_jq.transform_jq import JqFilterer, JqMapper, JqTransformer
+from dirigent_plugin import Contribution, extension
+
+
+class JqBlocks:
+    """The plugin object the host discovers under the dirigent.plugins.v1 entry-point group."""
+
+    @extension
+    def contribute(self) -> Contribution:
+        """Contribute the jq engines behind the transform, map and filter verbs."""
+        return Contribution(operators=[JqTransformer(), JqMapper(), JqFilterer()])
+
+
+plugin = JqBlocks()
+
+__all__ = [
+    "JqBlocks",
+    "JqFilterer",
+    "JqMapper",
+    "JqTransformer",
+    "plugin",
+]

dirigent_block_jq-0.17.2/src/dirigent_block_jq/jq_runner.py

@@ -0,0 +1,65 @@
+"""The jq runner: the process a jq program is compiled and evaluated in, spoken to over its pipes.
+
+jq is a C extension that holds the GIL for as long as a program runs, so a program evaluated
+in the worker's own process holds its event loop too: the step's timeout never fires, the
+lease heartbeat never runs, and the sweeper eventually hands the attempt to another worker
+while this one is still computing. There is no way to interrupt a jq program and no way to
+cancel a thread, so a program runs here, where killing the process ends it.
+
+The runner protocol is what the pipes carry, one JSON object per line each way: ``compile``
+holds a program under the id it is named by, ``run`` evaluates the program held under an id
+over one value, and ``forget`` releases one. The pipe closing is how the parent says it is
+done, and compiling a program and reading its outputs are the only jq in here.
+
+This module is run by path, never imported, so it costs the standard library and jq and
+nothing else to start. Importing it as part of its package would load the
+whole plugin in order to evaluate ``.name``.
+"""
+
+import json
+import sys
+from typing import Any
+
+import jq
+
+#: Typed ``Any`` because the jq binding is a C extension that ships no type information.
+libjq: Any = jq
+
+
+def main() -> None:
+    """Answer one request at a time until the pipe closes, holding the programs compiled so far."""
+    out = sys.stdout.buffer
+    programs: dict[str, Any] = {}
+    for line in sys.stdin.buffer:
+        reply = answer(programs, json.loads(line))
+        out.write(json.dumps(reply).encode() + b"\n")
+        out.flush()
+
+
+def answer(programs: dict[str, Any], request: dict[str, Any]) -> dict[str, Any]:
+    """Compile a program under its id, run the one an id names, or release it."""
+    kind = request["kind"]
+    if kind == "compile":
+        try:
+            compiled = libjq.compile(request["program"])
+        except ValueError as error:
+            return {"error": str(error).strip()}
+        # Held only once it has compiled, so a refused program is not one an id names.
+        programs[request["id"]] = compiled
+        return {"ok": True}
+    if kind == "forget":
+        programs.pop(request["id"], None)
+        return {"ok": True}
+    if kind == "run":
+        compiled = programs.get(request["id"])
+        if compiled is None:
+            return {"error": f"no program is compiled under {request['id']}"}
+        try:
+            return {"outputs": compiled.input_value(request["value"]).all()}
+        except ValueError as error:
+            return {"error": str(error).strip()}
+    return {"error": f"{kind} is not a request kind: compile, run, or forget"}
+
+
+if __name__ == "__main__":
+    main()

dirigent_block_jq-0.17.2/src/dirigent_block_jq/messages.py

@@ -0,0 +1,36 @@
+"""Every refusal the jq engine makes, catalogued under the ``transform.jq`` prefix.
+
+A jq refusal reaches an attempt as ``plugin.transform_failed``: the verb frame owns the
+failure, and the engine's sentence rides on it as the ``detail`` param.
+"""
+
+from dirigent_common import Catalogue
+
+JQ = Catalogue("transform.jq")
+
+PROGRAM_REFUSED = JQ.define("program_refused", "{detail}")
+
+NO_OUTPUT = JQ.define(
+    "no_output",
+    "the program produced no output, and a transform step has to produce one; "
+    "a program that means 'possibly nothing' emits [] or null explicitly",
+)
+
+MAP_OUTPUT_COUNT = JQ.define(
+    "map_output_count",
+    "the program produced {produced} outputs, and a map replaces an element with "
+    "exactly one; a program that drops elements is a filter.jq step, and one that "
+    "changes how many there are is a transform.jq step",
+)
+
+FILTER_OUTPUT_COUNT = JQ.define(
+    "filter_output_count",
+    "the program produced {produced} outputs, and a filter answers one true or false "
+    "per element; a program that reshapes an element is a map.jq or transform.jq step",
+)
+
+FILTER_ANSWER = JQ.define(
+    "filter_answer",
+    "the program answered {answer}, and a filter answers true or false; jq's "
+    "truthiness is not applied, so a program meaning 'has readings' writes '.count > 0'",
+)

dirigent_block_jq-0.17.2/src/dirigent_block_jq/transform_jq.py

@@ -0,0 +1,155 @@
+"""The ``jq`` engines: a jq program as the transform, map, and filter verbs' program.
+
+A program is compiled and evaluated in a jq process of its own, over the runner protocol the
+plugin contract defines. jq is a C extension that holds the GIL for as long as a program
+runs, so evaluating one on the worker would hold the event loop with it and starve the step
+timeout and the lease heartbeat that share it. A program cannot be interrupted and a thread
+cannot be cancelled, so the step's timeout ends a program the only way there is: the process
+running it is killed, and the step fails with it.
+
+A bad program is refused with jq's own message: at apply on the worker, where there is no
+runner, and again by the runner when the step compiles it.
+"""
+
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Annotated, Any, ClassVar
+
+import jq
+from pydantic import BaseModel, Field, JsonValue
+
+from dirigent_block_jq.messages import (
+    FILTER_ANSWER,
+    FILTER_OUTPUT_COUNT,
+    MAP_OUTPUT_COUNT,
+    PROGRAM_REFUSED,
+)
+from dirigent_block_jq.messages import NO_OUTPUT as NO_OUTPUT_MESSAGE
+from dirigent_common import JQ_MEDIA_TYPE
+from dirigent_plugin import Filterer, Mapper, ProgramConfig, RunnerEngine, Transformer, TransformError
+
+#: What a program producing nothing is told to write instead.
+NO_OUTPUT = NO_OUTPUT_MESSAGE.render()
+
+#: Wraps the author's program so jq's ``env`` and ``$ENV`` read an empty object instead of
+#: the worker's environment, which is where dirigent's own secrets live. The program keeps
+#: its own line numbers because the message a bad one is refused with comes from compiling
+#: the author's text, unwrapped.
+SANDBOX = "{} as $ENV | def env: {}; (\n"
+
+#: The script a jq process runs, started by path so that it imports jq and the standard
+#: library and nothing else.
+RUNNER = Path(__file__).with_name("jq_runner.py")
+
+#: Typed ``Any`` because the jq binding is a C extension that ships no type information.
+libjq: Any = jq
+
+
+class JqEngine(RunnerEngine):
+    """Where the three jq engines' programs run: in a jq process, never on the worker's loop."""
+
+    command: ClassVar[Sequence[str]] = (sys.executable, str(RUNNER))
+
+    def source(self, program: str) -> str:
+        """Hand the runner the author's program with env and $ENV shadowed."""
+        return f"{SANDBOX}{program}\n)"
+
+    def check_program(self, program: str) -> None:
+        """Compile the program here at apply, refusing a bad one with jq's own message about it."""
+        try:
+            # The author's text is compiled first, so a refusal carries jq's message about
+            # their program and not about the wrapper.
+            libjq.compile(program)
+            libjq.compile(self.source(program))
+        except ValueError as error:
+            raise TransformError(PROGRAM_REFUSED.render(detail=str(error).strip())) from error
+
+
+class JqProgramConfig(ProgramConfig):
+    """The program-shaped config of a jq engine, whichever verb is running it.
+
+    All three verbs take the same program in the same language, so all three publish the
+    same config: the frame's fields, with ``program`` narrowed to jq source.
+    """
+
+    program: Annotated[str, Field(min_length=1, json_schema_extra={"contentMediaType": JQ_MEDIA_TYPE})]
+    """The jq program this step runs."""
+
+
+class JqTransformer(JqEngine, Transformer):
+    """Reshapes one whole value by running a jq program over it.
+
+    A jq program opens no file, no socket, and starts nothing: it is handed a value and
+    returns values, which is why this engine executes no code on the worker and needs no
+    allowlist entry. Its two ways of reading an environment, ``env`` and ``$ENV``, are
+    shadowed, so a program sees an empty object rather than the process it runs in -- which
+    is a jq process of dirigent's own, so that a step's timeout can end it.
+
+    A jq program is a stream: it can emit zero, one, or many outputs. One output is the
+    step's value, many outputs are that list of values, and none is a refusal, because a
+    step that produced nothing has no output for the next step to read.
+    """
+
+    kind = "jq"
+    summary = "Reshape a value with a jq program."
+    config_model: ClassVar[type[BaseModel]] = JqProgramConfig
+
+    def apply(self, compiled: object, value: JsonValue) -> JsonValue:
+        """Run the program over one value, and read its stream of outputs as one result."""
+        produced = self.outputs(compiled, value)
+        if not produced:
+            raise TransformError(NO_OUTPUT)
+        return produced[0] if len(produced) == 1 else produced
+
+
+class JqMapper(JqEngine, Mapper):
+    """Replaces every element of a list with what a jq program makes of that element.
+
+    The program is run once per element, with the element as its input, and is sandboxed
+    exactly as ``transform.jq`` is: ``env`` and ``$ENV`` read an empty object.
+
+    A map replaces each element with one thing, so the stream a program emits for an element
+    has to be exactly one output. Zero of them and several of them are both refusals rather
+    than a shorter or longer list, because dropping elements is what ``filter.jq`` is for and
+    changing their number is what ``transform.jq`` is for.
+    """
+
+    kind = "jq"
+    summary = "Replace every element of a list with what a jq program makes of it."
+    config_model: ClassVar[type[BaseModel]] = JqProgramConfig
+
+    def apply(self, compiled: object, value: JsonValue) -> JsonValue:
+        """Run the program over one element, and take its single output as the replacement."""
+        produced = self.outputs(compiled, value)
+        if len(produced) != 1:
+            raise TransformError(MAP_OUTPUT_COUNT.render(produced=len(produced)))
+        return produced[0]
+
+
+class JqFilterer(JqEngine, Filterer):
+    """Keeps the elements of a list a jq program answers true for.
+
+    The program is run once per element, with the element as its input, and is sandboxed
+    exactly as ``transform.jq`` is: ``env`` and ``$ENV`` read an empty object.
+
+    The answer has to be exactly one output, and that output has to be ``true`` or ``false``.
+    jq's own truthiness is not applied: a program emitting ``0`` or ``""`` is a mistake
+    surfaced rather than an element quietly dropped, and an author who means "has readings"
+    writes ``.count > 0``.
+    """
+
+    kind = "jq"
+    summary = "Keep the elements of a list a jq program answers true for."
+    config_model: ClassVar[type[BaseModel]] = JqProgramConfig
+
+    def keep(self, compiled: object, value: JsonValue) -> bool:
+        """Run the program over one element, and read its single boolean output as the verdict."""
+        produced = self.outputs(compiled, value)
+        if len(produced) != 1:
+            raise TransformError(FILTER_OUTPUT_COUNT.render(produced=len(produced)))
+        answer = produced[0]
+        if not isinstance(answer, bool):
+            raise TransformError(FILTER_ANSWER.render(answer=json.dumps(answer)))
+        return answer