tactus 0.34.0__py3-none-any.whl → 0.35.0__py3-none-any.whl

tactus/utils/safe_file_library.py

@@ -34,12 +34,12 @@ class PathValidator:
         """
         self.base_path = os.path.realpath(base_path)
 
-    def validate(self, filepath: str) -> str:
+    def validate(self, file_path: str) -> str:
         """
         Validate and resolve a file path.
 
         Args:
-            filepath: Relative or absolute file path to validate.
+            file_path: Relative or absolute file path to validate.
 
         Returns:
             Resolved absolute path if valid.
@@ -48,14 +48,16 @@ class PathValidator:
             PermissionError: If path is outside the base directory.
         """
         # Join with base path and resolve to absolute
-        resolved = os.path.realpath(os.path.join(self.base_path, filepath))
+        resolved_path = os.path.realpath(os.path.join(self.base_path, file_path))
 
         # Check if resolved path is within base directory
         # Allow exact match (base_path itself) or paths that start with base_path + separator
-        if resolved != self.base_path and not resolved.startswith(self.base_path + os.sep):
-            raise PermissionError(f"Access denied: path outside working directory: {filepath}")
+        if resolved_path != self.base_path and not resolved_path.startswith(
+            self.base_path + os.sep
+        ):
+            raise PermissionError(f"Access denied: path outside working directory: {file_path}")
 
-        return resolved
+        return resolved_path
 
 
 def create_safe_file_library(base_path: str) -> Dict[str, Any]:
@@ -70,25 +72,27 @@ def create_safe_file_library(base_path: str) -> Dict[str, Any]:
     """
     validator = PathValidator(base_path)
 
-    def read(filepath: str) -> str:
+    def read(file_path: str) -> str:
         """Read entire file as text."""
-        path = validator.validate(filepath)
-        with open(path, "r", encoding="utf-8") as f:
-            return f.read()
+        validated_path = validator.validate(file_path)
+        with open(validated_path, "r", encoding="utf-8") as file_handle:
+            return file_handle.read()
 
-    def write(filepath: str, content: str) -> None:
+    def write(file_path: str, content: str) -> None:
         """Write text to file."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
         # Ensure parent directory exists
-        os.makedirs(os.path.dirname(path), exist_ok=True) if os.path.dirname(path) else None
-        with open(path, "w", encoding="utf-8") as f:
-            f.write(content)
+        parent_directory = os.path.dirname(validated_path)
+        if parent_directory:
+            os.makedirs(parent_directory, exist_ok=True)
+        with open(validated_path, "w", encoding="utf-8") as file_handle:
+            file_handle.write(content)
 
-    def exists(filepath: str) -> bool:
+    def exists(file_path: str) -> bool:
         """Check if file exists."""
         try:
-            path = validator.validate(filepath)
-            return os.path.exists(path)
+            validated_path = validator.validate(file_path)
+            return os.path.exists(validated_path)
         except PermissionError:
             return False
 
@@ -106,20 +110,20 @@ class LuaList:
     def __init__(self, data: List):
         self._data = data
 
-    def __getitem__(self, index):
+    def __getitem__(self, key_or_index):
         # Lua method access comes through __getitem__ with string keys
-        if isinstance(index, str):
+        if isinstance(key_or_index, str):
             # Handle method access
-            if index == "len":
+            if key_or_index == "len":
                 return self.len
-            elif index == "get":
+            elif key_or_index == "get":
                 return self.get
             else:
-                raise KeyError(f"Unknown method: {index}")
+                raise KeyError(f"Unknown method: {key_or_index}")
         # Lua numbers are floats, convert to int for indexing
-        if isinstance(index, float):
-            index = int(index)
-        return self._data[index]
+        if isinstance(key_or_index, float):
+            key_or_index = int(key_or_index)
+        return self._data[key_or_index]
 
     def __len__(self):
         return len(self._data)
@@ -131,11 +135,11 @@ class LuaList:
         """Return length - callable from Lua as data:len()."""
         return len(self._data)
 
-    def get(self, index):
+    def get(self, requested_index):
         """Alternative access method - data:get(0) instead of data[0]."""
-        if isinstance(index, float):
-            index = int(index)
-        return self._data[index]
+        if isinstance(requested_index, float):
+            requested_index = int(requested_index)
+        return self._data[requested_index]
 
 
 def create_safe_csv_library(base_path: str) -> Dict[str, Any]:
@@ -150,46 +154,48 @@ def create_safe_csv_library(base_path: str) -> Dict[str, Any]:
     """
     validator = PathValidator(base_path)
 
-    def read(filepath: str) -> LuaList:
+    def read(file_path: str) -> LuaList:
         """Read CSV file, returning list of dictionaries with headers as keys."""
-        path = validator.validate(filepath)
-        with open(path, "r", encoding="utf-8", newline="") as f:
-            reader = csv.DictReader(f)
+        validated_path = validator.validate(file_path)
+        with open(validated_path, "r", encoding="utf-8", newline="") as file_handle:
+            reader = csv.DictReader(file_handle)
             return LuaList(list(reader))
 
-    def write(filepath: str, data: List[Dict], options: Optional[Dict] = None) -> None:
+    def write(file_path: str, data: List[Dict], options: Optional[Dict] = None) -> None:
         """Write list of dictionaries to CSV file."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
 
         # Convert Lua table options to Python dict if needed
         if options and hasattr(options, "items"):
             options = dict(options.items())
         options = options or {}
-        headers = options.get("headers")
+        header_row = options.get("headers")
 
         # Convert headers from Lua table to Python list if needed
-        if headers and hasattr(headers, "values"):
-            headers = list(headers.values())
+        if header_row and hasattr(header_row, "values"):
+            header_row = list(header_row.values())
 
         # Convert Lua table to Python list if needed
         if hasattr(data, "values"):
             data = list(data.values())
 
-        if not headers and data:
+        if not header_row and data:
             # Get headers from first row
             first_row = data[0]
             if hasattr(first_row, "keys"):
-                headers = list(first_row.keys())
+                header_row = list(first_row.keys())
             elif isinstance(first_row, dict):
-                headers = list(first_row.keys())
+                header_row = list(first_row.keys())
             else:
                 raise ValueError("Cannot determine headers from data")
 
         # Ensure parent directory exists
-        os.makedirs(os.path.dirname(path), exist_ok=True) if os.path.dirname(path) else None
+        parent_directory = os.path.dirname(validated_path)
+        if parent_directory:
+            os.makedirs(parent_directory, exist_ok=True)
 
-        with open(path, "w", encoding="utf-8", newline="") as f:
-            writer = csv.DictWriter(f, fieldnames=headers)
+        with open(validated_path, "w", encoding="utf-8", newline="") as file_handle:
+            writer = csv.DictWriter(file_handle, fieldnames=header_row)
             writer.writeheader()
             for row in data:
                 # Convert Lua table to dict if needed
@@ -212,45 +218,51 @@ def create_safe_tsv_library(base_path: str) -> Dict[str, Any]:
     """
     validator = PathValidator(base_path)
 
-    def read(filepath: str) -> LuaList:
+    def read(file_path: str) -> LuaList:
         """Read TSV file, returning list of dictionaries with headers as keys."""
-        path = validator.validate(filepath)
-        with open(path, "r", encoding="utf-8", newline="") as f:
-            reader = csv.DictReader(f, delimiter="\t")
+        validated_path = validator.validate(file_path)
+        with open(validated_path, "r", encoding="utf-8", newline="") as file_handle:
+            reader = csv.DictReader(file_handle, delimiter="\t")
             return LuaList(list(reader))
 
-    def write(filepath: str, data: List[Dict], options: Optional[Dict] = None) -> None:
+    def write(file_path: str, data: List[Dict], options: Optional[Dict] = None) -> None:
         """Write list of dictionaries to TSV file."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
 
         # Convert Lua table options to Python dict if needed
         if options and hasattr(options, "items"):
             options = dict(options.items())
         options = options or {}
-        headers = options.get("headers")
+        header_row = options.get("headers")
 
         # Convert headers from Lua table to Python list if needed
-        if headers and hasattr(headers, "values"):
-            headers = list(headers.values())
+        if header_row and hasattr(header_row, "values"):
+            header_row = list(header_row.values())
 
         # Convert Lua table to Python list if needed
         if hasattr(data, "values"):
             data = list(data.values())
 
-        if not headers and data:
+        if not header_row and data:
             first_row = data[0]
             if hasattr(first_row, "keys"):
-                headers = list(first_row.keys())
+                header_row = list(first_row.keys())
             elif isinstance(first_row, dict):
-                headers = list(first_row.keys())
+                header_row = list(first_row.keys())
             else:
                 raise ValueError("Cannot determine headers from data")
 
         # Ensure parent directory exists
-        os.makedirs(os.path.dirname(path), exist_ok=True) if os.path.dirname(path) else None
-
-        with open(path, "w", encoding="utf-8", newline="") as f:
-            writer = csv.DictWriter(f, fieldnames=headers, delimiter="\t")
+        parent_directory = os.path.dirname(validated_path)
+        if parent_directory:
+            os.makedirs(parent_directory, exist_ok=True)
+
+        with open(validated_path, "w", encoding="utf-8", newline="") as file_handle:
+            writer = csv.DictWriter(
+                file_handle,
+                fieldnames=header_row,
+                delimiter="\t",
+            )
             writer.writeheader()
             for row in data:
                 if hasattr(row, "items"):
@@ -272,15 +284,15 @@ def create_safe_json_library(base_path: str) -> Dict[str, Any]:
     """
     validator = PathValidator(base_path)
 
-    def read(filepath: str) -> Any:
+    def read(file_path: str) -> Any:
         """Read JSON file and return parsed data."""
-        path = validator.validate(filepath)
-        with open(path, "r", encoding="utf-8") as f:
-            return json.load(f)
+        validated_path = validator.validate(file_path)
+        with open(validated_path, "r", encoding="utf-8") as file_handle:
+            return json.load(file_handle)
 
-    def write(filepath: str, data: Any, options: Optional[Dict] = None) -> None:
+    def write(file_path: str, data: Any, options: Optional[Dict] = None) -> None:
         """Write data to JSON file."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
 
         # Convert Lua table options to Python dict if needed
         if options and hasattr(options, "items"):
@@ -292,10 +304,12 @@ def create_safe_json_library(base_path: str) -> Dict[str, Any]:
         data = _lua_to_python(data)
 
         # Ensure parent directory exists
-        os.makedirs(os.path.dirname(path), exist_ok=True) if os.path.dirname(path) else None
+        parent_directory = os.path.dirname(validated_path)
+        if parent_directory:
+            os.makedirs(parent_directory, exist_ok=True)
 
-        with open(path, "w", encoding="utf-8") as f:
-            json.dump(data, f, indent=indent, default=str)
+        with open(validated_path, "w", encoding="utf-8") as file_handle:
+            json.dump(data, file_handle, indent=indent, default=str)
 
     return {"read": read, "write": write}
 
@@ -315,24 +329,26 @@ def create_safe_parquet_library(base_path: str) -> Dict[str, Any]:
 
     validator = PathValidator(base_path)
 
-    def read(filepath: str) -> LuaList:
+    def read(file_path: str) -> LuaList:
         """Read Parquet file, returning list of dictionaries."""
-        path = validator.validate(filepath)
-        table = pq.read_table(path)
+        validated_path = validator.validate(file_path)
+        table = pq.read_table(validated_path)
         return LuaList(table.to_pylist())
 
-    def write(filepath: str, data: List[Dict]) -> None:
+    def write(file_path: str, data: List[Dict]) -> None:
         """Write list of dictionaries to Parquet file."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
 
         # Convert Lua tables to Python
         data = _lua_to_python(data)
 
         # Ensure parent directory exists
-        os.makedirs(os.path.dirname(path), exist_ok=True) if os.path.dirname(path) else None
+        parent_directory = os.path.dirname(validated_path)
+        if parent_directory:
+            os.makedirs(parent_directory, exist_ok=True)
 
         table = pa.Table.from_pylist(data)
-        pq.write_table(table, path)
+        pq.write_table(table, validated_path)
 
     return {"read": read, "write": write}
 
@@ -352,38 +368,40 @@ def create_safe_hdf5_library(base_path: str) -> Dict[str, Any]:
 
     validator = PathValidator(base_path)
 
-    def read(filepath: str, dataset: str) -> List[Any]:
+    def read(file_path: str, dataset: str) -> List[Any]:
         """Read dataset from HDF5 file."""
-        path = validator.validate(filepath)
-        with h5py.File(path, "r") as f:
-            return f[dataset][:].tolist()
+        validated_path = validator.validate(file_path)
+        with h5py.File(validated_path, "r") as hdf5_file:
+            return hdf5_file[dataset][:].tolist()
 
-    def write(filepath: str, dataset: str, data: List) -> None:
+    def write(file_path: str, dataset: str, data: List) -> None:
         """Write data to HDF5 dataset."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
 
         # Convert Lua tables to Python
         data = _lua_to_python(data)
 
         # Ensure parent directory exists
-        os.makedirs(os.path.dirname(path), exist_ok=True) if os.path.dirname(path) else None
+        parent_directory = os.path.dirname(validated_path)
+        if parent_directory:
+            os.makedirs(parent_directory, exist_ok=True)
 
-        with h5py.File(path, "a") as f:
-            if dataset in f:
-                del f[dataset]
-            f.create_dataset(dataset, data=np.array(data))
+        with h5py.File(validated_path, "a") as hdf5_file:
+            if dataset in hdf5_file:
+                del hdf5_file[dataset]
+            hdf5_file.create_dataset(dataset, data=np.array(data))
 
-    def list_datasets(filepath: str) -> List[str]:
+    def list_datasets(file_path: str) -> List[str]:
         """List all datasets in HDF5 file."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
         datasets = []
-        with h5py.File(path, "r") as f:
+        with h5py.File(validated_path, "r") as hdf5_file:
 
-            def visitor(name, obj):
-                if isinstance(obj, h5py.Dataset):
+            def visitor(name: str, hdf5_object: Any) -> None:
+                if isinstance(hdf5_object, h5py.Dataset):
                     datasets.append(name)
 
-            f.visititems(visitor)
+            hdf5_file.visititems(visitor)
         return datasets
 
     return {"read": read, "write": write, "list": list_datasets}
@@ -403,9 +421,9 @@ def create_safe_excel_library(base_path: str) -> Dict[str, Any]:
 
     validator = PathValidator(base_path)
 
-    def read(filepath: str, options: Optional[Dict] = None) -> LuaList:
+    def read(file_path: str, options: Optional[Dict] = None) -> LuaList:
         """Read Excel file, returning list of dictionaries."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
 
         # Convert Lua table options to Python dict if needed
         if options and hasattr(options, "items"):
@@ -413,20 +431,24 @@ def create_safe_excel_library(base_path: str) -> Dict[str, Any]:
         options = options or {}
         sheet_name = options.get("sheet")
 
-        wb = load_workbook(path, read_only=True, data_only=True)
-        ws = wb[sheet_name] if sheet_name else wb.active
+        workbook = load_workbook(validated_path, read_only=True, data_only=True)
+        worksheet = workbook[sheet_name] if sheet_name else workbook.active
 
-        rows = list(ws.iter_rows(values_only=True))
+        rows = list(worksheet.iter_rows(values_only=True))
         if not rows:
             return LuaList([])
 
         # First row is headers
-        headers = [str(h) if h is not None else f"col_{i}" for i, h in enumerate(rows[0])]
-        return LuaList([dict(zip(headers, row)) for row in rows[1:]])
-
-    def write(filepath: str, data: List[Dict], options: Optional[Dict] = None) -> None:
+        header_row = [
+            str(header_value) if header_value is not None else f"col_{index}"
+            for index, header_value in enumerate(rows[0])
+        ]
+        data_rows = rows[1:]
+        return LuaList([dict(zip(header_row, row_values)) for row_values in data_rows])
+
+    def write(file_path: str, data: List[Dict], options: Optional[Dict] = None) -> None:
         """Write list of dictionaries to Excel file."""
-        path = validator.validate(filepath)
+        validated_path = validator.validate(file_path)
 
         # Convert Lua table options to Python dict if needed
         if options and hasattr(options, "items"):
@@ -438,65 +460,67 @@ def create_safe_excel_library(base_path: str) -> Dict[str, Any]:
         data = _lua_to_python(data)
 
         # Ensure parent directory exists
-        os.makedirs(os.path.dirname(path), exist_ok=True) if os.path.dirname(path) else None
+        parent_directory = os.path.dirname(validated_path)
+        if parent_directory:
+            os.makedirs(parent_directory, exist_ok=True)
 
-        wb = Workbook()
-        ws = wb.active
-        ws.title = sheet_name
+        workbook = Workbook()
+        worksheet = workbook.active
+        worksheet.title = sheet_name
 
         if data:
-            headers = list(data[0].keys())
-            ws.append(headers)
+            header_row = list(data[0].keys())
+            worksheet.append(header_row)
             for row in data:
-                ws.append([row.get(h) for h in headers])
+                worksheet.append([row.get(header) for header in header_row])
 
-        wb.save(path)
+        workbook.save(validated_path)
 
-    def sheets(filepath: str) -> List[str]:
+    def sheets(file_path: str) -> List[str]:
         """List sheet names in Excel file."""
-        path = validator.validate(filepath)
-        wb = load_workbook(path, read_only=True)
-        return wb.sheetnames
+        validated_path = validator.validate(file_path)
+        workbook = load_workbook(validated_path, read_only=True)
+        return workbook.sheetnames
 
     return {"read": read, "write": write, "sheets": sheets}
 
 
-def _lua_to_python(obj: Any) -> Any:
+def _lua_to_python(value: Any) -> Any:
     """
     Recursively convert Lua table-like objects to Python dicts/lists.
 
     Args:
-        obj: Object to convert (may be Lua table or Python object).
+        value: Object to convert (may be Lua table or Python object).
 
     Returns:
         Python dict, list, or original value.
     """
     # Check if it's a Lua table (has values() or items() method)
-    if hasattr(obj, "items"):
+    if hasattr(value, "items"):
         # Could be a dict-like Lua table
         try:
-            items = list(obj.items())
+            lua_items = list(value.items())
             # Check if it's array-like (all integer keys starting from 1)
-            if items and all(isinstance(k, (int, float)) for k, v in items):
-                keys = [int(k) for k, v in items]
-                if keys == list(range(1, len(keys) + 1)):
+            if lua_items and all(isinstance(key, (int, float)) for key, _ in lua_items):
+                lua_keys = [int(key) for key, _ in lua_items]
+                if lua_keys == list(range(1, len(lua_keys) + 1)):
                     # It's an array-like table, convert to list
-                    return [_lua_to_python(obj[k]) for k in range(1, len(keys) + 1)]
+                    return [_lua_to_python(value[key]) for key in range(1, len(lua_keys) + 1)]
             # It's a dict-like table
-            return {k: _lua_to_python(v) for k, v in items}
+            return {key: _lua_to_python(item) for key, item in lua_items}
         except (TypeError, AttributeError):
             pass
 
-    if hasattr(obj, "values") and not isinstance(obj, (dict, str)):
+    if hasattr(value, "values") and not isinstance(value, (dict, str)):
         try:
-            return [_lua_to_python(v) for v in obj.values()]
+            return [_lua_to_python(item) for item in value.values()]
         except (TypeError, AttributeError):
             pass
 
-    if isinstance(obj, dict):
-        return {k: _lua_to_python(v) for k, v in obj.items()}
+    if isinstance(value, dict):
+        return {key: _lua_to_python(item) for key, item in value.items()}
 
-    if isinstance(obj, list):
-        return [_lua_to_python(item) for item in obj]
+    if isinstance(value, list):
+        return [_lua_to_python(item) for item in value]
 
-    return obj
+    return value