abstract-utilities 0.2.2.513__py3-none-any.whl → 0.2.2.583__py3-none-any.whl

abstract_utilities/class_utils/caller_utils.py

@@ -1,4 +1,22 @@
 from .imports import *
+
+def get_initial_caller() -> str:
+    """
+    Return the TRUE original caller: the entrypoint script that launched the program.
+    """
+    main_mod = sys.modules.get('__main__')
+    
+    # interactive environments (REPL) may have no __file__
+    if not main_mod or not hasattr(main_mod, '__file__'):
+        return None
+
+    return os.path.realpath(main_mod.__file__)
+def get_initial_caller_dir() -> str:
+    """
+    Return the directory of the TRUE original entrypoint script.
+    """
+    caller = get_initial_caller()
+    return os.path.dirname(caller) if caller else None
 def get_caller(i: Optional[int] = None) -> str:
     """
     Return the filename of the calling frame.

abstract_utilities/class_utils/global_utils.py

@@ -48,9 +48,10 @@ def change_glob(var: str, val: any, glob: dict = return_globals()) -> any:
 def get_globes(string:str='',glob:dict=return_globals()):
     if string in glob:
         return glob[string]
-def if_none_default(string:str, default:any,glob:dict=return_globals()):
+def if_none_default(string:str, default:any,glob:dict=return_globals(),typ=None):
+    
     piece = get_globes(string=string,glob=glob)
-    if piece is None:
+    if piece is None or (typ and not isinstance(piece,typ)):
         piece = default
     return change_glob(var=string,val=piece,glob=glob)
 

abstract_utilities/class_utils/imports/imports.py

@@ -1,2 +1,2 @@
-from ...imports import inspect,os,json,functools,inspect,glob
+from ...imports import inspect,os,json,functools,inspect,glob,sys
 from typing import *

abstract_utilities/directory_utils/__init__.py

@@ -1,4 +1,2 @@
-from .directory_utils import *
-from .name_utils import *
-from .utils import *
-from .size_utils import *
+from .imports import *
+from .src import *

abstract_utilities/directory_utils/imports/__init__.py

@@ -0,0 +1,2 @@
+from .imports import *
+from .module_imports import *

abstract_utilities/directory_utils/imports/imports.py

@@ -0,0 +1 @@
+from ...imports import os,shlex

abstract_utilities/directory_utils/imports/module_imports.py

@@ -0,0 +1,2 @@
+from ...safe_utils import safe_join
+from ...ssh_utils import is_file

abstract_utilities/directory_utils/src/__init__.py

@@ -0,0 +1,4 @@
+from .directory_utils import *
+from .name_utils import *
+from .utils import *
+from .size_utils import *

abstract_utilities/directory_utils/src/directory_utils.py

@@ -0,0 +1,108 @@
+from pathlib import Path
+from .utils import *
+
+def get_shortest_path(*args):
+    shortest = None
+    args = {arg:str(arg).split('/') for arg in args if arg}
+    for path,spl in args.items():
+        if shortest is None or (len(spl)<len(shortest[-1])):
+            shortest=[path,spl]
+    return shortest[0]
+def get_common_root(paths):
+    """
+    Compute the deepest common parent directory of all sysroots.
+    """
+    paths = [Path(p).resolve() for p in paths]
+    common = os.path.commonpath(paths)
+    return common
+
+def get_dirs(path):
+    """
+    Get List of Immediate Subdirectories in a Path
+
+    This function uses the os.walk method to traverse through a directory tree and returns a list of immediate subdirectories
+    within the specified path.
+
+    Parameters:
+    - path (str): The path for which subdirectories need to be retrieved.
+
+    Returns:
+    - subdirectories (list): A list of immediate subdirectories within the specified path.
+
+    Example:
+    subdirs = get_dirs("/path/to/directory")
+    print("Immediate Subdirectories:", subdirs)
+    """
+    from os import walk
+    for (dirpath, dirnames, filenames) in walk(path):
+        return dirnames
+def get_directory(file_path: str) -> str:
+    """
+    Extracts and returns the directory path from a given file path.
+
+    Args:
+        file_path (str): A string representing the file path.
+
+    Returns:
+        str: The directory path extracted from the file path.
+    """
+    return os.path.dirname(file_path)
+def if_not_last_child_join(path:str,child:str):
+    """
+    Adds a child path to the given path if it's not already present at the end.
+
+    Args:
+        path (str): The parent path.
+        child (str): The child path to add.
+    
+    Returns:
+        str: The updated path.
+    """
+    if path.endswith(child):
+        return path
+    return simple_path_join(path, child)
+def createFolds(ls: list) -> None:
+    """
+    Creates multiple directories.
+
+    Args:
+        ls (list): The list of directory paths to create.
+    """
+    for k in range(len(ls)):
+        mkdirs(ls[k])
+def list_directory_contents(path: str) -> list:
+    """Returns a list of directory contents or a list with a single file, if the path is a file.
+
+    Args:
+        path (str): The path of the directory or file.
+
+    Returns:
+        list: A list of directory contents or a list with a single file path.
+    """
+    if is_file(path):
+        return [path]
+    elif is_valid_path(path):
+        return os.listdir(path)
+    return [path]
+def is_string_in_dir(path,strings,**kwargs):
+    dirname =  path
+    if is_file(path,**kwargs):
+        dirname = os.path.dirname(path)
+    pieces = [pa for pa in dirname.split('/') if pa and pa in strings]
+    if pieces:
+        return True
+    return False
+def raw_create_dirs(*paths):
+    """Recursively create all directories along the given path."""
+    full_path = os.path.abspath(safe_join(*paths))
+    sub_parts = [p for p in full_path.split(os.sep) if p]
+
+    current_path = "/" if full_path.startswith(os.sep) else ""
+    for part in sub_parts:
+        current_path = safe_join(current_path, part)
+        os.makedirs(current_path, exist_ok=True)
+    return full_path
+mkdirs=raw_create_dirs
+makedirs = mkdirs
+make_dirs = makedirs
+

abstract_utilities/directory_utils/src/name_utils.py

@@ -0,0 +1,43 @@
+from ..imports import *
+from .directory_utils import *
+def get_file_name(file_path: str) -> str:
+    """
+    Retrieves and returns the base name of a file from a given file path.
+
+    Args:
+        file_path (str): A string representing the file path.
+
+    Returns:
+        str: The base name of the file (without extension).
+    """
+    return split_text(get_base_name(file_path))[0]
+def get_abs_name_of_this():
+    """
+    Returns the absolute name of the current module.
+
+    Returns:
+        Path: The absolute name of the current module.
+    """
+    return os.path.abspath(__name__)
+def sanitize_filename(name: str):
+    """
+    Sanitize a filename by removing invalid characters.
+    
+    Args:
+    name (str): Filename to sanitize.
+    
+    Returns:
+    str: Sanitized filename.
+    """
+    return re.sub(r'[\\/*?:"<>|]', "", name)
+def get_base_name(file_path: str) -> str:
+    """
+    Extracts and returns the base name of a file from a given file path.
+
+    Args:
+        file_path (str): A string representing the file path.
+
+    Returns:
+        str: The base name of the file.
+    """
+    return os.path.basename(file_path)

abstract_utilities/directory_utils/src/size_utils.py

@@ -0,0 +1,57 @@
+from ..imports import *
+from .name_utils import *
+def get_os_info():
+    """
+    Get Operating System Information
+
+    This function retrieves information about the current operating system, including its name and bit size.
+
+    Returns:
+    - os_info (dict): A dictionary containing the operating system information.
+                      Keys:
+                      - "operating_system" (str): The name of the operating system (e.g., "Windows", "Linux", "Darwin").
+                      - "bit_size" (str): The bit size of the operating system (e.g., "32bit", "64bit").
+
+    Example:
+    os_info = get_os_info()
+    print("Operating System:", os_info["operating_system"])
+    print("Bit Size:", os_info["bit_size"])
+    """
+    os_name = platform.system()
+    bit_size = platform.architecture()[0]
+    return {"operating_system": os_name, "bit_size": bit_size}
+def mkGb(k) -> float:
+    """
+    Converts a value to Gigabytes (GB).
+
+    Args:
+        k (float): The value to convert to GB.
+
+    Returns:
+        float: The value converted to GB.
+    """
+    return float(float(k)*(10**9))
+
+def mkGbTrunk(k) -> float:
+    """
+    Converts a value to Gigabytes (GB) and truncates the result to five decimal places.
+
+    Args:
+        k (float): The value to convert to GB.
+
+    Returns:
+        float: The value converted to GB and truncated to five decimal places.
+    """
+    return trunc(mkGb(k), 5)
+
+def mkGbTrunFroPathTot(k) -> float:
+    """
+    Fetches the file size from a path, converts it to Gigabytes (GB) and truncates the result to five decimal places.
+
+    Args:
+        k (str): The file path.
+
+    Returns:
+        float: The file size converted to GB and truncated to five decimal places.
+    """
+    return trunc(mkGb(s.path.getsize(k)), 5)

abstract_utilities/directory_utils/src/utils.py

@@ -0,0 +1,116 @@
+from ..imports import *
+def split_text(string: str) -> tuple:
+    """
+    Splits a string into its base name and extension and returns them as a tuple.
+
+    Args:
+        string (str): A string to be split, typically representing a file name.
+
+    Returns:
+        tuple: A tuple containing the base name and extension of the input string.
+    """
+    return os.path.splitext(string)
+def get_ext(file_path: str) -> str:
+    """
+    Retrieves and returns the extension of a file from a given file path.
+
+    Args:
+        file_path (str): A string representing the file path.
+
+    Returns:
+        str: The extension of the file (including the dot).
+    """
+    return split_text(get_base_name(file_path))[1]
+
+def get_slash():
+    """
+    Returns the appropriate file path separator depending on the current operating system.
+    """
+    slash = '/'  # Assume a Unix-like system by default
+    if slash not in get_current_path():
+        slash = '\\'  # Use backslash for Windows systems
+    return slash
+def get_current_path():
+    """
+    Returns the current working directory.
+    
+    Returns:
+        str: The current working directory.
+    """
+    return os.getcwd()
+
+def get_home_folder():
+    """
+    Returns the path to the home directory of the current user.
+    
+    Returns:
+        str: The path to the home directory.
+    """
+    return os.path.expanduser("~")
+def simple_path_join(path_A:str, path_B:str):
+    """
+    Join two paths using the appropriate file path separator.
+
+    Args:
+        path_A (str): The first path to join.
+        path_B (str): The second path to join.
+    
+    Returns:
+        str: The joined path.
+    """
+    return os.path.join(str(path_A), str(path_B))
+
+def path_join(path_A, path_B=None):
+    """
+    Joins two paths or a list of paths using the appropriate file path separator.
+
+    Args:
+        path_A (str or list): The first path or list of paths to join.
+        path_B (str, optional): The second path to join. Defaults to None.
+    
+    Returns:
+        str: The joined path.
+    """
+    if path_B is not None:  # If path_B is provided, join path_A and path_B
+        return simple_path_join(path_A, path_B)
+    if isinstance(path_A, list):  # If path_A is a list, join all paths in the list
+        path = path_A[0]
+        for k in range(1, len(path_A)):
+            path = simple_path_join(path, path_A[k])
+        return path
+def update_global_variable(name: str, value) -> None:
+    """Updates the global variable with the provided name and value.
+
+    Args:
+        name (str): The name of the global variable.
+        value: The value to assign to the global variable.
+
+    Returns:
+        None
+    """
+    globals()[name] = value
+
+
+def trunc(a: float, x: int) -> float:
+    """
+    Truncates a float number to a specific number of decimal places.
+
+    Args:
+        a (float): The number to truncate.
+        x (int): The number of decimal places to retain.
+
+    Returns:
+        float: The truncated float number.
+    """
+    temp = str(a)
+    for i in range(len(temp)):
+        if temp[i] == '.':
+            try:
+                return float(temp[:i+x+1])
+            except:
+                return float(temp)
+    return float(temp)
+
+
+
+

abstract_utilities/file_utils/imports/constants.py

@@ -1,15 +1,40 @@
 from .imports import *
 from .module_imports import *
+# -------------------------
+# Config dataclass
+# -------------------------
+
 @dataclass
 class ScanConfig:
     allowed_exts: Set[str]
-    unallowed_exts: Set[str]
+    exclude_exts: Set[str]
     allowed_types: Set[str]
     exclude_types: Set[str]
     allowed_dirs: List[str] = field(default_factory=list)
     exclude_dirs: List[str] = field(default_factory=list)
     allowed_patterns: List[str] = field(default_factory=list)
     exclude_patterns: List[str] = field(default_factory=list)
+
+@dataclass
+class SearchParams(ScanConfig):
+    directories: List[str] = field(default_factory=list)
+    add: bool = False
+    recursive: bool = True
+    strings: List[str] = field(default_factory=list)
+    total_strings: bool = False
+    parse_lines: bool = False
+    spec_line: Union[bool, int] = False
+    get_lines: bool = False
+
+@dataclass
+class AllParams(SearchParams):
+    cfg = None
+    allowed: Optional[Callable[[str], bool]] = None
+    include_files: bool = True
+    recursive: bool = True
+# -------------------------
+# Default sets
+# -------------------------
 DEFAULT_ALLOWED_EXTS: Set[str] = {
     ".py", ".pyw",                             # python
     ".js", ".jsx", ".ts", ".tsx", ".mjs",      # JS/TS
@@ -27,11 +52,15 @@ DEFAULT_EXCLUDE_TYPES: Set[str] = {
 }
 
 # never want these—even if they sneak into ALLOWED
-_unallowed = set(get_media_exts(DEFAULT_EXCLUDE_TYPES)) | {'.bak', '.shp', '.cpg', '.dbf', '.shx','.geojson',".pyc",'.shx','.geojson','.prj','.sbn','.sbx'}
-DEFAULT_UNALLOWED_EXTS = {e for e in _unallowed if e not in DEFAULT_ALLOWED_EXTS}
+_unallowed = set(get_media_exts(DEFAULT_EXCLUDE_TYPES)) | {
+    ".bak", ".shp", ".cpg", ".dbf", ".shx", ".geojson",
+    ".pyc", ".prj", ".sbn", ".sbx"
+}
+DEFAULT_EXCLUDE_EXTS = {e.split('.')[-1] for e in _unallowed if e not in DEFAULT_ALLOWED_EXTS}
 
 DEFAULT_EXCLUDE_DIRS: Set[str] = {
-    "node_modules", "old","__pycache__", "backups", "backup", "backs", "trash", "depriciated", "old", "__init__"
+    "node_modules", "old","__pycache__", "backups", "backup",
+    "backs", "trash", "depriciated", "old", "__init__"
 }
 
 DEFAULT_EXCLUDE_PATTERNS: Set[str] = {
@@ -40,6 +69,51 @@ DEFAULT_EXCLUDE_PATTERNS: Set[str] = {
 REMOTE_RE = re.compile(r"^(?P<host>[^:\s]+@[^:\s]+):(?P<path>/.*)$")
 AllowedPredicate = Optional[Callable[[str], bool]]
 DEFAULT_EXCLUDE_FILE_PATTERNS=DEFAULT_EXCLUDE_PATTERNS
-DEFAULT_ALLOWED_PATTENS="*"
-DEFAULT_ALLOWED_DIRS="*"
-DEFAULT_ALLOWED_TYPES="*"
+DEFAULT_ALLOWED_PATTERNS: List[str] = ["*"]
+DEFAULT_ALLOWED_DIRS: List[str] = ["*"]
+DEFAULT_ALLOWED_TYPES: List[str] = ["*"]
+CANONICAL_MAP = {
+    "directories": ["directory", "directories", "dir","dirs","directory","directories","d","dirname", "paths", "path","roots","root"],
+    "files":["file","filepath","file_path","files","filepaths","file_paths","paths", "path","f"],
+    "allowed_exts": ["allow_ext", "allowed_ext", "include_ext", "include_exts", "exts_allowed"],
+    "exclude_exts": ["exclude_ext", "excluded_ext", "excluded_exts", "unallowed_ext", "unallowed_exts"],
+    "allowed_types": ["allow_type", "allowed_type", "include_type", "include_types", "types_allowed"],
+    "exclude_types": ["exclude_type", "excluded_type", "excluded_types", "unallowed_type", "unallowed_types"],
+    "allowed_dirs": ["allow_dir", "allowed_dir", "include_dir", "include_dirs", "dirs_allowed"],
+    "exclude_dirs": ["exclude_dir", "excluded_dir", "excluded_dirs", "unallowed_dir", "unallowed_dirs"],
+    "allowed_patterns": ["allow_pattern", "allowed_pattern", "include_pattern", "include_patterns", "patterns_allowed"],
+    "exclude_patterns": ["exclude_pattern", "excluded_pattern", "excluded_patterns", "unallowed_pattern", "unallowed_patterns"],
+    "add":["add"],
+    "cfg":["cfg"],
+    "recursive":["recursive"],
+    "strings":["strings"],
+    "total_strings":["total_strings"],
+    "parse_lines":["parse_lines"],
+    "spec_line":["spec_line"],
+    "get_lines":["get_lines"]
+}
+DEFAULT_ALLOWED_EXCLUDE_MAP={
+    "allowed_exts": {"default":DEFAULT_ALLOWED_EXTS,"type":type(DEFAULT_ALLOWED_EXTS),"canonical":CANONICAL_MAP.get("allowed_exts")},
+    "exclude_exts": {"default":DEFAULT_EXCLUDE_EXTS,"type":type(DEFAULT_EXCLUDE_EXTS),"canonical":CANONICAL_MAP.get("exclude_exts")},
+    "allowed_types": {"default":DEFAULT_ALLOWED_TYPES,"type":type(DEFAULT_ALLOWED_TYPES),"canonical":CANONICAL_MAP.get("allowed_types")},
+    "exclude_types": {"default":DEFAULT_EXCLUDE_TYPES,"type":type(DEFAULT_EXCLUDE_TYPES),"canonical":CANONICAL_MAP.get("exclude_types")},
+    "allowed_dirs": {"default":DEFAULT_ALLOWED_DIRS,"type":type(DEFAULT_ALLOWED_DIRS),"canonical":CANONICAL_MAP.get("allowed_dirs")},
+    "exclude_dirs": {"default":DEFAULT_EXCLUDE_DIRS,"type":type(DEFAULT_EXCLUDE_DIRS),"canonical":CANONICAL_MAP.get("exclude_dirs")},
+    "allowed_patterns": {"default":DEFAULT_ALLOWED_PATTERNS,"type":type(DEFAULT_ALLOWED_PATTERNS),"canonical":CANONICAL_MAP.get("allowed_patterns")},
+    "exclude_patterns": {"default":DEFAULT_EXCLUDE_PATTERNS,"type":type(DEFAULT_EXCLUDE_PATTERNS),"canonical":CANONICAL_MAP.get("exclude_patterns")},
+}
+DEFAULT_CANONICAL_MAP={
+    "directories":{"default":[],"type":list,"canonical":CANONICAL_MAP.get("directories")},
+    "files":{"default":[],"type":list,"canonical":CANONICAL_MAP.get("files")},
+    **DEFAULT_ALLOWED_EXCLUDE_MAP,
+    "allowed":{"default":None,"type":bool,"canonical":CANONICAL_MAP.get("allowed")},
+    "add":{"default":False,"type":bool,"canonical":CANONICAL_MAP.get("add")},
+    "recursive":{"default":True,"type":bool,"canonical":CANONICAL_MAP.get("recursive")},
+    "strings":{"default":None,"type":list,"canonical":CANONICAL_MAP.get("strings")},
+    "total_strings":{"default":False,"type":bool,"canonical":CANONICAL_MAP.get("total_strings")},
+    "parse_lines":{"default":False,"type":bool,"canonical":CANONICAL_MAP.get("parse_lines")},
+    "spec_line":{"default":False,"type":bool,"canonical":CANONICAL_MAP.get("spec_line")},
+    "get_lines":{"default":False,"type":bool,"canonical":CANONICAL_MAP.get("get_lines")},
+}
+
+

abstract_utilities/file_utils/imports/imports.py

@@ -8,10 +8,6 @@
 
 from ...imports import *
 from pathlib import Path
-
-
-
-
 from typing import *
 
 from typing import *

abstract_utilities/file_utils/imports/module_imports.py

@@ -4,5 +4,5 @@ from ...ssh_utils import *
 from ...env_utils import *
 from ...read_write_utils import read_from_file,write_to_file
 from ...log_utils import get_logFile
-from ...class_utils import get_caller, get_caller_path, get_caller_dir,SingletonMeta,run_pruned_func
+from ...class_utils import get_caller,get_initial_caller_dir, get_caller_path, get_caller_dir,SingletonMeta,run_pruned_func
 

abstract_utilities/file_utils/src/__init__.py

@@ -1,9 +1,7 @@
 from .file_filters import *
-from .file_utils import *
-from .filter_params import *
 from .map_utils import *
-from .pdf_utils import *
-from .file_reader import *
+from .reader_utils import *
 from .find_collect import *
+from .find_content import *
 from .initFunctionsGen import call_for_all_tabs,get_for_all_tabs
 

abstract_utilities/file_utils/src/file_filters/__init__.py

@@ -0,0 +1,4 @@
+from .ensure_utils import *
+from .filter_params import *
+from .filter_utils import *
+from .predicate_utils import *

abstract_utilities/file_utils/src/file_filters/ensure_utils.py

@@ -0,0 +1,116 @@
+from .filter_utils import *
+def normalize_listlike(value, typ=list, sep=','):
+    """Normalize comma-separated or iterable values into the desired type."""
+    if value in [True, None, False]:
+        return value
+    if isinstance(value, str):
+        value = [v.strip() for v in value.split(sep) if v.strip()]
+    return typ(value)
+
+def ensure_exts(exts):
+    if exts in [True, None, False]:
+        return exts
+    out = []
+    for ext in normalize_listlike(exts, list):
+        if not ext.startswith('.'):
+            ext = f".{ext}"
+        out.append(ext)
+    return set(out)
+
+def ensure_patterns(patterns):
+    """Normalize pattern list and ensure they are valid globs."""
+    if patterns in [True, None, False]:
+        return patterns
+    patterns = normalize_listlike(patterns, list)
+    out = []
+    for pattern in patterns:
+        if not pattern:
+            continue
+        if '*' not in pattern and '?' not in pattern:
+            # Implicitly make it a prefix match
+            if pattern.startswith('.') or pattern.startswith('~'):
+                pattern = f"*{pattern}"
+            else:
+                pattern = f"{pattern}*"
+        out.append(pattern)
+    return out
+def ensure_directories(*args,**kwargs):
+    directories = []
+    for arg in args:
+        arg_str = str(arg)
+        
+        if run_pruned_func(is_dir,arg_str,**kwargs):
+            directories.append(arg_str)
+        elif run_pruned_func(is_file,arg_str,**kwargs):
+            dirname = os.path.dirname(arg_str)
+            directories.append(dirname)
+    safe_directories = get_dir_filter_kwargs(**kwargs)
+    directories+= make_list(safe_directories.get('directories',get_initial_caller_dir()))
+    return list(set([r for r in directories if r]))
+def get_proper_type_str(string):
+    if not string:
+        return None
+    string_lower = string.lower()
+    items = {
+        "d":["dir","dirs","directory","directories","d","dirname"],
+        "f":["file","filepath","file_path","files","filepaths","file_paths","f"]
+     }
+    for key,values in items.items():
+        if string_lower in values:
+            return key
+    init = string_lower[0] if len(string_lower)>0 else None
+    if init in items:
+        return init
+def check_path_type(
+    path: str,
+    user: Optional[str] = None,
+    host: Optional[str] = None,
+    user_as_host: Optional[str] = None,
+    use_shell: bool = False
+) -> Literal["file", "directory", "missing", "unknown"]:
+    """
+    Determine whether a given path is a file, directory, or missing.
+    Works locally or remotely (via SSH).
+
+    Args:
+        path: The path to check.
+        user, host, user_as_host: SSH parameters if remote.
+        use_shell: Force shell test instead of Python os.path.
+    Returns:
+        One of: 'file', 'directory', 'missing', or 'unknown'
+    """
+
+    # --- remote check if user/host is given ---
+    if user_as_host or (user and host):
+        remote_target = user_as_host or f"{user}@{host}"
+        cmd = f"if [ -f '{path}' ]; then echo file; elif [ -d '{path}' ]; then echo directory; else echo missing; fi"
+        try:
+            result = subprocess.check_output(
+                ["ssh", remote_target, cmd],
+                stderr=subprocess.DEVNULL,
+                text=True,
+                timeout=5
+            ).strip()
+            return result if result in ("file", "directory", "missing") else "unknown"
+        except Exception:
+            return "unknown"
+
+    # --- local check ---
+    if not use_shell:
+        if os.path.isfile(path):
+            return "file"
+        elif os.path.isdir(path):
+            return "directory"
+        elif not os.path.exists(path):
+            return "missing"
+        return "unknown"
+    else:
+        # fallback using shell tests (useful for sandboxed contexts)
+        cmd = f"if [ -f '{path}' ]; then echo file; elif [ -d '{path}' ]; then echo directory; else echo missing; fi"
+        try:
+            output = subprocess.check_output(
+                cmd, shell=True, stderr=subprocess.DEVNULL, text=True
+            ).strip()
+            return output if output in ("file", "directory", "missing") else "unknown"
+        except Exception:
+            return "unknown"