Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat [6093]: mo.ui.file_browser ignore empty directories (#6261)

Max Koretskyi6f191323a2a1
diff --git a/marimo/_plugins/ui/_impl/file_browser.py b/marimo/_plugins/ui/_impl/file_browser.py
index bbaee9a158..96e39eb4f9 100644
--- a/marimo/_plugins/ui/_impl/file_browser.py
+++ b/marimo/_plugins/ui/_impl/file_browser.py
@@ -122,6 +122,12 @@ class file_browser(
files. Defaults to True.
restrict_navigation (bool, optional): If True, prevent the user from
navigating any level above the given path. Defaults to False.
+ ignore_empty_dirs (bool, optional): If True, hide directories that contain
+ no files (recursively). Directories are scanned up to 100 levels deep
+ to prevent stack overflow from deeply nested structures. Directory
+ symlinks are skipped during traversal to prevent infinite loops.
+ Filetype filtering is applied recursively and is case-insensitive.
+ This may impact performance for large directory trees. Defaults to False.
limit (int, optional): Maximum number of files to display.
If None (default), automatically chooses 50 for cloud storage (S3, GCS, Azure)
or 10000 for local filesystems. Set explicitly to override defaults.
@@ -145,6 +151,7 @@ class file_browser(
on_change: Optional[
Callable[[Sequence[FileBrowserFileInfo]], None]
] = None,
+ ignore_empty_dirs: bool = False,
) -> None:
validate_one_of(selection_mode, ["file", "directory"])
@@ -162,8 +169,20 @@ class file_browser(
)
self._selection_mode = selection_mode
- self._filetypes: set[str] = set(filetypes) if filetypes else set()
+ # Normalize filetypes: ensure lowercase and dot prefix for case-insensitive matching
+ if filetypes:
+ normalized_filetypes = set()
+ for ft in filetypes:
+ ft_lower = ft.lower()
+ # Ensure dot prefix
+ if not ft_lower.startswith("."):
+ ft_lower = f".{ft_lower}"
+ normalized_filetypes.add(ft_lower)
+ self._filetypes = normalized_filetypes
+ else:
+ self._filetypes = set()
self._restrict_navigation = restrict_navigation
+ self._ignore_empty_dirs = ignore_empty_dirs
self._initial_path: Path = initial_path
self._path_cls: type[Path]
@@ -215,6 +234,54 @@ class file_browser(
path = self._path_cls(path_str, **kwargs)
return path
+ def _has_files_recursive(
+ self, directory: Path, max_depth: int = 100
+ ) -> bool:
+ """Check if directory contains any files (recursively).
+
+ Returns True if the directory contains at least one file (not directory),
+ either directly or in any subdirectory. Returns False if the directory
+ contains only empty subdirectories or is empty.
+
+ Safety features:
+ - Directory symlinks are skipped to prevent infinite loops
+ - Recursion is limited to max_depth to prevent stack overflow
+ - Permission errors are handled gracefully (assumes directory has files)
+ - Filetype filtering is applied case-insensitively if configured
+
+ Args:
+ directory: The directory path to check
+ max_depth: Maximum recursion depth to prevent stack overflow from deeply
+ nested directories. When limit is reached, assumes directory has files for safety.
+
+ Returns:
+ bool: True if directory has files, False if empty or contains only empty dirs
+ """
+ if max_depth <= 0:
+ # Reached maximum depth, assume directory might have files to be safe
+ return True
+
+ try:
+ for item in directory.iterdir():
+ if item.is_file():
+ # Apply filetype filter if specified (case-insensitive)
+ if (
+ self._filetypes
+ and item.suffix.lower() not in self._filetypes
+ ):
+ continue
+ return True
+ elif item.is_dir() and not item.is_symlink():
+ # Skip directory symlinks to avoid infinite loops
+ # Recursively check subdirectories with decremented depth
+ if self._has_files_recursive(item, max_depth - 1):
+ return True
+ return False
+ except (PermissionError, OSError):
+ # If we can't access the directory, assume it's not empty
+ # to avoid hiding potentially accessible subdirectories
+ return True
+
def _list_directory(
self, args: ListDirectoryArgs
) -> ListDirectoryResponse:
@@ -248,9 +315,14 @@ class file_browser(
if self._selection_mode == "directory" and not is_directory:
continue
- # Skip non-matching file types
+ # Skip non-matching file types (case-insensitive)
if self._filetypes and not is_directory:
- if extension not in self._filetypes:
+ if extension.lower() not in self._filetypes:
+ continue
+
+ # Skip empty directories if ignore_empty_dirs is enabled
+ if self._ignore_empty_dirs and is_directory:
+ if not self._has_files_recursive(file):
continue
file_info = TypedFileBrowserFileInfo(
diff --git a/tests/_plugins/ui/_impl/test_file_browser.py b/tests/_plugins/ui/_impl/test_file_browser.py
index 8ac2a73466..d8b1fd1636 100644
--- a/tests/_plugins/ui/_impl/test_file_browser.py
+++ b/tests/_plugins/ui/_impl/test_file_browser.py
@@ -334,3 +334,506 @@ def test_is_truncated_with_filetype_filtering_edge_case(
assert response.total_count == 5
assert len(response.files) == 2
assert response.is_truncated is True
+
+
+def test_ignore_empty_dirs_initialization(tmp_path: Path) -> None:
+ """Test that ignore_empty_dirs parameter is properly initialized."""
+ # Creates:
+ # tmp_path/ (empty directory for initialization testing)
+
+ # Default should be False
+ fb_default = file_browser(initial_path=tmp_path)
+ assert fb_default._ignore_empty_dirs is False
+
+ # Explicit True
+ fb_true = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ assert fb_true._ignore_empty_dirs is True
+
+ # Explicit False
+ fb_false = file_browser(initial_path=tmp_path, ignore_empty_dirs=False)
+ assert fb_false._ignore_empty_dirs is False
+
+
+def test_ignore_empty_dirs_with_empty_directory(tmp_path: Path) -> None:
+ """Test that empty directories are hidden when ignore_empty_dirs=True."""
+ # Create structure with empty directories
+ # /
+ # ├── empty_dir / (empty directory)
+ # ├── another_empty / (empty directory)
+ # └── file.txt(empty file)
+
+ (tmp_path / "empty_dir").mkdir()
+ (tmp_path / "another_empty").mkdir()
+ (tmp_path / "file.txt").touch()
+
+ # Without ignore_empty_dirs (should show empty directories)
+ fb_false = file_browser(initial_path=tmp_path, ignore_empty_dirs=False)
+ response_false = fb_false._list_directory(
+ ListDirectoryArgs(path=str(tmp_path))
+ )
+
+ directory_names = [
+ f["name"] for f in response_false.files if f["is_directory"]
+ ]
+ file_names = [
+ f["name"] for f in response_false.files if not f["is_directory"]
+ ]
+
+ assert "empty_dir" in directory_names
+ assert "another_empty" in directory_names
+ assert "file.txt" in file_names
+
+ # With ignore_empty_dirs (should hide empty directories)
+ fb_true = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ response_true = fb_true._list_directory(
+ ListDirectoryArgs(path=str(tmp_path))
+ )
+
+ directory_names = [
+ f["name"] for f in response_true.files if f["is_directory"]
+ ]
+ file_names = [
+ f["name"] for f in response_true.files if not f["is_directory"]
+ ]
+
+ assert "empty_dir" not in directory_names
+ assert "another_empty" not in directory_names
+ assert "file.txt" in file_names
+
+
+def test_ignore_empty_dirs_with_nested_empty_directories(
+ tmp_path: Path,
+) -> None:
+ """Test that deeply nested empty directories are hidden."""
+ # Creates:
+ # tmp_path/
+ # ├── level1/
+ # │ └── level2/
+ # │ └── level3/ (nested empty structure)
+ # └── non_empty/
+ # └── file.txt (directory with files)
+
+ # Create nested empty directory structure
+ nested_path = tmp_path / "level1" / "level2" / "level3"
+ nested_path.mkdir(parents=True)
+
+ # Create a non-empty directory for comparison
+ non_empty_dir = tmp_path / "non_empty"
+ non_empty_dir.mkdir()
+ (non_empty_dir / "file.txt").touch()
+
+ fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+
+ # Should hide the nested empty structure but show the non-empty directory
+ assert "level1" not in directory_names
+ assert "non_empty" in directory_names
+
+
+def test_ignore_empty_dirs_with_files_in_subdirectories(
+ tmp_path: Path,
+) -> None:
+ """Test that directories with files in subdirectories are shown."""
+ # Creates:
+ # tmp_path/
+ # ├── has_files/
+ # │ └── nested/
+ # │ └── deep/
+ # │ └── deep_file.txt (file buried deep inside)
+ # └── empty_dir/ (truly empty)
+
+ # Create directory structure with files deep inside
+ deep_dir = tmp_path / "has_files" / "nested" / "deep"
+ deep_dir.mkdir(parents=True)
+ (deep_dir / "deep_file.txt").touch()
+
+ # Create empty directory for comparison
+ (tmp_path / "empty_dir").mkdir()
+
+ fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+
+ # Should show directory that has files somewhere inside
+ assert "has_files" in directory_names
+ # Should hide truly empty directory
+ assert "empty_dir" not in directory_names
+
+
+def test_ignore_empty_dirs_respects_filetype_filter(tmp_path: Path) -> None:
+ """Test that ignore_empty_dirs respects filetype filtering."""
+ # Creates:
+ # tmp_path/
+ # ├── python_only/
+ # │ └── script.py (has files, but wrong type)
+ # ├── text_files/
+ # │ └── document.txt (has files of correct type)
+ # └── empty_dir/ (truly empty)
+
+ # Create directory with only .py files (no .txt files)
+ py_dir = tmp_path / "python_only"
+ py_dir.mkdir()
+ (py_dir / "script.py").touch()
+
+ # Create directory with .txt files
+ txt_dir = tmp_path / "text_files"
+ txt_dir.mkdir()
+ (txt_dir / "document.txt").touch()
+
+ # Create empty directory
+ (tmp_path / "empty_dir").mkdir()
+
+ # Filter for .txt files only with ignore_empty_dirs=True
+ fb = file_browser(
+ initial_path=tmp_path, filetypes=[".txt"], ignore_empty_dirs=True
+ )
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+
+ # Should show directory with .txt files
+ assert "text_files" in directory_names
+ # Should hide directory with only .py files (filtered out)
+ assert "python_only" not in directory_names
+ # Should hide empty directory
+ assert "empty_dir" not in directory_names
+
+
+def test_ignore_empty_dirs_mixed_with_files(tmp_path: Path) -> None:
+ """Test ignore_empty_dirs behavior in a directory with mixed content."""
+ # Creates:
+ # tmp_path/
+ # ├── root_file.txt (file at root level)
+ # ├── good_dir/
+ # │ └── subfile.txt (directory with files)
+ # ├── empty_dir/ (truly empty)
+ # └── nested_empty/
+ # └── level2/ (nested empty structure)
+
+ # Create files at root level
+ (tmp_path / "root_file.txt").touch()
+
+ # Create non-empty subdirectory
+ good_dir = tmp_path / "good_dir"
+ good_dir.mkdir()
+ (good_dir / "subfile.txt").touch()
+
+ # Create empty subdirectory
+ (tmp_path / "empty_dir").mkdir()
+
+ # Create directory with nested empty directories only
+ nested_empty = tmp_path / "nested_empty" / "level2"
+ nested_empty.mkdir(parents=True)
+
+ fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ # Separate directories and files
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+ file_names = [f["name"] for f in response.files if not f["is_directory"]]
+
+ # Should show non-empty directory and root file
+ assert "good_dir" in directory_names
+ assert "root_file.txt" in file_names
+
+ # Should hide empty directories
+ assert "empty_dir" not in directory_names
+ assert "nested_empty" not in directory_names
+
+
+def test_ignore_empty_dirs_directory_selection_mode(tmp_path: Path) -> None:
+ """Test ignore_empty_dirs with selection_mode='directory'."""
+ # Creates:
+ # tmp_path/
+ # ├── empty_dir/ (empty directory)
+ # ├── good_dir/
+ # │ └── file.txt (directory with files)
+ # └── file.txt (file - filtered out in directory mode)
+
+ # Create empty directory
+ (tmp_path / "empty_dir").mkdir()
+
+ # Create directory with files
+ good_dir = tmp_path / "good_dir"
+ good_dir.mkdir()
+ (good_dir / "file.txt").touch()
+
+ # Create a file (should be filtered out in directory mode)
+ (tmp_path / "file.txt").touch()
+
+ fb = file_browser(
+ initial_path=tmp_path,
+ selection_mode="directory",
+ ignore_empty_dirs=True,
+ )
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ # All results should be directories (selection_mode filters files)
+ for item in response.files:
+ assert item["is_directory"] is True
+
+ directory_names = [f["name"] for f in response.files]
+
+ # Should show non-empty directory
+ assert "good_dir" in directory_names
+ # Should hide empty directory
+ assert "empty_dir" not in directory_names
+
+
+def test_ignore_empty_dirs_respects_max_depth(tmp_path: Path) -> None:
+ """Test that recursion depth is limited to prevent stack overflow."""
+ # Creates:
+ # tmp_path/
+ # ├── shallow_with_files/
+ # │ └── file.txt (file at shallow depth)
+ # ├── deep_structure/
+ # │ └── level1/
+ # │ └── level2/
+ # │ └── ... (many levels)
+ # │ └── deep_file.txt (file beyond max_depth)
+ # └── empty_dir/ (truly empty)
+
+ # Create shallow directory with files
+ shallow_dir = tmp_path / "shallow_with_files"
+ shallow_dir.mkdir()
+ (shallow_dir / "file.txt").touch()
+
+ # Create very deep directory structure (beyond max_depth)
+ deep_path = tmp_path / "deep_structure"
+ current = deep_path
+ # Create 102 levels deep (beyond default max_depth of 100)
+ for i in range(102):
+ current = current / f"level{i}"
+ current.mkdir(parents=True)
+ (current / "deep_file.txt").touch()
+
+ # Create empty directory for comparison
+ (tmp_path / "empty_dir").mkdir()
+
+ fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+
+ # Should show shallow directory with files
+ assert "shallow_with_files" in directory_names
+ # Should show deep structure (assumes has files when max_depth reached)
+ assert "deep_structure" in directory_names
+ # Should hide empty directory
+ assert "empty_dir" not in directory_names
+
+
+def test_ignore_empty_dirs_max_depth_boundary_conditions(
+ tmp_path: Path,
+) -> None:
+ """Test boundary conditions around max_depth limit."""
+ # Creates:
+ # tmp_path/
+ # ├── depth_100_with_file/
+ # │ └── level0/level1/.../level99/
+ # │ └── file.txt (file at exactly depth 100)
+ # ├── depth_101_with_file/
+ # │ └── level0/level1/.../level100/
+ # │ └── file.txt (file at depth 101 - beyond limit)
+ # ├── depth_100_empty/
+ # │ └── level0/level1/.../level99/ (empty at depth 100)
+ # └── depth_101_empty/
+ # └── level0/level1/.../level100/ (empty at depth 101 - beyond limit)
+
+ # Test case 1: File at exactly depth 100 (should be found)
+ depth_100_with_file = tmp_path / "depth_100_with_file"
+ current = depth_100_with_file
+ for i in range(100): # Create 100 levels deep
+ current = current / f"level{i}"
+ current.mkdir(parents=True)
+ (current / "file.txt").touch()
+
+ # Test case 2: File at depth 101 (beyond limit, should assume has files)
+ depth_101_with_file = tmp_path / "depth_101_with_file"
+ current = depth_101_with_file
+ for i in range(101): # Create 101 levels deep
+ current = current / f"level{i}"
+ current.mkdir(parents=True)
+ (current / "file.txt").touch()
+
+ # Test case 3: Empty at exactly depth 99 (should be detected as empty)
+ depth_99_empty = tmp_path / "depth_99_empty"
+ current = depth_99_empty
+ for i in range(99): # Create 99 levels deep (within limit)
+ current = current / f"level{i}"
+ current.mkdir(parents=True) # No file created
+
+ # Test case 4: Empty at depth 100 (at limit, should assume has files)
+ depth_100_empty = tmp_path / "depth_100_empty"
+ current = depth_100_empty
+ for i in range(100):
+ current = current / f"level{i}"
+ current.mkdir(parents=True) # No file created
+
+ fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+
+ # Should show directory with file at depth 100 (within limit)
+ assert "depth_100_with_file" in directory_names
+ # Should show directory with file at depth 101 (beyond limit, assumes has files)
+ assert "depth_101_with_file" in directory_names
+ # Should hide empty directory at depth 99 (within limit, detected as empty)
+ assert "depth_99_empty" not in directory_names
+ # Should show empty directory at depth 100 (at limit, assumes has files for safety)
+ assert "depth_100_empty" in directory_names
+
+
+def test_ignore_empty_dirs_case_insensitive_filetypes(tmp_path: Path) -> None:
+ """Test that filetype filtering is case-insensitive."""
+ # Creates:
+ # tmp_path/
+ # ├── mixed_case_files/
+ # │ ├── document.TXT (uppercase extension)
+ # │ ├── script.Py (mixed case extension)
+ # │ └── data.CSV (uppercase extension)
+ # ├── wrong_type_files/
+ # │ └── archive.zip (different extension)
+ # └── empty_dir/ (truly empty)
+
+ # Create directory with mixed case extensions
+ mixed_case_dir = tmp_path / "mixed_case_files"
+ mixed_case_dir.mkdir()
+ (mixed_case_dir / "document.TXT").touch() # Uppercase
+ (mixed_case_dir / "script.Py").touch() # Mixed case
+ (mixed_case_dir / "data.CSV").touch() # Uppercase
+
+ # Create directory with wrong file type
+ wrong_type_dir = tmp_path / "wrong_type_files"
+ wrong_type_dir.mkdir()
+ (wrong_type_dir / "archive.zip").touch()
+
+ # Create empty directory
+ (tmp_path / "empty_dir").mkdir()
+
+ # Test with lowercase filetypes and mixed input formats
+ fb = file_browser(
+ initial_path=tmp_path,
+ filetypes=[
+ "txt",
+ ".py",
+ ".CSV",
+ ], # Mixed formats: no dot, dot, uppercase
+ ignore_empty_dirs=True,
+ )
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+ file_names = [f["name"] for f in response.files if not f["is_directory"]]
+
+ # Should show directory with mixed case matching files
+ assert "mixed_case_files" in directory_names
+ # Should hide directory with non-matching file types
+ assert "wrong_type_files" not in directory_names
+ # Should hide empty directory
+ assert "empty_dir" not in directory_names
+
+ # Also test direct file listing to verify case-insensitive matching
+ fb_direct = file_browser(
+ initial_path=mixed_case_dir,
+ filetypes=["txt", ".py", ".csv"], # All lowercase
+ )
+ response_direct = fb_direct._list_directory(
+ ListDirectoryArgs(path=str(mixed_case_dir))
+ )
+ direct_files = [
+ f["name"] for f in response_direct.files if not f["is_directory"]
+ ]
+
+ # Should show all files despite case differences
+ assert "document.TXT" in direct_files
+ assert "script.Py" in direct_files
+ assert "data.CSV" in direct_files
+
+
+def test_ignore_empty_dirs_skips_directory_symlinks(tmp_path: Path) -> None:
+ """Test that directory symlinks are skipped to prevent infinite loops."""
+ # Creates:
+ # tmp_path/
+ # ├── real_dir/
+ # │ └── file.txt (real directory with files)
+ # ├── symlink_to_real_dir@ -> real_dir/ (symlink to real directory)
+ # ├── broken_symlink@ (broken symlink)
+ # └── empty_dir/ (truly empty)
+
+ # Create real directory with files
+ real_dir = tmp_path / "real_dir"
+ real_dir.mkdir()
+ (real_dir / "file.txt").touch()
+
+ # Create symlink to real directory
+ symlink_dir = tmp_path / "symlink_to_real_dir"
+ symlink_dir.symlink_to(real_dir)
+
+ # Create broken symlink
+ broken_symlink = tmp_path / "broken_symlink"
+ broken_symlink.symlink_to(tmp_path / "nonexistent")
+
+ # Create empty directory
+ (tmp_path / "empty_dir").mkdir()
+
+ fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+
+ # Should show real directory with files
+ assert "real_dir" in directory_names
+ # Should show valid directory symlinks (they're not recursively checked, so treated as potentially having content)
+ assert "symlink_to_real_dir" in directory_names
+ # Broken symlinks may not appear as directories, so we don't test for them
+ # Should hide empty directory
+ assert "empty_dir" not in directory_names
+
+
+def test_ignore_empty_dirs_symlink_loop_protection(tmp_path: Path) -> None:
+ """Test protection against symlink loops in deep directory structures."""
+ # Creates:
+ # tmp_path/
+ # ├── loop_start/
+ # │ ├── level1/
+ # │ │ ├── level2/
+ # │ │ │ └── back_to_start@ -> ../../../loop_start/ (creates loop)
+ # │ │ └── real_file.txt (file in the structure)
+ # │ └── file.txt (file at top level)
+ # └── empty_dir/ (truly empty)
+
+ # Create directory structure with potential for loops
+ loop_start = tmp_path / "loop_start"
+ loop_start.mkdir()
+ (loop_start / "file.txt").touch()
+
+ level1 = loop_start / "level1"
+ level1.mkdir()
+
+ level2 = level1 / "level2"
+ level2.mkdir()
+ (level1 / "real_file.txt").touch() # Add file to make structure non-empty
+
+ # Create symlink that would cause infinite loop
+ loop_symlink = level2 / "back_to_start"
+ loop_symlink.symlink_to(loop_start)
+
+ # Create empty directory
+ (tmp_path / "empty_dir").mkdir()
+
+ fb = file_browser(initial_path=tmp_path, ignore_empty_dirs=True)
+ response = fb._list_directory(ListDirectoryArgs(path=str(tmp_path)))
+
+ directory_names = [f["name"] for f in response.files if f["is_directory"]]
+
+ # Should show directory with files (symlinks are skipped so no infinite loop)
+ assert "loop_start" in directory_names
+ # Should hide empty directory
+ assert "empty_dir" not in directory_names
+
+ # Test should complete without hanging (no infinite loop)