Developer Tool
File Organizer
A safety-first Python command-line utility designed to automate file organization across complex directory structures without risking destructive operations.
01 / Type
Developer Tool
02 / Role
Creator & Maintainer
03 / Stack
Python • CLI development • PyPI package distribution • pytest • Ruff • GitHub Actions • Safe file operations
04 / Status
Open Source
Overview
A safety-first Python command-line utility designed to automate file organization across complex directory structures without risking destructive operations.
The Problem
Developers and power users frequently accumulate cluttered directories such as Downloads and Documents. Manual cleanup is repetitive, while ad-hoc scripts can accidentally overwrite or delete important files.
The Solution
Engineered a dependency-free Python CLI around pathlib and shutil, with dry-run execution, collision handling, and rule-based sorting so users can automate organization while keeping filesystem changes predictable.
Architecture
Engineering Decisions
Standard Library Only
Avoided external runtime dependencies so the CLI stays lightweight and can be distributed with minimal setup overhead.
Dry-Run First
Implemented a dry-run mode that reports intended operations without modifying the filesystem, making automation safer to inspect before execution.
Non-Destructive Conflict Handling
Designed duplicate-file handling to append numerical suffixes instead of overwriting existing files.
Challenges
Cross-Platform Pathing
Standardized path handling on pathlib so the same organization logic works across Windows, macOS, and Linux environments.
Large Directory Scanning
Used generator-based scanning to avoid loading an entire directory tree into memory at once.
Future Improvements
- Plugin system for custom sorting rules
- Interactive CLI wizard using prompt-toolkit
- Multithreaded operations for network drives
Impact & Outcomes
- 01Published PyPI package
- 02CI workflow
- 03Automated testing
- 04Safe file operations