Safe File Organizer

Automation must be safer than manual movement

A Downloads folder may contain images, documents, spreadsheets, archives, code and unknown files. The organizer groups top-level files into named subfolders based on lowercase extensions. Because movement changes real filesystem state, correctness includes avoiding overwrites, showing a preview and allowing cancellation with zero changes.

Define exclusions before scanning

1. The selected path must exist and be a directory.
2. Only top-level regular files are candidates; subdirectories are not traversed.
3. The running organizer script excludes itself.
4. Extension comparison is case-insensitive.
5. Unknown or extensionless files go to Other.
6. An existing destination is never overwritten.
7. No movement begins unless the user types exactly MOVE.

The narrow, non-recursive scope prevents accidentally reorganizing an entire nested project. Recursion can be an extension only after symlink handling, protected folders and rollback are designed.

A mapping keeps policy separate from movement

CATEGORIES = {
  "Images": {".jpg", ".png", ...},
  "Documents": {".pdf", ".docx", ...},
  "Code": {".py", ".c", ".html", ...}
}

category_for lowercases Path.suffix and searches the mapping. The classification rule is data, so adding an extension does not change the planning algorithm.

Important ambiguity

archive.tar.gz has .gz as its final suffix and is classified as an archive. A richer policy might inspect suffixes. A file extension is only a naming convention; it does not verify actual content. Security-sensitive systems need content inspection.

Separate decision from mutation

A dry preview lets the user detect a wrong directory or classification before anything changes. The plan is also testable without modifying files: provide a temporary directory, call build_plan and inspect its tuples.

The program sorts source names case-insensitively so preview order is deterministic. Determinism makes screenshots, tests and troubleshooting easier.

Never trade organization for data loss

If Images/photo.jpg already exists, moving another photo.jpg to that exact path could overwrite or fail depending on platform. The organizer tests the candidate and generates photo_1.jpg, photo_2.jpg, and so on until an unused name is found.

candidate = category / original_name
while candidate exists:
    candidate = category / f"{stem}_{counter}{suffix}"

This preserves both files, though it does not determine whether they contain duplicate bytes. Hash-based duplicate detection is a separate policy that should offer review rather than silently delete.

Runnable Python program using real files

Loading source…

Trace a five-file test folder

Verify without risking personal data

Directory scanning is linear; I/O dominates

c is the small number of categories. A sequence of filesystem moves is not atomic: power loss may leave a partially organized folder. A stronger version records a journal before each move and supports rollback. It must also define behavior for symbolic links and cross-filesystem copies.

Check safe automation principles

Extensions

1. Create a move journal and Undo Last Run.
2. Add modification-year subfolders after category.
3. Detect byte-identical files using hashes but require review before deletion.
4. Add configurable rules from JSON.
5. Design safe recursion with symlink-cycle protection.

Good automation makes consequences visible first

The Python APIs are straightforward; the engineering value lies in constrained scope, deterministic planning, explicit confirmation, collision protection, precise error reporting and temporary-directory tests.