readFileSystem/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a File System Browser - a Python desktop application built with PySide6 that displays files and folders from a specified directory in a table format. The default target directory is C://OEM (Windows).

Architecture

The application follows a simple two-layer architecture:

Layer 1: File System Reading (src/file_system.py)

• FileSystemReader: Core utility class that handles OS-level file operations

  • Reads directory contents using pathlib.Path
  • Handles permission errors gracefully (skips inaccessible files)
  • Returns sorted list of FileInfo objects (folders first, then alphabetically)
  • Extracts file metadata: name, size, type, modification timestamp

• FileInfo: Data class that represents a single file/folder entry

  • Includes size_readable property for human-readable file sizes (B, KB, MB, GB)
  • Distinguishes between folders and files via is_dir flag

Layer 2: PySide6 GUI (src/main.py)

• FileSystemBrowser: Main window that integrates file reading with UI display
  • Initializes UI layout with path label, refresh button, table widget, and status bar
  • Calls FileSystemReader.get_files_and_folders() to populate the table
  • Renders file metadata in 4-column table: Name, Type, Size, Modified
  • Visual feedback: folders displayed in blue, alternating row colors
  • Status bar updates with total item count and current path
  • load_files() method handles UI updates with exception handling

Entry Point (run.py)

• Imports and runs the main() function from src/main.py
• Creates a FileSystemBrowser instance with default path C://OEM

Common Commands

Running the Application

python run.py

Installing Dependencies

pip install -r requirements.txt

Development Setup

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python run.py

Key Design Decisions

1. Path Handling: Uses pathlib.Path for cross-platform compatibility (Windows, macOS, Linux)
2. Error Handling: Files/folders that cannot be read due to permissions are silently skipped rather than throwing exceptions
3. Sorting: Folders are displayed first, followed by files, all sorted alphabetically (case-insensitive)
4. File Type Detection: Uses file extension (suffix) or labels as "File" if no extension; folders labeled as "Folder"
5. Size Display: Folders show "—" for size since folder size isn't meaningful; files show converted size with unit
6. UI Responsiveness: QApplication.processEvents() called during load_files() to prevent UI freezing

Modifying the Target Directory

To browse a different directory, change the target_path parameter in run.py:

window = FileSystemBrowser(target_path="Your/Custom/Path")

Or modify the default in src/main.py:14.

Dependencies

• PySide6 6.7.1: Official Python bindings for Qt framework (GUI framework)

Notes for Future Development

• The application currently only reads one directory level (non-recursive)
• File I/O is synchronous; large directories may cause brief UI pause during initial load
• No persistent state is saved between sessions