Sweep
File organizer for a selected directory.
Overview
Sweep is a small Python command-line tool that organizes files in a selected directory. It scans files directly inside that directory, classifies them by their final extension, and calculates a category destination. preview reports those destinations without moving files; run performs the moves.
What Sweep currently does
For a selected directory, Sweep:
-
expands user-home notation such as
~; -
checks that the path exists and is a directory;
-
scans files directly inside the directory;
-
ignores subdirectories;
-
classifies each file by its lowercased final suffix;
-
calculates a destination in this form:
<directory>/<category>/<filename>
With preview, Sweep reports the classification and calculated destination. With run, it moves each file to that destination. A destination directory is created when a move needs it.
The command prints information for each file, including its name, category, suffix, size, and destination. It also prints totals and category counts. run additionally reports how many files were moved and how many were skipped.
Classification
Classification uses the lowercased final Path.suffix value. The current categories are:
| Category | Extensions |
|---|---|
| Images | .jpg, .png, .jpeg, .gif, .webp |
| Documents | .docx, .pdf, .md, .txt |
| Archives | .zip, .rar, .7z, .tar, .gz |
| Other | Every other final suffix, including no suffix |
For example:
photo.png → ImagesREPORT.PDF → Documentsarchive.tar.gz → ArchivesREADME → Other.hidden → Otherarchive.tar.gz is classified as an archive because .gz is its final suffix. .hidden has no suffix according to Python’s Path.suffix behavior.
Preview and run
Preview
sweep preview ~/Downloadspreview scans and classifies the files, calculates their destinations, and reports the planned organization. It does not move files.
Preview does not perform the move-time destination conflict check.
Run
sweep run ~/Downloadsrun performs the organization. It creates category directories as needed and moves files to their calculated destinations.
Conflict behavior
Sweep does not overwrite an existing destination file. When the destination already exists, the move is skipped and the source file is left in place.
There is no automatic rename, overwrite option, conflict-resolution strategy, transaction, or rollback.
Current limitations
The current implementation does not provide:
- recursive scanning;
- file watching or background automation;
- scheduling;
- configurable classification rules;
- content-based file detection;
- automatic renaming on conflicts;
- overwrite handling;
- rollback;
- broad whole-filesystem organization.
The target directory is supplied by the user. Downloads is only an example; it is not hardcoded.
Try it and read more
- 001 filename classifier: classify names in your browser (lab)
- Source repository