zrb 1.15.3__py3-none-any.whl → 2.0.0a4__py3-none-any.whl

zrb/task/base_trigger.py

@@ -5,7 +5,7 @@ from typing import Any
 from zrb.attr.type import fstring
 from zrb.callback.any_callback import AnyCallback
 from zrb.context.any_context import AnyContext
-from zrb.context.any_shared_context import AnySharedContext
+from zrb.context.print_fn import PrintFn
 from zrb.context.shared_context import SharedContext
 from zrb.dot_dict.dot_dict import DotDict
 from zrb.env.any_env import AnyEnv
@@ -36,7 +36,7 @@ class BaseTrigger(BaseTask):
         input: list[AnyInput | None] | AnyInput | None = None,
         env: list[AnyEnv | None] | AnyEnv | None = None,
         action: fstring | Callable[[AnyContext], Any] | None = None,
-        execute_condition: bool | str | Callable[[AnySharedContext], bool] = True,
+        execute_condition: bool | str | Callable[[AnyContext], bool] = True,
         queue_name: fstring | None = None,
         callback: list[AnyCallback] | AnyCallback = [],
         retries: int = 2,
@@ -50,6 +50,7 @@ class BaseTrigger(BaseTask):
         upstream: list[AnyTask] | AnyTask | None = None,
         fallback: list[AnyTask] | AnyTask | None = None,
         successor: list[AnyTask] | AnyTask | None = None,
+        print_fn: PrintFn | None = None,
     ):
         """
         Initializes a new instance of the BaseTrigger class.
@@ -103,6 +104,7 @@ class BaseTrigger(BaseTask):
             upstream=upstream,
             fallback=fallback,
             successor=successor,
+            print_fn=print_fn,
         )
         self._callbacks = callback
         self._queue_name = queue_name
@@ -127,7 +129,7 @@ class BaseTrigger(BaseTask):
         return self._callbacks
 
     async def exec_root_tasks(self, session: AnySession):
-        exchange_xcom = self.get_exchange_xcom(session)
+        exchange_xcom = self._get_exchange_xcom(session)
         exchange_xcom.add_push_callback(lambda: self._exchange_push_callback(session))
         return await super().exec_root_tasks(session)
 
@@ -136,8 +138,7 @@ class BaseTrigger(BaseTask):
         session.defer_coro(coro)
 
     async def _fanout_and_trigger_callback(self, session: AnySession):
-        exchange_xcom = self.get_exchange_xcom(session)
-        data = exchange_xcom.pop()
+        data = self.pop_exchange_xcom(session)
         coros = []
         for callback in self.callbacks:
             xcom_dict = DotDict({self.queue_name: Xcom([data])})
@@ -145,6 +146,7 @@ class BaseTrigger(BaseTask):
                 shared_ctx=SharedContext(
                     input=dict(session.shared_ctx.input),
                     xcom=xcom_dict,
+                    print_fn=self._print_fn,
                 ),
                 parent=session,
                 root_group=session.root_group,
@@ -156,8 +158,16 @@ class BaseTrigger(BaseTask):
             )
         await asyncio.gather(*coros)
 
-    def get_exchange_xcom(self, session: AnySession) -> Xcom:
+    def _get_exchange_xcom(self, session: AnySession) -> Xcom:
         shared_ctx = session.shared_ctx
         if self.queue_name not in shared_ctx.xcom:
             shared_ctx.xcom[self.queue_name] = Xcom()
         return shared_ctx.xcom[self.queue_name]
+
+    def push_exchange_xcom(self, session: AnySession, data: Any):
+        exchange_xcom = self._get_exchange_xcom(session)
+        exchange_xcom.push(data)
+
+    def pop_exchange_xcom(self, session: AnySession) -> Any:
+        exchange_xcom = self._get_exchange_xcom(session)
+        return exchange_xcom.pop()

zrb/task/cmd_task.py

@@ -6,6 +6,7 @@ from zrb.cmd.cmd_result import CmdResult
 from zrb.cmd.cmd_val import AnyCmdVal, CmdVal, SingleCmdVal
 from zrb.config.config import CFG
 from zrb.context.any_context import AnyContext
+from zrb.context.print_fn import PrintFn
 from zrb.env.any_env import AnyEnv
 from zrb.input.any_input import AnyInput
 from zrb.task.any_task import AnyTask
@@ -48,6 +49,7 @@ class CmdTask(BaseTask):
         warn_unrecommended_command: bool | None = None,
         max_output_line: int = 1000,
         max_error_line: int = 1000,
+        execution_timeout: int = 3600,
         is_interactive: bool = False,
         execute_condition: BoolAttr = True,
         retries: int = 2,
@@ -61,6 +63,7 @@ class CmdTask(BaseTask):
         upstream: list[AnyTask] | AnyTask | None = None,
         fallback: list[AnyTask] | AnyTask | None = None,
         successor: list[AnyTask] | AnyTask | None = None,
+        print_fn: PrintFn | None = None,
     ):
         super().__init__(
             name=name,
@@ -82,6 +85,7 @@ class CmdTask(BaseTask):
             upstream=upstream,
             fallback=fallback,
             successor=successor,
+            print_fn=print_fn,
         )
         self._shell = shell
         self._render_shell = render_shell
@@ -103,6 +107,7 @@ class CmdTask(BaseTask):
         self._render_cwd = render_cwd
         self._max_output_line = max_output_line
         self._max_error_line = max_error_line
+        self._execution_timeout = execution_timeout
         self._should_plain_print = plain_print
         self._should_warn_unrecommended_command = warn_unrecommended_command
         self._is_interactive = is_interactive
@@ -142,6 +147,7 @@ class CmdTask(BaseTask):
             register_pid_method=lambda pid: ctx.xcom.get(xcom_pid_key).push(pid),
             max_output_line=self._max_output_line,
             max_error_line=self._max_error_line,
+            timeout=self._execution_timeout,
             is_interactive=self._is_interactive,
         )
         # Check for errors

zrb/task/http_check.py

@@ -1,15 +1,19 @@
 import asyncio
 from collections.abc import Callable
+from typing import TYPE_CHECKING
 
 from zrb.attr.type import StrAttr
 from zrb.context.any_context import AnyContext
-from zrb.context.context import Context
+from zrb.context.print_fn import PrintFn
 from zrb.env.any_env import AnyEnv
 from zrb.input.any_input import AnyInput
 from zrb.task.any_task import AnyTask
 from zrb.task.base_task import BaseTask
 from zrb.util.attr import get_str_attr
 
+if TYPE_CHECKING:
+    from requests import Response
+
 
 class HttpCheck(BaseTask):
     def __init__(
@@ -19,16 +23,17 @@ class HttpCheck(BaseTask):
         icon: str | None = None,
         description: str | None = None,
         cli_only: bool = False,
-        input: list[AnyInput] | AnyInput | None = None,
-        env: list[AnyEnv] | AnyEnv | None = None,
+        input: list[AnyInput | None] | AnyInput | None = None,
+        env: list[AnyEnv | None] | AnyEnv | None = None,
         url: StrAttr = "http://localhost",
         render_url: bool = True,
         http_method: StrAttr = "GET",
         interval: int = 5,
-        execute_condition: bool | str | Callable[[Context], bool] = True,
+        execute_condition: bool | str | Callable[[AnyContext], bool] = True,
         upstream: list[AnyTask] | AnyTask | None = None,
         fallback: list[AnyTask] | AnyTask | None = None,
         successor: list[AnyTask] | AnyTask | None = None,
+        print_fn: PrintFn | None = None,
     ):
         super().__init__(
             name=name,
@@ -43,6 +48,7 @@ class HttpCheck(BaseTask):
             upstream=upstream,
             fallback=fallback,
             successor=successor,
+            print_fn=print_fn,
         )
         self._url = url
         self._render_url = render_url
@@ -57,7 +63,7 @@ class HttpCheck(BaseTask):
     def _get_http_method(self, ctx: AnyContext) -> str:
         return get_str_attr(ctx, self._http_method, "GET", auto_render=True).upper()
 
-    async def _exec_action(self, ctx: AnyContext) -> bool:
+    async def _exec_action(self, ctx: AnyContext) -> "bool | Response":
         import requests
 
         url = self._get_url(ctx)

zrb/task/make_task.py

@@ -2,7 +2,7 @@ from collections.abc import Callable
 from typing import Any
 
 from zrb.context.any_context import AnyContext
-from zrb.context.any_shared_context import AnySharedContext
+from zrb.context.print_fn import PrintFn
 from zrb.env.any_env import AnyEnv
 from zrb.group.any_group import AnyGroup
 from zrb.input.any_input import AnyInput
@@ -18,7 +18,7 @@ def make_task(
     cli_only: bool = False,
     input: list[AnyInput | None] | AnyInput | None = None,
     env: list[AnyEnv | None] | AnyEnv | None = None,
-    execute_condition: bool | str | Callable[[AnySharedContext], bool] = True,
+    execute_condition: bool | str | Callable[[AnyContext], bool] = True,
     retries: int = 2,
     retry_period: float = 0,
     readiness_check: list[AnyTask] | AnyTask | None = None,
@@ -30,10 +30,11 @@ def make_task(
     upstream: list[AnyTask] | AnyTask | None = None,
     fallback: list[AnyTask] | AnyTask | None = None,
     successor: list[AnyTask] | AnyTask | None = None,
+    print_fn: PrintFn | None = None,
     group: AnyGroup | None = None,
     alias: str | None = None,
 ) -> Callable[[Callable[[AnyContext], Any]], AnyTask]:
-    def _make_task(fn: Callable[[AnyContext], Any]) -> BaseTask:
+    def _make_task(fn: Callable[[AnyContext], Any]) -> AnyTask:
         task = BaseTask(
             name=name,
             color=color,
@@ -55,6 +56,7 @@ def make_task(
             upstream=upstream,
             fallback=fallback,
             successor=successor,
+            print_fn=print_fn,
         )
         if group is not None:
             return group.add_task(task, alias=alias)

zrb/task/rsync_task.py

@@ -1,7 +1,6 @@
-from collections.abc import Callable
-
-from zrb.attr.type import IntAttr, StrAttr
+from zrb.attr.type import BoolAttr, IntAttr, StrAttr
 from zrb.context.any_context import AnyContext
+from zrb.context.print_fn import PrintFn
 from zrb.env.any_env import AnyEnv
 from zrb.input.any_input import AnyInput
 from zrb.task.any_task import AnyTask
@@ -17,8 +16,8 @@ class RsyncTask(CmdTask):
         icon: str | None = None,
         description: str | None = None,
         cli_only: bool = False,
-        input: list[AnyInput] | AnyInput | None = None,
-        env: list[AnyEnv] | AnyEnv | None = None,
+        input: list[AnyInput | None] | AnyInput | None = None,
+        env: list[AnyEnv | None] | AnyEnv | None = None,
         shell: StrAttr | None = None,
         auto_render_shell: bool = True,
         remote_host: StrAttr | None = None,
@@ -39,18 +38,22 @@ class RsyncTask(CmdTask):
         render_local_source_path: bool = True,
         local_destination_path: StrAttr | None = None,
         render_local_destination_path: bool = True,
+        exclude_from: StrAttr | None = None,
+        render_exclude_from: bool = True,
         cwd: str | None = None,
         render_cwd: bool = True,
         plain_print: bool = False,
         max_output_line: int = 1000,
         max_error_line: int = 1000,
-        execute_condition: bool | str | Callable[[AnyContext], bool] = True,
+        execution_timeout: int = 3600,
+        execute_condition: BoolAttr = True,
         retries: int = 2,
         retry_period: float = 0,
         readiness_check: list[AnyTask] | AnyTask | None = None,
         upstream: list[AnyTask] | AnyTask | None = None,
         fallback: list[AnyTask] | AnyTask | None = None,
         successor: list[AnyTask] | AnyTask | None = None,
+        print_fn: PrintFn | None = None,
     ):
         super().__init__(
             name=name,
@@ -77,6 +80,7 @@ class RsyncTask(CmdTask):
             plain_print=plain_print,
             max_output_line=max_output_line,
             max_error_line=max_error_line,
+            execution_timeout=execution_timeout,
             execute_condition=execute_condition,
             retries=retries,
             retry_period=retry_period,
@@ -84,6 +88,7 @@ class RsyncTask(CmdTask):
             upstream=upstream,
             fallback=fallback,
             successor=successor,
+            print_fn=print_fn,
         )
         self._remote_source_path = remote_source_path
         self._render_remote_source_path = render_remote_source_path
@@ -93,6 +98,8 @@ class RsyncTask(CmdTask):
         self._render_local_source_path = render_local_source_path
         self._local_destination_path = local_destination_path
         self._render_local_destination_path = render_local_destination_path
+        self._exclude_from = exclude_from
+        self._render_exclude_from = render_exclude_from
 
     def _get_source_path(self, ctx: AnyContext) -> str:
         local_source_path = self._get_local_source_path(ctx)
@@ -144,16 +151,29 @@ class RsyncTask(CmdTask):
             auto_render=self._render_local_destination_path,
         )
 
+    def _get_exclude_from_param(self, ctx: AnyContext) -> str:
+        exclude_from = get_str_attr(
+            ctx,
+            self._exclude_from,
+            "",
+            auto_render=self._render_exclude_from,
+        ).strip()
+        if exclude_from == "":
+            return ""
+        return f"--exclude-from='{exclude_from}'"
+
     def _get_cmd_script(self, ctx: AnyContext) -> str:
         port = self._get_remote_port(ctx)
         password = self._get_remote_password(ctx)
         key = self._get_remote_ssh_key(ctx)
         src = self._get_source_path(ctx)
         dst = self._get_destination_path(ctx)
+        exclude_from = self._get_exclude_from_param(ctx)
+        exclude_from_with_space = f"{exclude_from} " if exclude_from != "" else ""
         if key != "" and password != "":
-            return f'sshpass -p "$_ZRB_SSH_PASSWORD" rsync --mkpath -avz -e "ssh -i {key} -p {port}" {src} {dst}'  # noqa
+            return f'sshpass -p "$_ZRB_SSH_PASSWORD" rsync --mkpath -avz -e "ssh -i {key} -p {port}" {exclude_from_with_space}{src} {dst}'  # noqa
         if key != "":
-            return f'rsync --mkpath -avz -e "ssh -i {key} -p {port}" {src} {dst}'
+            return f'rsync --mkpath -avz -e "ssh -i {key} -p {port}" {exclude_from_with_space}{src} {dst}'  # noqa
         if password != "":
-            return f'sshpass -p "$_ZRB_SSH_PASSWORD" rsync --mkpath -avz -e "ssh -p {port}" {src} {dst}'  # noqa
-        return f'rsync --mkpath -avz -e "ssh -p {port}" {src} {dst}'
+            return f'sshpass -p "$_ZRB_SSH_PASSWORD" rsync --mkpath -avz -e "ssh -p {port}" {exclude_from_with_space}{src} {dst}'  # noqa
+        return f'rsync --mkpath -avz -e "ssh -p {port}" {exclude_from_with_space}{src} {dst}'

zrb/task/scaffolder.py

@@ -2,10 +2,11 @@ import os
 import shutil
 from collections.abc import Callable
 
-from zrb.attr.type import BoolAttr, StrAttr
+from zrb.attr.type import StrAttr
 from zrb.content_transformer.any_content_transformer import AnyContentTransformer
 from zrb.content_transformer.content_transformer import ContentTransformer
 from zrb.context.any_context import AnyContext
+from zrb.context.print_fn import PrintFn
 from zrb.env.any_env import AnyEnv
 from zrb.input.any_input import AnyInput
 from zrb.task.any_task import AnyTask
@@ -24,8 +25,8 @@ class Scaffolder(BaseTask):
         icon: str | None = None,
         description: str | None = None,
         cli_only: bool = False,
-        input: list[AnyInput] | AnyInput | None = None,
-        env: list[AnyEnv] | AnyEnv | None = None,
+        input: list[AnyInput | None] | AnyInput | None = None,
+        env: list[AnyEnv | None] | AnyEnv | None = None,
         source_path: StrAttr | None = None,
         render_source_path: bool = True,
         destination_path: StrAttr | None = None,
@@ -36,7 +37,7 @@ class Scaffolder(BaseTask):
             list[AnyContentTransformer] | AnyContentTransformer | TransformConfig
         ) = [],
         render_transform_content: bool = True,
-        execute_condition: BoolAttr = True,
+        execute_condition: bool | str | Callable[[AnyContext], bool] = True,
         retries: int = 2,
         retry_period: float = 0,
         readiness_check: list[AnyTask] | AnyTask | None = None,
@@ -48,6 +49,7 @@ class Scaffolder(BaseTask):
         upstream: list[AnyTask] | AnyTask | None = None,
         fallback: list[AnyTask] | AnyTask | None = None,
         successor: list[AnyTask] | AnyTask | None = None,
+        print_fn: PrintFn | None = None,
     ):
         super().__init__(
             name=name,
@@ -69,6 +71,7 @@ class Scaffolder(BaseTask):
             upstream=upstream,
             fallback=fallback,
             successor=successor,
+            print_fn=print_fn,
         )
         self._source_path = source_path
         self._render_source_path = render_source_path

zrb/task/scheduler.py

@@ -6,6 +6,7 @@ from zrb.attr.type import StrAttr, fstring
 from zrb.callback.any_callback import AnyCallback
 from zrb.context.any_context import AnyContext
 from zrb.context.any_shared_context import AnySharedContext
+from zrb.context.print_fn import PrintFn
 from zrb.env.any_env import AnyEnv
 from zrb.input.any_input import AnyInput
 from zrb.task.any_task import AnyTask
@@ -24,8 +25,8 @@ class Scheduler(BaseTrigger):
         cli_only: bool = False,
         input: list[AnyInput | None] | AnyInput | None = None,
         env: list[AnyEnv | None] | AnyEnv | None = None,
-        schedule: StrAttr = None,
-        execute_condition: bool | str | Callable[[AnySharedContext], bool] = True,
+        schedule: StrAttr | None = None,
+        execute_condition: bool | str | Callable[[AnyContext], bool] = True,
         queue_name: fstring | None = None,
         callback: list[AnyCallback] | AnyCallback = [],
         retries: int = 2,
@@ -39,6 +40,7 @@ class Scheduler(BaseTrigger):
         upstream: list[AnyTask] | AnyTask | None = None,
         fallback: list[AnyTask] | AnyTask | None = None,
         successor: list[AnyTask] | AnyTask | None = None,
+        print_fn: PrintFn | None = None,
     ):
         super().__init__(
             name=name,
@@ -62,6 +64,7 @@ class Scheduler(BaseTrigger):
             upstream=upstream,
             fallback=fallback,
             successor=successor,
+            print_fn=print_fn,
         )
         self._cron_pattern = schedule
 
@@ -76,6 +79,6 @@ class Scheduler(BaseTrigger):
             ctx.print(f"Current time: {now}")
             if match_cron(cron_pattern, now):
                 ctx.print(f"Matching {now} with pattern: {cron_pattern}")
-                xcom = self.get_exchange_xcom(ctx.session)
-                xcom.push(now)
+                if ctx.session is not None:
+                    self.push_exchange_xcom(ctx.session, now)
             await asyncio.sleep(60)

zrb/task/tcp_check.py

@@ -3,7 +3,7 @@ from collections.abc import Callable
 
 from zrb.attr.type import IntAttr, StrAttr
 from zrb.context.any_context import AnyContext
-from zrb.context.context import Context
+from zrb.context.print_fn import PrintFn
 from zrb.env.any_env import AnyEnv
 from zrb.input.any_input import AnyInput
 from zrb.task.any_task import AnyTask
@@ -19,16 +19,17 @@ class TcpCheck(BaseTask):
         icon: str | None = None,
         description: str | None = None,
         cli_only: bool = False,
-        input: list[AnyInput] | AnyInput | None = None,
-        env: list[AnyEnv] | AnyEnv | None = None,
+        input: list[AnyInput | None] | AnyInput | None = None,
+        env: list[AnyEnv | None] | AnyEnv | None = None,
         host: StrAttr = "localhost",
         render_host: bool = True,
         port: IntAttr = 80,
         interval: int = 5,
-        execute_condition: bool | str | Callable[[Context], bool] = True,
+        execute_condition: bool | str | Callable[[AnyContext], bool] = True,
         upstream: list[AnyTask] | AnyTask | None = None,
         fallback: list[AnyTask] | AnyTask | None = None,
         successor: list[AnyTask] | AnyTask | None = None,
+        print_fn: PrintFn | None = None,
     ):
         super().__init__(
             name=name,
@@ -43,6 +44,7 @@ class TcpCheck(BaseTask):
             upstream=upstream,
             fallback=fallback,
             successor=successor,
+            print_fn=print_fn,
         )
         self._host = host
         self._render_host = render_host

zrb/util/ascii_art/art/bee.txt

@@ -0,0 +1,17 @@
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠛⣉⡙⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠛⣡⣴⣿⣿⠇⣾⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⢃⣴⣿⣿⣿⣿⡟⢰⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⠟⢿⣿⣿⣿⣿⣿⡇⣸⣿⣿⣿⣿⡟⣠⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣇⣀⡲⣦⢻⣿⣿⣿⣿⡇⣿⣿⣿⣿⡟⣰⣿⡿⠿⠿⢿⣿⣿⣿⣿⣿
+⣿⣿⣧⠙⠸⣿⣿⣿⣿⡇⣿⣿⣿⢏⠼⣋⣥⣶⣿⣿⣦⣤⣉⡛⠻⢿
+⣿⢟⡁⠀⠀⠀⠙⣿⣿⣇⢿⣿⠋⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⠈
+⡇⠀⡿⠀⠀⠀⠀⠈⠉⣹⣾⠕⠾⣿⣿⣿⣿⡿⠿⠿⠟⠛⢛⣉⣤⣾
+⣇⠀⠀⢀⠀⠀⠠⢀⣴⣿⠏⠀⢀⣶⡶⣶⣶⣶⣾⣿⣿⣿⣿⣿⣿⣿
+⣿⣶⣤⣤⣤⣦⣶⡿⠟⠁⠀⢠⣾⣿⠃⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⡄⠀⣀⣠⣴⣿⠟⠁⠀⢠⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⠛⠛⠋⠁⠀⠀⣠⣿⡿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⣤⣤⣶⣿⡿⠋⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣯⡁⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿

zrb/util/ascii_art/art/cat.txt

@@ -0,0 +1,9 @@
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⢿⣿⣿⣿⣿
+⣿⣿⣿⣿⡿⢋⠹⣿⣿⣿⣿⣿⠟⢿⣿⣿⣿⣿⣿⣿⠃⠀⢨⣿⣿⣿⣿
+⣿⣿⣿⠟⣠⣿⣧⣈⣉⣉⣉⣁⣶⡌⢻⣿⣿⣿⣿⣿⠘⠀⣿⣿⣿⣿⣿
+⣿⣿⠏⣼⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡄⠛⠛⠛⠛⠛⠀⡀⠻⣿⣿⣿⣿
+⣿⣿⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠘⣿⣿⣿⣿⣿⣿⣦⠈⢋⣉⠙
+⣿⣿⡎⢿⣿⣶⣶⣿⣿⣿⣿⣤⣼⣿⡟⢠⣿⣿⣿⡿⠿⠟⠛⣀⣡⣤⣴
+⠟⣁⣴⣦⠉⠛⠛⠛⠛⠛⠿⠟⠛⠁⠀⣋⣉⣥⣴⣶⣾⣿⣿⣿⣿⣿⣿
+⣤⣭⣤⣶⣶⣿⣿⣿⠋⣠⡼⢋⣤⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣤⣤⣴⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿

zrb/util/ascii_art/art/ghost.txt

@@ -0,0 +1,16 @@
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⢋⣉⣉⣉⣉⠛⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⡿⠋⣠⣾⣿⣿⣿⣿⣿⣷⣦⡈⢻⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⡿⢁⣾⡟⠁⣨⣿⣿⡅⠈⢻⣿⣿⡄⢻⣿⣿⣿⣿⣿⣿
+⣿⠏⣤⣤⣉⠛⠃⢸⣿⣷⣾⡟⠉⠉⢻⣶⣾⣿⣿⡇⢸⣿⣿⣿⣿⣿⣿
+⣿⣧⠄⣹⣿⣿⣷⣬⣿⣿⣿⡇⠀⠀⢸⣿⣿⣿⣿⡇⢸⡿⠿⠿⠿⢿⣿
+⣿⠇⣰⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⣴⣿⣿⣿⣿⣿⣥⣤⣶⣶⣶⡶⠆⣹
+⡏⢰⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣯⢰⣾⣿
+⣧⠘⢿⡿⠟⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡀⣿⣿
+⣿⣷⣦⣴⠂⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⣿⣿
+⣿⣿⣿⣿⡀⠻⠿⠋⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡏⢠⣈⠛⣁⣼⣿⣿
+⣿⣿⣿⣿⣿⣿⣾⣿⣆⠘⣿⣿⣿⣿⣿⣿⡟⠙⠛⠃⣼⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧⡘⢿⣿⣿⣿⣿⡀⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣆⡙⢿⣿⣿⣧⡈⠻⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⣉⡙⠻⠿⣦⠙⢿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣦⣌⠡⠘⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⣠⣿⣿⣿⣿⣿⣿

zrb/util/ascii_art/art/panda.txt

@@ -0,0 +1,17 @@
+⣿⣿⣿⣿⣿⣿⣿⣿⠿⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⠏⠀⠀⠀⠀⠙⠿⠿⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⡀⠀⣠⣴⣶⣿⣿⣿⣿⣶⣮⣝⠻⢿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⡟⣡⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⡀⠀⠀⠙⢿
+⣿⠿⣿⣿⡿⢰⣿⡿⠋⠉⠉⢻⣿⣿⣿⣿⣿⣿⣿⣿⣿⡄⠀⠀⣸
+⠁⠀⠀⠙⠃⢿⣿⡅⠀⠀⢀⣼⣿⣿⣿⣿⠟⠛⠻⣿⣿⣷⢀⣴⣿
+⡀⠀⠀⠀⠀⠸⣿⣛⣳⣾⣿⢿⡍⢉⣻⡇⠰⠀⠀⣿⣿⣿⢸⣿⣿
+⣷⡀⠀⠀⠀⠀⠈⠻⢿⣿⣿⣷⣶⣬⣽⣿⣦⣤⣤⣟⣿⢇⣾⣿⣿
+⣿⣿⣄⠀⠀⠀⠀⠀⠀⠈⠙⠻⠿⣿⣿⣿⣿⣮⣿⠟⣡⣾⣿⣿⣿
+⣿⣿⣿⡇⢰⣶⣤⣤⣤⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⢻⣿⣿⣿⣿⣿
+⣿⣿⣿⣇⣿⣿⣿⣿⣿⣿⣿⣿⣷⣶⣤⡀⠀⠀⠀⠀⢻⣿⣿⣿⣿
+⣿⣿⣿⡈⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⡄⠀⠀⠀⠀⢿⣿⣿⣿
+⣿⣿⣿⡇⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⢸⣿⣿⣿
+⣿⣿⣿⡇⠀⠙⠿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠃⢠⣄⣀⣠⣿⣿⣿⣿
+⣿⣿⣿⣿⠀⠀⠀⠀⠉⣉⣛⣛⡛⠉⠁⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣆⠀⠀⠀⣰⣿⣿⣿⣷⡀⠀⠀⢀⣾⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣷⣶⣶⣿⣿⣿⣿⣿⣿⣶⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿

zrb/util/ascii_art/art/rose.txt

@@ -0,0 +1,14 @@
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⣿⣿⣿⣿⠁⠀⠉⠉⠛⠛⠛⠉⠛⢻⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⠟⠋⠁⠀⠀⠀⠈⠙⢧⣤⣤⡀⠀⠀⠀⠀⠀⠀⠀⢻⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⡿⠀⠀⠀⠀⠀⢀⣠⡴⠾⠛⠛⠿⣷⣄⠀⠀⠀⠀⠀⠀⢻⣿⣿⣿⣿
+⣿⣿⣿⠋⠀⠀⠀⠀⣠⣶⣿⠁⠀⠀⣀⡀⠀⠈⠻⣦⡀⠀⠀⠀⠀⠀⣿⣿⣿⣿
+⣿⣿⡏⠀⠀⠀⠀⣰⡿⠛⠙⠿⠛⠉⠛⠟⢿⣷⣄⣸⡇⠐⢦⣤⣤⠔⠛⠻⣿⣿
+⣿⣿⡃⠀⠀⠀⠀⡟⠀⣠⠀⠀⠀⠀⢀⠀⠀⠹⠛⠛⣧⠀⠀⠙⠁⠀⠀⠀⠘⣿
+⣿⣿⣷⡀⠀⠀⢸⠀⢰⣿⡀⠀⠀⠀⢹⣿⠀⢀⡆⠀⠘⣆⣴⣿⠀⠀⠀⠀⠀⠘
+⣿⡟⠀⠙⣄⠀⢸⠀⠀⢻⣷⣄⠀⠤⠞⠋⣠⡾⠁⠀⢠⠟⠉⠻⡇⠀⠀⠀⠀⢰
+⡿⠁⠀⠀⣿⣷⣾⣧⠀⠀⠈⠛⢳⠤⠒⠚⠉⠀⢀⡴⠃⠀⠀⠀⠃⠀⠀⠀⣠⣿
+⡁⠀⠀⠀⣿⠀⠀⠹⣷⠄⢀⣠⣴⣿⣶⣤⣶⡾⠋⠀⠀⠀⠀⠀⠀⠀⠀⣴⣿⣿
+⣷⡄⠀⠀⢻⠀⠀⠀⠘⢧⡀⠈⠉⠛⠛⠋⠉⠀⠀⠀⣀⣠⣴⣂⣀⠠⠊⢹⣿⣿
+⣿⣿⣦⡀⢈⡄⠀⠀⠀⠀⠉⠙⠒⠒⠦⠤⠤⣶⣶⣿⣿⠿⠛⠋⠁⠀⢀⣾⣿⣿
+⣿⣿⣿⣿⣿⣷⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣸⠋⠀⠀⠀⠀⣠⣴⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣦⣄⡀⠀⠀⢀⣀⣠⣴⣾⣿⣶⣤⣠⣴⣿⣿⣿⣿⣿⣿⣿

zrb/util/ascii_art/art/unicorn.txt

@@ -0,0 +1,15 @@
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠛⠉⢠⡟⠋⣽⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⠿⠛⠋⠉⠑⠁⠀⠀⠈⠀⣼⣿⣿⣿⣿⠿⠟⢛⣫⣽⣶
+⣿⣿⣿⡿⠋⠁⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠉⢁⣠⣴⣾⣿⣿⣿⣿
+⣿⣿⣯⡴⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣾⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⡿⠋⠀⠀⠀⠀⠀⠀⠀⠀⡄⠀⠀⠀⠀⠈⠁⢻⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⣧⡀⠀⠀⠀⠀⠀⠘⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠹⣷⣶⣦⡀⠀⠀⠀⢻⣿⣿⣿⣿⣿⣿⣿
+⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠙⢿⣷⠀⡀⠀⢸⣿⣿⣿⣿⣿⣿⣿
+⣿⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⢿⣧⣷⣤⣾⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣦⣄⡀⠀⠀⠈⢦⡀⠀⠀⠀⢀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣧⣤⣀⠀⣿⡀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣾⣷⠀⢠⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣇⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿

zrb/util/ascii_art/banner.py

@@ -0,0 +1,92 @@
+import os
+import random
+
+
+def create_banner(art: str | None = None, text: str | None = None) -> str:
+    # First get art using _get_art_only
+    art_content = _get_art_only(art)
+
+    # If no text provided, just return the art
+    if text is None or text.strip() == "":
+        return art_content
+
+    # Find the longest line in the art, make every line has the same length
+    art_lines = art_content.splitlines()
+    if not art_lines:
+        return text
+
+    # Find the maximum line length in the art
+    max_art_length = max(len(line) for line in art_lines)
+
+    # Pad all art lines to the same length
+    padded_art_lines = [line.ljust(max_art_length) for line in art_lines]
+
+    # Split text into lines
+    text_lines = text.splitlines()
+
+    # Combine art and text lines
+    combined_lines = []
+
+    # Determine the maximum number of lines we need
+    max_lines = max(len(padded_art_lines), len(text_lines))
+
+    # Calculate vertical offsets for centering
+    art_offset = (max_lines - len(padded_art_lines)) // 2
+    text_offset = (max_lines - len(text_lines)) // 2
+
+    for i in range(max_lines):
+        # Get art line (or empty string if we've run out of art lines)
+        art_index = i - art_offset
+        if 0 <= art_index < len(padded_art_lines):
+            art_line = padded_art_lines[art_index]
+        else:
+            art_line = " " * max_art_length
+
+        # Get text line (or empty string if we've run out of text lines)
+        text_index = i - text_offset
+        if 0 <= text_index < len(text_lines):
+            text_line = text_lines[text_index]
+        else:
+            text_line = ""
+
+        # Combine art and text lines
+        combined_line = art_line + "  " + text_line
+        combined_lines.append(combined_line)
+
+    # Return the combined result
+    return "\n".join(combined_lines)
+
+
+def _get_art_only(art: str | None = None) -> str:
+    # If name is provided
+    if art is not None:
+        # 1) name is a file, load the content of the file, return
+        expanded_name = os.path.expanduser(art)
+        if os.path.isfile(expanded_name):
+            with open(expanded_name, "r") as f:
+                return f.read()
+
+        # 2) name is a string, but not a file
+        # Check if art/name.txt exists in the script directory
+        cwd = os.path.dirname(__file__)
+        art_path = os.path.join(cwd, "art", f"{art}.txt")
+        if os.path.isfile(art_path):
+            with open(art_path, "r") as f:
+                return f.read()
+
+    # 3) otherwise load random file from art/ directory
+    cwd = os.path.dirname(__file__)
+    art_dir = os.path.join(cwd, "art")
+    # Get all .txt files in the art directory
+    try:
+        art_files = [f for f in os.listdir(art_dir) if f.endswith(".txt")]
+    except FileNotFoundError:
+        # If art directory doesn't exist, return empty string
+        return ""
+    if not art_files:
+        return ""
+    # Select a random file
+    random_file = random.choice(art_files)
+    random_file_path = os.path.join(art_dir, random_file)
+    with open(random_file_path, "r") as f:
+        return f.read()