fl-classifier 0.2.0

A tool to automatically classify files based on extension or timestamp

File Classifier

A powerful, cross-platform Python utility for organizing files and folders automatically based on extensions, folder names, or timestamps.

Features

• Multiple Classification Methods:

  • Extension-based: Classifies files into categories based on their extensions
  • Time-based: Organizes files by creation, modification, or access time
  • Folder classification: Categorizes folders based on common naming patterns

• File Categories:

  • Documents (PDF, DOC, TXT, etc.)
  • Images (JPG, PNG, GIF, etc.)
  • Audio (MP3, WAV, FLAC, etc.)
  • Videos (MP4, AVI, MKV, etc.)
  • Archives (ZIP, RAR, 7Z, etc.)
  • Code (PY, JAVA, HTML, etc.)
  • Executables (EXE, MSI, APP, etc.)
  • Others (for extensions not in the above categories)

• Folder Categories:

  • Projects: For development and project-related folders
  • Backups: For backup and archived content
  • Documents: For document and report folders
  • Media: For photos, videos, music folders
  • Downloads: For download folders
  • Applications: For software and apps
  • Data: For datasets and databases
  • Web: For web-related content
  • Dated: For folders with date patterns (auto-detected)
  • Versioned: For folders with version patterns (auto-detected)
  • Uncategorized: For folders that don't match any patterns

• Operation Modes:

  • Move (default): Moves files/folders to target directories
  • Copy: Creates copies instead of moving
  • Symlink: Creates symbolic links to original files/folders
  • Dry-run: Shows what would happen without making changes

• Cross-Platform Compatibility:

  • Works on Windows, macOS, and Linux

Requirements

• Python 3.6 or higher
• No additional libraries required (uses standard library only)

Installation

Download the script and make it executable:

chmod +x file_classifier.py

Or run it directly with Python:

python file_classifier.py [options]

Usage

Basic Usage

python file_classifier.py SOURCE_DIR [TARGET_DIR]

If TARGET_DIR is not specified, files will be organized in a new directory called ./classified.

Common Options

-l, --symlinks       Create symlinks instead of moving files
-c, --copy           Copy files instead of moving them
-d, --dry-run        Show what would be done without actually doing it
-f, --folders        Include folders in the classification

Classification Methods

-e, --extensions     Classify by file extensions (default behavior)
-t, --time           Organize by time attribute

Time-based Organization Options

--time-attr {modified,created,accessed}
                     Time attribute to use (default: modified)
--time-format FORMAT
                     Time format for directories (default: '%Y-%m' for year-month)

Collision Handling Options

--on-conflict {skip,rename,overwrite}
                     How to handle file conflicts (default: skip)
                     - skip: Skip files that already exist
                     - rename: Rename new files (file.txt → file_1.txt)
                     - overwrite: Replace existing files

Examples

See the examples/ directory for detailed, runnable examples:

1. Basic Organization - Classify files by extension
2. Time-Based - Organize by modification date
3. Copy Mode - Copy instead of move
4. Dry Run & Conflicts - Preview and handle duplicates

Quick Examples

Extension-based Organization

# Classify all files in Downloads folder by extension
python file_classifier.py ~/Downloads ~/Organized

# Classify files and folders, create copies instead of moving
python file_classifier.py ~/Documents ~/Organized -f -c

# Create symlinks instead of moving files
python file_classifier.py ~/Pictures ~/Organized -l

# Preview what would happen without making any changes
python file_classifier.py ~/Desktop -d

Time-based Organization

# Organize files by their modification time (year-month)
python file_classifier.py ~/Documents ~/TimeOrganized -t

# Organize by creation date with year-month-day format
python file_classifier.py ~/Photos ~/Chronological -t --time-attr created --time-format "%Y-%m-%d"

# Organize files and folders by access time
python file_classifier.py ~/Downloads ~/AccessOrganized -t --time-attr accessed -f

Troubleshooting

Issue: Files are being skipped

Cause: Files already exist in target directory

Solution: Files with the same name in the target will be skipped by default. Check the logs for "already exists" warnings.

Issue: Want to preview changes first

Solution: Use --dry-run flag to see what would happen without making changes:

python file_classifier.py ~/Downloads ~/Organized --dry-run

Issue: Permission denied errors

Cause: Insufficient permissions to read source or write to target directory

Solution:

• Check directory permissions
• Run with appropriate user privileges
• Ensure target directory is writable

Issue: Symlinks not working on Windows

Cause: Symlink creation requires administrator privileges on Windows

Solution: Run terminal as administrator, or use --copy mode instead

FAQ

Q: What happens if a file or folder already exists in the target directory? A: By default, the script will skip it and log a warning message. The file will remain in the source directory.

Q: Can I undo the organization? A: Currently, there's no built-in undo feature. We recommend:

• Use --dry-run first to preview changes
• Use --copy mode to keep original files
• Keep backups of important directories

Q: Will the organization preserve the directory structure? A: No, all files are flattened to the corresponding category directories. For hierarchical organization, consider using the time-based organization with a hierarchical format like %Y/%m/%d.

Q: Can I customize file categories? A: Yes, you can edit the FILE_CATEGORIES dictionary in the script to add or modify categories. Configuration file support is planned for future releases.

Q: Does it work on Windows? A: Yes! The tool uses Python's pathlib for cross-platform compatibility and works on Windows, macOS, and Linux.

Q: Can I organize files in subdirectories? A: Currently, only files in the top level of the source directory are processed. Recursive mode is planned for future releases.

Q: How do I install the package? A: Install via pip:

pip install fl-classifier

Then run with:

fl-classifier ~/Downloads ~/Organized
# or
python -m fl_classifier ~/Downloads ~/Organized

License

This utility is released under the MIT License. Feel free to use, modify, and distribute it.