zrb 1.5.11__py3-none-any.whl → 1.5.12__py3-none-any.whl

zrb/util/codemod/modify_method.py

@@ -6,24 +6,85 @@ from zrb.util.codemod.modification_mode import APPEND, PREPEND, REPLACE
 def replace_method_code(
     original_code: str, class_name: str, method_name: str, new_code: str
 ) -> str:
+    """
+    Replace the entire code body of a specified method within a class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class containing the method.
+        method_name (str): The name of the method to modify.
+        new_code (str): The new code body for the method as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class or method is not found in the code.
+    """
     return _modify_method(original_code, class_name, method_name, new_code, REPLACE)
 
 
 def prepend_code_to_method(
     original_code: str, class_name: str, method_name: str, new_code: str
 ) -> str:
+    """
+    Prepend code to the body of a specified method within a class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class containing the method.
+        method_name (str): The name of the method to modify.
+        new_code (str): The code to prepend as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class or method is not found in the code.
+    """
     return _modify_method(original_code, class_name, method_name, new_code, PREPEND)
 
 
 def append_code_to_method(
     original_code: str, class_name: str, method_name: str, new_code: str
 ) -> str:
+    """
+    Append code to the body of a specified method within a class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class containing the method.
+        method_name (str): The name of the method to modify.
+        new_code (str): The code to append as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class or method is not found in the code.
+    """
     return _modify_method(original_code, class_name, method_name, new_code, APPEND)
 
 
 def _modify_method(
     original_code: str, class_name: str, method_name: str, new_code: str, mode: int
 ) -> str:
+    """
+    Modify the code body of a specified method within a class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class containing the method.
+        method_name (str): The name of the method to modify.
+        new_code (str): The code to add/replace as a string.
+        mode (int): The modification mode (PREPEND, APPEND, or REPLACE).
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class or method is not found in the code.
+    """
     # Parse the original code into a module
     module = cst.parse_module(original_code)
     # Initialize the transformer with the necessary information
@@ -40,7 +101,20 @@ def _modify_method(
 
 
 class _MethodModifier(cst.CSTTransformer):
+    """
+    A LibCST transformer to modify the code body of a method within a ClassDef node.
+    """
+
     def __init__(self, class_name: str, method_name: str, new_code: str, mode: int):
+        """
+        Initialize the transformer.
+
+        Args:
+            class_name (str): The name of the target class.
+            method_name (str): The name of the target method.
+            new_code (str): The new code body as a string.
+            mode (int): The modification mode (PREPEND, APPEND, or REPLACE).
+        """
         self.class_name = class_name
         self.method_name = method_name
         # Use parse_module to handle multiple statements
@@ -52,6 +126,9 @@ class _MethodModifier(cst.CSTTransformer):
     def leave_ClassDef(
         self, original_node: cst.ClassDef, updated_node: cst.ClassDef
     ) -> cst.ClassDef:
+        """
+        Called when leaving a ClassDef node. Modifies the body of the target method.
+        """
         # Check if the class matches the target class
         if original_node.name.value == self.class_name:
             self.class_found = True

zrb/util/codemod/modify_module.py

@@ -1,4 +1,14 @@
 def prepend_code_to_module(original_code: str, new_code: str) -> str:
+    """
+    Prepend code to a module after the last import statement.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        new_code (str): The code to prepend as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+    """
     lines = original_code.splitlines()
     last_import_index = -1
     for i, line in enumerate(lines):

zrb/util/cron.py

@@ -2,7 +2,20 @@ import datetime
 
 
 def parse_cron_field(field: str, min_value: int, max_value: int):
-    """Parse a cron field with support for wildcards (*), ranges, lists, and steps."""
+    """
+    Parse a cron field string into a set of integer values.
+
+    Supports wildcards (*), ranges (e.g., 1-5), lists (e.g., 1,3,5),
+    and step values (e.g., */5, 1-10/2).
+
+    Args:
+        field (str): The cron field string (e.g., "*", "1-5", "*/10").
+        min_value (int): The minimum allowed value for the field.
+        max_value (int): The maximum allowed value for the field.
+
+    Returns:
+        set[int]: A set of integer values represented by the cron field.
+    """
     values = set()
     if field == "*":
         return set(range(min_value, max_value + 1))
@@ -34,7 +47,16 @@ def parse_cron_field(field: str, min_value: int, max_value: int):
 
 
 def handle_special_cron_patterns(pattern: str, dt: datetime.datetime):
-    """Handle special cron patterns like @yearly, @monthly, etc."""
+    """
+    Check if a datetime object matches a special cron pattern.
+
+    Args:
+        pattern (str): The special cron pattern (e.g., "@yearly", "@monthly").
+        dt (datetime.datetime): The datetime object to check.
+
+    Returns:
+        bool: True if the datetime matches the pattern, False otherwise.
+    """
     if pattern == "@yearly" or pattern == "@annually":
         return dt.month == 1 and dt.day == 1 and dt.hour == 0 and dt.minute == 0
     elif pattern == "@monthly":
@@ -53,7 +75,19 @@ def handle_special_cron_patterns(pattern: str, dt: datetime.datetime):
 
 
 def match_cron(cron_pattern: str, dt: datetime.datetime):
-    """Check if a datetime object matches a cron pattern, including special cases."""
+    """
+    Check if a datetime object matches a cron pattern.
+
+    Supports standard cron format (minute hour day month day_of_week)
+    and special patterns (e.g., "@yearly", "@monthly").
+
+    Args:
+        cron_pattern (str): The cron pattern string.
+        dt (datetime.datetime): The datetime object to check.
+
+    Returns:
+        bool: True if the datetime matches the cron pattern, False otherwise.
+    """
     # Handle special cron patterns
     if cron_pattern.startswith("@"):
         return handle_special_cron_patterns(cron_pattern, dt)

zrb/util/file.py

@@ -3,6 +3,15 @@ import re
 
 
 def read_file(file_path: str, replace_map: dict[str, str] = {}) -> str:
+    """Reads a file and optionally replaces content based on a map.
+
+    Args:
+        file_path: The path to the file.
+        replace_map: A dictionary of strings to replace.
+
+    Returns:
+        The content of the file with replacements applied.
+    """
     with open(
         os.path.abspath(os.path.expanduser(file_path)), "r", encoding="utf-8"
     ) as f:
@@ -15,6 +24,15 @@ def read_file(file_path: str, replace_map: dict[str, 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)]
@@ -22,10 +40,24 @@ def read_file_with_line_numbers(
 
 
 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]):
+    """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.
+    """
     if isinstance(content, list):
         content = "\n".join([line for line in content if line is not None])
     dir_path = os.path.dirname(file_path)

zrb/util/git.py

@@ -19,6 +19,21 @@ async def get_diff(
     current_commit: str,
     print_method: Callable[..., Any] = print,
 ) -> DiffResult:
+    """
+    Get the difference between two commits in a Git repository.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        source_commit (str): The source commit hash or reference.
+        current_commit (str): The current commit hash or reference.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Returns:
+        DiffResult: An object containing lists of created, removed, and updated files.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code.
+    """
     cmd_result, exit_code = await run_command(
         cmd=["git", "diff", source_commit, current_commit],
         cwd=repo_dir,
@@ -55,6 +70,18 @@ async def get_diff(
 
 
 async def get_repo_dir(print_method: Callable[..., Any] = print) -> str:
+    """
+    Get the top-level directory of the Git repository.
+
+    Args:
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Returns:
+        str: The absolute path to the repository's top-level directory.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code.
+    """
     cmd_result, exit_code = await run_command(
         cmd=["git", "rev-parse", "--show-toplevel"],
         print_method=print_method,
@@ -67,6 +94,19 @@ async def get_repo_dir(print_method: Callable[..., Any] = print) -> str:
 async def get_current_branch(
     repo_dir: str, print_method: Callable[..., Any] = print
 ) -> str:
+    """
+    Get the current branch name of the Git repository.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Returns:
+        str: The name of the current branch.
+
+    Raises:
+        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"],
         cwd=repo_dir,
@@ -80,6 +120,19 @@ async def get_current_branch(
 async def get_branches(
     repo_dir: str, print_method: Callable[..., Any] = print
 ) -> list[str]:
+    """
+    Get a list of all branches in the Git repository.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Returns:
+        list[str]: A list of branch names.
+
+    Raises:
+        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"],
         cwd=repo_dir,
@@ -95,6 +148,20 @@ async def get_branches(
 async def delete_branch(
     repo_dir: str, branch_name: str, print_method: Callable[..., Any] = print
 ) -> str:
+    """
+    Delete a branch in the Git repository.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        branch_name (str): The name of the branch to delete.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Returns:
+        str: The output of the git command.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code.
+    """
     cmd_result, exit_code = await run_command(
         cmd=["git", "branch", "-D", branch_name],
         cwd=repo_dir,
@@ -106,6 +173,16 @@ async def delete_branch(
 
 
 async def add(repo_dir: str, print_method: Callable[..., Any] = print):
+    """
+    Add all changes to the Git staging area.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code.
+    """
     _, exit_code = await run_command(
         cmd=["git", "add", ".", "-A"],
         cwd=repo_dir,
@@ -118,6 +195,18 @@ async def add(repo_dir: str, print_method: Callable[..., Any] = print):
 async def commit(
     repo_dir: str, message: str, print_method: Callable[..., Any] = print
 ) -> str:
+    """
+    Commit changes in the Git repository.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        message (str): The commit message.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code, unless it's
+            the "nothing to commit" message.
+    """
     cmd_result, exit_code = await run_command(
         cmd=["git", "commit", "-m", message],
         cwd=repo_dir,
@@ -135,6 +224,18 @@ async def commit(
 async def pull(
     repo_dir: str, remote: str, branch: str, print_method: Callable[..., Any] = print
 ) -> str:
+    """
+    Pull changes from a remote repository and branch.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        remote (str): The name of the remote.
+        branch (str): The name of the branch.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code.
+    """
     _, exit_code = await run_command(
         cmd=["git", "pull", remote, branch],
         cwd=repo_dir,
@@ -147,6 +248,18 @@ async def pull(
 async def push(
     repo_dir: str, remote: str, branch: str, print_method: Callable[..., Any] = print
 ) -> str:
+    """
+    Push changes to a remote repository and branch.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        remote (str): The name of the remote.
+        branch (str): The name of the branch.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code.
+    """
     _, exit_code = await run_command(
         cmd=["git", "push", "-u", remote, branch],
         cwd=repo_dir,

zrb/util/git_subtree.py

@@ -19,6 +19,15 @@ class SubTreeConfig(BaseModel):
 
 
 def load_config(repo_dir: str) -> SubTreeConfig:
+    """
+    Load the subtree configuration from subtrees.json.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+
+    Returns:
+        SubTreeConfig: The loaded subtree configuration.
+    """
     file_path = os.path.join(repo_dir, "subtrees.json")
     if not os.path.exists(file_path):
         return SubTreeConfig(data={})
@@ -26,6 +35,13 @@ def load_config(repo_dir: str) -> SubTreeConfig:
 
 
 def save_config(repo_dir: str, config: SubTreeConfig):
+    """
+    Save the subtree configuration to subtrees.json.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        config (SubTreeConfig): The subtree configuration to save.
+    """
     file_path = os.path.join(repo_dir, "subtrees.json")
     write_file(file_path, config.model_dump_json(indent=2))
 
@@ -38,6 +54,22 @@ async def add_subtree(
     prefix: str,
     print_method: Callable[..., Any] = print,
 ):
+    """
+    Add a Git subtree to the repository.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        name (str): The name for the subtree configuration.
+        repo_url (str): The URL of the subtree repository.
+        branch (str): The branch of the subtree repository.
+        prefix (str): The local path where the subtree will be added.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Raises:
+        ValueError: If the prefix directory already exists or subtree config
+            name already exists.
+        Exception: If the git command returns a non-zero exit code.
+    """
     config = load_config()
     if os.path.isdir(prefix):
         raise ValueError(f"Directory exists: {prefix}")
@@ -71,6 +103,19 @@ async def pull_subtree(
     branch: str,
     print_method: Callable[..., Any] = print,
 ):
+    """
+    Pull changes from a Git subtree.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        prefix (str): The local path of the subtree.
+        repo_url (str): The URL of the subtree repository.
+        branch (str): The branch of the subtree repository.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code.
+    """
     _, exit_code = await run_command(
         cmd=[
             "git",
@@ -95,6 +140,19 @@ async def push_subtree(
     branch: str,
     print_method: Callable[..., Any] = print,
 ):
+    """
+    Push changes to a Git subtree.
+
+    Args:
+        repo_dir (str): The path to the Git repository.
+        prefix (str): The local path of the subtree.
+        repo_url (str): The URL of the subtree repository.
+        branch (str): The branch of the subtree repository.
+        print_method (Callable[..., Any]): Method to print command output.
+
+    Raises:
+        Exception: If the git command returns a non-zero exit code.
+    """
     _, exit_code = await run_command(
         cmd=[
             "git",

zrb/util/group.py

@@ -9,6 +9,21 @@ class NodeNotFoundError(ValueError):
 def extract_node_from_args(
     root_group: AnyGroup, args: list[str], web_only: bool = False
 ) -> tuple[AnyGroup | AnyTask, list[str], list[str]]:
+    """
+    Extract a node (Group or Task) from a list of command-line arguments.
+
+    Args:
+        root_group (AnyGroup): The root group to start the search from.
+        args (list[str]): The list of command-line arguments.
+        web_only (bool): If True, only consider tasks that are not CLI-only.
+
+    Returns:
+        tuple[AnyGroup | AnyTask, list[str], list[str]]: A tuple containing the
+            extracted node, the path to the node, and any residual arguments.
+
+    Raises:
+        NodeNotFoundError: If no matching task or group is found for a given argument.
+    """
     node = root_group
     node_path = []
     residual_args = []
@@ -17,8 +32,12 @@ def extract_node_from_args(
         if web_only and task is not None and task.cli_only:
             task = None
         group = node.get_group_by_alias(name)
-        if group is not None and len(get_all_subtasks(group, web_only)) == 0:
-            # If group doesn't contain any task, then ignore its existence
+        # Only ignore empty groups if web_only is True
+        if (
+            group is not None
+            and web_only
+            and len(get_all_subtasks(group, web_only)) == 0
+        ):
             group = None
         if task is None and group is None:
             raise NodeNotFoundError(
@@ -40,8 +59,21 @@ def extract_node_from_args(
 
 
 def get_node_path(group: AnyGroup, node: AnyGroup | AnyTask) -> list[str] | None:
+    """
+    Get the path (aliases) to a specific node within a group hierarchy.
+
+    Args:
+        group (AnyGroup): The group to search within.
+        node (AnyGroup | AnyTask): The target node.
+
+    Returns:
+        list[str] | None: A list of aliases representing the path to the node,
+            or None if the node is not found.
+    """
     if group is None:
         return []
+    if group == node:  # Handle the case where the target is the starting group
+        return [group.name]
     if isinstance(node, AnyTask):
         for alias, subtask in group.subtasks.items():
             if subtask == node:
@@ -60,6 +92,16 @@ def get_node_path(group: AnyGroup, node: AnyGroup | AnyTask) -> list[str] | None
 def get_non_empty_subgroups(
     group: AnyGroup, web_only: bool = False
 ) -> dict[str, AnyGroup]:
+    """
+    Get subgroups that contain at least one task.
+
+    Args:
+        group (AnyGroup): The group to search within.
+        web_only (bool): If True, only consider tasks that are not CLI-only.
+
+    Returns:
+        dict[str, AnyGroup]: A dictionary of subgroups that are not empty.
+    """
     return {
         alias: subgroup
         for alias, subgroup in group.subgroups.items()
@@ -68,6 +110,16 @@ def get_non_empty_subgroups(
 
 
 def get_subtasks(group: AnyGroup, web_only: bool = False) -> dict[str, AnyTask]:
+    """
+    Get the direct subtasks of a group.
+
+    Args:
+        group (AnyGroup): The group to search within.
+        web_only (bool): If True, only include tasks that are not CLI-only.
+
+    Returns:
+        dict[str, AnyTask]: A dictionary of subtasks.
+    """
     return {
         alias: subtask
         for alias, subtask in group.subtasks.items()
@@ -76,6 +128,16 @@ def get_subtasks(group: AnyGroup, web_only: bool = False) -> dict[str, AnyTask]:
 
 
 def get_all_subtasks(group: AnyGroup, web_only: bool = False) -> list[AnyTask]:
+    """
+    Get all subtasks (including nested ones) within a group hierarchy.
+
+    Args:
+        group (AnyGroup): The group to search within.
+        web_only (bool): If True, only include tasks that are not CLI-only.
+
+    Returns:
+        list[AnyTask]: A list of all subtasks.
+    """
     subtasks = [
         subtask
         for subtask in group.subtasks.values()

zrb/util/load.py

@@ -11,6 +11,17 @@ pattern = re.compile("[^a-zA-Z0-9]")
 
 @lru_cache
 def load_file(script_path: str, sys_path_index: int = 0) -> Any | None:
+    """
+    Load a Python module from a file path.
+
+    Args:
+        script_path (str): The path to the Python script.
+        sys_path_index (int): The index to insert the script directory into sys.path.
+
+    Returns:
+        Any | None: The loaded module object, or None if the file does not
+            exist or cannot be loaded.
+    """
     if not os.path.isfile(script_path):
         return None
     module_name = pattern.sub("", script_path)
@@ -31,6 +42,15 @@ def load_file(script_path: str, sys_path_index: int = 0) -> Any | None:
 
 
 def _get_new_python_path(dir_path: str) -> str:
+    """
+    Helper function to update the PYTHONPATH environment variable.
+
+    Args:
+        dir_path (str): The directory path to add to PYTHONPATH.
+
+    Returns:
+        str: The new value for the PYTHONPATH environment variable.
+    """
     current_python_path = os.getenv("PYTHONPATH")
     if current_python_path is None or current_python_path == "":
         return dir_path
@@ -40,5 +60,14 @@ def _get_new_python_path(dir_path: str) -> str:
 
 
 def load_module(module_name: str) -> Any:
+    """
+    Load a Python module by its name.
+
+    Args:
+        module_name (str): The name of the module to load.
+
+    Returns:
+        Any: The loaded module object.
+    """
     module = importlib.import_module(module_name)
     return module

zrb/util/run.py

@@ -4,6 +4,15 @@ 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.
+
+    Args:
+        value (Any): The value to run. Can be awaitable or not.
+
+    Returns:
+        Any: The result of the awaited value or the value itself if not awaitable.
+    """
     if inspect.isawaitable(value):
         return await value
     return await asyncio.to_thread(lambda: value)