zrb 0.0.118__tar.gz → 0.0.119__tar.gz

{zrb-0.0.118 → zrb-0.0.119}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: zrb
-Version: 0.0.118
-Summary: Super framework for your super app
+Version: 0.0.119
+Summary: A Framework to Enhance Your Workflow
 Author-email: Go Frendi Gunawan <gofrendiasgard@gmail.com>
 Requires-Python: >=3.10.0
 Description-Content-Type: text/markdown

{zrb-0.0.118 → zrb-0.0.119}/docs/faq/README.md

@@ -3,7 +3,7 @@
 # FAQ
 
 - [Why Python](why-python.md)
-- [Does Zrb has A Scheduler](does-zrb-has-a-scheduler.md)
+- [Does Zrb have a scheduler](does-zrb-have-a-scheduler.md)
 - [How to get data from other tasks](how-to-get-data-from-other-tasks.md)
 
 🔖 [Table of Contents](../README.md)

zrb-0.0.119/docs/faq/does-zrb-have-a-scheduler.md

@@ -0,0 +1,20 @@
+🔖 [Table of Contents](../README.md) / [FAQ](README.md)
+
+
+# Does Zrb Have a Scheduler?
+
+No, but you can use `RecurringTask` and `TimeWatcher`
+
+
+# How To Make A Scheduled Task?
+
+There are some [tricks](../tutorials/running-task-by-schedule.md) you can use.
+
+For example, you can use:
+
+- RecurringTask
+- Infinite loop
+- Cronjob
+- Orchestrator like Airflow.
+
+🔖 [Table of Contents](../README.md) / [FAQ](README.md)

{zrb-0.0.118 → zrb-0.0.119}/docs/getting-started.md

@@ -18,7 +18,7 @@ Welcome to Zrb's getting started guide. We will cover everything you need to kno
     - [Task Definition](#task-definition)
       - [Creating a Task Using Task Classes](#creating-a-task-using-task-classes)
       - [Creating a Task Using Python Decorator](#creating-a-task-using-python-decorator)
-    - [Task Parameters](#task-parameters)
+      - [Task Parameters](#task-parameters)
     - [Task Inputs](#task-inputs)
     - [Task Environments](#task-environments)
     - [Switching Environment](#switching-environment)
@@ -282,17 +282,21 @@ Commands:
 
 ## Activating Virtual Environment
 
-Working in a virtual environment is recommended in most cases. This encapsulates your project pip packages, ensuring better independence and reproducibility.
+> __📝 NOTE:__ Using virtual environment is not required, but highly recommended.
+
+A virtual environment encapsulates your project pip packages from other projects, ensuring better independence and reproducibility.
 
 ### Activating Virtual Environment On A Generated Project
 
-If you generate the project by invoking `zrb project create`, then you need to run the following command every time you start working on the project:
+If you generate the project by invoking `zrb project create`, you can create/activate the virtual environment by running the following command:
 
 ```bash
 source project.sh
 ```
 
-The command will activate the project's virtual environment and install necessary pip packages.
+The command will activate the project's virtual environment and install the necessary pip packages.
+
+You should run the command every time you start working on the project.
 
 ### Activating Virtual Environment On A Manually Created Project
 
@@ -310,10 +314,7 @@ Once you make the virtual environment, you can activate it by invoking the follo
 source .venv/bin/activate
 ```
 
-You need to run the command every time you start working on the project.
-
-
-> __💡 HINT:__ Working with virtual environment is recommended whenever you work with any Python project, including Zrb project.
+You should activate the virtual environment whenever you start working on the project.
 
 
 # Creating a Task
@@ -530,14 +531,16 @@ from zrb import runner, TaskClass
 # Define a task, along with it's parameters
 task_name = TaskClass(
     name='task-name',
-    parameter=value,
-    other_parameter=other_value
+    description='the description'
+    # ... other task parameters
 )
 
 # regiter the task to zrb runner
 runner.register(task_name)
 ```
 
+> __💡 HINT:__ Check out [task-parameter section](#task-parameters) to see the commonly used parameters
+
 There are several built-in task classes. Each with its specific use case:
 
 - __CmdTask__: Run a CLI command/shell script.
@@ -562,8 +565,8 @@ from zrb import runner, python_task
 # Decorate a function named `task_name`
 @python_task(
     name='task-name',
-    parameter=value,
-    other_parameter=other_value,
+    description='the description'
+    # ... other task parameters
     runner=runner # register the task to zrb runner
 )
 def task_name(*args, **kwargs):
@@ -572,12 +575,14 @@ def task_name(*args, **kwargs):
 # Note that python_task decorator turn your function into a task. So `task_name` is now a task, not a function.
 ```
 
+> __💡 HINT:__ Check out [task-parameter section](#task-parameters) to see the commonly used parameters
+
 Using `@python_task` decorator is your best choice if you need to write complex logic in Python.
 
 
-## Task Parameters
+### Task Parameters
 
-Each task has its specific parameter. However, the following tasks are typically available:
+Each task has its specific parameter. However, the following parameters are typically available:
 
 - __name__: The name of the task. When you invoke the task using the CLI, you need to use this name. By convention, the name should-be written in `kebab-case` (i.e., separated by `-`)
 - __description__: The description of the task.
@@ -873,7 +878,7 @@ Host: stalchmst.com
 
 # Creating a long-running task
 
-Commonly, you can determine whether a task is successful/failed after it is completed. However, some tasks might run forever, and you can only see whether the task is completed or failed by checking other behaviors. For example, a web server is successfully running if you can get the expected HTTP response from the server.
+Commonly, you can determine whether a task is successful/failed after the task is finished. However, some tasks might run forever, and you can only see whether the task is completed or failed by checking other behaviors. For example, a web server is successfully running if you can get the expected HTTP response from the server.
 
 Zrb has some checking mechanisms to handle this use case.
 
@@ -883,54 +888,18 @@ Let's start by scaffolding a CmdTask named `run-jupyterlab`.
 zrb project add cmd-task --project-dir "." --task-name "run-jupyterlab"
 ```
 
-Once you do so, you can start modifying `_automate/`
-
-In some cases, your task has to run forever (i.e., web server).
-
-Arasaka is a data-driven (and family-driven) company. They need their data scientists to experiment a lot to present the most valuable information/knowledge.
-
-For this, they need to be able to create a lot of notebooks for experimentation.
-
-To make sure things work, you need to:
-- Install jupyterlab.
-- Add Jupyterlab to your `requirements.txt`.
-- Create a `notebooks` directory under `src`.
-- Create a `start-jupyter` task.
-
-Let's start by installing jupyterlab
-
-```bash
-pip install jupyterlab
-```
-
-Once jupyterlab has been installed, you need to add it into requirements.txt. You can do so by typing `pip freeze | grep jupyterlab` and add the output to your `requirements.txt`. Or you can do it with a single command:
+You will notice that Zrb automatically creates a file named `_automate/run_jupyterlab.py`
 
-```bash
-pip freeze | grep jupyterlab >> requirements.txt
-```
-
-Now let's make a `notebooks` directory under `src`.
-
-```bash
-mkdir -p src/notebooks
-touch src/notebooks/.gitkeep
-```
+We will need to modify the file.
 
-You need an empty `.gitkeep` file, to tell git to not ignore the directory.
 
 ## Adding start-jupyterlab
 
 We have a few requirements for `start-jupyterlab` task
 
-- You should show Arasaka banner before starting jupyterlab.
-- `start-jupyterlab` is considered completed only if the port is accessible.
-- Arasaka employee can choose the port to serve jupyterlab in their computer.
-
-Let's start by adding the task to your project.
-
-```bash
-zrb project add cmd-task --project-dir . --task-name start-jupyterlab
-```
+- Before starting Jupyterlab, you need to make sure that Jupyterlab is already installed.
+- Jupyterlab is considered completed once the port is accessible.
+- Jupyterlab HTTP port should be `8080` by default, but users should be able to override the Jupyterlab HTTP port.
 
 Now, let's modify `_automate/start_jupyterlab.py` into the following:
 
@@ -978,6 +947,9 @@ Let's run the task:
 zrb project run-jupyterlab
 ```
 
+<details>
+<summary>Show output</summary>
+
 ```
 Jupyterlab port [8080]: 
 🤖 ○ ◷ 2023-11-12 10:26:32.759 ❁ 58728 → 1/3 🐨 zrb project install-jupyterlab • Run script: pip install jupyterlab
@@ -1011,6 +983,8 @@ Support zrb growth and development!
 🤖 ○ ◷ 2023-11-12 10:26:36.807 ❁ 58920 → 1/3 🐹 zrb project run-jupyterlab • Completed in 4.050489664077759 seconds
 ```
 
+</details>
+
 Open up your browser on [http://localhost:8080](http://localhost:8080) to start working with the notebook.
 
 # Now you are ready

{zrb-0.0.118 → zrb-0.0.119}/docs/tutorials/running-task-by-schedule.md

@@ -1,16 +1,57 @@
 🔖 [Table of Contents](../README.md) / [Tutorials](README.md)
 
-# Run Task by Schedule
+# Running Task by Schedule
 
 Zrb doesn't have any built-in scheduler. However, there are some workarounds you can use:
 
+- Using RecurringTask
 - Creating an infinite loop
 - Using Cronjob
 - Using Airflow or other orchestrator
 
+# Using RecurringTask
+
+The best approach is by turning your task into a recurring task.
+
+```python
+from zrb import CmdTask, TimeWatcher, RecurringTask, runner
+
+# Your original task
+hello = CmdTask(
+    name='hello',
+    cmd='echo "hello world"'
+)
+runner.register(hello)
+
+
+# Your recurring task
+scheduled_hello = RecurringTask(
+    name='scheduled-hello',
+    inputs=[
+        StrInput(name='schedule', default='* * * * *')
+    ],
+    triggers=[
+        TimeWatcher(schedule='{{input.schedule}}')
+    ],
+    task=hello
+)
+runner.register(scheduled_hello)
+```
+
+Notice that `TimeWatcher`'s `schedule` is a [cron schedule expression](https://crontab.guru/).
+
+The expression `* * * * *` means that the task will be executed every minute.
+
+To execute `scheduled-hello`, you can invoke:
+
+```bash
+zrb scheduled-hello
+```
+
+
 # Creating an Infinite Loop
 
-The simplest approach is by turning your task into a function, and call your function after some interval.
+Another simple approach is by turning your task into a function, and call your function after some interval.
 
 For example, you want to run `hello` task every 5 seconds. Then you can create the following Python script and run it. 
 
@@ -38,6 +79,7 @@ while True:
 python scheduled_hello.py
 ```
 
+
 # Using CronJob
 
 

{zrb-0.0.118 → zrb-0.0.119}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "zrb"
-version = "0.0.118"
+version = "0.0.119"
 authors = [
   { name="Go Frendi Gunawan", email="gofrendiasgard@gmail.com" },
 ]
-description = "Super framework for your super app"
+description = "A Framework to Enhance Your Workflow"
 readme = "README.md"
 requires-python = ">=3.10.0"
 classifiers = [

{zrb-0.0.118 → zrb-0.0.119}/src/zrb/builtin/__init__.py

@@ -12,7 +12,7 @@ from zrb.builtin import devtool
 from zrb.builtin import generator
 from zrb.builtin import process
 from zrb.builtin import say
-from zrb.builtin import watch
+from zrb.builtin import watch_changes
 from zrb.builtin import schedule
 
 assert base64
@@ -29,5 +29,5 @@ assert devtool
 assert generator
 assert process
 assert say
-assert watch
+assert watch_changes
 assert schedule

zrb-0.0.119/src/zrb/builtin/helper/reccuring_action.py

@@ -0,0 +1,46 @@
+from zrb.task.task import Task
+from zrb.task.cmd_task import CmdTask
+from zrb.task.notifier import Notifier
+from zrb.task_input.str_input import StrInput
+
+
+def create_recurring_action(
+    title: str,
+    default_message: str = '👋'
+) -> Task:
+    # define inputs
+    message_input = StrInput(
+        name='message',
+        default=default_message,
+        prompt='Message to be shown',
+    )
+    command_input = StrInput(
+        name='command',
+        default='',
+        prompt='Command to be executed',
+    )
+    # define tasks
+    run_command = CmdTask(
+        name='run-command',
+        icon='⚙️',
+        color='blue',
+        inputs=[command_input],
+        should_execute='{{ input.command != "" }}',
+        cmd='{{ input.command }}'
+    )
+    notify = Notifier(
+        name='notify',
+        icon='📢',
+        color='green',
+        inputs=[message_input],
+        title=title,
+        message='{{ input.message }}',
+        should_execute='{{ input.message != "" }}',
+    )
+    # return aggregator task
+    return Task(
+        name='recurring-action',
+        inputs=[message_input, command_input],
+        upstreams=[run_command, notify],
+        retry=0
+    )

zrb-0.0.119/src/zrb/builtin/schedule.py

@@ -0,0 +1,34 @@
+from zrb.task.recurring_task import RecurringTask
+from zrb.task.time_watcher import TimeWatcher
+from zrb.task_input.str_input import StrInput
+from zrb.runner import runner
+from zrb.builtin.helper.reccuring_action import create_recurring_action
+
+
+schedule = RecurringTask(
+    name='schedule',
+    icon='📅',
+    color='yellow',
+    description='Show message/run command periodically',
+    inputs=[
+        StrInput(
+            name='schedule',
+            default='* * * * *',
+            prompt='Schedule cron pattern (minute hour day(month) month day(week)',  # noqa
+            description='Schedule cron pattern to show the message'
+        ),
+    ],
+    triggers=[
+        TimeWatcher(
+            name='watch-schedule',
+            color='cyan',
+            icon='⏰',
+            schedule='{{input.schedule}}'
+        )
+    ],
+    task=create_recurring_action(
+        title='Schedule',
+        default_message='{{datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")}}',  # noqa
+    )
+)
+runner.register(schedule)

zrb-0.0.119/src/zrb/builtin/watch_changes.py

@@ -0,0 +1,31 @@
+from zrb.task.recurring_task import RecurringTask
+from zrb.task.path_watcher import PathWatcher
+from zrb.task_input.str_input import StrInput
+from zrb.runner import runner
+from zrb.builtin.helper.reccuring_action import create_recurring_action
+
+
+watch_changes = RecurringTask(
+    name='watch-changes',
+    icon='🕵️',
+    color='yellow',
+    description='Watch changes and show message/run command',
+    inputs=[
+        StrInput(
+            name='pattern',
+            default='*.*',
+            prompt='File pattern',
+            description='File pattern to be watched'
+        ),
+    ],
+    triggers=[
+        PathWatcher(
+            name='watch-path',
+            color='cyan',
+            icon='👀',
+            path='{{input.pattern}}'
+        )
+    ],
+    task=create_recurring_action(title='Watch')
+)
+runner.register(watch_changes)

zrb-0.0.119/src/zrb/shell-scripts/notify.ps1

@@ -0,0 +1,16 @@
+param (
+    [string]$Title,
+    [string]$Message
+)
+
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
+$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$toastXml = [xml] $template.GetXml()
+$toastTextElements = $toastXml.GetElementsByTagName("text")
+$toastTextElements[0].AppendChild($toastXml.CreateTextNode($Title)) # Title
+$toastTextElements[1].AppendChild($toastXml.CreateTextNode($Message)) # Message
+$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$xml.LoadXml($toastXml.OuterXml)
+$newToast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+$toastNotifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Zrb")
+$toastNotifier.Show($newToast)

{zrb-0.0.118 → zrb-0.0.119}/src/zrb/task/base_remote_cmd_task.py

@@ -262,3 +262,6 @@ class BaseRemoteCmdTask(BaseTask):
             retry=0,
             return_upstream_result=True
         )
+
+    def __repr__(self) -> str:
+        return f'<BaseRemoteCmdTask name={self._name}>'

{zrb-0.0.118 → zrb-0.0.119}/src/zrb/task/base_task/base_task.py

@@ -245,7 +245,6 @@ class BaseTask(
                 selected_advertisement = get_advertisement(advertisements)
                 selected_advertisement.show()
             self._show_done_info()
-            self._play_bell()
         await self.on_ready()
         return True
 

{zrb-0.0.118 → zrb-0.0.119}/src/zrb/task/base_task/component/base_task_model.py

@@ -169,7 +169,7 @@ class BaseTaskModel(CommonTaskModel, PidModel, TimeTracker):
         print(result)
 
     def _play_bell(self):
-        print('\a', end='', file=sys.stderr)
+        print('\a', end='', file=sys.stderr, flush=True)
 
     def _show_done_info(self):
         elapsed_time = self._get_elapsed_time()

{zrb-0.0.118 → zrb-0.0.119}/src/zrb/task/checker.py

@@ -87,3 +87,6 @@ class Checker(BaseTask):
             self.print_out_dark(message)
             return
         self.log_debug(message)
+
+    def __repr__(self) -> str:
+        return f'<Checker name={self._name}>'

zrb-0.0.119/src/zrb/task/notifier.py

@@ -0,0 +1,157 @@
+from zrb.helper.typing import Any, Callable, Iterable, Optional, Union
+from zrb.helper.typecheck import typechecked
+from zrb.task.base_task.base_task import BaseTask
+from zrb.task.any_task import AnyTask
+from zrb.task.any_task_event_handler import (
+    OnTriggered, OnWaiting, OnSkipped, OnStarted, OnReady, OnRetry, OnFailed
+)
+from zrb.task_env.env import Env
+from zrb.task_env.env_file import EnvFile
+from zrb.task_group.group import Group
+from zrb.task_input.any_input import AnyInput
+from zrb.helper.accessories.icon import get_random_icon
+from zrb.helper.string.modification import double_quote
+
+import os
+import subprocess
+
+CURRENT_DIR = os.path.dirname(__file__)
+NOTIFY_PS1_PATH = os.path.realpath(os.path.abspath(os.path.join(
+    os.path.dirname(CURRENT_DIR), 'shell-scripts', 'notify.ps1'
+)))
+
+
+@typechecked
+class Notifier(BaseTask):
+    def __init__(
+        self,
+        name: str = 'port-check',
+        group: Optional[Group] = None,
+        inputs: Iterable[AnyInput] = [],
+        envs: Iterable[Env] = [],
+        env_files: Iterable[EnvFile] = [],
+        icon: Optional[str] = None,
+        color: Optional[str] = None,
+        description: str = '',
+        title: str = '',
+        message: str = '',
+        show_toast: bool = True,
+        show_stdout: bool = True,
+        upstreams: Iterable[AnyTask] = [],
+        on_triggered: Optional[OnTriggered] = None,
+        on_waiting: Optional[OnWaiting] = None,
+        on_skipped: Optional[OnSkipped] = None,
+        on_started: Optional[OnStarted] = None,
+        on_ready: Optional[OnReady] = None,
+        on_retry: Optional[OnRetry] = None,
+        on_failed: Optional[OnFailed] = None,
+        checking_interval: Union[int, float] = 0,
+        retry: int = 2,
+        retry_interval: Union[float, int] = 1,
+        should_execute: Union[bool, str, Callable[..., bool]] = True
+    ):
+        BaseTask.__init__(
+            self,
+            name=name,
+            group=group,
+            inputs=inputs,
+            envs=envs,
+            env_files=env_files,
+            icon=icon,
+            color=color,
+            description=description,
+            upstreams=upstreams,
+            on_triggered=on_triggered,
+            on_waiting=on_waiting,
+            on_skipped=on_skipped,
+            on_started=on_started,
+            on_ready=on_ready,
+            on_retry=on_retry,
+            on_failed=on_failed,
+            checkers=[],
+            checking_interval=checking_interval,
+            retry=retry,
+            retry_interval=retry_interval,
+            should_execute=should_execute,
+        )
+        self._title = title if title != '' else name
+        self._message = message if message != '' else get_random_icon()
+        self._show_toast = show_toast
+        self._show_stdout = show_stdout
+
+    async def run(self, *args: Any, **kwargs: Any) -> str:
+        title = self.render_str(self._title)
+        message = self.render_str(self._message)
+        notify_kwargs = {
+            key: value
+            for key, value in kwargs.items() if key not in ('title', 'message')
+        }
+        await self.notify(title, message, **notify_kwargs)
+        return message
+
+    async def notify(self, title: str, message: str, **kwargs: Any) -> None:
+        task: BaseTask = kwargs.get('_task')
+        if self._show_toast and _is_powershell_available():
+            cmd = [
+                'powershell.exe',
+                '-ExecutionPolicy', 'Bypass',
+                '-File', NOTIFY_PS1_PATH,
+                '-Title', title,
+                '-Message', message
+            ]
+            subprocess.run(cmd, stdout=subprocess.DEVNULL)
+        if self._show_toast and _is_osascript_available():
+            q_message = double_quote(message)
+            q_title = double_quote(title)
+            cmd = [
+                'osascript',
+                '-e',
+                f'display notification "{q_message}" with title "{q_title}"'
+            ]
+        if self._show_toast and _is_notify_send_available():
+            cmd = ['notify-send', title, message]
+            subprocess.run(cmd, stdout=subprocess.DEVNULL)
+        if self._show_stdout:
+            task.print_out(message)
+            task._play_bell()
+
+    def __repr__(self) -> str:
+        return f'<Notifier name={self._name}>'
+
+
+def _is_powershell_available():
+    try:
+        subprocess.run(
+            ['powershell.exe', '-Command', 'echo "Checking PowerShell"'],
+            check=True, stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError, PermissionError):
+        return False
+
+
+def _is_notify_send_available():
+    try:
+        subprocess.run(
+            ['notify-send', '--version'],
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError, PermissionError):
+        return False
+
+
+def _is_osascript_available():
+    try:
+        subprocess.run(
+            ['osascript', '-e', 'return'],
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError, PermissionError):
+        return False