Paths and Files¶

def resolve(self, location: str | Path | None = None) -> str:
    """Resolve a logical location to a filesystem path.

    Relative locations are resolved below `root`. Absolute locations are
    returned unchanged, which lets callers pass explicit local paths when they
    already have them.

    Args:
        location: Relative or absolute path-like location. If omitted, the
            store root is returned.

    Returns:
        Resolved filesystem path as a string.
    """
    if location is None:
        return self.root
    path = Path(location)
    if path.is_absolute():
        return str(path)
    return str(Path(self.root) / path)

def create_dir(self, location: str | Path) -> None:
    """Create a directory, including missing parents.

    Args:
        location: Relative or absolute directory location to create.
    """
    Path(self.resolve(location)).mkdir(parents=True, exist_ok=True)

def delete_dir(self, location: str | Path, *, missing_ok: bool = True) -> None:
    """Delete a directory tree.

    Args:
        location: Relative or absolute directory location to delete.
        missing_ok: Return silently when the directory does not exist.

    Raises:
        FileNotFoundError: If the directory is missing and `missing_ok` is false.
        NotADirectoryError: If the resolved location exists but is not a directory.
    """
    path = Path(self.resolve(location))
    if not path.exists():
        if missing_ok:
            return
        raise FileNotFoundError(f"Directory does not exist: {path}")
    if not path.is_dir():
        raise NotADirectoryError(f"Path is not a directory: {path}")
    shutil.rmtree(path)

def delete_file(self, location: str | Path, *, missing_ok: bool = True) -> None:
    """Delete a file.

    Args:
        location: Relative or absolute file location to delete.
        missing_ok: Return silently when the file does not exist.

    Raises:
        FileNotFoundError: If the file is missing and `missing_ok` is false.
        IsADirectoryError: If the resolved location exists but is not a file.
    """
    path = Path(self.resolve(location))
    if not path.exists():
        if missing_ok:
            return
        raise FileNotFoundError(f"File does not exist: {path}")
    if not path.is_file():
        raise IsADirectoryError(f"Path is not a file: {path}")
    path.unlink()

def list_files(
    self,
    location: str | Path | None = None,
    pattern: str = "*",
) -> tuple[str, ...]:
    """List non-hidden files below a store location.

    Files are matched with `pathlib.Path.rglob`, returned as sorted POSIX
    paths relative to `root`, and skipped when any path component below
    `location` starts with `.`.

    Args:
        location: Directory to search. Defaults to the store root.
        pattern: Recursive glob pattern, such as `"*.xlsx"` or
            `"**/*.parquet"`.

    Returns:
        Sorted tuple of matching file paths relative to the store root.

    Raises:
        FileNotFoundError: If `location` is missing or is not a directory.

    Examples:
        Use the dataset ingest spec to find Pozzato raw Excel files while
        excluding paths such as `README.xlsx`:

        >>> paths = []
        >>> for pattern in raw_spec.included_file_patterns:
        ...     paths.extend(
        ...         path
        ...         for path in store.list_files(raw_root, pattern=pattern)
        ...         if raw_spec.is_included_file(path)
        ...     )
    """
    root = Path(self.resolve(location))
    if not root.exists() or not root.is_dir():
        raise FileNotFoundError(f"Directory does not exist: {root}")
    paths = [
        path.relative_to(self.root).as_posix()
        for path in root.rglob(pattern)
        if path.is_file()
        and not any(part.startswith(".") for part in path.relative_to(root).parts)
    ]
    return tuple(sorted(paths))

@contextmanager
def local_file(self, location: str | Path) -> Iterator[Path]:
    """Yield a concrete local path for a logical store location.

    Args:
        location: Relative or absolute file location.

    Yields:
        Resolved local `pathlib.Path`.

    Examples:
        The Pozzato raw adapter uses this to pass a local Excel path to
        `fastexcel`:

        >>> with store.local_file(source_path) as path:
        ...     excel = fastexcel.read_excel(path)
    """
    yield Path(self.resolve(location))