sfo-file-organizer 1.1.0

A Python utility that automatically organizes files into categorized folders based on file types, with rule-based classification and real-time monitoring.

SFO File Organizer

A Python utility that automatically organizes files into categorized folders based on their file types, with support for rule-based classification, structured logging, and real-time monitoring.

Features

• 📁 Smart Classification
  • Rule-based classification (keywords take priority)
  • Extension-based fallback classification (supports PHP, TS, JSX, etc.)
• ⚙️ Customizable Categories - Easy to add custom file categories and rules
• 🔄 Duplicate Handling - Automatic renaming for duplicate filenames
• 📊 Statistics - Summary report after organization
• 🧪 Dry-Run Mode - Preview changes without moving files
• 📝 Structured Logging - Console and file logging with configurable levels
• 🖥️ Modern Desktop UI - Sleek dark-themed interface with:
  • Scheduling: Automate organization to run daily.
  • Flatten Directory: Undo organization by moving files back to the root.
    • Organized Only: Safely targets only folders created by the organizer.
    • Flatten ALL: Powerful option to flatten the entire directory structure.
  • Watch Mode: Real-time folder monitoring.
• ↩️ Undo Support - Easily revert any organization session (auto-cleans empty folders)
• 🧠 Smart Context - Auto-detects folder purpose by name (Photos, Documents, etc.) for specialized sorting

Platform Compatibility

Platform	Pre-built Executable	Run from Source
Windows	✅ .exe available	✅ Supported
macOS	✅ Available via GitHub Releases	✅ Supported
Linux	✅ Available via GitHub Releases	✅ Supported

Note: Pre-built executables for all platforms are automatically generated via GitHub Actions and attached to each Release.

macOS / Linux Setup

1. Install Python 3.8+ (usually pre-installed on Linux, download from python.org for macOS)

2. Clone and install dependencies:

   git clone https://github.com/pjames-tech/sfo-file-organizer.git
   cd sfo-file-organizer
   pip install -r requirements.txt
   

3. Run the GUI:

   python gui.py
   

4. Or run the CLI:

   python organizer.py --source ~/Downloads
   

Building Your Own Executable (Optional)

If you want to create a native executable for your platform:

# Install PyInstaller
pip install pyinstaller

# Build the executable
pyinstaller --onefile --windowed gui.py

The executable will be created in the dist/ folder.

Architecture

sfo-file-organizer/
├── organizer.py        # Main CLI and orchestration
├── gui.py              # Desktop GUI application (tkinter)
├── app_config.py       # Configuration and file categories
├── rules.py            # Rule-based classification engine
├── scheduler.py        # Windows Task Scheduler integration
├── history.py          # Undo/redo history management
├── logging_config.py   # Logging configuration
├── run_organizer.bat   # Batch script helper
├── requirements.txt    # Dependencies
└── tests/              # Unit tests

Classification Priority

1. Keyword Rules - Custom rules take priority.
2. File Extension - Standard classification based on file type.

Installation

Option 1: Install via pip (Recommended for all platforms)

pip install sfo-file-organizer

Then run:

sfo-file-organizer        # Launch GUI
sfo                       # Shortcut for GUI
sfo-cli --source ~/Downloads  # CLI mode

Option 2: Download Pre-built Executable

Platform	Download
Windows	SFO-File-Organizer-Windows.exe
macOS	SFO-File-Organizer-macOS.zip
Linux	SFO-File-Organizer-Linux

Option 3: Run from Source

git clone https://github.com/pjames-tech/sfo-file-organizer.git
cd sfo-file-organizer
pip install -r requirements.txt
python gui.py

Usage

Quick Start

1. Install using one of the methods above.
2. Launch the application (GUI or CLI).
3. Select the folder you want to organize.
4. Click "Organize Now" and watch your files get sorted!

👁️ Watch Mode

Watch Mode monitors your source folder in real-time. Any file you drop into the folder will be automatically categorized and moved instantly.

• GUI: Just toggle the "Watch Mode" switch.
• CLI: Run python organizer.py --watch

Desktop GUI

Launch the graphical interface:

python gui.py

Features:

• 📂 Browse and select any folder to organize
• 🚀 Organize Now - One-click file organization
• 👁️ Preview Changes - See what will happen before committing
• 🧹 Flatten - Move files out of organizer-created subfolders back to the root (preserves pre-existing folders)
• ⏰ Automation - Schedule daily organization tasks
• ↩️ Undo Last - Restore files to their original locations and clean up empty folders
• 📋 Activity log with colored output
• 🧠 Smart Context - Enable to sort images by year or documents by type based on folder name
• ⌚ Watch Mode - Real-time folder monitoring

CLI Mode

# Organize Downloads folder (in-place)
python organizer.py --source ~/Downloads

# Dry-run (preview without moving files)
python organizer.py --dry-run --source ~/Downloads

# Undo last organization
python organizer.py --undo

# View history
python organizer.py --history

CLI Options

Flag	Short	Description
--source	-s	Source directory to organize
--dest	-d	Destination directory (default: same as source)
--dry-run	-n	Preview changes without moving files
--in-place	-i	Organize within source folder (default)
--watch	-w	Monitor folder and organize in real-time
--undo		Undo the last organization
--history		Show organization history
--log-level	-l	Set logging level (DEBUG, INFO, WARNING, ERROR)
--no-log-file		Disable logging to file

Examples

# Preview what would happen
python organizer.py --dry-run --source ./messy_folder

# Quick organize current downloads
python organizer.py --source ~/Downloads

# Start watching a folder
python organizer.py --watch --source ~/Downloads

Configuration

File Categories (app_config.py)

FILE_CATEGORIES = {
    "Images": [".jpg", ".jpeg", ".png", ".gif", ...],
    "Documents": [".pdf", ".doc", ".docx", ".txt", ...],
    "Videos": [".mp4", ".mkv", ".avi", ...],
    "Code": [".py", ".js", ".php", ".ts", ".jsx", ...],
    # Add custom categories here
}

Keyword Rules (rules.py)

KEYWORD_RULES = {
    "invoice": "Documents",    # Files with "invoice" go to Documents
    "screenshot": "Images",    # Files with "screenshot" go to Images
    # Add custom rules here
}

Testing

# Install pytest
pip install pytest

# Run all tests
pytest tests/ -v

Automatic Scheduling (Windows Task Scheduler)

Run the organizer automatically on a schedule using the included batch script.

Quick Setup

1. Edit run_organizer.bat to customize your source/destination folders:

   "C:\Python314\python.exe" organizer.py --source "%USERPROFILE%\Downloads" --dest "%USERPROFILE%\Downloads" --log-level INFO
   

2. Create the scheduled task (run in PowerShell as admin):

   schtasks /create /tn "Smart File Organizer" /tr "C:\path\to\run_organizer.bat" /sc daily /st 12:00 /f
   

License

MIT License