dyngle 0.4.0__tar.gz → 0.4.2__tar.gz

{dyngle-0.4.0 → dyngle-0.4.2}/PACKAGE.md

@@ -37,30 +37,45 @@ Dyngle reads configuration from YAML files. You can specify the config file loca
 - `.dyngle.yml` in current directory
 - `~/.dyngle.yml` in home directory
 
-## Workflow structure
+The configuration has 2 parts: `operations:` and `expressions`.
 
-Each operation is defined as a list of tasks under `dyngle.operations`. Tasks are executed sequentially using Python's subprocess module for security.
+## Data
 
-Example with multiple operations:
+Dyngle maintains a block of data throughout operations, which is parsed from YAML in stdin.
+
+## Operations
+
+Operations contain steps as a YAML array. The lifecycle of an operation is:
+
+1. Load input data if it exists from YAML on stdin (if no tty)
+2. Perform template rendering on a step, using data and expressions (see below)
+3. Execute the step in a subprocess
+4. Continue with the next step
+
+Note that operations in the config are _not_ full shell lines. They are passed directly to the system.
+
+## Templates
+
+Prior to running commands, the line containing that command is processed as a template. Entries from the data set can be substituted into the command line using Jinja-like expressions in double-curly brackets (`{{` and `}}`).
+
+For example, if stdin contains the following data:
 
 ```yaml
-dyngle:
-  operations:
-    test:
-      - python -m unittest discover
-      - python -m coverage report
-    docs:
-      - sphinx-build docs docs/_build
-      - open docs/_build/index.html
-    setup:
-      - python -m venv venv
-      - source venv/bin/activate
-      - pip install -r requirements.txt
+name: Francis
+```
+
+And the command looks like:
+
+``` yaml
+- echo "Hello {{name}}!"
 ```
 
+Then the command will output "Hello Francis!".
+
+
 ## Expressions
 
-Configs can also contain expressions.
+Configs can also contain expressions, written in Python, that can also be referenced in operation steps.
 
 ```yaml
 dyngle:
@@ -70,6 +85,7 @@ dyngle:
   operations:
     say-hello: echo {{say-hello}}
 ```
+
 Expressions can use a controlled subset of the Python standard library, including:
 
 - Built-in data types such as `str()`
@@ -77,10 +93,11 @@ Expressions can use a controlled subset of the Python standard library, includin
 - The core modules from the `datetime` package (but some methods such as `strftime()` will fail)
 - A specialized function called `formatted()` to perform string formatting operations on a `datetime` object
 - A restricted version of `Path()` that only operates within the current working directory
+- Various other useful utilities, mostly read-only, such as the `math` module
 
 ## Security
 
-Commands are executed using Python's `subprocess.run()` with arguments split in a shell-like fashion. The shell is not used, which reduces the likelihood of shell injection attacks. However, note that Dyngle is not robust to malicious configuration. 
+Commands are executed using Python's `subprocess.run()` with arguments split in a shell-like fashion. The shell is not used, which reduces the likelihood of shell injection attacks. However, note that Dyngle is not robust to malicious configuration. Use with caution.
 
 ## Quick installation (MacOS)
 

{dyngle-0.4.0 → dyngle-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dyngle
-Version: 0.4.0
+Version: 0.4.2
 Summary: Run lightweight local workflows
 License: MIT
 Author: Steampunk Wizard
@@ -52,30 +52,45 @@ Dyngle reads configuration from YAML files. You can specify the config file loca
 - `.dyngle.yml` in current directory
 - `~/.dyngle.yml` in home directory
 
-## Workflow structure
+The configuration has 2 parts: `operations:` and `expressions`.
 
-Each operation is defined as a list of tasks under `dyngle.operations`. Tasks are executed sequentially using Python's subprocess module for security.
+## Data
 
-Example with multiple operations:
+Dyngle maintains a block of data throughout operations, which is parsed from YAML in stdin.
+
+## Operations
+
+Operations contain steps as a YAML array. The lifecycle of an operation is:
+
+1. Load input data if it exists from YAML on stdin (if no tty)
+2. Perform template rendering on a step, using data and expressions (see below)
+3. Execute the step in a subprocess
+4. Continue with the next step
+
+Note that operations in the config are _not_ full shell lines. They are passed directly to the system.
+
+## Templates
+
+Prior to running commands, the line containing that command is processed as a template. Entries from the data set can be substituted into the command line using Jinja-like expressions in double-curly brackets (`{{` and `}}`).
+
+For example, if stdin contains the following data:
 
 ```yaml
-dyngle:
-  operations:
-    test:
-      - python -m unittest discover
-      - python -m coverage report
-    docs:
-      - sphinx-build docs docs/_build
-      - open docs/_build/index.html
-    setup:
-      - python -m venv venv
-      - source venv/bin/activate
-      - pip install -r requirements.txt
+name: Francis
+```
+
+And the command looks like:
+
+``` yaml
+- echo "Hello {{name}}!"
 ```
 
+Then the command will output "Hello Francis!".
+
+
 ## Expressions
 
-Configs can also contain expressions.
+Configs can also contain expressions, written in Python, that can also be referenced in operation steps.
 
 ```yaml
 dyngle:
@@ -85,6 +100,7 @@ dyngle:
   operations:
     say-hello: echo {{say-hello}}
 ```
+
 Expressions can use a controlled subset of the Python standard library, including:
 
 - Built-in data types such as `str()`
@@ -92,10 +108,11 @@ Expressions can use a controlled subset of the Python standard library, includin
 - The core modules from the `datetime` package (but some methods such as `strftime()` will fail)
 - A specialized function called `formatted()` to perform string formatting operations on a `datetime` object
 - A restricted version of `Path()` that only operates within the current working directory
+- Various other useful utilities, mostly read-only, such as the `math` module
 
 ## Security
 
-Commands are executed using Python's `subprocess.run()` with arguments split in a shell-like fashion. The shell is not used, which reduces the likelihood of shell injection attacks. However, note that Dyngle is not robust to malicious configuration. 
+Commands are executed using Python's `subprocess.run()` with arguments split in a shell-like fashion. The shell is not used, which reduces the likelihood of shell injection attacks. However, note that Dyngle is not robust to malicious configuration. Use with caution.
 
 ## Quick installation (MacOS)
 

{dyngle-0.4.0 → dyngle-0.4.2}/dyngle/template.py

@@ -11,15 +11,17 @@ class Template:
 
     template: str
 
-    def render(self, data: dict, expressions: dict = None) -> str:
+    def render(self, data: dict = None, expressions: dict = None) -> str:
         """Render the template with the provided data."""
+        data = data if data else {}
+        expressions = expressions if expressions else {}
         resolver = partial(self._resolve, data=data, expressions=expressions)
         return PATTERN.sub(resolver, self.template)
 
     def _resolve(self, match, *, data: dict, expressions: dict):
         """Resolve a single name/path from the template."""
         key = match.group(1).strip()
-        if expressions and (key in expressions):
+        if key in expressions:
             return expressions[key](data)
         else:
             parts = key.split('.')

{dyngle-0.4.0 → dyngle-0.4.2}/pyproject.toml

@@ -8,7 +8,7 @@ description = "Run lightweight local workflows"
 authors = ["Steampunk Wizard <dyngle@steamwiz.io>"]
 license = "MIT"
 readme = "PACKAGE.md"
-version = "0.4.0"
+version = "0.4.2"
 
 [tool.poetry.dependencies]
 python = "~3.11"