dirigent-examples 0.23.4__tar.gz → 0.24.0__tar.gz

{dirigent_examples-0.23.4 → dirigent_examples-0.24.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: dirigent-examples
-Version: 0.23.4
+Version: 0.24.0
 Summary: The dirigent example corpus: the shelves of runnable documents, installed.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-client==0.23.4
-Requires-Dist: dirigent-plugin==0.23.4
+Requires-Dist: dirigent-client==0.24.0
+Requires-Dist: dirigent-plugin==0.24.0
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 

{dirigent_examples-0.23.4 → dirigent_examples-0.24.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-examples"
-version = "0.23.4"
+version = "0.24.0"
 description = "The dirigent example corpus: the shelves of runnable documents, installed."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,8 +11,8 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-client==0.23.4",
-    "dirigent-plugin==0.23.4",
+    "dirigent-client==0.24.0",
+    "dirigent-plugin==0.24.0",
 ]
 
 [project.entry-points."dirigent.plugins.v1"]

{dirigent_examples-0.23.4 → dirigent_examples-0.24.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-examples"
-version = "0.23.4"
+version = "0.24.0"
 description = "The dirigent example corpus: the shelves of runnable documents, installed."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -12,8 +12,8 @@ classifiers = [
 ]
 dependencies = [
     # The python/ shelf is SDK scripts a reader runs, so the corpus carries the client.
-    "dirigent-client==0.23.4",
-    "dirigent-plugin==0.23.4",
+    "dirigent-client==0.24.0",
+    "dirigent-plugin==0.24.0",
 ]
 
 [project.entry-points."dirigent.plugins.v1"]

{dirigent_examples-0.23.4 → dirigent_examples-0.24.0}/src/dirigent_examples/shelves/README.md

@@ -19,6 +19,7 @@ The documents live on topic shelves, each with its own README:
 | [`transform/`](transform) | The reshaping verbs: jq programs and the `convert.std` codec, no allowlist anywhere. |
 | [`recipes/`](recipes) | One question per file: how to group, join, pivot, clean, convert, check, store, and call. |
 | [`triggers/`](triggers) | What starts a run on its own: the three clocks, the inbound webhook, and a watch on a sensor. |
+| [`sources/`](sources) | A pipeline that starts where an input arrives: a source, a reply, and a run entered by hand. |
 | [`sensors/`](sensors) | Steps that wait for the world: a drop landing, a clock window opening. |
 | [`queues/`](queues) | A run started by a message: a Kafka topic and a RabbitMQ queue, waited on as sensors. |
 | [`execute/`](execute) | Code on the worker: a shell step behind the allowlist. |

{dirigent_examples-0.23.4 → dirigent_examples-0.24.0}/src/dirigent_examples/shelves/patterns/fan-out-item-wise.yaml

@@ -10,7 +10,7 @@
 # item 3 there, ${item} is the same element in both, and ${steps.<name>.item.output} is the
 # matching item's output.
 #
-# Three things the pairing buys, and one it costs:
+# Four things the pairing buys, and one it costs:
 #
 #   1. The width is the adopted grid's. Here that grid comes from params, so it was fixed when
 #      the run was created; adopting a grid read from a step's output expands when that one does.
@@ -18,7 +18,10 @@
 #      across a step that is not waited for would read an item that has not run.
 #   3. Adoption chains. A third step may map over the second's items and still reach the
 #      first's, because they are all one grid.
-#   4. The cost: an item whose match did not succeed is SKIPPED, not failed and not run. Its
+#   4. Each item goes on its own. shape runs under items: continue, so write_one's file for a
+#      region is written as soon as that region is shaped, not once every region has been.
+#      Under fail_fast the batch stands or falls together, and write_one waits for all of it.
+#   5. The cost: an item whose match did not succeed is SKIPPED, not failed and not run. Its
 #      input never existed, so there is nothing to attempt. The rest of the grid carries on.
 #
 # Hop by hop:

dirigent_examples-0.24.0/src/dirigent_examples/shelves/sources/README.md

@@ -0,0 +1,17 @@
+# Sources
+
+A pipeline that starts where an input arrives. A step is one of three things: a block, a
+source, where an input enters and whose output is that input, or a reply, which the server
+renders from the run's outputs to answer whoever sent it.
+
+| Document | What it shows |
+| --- | --- |
+| [`echo-by-hand.yaml`](echo-by-hand.yaml) | The smallest pipeline with a source: the input answered straight back. |
+| [`greet-by-hand.yaml`](greet-by-hand.yaml) | A path parameter, a jq step between the source and the reply, and a status of its own. |
+| [`signup-form.yaml`](signup-form.yaml) | A urlencoded form taken, and its caller answered 202 the moment the run exists. |
+
+Each runs by hand: `dg run --local` takes the source's `sample`, and `--input` gives one
+instead (`--source` names which source when a pipeline has several). Applied to a server, an
+endpoint is called at its route under `/endpoints` with the token the apply printed, and
+`dg source call` does that for you. A reply that holds its caller until it answers comes next;
+until then every caller is answered 202.

dirigent_examples-0.24.0/src/dirigent_examples/shelves/sources/echo-by-hand.yaml

@@ -0,0 +1,41 @@
+# The smallest pipeline with a source: what arrives is answered straight back.
+#
+# A SOURCE IS WHERE AN INPUT ENTERS. `ask` is not a block: it is the pipeline's first node, and
+# a run of the pipeline starts with it already settled, its output the input that arrived. The
+# endpoint kind's input is the request: method, path, query, headers, and the body, which is
+# what `${steps.ask.output.body}` reads.
+#
+# A REPLY IS WHAT THE CALLER IS ANSWERED WITH. `answer` is rendered by the server the moment
+# the steps it depends on have settled; no worker ever claims it. Run by hand, nobody is
+# waiting on the other end, so it renders and records what it would have answered.
+#
+# RUN IT BY HAND, here, with no server. No --input takes the source's sample:
+#
+#   dg run --local examples/sources/echo-by-hand.yaml
+#   dg run --local examples/sources/echo-by-hand.yaml --input '{body: {said: hi}}'
+#
+# EXPECT THIS RUN TO SUCCEED in well under a second, the reply's body the sample's.
+
+format: dirigent/v1
+kind: pipeline
+code: echo-by-hand
+name: Echo, by hand
+description: |
+  A source takes an input and a reply answers with it: the smallest pipeline with a source,
+  run by hand with its sample or with an input given.
+
+tags: [sources]
+
+steps:
+  ask:
+    source:
+      kind: endpoint
+      path: /echo
+      methods: [POST]
+    sample:
+      body: {said: hello from the sample}
+  answer:
+    depends_on: [ask]
+    reply:
+      status: 200
+      body: ${steps.ask.output.body}

dirigent_examples-0.24.0/src/dirigent_examples/shelves/sources/greet-by-hand.yaml

@@ -0,0 +1,50 @@
+# A request names someone, a step shapes the greeting, and a reply answers with it.
+#
+# THE PATH CARRIES A VALUE. The route `/greet/{name}` fills `path_params.name` from the path a
+# request is made at; run by hand, the input says it outright. The endpoint kind makes a
+# partial input whole -- the method its route declares, the path its template fills, the
+# body's content type and size -- so a sample or an --input says only what matters.
+#
+# BETWEEN THE SOURCE AND THE REPLY IS AN ORDINARY PIPELINE. `shape` is a jq transform like any
+# other, reading the source's output the way any step reads an upstream one, and the reply
+# answers with what it made, under a status of its own.
+#
+#   dg run --local examples/sources/greet-by-hand.yaml
+#   dg run --local examples/sources/greet-by-hand.yaml --input '{path_params: {name: Bergen}, body: {mood: wet}}'
+#
+# A method the route does not declare is refused before any run exists:
+#
+#   dg run --local examples/sources/greet-by-hand.yaml --input '{method: GET}'
+#
+# EXPECT THIS RUN TO SUCCEED in well under a second, answering 201 with the greeting.
+
+format: dirigent/v1
+kind: pipeline
+code: greet-by-hand
+name: Greet, by hand
+description: |
+  A request names someone in its path, a jq step shapes the greeting, and a reply answers
+  201 with it. Run by hand with the source's sample, or with an input given.
+
+tags: [sources, transform, jq, references]
+
+steps:
+  ask:
+    source:
+      kind: endpoint
+      path: /greet/{name}
+      methods: [POST]
+    sample:
+      path_params: {name: Oslo}
+      body: {mood: cheerful}
+  shape:
+    block: transform.jq
+    depends_on: [ask]
+    config:
+      input: ${steps.ask.output}
+      program: '{greeting: ("hello " + .path_params.name), mood: .body.mood}'
+  answer:
+    depends_on: [shape]
+    reply:
+      status: 201
+      body: ${steps.shape.output.value}

dirigent_examples-0.24.0/src/dirigent_examples/shelves/sources/signup-form.yaml

@@ -0,0 +1,48 @@
+# A form posted to this instance becomes a run, and its caller is answered 202 at once.
+#
+# A SOURCE TAKES A FORM AS WELL AS JSON. `signup` narrows its endpoint to urlencoded forms, so
+# a browser's <form method=post> or `curl -d` reaches it and a JSON body is refused 415. The
+# form arrives as `${steps.signup.output.body}`, each field a string, a repeated one a list.
+#
+# NOTHING WAITS FOR THE RUN. There is no reply, so the caller is answered 202 the moment the
+# run exists, with where to read it, and `tidy` runs afterwards on a worker.
+#
+# RUN IT BY HAND, here, with no server. No --input takes the source's sample:
+#
+#   dg run --local examples/sources/signup-form.yaml
+#
+# ON A SERVER, apply it and call it with the token the apply printed:
+#
+#   dg apply examples/sources/signup-form.yaml
+#   dg source call signup-form signup --form email=ada@example.org --form name=Ada --source-token "$TOKEN"
+#   curl -d email=ada@example.org -d name=Ada -H "Authorization: Bearer $TOKEN" \
+#     http://localhost:3333/endpoints/signups
+#
+# EXPECT THIS RUN TO SUCCEED in well under a second, `tidy` holding the address lowercased.
+
+format: dirigent/v1
+kind: pipeline
+code: signup-form
+name: Signup, by form
+description: |
+  A urlencoded form posted to an endpoint becomes a run, and its caller is answered 202 with
+  where to read it; a jq step tidies what the form carried.
+
+tags: [sources, forms, transform, jq]
+
+steps:
+  signup:
+    source:
+      kind: endpoint
+      path: /signups
+      accepts: [application/x-www-form-urlencoded]
+      max_body: 4KB
+    sample:
+      content_type: application/x-www-form-urlencoded
+      body: {email: Ada@Example.org, name: Ada}
+  tidy:
+    block: transform.jq
+    depends_on: [signup]
+    config:
+      input: ${steps.signup.output.body}
+      program: '{email: (.email | ascii_downcase), name: .name}'