zrb 0.28.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

zrb/runner/cli.py

@@ -0,0 +1,179 @@
+import sys
+from typing import Any
+
+from zrb.config import BANNER, VERSION, WEB_HTTP_PORT
+from zrb.context.any_context import AnyContext
+from zrb.context.shared_context import SharedContext
+from zrb.group.group import Group
+from zrb.runner.common_util import get_run_kwargs
+from zrb.runner.web_app import create_web_app
+from zrb.runner.web_config.config_factory import web_config
+from zrb.session.session import Session
+from zrb.session_state_logger.session_state_logger_factory import session_state_logger
+from zrb.task.any_task import AnyTask
+from zrb.task.make_task import make_task
+from zrb.util.cli.style import (
+    stylize_bold_yellow,
+    stylize_faint,
+    stylize_section_header,
+)
+from zrb.util.group import extract_node_from_args, get_non_empty_subgroups, get_subtasks
+from zrb.util.load import load_zrb_init
+from zrb.util.string.conversion import double_quote
+
+
+class Cli(Group):
+    def run(self, args: list[str] = []):
+        load_zrb_init()
+        kwargs, args = self._extract_kwargs_from_args(args)
+        node, node_path, args = extract_node_from_args(self, args)
+        if isinstance(node, Group):
+            self._show_group_info(node)
+            return
+        if "h" in kwargs or "help" in kwargs:
+            self._show_task_info(node)
+            return
+        run_kwargs = get_run_kwargs(task=node, args=args, kwargs=kwargs, prompt=True)
+        try:
+            result = self._run_task(node, args, run_kwargs)
+            if result is not None:
+                print(result)
+            return result
+        finally:
+            run_command = self._get_run_command(node_path, run_kwargs)
+            self._print_run_command(run_command)
+
+    def _print_run_command(self, run_command: str):
+        print(
+            stylize_faint("To run again:"),
+            stylize_bold_yellow(run_command),
+            file=sys.stderr,
+        )
+
+    def _get_run_command(self, node_path: list[str], run_kwargs: dict[str, str]) -> str:
+        parts = [self.name] + node_path
+        if len(run_kwargs) > 0:
+            parts += [
+                self._get_run_command_param(key, val) for key, val in run_kwargs.items()
+            ]
+        return " ".join(parts)
+
+    def _get_run_command_param(self, key: str, val: str) -> str:
+        if '"' in val or "'" in val or " " in val or val == "":
+            return f"--{key} {double_quote(val)}"
+        return f"--{key} {val}"
+
+    def _run_task(
+        self, task: AnyTask, args: list[str], run_kwargs: dict[str, str]
+    ) -> tuple[Any]:
+        shared_ctx = SharedContext(args=args)
+        for task_input in task.inputs:
+            if task_input.name in run_kwargs:
+                task_input.update_shared_context(
+                    shared_ctx, run_kwargs[task_input.name]
+                )
+                continue
+        return task.run(Session(shared_ctx=shared_ctx, root_group=self))
+
+    def _show_task_info(self, task: AnyTask):
+        description = task.description
+        inputs = task.inputs
+        if description != task.name and description != "":
+            print(stylize_section_header("DESCRIPTION"))
+            print(description)
+            print()
+        if len(inputs) > 0:
+            print(stylize_section_header("INPUTS"))
+            max_input_name_length = max(len(task_input.name) for task_input in inputs)
+            for task_input in inputs:
+                task_input_name = task_input.name.ljust(max_input_name_length + 1)
+                print(f"  --{task_input_name}: {task_input.description}")
+            print()
+
+    def _show_group_info(self, group: Group):
+        if group.banner != "":
+            print(group.banner)
+            print()
+        if group.description != group.name and group.description != "":
+            print(stylize_section_header("DESCRIPTION"))
+            print(group.description)
+            print()
+        subgroups = get_non_empty_subgroups(group)
+        if len(subgroups) > 0:
+            print(stylize_section_header("GROUPS"))
+            max_subgroup_alias_length = max(len(s) for s in subgroups)
+            for alias, subgroup in subgroups.items():
+                alias = alias.ljust(max_subgroup_alias_length + 1)
+                print(f"  {alias}: {subgroup.description}")
+            print()
+        subtasks = get_subtasks(group)
+        if len(subtasks) > 0:
+            print(stylize_section_header("TASKS"))
+            max_subtask_alias_length = max(len(s) for s in subtasks)
+            for alias, subtask in subtasks.items():
+                alias = alias.ljust(max_subtask_alias_length + 1)
+                print(f"  {alias}: {subtask.description}")
+            print()
+
+    def _extract_kwargs_from_args(
+        self, args: list[str]
+    ) -> tuple[dict[str, Any], list[str]]:
+        residual_args = []  # To store positional arguments
+        kwargs = {}  # To store options as a dictionary
+        i = 0
+        while i < len(args):
+            arg = args[i]
+            if arg.startswith("--"):
+                # Handle key-value pairs like --keyword=value
+                if "=" in arg:
+                    key, value = arg[2:].split("=", 1)
+                    kwargs[key] = value
+                else:
+                    # Handle flags like --this followed by a value or set to True
+                    key = arg[2:]
+                    # Check if the next item is a value or another flag
+                    if i + 1 < len(args) and not args[i + 1].startswith("-"):
+                        kwargs[key] = args[i + 1]
+                        i += 1  # Skip the next argument as it's a value
+                    else:
+                        kwargs[key] = True
+            elif arg.startswith("-"):
+                # Handle short flags like -t or -n
+                key = arg[1:]
+                kwargs[key] = True
+            else:
+                # Anything else is considered a positional argument
+                residual_args.append(arg)
+            i += 1
+        return kwargs, residual_args
+
+
+cli = Cli(name="zrb", description="Your Automation Powerhouse", banner=BANNER)
+
+
+@make_task(
+    name="version", description="🌟 Get current Zrb version", retries=0, group=cli
+)
+def get_version(_: AnyContext):
+    return VERSION
+
+
+server_group = cli.add_group(
+    Group(name="server", description="🌐 Server related command")
+)
+
+
+@make_task(
+    name="start-server",
+    description="🚀 Start Zrb Web Server",
+    cli_only=True,
+    retries=0,
+    group=server_group,
+    alias="start",
+)
+async def start_server(_: AnyContext):
+    from uvicorn import Config, Server
+
+    app = create_web_app(cli, web_config, session_state_logger)
+    server = Server(Config(app=app, host="0.0.0.0", port=WEB_HTTP_PORT, loop="asyncio"))
+    await server.serve()

zrb/runner/common_util.py

@@ -0,0 +1,31 @@
+from typing import Any
+
+from zrb.context.shared_context import SharedContext
+from zrb.task.any_task import AnyTask
+
+
+def get_run_kwargs(
+    task: AnyTask, args: list[str], kwargs: dict[str, str], prompt: bool = True
+) -> tuple[Any]:
+    arg_index = 0
+    str_kwargs = {key: val for key, val in kwargs.items()}
+    run_kwargs = {**str_kwargs}
+    shared_ctx = SharedContext(args=args)
+    for task_input in task.inputs:
+        if task_input.name in str_kwargs:
+            # Update shared context for next input default value
+            task_input.update_shared_context(shared_ctx, str_kwargs[task_input.name])
+        elif arg_index < len(args) and task_input.allow_positional_parsing:
+            run_kwargs[task_input.name] = args[arg_index]
+            # Update shared context for next input default value
+            task_input.update_shared_context(shared_ctx, run_kwargs[task_input.name])
+            arg_index += 1
+        else:
+            if prompt:
+                str_value = task_input.prompt_cli_str(shared_ctx)
+            else:
+                str_value = task_input.get_default_str(shared_ctx)
+            run_kwargs[task_input.name] = str_value
+            # Update shared context for next input default value
+            task_input.update_shared_context(shared_ctx, run_kwargs[task_input.name])
+    return run_kwargs

zrb/runner/web_app.py

@@ -0,0 +1,69 @@
+import asyncio
+import sys
+from typing import TYPE_CHECKING
+
+from zrb.config import BANNER, VERSION
+from zrb.group.any_group import AnyGroup
+from zrb.runner.web_config.config import WebConfig
+from zrb.runner.web_route.docs_route import serve_docs
+from zrb.runner.web_route.error_page.serve_default_404 import serve_default_404
+from zrb.runner.web_route.home_page.home_page_route import serve_home_page
+from zrb.runner.web_route.login_api_route import serve_login_api
+from zrb.runner.web_route.login_page.login_page_route import serve_login_page
+from zrb.runner.web_route.logout_api_route import serve_logout_api
+from zrb.runner.web_route.logout_page.logout_page_route import serve_logout_page
+from zrb.runner.web_route.node_page.node_page_route import serve_node_page
+from zrb.runner.web_route.refresh_token_api_route import serve_refresh_token_api
+from zrb.runner.web_route.static.static_route import serve_static_resources
+from zrb.runner.web_route.task_input_api_route import serve_task_input_api
+from zrb.runner.web_route.task_session_api_route import serve_task_session_api
+from zrb.session_state_logger.any_session_state_logger import AnySessionStateLogger
+
+if TYPE_CHECKING:
+    # We want fastapi to only be loaded when necessary to decrease footprint
+    from fastapi import FastAPI
+
+
+def create_web_app(
+    root_group: AnyGroup,
+    web_config: WebConfig,
+    session_state_logger: AnySessionStateLogger,
+) -> "FastAPI":
+    from contextlib import asynccontextmanager
+
+    from fastapi import FastAPI
+
+    _COROS = []
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        for line in BANNER.split("\n") + [
+            f"Zrb Server running on http://localhost:{web_config.port}"
+        ]:
+            print(line, file=sys.stderr)
+        yield
+        for coro in _COROS:
+            coro.cancel()
+        asyncio.gather(*_COROS)
+
+    app = FastAPI(
+        title="Zrb",
+        version=VERSION,
+        summary="Your Automation Powerhouse",
+        lifespan=lifespan,
+        docs_url=None,
+    )
+
+    serve_default_404(app, root_group, web_config)
+    serve_static_resources(app, web_config)
+    serve_docs(app)
+    serve_home_page(app, root_group, web_config)
+    serve_login_page(app, root_group, web_config)
+    serve_logout_page(app, root_group, web_config)
+    serve_node_page(app, root_group, web_config)
+    serve_login_api(app, web_config)
+    serve_logout_api(app, web_config)
+    serve_refresh_token_api(app, web_config)
+    serve_task_input_api(app, root_group, web_config)
+    serve_task_session_api(app, root_group, web_config, session_state_logger, _COROS)
+    return app

zrb/runner/web_config/config.py

@@ -0,0 +1,91 @@
+from typing import Callable
+
+from zrb.runner.web_schema.user import User
+from zrb.task.any_task import AnyTask
+
+
+class WebConfig:
+    def __init__(
+        self,
+        port: int,
+        secret_key: str,
+        access_token_expire_minutes: int,
+        refresh_token_expire_minutes: int,
+        access_token_cookie_name: str,
+        refresh_token_cookie_name: str,
+        enable_auth: bool,
+        super_admin_username: str,
+        super_admin_password: str,
+        guest_username: str,
+        guest_accessible_tasks: list[AnyTask | str] = [],
+        find_user_by_username: Callable[[str], User | None] | None = None,
+    ):
+        self.secret_key = secret_key
+        self.access_token_expire_minutes = access_token_expire_minutes
+        self.refresh_token_expire_minutes = refresh_token_expire_minutes
+        self.access_token_cookie_name = access_token_cookie_name
+        self.refresh_token_cookie_name = refresh_token_cookie_name
+        self.enable_auth = enable_auth
+        self.port = port
+        self._user_list = []
+        self.super_admin_username = super_admin_username
+        self.super_admin_password = super_admin_password
+        self.guest_username = guest_username
+        self.guest_accessible_tasks = guest_accessible_tasks
+        self._find_user_by_username = find_user_by_username
+
+    @property
+    def default_user(self) -> User:
+        if self.enable_auth:
+            return User(
+                username=self.guest_username,
+                password="",
+                is_guest=True,
+                accessible_tasks=self.guest_accessible_tasks,
+            )
+        return User(
+            username=self.guest_username,
+            password="",
+            is_guest=True,
+            is_super_admin=True,
+        )
+
+    @property
+    def super_admin(self) -> User:
+        return User(
+            username=self.super_admin_username,
+            password=self.super_admin_password,
+            is_super_admin=True,
+        )
+
+    @property
+    def user_list(self) -> list[User]:
+        if not self.enable_auth:
+            return [self.default_user]
+        return self._user_list + [self.super_admin, self.default_user]
+
+    def set_guest_accessible_tasks(self, tasks: list[AnyTask | str]):
+        self.guest_accessible_tasks = tasks
+
+    def set_find_user_by_username(
+        self, find_user_by_username: Callable[[str], User | None]
+    ):
+        self._find_user_by_username = find_user_by_username
+
+    def append_user(self, user: User):
+        duplicates = [
+            existing_user
+            for existing_user in self.user_list
+            if existing_user.username == user.username
+        ]
+        if len(duplicates) > 0:
+            raise ValueError(f"User already exists {user.username}")
+        self._user_list.append(user)
+
+    def find_user_by_username(self, username: str) -> User | None:
+        user = None
+        if self._find_user_by_username is not None:
+            user = self._find_user_by_username(username)
+        if user is None:
+            user = next((u for u in self.user_list if u.username == username), None)
+        return user

zrb/runner/web_config/config_factory.py

@@ -0,0 +1,26 @@
+from zrb.config import (
+    WEB_ACCESS_TOKEN_COOKIE_NAME,
+    WEB_AUTH_ACCESS_TOKEN_EXPIRE_MINUTES,
+    WEB_AUTH_REFRESH_TOKEN_EXPIRE_MINUTES,
+    WEB_ENABLE_AUTH,
+    WEB_GUEST_USERNAME,
+    WEB_HTTP_PORT,
+    WEB_REFRESH_TOKEN_COOKIE_NAME,
+    WEB_SECRET_KEY,
+    WEB_SUPER_ADMIN_PASSWORD,
+    WEB_SUPER_ADMIN_USERNAME,
+)
+from zrb.runner.web_config.config import WebConfig
+
+web_config = WebConfig(
+    port=WEB_HTTP_PORT,
+    secret_key=WEB_SECRET_KEY,
+    access_token_expire_minutes=WEB_AUTH_ACCESS_TOKEN_EXPIRE_MINUTES,
+    refresh_token_expire_minutes=WEB_AUTH_REFRESH_TOKEN_EXPIRE_MINUTES,
+    access_token_cookie_name=WEB_ACCESS_TOKEN_COOKIE_NAME,
+    refresh_token_cookie_name=WEB_REFRESH_TOKEN_COOKIE_NAME,
+    enable_auth=WEB_ENABLE_AUTH,
+    super_admin_username=WEB_SUPER_ADMIN_USERNAME,
+    super_admin_password=WEB_SUPER_ADMIN_PASSWORD,
+    guest_username=WEB_GUEST_USERNAME,
+)

zrb/runner/web_route/docs_route.py

@@ -0,0 +1,17 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # We want fastapi to only be loaded when necessary to decrease footprint
+    from fastapi import FastAPI
+
+
+def serve_docs(app: "FastAPI") -> None:
+    from fastapi.openapi.docs import get_swagger_ui_html
+
+    @app.get("/docs", include_in_schema=False)
+    async def swagger_ui_html():
+        return get_swagger_ui_html(
+            openapi_url="/openapi.json",
+            title="Zrb",
+            swagger_favicon_url="/static/favicon-32x32.png",
+        )

zrb/runner/web_route/error_page/serve_default_404.py

@@ -0,0 +1,28 @@
+from typing import TYPE_CHECKING
+
+from zrb.group.any_group import AnyGroup
+from zrb.runner.web_config.config import WebConfig
+from zrb.runner.web_route.error_page.show_error_page import show_error_page
+from zrb.runner.web_util.user import get_user_from_request
+
+if TYPE_CHECKING:
+    # We want fastapi to only be loaded when necessary to decrease footprint
+    from fastapi import FastAPI
+
+
+def serve_default_404(
+    app: "FastAPI",
+    root_group: AnyGroup,
+    web_config: WebConfig,
+) -> None:
+    from fastapi import Request
+    from fastapi.exception_handlers import http_exception_handler
+    from fastapi.responses import HTMLResponse
+
+    @app.exception_handler(404)
+    async def default_404(request: Request, exc: Exception) -> HTMLResponse:
+        if request.url.path.startswith("/api"):
+            # Re-raise the exception to let FastAPI handle it
+            return await http_exception_handler(request, exc)
+        user = await get_user_from_request(web_config, request)
+        return show_error_page(user, root_group, 404, "Not found")

zrb/runner/web_route/error_page/show_error_page.py

@@ -0,0 +1,28 @@
+import os
+
+from zrb.group.any_group import AnyGroup
+from zrb.runner.web_schema.user import User
+from zrb.runner.web_util.html import get_html_auth_link
+from zrb.util.file import read_file
+from zrb.util.string.format import fstring_format
+
+
+def show_error_page(user: User, root_group: AnyGroup, status_code: int, message: str):
+    from fastapi.responses import HTMLResponse
+
+    _DIR = os.path.dirname(__file__)
+    _VIEW_TEMPLATE = read_file(os.path.join(_DIR, "view.html"))
+    auth_link = get_html_auth_link(user)
+    return HTMLResponse(
+        fstring_format(
+            _VIEW_TEMPLATE,
+            {
+                "name": root_group.name,
+                "description": root_group.description,
+                "auth_link": auth_link,
+                "error_status_code": status_code,
+                "error_message": message,
+            },
+        ),
+        status_code=status_code,
+    )

zrb/runner/web_route/error_page/view.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="color-scheme" content="light dark">
+        <link rel="stylesheet" href="/static/pico.min.css">
+        <link rel="icon" href="/static/favicon-32x32.png" sizes="32x32" type="image/png">
+        <title>Zrb</title>
+        <link rel="stylesheet" href="/static/common.css">
+    </head>
+
+    <body>
+        <header class="container">
+            <hgroup>
+                <h1>{name}</h1>
+                <p>{description}</p>
+                <nav>
+                    <ul>
+                        <li><a href="/">🏠 Home</a></li>
+                        <li><a href="/docs">💻 API Documentation</a></li>
+                    </ul>
+                    <ul>
+                        <li>{auth_link}</li>
+                    </ul>
+                </nav>
+            </hgroup>
+        </header>
+        <main class="container">
+            <article>
+                <h2>{error_status_code}</h2>
+                <p>{error_message}</p>
+            </article>
+        </main>
+    </body>
+    <script src="/refresh-token.js"></script>
+
+</html>

zrb/runner/web_route/home_page/home_page_route.py

@@ -0,0 +1,51 @@
+import os
+from typing import TYPE_CHECKING
+
+from zrb.group.any_group import AnyGroup
+from zrb.runner.web_config.config import WebConfig
+from zrb.runner.web_util.html import (
+    get_html_auth_link,
+    get_html_subgroup_info,
+    get_html_subtask_info,
+)
+from zrb.runner.web_util.user import get_user_from_request
+from zrb.util.file import read_file
+from zrb.util.string.format import fstring_format
+
+if TYPE_CHECKING:
+    # We want fastapi to only be loaded when necessary to decrease footprint
+    from fastapi import FastAPI
+
+
+def serve_home_page(
+    app: "FastAPI",
+    root_group: AnyGroup,
+    web_config: WebConfig,
+) -> None:
+    from fastapi import Request
+    from fastapi.responses import HTMLResponse
+
+    # Serve homepage
+    @app.get("/", response_class=HTMLResponse, include_in_schema=False)
+    @app.get("/ui", response_class=HTMLResponse, include_in_schema=False)
+    @app.get("/ui/", response_class=HTMLResponse, include_in_schema=False)
+    async def home_page_ui(request: Request) -> HTMLResponse:
+
+        _DIR = os.path.dirname(__file__)
+        _VIEW_TEMPLATE = read_file(os.path.join(_DIR, "view.html"))
+        user = await get_user_from_request(web_config, request)
+        group_info = get_html_subgroup_info(user, "/ui/", root_group)
+        task_info = get_html_subtask_info(user, "/ui/", root_group)
+        auth_link = get_html_auth_link(user)
+        return HTMLResponse(
+            fstring_format(
+                _VIEW_TEMPLATE,
+                {
+                    "group_info": group_info,
+                    "task_info": task_info,
+                    "name": root_group.name,
+                    "description": root_group.description,
+                    "auth_link": auth_link,
+                },
+            )
+        )

zrb/runner/web_route/home_page/view.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="color-scheme" content="light dark">
+        <link rel="stylesheet" href="/static/pico.min.css">
+        <link rel="icon" href="/static/favicon-32x32.png" sizes="32x32" type="image/png">
+        <title>Zrb</title>
+        <link rel="stylesheet" href="/static/common.css">
+    </head>
+    <body>
+        <header class="container">
+            <hgroup>
+                <h1>{name}</h1>
+                <p>{description}</p>
+                <nav>
+                    <ul>
+                        <li><a href="/docs">💻 API Documentation</a></li>
+                    </ul>
+                    <ul>
+                        <li>{auth_link}</li>
+                    </ul>
+                </nav>
+            </hgroup>
+        </header>
+        <main class="container">
+                {group_info}
+                {task_info}
+        </main>
+    </body>
+    <script src="/refresh-token.js"></script>
+</html>

zrb/runner/web_route/login_api_route.py

@@ -0,0 +1,31 @@
+from typing import TYPE_CHECKING, Annotated
+
+from zrb.runner.web_config.config import WebConfig
+from zrb.runner.web_util.cookie import set_auth_cookie
+from zrb.runner.web_util.token import generate_tokens_by_credentials
+
+if TYPE_CHECKING:
+    # We want fastapi to only be loaded when necessary to decrease footprint
+    from fastapi import FastAPI
+
+
+def serve_login_api(app: "FastAPI", web_config: WebConfig) -> None:
+    from fastapi import Depends, Response
+    from fastapi.responses import JSONResponse
+    from fastapi.security import OAuth2PasswordRequestForm
+
+    @app.post("/api/v1/login")
+    async def login_api(
+        response: Response, form_data: Annotated[OAuth2PasswordRequestForm, Depends()]
+    ):
+        token = generate_tokens_by_credentials(
+            web_config=web_config,
+            username=form_data.username,
+            password=form_data.password,
+        )
+        if token is None:
+            return JSONResponse(
+                content={"detail": "Incorrect username or password"}, status_code=400
+            )
+        set_auth_cookie(web_config, response, token)
+        return token

zrb/runner/web_route/login_page/login_page_route.py

@@ -0,0 +1,39 @@
+import os
+from typing import TYPE_CHECKING
+
+from zrb.group.any_group import AnyGroup
+from zrb.runner.web_config.config import WebConfig
+from zrb.runner.web_util.html import get_html_auth_link
+from zrb.runner.web_util.user import get_user_from_request
+from zrb.util.file import read_file
+from zrb.util.string.format import fstring_format
+
+if TYPE_CHECKING:
+    # We want fastapi to only be loaded when necessary to decrease footprint
+    from fastapi import FastAPI
+
+
+def serve_login_page(
+    app: "FastAPI",
+    root_group: AnyGroup,
+    web_config: WebConfig,
+) -> None:
+    from fastapi import Request
+    from fastapi.responses import HTMLResponse
+
+    @app.get("/login", response_class=HTMLResponse, include_in_schema=False)
+    async def login(request: Request) -> HTMLResponse:
+        _DIR = os.path.dirname(__file__)
+        _VIEW_TEMPLATE = read_file(os.path.join(_DIR, "view.html"))
+        user = await get_user_from_request(web_config, request)
+        auth_link = get_html_auth_link(user)
+        return HTMLResponse(
+            fstring_format(
+                _VIEW_TEMPLATE,
+                {
+                    "name": root_group.name,
+                    "description": root_group.description,
+                    "auth_link": auth_link,
+                },
+            )
+        )