zrb 0.0.72__tar.gz → 0.0.73__tar.gz

{zrb-0.0.72 → zrb-0.0.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zrb
-Version: 0.0.72
+Version: 0.0.73
 Summary: Your faithful companion
 Author-email: Go Frendi Gunawan <gofrendiasgard@gmail.com>
 Requires-Python: >=3.8

{zrb-0.0.72 → zrb-0.0.73}/docs/concepts/README.md

@@ -3,5 +3,6 @@
 # Concepts
 
 - [Tasks](tasks/README.md)
+- [Template](template.md)
 
 🔖 [Table of Contents](../README.md)

zrb-0.0.73/docs/concepts/template.md

@@ -0,0 +1,75 @@
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)
+
+# Template
+
+You can use [Jinja template](https://jinja.palletsprojects.com/en/3.1.x/templates) for
+- task input's default value
+- task environment's default value
+- several task's properties like `cmd`, `cmd_path`, `setup_cmd`, etc.
+
+There are several render data you can use. Some are always available, while some others are only available in specific properties
+
+# Common render data
+
+The following render data are always available:
+
+- `datetime`: Python datetime module
+- `os`: Python os module
+- `platform`: Python platform module
+- `time`: Python time module
+- `util`: Containing several utility function:
+    - `coalesce(value, *alternatives)`: you can use this function to coalesce value with alternatives
+    - `coalesce_str(value, *alternatives)`: Same as `util.coalesce`, but empty string is treated as `None` or `undefined`
+    - `to_camel_case(text)`: Return a `camelCased` text.
+    - `to_pascal_case(text)`: Return a `PascalCased` text.
+    - `to_kebab_case(text)`: Return a `kebab-cased` text.
+    - `to_snake_case(text)`: Return a `snake_cased` text.
+    - `to_human_readable(text)`: Return a `human readable` text.
+    - `to_boolean(text)`: Convert text to boolean. This function handle case-insensitive text, but it will throw an error if the text is neither true/false value representation.
+        - True value: `true`, `1`, `yes`, `y`, `active`
+        - False value: `false`, `0`, `0`, `n`, `inactive`
+
+# Special render data
+
+
+- `input`: Map representation task input's value. Accessible when you set `task environment`'s property or any `task` property.
+    - `<snake_case_key>`: All task key inputs are snake-cased. These keys are accessible when you set `task environment`'s default property or any `task` property.
+    - `_task`: Representation of current task object, only accessible from `task` property
+    - `_kwargs`: Map representation of current task input keyword arguments, only accessible from `task` property
+    - `_args`: List representation of current task input arguments, only accessible from `task` property
+- `env`: Map representation of task environment. Only accessible from task property.
+
+# Example
+
+```python
+from zrb import CmdTask, runner
+
+demo = CmdTask(
+    name='demo',
+    inputs=[
+        StrInput(
+            name='image-name',
+            default='docker.io/gofrendi/{{util.to_kebab_case(input.app_name)}}'
+        )
+    ],
+    envs=[
+        Env(name='IMAGE', default='{{input.image_name}}')
+    ],
+    cmd=[
+        'echo {{ input._args.0 }}',
+        'echo {% for arg in input._args %}{{ arg }}{% endfor %}',
+        'echo Image name (via input): {{ input.image_name }}',
+        'echo Image name (via env): {{ env.IMAGE }}',
+        'echo Image name (via env variable): $IMAGE',
+    ]
+)
+runner.register(demo)
+```
+
+You can try to invoke:
+
+```
+zrb demo --image-name docker.io/my-image one two three
+```
+
+🔖 [Table of Contents](../README.md) / [Concepts](README.md)

{zrb-0.0.72 → zrb-0.0.73}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "zrb"
-version = "0.0.72"
+version = "0.0.73"
 authors = [
   { name="Go Frendi Gunawan", email="gofrendiasgard@gmail.com" },
 ]

{zrb-0.0.72 → zrb-0.0.73}/src/zrb/task/base_task.py

@@ -344,56 +344,70 @@ class TaskModel(
             if override or key not in self._env_map:
                 self._env_map[key] = val
 
-    def render_any(self, val: Any) -> Any:
+    def render_any(
+        self, val: Any, data: Optional[Mapping[str, Any]] = None
+    ) -> Any:
         if isinstance(val, str):
-            return self.render_str(val)
+            return self.render_str(val, data)
         return val
 
-    def render_float(self, val: Union[str, float]) -> float:
+    def render_float(
+        self, val: Union[str, float], data: Optional[Mapping[str, Any]] = None
+    ) -> float:
         if isinstance(val, str):
-            return float(self.render_str(val))
+            return float(self.render_str(val, data))
         return val
 
-    def render_int(self, val: Union[str, int]) -> int:
+    def render_int(
+        self, val: Union[str, int], data: Optional[Mapping[str, Any]] = None
+    ) -> int:
         if isinstance(val, str):
-            return int(self.render_str(val))
+            return int(self.render_str(val, data))
         return val
 
-    def render_bool(self, val: Union[str, bool]) -> bool:
+    def render_bool(
+        self, val: Union[str, bool], data: Optional[Mapping[str, Any]] = None
+    ) -> bool:
         if isinstance(val, str):
-            return to_boolean(self.render_str(val))
+            return to_boolean(self.render_str(val, data))
         return val
 
-    def render_str(self, val: str) -> str:
+    def render_str(
+        self, val: str, data: Optional[Mapping[str, Any]] = None
+    ) -> str:
         if val in self._rendered_str:
             return self._rendered_str[val]
         if not is_probably_jinja(val):
             return val
         template = jinja2.Template(val)
-        data = self._get_render_data()
-        self.log_debug(f'Render string template: {val}, with data: {data}')
+        render_data = self._get_render_data(additional_data=data)
+        self.log_debug(f'Render string: {val}, with data: {render_data}')
         try:
-            rendered_text = template.render(data)
+            rendered_text = template.render(render_data)
             self.log_debug(f'Get rendered result: {rendered_text}')
         except Exception:
-            raise Exception(f'Fail to render "{val}" with data: {data}')
+            raise Exception(f'Fail to render "{val}" with data: {render_data}')
         self._rendered_str[val] = rendered_text
         return rendered_text
 
-    def render_file(self, location: str) -> str:
+    def render_file(
+        self, location: str, data: Optional[Mapping[str, Any]] = None
+    ) -> str:
         location_dir = os.path.dirname(location)
         env = jinja2.Environment(
             loader=AnyExtensionFileSystemLoader([location_dir])
         )
         template = env.get_template(location)
-        data = self._get_render_data()
-        data['TEMPLATE_DIR'] = location_dir
-        self.log_debug(f'Render template file: {template}, with data: {data}')
-        rendered_text = template.render(data)
+        render_data = self._get_render_data(additional_data=data)
+        render_data['TEMPLATE_DIR'] = location_dir
+        self.log_debug(f'Render template: {template} with data: {render_data}')
+        rendered_text = template.render(render_data)
         self.log_debug(f'Get rendered result: {rendered_text}')
         return rendered_text
 
-    def _get_render_data(self) -> Mapping[str, Any]:
+    def _get_render_data(
+        self, additional_data: Optional[Mapping[str, Any]] = None
+    ) -> Mapping[str, Any]:
         if self._render_data is not None:
             return self._render_data
         render_data = dict(DEFAULT_RENDER_DATA)
@@ -401,6 +415,8 @@ class TaskModel(
             'env': self._env_map,
             'input': self._input_map,
         })
+        if additional_data is not None:
+            render_data.update(additional_data)
         self._render_data = render_data
         return render_data
 
@@ -565,7 +581,7 @@ class BaseTask(TaskModel):
 
     def get_upstreams(self) -> Iterable[TTask]:
         return self._upstreams
-    
+
     def add_upstreams(self, *upstreams: TTask):
         if not self._can_add_upstream:
             raise Exception(f'Cannot add upstreams on `{self._name}`')

{zrb-0.0.72 → zrb-0.0.73}/src/zrb/task/docker_compose_task.py

@@ -257,4 +257,4 @@ class DockerComposeTask(CmdTask):
             f'docker compose {options} {self._compose_cmd} {flags} {args}',
         ])
         self.log_info(f'Command: {cmd_str}')
-        return cmd_str
+        return cmd_str

{zrb-0.0.72 → zrb-0.0.73}/test/task/test_flow_task.py

@@ -76,5 +76,7 @@ def test_flow_task_with_existing_tasks():
     main_loop = flow_task.create_main_loop()
     main_loop()
     assert outputs[0] == 'Lab prepared'
+    assert 'Na' in outputs
+    assert 'Cl' in outputs
     assert outputs[3] == 'NaCl'