annie.system.fsbrowse

Filesystem browsing helpers for the folder-picker dialog (service).

Pure, side-effect-free directory navigation used by the Dataset tab’s folder picker. Kept out of the UI layer so it can be unit-tested without NiceGUI: the picker dialog (annie/pages/folder_picker.py) is a thin view over these.

Functions

resolve_start_dir(→ pathlib.Path)	Return a sensible existing directory to open the picker at.
parent_of(→ pathlib.Path | None)	Return the parent directory, or None if already at the filesystem root.
drive_roots(→ list[pathlib.Path])	Return the drive roots (C:/, E:/, …) on Windows; empty elsewhere.
other_drives(→ list[P])	Return the drives in drives other than the one current lives on.
scan_entries(→ tuple[list[pathlib.Path], ...)	List a directory's subfolders (and optionally files) in a single pass.
list_subdirectories(→ list[pathlib.Path])	List immediate subdirectories of path, sorted case-insensitively.
list_files(→ list[pathlib.Path])	List immediate files of path, sorted case-insensitively.

Module Contents

annie.system.fsbrowse.resolve_start_dir(start: str | pathlib.Path | None) → pathlib.Path

Return a sensible existing directory to open the picker at.

Falls back gracefully: the given path if it is a directory, else its nearest existing ancestor, else the user’s home directory.

Parameters:

start – A path hint (e.g. the current text-field value), or None.

Returns:

An existing directory to start browsing from.

annie.system.fsbrowse.parent_of(path: str | pathlib.Path) → pathlib.Path | None

Return the parent directory, or None if already at the filesystem root.

Parameters:

path – The current directory.

Returns:

The parent Path, or None at the root.

annie.system.fsbrowse.drive_roots() → list[pathlib.Path]

Return the drive roots (C:/, E:/, …) on Windows; empty elsewhere.

Lets the picker leave C:/ for another drive, such as an external USB disk; on macOS/Linux every disk is already reachable below /.

annie.system.fsbrowse.other_drives[P: pathlib.PurePath](current: pathlib.PurePath, drives: list[P]) → list[P]

Return the drives in drives other than the one current lives on.

Parameters:

• current – The directory being shown (usually a drive root).

• drives – All drive roots, e.g. from drive_roots().

Returns:

The other drive roots, in the given order.

annie.system.fsbrowse.scan_entries(path: str | pathlib.Path, *, want_files: bool, suffixes: tuple[str, ...] | None = None, show_hidden: bool = False) → tuple[list[pathlib.Path], list[pathlib.Path]]

List a directory’s subfolders (and optionally files) in a single pass.

Uses os.scandir(), whose entries carry the file type read straight from the directory itself, so classifying each child as a folder or file costs no extra stat syscall on the common case. This matters on large or slow (external / networked) drives, where the old one-stat-per-entry approach could freeze the picker for many seconds. Unreadable directories yield empty lists rather than raising, so a permission error never breaks the picker.

Parameters:

• path – The directory to list.

• want_files – Also collect files (skipped entirely when False).

• suffixes – Lower-case dotted suffixes to keep among files, or None for all.

• show_hidden – Include hidden entries (see _is_hidden()) when True.

Returns:

A (subdirs, files) pair, each sorted by lower-cased name; files is empty when want_files is False.

annie.system.fsbrowse.list_subdirectories(path: str | pathlib.Path, *, show_hidden: bool = False) → list[pathlib.Path]

List immediate subdirectories of path, sorted case-insensitively.

Hidden entries (dotfiles, including macOS AppleDouble ._*, and entries Windows marks hidden) are excluded by default. Unreadable directories yield an empty list rather than raising, so a permission error never breaks the picker.

Parameters:

• path – The directory to list.

• show_hidden – Include hidden entries (see _is_hidden()) when True.

Returns:

The child directories, sorted by lower-cased name.

annie.system.fsbrowse.list_files(path: str | pathlib.Path, *, suffixes: tuple[str, ...] | None = None, show_hidden: bool = False) → list[pathlib.Path]

List immediate files of path, sorted case-insensitively.

Hidden entries are excluded by default; an optional suffix filter restricts the result (e.g. (".csv",)). Unreadable directories yield an empty list.

Parameters:

• path – The directory to list.

• suffixes – Lower-case dotted suffixes to keep, or None for all files.

• show_hidden – Include hidden entries (see _is_hidden()) when True.

Returns:

The child files, sorted by lower-cased name.