treescript-builder 0.1__py3-none-any.whl

treescript_builder/input/line_reader.py

@@ -0,0 +1,136 @@
+"""Line Reader.
+
+The Default Input Reader.
+    Processes a single line at a time, and determines its key properties.
+    The Depth is the Integer number of directories between the current line and the root.
+    The Directory Boolean indicates whether the line represents a Directory.
+    The Name String is the name of the line.
+ Author: DK96-OS 2024 - 2025
+"""
+from itertools import groupby
+from sys import exit
+from typing import Generator
+
+from treescript_builder.data.tree_data import TreeData
+from treescript_builder.input.string_validation import validate_dir_name, validate_name
+
+SPACE_CHARS = (' ', ' ', ' ', ' ')
+
+
+def read_input_tree(input_tree_data: str) -> Generator[TreeData, None, None]:
+    """ Generate structured Tree Data from the Input Data String.
+
+**Parameters:**
+ - input_data (InputData): The Input.
+
+**Returns:**
+ Generator[TreeData] - Produces TreeData from the Input Data.
+
+**Raises:**
+ SystemExit - When any Line cannot be read successfully.
+    """
+    line_number = 1
+    for is_newline, group in groupby(input_tree_data, lambda x: x in ["\n", "\r"]):
+        if is_newline:
+            line_number += sum(1 for _ in group) # Line number increase by size of group
+        else:
+            line = ''.join(group)
+            if len(lstr := line.lstrip()) == 0 or lstr.startswith('#'):
+                continue
+            yield _process_line(line_number, line)
+
+
+def _process_line(
+    line_number: int,
+    line: str,
+) -> TreeData:
+    """ Processes a single line of the input tree structure.
+ - Returns a tuple indicating the depth, type (file or directory), name of file or dir, and file data if available.
+
+**Parameters:**
+ - line_number (int): The line-number in the input tree structure, starting from 1.
+ - line (str): A line from the input tree structure.
+
+**Returns:**
+ tuple: (int, bool, str, str) where int is the depth, bool is true when is Directory, and str is name, followed by str data.
+
+**Raises:**
+ SystemExit - When Line cannot be read successfully.
+    """
+    # Calculate the Depth
+    depth = _calculate_depth(line)
+    if depth < 0:
+        exit(f"Invalid Space Count in Line: {line_number}")
+    # Remove Space
+    args = line.strip()
+    # Try to split line into multiple arguments
+    for space_char in SPACE_CHARS:
+        if space_char in args:
+            args = args.split(space_char)
+            break
+    # Check whether line was split or not
+    if isinstance(args, str):
+        name = args
+        data_label = ""
+    elif isinstance(args, list) and len(args) >= 2:
+        name = args[0]
+        data_label = args[1]
+    else:
+        exit(f"Invalid Line: {line_number}")
+    # Validate the Node Name and Type.
+    node_info = _validate_node_name(name)
+    if node_info is None:
+        exit(f'Invalid Node on Line: {line_number}')
+    (is_dir, name) = node_info
+    return TreeData(
+        line_number,
+        depth,
+        is_dir,
+        name,
+        data_label
+    )
+
+
+def _validate_node_name(node_name: str) -> tuple[bool, str] | None:
+    """ Determine whether this Tree Node is a Directory, and validate the name.
+
+**Parameters:**
+ - node_name (str): The argument received for the node name.
+
+**Returns:**
+ tuple[bool, str] - Node information, first whether it is a directory, then the valid name of the node.
+    
+**Raises:**
+ SystemExit - When the directory name is invalid.
+    """
+    try:
+        # Check if the line contains any slash characters
+        if (dir_name := validate_dir_name(node_name)) is not None:
+            return (True, dir_name)
+        # Fall-Through to File Node
+    except ValueError as e:
+        # An error in the dir name, such that it cannot be a file either
+        return None
+    # Is a File
+    if validate_name(node_name):
+        return (False, node_name)
+    return None
+
+
+def _calculate_depth(line: str) -> int:
+    """ Calculates the depth of a line in the tree structure.
+
+**Parameters:**
+ - line (str): A line from the tree command output.
+
+**Returns:**
+ int: The depth of the line in the tree structure, or -1 if space count is invalid.
+    """
+    from itertools import takewhile
+    space_count = len(list(
+        takewhile(lambda c: c in SPACE_CHARS, line)
+    ))
+    # Bit Shift Shuffle Equivalence Validation (space_count is divisible by 2)
+    if (depth := space_count >> 1) << 1 == space_count:
+        return depth
+    return -1  # Invalid Space Count! Someone made an off-by-one whitespace mistake!

treescript_builder/input/string_validation.py

@@ -0,0 +1,130 @@
+"""String Validation Methods.
+ Author: DK96-OS 2024 - 2025
+"""
+from typing import Literal
+
+
+def validate_name(argument) -> bool:
+    """ Determine whether an argument is a non-empty string.
+ - Does not count whitespace.
+ - Uses the strip method to remove empty space.
+
+**Parameters:**
+ - argument (str) : The given argument.
+
+**Returns:**
+ bool - True if the argument qualifies as valid.
+    """
+    if argument is None or not isinstance(argument, str):
+        return False
+    elif len(argument.strip()) < 1:
+        return False
+    return True
+
+
+def validate_data_label(data_label: str) -> bool:
+    """ Determine whether a Data Label is Valid.
+
+**Parameters:**
+ - data_label (str): The String to check for validity.
+
+**Returns:**
+ bool - Whether the String is a valid Data Label.
+    """
+    if not 0 < len(data_label) < 100:
+        return False
+    if '/' in data_label or '\\' in data_label:
+        return False
+    # Remove Dash Characters
+    if '-' in data_label:
+        data_label = data_label.replace('-', '')
+    # Remove Underscore Characters
+    if '_' in data_label:
+        data_label = data_label.replace('_', '')
+    # Remove Dot Characters
+    if '.' in data_label:
+        data_label = data_label.replace('.', '')
+    if '!' == data_label:
+        return True
+    # All Remaining Characters must be alphanumeric
+    return data_label.isalnum()
+
+
+def validate_dir_name(dir_name: str) -> str | None:
+    """ Determine that a directory is correctly formatted.
+ - This method should be called once for each slash type.
+
+**Parameters:**
+ - dir_name (str): The given input to be validated.
+
+**Returns:**
+ str | None - The valid directory name, or none if it may be a file.
+
+**Raises:**
+ ValueError - When the name is not suitable for directories or files.
+    """
+    # Keep Name Length Reasonable
+    if (name_length := len(dir_name)) >= 100:
+        raise ValueError(f'Name too Long!: {name_length}')
+    # Check for slash characters
+    if (name := _filter_slash_chars(dir_name)) is not None:
+        # Is a Dir
+        if len(name) == 0:
+            raise ValueError('The name is empty')
+        # Check for invalid characters (parent dir, current dir)
+        if name in ['.', '..']:
+            raise ValueError('Invalid Directory')
+        return name
+    # Is a File
+    return None
+
+
+def _validate_slash_char(dir_name: str) -> Literal['\\', '/'] | None:
+    """ Determine which slash char is used by the directory, if it is a directory.
+ - Discourages use of both slash chars, by raising ValueError.
+
+**Parameters:**
+ - dir_name (str): The given input to be validated.
+
+**Returns:**
+ str | None - The slash character used, or none if no chars were found.
+
+**Raises:**
+ ValueError - When the name contains both slash characters.
+    """
+    slash = None
+    if '/' in dir_name:
+        slash = '/'
+    if '\\' in dir_name:
+        if slash is not None:
+            raise ValueError('Invalid Directory slash character combination.')
+        slash = '\\'
+    return slash
+
+
+def _filter_slash_chars(dir_name: str) -> str | None:
+    """ Remove all of the slash characters and return the directory name.
+- Returns None when there are no slash characters found.
+- Raises ValueError when slash characters are used improperly.
+
+**Parameters:**
+ - dir_name (str): The given input to be validated.
+
+**Returns:**
+ str | None - The valid directory name, or none if it may be a file.
+
+**Raises:**
+ ValueError - When the name is not suitable for directories or files.
+    """
+    slash = _validate_slash_char(dir_name)
+    if slash is None:
+        return None
+    if dir_name.endswith(slash) or dir_name.startswith(slash):
+        name = dir_name.strip(slash)
+        # Check for internal slash characters
+        if slash in name:
+            raise ValueError('Multi-dir line detected')
+    else:
+        # Found slash chars only within the node name (multi-dir line)
+        raise ValueError('Multi-dir line detected')
+    return name

treescript_builder/tree/__init__.py

@@ -0,0 +1,56 @@
+"""The Tree Module.
+"""
+from treescript_builder.input.input_data import InputData
+from treescript_builder.input.line_reader import read_input_tree
+
+
+def build_tree(input_data: InputData) -> tuple[bool, ...]:
+    """ Build The Tree as defined by the InputData.
+
+**Parameters:**
+ - input_data (str): The InputData produced by the Input Module.
+
+**Returns:**
+ tuple[bool, ...] - The results of each individual Builder operation.
+
+**Raises:**
+ SystemExit - If a Tree Validation error occurs.
+	"""
+    if input_data.is_reversed:
+        from treescript_builder.tree.trim_validation import validate_trim
+        instructions = validate_trim(
+            read_input_tree(input_data.tree_input),
+            input_data.data_dir
+        )
+        from treescript_builder.tree.tree_trimmer import trim
+        results = trim(instructions)
+    else:
+        from treescript_builder.tree.build_validation import validate_build
+        instructions = validate_build(
+            read_input_tree(input_data.tree_input),
+            input_data.data_dir
+        )
+        from treescript_builder.tree.tree_builder import build
+        results = build(instructions)
+    #
+    return results
+
+
+def process_results(results: tuple[bool, ...]) -> str:
+    """ Process and Summarize the Results.
+
+**Parameters:**
+ - results (tuple[bool]): A tuple containing the results of the operations.
+
+**Returns:**
+ str - A summary of the number of operations that succeeded.
+    """
+    if (length := len(results)) == 0:
+        return 'No operations ran.'
+    if (success := sum(iter(results))) == 0:
+        return f"All {length} operations failed."
+    elif success == length:
+        return f"All {length} operations succeeded."
+    # Compute the Fraction of success operations
+    success_percent = round(100 * success / length, 1)
+    return f"{success} out of {length} operations succeeded: {success_percent}%"

treescript_builder/tree/build_validation.py

@@ -0,0 +1,111 @@
+"""Tree Validation Methods for the Build Operation.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+from typing import Generator
+
+from treescript_builder.data.data_directory import DataDirectory
+from treescript_builder.data.instruction_data import InstructionData
+from treescript_builder.data.tree_data import TreeData
+from treescript_builder.data.tree_state import TreeState
+
+
+def validate_build(
+    tree_data: Generator[TreeData, None, None],
+    data_dir_path: Path | None = None,
+    verbose: bool = False,
+) -> tuple[InstructionData, ...]:
+    """ Validate the Build Instructions.
+
+**Parameters:**
+ - tree_data (Generator[TreeData]): The Generator that provides TreeData.
+ - data_dir_path (Path?): The optional Data Directory Path. Default: None.
+ - verbose (bool): Whether to print DataDirectory information during validation.
+
+**Returns:**
+ tuple[InstructionData] - A generator that yields Instructions.
+    """
+    if data_dir_path is None:
+        return tuple(iter(_validate_build_generator(tree_data)))
+    else:
+        data = DataDirectory(data_dir_path)
+        if verbose:
+            print(f"Validating Build With DataDir: {data_dir_path}")
+        return tuple(iter(_validate_build_generator_data(tree_data, data)))
+
+
+def _validate_build_generator(
+    tree_data: Generator[TreeData, None, None]
+) -> Generator[InstructionData, None, None]:
+    tree_state = TreeState()
+    for node in tree_data:
+        # Error if any Nodes have Data Labels
+        if node.data_label != '':
+            exit(f"Found Data Label on Line {node.line_number} with no Data Directory: {node.data_label}")
+        # Calculate Tree Depth Change
+        if tree_state.validate_tree_data(node) == 0:
+            if node.is_dir:
+                tree_state.add_to_queue(node.name)
+            else:
+                # Merge Queue into Stack
+                if (new_dir := tree_state.process_queue()) is not None:
+                    yield InstructionData(True, new_dir)
+                yield InstructionData(
+                    False, tree_state.get_current_path() / node.name
+                )
+        else:
+            # Merge Queue into Stack
+            if (new_dir := tree_state.process_queue()) is not None:
+                yield InstructionData(True, new_dir, None)
+            # Pop Stack to required Depth
+            if not tree_state.reduce_depth(node.depth):
+                exit(f"Invalid Depth at Line: {node.line_number}")
+            if node.is_dir:
+                tree_state.add_to_queue(node.name)
+            else:
+                yield InstructionData(
+                    False, tree_state.get_current_path() / node.name
+                )
+    # Always Finish Build Sequence with ProcessQueue
+    if (dir := tree_state.process_queue()) is not None:
+        yield InstructionData(True, dir)
+
+
+def _validate_build_generator_data(
+    tree_data: Generator[TreeData, None, None],
+    data_dir: DataDirectory
+) -> Generator[InstructionData, None, None]:
+    tree_state = TreeState()
+    for node in tree_data:
+        # Calculate Tree Depth Change
+        if tree_state.validate_tree_data(node) == 0:
+            if node.is_dir:
+                tree_state.add_to_queue(node.name)
+            else:
+                # Build Queued Directories
+                if (new_dir := tree_state.process_queue()) is not None:
+                    yield InstructionData(True, new_dir)
+                # Build File
+                yield InstructionData(
+                    False,
+                    tree_state.get_current_path() / node.name,
+                    data_dir.validate_build(node)
+                )
+        else:
+            # Merge Queue into Stack
+            if (new_dir := tree_state.process_queue()) is not None:
+                yield InstructionData(True, new_dir)
+            # Pop Stack to required Depth
+            if not tree_state.reduce_depth(node.depth):
+                exit(f"Invalid Tree Depth on Line {node.line_number} : {node.name}")
+            if node.is_dir:
+                tree_state.add_to_queue(node.name)
+            else:
+                yield InstructionData(
+                    False,
+                    tree_state.get_current_path() / node.name,
+                    data_dir.validate_build(node)
+                )
+    # Always Finish Build Sequence with ProcessQueue
+    if (dir := tree_state.process_queue()) is not None:
+        yield InstructionData(True, dir)

treescript_builder/tree/tree_builder.py

@@ -0,0 +1,77 @@
+"""Tree Building Operations.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+from shutil import copy2
+
+from treescript_builder.data.instruction_data import InstructionData
+
+
+def build(instructions: tuple[InstructionData, ...]) -> tuple[bool, ...]:
+    """ Execute the Instructions in build mode.
+
+**Parameters:**
+ - instructions(tuple[InstructionData]): The Instructions to execute.
+
+**Returns:**
+ tuple[bool] - The success or failure of each instruction.
+    """
+    return tuple(_build(i) for i in instructions)
+
+
+def _build(i: InstructionData) -> bool:
+    """ Execute a single instruction.
+
+**Parameters:**
+ - instruction(InstructionData): The data required to execute the operation.
+
+**Returns:**
+ bool - Whether the given operation succeeded.
+    """
+    if i.is_dir:
+        return _make_dir_exist(i.path)
+    elif i.data_path is None:
+        i.path.touch(exist_ok=True)
+        return True
+    else:
+        return _create_file(i.path, i.data_path)
+
+
+def _create_file(
+    path: Path,
+    data: Path
+) -> bool:
+    """ Create a File at the given path, with data from the Data Directory.
+
+**Parameters:**
+ - path (Path): The Path to the File to be created, and written to.
+ - data (Path): A Data Directory Path to be copied to the new File.
+
+**Returns:**
+ bool - Whether the File operation succeeded.
+    """
+    try:
+        copy2(data, path)
+    except BaseException as e:
+        return False
+    return True
+
+
+def _make_dir_exist(
+    path: Path
+) -> bool:
+    """ Ensure that the Directory at the given Path exists.
+
+**Parameters:**
+ - path (Path): The Path to the File to be created, and written to.
+
+**Returns:**
+ bool - True if the Operation Succeeded, or if the Path already exists.
+    """
+    if path.exists():
+        return True
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+    except IOError as e:
+        return False
+    return True

treescript_builder/tree/tree_trimmer.py

@@ -0,0 +1,70 @@
+"""Tree Trimming Methods.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+from shutil import move
+
+from treescript_builder.data.instruction_data import InstructionData
+
+
+def trim(instructions: tuple[InstructionData, ...]) -> tuple[bool, ...]:
+    """ Execute the Instructions in trim mode.
+
+**Parameters:**
+ - instructions(tuple[InstructionData]): The Instructions to execute.
+
+**Returns:**
+ tuple[bool] - The success or failure of each instruction.
+    """
+    return tuple(_trim(i) for i in instructions)
+
+
+def _trim(instruct: InstructionData) -> bool:
+    if instruct.is_dir:
+        return _remove_dir(instruct.path)
+    if instruct.data_path is None:
+        try:
+            instruct.path.unlink(missing_ok=True)
+            return True
+        except IOError as e:
+            print("IO File Error")
+            return False
+    return _extract_file(instruct.path, instruct.data_path)
+
+
+def _extract_file(
+    path: Path,
+    data: Path
+) -> bool:
+    """ Moves the File to the Data Directory.
+
+**Parameters:**
+ - path (Path): The path to the File in the Tree.
+ - data (Path): A Path to a File in the Data Directory.
+
+**Returns:**
+ bool - Whether the entire operation succeeded.
+    """
+    try:
+        move(path, data)
+        return True
+    except:
+        return False
+
+
+def _remove_dir(
+    path: Path,
+) -> bool:
+    """ Tries to Remove a Directory, if it is Empty.
+
+**Parameters:**
+ - path (Path): The path to the Directory.
+
+**Returns:**
+ bool : Whether the Directory was Empty, and has been removed.
+    """
+    try:
+        path.rmdir()
+    except BaseException as e:
+        return False
+    return True

treescript_builder/tree/trim_validation.py

@@ -0,0 +1,97 @@
+"""Tree Validation Methods for the Trim Operation.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+from typing import Generator
+
+from treescript_builder.data.data_directory import DataDirectory
+from treescript_builder.data.instruction_data import InstructionData
+from treescript_builder.data.tree_data import TreeData
+from treescript_builder.data.tree_state import TreeState
+
+
+def validate_trim(
+    tree_data: Generator[TreeData, None, None],
+    data_dir_path: Path | None = None,
+    verbose: bool = False,
+) -> tuple[InstructionData, ...]:
+    """ Validate the Trim Instructions.
+
+**Parameters:**
+ - tree_data (Generator[TreeData]): The Generator that provides TreeData.
+ - data_dir_path (Path?): The optional Path to a Data Directory. Default: None.
+ - verbose (bool): Whether to print DataDirectory information during validation.
+
+**Returns:**
+ tuple[InstructionData] - A generator that yields Instructions.
+    """
+    if data_dir_path is None:
+        return tuple(iter(_validate_trim_generator(tree_data)))
+    else:
+        data = DataDirectory(data_dir_path)
+        if verbose:
+            print(f"Validating Trim With DataDir: {data_dir_path}")
+        return tuple(iter(_validate_trim_generator_data(tree_data, data)))
+
+
+def _validate_trim_generator(
+    tree_data: Generator[TreeData, None, None]
+) -> Generator[InstructionData, None, None]:
+    tree_state = TreeState()
+    for node in tree_data:
+        # Calculate Tree Depth Change
+        if tree_state.validate_tree_data(node) == 1:
+            if node.is_dir:
+                tree_state.add_to_stack(node.name)
+            else:
+                yield InstructionData(
+                    False, tree_state.get_current_path() / node.name
+                )
+        else:
+            # Pop Stack to required Depth
+            for i in tree_state.process_stack(node.depth):
+                yield InstructionData(True, i)
+            # Dir or File
+            if node.is_dir:
+                tree_state.add_to_stack(node.name)
+            else:
+                yield InstructionData(
+                    False, tree_state.get_current_path() / node.name
+                )
+    # Finish Trim Sequence with Pop Stack
+    for i in tree_state.process_stack(0):
+        yield InstructionData(True, i)
+
+
+def _validate_trim_generator_data(
+    tree_data: Generator[TreeData, None, None],
+    data_dir: DataDirectory
+) -> Generator[InstructionData, None, None]:
+    tree_state = TreeState()
+    for node in tree_data:
+        # Calculate Tree Depth Change
+        if tree_state.validate_tree_data(node) == 1:
+            if node.is_dir:
+                tree_state.add_to_stack(node.name)
+            else:
+                yield InstructionData(
+                    False,
+                    tree_state.get_current_path() / node.name,
+                    data_dir.validate_trim(node)
+                )
+        else:
+            # Pop Stack to required Depth
+            for i in tree_state.process_stack(node.depth):
+                yield InstructionData(True, i)
+            # Dir or File
+            if node.is_dir:
+                tree_state.add_to_stack(node.name)
+            else:
+                yield InstructionData(
+                    False,
+                    tree_state.get_current_path() / node.name,
+                    data_dir.validate_trim(node)
+                )
+    # Finish Trim Sequence with Pop Stack
+    for i in tree_state.process_stack(0):
+        yield InstructionData(True, i)