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

zrb/util/attr.py

@@ -9,52 +9,59 @@ from zrb.attr.type import (
     StrDictAttr,
     StrListAttr,
 )
+from zrb.context.any_context import AnyContext
 from zrb.context.any_shared_context import AnySharedContext
 from zrb.util.string.conversion import to_boolean
 
 
 def get_str_list_attr(
-    shared_ctx: AnySharedContext, attr: StrListAttr | None, auto_render: bool = True
+    ctx: AnyContext | AnySharedContext,
+    attr: StrListAttr | None,
+    auto_render: bool = True,
 ) -> list[str]:
     """
     Retrieve a list of strings from shared context attributes.
 
     Args:
-        shared_ctx (AnySharedContext): The shared context object.
+        ctx (AnyContext): The shared context object.
         attr (StrListAttr | None): The string list attribute to retrieve.
         auto_render (bool): Whether to auto-render the attribute values.
 
     Returns:
         list[str]: A list of string attributes.
     """
+    if attr is None:
+        return []
     if callable(attr):
-        return attr(shared_ctx)
-    return {get_str_attr(shared_ctx, val, "", auto_render) for val in attr}
+        return attr(ctx)
+    return [get_str_attr(ctx, val, "", auto_render) for val in attr]
 
 
 def get_str_dict_attr(
-    shared_ctx: AnySharedContext, attr: StrDictAttr | None, auto_render: bool = True
+    ctx: AnyContext | AnySharedContext,
+    attr: StrDictAttr | None,
+    auto_render: bool = True,
 ) -> dict[str, Any]:
     """
     Retrieve a dictionary of strings from shared context attributes.
 
     Args:
-        shared_ctx (AnySharedContext): The shared context object.
+        ctx (AnyContext): The shared context object.
         attr (StrDictAttr | None): The string dictionary attribute to retrieve.
         auto_render (bool): Whether to auto-render the attribute values.
 
     Returns:
         dict[str, Any]: A dictionary of string attributes.
     """
+    if attr is None:
+        return {}
     if callable(attr):
-        return attr(shared_ctx)
-    return {
-        key: get_str_attr(shared_ctx, val, "", auto_render) for key, val in attr.items()
-    }
+        return attr(ctx)
+    return {key: get_str_attr(ctx, val, "", auto_render) for key, val in attr.items()}
 
 
 def get_str_attr(
-    shared_ctx: AnySharedContext,
+    ctx: AnyContext | AnySharedContext,
     attr: StrAttr | None,
     default: StrAttr = "",
     auto_render: bool = True,
@@ -63,7 +70,7 @@ def get_str_attr(
     Retrieve a string from shared context attributes.
 
     Args:
-        shared_ctx (AnySharedContext): The shared context object.
+        ctx (AnyContext): The shared context object.
         attr (StrAttr | None): The string attribute to retrieve.
         default (StrAttr): The default value if the attribute is None.
         auto_render (bool): Whether to auto-render the attribute value.
@@ -71,14 +78,16 @@ def get_str_attr(
     Returns:
         str: The string attribute value.
     """
-    val = get_attr(shared_ctx, attr, default, auto_render)
-    if not isinstance(val, str):
-        return str(val)
-    return val
+    val = get_attr(ctx, attr, default, auto_render)
+    if isinstance(val, str):
+        return val
+    if val is None:
+        return ""
+    return str(val)
 
 
 def get_bool_attr(
-    shared_ctx: AnySharedContext,
+    ctx: AnyContext | AnySharedContext,
     attr: BoolAttr | None,
     default: BoolAttr = False,
     auto_render: bool = True,
@@ -87,7 +96,7 @@ def get_bool_attr(
     Retrieve a boolean from shared context attributes.
 
     Args:
-        shared_ctx (AnySharedContext): The shared context object.
+        ctx (AnyContext): The shared context object.
         attr (BoolAttr | None): The boolean attribute to retrieve.
         default (BoolAttr): The default value if the attribute is None.
         auto_render (bool): Whether to auto-render the attribute value if it's a string.
@@ -95,14 +104,16 @@ def get_bool_attr(
     Returns:
         bool: The boolean attribute value.
     """
-    val = get_attr(shared_ctx, attr, default, auto_render)
-    if isinstance(val, str):
-        return to_boolean(val)
-    return val
+    val = get_attr(ctx, attr, default, auto_render)
+    if isinstance(val, bool):
+        return val
+    if val is None:
+        return False
+    return to_boolean(val)
 
 
 def get_int_attr(
-    shared_ctx: AnySharedContext,
+    ctx: AnyContext | AnySharedContext,
     attr: IntAttr | None,
     default: IntAttr = 0,
     auto_render: bool = True,
@@ -111,7 +122,7 @@ def get_int_attr(
     Retrieve an integer from shared context attributes.
 
     Args:
-        shared_ctx (AnySharedContext): The shared context object.
+        ctx (AnyContext): The shared context object.
         attr (IntAttr | None): The integer attribute to retrieve.
         default (IntAttr): The default value if the attribute is None.
         auto_render (bool): Whether to auto-render the attribute value if it's a string.
@@ -119,14 +130,16 @@ def get_int_attr(
     Returns:
         int: The integer attribute value.
     """
-    val = get_attr(shared_ctx, attr, default, auto_render)
-    if isinstance(val, str):
-        return int(val)
-    return val
+    val = get_attr(ctx, attr, default, auto_render)
+    if isinstance(val, int):
+        return val
+    if val is None:
+        return 0
+    return int(val)
 
 
 def get_float_attr(
-    shared_ctx: AnySharedContext,
+    ctx: AnyContext | AnySharedContext,
     attr: FloatAttr | None,
     default: FloatAttr = 0.0,
     auto_render: bool = True,
@@ -135,7 +148,7 @@ def get_float_attr(
     Retrieve a float from shared context attributes.
 
     Args:
-        shared_ctx (AnySharedContext): The shared context object.
+        ctx (AnyContext): The shared context object.
         attr (FloatAttr | None): The float attribute to retrieve.
         default (FloatAttr): The default value if the attribute is None.
         auto_render (bool): Whether to auto-render the attribute value if it's a string.
@@ -143,14 +156,16 @@ def get_float_attr(
     Returns:
         float | None: The float attribute value.
     """
-    val = get_attr(shared_ctx, attr, default, auto_render)
-    if isinstance(val, str):
-        return float(val)
-    return val
+    val = get_attr(ctx, attr, default, auto_render)
+    if isinstance(val, (int, float)):
+        return val
+    if val is None:
+        return 0.0
+    return float(val)
 
 
 def get_attr(
-    shared_ctx: AnySharedContext,
+    ctx: AnyContext | AnySharedContext,
     attr: AnyAttr,
     default: AnyAttr,
     auto_render: bool = True,
@@ -159,7 +174,7 @@ def get_attr(
     Retrieve an attribute value from shared context, handling callables and rendering.
 
     Args:
-        shared_ctx (AnySharedContext): The shared context object.
+        ctx (AnyContext): The shared context object.
         attr (AnyAttr): The attribute to retrieve. Can be a value, a callable,
             or a string to render.
         default (AnyAttr): The default value if the attribute is None.
@@ -170,10 +185,10 @@ def get_attr(
     """
     if attr is None:
         if callable(default):
-            return default(shared_ctx)
+            return default(ctx)
         return default
     if callable(attr):
-        return attr(shared_ctx)
+        return attr(ctx)
     if isinstance(attr, str) and auto_render:
-        return shared_ctx.render(attr)
+        return ctx.render(attr)
     return attr

zrb/util/cli/markdown.py

@@ -0,0 +1,32 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rich.theme import Theme
+
+
+def render_markdown(
+    markdown_text: str, width: int | None = None, theme: "Theme | None" = None
+) -> str:
+    """
+    Renders Markdown to a string, ensuring link URLs are visible.
+    """
+    from rich.console import Console
+    from rich.markdown import Markdown
+    from rich.theme import Theme
+
+    if theme is None:
+        theme = Theme(
+            {
+                "markdown.link": "bold bright_cyan underline",
+                "markdown.link_url": "italic bright_cyan underline",
+                # Optional: You can customize headers or code blocks here too
+                "markdown.h1": "bold magenta",
+                "markdown.code": "bold white on #333333",
+            }
+        )
+
+    console = Console(width=width, theme=theme, force_terminal=True)
+    markdown = Markdown(markdown_text, hyperlinks=False)
+    with console.capture() as capture:
+        console.print(markdown)
+    return capture.get()

zrb/util/cli/text.py

@@ -0,0 +1,30 @@
+import os
+import subprocess
+import tempfile
+
+from zrb.util.file import read_file
+
+
+def edit_text(
+    prompt_message: str,
+    value: str,
+    editor: str = "vi",
+    extension: str = ".txt",
+) -> str:
+    with tempfile.NamedTemporaryFile(delete=False, suffix=extension) as temp_file:
+        temp_file_name = temp_file.name
+        if prompt_message.strip() != "":
+            prompt_message_eol = f"{prompt_message}\n"
+            temp_file.write(prompt_message_eol.encode())
+        # Pre-fill with default content
+        if value:
+            temp_file.write(value.encode())
+        temp_file.flush()
+        subprocess.call([editor, temp_file_name])
+        # Read the edited content
+        edited_content = read_file(temp_file_name)
+    if prompt_message.strip() != "":
+        parts = [text.strip() for text in edited_content.split(prompt_message, 1)]
+        edited_content = "\n".join(parts).lstrip()
+    os.remove(temp_file_name)
+    return edited_content

zrb/util/cmd/command.py

@@ -5,7 +5,7 @@ import signal
 import sys
 from collections import deque
 from collections.abc import Callable
-from typing import TextIO
+from typing import Any, TextIO
 
 import psutil
 
@@ -62,6 +62,8 @@ async def run_command(
     register_pid_method: Callable[[int], None] | None = None,
     max_output_line: int = 1000,
     max_error_line: int = 1000,
+    max_display_line: int | None = None,
+    timeout: int = 3600,
     is_interactive: bool = False,
 ) -> tuple[CmdResult, int]:
     """
@@ -77,6 +79,8 @@ async def run_command(
     actual_print_method = print_method if print_method is not None else print
     if cwd is None:
         cwd = os.getcwd()
+    if max_display_line is None:
+        max_display_line = max(max_output_line, max_error_line)
     # While environment variables alone weren't the fix, they are still
     # good practice for encouraging simpler output from tools.
     child_env = (env_map or os.environ).copy()
@@ -95,17 +99,33 @@ async def run_command(
     if register_pid_method is not None:
         register_pid_method(cmd_process.pid)
     # Use the new, simple, and correct stream reader.
+    display_lines = deque(maxlen=max_display_line if max_display_line > 0 else 0)
     stdout_task = asyncio.create_task(
-        __read_stream(cmd_process.stdout, actual_print_method, max_output_line)
+        __read_stream(
+            cmd_process.stdout, actual_print_method, max_output_line, display_lines
+        )
     )
     stderr_task = asyncio.create_task(
-        __read_stream(cmd_process.stderr, actual_print_method, max_error_line)
+        __read_stream(
+            cmd_process.stderr, actual_print_method, max_error_line, display_lines
+        )
+    )
+    timeout_task = (
+        asyncio.create_task(asyncio.sleep(timeout)) if timeout and timeout > 0 else None
     )
     try:
-        return_code = await cmd_process.wait()
+        wait_task = asyncio.create_task(cmd_process.wait())
+        done, pending = await asyncio.wait(
+            {wait_task, timeout_task} if timeout_task else {wait_task},
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+        if timeout_task and timeout_task in done:
+            raise asyncio.TimeoutError()
+        return_code = wait_task.result()
         stdout, stderr = await asyncio.gather(stdout_task, stderr_task)
-        return CmdResult(stdout, stderr), return_code
-    except (KeyboardInterrupt, asyncio.CancelledError):
+        display = "\r\n".join(display_lines)
+        return CmdResult(stdout, stderr, display=display), return_code
+    except (KeyboardInterrupt, asyncio.CancelledError, asyncio.TimeoutError):
         try:
             os.killpg(cmd_process.pid, signal.SIGINT)
             await asyncio.wait_for(cmd_process.wait(), timeout=2.0)
@@ -133,13 +153,14 @@ def __get_cmd_stdin(is_interactive: bool) -> int | TextIO:
 async def __read_stream(
     stream: asyncio.StreamReader,
     print_method: Callable[..., None],
-    max_lines: int,
+    max_line: int,
+    display_queue: deque[Any],
 ) -> str:
     """
     Reads from the stream using the robust `readline()` and correctly
     interprets carriage returns (`\r`) as distinct print events.
     """
-    captured_lines = deque(maxlen=max_lines if max_lines > 0 else 0)
+    captured_lines = deque(maxlen=max_line if max_line > 0 else 0)
     while True:
         try:
             line_bytes = await stream.readline()
@@ -149,8 +170,9 @@ async def __read_stream(
             # Safety valve for the memory limit.
             error_msg = "[ERROR] A single line of output was too long to process."
             print_method(error_msg)
-            if max_lines > 0:
+            if max_line > 0:
                 captured_lines.append(error_msg)
+                display_queue.append(error_msg)
             break
         except (KeyboardInterrupt, asyncio.CancelledError):
             raise
@@ -165,8 +187,9 @@ async def __read_stream(
                     print_method(clean_part, end="\r\n")
                 except Exception:
                     print_method(clean_part)
-                if max_lines > 0:
+                if max_line > 0:
                     captured_lines.append(clean_part)
+                    display_queue.append(clean_part)
     return "\r\n".join(captured_lines)
 
 

zrb/util/file.py

@@ -1,5 +1,7 @@
+import fnmatch
 import os
 import re
+from typing import Literal
 
 
 def read_file(file_path: str, replace_map: dict[str, str] = {}) -> str:
@@ -48,46 +50,22 @@ def _read_pdf_file_content(file_path: str) -> str:
         )
 
 
-def read_file_with_line_numbers(
-    file_path: str, replace_map: dict[str, str] = {}
-) -> str:
-    """Reads a file and returns content with line numbers.
-
-    Args:
-        file_path: The path to the file.
-        replace_map: A dictionary of strings to replace.
-
-    Returns:
-        The content of the file with line numbers and replacements applied.
-    """
-    content = read_file(file_path, replace_map)
-    lines = content.splitlines()
-    numbered_lines = [f"{i + 1} | {line}" for i, line in enumerate(lines)]
-    return "\n".join(numbered_lines)
-
-
-def read_dir(dir_path: str) -> list[str]:
-    """Reads a directory and returns a list of file names.
-
-    Args:
-        dir_path: The path to the directory.
-
-    Returns:
-        A list of file names in the directory.
-    """
-    return [f for f in os.listdir(os.path.abspath(os.path.expanduser(dir_path)))]
-
-
-def write_file(file_path: str, content: str | list[str]):
+def write_file(
+    file_path: str,
+    content: str | list[str],
+    mode: Literal["w", "wt", "tw", "a", "at", "ta", "x", "xt", "tx"] = "w",
+):
     """Writes content to a file.
 
     Args:
         file_path: The path to the file.
         content: The content to write, either a string or a list of strings.
+        mode: Writing mode (by default "w")
     """
     if isinstance(content, list):
         content = "\n".join([line for line in content if line is not None])
-    dir_path = os.path.dirname(file_path)
+    abs_file_path = os.path.abspath(os.path.expanduser(file_path))
+    dir_path = os.path.dirname(abs_file_path)
     os.makedirs(dir_path, exist_ok=True)
     should_add_eol = content.endswith("\n")
     # Remove trailing newlines, but keep one if the file originally ended up with newline
@@ -95,5 +73,55 @@ def write_file(file_path: str, content: str | list[str]):
     content = content.rstrip("\n")
     if should_add_eol:
         content += "\n"
-    with open(os.path.abspath(os.path.expanduser(file_path)), "w") as f:
+    with open(abs_file_path, mode) as f:
         f.write(content)
+
+
+def list_files(
+    path: str = ".",
+    include_hidden: bool = False,
+    depth: int = 3,
+    excluded_patterns: list[str] = [],
+) -> list[str]:
+    all_files: list[str] = []
+    abs_path = os.path.abspath(os.path.expanduser(path))
+    if not os.path.exists(abs_path):
+        raise FileNotFoundError(f"Path does not exist: {path}")
+
+    patterns_to_exclude = excluded_patterns
+    if depth <= 0:
+        depth = 1
+
+    initial_depth = abs_path.rstrip(os.sep).count(os.sep)
+    for root, dirs, files in os.walk(abs_path, topdown=True):
+        current_depth = root.rstrip(os.sep).count(os.sep) - initial_depth
+        if current_depth >= depth - 1:
+            del dirs[:]
+
+        dirs[:] = [
+            d
+            for d in dirs
+            if (include_hidden or not d.startswith("."))
+            and not _is_excluded(d, patterns_to_exclude)
+        ]
+
+        for filename in files:
+            if (include_hidden or not filename.startswith(".")) and not _is_excluded(
+                filename, patterns_to_exclude
+            ):
+                full_path = os.path.join(root, filename)
+                rel_full_path = os.path.relpath(full_path, abs_path)
+                if not _is_excluded(rel_full_path, patterns_to_exclude):
+                    all_files.append(rel_full_path)
+    return sorted(all_files)
+
+
+def _is_excluded(name: str, patterns: list[str]) -> bool:
+    for pattern in patterns:
+        if fnmatch.fnmatch(name, pattern):
+            return True
+        parts = name.split(os.path.sep)
+        for part in parts:
+            if fnmatch.fnmatch(part, pattern):
+                return True
+    return False

zrb/util/git.py

@@ -131,7 +131,7 @@ async def get_branches(
         Exception: If the git command returns a non-zero exit code.
     """
     cmd_result, exit_code = await run_command(
-        cmd=["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        cmd=["git", "branch"],
         cwd=repo_dir,
         print_method=print_method,
     )
@@ -160,7 +160,7 @@ async def delete_branch(
         Exception: If the git command returns a non-zero exit code.
     """
     cmd_result, exit_code = await run_command(
-        cmd=["git", "branch", "-D", branch_name],
+        cmd=["git", "branch", "-d", branch_name],
         cwd=repo_dir,
         print_method=print_method,
     )

zrb/util/{llm/prompt.py → markdown.py}

@@ -8,7 +8,6 @@ def _adjust_markdown_headers(md: str, level_change: int) -> str:
     for line in lines:
         stripped_line = line.strip()
         fence_match = re.match(r"^([`~]{3,})", stripped_line)
-
         if fence_match:
             current_fence = fence_match.group(1)
             if (
@@ -31,7 +30,7 @@ def _adjust_markdown_headers(md: str, level_change: int) -> str:
                 new_lines.append(new_header)
             else:
                 new_lines.append(line)
-    return "\n".join(new_lines)
+    return "\n".join(new_lines).rstrip()
 
 
 def demote_markdown_headers(md: str) -> str:
@@ -42,7 +41,7 @@ def promote_markdown_headers(md: str) -> str:
     return _adjust_markdown_headers(md, level_change=-1)
 
 
-def make_prompt_section(header: str, content: str, as_code: bool = False) -> str:
+def make_markdown_section(header: str, content: str, as_code: bool = False) -> str:
     if content.strip() == "":
         return ""
     if as_code:

zrb/util/match.py

@@ -0,0 +1,78 @@
+import os
+import re
+
+
+def fuzzy_match(text: str, pattern: str) -> tuple[bool, float]:
+    """
+    Match text against a pattern using a fuzzy search algorithm similar to VSCode's Ctrl+P.
+
+    The pattern is split into tokens by whitespace and path separators.
+    Each token must be found in the text (in order).
+
+    Args:
+        text: The string to search in.
+        pattern: The search pattern (e.g., "src main" or "util/io").
+
+    Returns:
+        A tuple (matched, score).
+        - matched: True if the pattern matches the text.
+        - score: A float representing the match quality (lower is better).
+    """
+    text_cmp = text.lower()
+    # Normalize pattern -> tokens split on path separators or whitespace
+    search_pattern = pattern.strip()
+    tokens = (
+        [t for t in re.split(rf"[{re.escape(os.path.sep)}\s]+", search_pattern) if t]
+        if search_pattern
+        else []
+    )
+    tokens = [t.lower() for t in tokens]
+    if not tokens:
+        return True, 0.0
+    last_pos = 0
+    score = 0.0
+    for token in tokens:
+        # try contiguous substring search first
+        idx = text_cmp.find(token, last_pos)
+        if idx != -1:
+            # good match: reward contiguous early matches
+            score += idx  # smaller idx preferred
+            last_pos = idx + len(token)
+        else:
+            # fallback to subsequence matching
+            res = _find_subsequence_range(text_cmp, token, last_pos)
+            if res is None:
+                return False, 0.0
+
+            pos, end_pos = res
+
+            # subsequence match is less preferred than contiguous substring
+            score += pos + 0.5 * len(token)
+            last_pos = end_pos
+    # prefer shorter texts when score ties, so include length as tiebreaker
+    score += 0.01 * len(text)
+    return True, score
+
+
+def _find_subsequence_range(
+    hay: str, needle: str, start: int = 0
+) -> tuple[int, int] | None:
+    """
+    Try to locate needle in hay as a subsequence starting at `start`.
+    Returns (start_index, end_index) where end_index is the index AFTER the last matched character.
+    """
+    if not needle:
+        return start, start
+    i = start
+    j = 0
+    first_pos = None
+    while i < len(hay) and j < len(needle):
+        if hay[i] == needle[j]:
+            if first_pos is None:
+                first_pos = i
+            j += 1
+        i += 1
+
+    if j == len(needle):
+        return first_pos, i
+    return None

zrb/util/run.py

@@ -5,7 +5,7 @@ from typing import Any
 
 async def run_async(value: Any) -> Any:
     """
-    Run a value asynchronously, awaiting if it's awaitable or running in a thread if not.
+    Run a value asynchronously, awaiting if it's awaitable or returning it directly.
 
     Args:
         value (Any): The value to run. Can be awaitable or not.
@@ -14,7 +14,7 @@ async def run_async(value: Any) -> Any:
         Any: The result of the awaited value or the value itself if not awaitable.
     """
     if isinstance(value, asyncio.Task):
-        return value
+        return await value
     if inspect.isawaitable(value):
         return await value
-    return await asyncio.to_thread(lambda: value)
+    return value

zrb/util/string/conversion.py

@@ -1,7 +1,7 @@
 import re
 
 NON_ALPHA_NUM = re.compile(r"[^a-zA-Z0-9]+")
-TRUE_STRS = ["true", "1", "yes", "y", "active", "on"]
+TRUE_STRS = ["true", "1", "yes", "y", "active", "on", "okay", "ok"]
 FALSE_STRS = ["false", "0", "no", "n", "inactive", "off"]
 
 

zrb/util/truncate.py

@@ -0,0 +1,23 @@
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def truncate_str(value: Any, limit: int):
+    # If value is a string, truncate
+    if isinstance(value, str):
+        if len(value) > limit:
+            if limit < 4:
+                return value[:limit]
+            return value[: limit - 4] + " ..."
+    # If value is a dict, process recursively
+    elif isinstance(value, Mapping):
+        return {k: truncate_str(v, limit) for k, v in value.items()}
+    # If value is a list or tuple, process recursively preserving type
+    elif isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        t = type(value)
+        return t(truncate_str(v, limit) for v in value)
+    # If value is a set, process recursively preserving type
+    elif isinstance(value, set):
+        return {truncate_str(v, limit) for v in value}
+    # Other types are returned unchanged
+    return value