first dev release

Author: AAriam

pyproject.toml

@@ -1,4 +1,3 @@
-
 [build-system]
 requires = ["setuptools>=61.0", "versioningit"]
 build-backend = "setuptools.build_meta"
@@ -15,8 +14,7 @@ namespaces = true
 
 
 # ----------------------------------------- Project Metadata -------------------------------------
-#
 [project]
-version = "0.0.0.dev0"
+version = "0.0.0.dev1"
 name = "FileEx"
 requires-python = ">=3.10"

src/fileex/__init__.py

@@ -1,2 +1,3 @@
 """FileEx"""
 
+from fileex import exception, directory, search

src/fileex/directory.py

@@ -0,0 +1,46 @@
+from pathlib import Path as _Path
+import shutil as _shutil
+
+from fileex import exception as _exception
+
+
+def delete_contents(
+    path: str | _Path, exclude: list[str] | None = None, raise_existence: bool = True
+) -> list[str] | None:
+    """
+    Delete all files and directories within a given directory,
+    excluding those specified by `exclude`.
+
+    Parameters
+    ----------
+    path : str | pathlib.Path
+        Path to the directory whose content should be deleted.
+    exclude : list[str] | None, default: None
+        List of file and directory names to exclude from deletion.
+    raise_existence : bool, default: True
+        Raise an error when the directory does not exist.
+
+    Returns
+    -------
+    deleted_names : list[str] | None
+        Names of the files and directories that were deleted,
+        or None if the directory does not exist and `raise_existence` is set to False.
+
+    Raises
+    ------
+    fileex.exception.FileExPathNotFoundError
+        If the directory does not exist and `raise_existence` is set to True.
+    """
+    path = _Path(path)
+    if not path.is_dir():
+        if raise_existence:
+            raise _exception.FileExPathNotFoundError(path, is_dir=True)
+        return
+    if not exclude:
+        exclude = []
+    deleted_names = []
+    for item in path.iterdir():
+        if item.name not in exclude:
+            deleted_names.append(item.name)
+            item.unlink() if item.is_file() else _shutil.rmtree(item)
+    return deleted_names

src/fileex/exception.py

@@ -0,0 +1,25 @@
+from pathlib import Path as _Path
+
+
+class FileExError(Exception):
+    """Base class for all FileEx errors."""
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+        return
+
+
+class FileExInputError(FileExError):
+    """Error in the input arguments provided to FileEx methods."""
+    def __init__(self, message: str):
+        super().__init__(message)
+        return
+
+
+class FileExPathNotFoundError(FileExError):
+    """The given path does not exist."""
+    def __init__(self, path: _Path, is_dir: bool):
+        self.path = path
+        message = f"No {'directory' if is_dir else 'file'} found at '{path}'."
+        super().__init__(message)
+        return

src/fileex/search.py

@@ -0,0 +1,40 @@
+from pathlib import Path as _Path
+
+from fileex import exception as _exception
+
+
+def path_in_hierarchy(
+    path: str | _Path,
+    leaf_dir: str | _Path = ".",
+    root_dir: str | _Path = "/",
+) -> _Path | None:
+    """Find a path in the directory hierarchy.
+
+    Parameters
+    ----------
+    path : str | pathlib.Path
+        Relative path to the file or directory to find.
+    leaf_dir : str | pathlib.Path, default: "."
+        Directory to start the search from.
+    root_dir : str | pathlib.Path, default: "/"
+        Directory to stop the search at.
+        This must be an ancestor of `leaf_dir`.
+
+    Returns
+    -------
+    path : pathlib.Path | None
+        Absolute path to the file or directory if found, else None.
+    """
+    path = _Path(path)
+    leaf_dir = _Path(leaf_dir).resolve()
+    root_dir = _Path(root_dir).resolve()
+    try:
+        leaf_dir.relative_to(root_dir)
+    except ValueError:
+        raise _exception.FileExInputError("Input argument 'leaf_dir' must be a descendant of 'root_dir'.")
+    while leaf_dir != root_dir:
+        possible_path = leaf_dir / path
+        if possible_path.exists():
+            return possible_path
+        leaf_dir = leaf_dir.parent
+    return