Metadata-Version: 2.4
Name: downsorter
Version: 0.2.0
Summary: Organize files by extension into category folders from the command line.
Author: Your Name
License: MIT
Keywords: downloads,file sorting,organization,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Downsorter

A small Python CLI tool that organizes files by extension into category folders.

Use it to clean up a messy folder, especially downloads, by moving images, documents, archives, installers, code, audio, and video files into the right subfolders.

## Features

- Organizes files by extension into category folders
- Preview mode so you can see changes before moving anything
- Safe move mode with `--apply` to actually perform the file moves
- Handles duplicate names by renaming files to `name (1).ext`, `name (2).ext`, etc.
- Ignores common system files like `desktop.ini` and `thumbs.db`
- Supports minimum file age filtering with `--min-age-days`
- Writes a CSV log of all moves for auditing
- Works on Windows, macOS, and Linux with Python 3.10+

## Platform Support

| Platform | Support | Notes |
| --- | --- | --- |
| Windows 10/11 | Supported | Best tested platform for this project |
| macOS | Supported | Works with Python 3.10+ |
| Linux | Supported | Works with Python 3.10+ |

## Files

- `sorter.py` - main CLI script and package entry point
- `README.md` - project instructions
- `pyproject.toml` - package metadata for PyPI
- `LICENSE` - MIT license text
- `movelogs.csv` - example move log file written by the script

## Install

### From source

```bash
pip install .
```

### From PyPI

```bash
pip install downsorter
```

## Usage

### Preview what will happen

This is the safest way to run the tool first.

```bash
downsorter --folder "C:\Users\YourName\Downloads"
```

### Actually move files

```bash
downsorter --folder "C:\Users\YourName\Downloads" --apply
```

### Only move files older than 7 days

```bash
downsorter --folder "C:\Users\YourName\Downloads" --min-age-days 7 --apply
```

### Use a custom log file

```bash
downsorter --folder "C:\Users\YourName\Downloads" --apply --log-file my-moves.csv
```

## Options

- `--folder`: Folder to organize. Defaults to the current user's Downloads folder.
- `--apply`: Actually move files. Without this flag, the script only previews the planned moves.
- `--min-age-days`: Only move files that have not been modified for at least this many days.
- `--log-file`: CSV file where completed moves are recorded.

## How it works

1. The script scans the target folder for files.
2. It matches each file extension against a category list.
3. It builds a plan showing where each file would move.
4. In preview mode, it only prints the plan.
5. In apply mode, it creates category folders, moves files, and logs the results.

## Categories

The project currently sorts files into:

- `Images` (.jpg, .jpeg, .png, .webp, .bmp)
- `PDFs` (.pdf)
- `Documents` (.doc, .docx, .txt, .md, .rtf)
- `Spreadsheets` (.xls, .xlsx, .csv, .tsv)
- `PPTs` (.ppt, .pptx)
- `Archives` (.rar, .zip, .7z, .tar, .gz)
- `Installers` (.exe, .msi)
- `Code` (.py, .js, .html, .css, .json, .xml, .cpp, .java)
- `Audio` (.mp3, .wav, .flac, .aac, .ogg)
- `Videos` (.mp4, .gif, .mov, .mkv, .avi, .webm)
- `Other` for everything else

## Example

Run this to preview then apply:

```bash
downsorter --folder "C:\Users\YourName\Downloads"
downsorter --folder "C:\Users\YourName\Downloads" --apply
```

## License

This project is licensed under the MIT License.
