treescript-builder 0.1__py3-none-any.whl

treescript_builder/__init__.py

@@ -0,0 +1,4 @@
+""" TreeScript Builder.
+ - Previously, and sometimes referred to as FileTreeBuilder.
+ Author: DK96-OS 2024 - 2025
+"""

treescript_builder/__main__.py

@@ -0,0 +1,18 @@
+#!/usr/bin/python
+
+
+def main():
+    # Author: DK96-OS 2024 - 2025
+    from treescript_builder.input import validate_input_arguments
+    from treescript_builder.tree import build_tree
+    from sys import argv
+    build_tree(validate_input_arguments(argv[1:]))
+
+
+if __name__ == "__main__":
+    from sys import path
+    from pathlib import Path
+    # Get the directory of the current file (__file__ is the path to the script being executed)
+    current_directory = Path(__file__).resolve().parent.parent
+    path.append(str(current_directory)) # Add the directory to sys.path
+    main()

treescript_builder/data/data_directory.py

@@ -0,0 +1,85 @@
+"""Data Directory Management.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+from sys import exit
+
+from treescript_builder.data.tree_data import TreeData
+from treescript_builder.input.string_validation import validate_data_label
+
+
+class DataDirectory:
+    """ Manages Access to the Data Directory.
+     - Search for a Data Label, and obtain the Path to the Data File.
+    """
+
+    def __init__(self, data_dir: Path):
+        if not isinstance(data_dir, Path) or not data_dir.exists():
+            exit('The Data Directory must be a Path that Exists!')
+        self._data_dir = data_dir
+        # todo: Create a map of used Data Labels
+
+    def validate_build(self, node: TreeData) -> Path | None:
+        """ Determine if the Data File supporting this Tree node is available.
+
+        Parameters:
+        - node (TreeData): The TreeData to validate.
+
+        Returns:
+        Path - The Path to the Data File in the Data Directory.
+
+        Raises:
+        SystemExit - When the Data label is invalid, or the Data File does not exist.
+        """
+        if node.data_label == '' or node.is_dir:
+            return None
+        if node.data_label == '!':
+            data_path = self._search_label(node.name)
+        else:
+            data_path = self._search_label(node.data_label)
+        if data_path is None:
+            exit(f'Data Label ({node.data_label}) not found in Data Directory on line: {node.line_number}')
+        return data_path
+
+    def validate_trim(self, node: TreeData) -> Path | None:
+        """ Determine if the File already exists in the Data Directory.
+
+        Parameters:
+        - node (TreeData): The TreeData to validate.
+
+        Returns:
+        Path - The Path to a new File in the Data Directory.
+
+        Raises:
+        SystemExit - When the Data label is invalid, or the Data File already exists.
+        """
+        # Ensure that the name of the Label is valid
+        if node.data_label == '' or node.is_dir:
+            return None
+        data_label = node.name if node.data_label == '!' else node.data_label
+        if not validate_data_label(data_label):
+            exit(f'Invalid Data Label on line: {node.line_number}')
+        # Check if the Data File already exists
+        data_path = self._search_label(data_label)
+        if data_path is not None:
+            exit(f'Data File already exists!\n({data_label}) on line: {node.line_number}')
+        # Create the Data Label Path in the Directory
+        return self._data_dir / data_label
+
+    def _search_label(self, data_label: str) -> Path | None:
+        """ Search for a Data Label in this Data Directory.
+
+        Parameters:
+        - data_label (str): The Data Label to search for.
+
+        Returns:
+        Path (optional) - The Path to the Data File, or None.
+        """
+        if not validate_data_label(data_label):
+            return None
+        # Find the Data Label File
+        data_files = self._data_dir.glob(data_label)
+        try:
+            return next(data_files)
+        except StopIteration as s:
+            return None

treescript_builder/data/instruction_data.py

@@ -0,0 +1,19 @@
+"""The Instruction Data in a Tree Operation.
+ Author: DK96-OS 2024 - 2025
+"""
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class InstructionData:
+    """ The Data required to execute the Instruction.
+
+**Fields:**
+ - is_dir (bool): Whether the Instruction relates to a Directory.
+ - path (Path): The Path of the Instruction.
+ - data_path (Path?): The Data Directory Path of the Instruction, if applicable. Default: None.
+    """
+    is_dir: bool
+    path: Path
+    data_path: Path | None = None

treescript_builder/data/path_stack.py

@@ -0,0 +1,86 @@
+""" Path Stack Management.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+
+
+class PathStack:
+    """ A Stack of Directory names in a Path.
+    """
+
+    def __init__(self):
+        # The Stack of Directories in the Path.
+        self._stack = []
+
+    def push(self, directory_name: str):
+        """ Push a directory to the Path Stack.
+
+        Parameters:
+        - directory_name (str): The name of the next directory in the Path Stack.
+        """
+        self._stack.append(directory_name)
+
+    def pop(self) -> str | None:
+        """
+        Pop the top of the Stack, and return the directory name.
+
+        Returns:
+        str : The String removed from the top of the Stack.
+        """
+        if len(self._stack) <= 0:
+            return None
+        return self._stack.pop()
+
+    def join_stack(self) -> Path:
+        """
+        Combines all elements in the path Stack to form the parent directory.
+
+        Returns:
+        Path representing the current directory.
+        """
+        if len(self._stack) == 0:
+            return Path("./")
+        return Path(f"./{'/'.join(self._stack)}/")
+
+    def create_path(self, filename: str) -> Path:
+        """
+        Combines all Elements in the Stack and appends a File name.
+
+        Parameters:
+        - filename (str): The name of the file to append to the end of the path.
+
+        Returns:
+        Path : The Path to the file.
+        """
+        if type(filename) is not str or len(filename) < 1:
+            return self.join_stack()
+        return self.join_stack() / filename
+
+    def reduce_depth(self, depth: int) -> bool:
+        """
+        Reduce the Depth of the Path Stack.
+
+        Parameters:
+        - depth (int): The depth to reduce the stack to.
+
+        Returns:
+        boolean : Whether the Reduction was successful, ie 0 or more Stack pops.
+        """
+        current_depth = self.get_depth()
+        if current_depth < depth or depth < 0:
+            return False
+        if current_depth == depth:
+            return True
+        for _ in range(current_depth, depth, -1):
+            self._stack.pop()
+        return True
+
+    def get_depth(self) -> int:
+        """
+        Obtain the current Depth of the Stack.
+            The state where the current directory is the path, ie: './' has a depth of 0.
+
+        Returns:
+        int : The number of elements in the Path Stack.
+        """
+        return len(self._stack)

treescript_builder/data/tree_data.py

@@ -0,0 +1,23 @@
+"""Tree Node DataClass.
+ Author: DK96-OS 2024 - 2025
+"""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TreeData:
+    """ A DataClass representing a Tree Node.
+
+Fields:
+ - line_number (int): The line number of this tree node in the TreeScript file.
+ - depth (int): The depth in the tree, from the root. Starts at zero.
+ - is_dir (bool): Whether this Node is a directory.
+ - name (str): The Name of the Tree Node.
+ - data_label (str): The Data Label, may be empty string.
+    """
+
+    line_number: int
+    depth: int
+    is_dir: bool
+    name: str
+    data_label: str = ''

treescript_builder/data/tree_state.py

@@ -0,0 +1,132 @@
+"""Tree State.
+    A Key component in Tree Validation for Build operations.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+from sys import exit
+from typing import Generator
+
+from treescript_builder.data.path_stack import PathStack
+from treescript_builder.data.tree_data import TreeData
+
+
+class TreeState:
+    """ Manages the State of the Tree during Validation.
+    """
+
+    def __init__(self):
+        self._stack = PathStack()
+        self._queue = []
+        self._prev_line_number = 0
+
+    def validate_tree_data(self, node: TreeData) -> int:
+        """ Ensure that the next TreeData is valid, relative to current state.
+         - Calculate the change in depth, occurring with this TreeData.
+
+        Parameters:
+         - node (TreeData): The next TreeData in the sequence to Validate.
+
+        Returns:
+         int - The difference between the TreeData depth and the TreeState depth.
+
+        Raises:
+         SystemExit - When the TreeData is invalid, relative to the current TreeState.
+        """
+        self._update_line_number(node.line_number)
+        # Calculate the Change in Depth
+        if node.depth < 0:
+            exit("Invalid Depth Value")
+        # Ensure that the depth change is zero or less
+        if (delta := node.depth - self.get_current_depth()) > 0:
+            exit(f"You have jumped {delta} steps in the tree on line: {node.line_number}")
+        return delta
+
+    def get_current_depth(self) -> int:
+        """ Determine the Current Depth of the Tree.
+         - Includes Elements in both the Stack and the Queue.
+
+        Returns:
+         int - The total number of elements, combining stack and queue
+        """
+        return self._stack.get_depth() + len(self._queue)
+
+    def get_current_path(self) -> Path:
+        """ Obtain the Current Path of the Tree.
+
+        Returns:
+         str - A Path equivalent to the current Tree State.
+        """
+        if len(self._queue) > 0:
+            self.process_queue()
+        return self._stack.join_stack()
+
+    def add_to_queue(self, dir_name: str):
+        """ Add a directory to the Queue.
+
+        Parameters:
+         - dir_name (str): The name of the Directory to enqueue.
+        """
+        self._queue.append(dir_name)
+
+    def add_to_stack(self, dir_name: str):
+        """ Add a directory to the Stack.
+
+        Parameters:
+         - dir_name (str): The name of the Directory.
+        """
+        self._stack.push(dir_name)
+
+    def process_queue(self) -> Path | None:
+        """Process the Directories in the Queue.
+         - Adds all directories from the Queue to the Stack.
+
+        Returns:
+         Path? - The whole Path from the Stack.
+        """
+        if len(self._queue) < 1:
+            return None
+        for element in self._queue:
+            self._stack.push(element)
+        self._queue.clear()
+        # Return the new Path as a str
+        return self._stack.join_stack()
+
+    def process_stack(self, depth: int) -> Generator[Path, None, None]:
+        """ Pop the Stack to the Desired Depth.
+
+        Parameters:
+         - depth (int): The depth to process the stack to.
+
+        Returns:
+         Generator[Path] - Provides a Path for each entry in the Stack.
+        """
+        if depth < 0:
+            exit('Invalid Depth')
+        while depth < self._stack.get_depth():
+            if (entry := self._stack.pop()) is not None:
+                yield self._stack.create_path(entry)
+
+    def reduce_depth(self, depth: int) -> bool:
+        """ Pop an element from the stack.
+
+        Parameters:
+         - depth (int): The Depth to pop the Stack to.
+
+        Returns:
+         bool - Whether the depth reduction succeeded, ie. 0 or more elements popped.
+        """
+        return self._stack.reduce_depth(depth)
+
+    def _update_line_number(self, line_number: int):
+        """ Validate the Line Number is always increasing.
+
+        Parameters:
+         - line_number (int): The line number from the next TreeData.
+
+        Raises:
+         SystemExit - When the Line Number does not increase.
+        """
+        if self._prev_line_number < line_number:
+            self._prev_line_number = line_number
+        else:
+            exit("Invalid Tree Data Sequence")

treescript_builder/input/__init__.py

@@ -0,0 +1,28 @@
+"""The Input Module.
+ - Validate And Format Input Arguments.
+ - Read Input Tree String from File.
+ Author: DK96-OS 2024 - 2025
+"""
+from treescript_builder.input.argument_parser import parse_arguments
+from treescript_builder.input.file_validation import validate_input_file, validate_directory
+from treescript_builder.input.input_data import InputData
+
+
+def validate_input_arguments(arguments: list[str]) -> InputData:
+    """ Parse and Validate the Arguments, then return as InputData.
+
+**Parameters:**
+ - arguments (list[str]): The list of Arguments to validate.
+    
+**Returns:**
+ InputData - An InputData instance.
+
+**Raises:**
+ SystemExit - If Arguments, Input File or Directory names invalid.
+    """
+    arg_data = parse_arguments(arguments)
+    return InputData(
+        validate_input_file(arg_data.input_file_path_str),
+        validate_directory(arg_data.data_dir_path_str),
+        arg_data.is_reversed
+    )

treescript_builder/input/argument_data.py

@@ -0,0 +1,22 @@
+"""The Arguments Received from the Command Line Input.
+ - This DataClass is created after the argument syntax is validated.
+ - Syntax Validation:
+    - The Input File is Present and non-blank.
+    - When Data Directory is present, it is non-blank.
+ Author: DK96-OS 2024 - 2025
+"""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ArgumentData:
+    """ The syntactically valid arguments received by the Program.
+
+**Fields:**
+ - input_file_path_str (str): The Name of the File containing the Tree Structure.
+ - data_dir_path_str (str?): The Directory Name containing Files Used in File Tree Operation.
+ - is_reversed (bool): Flag to determine if the File Tree Operation Is To be Oppositely Trimmed.
+    """
+    input_file_path_str: str
+    data_dir_path_str: str | None
+    is_reversed: bool

treescript_builder/input/argument_parser.py

@@ -0,0 +1,102 @@
+"""Defines and Validates Argument Syntax.
+ - Encapsulates Argument Parser.
+ - Returns Argument Data, the args provided by the User.
+ Author: DK96-OS 2024 - 2025
+"""
+from argparse import ArgumentParser
+from sys import exit
+from typing import Optional
+
+from treescript_builder.input.argument_data import ArgumentData
+from treescript_builder.input.string_validation import validate_name
+
+
+def parse_arguments(args: Optional[list[str]] = None) -> ArgumentData:
+    """ Parse command line arguments.
+
+    Parameters:
+     - args: A list of argument strings.
+
+    Returns:
+    ArgumentData : Container for Valid Argument Data.
+    """
+    if args is None or len(args) == 0:
+        exit("No Arguments given. ")
+    # Initialize the Parser and Parse Immediately
+    try:
+        parsed_args = _define_arguments().parse_args(args)
+    except SystemExit as e:
+        exit("Unable to Parse Arguments.")
+    #
+    return _validate_arguments(
+        parsed_args.tree_file_name,
+        parsed_args.data_dir,
+        parsed_args.reverse
+    )
+
+
+def _validate_arguments(
+    tree_file_name: str,
+    data_dir_name: str,
+    is_reverse: bool
+) -> ArgumentData:
+    """ Checks the values received from the ArgParser.
+        - Uses Validate Name method from StringValidation.
+        - Ensures that Reverse Operations have a Data Directory.
+    
+    Parameters:
+     - tree_file_name (str): The file name of the tree input.
+     - data_dir_name (str): The Data Directory name.
+     - is_reverse (bool): Whether the builder operation is reversed.
+
+    Returns:
+    ArgumentData - A DataClass of syntactically correct arguments.
+    """
+    # Validate Tree Name Syntax
+    if not validate_name(tree_file_name):
+        exit("The Tree File argument was invalid.")
+    # Validate Data Directory Name Syntax if Present
+    if data_dir_name is None:
+        pass
+    elif not validate_name(data_dir_name):
+        exit("The Data Directory argument was invalid.")
+    #
+    return ArgumentData(
+        tree_file_name,
+        data_dir_name,
+        is_reverse
+    )
+
+
+def _define_arguments() -> ArgumentParser:
+    """
+    Initializes and Defines Argument Parser.
+       - Sets Required/Optional Arguments and Flags.
+
+    Returns:
+    argparse.ArgumentParser - An instance with all supported FTB Arguments.
+    """
+    parser = ArgumentParser(
+        description="File Tree Builder"
+    )
+    # Required argument
+    parser.add_argument(
+        'tree_file_name',
+        type=str,
+        help='The File containing the Tree Node Structure'
+    )
+    # Optional arguments
+    parser.add_argument(
+        '--data_dir',
+        default=None,
+        help='The Data Directory'
+    )
+    parser.add_argument(
+        '-r',
+        '--reverse',
+        '--trim',
+        action='store_true',
+        default=False,
+        help='Flag to reverse the File Tree Operation'
+    )
+    return parser

treescript_builder/input/file_validation.py

@@ -0,0 +1,52 @@
+""" File Validation Methods.
+    These Methods all raise SystemExit exceptions.
+ Author: DK96-OS 2024 - 2025
+"""
+from pathlib import Path
+from sys import exit
+
+from treescript_builder.input.string_validation import validate_name
+
+
+def validate_input_file(file_name: str) -> str | None:
+    """ Read the Input File, Validate (non-blank) data, and return Input str.
+
+    Parameters:
+    - file_name (str): The Name of the Input File.
+
+    Returns:
+    str - The String Contents of the Input File.
+
+    Raises:
+    SystemExit - If the File does not exist, or is empty or blank, or read failed.
+    """
+    file_path = Path(file_name)
+    if not file_path.exists():
+        exit("The Input File does not Exist.")
+    try:
+        if (data := file_path.read_text()) is not None and validate_name(data):
+            return data
+    except IOError as e:
+        exit("Failed to Read from File.")
+    return None
+
+
+def validate_directory(dir_path_str: str | None) -> Path | None:
+    """ Ensure that if the Directory is present, it Exists.
+
+    Parameters:
+    - dir_path_str (str, optional): The String representation of the Path to the Directory.
+
+    Returns:
+    Path? - The , or None if given input is None.
+
+    Raises:
+    SystemExit - If a given path does not exist.
+    """
+    if dir_path_str is None:
+        return None
+    if not validate_name(dir_path_str):
+        exit("Data Directory is invalid")
+    if (path := Path(dir_path_str)).exists():
+        return path
+    exit("The given Directory does not exist!")

treescript_builder/input/input_data.py

@@ -0,0 +1,19 @@
+"""Valid Input Data Class.
+ Author: DK96-OS 2024 - 2025
+"""
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class InputData:
+    """A Data Class Containing Program Input.
+
+**Fields:**
+ - tree_input (str): The Tree Input to the FTB operation.
+ - data_dir (Path, optional): An Optional Path to the Data Directory.
+ - is_reversed (bool): Whether this FTB operation is reversed.
+    """
+    tree_input: str
+    data_dir: Path | None
+    is_reversed: bool