sfo-file-organizer 1.0.0__tar.gz

sfo_file_organizer-1.0.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: sfo-file-organizer
+Version: 1.0.0
+Summary: A Python utility that automatically organizes files into categorized folders based on file types, with rule-based classification and real-time monitoring.
+Author: pjames-tech
+License: MIT
+Project-URL: Homepage, https://github.com/pjames-tech/sfo-file-organizer
+Project-URL: Repository, https://github.com/pjames-tech/sfo-file-organizer
+Project-URL: Issues, https://github.com/pjames-tech/sfo-file-organizer/issues
+Keywords: file-organizer,automation,file-management,desktop-app
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Desktop Environment :: File Managers
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: watchdog>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pyinstaller>=6.0.0; extra == "dev"
+
+# 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 (only targets organizer-created folders).
+  - **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](https://github.com/pjames-tech/sfo-file-organizer/releases).
+
+### macOS / Linux Setup
+
+1. **Install Python 3.8+** (usually pre-installed on Linux, download from [python.org](https://python.org) for macOS)
+
+2. **Clone and install dependencies:**
+
+   ```bash
+   git clone https://github.com/pjames-tech/sfo-file-organizer.git
+   cd sfo-file-organizer
+   pip install -r requirements.txt
+   ```
+
+3. **Run the GUI:**
+
+   ```bash
+   python gui.py
+   ```
+
+4. **Or run the CLI:**
+
+   ```bash
+   python organizer.py --source ~/Downloads
+   ```
+
+### Building Your Own Executable (Optional)
+
+If you want to create a native executable for your platform:
+
+```bash
+# Install PyInstaller
+pip install pyinstaller
+
+# Build the executable
+pyinstaller --onefile --windowed gui.py
+```
+
+The executable will be created in the `dist/` folder.
+
+## Architecture
+
+```text
+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)
+
+```bash
+pip install sfo-file-organizer
+```
+
+Then run:
+
+```bash
+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](https://github.com/pjames-tech/sfo-file-organizer/releases/latest/download/SFO-File-Organizer-Windows.exe) |
+| **macOS**   | [SFO-File-Organizer-macOS.zip](https://github.com/pjames-tech/sfo-file-organizer/releases/latest/download/SFO-File-Organizer-macOS.zip)     |
+| **Linux**   | [SFO-File-Organizer-Linux](https://github.com/pjames-tech/sfo-file-organizer/releases/latest/download/SFO-File-Organizer-Linux)             |
+
+### Option 3: Run from Source
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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`)
+
+```python
+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`)
+
+```python
+KEYWORD_RULES = {
+    "invoice": "Documents",    # Files with "invoice" go to Documents
+    "screenshot": "Images",    # Files with "screenshot" go to Images
+    # Add custom rules here
+}
+```
+
+## Testing
+
+```bash
+# 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:
+
+   ```batch
+   "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):
+
+   ```powershell
+   schtasks /create /tn "Smart File Organizer" /tr "C:\path\to\run_organizer.bat" /sc daily /st 12:00 /f
+   ```
+
+## License
+
+MIT License

sfo_file_organizer-1.0.0/README.md

@@ -0,0 +1,257 @@
+# 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 (only targets organizer-created folders).
+  - **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](https://github.com/pjames-tech/sfo-file-organizer/releases).
+
+### macOS / Linux Setup
+
+1. **Install Python 3.8+** (usually pre-installed on Linux, download from [python.org](https://python.org) for macOS)
+
+2. **Clone and install dependencies:**
+
+   ```bash
+   git clone https://github.com/pjames-tech/sfo-file-organizer.git
+   cd sfo-file-organizer
+   pip install -r requirements.txt
+   ```
+
+3. **Run the GUI:**
+
+   ```bash
+   python gui.py
+   ```
+
+4. **Or run the CLI:**
+
+   ```bash
+   python organizer.py --source ~/Downloads
+   ```
+
+### Building Your Own Executable (Optional)
+
+If you want to create a native executable for your platform:
+
+```bash
+# Install PyInstaller
+pip install pyinstaller
+
+# Build the executable
+pyinstaller --onefile --windowed gui.py
+```
+
+The executable will be created in the `dist/` folder.
+
+## Architecture
+
+```text
+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)
+
+```bash
+pip install sfo-file-organizer
+```
+
+Then run:
+
+```bash
+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](https://github.com/pjames-tech/sfo-file-organizer/releases/latest/download/SFO-File-Organizer-Windows.exe) |
+| **macOS**   | [SFO-File-Organizer-macOS.zip](https://github.com/pjames-tech/sfo-file-organizer/releases/latest/download/SFO-File-Organizer-macOS.zip)     |
+| **Linux**   | [SFO-File-Organizer-Linux](https://github.com/pjames-tech/sfo-file-organizer/releases/latest/download/SFO-File-Organizer-Linux)             |
+
+### Option 3: Run from Source
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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`)
+
+```python
+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`)
+
+```python
+KEYWORD_RULES = {
+    "invoice": "Documents",    # Files with "invoice" go to Documents
+    "screenshot": "Images",    # Files with "screenshot" go to Images
+    # Add custom rules here
+}
+```
+
+## Testing
+
+```bash
+# 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:
+
+   ```batch
+   "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):
+
+   ```powershell
+   schtasks /create /tn "Smart File Organizer" /tr "C:\path\to\run_organizer.bat" /sc daily /st 12:00 /f
+   ```
+
+## License
+
+MIT License

sfo_file_organizer-1.0.0/app_config.py

@@ -0,0 +1,94 @@
+"""
+Configuration settings for SFO File Organizer.
+"""
+
+import os
+import sys
+import shutil
+from pathlib import Path
+
+def get_resource_path(relative_path: str) -> str:
+    """Get absolute path to resource, works for dev and for PyInstaller."""
+    try:
+        # PyInstaller creates a temp folder and stores path in _MEIPASS
+        base_path = sys._MEIPASS
+    except Exception:
+        base_path = os.path.abspath(".")
+    return os.path.join(base_path, relative_path)
+
+def get_data_dir() -> Path:
+    """Get path to persistent data directory (APPDATA on Windows)."""
+    if getattr(sys, 'frozen', False):
+        # Running as bundled exe
+        app_data = os.getenv('APPDATA')
+        if app_data:
+            path = Path(app_data) / "SFOFileOrganizer"
+        else:
+            path = Path(sys.executable).parent / "data"
+    else:
+        # Running in dev
+        path = Path(__file__).parent
+    
+    # Ensure directory exists
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        # Fallback to current directory if all else fails
+        path = Path(".")
+        
+    return path
+
+# Data directory for persistent storage (History, Custom Rules)
+# We use APPDATA to ensure data survives app updates/moves
+APPDATA_PATH = os.environ.get("APPDATA", os.path.expanduser("~"))
+DATA_DIR = Path(APPDATA_PATH) / "SFOFileOrganizer"
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+# Define paths for data files
+HISTORY_FILE = DATA_DIR / "organizer_history.json"
+CUSTOM_RULES_FILE = DATA_DIR / "custom_rules.json"
+
+def initialize_data():
+    """Copy default data files to the persistent DATA_DIR if they don't exist."""
+    defaults = [CUSTOM_RULES_FILE.name] # Use .name to get "custom_rules.json"
+    for filename in defaults:
+        dest_path = DATA_DIR / filename
+        if not dest_path.exists():
+            source_path = get_resource_path(filename)
+            if os.path.exists(source_path) and source_path != str(dest_path):
+                try:
+                    shutil.copy2(source_path, dest_path)
+                except Exception:
+                    pass
+
+initialize_data()
+
+# Default directories (in-place organization by default)
+DEFAULT_SOURCE_DIR = str(Path.home() / "Downloads")
+DEFAULT_DEST_DIR = DEFAULT_SOURCE_DIR  # Same as source for in-place organizing
+
+# File categories and their extensions
+FILE_CATEGORIES = {
+    "Images": [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".svg", ".webp", ".ico", ".tiff"],
+    "Documents": [".pdf", ".doc", ".docx", ".txt", ".rtf", ".odt", ".xls", ".xlsx", ".ppt", ".pptx"],
+    "Videos": [".mp4", ".mkv", ".avi", ".mov", ".wmv", ".flv", ".webm"],
+    "Audio": [".mp3", ".wav", ".flac", ".aac", ".ogg", ".wma", ".m4a"],
+    "Archives": [".zip", ".rar", ".7z", ".tar", ".gz", ".bz2"],
+    "Code": [".py", ".js", ".html", ".css", ".java", ".cpp", ".c", ".h", ".json", ".xml", ".php", ".ts", ".tsx", ".jsx"],
+    "Executables": [".exe", ".msi", ".bat", ".sh", ".app", ".dmg"],
+    "Fonts": [".ttf", ".otf", ".woff", ".woff2"],
+}
+
+# Logging settings
+LOG_FILE = "organizer.log"
+LOG_LEVEL = "INFO"
+
+# Detailed categories for Smart Context mode (Sub-types for Documents)
+DETAILED_CATEGORIES = {
+    # Documents breakdown
+    ".pdf": "PDFs",
+    ".doc": "Word Documents", ".docx": "Word Documents",
+    ".xls": "Spreadsheets", ".xlsx": "Spreadsheets", ".csv": "Spreadsheets",
+    ".ppt": "Presentations", ".pptx": "Presentations",
+    ".txt": "Text Files", ".md": "Text Files", ".rtf": "Text Files",
+}