Directory

provide.foundation.file.directory

TODO: Add module docstring.

Functions

ensure_dir

ensure_dir(
    path: Path | str, mode: int = 493, parents: bool = True
) -> Path

Ensure directory exists with proper permissions.

Parameters:

Name	Type	Description	Default
path	Path | str	Directory path	required
mode	int	Directory permissions	493
parents	bool	Create parent directories if needed	True

Returns:

Type	Description
Path	Path object for the directory

Source code in provide/foundation/file/directory.py

def ensure_dir(
    path: Path | str,
    mode: int = 0o755,
    parents: bool = True,
) -> Path:
    """Ensure directory exists with proper permissions.

    Args:
        path: Directory path
        mode: Directory permissions
        parents: Create parent directories if needed

    Returns:
        Path object for the directory

    """
    path = Path(path)

    if not path.exists():
        path.mkdir(mode=mode, parents=parents, exist_ok=True)
        log.debug("Created directory", path=str(path), mode=oct(mode))
    elif not path.is_dir():
        raise NotADirectoryError(f"Path exists but is not a directory: {path}")

    return path

ensure_parent_dir

ensure_parent_dir(
    file_path: Path | str, mode: int = 493
) -> Path

Ensure parent directory of file exists.

Parameters:

Name	Type	Description	Default
file_path	Path | str	File path whose parent to ensure	required
mode	int	Directory permissions	493

Returns:

Type	Description
Path	Path object for the parent directory

Source code in provide/foundation/file/directory.py

def ensure_parent_dir(
    file_path: Path | str,
    mode: int = 0o755,
) -> Path:
    """Ensure parent directory of file exists.

    Args:
        file_path: File path whose parent to ensure
        mode: Directory permissions

    Returns:
        Path object for the parent directory

    """
    file_path = Path(file_path)
    parent = file_path.parent

    if parent and parent != Path():
        return ensure_dir(parent, mode=mode, parents=True)

    return parent

safe_rmtree

safe_rmtree(
    path: Path | str, missing_ok: bool = True
) -> bool

Remove directory tree safely.

Parameters:

Name	Type	Description	Default
path	Path | str	Directory to remove	required
missing_ok	bool	If True, don't raise error if doesn't exist	True

Returns:

Type	Description
bool	True if removed, False if didn't exist

Raises:

Type	Description
OSError	If removal fails and directory exists

Source code in provide/foundation/file/directory.py

@resilient(fallback=False, suppress=(FileNotFoundError,) if False else ())
def safe_rmtree(
    path: Path | str,
    missing_ok: bool = True,
) -> bool:
    """Remove directory tree safely.

    Args:
        path: Directory to remove
        missing_ok: If True, don't raise error if doesn't exist

    Returns:
        True if removed, False if didn't exist

    Raises:
        OSError: If removal fails and directory exists

    """
    path = Path(path)

    if path.exists():
        shutil.rmtree(path)
        log.debug("Removed directory tree", path=str(path))
        return True
    if missing_ok:
        log.debug("Directory already absent", path=str(path))
        return False
    raise FileNotFoundError(f"Directory does not exist: {path}")