treescript-builder 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

treescript_builder/input/__init__.py

@@ -25,4 +25,4 @@ def validate_input_arguments(arguments: list[str]) -> 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_parser.py

@@ -55,9 +55,7 @@ def _validate_arguments(
     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):
+    if data_dir_name is not None and not validate_name(data_dir_name):
         exit("The Data Directory argument was invalid.")
     return ArgumentData(
         tree_file_name,
@@ -96,4 +94,4 @@ def _define_arguments() -> ArgumentParser:
         default=False,
         help='Flag to reverse the File Tree Operation'
     )
-    return parser
+    return parser

treescript_builder/input/file_validation.py

@@ -3,13 +3,28 @@
  Author: DK96-OS 2024 - 2025
 """
 from pathlib import Path
+from stat import S_ISLNK
 from sys import exit
 
 from treescript_builder.input.string_validation import validate_name
 
 
+_FILE_SIZE_LIMIT = 32 * 1024 # 32 KB
+_FILE_SIZE_LIMIT_ERROR_MSG = "File larger than 32 KB Limit."
+_FILE_SYMLINK_DISABLED_MSG = "Symlink file paths are disabled."
+
+_FILE_DOES_NOT_EXIST_MSG = "The File does not Exist."
+_FILE_READ_OSERROR_MSG = "Failed to Read from File."
+_FILE_VALIDATION_ERROR_MSG = "Invalid Input File Contents."
+
+_NOT_A_DIR_ERROR_MSG = "Not a Directory."
+_DIR_DOES_NOT_EXIST_MSG = "The Directory does not exist."
+
+
 def validate_input_file(file_name: str) -> str | None:
     """ Read the Input File, Validate (non-blank) data, and return Input str.
+ - Max FileSize is 32 KB.
+ - Symlink type file paths are disabled.
 
 **Parameters:**
  - file_name (str): The Name of the Input File.
@@ -18,35 +33,43 @@ def validate_input_file(file_name: str) -> str | None:
  str - The String Contents of the Input File.
 
 **Raises:**
- SystemExit - If the File does not exist, or is empty or blank, or read failed.
+ SystemExit - If the File does not exist, or is empty, blank, over 32 KB, or if the read or validation operation 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
+        if not file_path.exists():
+            exit(_FILE_DOES_NOT_EXIST_MSG)
+        if S_ISLNK((stat := file_path.lstat()).st_mode):
+            exit(_FILE_SYMLINK_DISABLED_MSG)
+        if stat.st_size > _FILE_SIZE_LIMIT:
+            exit(_FILE_SIZE_LIMIT_ERROR_MSG)
+        if (data := file_path.read_text()) is not None:
+            if validate_name(data):
+                return data
+            exit(_FILE_VALIDATION_ERROR_MSG)
+        # Fallthrough: return None
     except OSError:
-        exit("Failed to Read from File.")
+        exit(_FILE_READ_OSERROR_MSG)
     return None
 
 
 def validate_directory(dir_path_str: str | None) -> Path | None:
-    """ Ensure that if the Directory is present, it Exists.
+    """ Ensure that if the Directory argument is present, it Exists.
+ - Allows None to pass through the method.
 
 **Parameters:**
-- dir_path_str (str, optional): The String representation of the Path to the Directory.
+ - dir_path_str (str?): The String representation of the Path to the Directory.
 
 **Returns:**
- Path? - The , or None if given input is None.
+ Path? - The Path to the DataDirectory, or None if given input is None.
 
 **Raises:**
- SystemExit - If a given path does not exist.
+ SystemExit - If a given path does not exist, or is not a Directory.
     """
     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!")
+        if path.is_dir():
+            return path
+        exit(_NOT_A_DIR_ERROR_MSG)
+    exit(_DIR_DOES_NOT_EXIST_MSG)

treescript_builder/input/string_validation.py

@@ -1,6 +1,7 @@
 """ String Validation Methods.
  Author: DK96-OS 2024 - 2025
 """
+from itertools import permutations, repeat
 from typing import Literal
 
 
@@ -10,7 +11,7 @@ def validate_name(argument) -> bool:
  - Uses the strip method to remove empty space.
 
 **Parameters:**
- - argument (str) : The given argument.
+ - argument (str): The given argument, which needs validation.
 
 **Returns:**
  bool - True if the argument qualifies as valid.
@@ -24,6 +25,10 @@ def validate_name(argument) -> bool:
 
 def validate_data_label(data_label: str) -> bool:
     """ Determine whether a Data Label is Valid.
+ - Allows the approved non-alphanumeric chars.
+ - The exclamation point (!) is a valid DataLabel, if by itself.
+ - If a slash char is found in the string, it is invalid.
+ - Small strings (length <= 2) consisting of only punctuation are invalid.
 
 **Parameters:**
  - data_label (str): The String to check for validity.
@@ -31,52 +36,62 @@ def validate_data_label(data_label: str) -> bool:
 **Returns:**
  bool - Whether the String is a valid Data Label.
     """
-    if not 0 < len(data_label) < 100:
+    if len(data_label) < 3:
+        if '!' == data_label: # 33
+            return True
+        if data_label == '' or _is_invalid_small_tree_string(data_label):
+            return False
+    elif len(data_label) > 99:
         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()
+    for ch in data_label:
+        n = ord(ch)
+        # ALLOWED: Special Punctuation (-._) Codes: 45, 46, 95
+        # Numbers: 48 - 57
+        # UpperCase: 65 - 90
+        # LowerCase: 97 - 122
+        if not (n != 47 and 45 <= n <= 57 if n < 65 else n <= 90 or n <= 122 and (n == 95 or 97 <= n)):
+            return False
+    return True
 
 
 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.
+ str? - 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:
+    if (name_length := len(dir_name)) >= 100: # Keep Name Length Reasonable
         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 ['.', '..']:
+    # Check for slash chars
+    if (name := _filter_slash_chars(dir_name)) is not None: # Is a Dir
+        # Validate chars (parent dir, current dir)
+        if name in ['', '.', '..']:
             raise ValueError('Invalid Directory')
         return name
-    # Is a File
-    return None
+    else: # Is a File
+        return None
+
+
+def _is_invalid_small_tree_string(tree_string: str) -> bool:
+    """ Checks strings of length 1 or 2 for invalid combinations of chars that are generally valid in larger strings..
+ - The dot strings are not allowed because they may escape the DataDirectory.
+ - The permutations including line characters are not allowed, to help prevent mistakes (typos) and so on.
+ 
+**Parameters:**
+ - data_label (str): The Data Label to check, which should be of length 2 or 1.
+
+**Returns:**
+ bool - True, if the given parameter is invalid, given the specific filtering criteria.
+    """
+    return tree_string in (invalid_chars := ('.', '_', '-')) or \
+        tree_string in (''.join(repeat(x, 2)) for x in invalid_chars) or \
+        tree_string in permutations(invalid_chars, 2)
 
 
 def _validate_slash_char(dir_name: str) -> Literal['\\', '/'] | None:
@@ -87,44 +102,43 @@ def _validate_slash_char(dir_name: str) -> Literal['\\', '/'] | None:
  - dir_name (str): The given input to be validated.
 
 **Returns:**
- str | None - The slash character used, or none if no chars were found.
+ str? - The slash character used, or none if no chars were found.
 
 **Raises:**
  ValueError - When the name contains both slash characters.
     """
-    slash = None
+    slash: Literal['\\', '/'] | None = None
     if '/' in dir_name:
         slash = '/'
+        # Also check for other slash
     if '\\' in dir_name:
         if slash is not None:
-            raise ValueError('Invalid Directory slash character combination.')
+            raise ValueError('Invalid character combination: forward and back slash in the same path.')
         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.
+ - Returns None when there are no slash characters found.
 
 **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.
+ str? - The valid directory Name, or None if it may be a file (there were no slash chars found).
 
 **Raises:**
- ValueError - When the name is not suitable for directories or files.
+ ValueError - When the name is not suitable for directories or files, such as when slash characters are used improperly.
     """
-    slash = _validate_slash_char(dir_name)
-    if slash is None:
+    slash: Literal['\\', '/'] | None = _validate_slash_char(dir_name)
+    if slash is None: # No slash chars found.
         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:
+        name: str = dir_name.strip(slash)
+        if slash in name: # Has internal slash characters
             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
+    return name

{treescript_builder-0.1.3.dist-info → treescript_builder-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treescript-builder
-Version: 0.1.3
+Version: 0.1.5
 Summary: Builds File Trees from TreeScript. If DataLabels are present in TreeScript, a DataDirectory argument is required.
 Home-page: https://github.com/DK96-OS/treescript-builder
 Author: DK96-OS
@@ -13,9 +13,10 @@ Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.12
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: author
@@ -34,27 +35,70 @@ Dynamic: summary
 Script for Building File Trees.
  - Makes your dreams come true.
 
-## How To
-1. Prepare Your TreeScript Designs.
-   - Initial and Final TreeScripts.
-   - Build New Project Package/Module.
-2. Logical Order of TreeScript Builder Operations.
-3. Run TreeScript Builder from the CommandLine.
-   - Apply combinations of Operations to build TreeScript Workflows.
-
-# Project Technical Details:
+## How To Make The Most Of TreeScript
+1. Think in File Trees:
+   - Initial and Final Trees.
+   - Tree Templates for New Modules, Packages, Apps.
+   - Data Directory and Data Labels.
+2. Prepare Your TreeScript Designs.
+   - New Project in any language you want.
+   - New Feature in a New Module File Tree.
+3. Plan TreeScript Operations.
+   - Split Larger Trees into multiple TreeScript Files.
+   - Combine Trim and Build Operations in a Sequence to meet Workflow requirements.
+   - Apply other TreeScript Packages to your Workflow:
+     - [TreeScript-Diff] : Difference between two TreeScript files.
+     - [TreeScript-Files] : Convert TreeScript into a list of File Paths.
+     - [TreeScriptify] : Create TreeScript from existing File Trees.
+4. Run TreeScript, as part of your Workflow.
+   - Install; add aliases to your terminal config file, if desired.
+
+## Script Structure
+ - Directory names contain a slash char.
+ - The Indentation is 2 spaces per level.
+
+### Directory Slash Chars
+ - Both directions are accepted: `\`, `/`
+ - Start or End of the Directory Name: `\src` or `src/`
+ - No spaces between Name and char.
+
+### Example
+
+```treescript
+src/
+  __init__.py
+  dir/
+```
+
+# Project Technical Details
 
 ## File Tree Builder
 Execute the File Tree Builder with the `ftb` command.
 - Creates Files and Directories
 - If DataLabels are present, a DataDirectory is required.
 
-### File Tree Trimmer (Remover)
+## File Tree Trimmer (Remover)
 Execute the File Tree Remover by adding the `--trim` argument.
 - Removes Files and Empty Directories.
 - DataLabels require DataDirectory.
   - Files are exported to the DataDirectory. 
 
+### Builder DataLabel
+A `DataLabel` is a link to Text content to be inserted into the file.
+ - DataLabel must be present in the DataDirectory, if present in the TreeScript File.
+ - DataDirectory contents are checked during the Tree Validation phase of program execution.
+
+#### Valid DataLabels
+The range of accepted DataLabel characters has been narrowed to reduce risk.
+ - Letters: A - z
+ - Numbers: 0 - 9
+ - Punctuation: -_.
+
+#### Invalid DataLabels
+The dot directories are invalid.
+ - Current Dir: .
+ - Parent Dir: ..
+
 ## Default Input Reader
 Before the Reader receives TreeScript, the input is filtered so comments and empty lines are not ever seen by the Reader.
 The Default Input Reader processes one line at a time and calculates multiple file tree node properties that it stores in dataclass objects.
@@ -65,23 +109,18 @@ It calculates for each node:
 - Depth in tree
 - (optional) DataArgument
 
-## Builder Data Feature
-The Builder provides one additional feature that goes beyond creation of the File Tree. This feature enables Files to be created with data inserted immediately.
-
 ### Input Data Argument
 The Data Argument specifies what will be inserted into the file that is created. The Data Argument is provided in the Input File, immediately after the File Name (separated by a space). There are two types of Data Arguments:
 - DataLabel
 - InlineContent
 
-### Builder DataLabel Feature
-A `DataLabel` is a link to Text content to be inserted into the file.
- - DataLabel is present in both the DataDirectory, and the TreeScript File.
-
 ## Tree Trim Data Directory Feature
 The Remover provides an additional feature beyond the removal of files in the Tree. This feature enables Files to be saved to a Data Directory when they are removed. Rather than destroying the file data, it is moved to a new directory.
 
-
 ## To-Do Features 
+ - Append/Prepend
+ - Overwrite Prevention
+ - Inline Content
 
 ### Builder File Inline Content (TODO)
 `Inline Content` is written in the Tree Node Structure Input file itself. To distinguish `DataContent` from a `DataLabel`, the Content must begin with a special character.
@@ -94,7 +133,7 @@ This feature is a neat mid-sized improvement that may open up opportunities for
  - Adding a new file late in the process.
    - such as after data directory is already prepared, and you review TS and notice a little thing missing.
    - value-adding option that helps you build files faster, more convenient than the DataDirectory.
- - Workflows that use TreeScript.
+ - Workflows that use TreeScript:
    - Easier To Plan, and Communicate What You Did.
    - Package Restructuring, Migrations.
    - Test Environment Setup

{treescript_builder-0.1.3.dist-info → treescript_builder-0.1.5.dist-info}/RECORD

@@ -6,21 +6,21 @@ treescript_builder/data/instruction_data.py,sha256=VqJ25-1Na0b2KamuKaVDN6qGPn-8M
 treescript_builder/data/path_stack.py,sha256=QqpbrhWH3VwVqbDGBZW_CU4WGiZ6f4T7eFHzTd5zL5I,2423
 treescript_builder/data/tree_data.py,sha256=zdICXPy48ysthu9PPAse00ZHdL-Lk1PKVhUp4pMgyQU,590
 treescript_builder/data/tree_state.py,sha256=bLTwKKPYIiLMExZzzMydZpGSAotzx3_W7wyrzWfb9PQ,4451
-treescript_builder/input/__init__.py,sha256=Ue8rD6DXZF-lu4vAoZdMjHPHL27LO3XHKxlShcBptYc,920
+treescript_builder/input/__init__.py,sha256=JONsaG0Iq_w-b9BUpHPpc89DFG8sM8Dxrswb3tWvzY8,921
 treescript_builder/input/argument_data.py,sha256=PFacb8g-RXh4-RH8foW4eINms6REWpm_knaehYAICfA,806
-treescript_builder/input/argument_parser.py,sha256=SImhEs4crP9iF--5LnOVihOEPXrcEbZ_6CUXeG0mL0M,2809
-treescript_builder/input/file_validation.py,sha256=ZEdQiFOOmhIz_nDXRsdWh70cBOxfCqNkartMeAUHEEw,1494
+treescript_builder/input/argument_parser.py,sha256=ARPI-EFO5MkXSQqLjyiQPkxg-sB2jP14wf6K4y64Tog,2795
+treescript_builder/input/file_validation.py,sha256=m0zxntGDkkzWLb3PQKKsxfRSSDgd0dhK35IbaUmN_gw,2404
 treescript_builder/input/input_data.py,sha256=mP8FAI26UDRwfuEFWXsJJnw77Qxv_yjkuy4NFiTZVOg,479
 treescript_builder/input/line_reader.py,sha256=_-mWwr9bfROFP34l9d787Qr7nNSqqMnzXMRKjlIwBQA,4410
-treescript_builder/input/string_validation.py,sha256=wG4ZEDI18ztg2g-zSed4rxOAFtxkqQbaLeBOP8AwBl0,3951
+treescript_builder/input/string_validation.py,sha256=6H17UWamTPp2aBC-EVX1P58E0a-F6eD1--HH8CWrmIQ,5020
 treescript_builder/tree/__init__.py,sha256=3YgyrVcplTYEtFL9PuEM2k08LM8N8xsdRmNJR0rbA4s,1884
 treescript_builder/tree/build_validation.py,sha256=fQwNX_fovjvpq63HZ4NCYQxPrPYlmC_0gFK_LomF45I,4214
 treescript_builder/tree/tree_builder.py,sha256=0OiJ_Rjpm9Ux1DXvP4d6lHw9CoUCpu6lTfxTmLVOTfQ,1862
 treescript_builder/tree/tree_trimmer.py,sha256=4cYrnAPX4WQi9JW60K20KPWb9aAtkPYTZWeZ4scEjps,1581
 treescript_builder/tree/trim_validation.py,sha256=W5FCLBLurHSQYUanU8VmJeprL11OVa7-Z2pCZ39IchQ,3357
-treescript_builder-0.1.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-treescript_builder-0.1.3.dist-info/METADATA,sha256=A0NdpQsnMnOTksy0JRSwyOCVGL2srdWkNwuWnhw6Mic,4143
-treescript_builder-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-treescript_builder-0.1.3.dist-info/entry_points.txt,sha256=eOmYzJQPcGaH2GGBfwwU6UH_33tGtsK_ogxB4DnVrFI,111
-treescript_builder-0.1.3.dist-info/top_level.txt,sha256=parytS3LU7PXBsMVe_puiTOva14bUCzvFwcIwF_Y3Ks,19
-treescript_builder-0.1.3.dist-info/RECORD,,
+treescript_builder-0.1.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+treescript_builder-0.1.5.dist-info/METADATA,sha256=2tCtMWKlwKBvn8Exn9_YEx28qHZOQvRKPSnS0Hv8jDo,5299
+treescript_builder-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+treescript_builder-0.1.5.dist-info/entry_points.txt,sha256=eOmYzJQPcGaH2GGBfwwU6UH_33tGtsK_ogxB4DnVrFI,111
+treescript_builder-0.1.5.dist-info/top_level.txt,sha256=parytS3LU7PXBsMVe_puiTOva14bUCzvFwcIwF_Y3Ks,19
+treescript_builder-0.1.5.dist-info/RECORD,,