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

zrb/util/cmd/remote.py

@@ -10,6 +10,21 @@ def get_remote_cmd_script(
     use_password: bool = False,
     ssh_key: str = "",
 ) -> str:
+    """
+    Generate an SSH command script to execute a command on a remote host.
+
+    Args:
+        cmd_script (str): The command script to execute on the remote host.
+        host (str): The remote host address.
+        port (int | str): The SSH port.
+        user (str): The SSH user.
+        password (str): The SSH password (used with sshpass if use_password is True).
+        use_password (bool): Whether to use password authentication with sshpass.
+        ssh_key (str): The path to the SSH private key file.
+
+    Returns:
+        str: The generated SSH command script.
+    """
     quoted_script = shlex.quote(cmd_script)
     if ssh_key != "" and use_password:
         return f'sshpass -p "{password}" ssh -t -p "{port}" -i "{ssh_key}" "{user}@{host}" {quoted_script}'  # noqa

zrb/util/codemod/modification_mode.py

@@ -1,3 +1,7 @@
+"""
+Defines constants representing different modification modes for codemod operations.
+"""
+
 PREPEND = 0
 APPEND = 1
 REPLACE = 2

zrb/util/codemod/modify_class.py

@@ -4,18 +4,75 @@ from zrb.util.codemod.modification_mode import APPEND, PREPEND, REPLACE
 
 
 def replace_class_code(original_code: str, class_name: str, new_code: str) -> str:
+    """
+    Replace the entire code body of a specified class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class to modify.
+        new_code (str): The new code body for the class as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class is not found in the code.
+    """
     return _modify_code(original_code, class_name, new_code, REPLACE)
 
 
 def prepend_code_to_class(original_code: str, class_name: str, new_code: str) -> str:
+    """
+    Prepend code to the body of a specified class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class 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 is not found in the code.
+    """
     return _modify_code(original_code, class_name, new_code, PREPEND)
 
 
 def append_code_to_class(original_code: str, class_name: str, new_code: str) -> str:
+    """
+    Append code to the body of a specified class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class 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 is not found in the code.
+    """
     return _modify_code(original_code, class_name, new_code, APPEND)
 
 
 def _modify_code(original_code: str, class_name: str, new_code: str, mode: int) -> str:
+    """
+    Modify the code body of a specified class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class 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 is not found in the code.
+    """
     # Parse the original code into a module
     module = cst.parse_module(original_code)
     # Initialize transformer with the class name and method code
@@ -30,7 +87,19 @@ def _modify_code(original_code: str, class_name: str, new_code: str, mode: int)
 
 
 class _ClassCodeModifier(cst.CSTTransformer):
+    """
+    A LibCST transformer to modify the code body of a ClassDef node.
+    """
+
     def __init__(self, class_name: str, new_code: str, mode: int):
+        """
+        Initialize the transformer.
+
+        Args:
+            class_name (str): The name of the target class.
+            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.new_code = cst.parse_module(new_code).body
         self.class_found = False
@@ -39,6 +108,9 @@ class _ClassCodeModifier(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 class.
+        """
         # Check if this is the target class
         if original_node.name.value == self.class_name:
             self.class_found = True

zrb/util/codemod/modify_class_parent.py

@@ -6,24 +6,81 @@ from zrb.util.codemod.modification_mode import APPEND, PREPEND, REPLACE
 def replace_parent_class(
     original_code: str, class_name: str, parent_class_name: str
 ) -> str:
+    """
+    Replace the parent class of a specified class in the provided code.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class to modify.
+        parent_class_name (str): The new parent class name.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class is not found in the code.
+    """
     return _modify_parent_class(original_code, class_name, parent_class_name, REPLACE)
 
 
 def append_parent_class(
     original_code: str, class_name: str, parent_class_name: str
 ) -> str:
+    """
+    Append a parent class to a specified class in the provided code.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class to modify.
+        parent_class_name (str): The parent class name to append.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class is not found in the code.
+    """
     return _modify_parent_class(original_code, class_name, parent_class_name, APPEND)
 
 
 def prepend_parent_class(
     original_code: str, class_name: str, parent_class_name: str
 ) -> str:
+    """
+    Prepend a parent class to a specified class in the provided code.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class to modify.
+        parent_class_name (str): The parent class name to prepend.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class is not found in the code.
+    """
     return _modify_parent_class(original_code, class_name, parent_class_name, PREPEND)
 
 
 def _modify_parent_class(
     original_code: str, class_name: str, parent_class_name: str, mode: int
 ) -> str:
+    """
+    Modify the parent class(es) of a specified class in the provided code.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class to modify.
+        parent_class_name (str): The parent class name to add/replace.
+        mode (int): The modification mode (PREPEND, APPEND, or REPLACE).
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class is not found in the code.
+    """
     # Parse the original code into a module
     module = cst.parse_module(original_code)
     # Initialize transformer with the class name and parent class name
@@ -39,6 +96,14 @@ def _modify_parent_class(
 
 class _ParentClassAdder(cst.CSTTransformer):
     def __init__(self, class_name: str, parent_class_name: str, mode: int):
+        """
+        Initialize the transformer.
+
+        Args:
+            class_name (str): The name of the target class.
+            parent_class_name (str): The name of the parent class to add/replace.
+            mode (int): The modification mode (PREPEND, APPEND, or REPLACE).
+        """
         self.class_name = class_name
         self.parent_class_name = parent_class_name
         self.class_found = False
@@ -47,6 +112,9 @@ class _ParentClassAdder(cst.CSTTransformer):
     def leave_ClassDef(
         self, original_node: cst.ClassDef, updated_node: cst.ClassDef
     ) -> cst.ClassDef:
+        """
+        Called when leaving a ClassDef node. Modifies the bases of the target class.
+        """
         # Check if this is the target class
         if original_node.name.value == self.class_name:
             self.class_found = True

zrb/util/codemod/modify_class_property.py

@@ -10,6 +10,22 @@ def append_property_to_class(
     annotation: str,
     default_value: str,
 ) -> str:
+    """
+    Append a property with type annotation and default value to a specified class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class to modify.
+        property_name (str): The name of the property to add.
+        annotation (str): The type annotation for the property as a string.
+        default_value (str): The default value for the property as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class is not found in the code.
+    """
     return _modify_class_property(
         original_code, class_name, property_name, annotation, default_value, APPEND
     )
@@ -22,6 +38,22 @@ def prepend_property_to_class(
     annotation: str,
     default_value: str,
 ) -> str:
+    """
+    Prepend a property with type annotation and default value to a specified class.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class to modify.
+        property_name (str): The name of the property to add.
+        annotation (str): The type annotation for the property as a string.
+        default_value (str): The default value for the property as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class is not found in the code.
+    """
     return _modify_class_property(
         original_code, class_name, property_name, annotation, default_value, PREPEND
     )
@@ -35,6 +67,23 @@ def _modify_class_property(
     default_value: str,
     mode: int,
 ) -> str:
+    """
+    Modify a class by adding a property with type annotation and default value.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        class_name (str): The name of the class to modify.
+        property_name (str): The name of the property to add.
+        annotation (str): The type annotation for the property as a string.
+        default_value (str): The default value for the property as a string.
+        mode (int): The modification mode (PREPEND or APPEND).
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified class is not found in the code.
+    """
     # Parse the original code into a module
     module = cst.parse_module(original_code)
     # Initialize transformer with the class name, property name, annotation, and default value
@@ -51,6 +100,11 @@ def _modify_class_property(
 
 
 class _ClassPropertyModifier(cst.CSTTransformer):
+    """
+    A LibCST transformer to add a property with type annotation and default
+    value to a ClassDef node.
+    """
+
     def __init__(
         self,
         class_name: str,
@@ -59,6 +113,16 @@ class _ClassPropertyModifier(cst.CSTTransformer):
         default_value: str,
         mode: int,
     ):
+        """
+        Initialize the transformer.
+
+        Args:
+            class_name (str): The name of the target class.
+            property_name (str): The name of the property to add.
+            annotation (str): The type annotation for the property as a string.
+            default_value (str): The default value for the property as a string.
+            mode (int): The modification mode (PREPEND or APPEND).
+        """
         self.class_name = class_name
         self.property_name = property_name
         self.annotation = cst.Annotation(cst.parse_expression(annotation))
@@ -69,6 +133,9 @@ class _ClassPropertyModifier(cst.CSTTransformer):
     def leave_ClassDef(
         self, original_node: cst.ClassDef, updated_node: cst.ClassDef
     ) -> cst.ClassDef:
+        """
+        Called when leaving a ClassDef node. Adds the property to the target class.
+        """
         # Check if this is the target class
         if original_node.name.value == self.class_name:
             self.class_found = True

zrb/util/codemod/modify_dict.py

@@ -6,18 +6,64 @@ from zrb.util.codemod.modification_mode import APPEND, PREPEND
 def prepend_key_to_dict(
     original_code: str, dictionary_name: str, new_key: str, new_value: str
 ) -> str:
+    """
+    Prepend a new key-value pair to a dictionary in the provided code.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        dictionary_name (str): The name of the dictionary variable.
+        new_key (str): The key to prepend.
+        new_value (str): The value for the new key.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified dictionary is not found in the code.
+    """
     return _modify_dict(original_code, dictionary_name, new_key, new_value, PREPEND)
 
 
 def append_key_to_dict(
     original_code: str, dictionary_name: str, new_key: str, new_value: str
 ) -> str:
+    """
+    Append a new key-value pair to a dictionary in the provided code.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        dictionary_name (str): The name of the dictionary variable.
+        new_key (str): The key to append.
+        new_value (str): The value for the new key.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified dictionary is not found in the code.
+    """
     return _modify_dict(original_code, dictionary_name, new_key, new_value, APPEND)
 
 
 def _modify_dict(
     original_code: str, dictionary_name: str, new_key: str, new_value: str, mode: int
 ) -> str:
+    """
+    Modify a dictionary in the provided code by adding a new key-value pair.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        dictionary_name (str): The name of the dictionary variable.
+        new_key (str): The key to add.
+        new_value (str): The value for the new key.
+        mode (int): The modification mode (PREPEND or APPEND).
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified dictionary 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
@@ -34,7 +80,20 @@ def _modify_dict(
 
 
 class _DictionaryModifier(cst.CSTTransformer):
+    """
+    A LibCST transformer to modify a dictionary by adding a new key-value pair.
+    """
+
     def __init__(self, dictionary_name: str, new_key: str, new_value: str, mode: int):
+        """
+        Initialize the transformer.
+
+        Args:
+            dictionary_name (str): The name of the target dictionary variable.
+            new_key (str): The key to add.
+            new_value (str): The value for the new key.
+            mode (int): The modification mode (PREPEND or APPEND).
+        """
         self.dictionary_name = dictionary_name
         self.new_key = new_key
         self.new_value = new_value
@@ -44,6 +103,9 @@ class _DictionaryModifier(cst.CSTTransformer):
     def leave_Assign(
         self, original_node: cst.Assign, updated_node: cst.Assign
     ) -> cst.Assign:
+        """
+        Called when leaving an Assign node. Modifies the dictionary if the target matches.
+        """
         # Extract the first target from updated_node, which will be an AssignTarget
         target = updated_node.targets[0]
         # Check if the target is a Name (which should represent the dictionary)

zrb/util/codemod/modify_function.py

@@ -4,24 +4,81 @@ from zrb.util.codemod.modification_mode import APPEND, PREPEND, REPLACE
 
 
 def replace_function_code(original_code: str, function_name: str, new_code: str) -> str:
+    """
+    Replace the entire code body of a specified function.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        function_name (str): The name of the function to modify.
+        new_code (str): The new code body for the function as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified function is not found in the code.
+    """
     return _modify_function(original_code, function_name, new_code, REPLACE)
 
 
 def prepend_code_to_function(
     original_code: str, function_name: str, new_code: str
 ) -> str:
+    """
+    Prepend code to the body of a specified function.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        function_name (str): The name of the function 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 function is not found in the code.
+    """
     return _modify_function(original_code, function_name, new_code, PREPEND)
 
 
 def append_code_to_function(
     original_code: str, function_name: str, new_code: str
 ) -> str:
+    """
+    Append code to the body of a specified function.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        function_name (str): The name of the function 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 function is not found in the code.
+    """
     return _modify_function(original_code, function_name, new_code, APPEND)
 
 
 def _modify_function(
     original_code: str, function_name: str, new_code: str, mode: int
 ) -> str:
+    """
+    Modify the code body of a specified function.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        function_name (str): The name of the function 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 function 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
@@ -36,7 +93,19 @@ def _modify_function(
 
 
 class _FunctionCodeModifier(cst.CSTTransformer):
+    """
+    A LibCST transformer to modify the code body of a FunctionDef node.
+    """
+
     def __init__(self, function_name: str, new_code: str, mode: int):
+        """
+        Initialize the transformer.
+
+        Args:
+            function_name (str): The name of the target function.
+            new_code (str): The new code body as a string.
+            mode (int): The modification mode (PREPEND, APPEND, or REPLACE).
+        """
         self.function_name = function_name
         # Use parse_module to handle multiple statements
         self.new_code = cst.parse_module(new_code).body
@@ -44,9 +113,12 @@ class _FunctionCodeModifier(cst.CSTTransformer):
         self.mode = mode
 
     def leave_FunctionDef(
-        self, original_node: cst.ClassDef, updated_node: cst.ClassDef
-    ) -> cst.ClassDef:
-        # Check if the class matches the target class
+        self, original_node: cst.FunctionDef, updated_node: cst.FunctionDef
+    ) -> cst.FunctionDef:
+        """
+        Called when leaving a FunctionDef node. Modifies the body of the target function.
+        """
+        # Check if the function matches the target function
         if original_node.name.value == self.function_name:
             self.function_found = True
             if self.mode == REPLACE:

zrb/util/codemod/modify_function_call.py

@@ -6,24 +6,81 @@ from zrb.util.codemod.modification_mode import APPEND, PREPEND, REPLACE
 def replace_function_call_param(
     original_code: str, function_name: str, new_param: str
 ) -> str:
+    """
+    Replace the parameters of a specified function call.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        function_name (str): The name of the function call to modify.
+        new_param (str): The new parameter(s) as a string (e.g., "param1, param2=value").
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified function call is not found in the code.
+    """
     return _modify_function_call(original_code, function_name, new_param, REPLACE)
 
 
 def prepend_param_to_function_call(
     original_code: str, function_name: str, new_param: str
 ) -> str:
+    """
+    Prepend a parameter to a specified function call.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        function_name (str): The name of the function call to modify.
+        new_param (str): The parameter to prepend as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified function call is not found in the code.
+    """
     return _modify_function_call(original_code, function_name, new_param, PREPEND)
 
 
 def append_param_to_function_call(
     original_code: str, function_name: str, new_param: str
 ) -> str:
+    """
+    Append a parameter to a specified function call.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        function_name (str): The name of the function call to modify.
+        new_param (str): The parameter to append as a string.
+
+    Returns:
+        str: The modified Python code as a string.
+
+    Raises:
+        ValueError: If the specified function call is not found in the code.
+    """
     return _modify_function_call(original_code, function_name, new_param, APPEND)
 
 
 def _modify_function_call(
     original_code: str, function_name: str, new_param: str, mode: int
 ) -> str:
+    """
+    Modify the parameters of a specified function call.
+
+    Args:
+        original_code (str): The original Python code as a string.
+        function_name (str): The name of the function call to modify.
+        new_param (str): The parameter(s) 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 function call 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 +97,19 @@ def _modify_function_call(
 
 
 class _FunctionCallParamModifier(cst.CSTTransformer):
+    """
+    A LibCST transformer to modify the parameters of a function call.
+    """
+
     def __init__(self, func_name: str, new_param: str, mode: int):
+        """
+        Initialize the transformer.
+
+        Args:
+            func_name (str): The name of the target function.
+            new_param (str): The new parameter(s) as a string.
+            mode (int): The modification mode (PREPEND, APPEND, or REPLACE).
+        """
         self.func_name = func_name
         # Parse the new parameter to ensure it’s a valid CST node
         self.new_param = cst.parse_expression(new_param)
@@ -48,6 +117,9 @@ class _FunctionCallParamModifier(cst.CSTTransformer):
         self.mode = mode
 
     def leave_Call(self, original_node: cst.Call, updated_node: cst.Call) -> cst.Call:
+        """
+        Called when leaving a Call node. Modifies the arguments of the target function call.
+        """
         # Check if the function call name matches the target function
         if (
             isinstance(original_node.func, cst.Name)