84 lines
3.3 KiB
Markdown
84 lines
3.3 KiB
Markdown
|
# 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
|
||
|
|
```bash
|
||
|
|
python run.py
|
||
|
|
```
|
||
|
|
|
||
|
|
### Installing Dependencies
|
||
|
|
```bash
|
||
|
|
pip install -r requirements.txt
|
||
|
|
```
|
||
|
|
|
||
|
|
### Development Setup
|
||
|
|
```bash
|
||
|
|
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](run.py):
|
||
|
|
```python
|
||
|
|
window = FileSystemBrowser(target_path="Your/Custom/Path")
|
||
|
|
```
|
||
|
|
|
||
|
|
Or modify the default in [src/main.py:14](src/main.py#L14).
|
||
|
|
|
||
|
|
## 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
|