annie.system.fsbrowse
=====================

.. py:module:: annie.system.fsbrowse

.. autoapi-nested-parse::

   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
---------

.. autoapisummary::

   annie.system.fsbrowse.resolve_start_dir
   annie.system.fsbrowse.parent_of
   annie.system.fsbrowse.drive_roots
   annie.system.fsbrowse.other_drives
   annie.system.fsbrowse.scan_entries
   annie.system.fsbrowse.list_subdirectories
   annie.system.fsbrowse.list_files


Module Contents
---------------

.. py:function:: 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.

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

   :returns: An existing directory to start browsing from.


.. py:function:: parent_of(path: str | pathlib.Path) -> pathlib.Path | None

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

   :param path: The current directory.

   :returns: The parent :class:`~pathlib.Path`, or ``None`` at the root.


.. py:function:: 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 ``/``.


.. py:function:: 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.

   :param current: The directory being shown (usually a drive root).
   :param drives: All drive roots, e.g. from :func:`drive_roots`.

   :returns: The other drive roots, in the given order.


.. py:function:: 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 :func:`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.

   :param path: The directory to list.
   :param want_files: Also collect files (skipped entirely when ``False``).
   :param suffixes: Lower-case dotted suffixes to keep among files, or ``None`` for all.
   :param show_hidden: Include hidden entries (see :func:`_is_hidden`) when ``True``.

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


.. py:function:: 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.

   :param path: The directory to list.
   :param show_hidden: Include hidden entries (see :func:`_is_hidden`) when ``True``.

   :returns: The child directories, sorted by lower-cased name.


.. py:function:: 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.

   :param path: The directory to list.
   :param suffixes: Lower-case dotted suffixes to keep, or ``None`` for all files.
   :param show_hidden: Include hidden entries (see :func:`_is_hidden`) when ``True``.

   :returns: The child files, sorted by lower-cased name.